julian
17c08e6392
- Nx 22.7 monorepo (pnpm 11.1, TypeScript 5.9, Node 24) - apps/api: NestJS 11 (CJS conforme CODING-RULES.md PGD-DB-004) - apps/web: React 19 + Vite 8 (ESM) - libs/shared/api-interface: Zod contract base - Docker Compose dev: Postgres 18, Valkey 8, MinIO, Mailpit - WDS artifacts: - design-artifacts/A-Product-Brief/ (5 docs canônicos + 16 dialogs) - design-artifacts/B-Trigger-Map/ (hub + 4 personas + feature impact) - Stack canon: STACK.md v2.2 + CODING-RULES.md v2.0 + brand.md - AGENTS.md + README.md como entrada para devs/agentes Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
93 lines
4.8 KiB
Markdown
93 lines
4.8 KiB
Markdown
# Template Substitution Rules
|
|
|
|
The SKILL-template provides a minimal skeleton: frontmatter, overview, agent identity sections, memory, and activation with config loading. Everything beyond that is crafted by the builder based on what was learned during discovery and requirements phases.
|
|
|
|
## Frontmatter
|
|
|
|
- `{module-code-or-empty}` → Module code prefix with hyphen (e.g., `cis-`) or empty for standalone. The `bmad-` prefix is reserved for official BMad creations; user agents should not include it.
|
|
- `{agent-name}` → Agent functional name (kebab-case)
|
|
- `{skill-description}` → Two parts: [4-6 word summary]. [trigger phrases]
|
|
- `{displayName}` → Friendly display name
|
|
- `{skillName}` → Full skill name with module prefix
|
|
|
|
## Module Conditionals
|
|
|
|
### For Module-Based Agents
|
|
|
|
- `{if-module}` ... `{/if-module}` → Keep the content inside
|
|
- `{if-standalone}` ... `{/if-standalone}` → Remove the entire block including markers
|
|
- `{module-code}` → Module code without trailing hyphen (e.g., `cis`)
|
|
- `{module-setup-skill}` → Name of the module's setup skill (e.g., `cis-setup`)
|
|
|
|
### For Standalone Agents
|
|
|
|
- `{if-module}` ... `{/if-module}` → Remove the entire block including markers
|
|
- `{if-standalone}` ... `{/if-standalone}` → Keep the content inside
|
|
|
|
## Memory Conditionals (legacy — stateless agents)
|
|
|
|
- `{if-memory}` ... `{/if-memory}` → Keep if agent has persistent memory, otherwise remove
|
|
- `{if-no-memory}` ... `{/if-no-memory}` → Inverse of above
|
|
|
|
## Headless Conditional (legacy — stateless agents)
|
|
|
|
- `{if-headless}` ... `{/if-headless}` → Keep if agent supports headless mode, otherwise remove
|
|
|
|
## Agent Type Conditionals
|
|
|
|
These replace the legacy memory/headless conditionals for the new agent type system:
|
|
|
|
- `{if-memory-agent}` ... `{/if-memory-agent}` → Keep for memory and autonomous agents, remove for stateless
|
|
- `{if-stateless-agent}` ... `{/if-stateless-agent}` → Keep for stateless agents, remove for memory/autonomous
|
|
- `{if-evolvable}` ... `{/if-evolvable}` → Keep if agent has evolvable capabilities (owner can teach new capabilities)
|
|
- `{if-pulse}` ... `{/if-pulse}` → Keep if agent has autonomous mode (PULSE enabled)
|
|
|
|
**Mapping from legacy conditionals:**
|
|
- `{if-memory}` is equivalent to `{if-memory-agent}` — both mean the agent has persistent state
|
|
- `{if-headless}` maps to `{if-pulse}` — both mean the agent can operate autonomously
|
|
|
|
## Template Selection
|
|
|
|
The builder selects the appropriate SKILL.md template based on agent type:
|
|
|
|
- **Stateless agent:** Use `./assets/SKILL-template.md` (full identity, no Three Laws/Sacred Truth)
|
|
- **Memory/autonomous agent:** Use `./assets/SKILL-template-bootloader.md` (lean bootloader with Three Laws, Sacred Truth, 3-path activation)
|
|
|
|
## Customize.toml Emission
|
|
|
|
Every agent ships `customize.toml` alongside SKILL.md. The template is `./assets/customize-template.toml`. Fill the `[agent]` metadata block from Phase 3's metadata gathering:
|
|
|
|
- `{agent-code}` → stable identifier (skill dir basename without module prefix)
|
|
- `{agent-name-or-empty}` → display name, or empty string for First-Breath-named agents
|
|
- `{agent-title}` → role title
|
|
- `{agent-icon}` → single emoji
|
|
- `{agent-description}` → one-sentence description
|
|
- `{agent-type}` → `stateless` | `memory` | `autonomous`
|
|
|
|
### Customization Opt-In Conditional
|
|
|
|
- `{if-customizable}` ... `{/if-customizable}` → Keep the content inside when the author opted in to the override surface; add the resolver step to SKILL.md; reference lifted scalars as `{agent.<name>}` in SKILL.md body.
|
|
- When not opted in → Remove the entire block including markers; `customize.toml` ships with metadata only; SKILL.md has no resolver step and uses hardcoded paths.
|
|
|
|
Lifted configurable scalars are referenced in SKILL.md as `{agent.<name>}` (e.g. `{agent.style_guide_template}`). These are resolved at runtime by the resolver, not at build time — emit them verbatim.
|
|
|
|
## Beyond the Template
|
|
|
|
The builder determines the rest of the agent structure — capabilities, activation flow, sanctum templates, init script, First Breath, capability routing, external skills, scripts — based on the agent's requirements. The template intentionally does not prescribe these.
|
|
|
|
## Path References
|
|
|
|
All generated agents use `./` prefix for skill-internal paths:
|
|
|
|
**Stateless agents:**
|
|
- `./references/{capability}.md` — Individual capability prompts
|
|
- `./scripts/` — Python/shell scripts for deterministic operations
|
|
|
|
**Memory agents:**
|
|
- `./references/first-breath.md` — First Breath onboarding (loaded when no sanctum exists)
|
|
- `./references/memory-guidance.md` — Memory philosophy
|
|
- `./references/capability-authoring.md` — Capability evolution framework (if evolvable)
|
|
- `./references/{capability}.md` — Individual capability prompts
|
|
- `./assets/{FILE}-template.md` — Sanctum templates (copied by init script)
|
|
- `./scripts/init-sanctum.py` — Deterministic sanctum scaffolding
|