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>
199 lines
11 KiB
Markdown
199 lines
11 KiB
Markdown
# Standard Agent Fields
|
|
|
|
## Frontmatter Fields
|
|
|
|
Only these fields go in the YAML frontmatter block:
|
|
|
|
| Field | Description | Example |
|
|
| ------------- | ------------------------------------------------- | ----------------------------------------------- |
|
|
| `name` | Full skill name (kebab-case, same as folder name) | `agent-tech-writer`, `cis-agent-lila` |
|
|
| `description` | [What it does]. [Use when user says 'X' or 'Y'.] | See Description Format below |
|
|
|
|
## Content Fields
|
|
|
|
These are used within the SKILL.md body — never in frontmatter:
|
|
|
|
| Field | Description | Example |
|
|
| ------------- | ---------------------------------------- | ------------------------------------ |
|
|
| `displayName` | Friendly name (title heading, greetings) | `Paige`, `Lila`, `Floyd` |
|
|
| `title` | Role title | `Tech Writer`, `Holodeck Operator` |
|
|
| `icon` | Single emoji | `🔥`, `🌟` |
|
|
| `role` | Functional role | `Technical Documentation Specialist` |
|
|
| `memory` | Memory folder (optional) | `{skillName}/` |
|
|
|
|
### Memory Agent Fields (bootloader SKILL.md only)
|
|
|
|
These fields appear in memory agent SKILL.md files, which use a lean bootloader structure instead of the full stateless layout:
|
|
|
|
| Field | Description | Example |
|
|
| ------------------ | -------------------------------------------------------- | ------------------------------------------------------------------ |
|
|
| `identity-seed` | 2-3 sentence personality DNA (expands in PERSONA.md) | "Equal parts provocateur and collaborator..." |
|
|
| `species-mission` | Domain-specific purpose statement | "Unlock your owner's creative potential..." |
|
|
| `agent-type` | One of: `stateless`, `memory`, `autonomous` | `memory` |
|
|
| `onboarding-style` | First Breath style: `calibration` or `configuration` | `calibration` |
|
|
| `sanctum-location` | Path to sanctum folder | `{project-root}/_bmad/memory/{skillName}/` |
|
|
|
|
### Sanctum Template Seed Fields (CREED, BOND, PERSONA templates)
|
|
|
|
These are content blocks the builder fills during Phase 5 Build. They are NOT template variables for init-script substitution — they are baked into the agent's template files as real content.
|
|
|
|
| Field | Destination Template | Description |
|
|
| --------------------------- | ----------------------- | ------------------------------------------------------------ |
|
|
| `core-values` | CREED-template.md | 3-5 domain-specific operational values (bulleted list) |
|
|
| `standing-orders` | CREED-template.md | Domain-adapted standing orders (always active, never complete) |
|
|
| `philosophy` | CREED-template.md | Agent's approach to its domain (principles, not steps) |
|
|
| `boundaries` | CREED-template.md | Behavioral guardrails |
|
|
| `anti-patterns-behavioral` | CREED-template.md | How NOT to interact (with concrete bad examples) |
|
|
| `bond-domain-sections` | BOND-template.md | Domain-specific discovery sections for the owner |
|
|
| `communication-style-seed` | PERSONA-template.md | Initial personality expression seed |
|
|
| `vibe-prompt` | PERSONA-template.md | Prompt for vibe discovery during First Breath |
|
|
|
|
## Customization Surface (`customize.toml`)
|
|
|
|
Every agent ships a `customize.toml` alongside SKILL.md. The file has two parts: a metadata block that is always emitted, and an override surface that is emitted only when the author opted in during build.
|
|
|
|
### Metadata block (always present)
|
|
|
|
Consumed by the installer to populate `module.yaml:agents[]` and the central config's `[agents.<code>]` section. Required for every agent regardless of archetype.
|
|
|
|
| Field | Type | Required | Notes |
|
|
| ------------- | ------ | -------- | --------------------------------------------------------------------- |
|
|
| `code` | string | yes | Stable identifier. Matches skill directory basename (no module prefix). |
|
|
| `name` | string | optional | Display name. Empty string is valid for First-Breath-named agents. |
|
|
| `title` | string | yes | Role title. Always fillable at build time. |
|
|
| `icon` | string | yes | Single emoji. |
|
|
| `description` | string | yes | One-sentence summary of what the agent does. |
|
|
| `agent_type` | string | yes | One of `stateless`, `memory`, `autonomous`. |
|
|
|
|
**First-Breath-named agents:** leave `name = ""` at build time. The owner fills it post-activation in `{project-root}/_bmad/custom/config.toml`:
|
|
|
|
```toml
|
|
[agents.<code>]
|
|
name = "..."
|
|
```
|
|
|
|
UIs tolerate empty `name` and fall back to `title`.
|
|
|
|
### Override surface (emitted only when opted in)
|
|
|
|
Loaded via `_bmad/scripts/resolve_customization.py` at activation. Skip entirely for agents that did not opt in to customization.
|
|
|
|
| Field | Type | Purpose |
|
|
| -------------------------- | ------------- | -------------------------------------------------------------- |
|
|
| `activation_steps_prepend` | array[string] | Steps run before standard activation. Overrides append. |
|
|
| `activation_steps_append` | array[string] | Steps run after greet, before user input. Overrides append. |
|
|
| `persistent_facts` | array[string] | Facts (literal or `file:` prefixed). Overrides append. |
|
|
|
|
### Agent-specific scalars (lifted during Configurability Discovery)
|
|
|
|
Named by purpose and suffix. Override wins (scalar merge rule).
|
|
|
|
| Naming pattern | Use for | Example |
|
|
| ----------------------- | --------------------------------------------- | ------------------------------------------------ |
|
|
| `<purpose>_template` | File paths for templates the agent loads | `style_guide_template = "resources/style.md"` |
|
|
| `<purpose>_output_path` | Writable destinations | `report_output_path = "{project-root}/reports"` |
|
|
| `on_<event>` | Prompt or command executed at a hook point | `on_session_close = ""` |
|
|
|
|
**Path resolution within scalar values:**
|
|
|
|
- Bare paths (e.g. `resources/style.md`) resolve from the skill root.
|
|
- `{project-root}/...` resolves from the project working directory — use for org-owned overrides.
|
|
- Config variables are used directly (they already contain `{project-root}`) — no double-prefix.
|
|
|
|
### How SKILL.md references the resolved values
|
|
|
|
After the resolver step runs, read customized values as `{agent.<name>}`:
|
|
|
|
```markdown
|
|
Load the style guide from `{agent.style_guide_template}`.
|
|
```
|
|
|
|
### Override files
|
|
|
|
Teams and users override without editing `customize.toml`:
|
|
|
|
- Team: `{project-root}/_bmad/custom/{skill-name}.toml`
|
|
- Personal: `{project-root}/_bmad/custom/{skill-name}.user.toml`
|
|
|
|
Both use the same `[agent]` block shape. Merge order: base (skill's `customize.toml`) → team → user.
|
|
|
|
### Memory / autonomous agents — prefer sanctum over this surface
|
|
|
|
For memory and autonomous agents, the sanctum (PERSONA.md, CREED.md, BOND.md, CAPABILITIES.md) is the primary behavior-customization surface. It's calibrated at First Breath and evolves over time through owner edits and teaching. The `[agent]` override surface is usually empty for these archetypes — opt in only when there is a specific need (e.g. org-mandated pre-sanctum-load compliance step) that the sanctum cannot express.
|
|
|
|
## Overview Section Format
|
|
|
|
The Overview is the first section after the title — it primes the AI for everything that follows.
|
|
|
|
**3-part formula:**
|
|
|
|
1. **What** — What this agent does
|
|
2. **How** — How it works (role, approach, modes)
|
|
3. **Why/Outcome** — Value delivered, quality standard
|
|
|
|
**Templates by agent type:**
|
|
|
|
**Companion agents:**
|
|
|
|
```markdown
|
|
This skill provides a {role} who helps users {primary outcome}. Act as {displayName} — {key quality}. With {key features}, {displayName} {primary value proposition}.
|
|
```
|
|
|
|
**Workflow agents:**
|
|
|
|
```markdown
|
|
This skill helps you {outcome} through {approach}. Act as {role}, guiding users through {key stages/phases}. Your output is {deliverable}.
|
|
```
|
|
|
|
**Utility agents:**
|
|
|
|
```markdown
|
|
This skill {what it does}. Use when {when to use}. Returns {output format} with {key feature}.
|
|
```
|
|
|
|
## SKILL.md Description Format
|
|
|
|
```
|
|
{description of what the agent does}. Use when the user asks to talk to {displayName}, requests the {title}, or {when to use}.
|
|
```
|
|
|
|
## Path Rules
|
|
|
|
### Same-Folder References
|
|
|
|
Use `./` only when referencing a file in the same directory as the file containing the reference:
|
|
|
|
- From `references/build-process.md` → `./some-guide.md` (both in references/)
|
|
- From `scripts/scan.py` → `./utils.py` (both in scripts/)
|
|
|
|
### Cross-Directory References
|
|
|
|
Use bare paths relative to the skill root — no `./` prefix:
|
|
|
|
- `references/memory-system.md`
|
|
- `scripts/calculate-metrics.py`
|
|
- `assets/template.md`
|
|
|
|
These work from any file in the skill because they're always resolved from the skill root. **Never use `./` for cross-directory paths** — `./scripts/foo.py` from a file in `references/` is misleading because `scripts/` is not next to that file.
|
|
|
|
### Memory Files
|
|
|
|
Always use `{project-root}` prefix: `{project-root}/_bmad/memory/{skillName}/`
|
|
|
|
The memory `index.md` is the single entry point to the agent's memory system — it tells the agent what else to load (boundaries, logs, references, etc.). Load it once on activation; don't duplicate load instructions for individual memory files.
|
|
|
|
### Project-Scope Paths
|
|
|
|
Use `{project-root}/...` for any path relative to the project root:
|
|
|
|
- `{project-root}/_bmad/planning/prd.md`
|
|
- `{project-root}/docs/report.md`
|
|
|
|
### Config Variables
|
|
|
|
Use directly — they already contain `{project-root}` in their resolved values:
|
|
|
|
- `{output_folder}/file.md`
|
|
- Correct: `{bmad_builder_output_folder}/agent.md`
|
|
- Wrong: `{project-root}/{bmad_builder_output_folder}/agent.md` (double-prefix)
|