Add Framework Development

---
name: add-framework-development
description: "Internal skill for developing ADD framework artefacts (commands, skills, agents, scripts). Use when add-framework--plan analyzes viability of new framework features, when add-framework--build implements framework artefacts, or when creating/modifying commands, skills, or agents. Always use this skill before proposing or implementing changes to the framework itself."
---

# Framework Development — Internal Reference

<!-- uses:
- skill: add-commit
- skill: building-commands
- skill: add-artefact-graph
- skill: add-product-artefact-renaming
- skill: add-framework-injection (conditional)
- mention: add-framework--plan
- mention: add-framework--build
-->

Operational knowledge for creating and modifying ADD framework artefacts. Built to the workbench providers and distributed to no user — exists so `add-framework--plan` assesses viability and `add-framework--build` implements correctly.

## When to Use
- `add-framework--plan` analyzing if a proposal is technically viable (STEP 0 and STEP 2)
- An injection change also loads `add-framework-injection`. This skill does not restate slot, fallback, or STEP ID rules.
- `add-framework--build` implementing a new command, skill, agent, or script
- Modifying existing framework artefacts (commands, skills, agents)
- Deciding WHAT TYPE of artefact to create for a given need
- Understanding how the build pipeline distributes artefacts to providers

## When NOT to Use
- **Implementing user-facing features** (backend/frontend code) → use development skills directly
- **Understanding what artefacts exist** → use `add--ecosystem` skill (ecosystem map)
- **Writing prompts for commands** → use `building-commands` skill (prompt engineering patterns)
- **Running the project** → use `AGENTS.md` (project standards and conventions)

---

## 0. Decision Framework — What to Create?

This is the FIRST question `add-framework--plan` must answer. Wrong artefact type = wasted effort.

| Need | Create | Why |
|------|--------|-----|
| Orchestrate a multi-step workflow with gates and user interaction | **Command** | Commands control execution flow, enforce gates, dispatch agents |
| Teach patterns/rules that multiple commands need | **Skill** | Skills are reusable knowledge packs loaded by commands and agents |
| Specialize an agent with restricted tools, model, and memory | **Agent** | Agents are isolated specialists with persistent project memory |
| Automate a deterministic task (no LLM reasoning needed) | **Script** | Native Node scripts are fast, predictable, and need no LLM tokens |

### Decision Tree

```
Does it need LLM reasoning?
├── NO → Script (.codeadd/scripts/)
└── YES
    ├── Does it orchestrate a workflow with multiple steps/gates?
    │   └── YES → Command
    ├── Does it need to run in isolated context with restricted tools?
    │   └── YES → Agent
    └── Is it reusable knowledge that commands/agents consume?
        └── YES → Skill
```

### Common Mistakes in Classification

| Mistake | Why it's wrong | Correct approach |
|---------|---------------|-----------------|
| Creating a command for something that's just knowledge | Commands orchestrate; if there's no workflow, it's a skill | Create a skill, let commands load it |
| Creating an agent for a one-off task | Agents have overhead (spawn, memory); overkill for simple tasks | Use inline execution in the command |
| Creating a skill that tries to execute steps | Skills teach, they don't execute; execution is commands' job | Split: skill for knowledge, command for workflow |
| Creating a script for something that needs context | Scripts can't reason about code or make judgment calls | Create a command or agent instead |

---

## Artefact Types

| Type | Source path | Format |
|------|------------|--------|
| Command | `framwork/.codeadd/commands/{name}.md` | Markdown with structured sections |
| Skill | `framwork/.codeadd/skills/{name}/SKILL.md` | Markdown with YAML frontmatter |
| Agent | `framwork/.codeadd/agents/{name}-agent.md` | Markdown with YAML frontmatter |
| Script | `framwork/.codeadd/scripts/{name}.cjs` | Node |

No counts: `AGENTS.md`'s generated inventory lists what exists.

Workbench artefacts (source at `workbench/`, built to the root provider dirs, shipped to no user): `workbench/skills/`, `workbench/commands/`

**The graph holds five kinds these four do not cover**, and every one of them ships:

| Graph kind | Source | Authored? |
|---|---|---|
| `reference` | a skill's own `references/` subdocs | yes |
| `fragment` | `fragments/{feature}/` and `plugins/{plugin}/fragments/` | yes — and declaring, so it carries a `uses:` block |
| `template` | `.codeadd/templates/` | yes, but neither declaring nor sniffable |
| `feature` | one per `fragments/{name}/` directory | no — derived from the layout |
| `plugin` | one per `plugins/{name}/` directory | no — derived from the layout |

A plugin's own `skills/` are `skill` nodes like any other, and are NOT registered in
`provider-map.json`: a plugin skill reaches a user through the plugin catalog.

---

## 1. Command Structure

Commands are workflow orchestrators. They load skills, dispatch agents, enforce gates, and produce documents.

### Anatomy

```markdown
# [Command Title]

> **LANG:** Respond in user's native language (detect from input). Tech terms always in English. Short sentences, one idea each; the common word over the rare one; a technical term explained in one line the first time it appears.

[One-line description]

## ⛔⛔⛔ MANDATORY SEQUENTIAL EXECUTION ⛔⛔⛔

STEP 1: [Action]    → [What happens]
STEP 2: [Action]    → [What happens]

## STEP 1: [Title]
### 1.1: [Subsection]

**GATE: [gate_name]** - MANDATORY before [condition]
**GATE CHECK:** [what must be true?] IF NO -> STOP.

**DISPATCH AGENT: @[agent-name]**
**WAIT:** [condition before continuing]

## Rules
ALWAYS:
- [imperative]
NEVER:
- [prohibition]
```

### Key Elements

**Frontmatter** — `> **KEY:** value` format (not YAML):
- `LANG`, `OWNER`, `ARCHITECTURE REFERENCE`, `DOCS`, `MODE`

**No `## Spec` section** — DO NOT add a top-of-file `## Spec` JSON metadata block to commands or skills. Output paths, modes, schemas belong in the frontmatter `description` and STEP body. Nothing programmatically consumes `## Spec`. See `building-commands` skill for the prohibition.

**Tool Prohibitions** — `⛔⛔⛔ ABSOLUTE PROHIBITIONS` block:
```
⛔ DO NOT USE: [tool] for [context]
✅ DO: [correct alternative]
```

**Gates** — Named checkpoints that block execution:
- `**GATE: feature_identified**` — named gate
- `**GATE CHECK:** [condition]? IF NO -> STOP.` — inline check

**Subagent Dispatch** — Named agents with fallback:
```markdown
| Area | Named Agent | Fallback |
|------|-------------|----------|
| Database | @database-agent | Generic subagent + skill add-database-development |

**DISPATCH AGENT: @database-agent**
Prompt: [full prompt with ${FEATURE_ID}, output path, format template]
```

**Wait Points** — `**WAIT:** [condition]` blocks execution until artifact exists.

**Output Paths** — Always use `${FEATURE_ID}` variable:
- `docs/features/${FEATURE_ID}/plan.md`
- `docs/features/${FEATURE_ID}/design.md`
- Temp files: `plan-database.md`, `plan-backend.md`, etc.

**Completion** — Always reference `add--ecosystem` skill for next steps.

---

## 2. Skill Structure

Skills are knowledge packs loaded into context. They teach patterns, not execute workflows.

### Anatomy

```yaml
---
name: add-[kebab-case]        # REQUIRED, matches directory name
description: "Use when..."    # REQUIRED, action-verb trigger phrase
category: [meta|technique|reference|discipline]  # optional
---
```

```markdown
# [skill-name] — [Subtitle]

## When to Use
- [specific scenario 1]
- [specific scenario 2]

## When NOT to Use
- **[anti-pattern]** → use `/add.[other]` instead

## [Content Sections]

## Common Rationalizations (BLOCKED)
| Excuse | Reality |
|--------|---------|
| "[excuse]" | [why it's wrong] |
```

### Tiers

| Tier | Lines | Structure | Example |
|------|-------|-----------|---------|
| 1 (simple) | <100 | Single SKILL.md, basic sections | add-commit |
| 2 (medium) | 100-300 | JSON spec blocks, templates, checklists | add-tasks-checklist |
| 3 (complex) | 300+ | SKILL.md dispatcher + reference subdocs | add-ux-design |

**Subdoc pattern (canonical — `references/`, any tier):**
```
add-qa/
  SKILL.md                    ← dispatcher/index
  references/coordinator.md   ← reference doc
```

⛔ **One convention only: `references/`.** It is what `add--skill-creator` prescribes (anti-pattern table + pre-deploy checklist) and what the majority of skills use — `add--doc-schemas`, `add--investigation`, `add--skill-creator`, `add--backend-architecture`, `add--frontend-architecture`, `add--subagent-driven-development`, `add--qa`. New subdocs go there regardless of tier; a Tier-2 skill that outgrows one file uses `references/` too, it does not go flat.

**Flat siblings are legacy**, not an alternative: `add-ux-design` (14 files), `add-architecture-discovery`, `add-health-check`, `add-stripe`. Adding a subdoc to one of those may follow its existing flat layout — mixing both inside one skill is worse than either. Do NOT introduce a flat subdoc in a skill that has none.

`scripts/build.js` (`skillStrategy.postWrite`) copies subdirs and siblings recursively, so both layouts distribute identically — the choice is purely about authoring consistency. Reference a subdoc as `{{skill:NAME/references/FILE.md}}` (the `{{skill:}}` resolver matches greedily past `/`).

### Conventions

- **Structured data:** Inline JSON `{"key":"value"}` for lookup tables, checklists, scoring
- **Anti-rationalization:** Tables with `Excuse | Reality` columns
- **Enforcement:** `⚠️ REGRA OBRIGATÓRIA`, `NEVER/MUST`, `**OBRIGATÓRIO**`
- **Cross-references:** `{{skill:add-[name]/[file]}}` for files, `/add.[name]` for commands
- **Token efficiency:** JSON minified, no decorative formatting
- **`--yolo` (scoped, NOT a general convention):** an autonomy flag supported ONLY by `add-review`, where it skips the staging question. Unattended delivery is not this flag: it is the `delivery: automatic` mode `add-delivery-mode` owns, chosen once at `add-brainstorm`'s approval. With a read-only `add-review` the flag's auto-correct half no longer exists. Plan 0057 removed it from `add-plan` because a design pipeline with a skip-all-confirmations flag can silently ship an unreviewed contract. Do NOT add it to new commands, and do NOT assume a command accepts it — grep the target command first.

---

## 3. Agent Structure

Agents are specialized subagents with preloaded skills, tool restrictions, and persistent memory. Claude Code native feature.

### Anatomy

```yaml
---
name: [name]-agent
description: [1-2 sentences — what it does + when Claude should use it]
model: [inherit|sonnet|haiku|opus]
tools: [comma-separated tool list]
disallowedTools: [tools to deny]
skills:
  - add-[skill-1]
  - add-[skill-2]
memory: project
---

[System prompt — body becomes the agent's instructions]
[Include domain knowledge, patterns, output format expectations]
```

### Frontmatter Fields

| Field | Required | Values |
|-------|----------|--------|
| name | yes | `[name]-agent` (kebab-case) |
| description | yes | Trigger phrase — "use proactively" encourages auto-delegation |
| model | no | `inherit` (full reasoning), `sonnet` (balanced), `haiku` (fast/cheap) |
| tools | no | Allowlist: `Read, Glob, Grep, Bash, Write, Edit` |
| disallowedTools | no | Denylist: `Write, Edit, NotebookEdit` for read-only agents |
| readonly | no | `true` for a read-only agent. **Not redundant with the two above** — provider dialects read different keys, so an agent that must be read-only everywhere declares `readonly` AND the denylist. ⛔ Neither key stops a shell write: an agent granted `Bash` keeps its read-only promise in prose, and must state it as a prohibition |
| skills | no | Array of skill names to preload into context |
| memory | no | `project` (`.claude/agent-memory/`), `user`, `local` |
| maxTurns | no | Limit agentic turns |
| permissionMode | no | `default`, `acceptEdits`, `dontAsk`, `bypassPermissions`, `plan` |
| hooks | no | Lifecycle hooks scoped to agent |
| mcpServers | no | MCP servers (inline or reference) |
| background | no | `true` to always run as background task |
| effort | no | `low`, `medium`, `high`, `max` |
| isolation | no | `worktree` for isolated git worktree |

### Constraints

- Agents CANNOT spawn other agents (leaf nodes only)
- Commands orchestrate; agents execute and return
- Agents don't inherit parent's skills — only what's in their `skills:` field
- Agent source filename: `{name}-agent.md`

### Design Guidelines

| Need | Model | Tools | Memory |
|------|-------|-------|--------|
| Exploration/discovery | haiku | Read-only | project |
| Code review/audit | sonnet | Read-only | project |
| Implementation | inherit | All | project |
| Architecture decisions | inherit | Read-only | project |
| Design proposals | sonnet | Read/Write | project |

### Plugin Agent-Injection Markers

Plugins (see AGENTS.md → Plugin System) can inject capability into agent definitions, not just commands — carrying an external-tool capability across the command→subagent dispatch boundary (agents never see a command's injected fragment). To make an agent a plugin injection target:

- **LOAD `add-framework-injection` before authoring the slot, the marker pair, or its fallback.** It owns the source grammar and STEP IDs. Bare marker pairs fail the build.
- Author the per-agent fragment at `framwork/.codeadd/plugins/{plugin}/fragments/agents/{agent}.md` with a section matching the slot member.
- Declare the target in the catalog entry's `agents` array (`{ agent, sections }`).
- **Exclusion is by omission:** an agent with a tool allowlist that blocks MCP (e.g. `tools: Glob, Read`), or whose purpose is not the code graph, simply carries no marker — so the build emits no sidecar entry for it and it is never injected. Never add an injection marker to an MCP-blocked agent.
- After adding/moving a marker, **rebuild** (`node scripts/build.js`) to regenerate the sidecar.

Only providers with an `agentsSubdir` (currently Claude) receive agent injection.

---

## 4. Build Pipeline

### Why provider-map.json Governs Everything

The framework is distributed to **15 providers** (Claude, Codex, Gemini, Copilot, Cursor, Kiro, etc.). Each provider has different directory structures, file formats, and capabilities. A single source file in `.codeadd/` must produce correct output for ALL providers.

**Every decision when writing commands, skills, or agents must consider:**
1. Will the file paths resolve correctly across providers? (use `{{cmd:}}` / `{{skill:}}` variables)
2. Does this feature depend on a capability not all providers have? (check `capabilities`)
3. Will the format transform correctly? (md → toml for Gemini)

**provider-map.json is the single source of truth** — it determines where files go, how they're transformed, and what capabilities are available.

### Source → Provider Installation

```
framwork/.codeadd/          ← SOURCE OF TRUTH (you write here)
  ├── agents/               ← agent definitions
  ├── commands/             ← command definitions
  ├── skills/               ← skill modules
  └── scripts/              ← node scripts

     ↓ node scripts/build.js (reads provider-map.json)
     ↓ per provider: lint → strip comments → resolve paths → transform format → write

framwork/.claude/           ← Claude Code output
framwork/.agents/           ← OpenAI Codex output
framwork/.gemini/           ← Gemini CLI output (TOML!)
framwork/.github/           ← GitHub Copilot output
[... 15 providers total]
```

### provider-map.json Structure

```json
{
  "providers": {
    "claude": {
      "dir": "framwork/.claude",
      "commands": "commands/{name}.md",      // ← output pattern for commands
      "skills": "skills/{name}/SKILL.md",    // ← output pattern for skills
      "agents": "agents/{name}.md",          // ← output pattern for agents (null if unsupported)
      "capabilities": {
        "hooks": true,          // lifecycle hooks support
        "agentDispatch": true,  // can dispatch subagents
        "mcp": true,            // Model Context Protocol
        "nativeFormat": "md",   // file format (md or toml)
        "slashCommands": true   // supports / commands
      }
    }
  },
  "commands": { "add-build": { "description": "..." } },  // registry
  "skills":   { "add--backend-development": {} },           // registry
  "agents":   { "backend-agent": { "description": "..." }} // registry
}
```

### How Output Paths Vary Per Provider

The same command gets installed to DIFFERENT paths depending on the provider:

| Provider | Commands pattern | Skills pattern | Agents pattern |
|----------|-----------------|----------------|----------------|
| Claude | `commands/{name}.md` | `skills/{name}/SKILL.md` | `agents/{name}.md` |
| Codex | `skills/{name}/SKILL.md` | `skills/{name}/SKILL.md` | — |
| Antigrav | `skills/{name}/SKILL.md` | `skills/{name}/SKILL.md` | — |
| KiloCode | `workflows/{name}.md` | `skills/{name}/SKILL.md` | — |
| Copilot | `agents/{name}.md` | `skills/{name}/SKILL.md` | — |
| Gemini | `commands/{name}.toml` | `skills/{name}/SKILL.md` | — |
| Kiro | `prompts/{name}.md` | `skills/{name}/SKILL.md` | — |
| Windsurf | `workflows/{name}.md` | `skills/{name}/SKILL.md` | — |

**When `agents` is null** → provider doesn't support agents → build.js skips agent installation for that provider.

### Format Transformers

Build.js transforms content based on `capabilities.nativeFormat`:

**`md` transformer** (most providers): Wraps content with YAML frontmatter:
```yaml
---
description: [from provider-map.json]
---
[original content]
```

If the output path contains `SKILL.md` (e.g., Codex commands → `skills/{name}/SKILL.md`), adds `name:` field:
```yaml
---
name: add-build
description: Development execution specialist...
---
```

**`toml` transformer** (Gemini only): Wraps content in TOML format:
```toml
# AUTO-GENERATED - source: framwork/.codeadd/commands/add-build.md
description = "Development execution specialist..."
prompt = """
[original content]
"""
```

**Agent passthrough**: Agents get no command/skill wrapping. Each provider gets its own frontmatter dialect (`AGENT_DIALECTS` in `scripts/build.js`); only Claude keeps the source `model`, because the sources pin Claude model names that fail on other providers.

### Resource Path Variables — When and How to Use

**The problem:** You write a command that references another command or skill. If you hardcode `.claude/commands/add-plan.md`, it breaks for Codex (which puts commands in `.agents/skills/add-plan/SKILL.md`).

**The solution:** Build-time variables that resolve per provider.

#### `{{cmd:NAME}}` — Reference a command

```markdown
<!-- IN YOUR SOURCE FILE (.codeadd/commands/add-build.md): -->
Read {{cmd:add-plan}} for the technical plan.

<!-- AFTER BUILD for Claude: -->
Read .claude/commands/add-plan.md for the technical plan.

<!-- AFTER BUILD for Codex: -->
Read .agents/skills/add-plan/SKILL.md for the technical plan.

<!-- AFTER BUILD for Gemini: -->
Read .gemini/commands/add-plan.toml for the technical plan.
```

#### `{{skill:NAME/FILE}}` — Reference a skill file

```markdown
<!-- IN YOUR SOURCE FILE: -->
Load {{skill:add--backend-development/SKILL.md}} before implementation.

<!-- AFTER BUILD for Claude: -->
Load .claude/skills/add--backend-development/SKILL.md before implementation.

<!-- AFTER BUILD for Copilot: -->
Load .github/skills/add--backend-development/SKILL.md before implementation.
```

#### Scripts — NO variable needed

Scripts live at `.codeadd/scripts/` and this path is the same for all providers:
```markdown
node .codeadd/scripts/status.cjs
```

### Provider Capabilities — What to Check When Writing Commands

Not all providers support all features. When a command uses a capability, it MUST consider providers that lack it:

| Capability | Providers WITHOUT it | Impact on commands |
|-----------|---------------------|-------------------|
| `agentDispatch` | Gemini, Shai, Windsurf | Cannot dispatch subagents — commands that dispatch `@agents` won't work |
| `hooks` | Antigrav, KiloCode, Bob, Qwen, Shai, Windsurf | No lifecycle hooks — pre/post tool hooks unavailable |
| `mcp` | Gemini | No MCP servers — agents with `mcpServers:` won't connect |
| `slashCommands` | Codex, Bob, Copilot | No `/command` invocation — must use natural language |

**When writing a command that dispatches agents:**
- The command works on providers with `agentDispatch: true`
- On providers without it, the command's content still loads but subagent dispatches will be ignored by the runtime
- Always include fallback guidance: "If agent dispatch is unavailable, execute inline"

### Build Process Step by Step (`scripts/build.js`)

1. **`readMap()`** — loads `framwork/provider-map.json`
2. **For each resource** (command/skill/agent):
   a. **Read source** from `.codeadd/`
   b. **`lintResourcePaths()`** — warns if raw `.codeadd/commands/` or `.codeadd/skills/` paths found (should use `{{cmd:}}` / `{{skill:}}`)
   c. **`extractInjectionPoints()`** — for commands/agents: records each `feature:`/`plugin:` marker as a content anchor into `framwork/.codeadd/injection-points.json` (then the markers are stripped)
   d. **`stripHtmlComments()`** — removes ALL `<!-- -->` comments (incl. injection markers) + collapses blank lines (token savings)
   e. **`resolveResourcePaths()`** — replaces `{{cmd:NAME}}` and `{{skill:NAME/FILE}}` for each provider
   f. **Transform** — applies `md` or `toml` transformer based on provider's `nativeFormat`
   g. **Write** — outputs to provider directory
   h. **`postWrite`** — for skills: copies extra subdocs (reference files, scripts, etc.)

### Registering New Artefacts

**Every new command, skill, or agent MUST be registered in provider-map.json:**

```json
// New command:
"commands": { "add.mycommand": { "description": "What it does in one line" } }

// New skill:
"skills": { "add-my-skill": {} }

// New agent:
"agents": { "my-agent": { "description": "What it does in one line" } }
```

If not registered, `build.js` won't process the file and it won't be distributed to any provider.

### Selective Provider Distribution

By default, artefacts go to ALL providers. To restrict to specific providers, add a `providers` array:

```json
"commands": {
  "add.mycommand": {
    "description": "...",
    "providers": ["claude", "codex", "cursor"]  // only these 3
  }
}
```

### Pre-Build Validation Checklist

- [ ] No raw `.codeadd/commands/` references outside code blocks (use `{{cmd:NAME}}`)
- [ ] No raw `.codeadd/skills/` references outside code blocks (use `{{skill:NAME/FILE}}`)
- [ ] Script paths use `.codeadd/scripts/` literal (no variable needed)
- [ ] New artefact registered in `provider-map.json` (commands/skills/agents section)
- [ ] Command/skill names match `provider-map.json` keys exactly
- [ ] Skill directory names include `add-` prefix
- [ ] Agent filenames follow `{name}-agent.md` pattern
- [ ] If command dispatches agents: provider capability check considered
- [ ] HTML comments `<!-- -->` used for build-only notes (stripped from output)
- [ ] Run `node scripts/build.js` to verify no LINT warnings

---

## 5. Creating New Artefacts

### New Command

1. Create `framwork/.codeadd/commands/{name}.md` following command anatomy
2. Register in `framwork/provider-map.json` → `commands` section
3. Run `node scripts/build.js` to distribute
4. Update `add--ecosystem` skill with new command entry

### New Skill

1. Create `framwork/.codeadd/skills/{name}/SKILL.md` following skill anatomy
2. For Tier 3: add reference subdocs in same directory
3. Register in `framwork/provider-map.json` → `skills` section
4. Run `node scripts/build.js` to distribute
5. Update `add--ecosystem` skill with new skill entry

### New Agent

1. Create `framwork/.codeadd/agents/{name}-agent.md` following agent anatomy
2. Register in `framwork/provider-map.json` → `agents` section
3. Run `node scripts/build.js` to distribute
4. Update `add--ecosystem` skill with new agent entry
5. Update commands that should dispatch this agent (add `@{name}-agent` to dispatch table)

### Internal-Only Artefact

1. Create directly in `workbench/skills/{name}/SKILL.md` or `workbench/commands/{name}.md`
2. Register it in `workbench/provider-map.json` — NEVER in `framwork/provider-map.json`
3. Do NOT add to framwork/.codeadd/
4. `scripts/build.js` never distributes it. `scripts/build-workbench.js` builds it to `.claude/`, `.opencode/`, `.agents/` and `.codex/` at the repository root, and none of those is packaged by `release.yml` nor written by the installer

---

## 6. Runtime Behavior — How Artefacts Interact

### How Commands Load Skills

Commands instruct the LLM to read skill files. This is NOT automatic — it's a prompt instruction:

```markdown
<!-- In a command source file: -->
## STEP 1: Load Context
Read {{skill:add--backend-development/SKILL.md}} before implementation.
```

At runtime, the LLM sees the resolved path (e.g., `.claude/skills/add--backend-development/SKILL.md`) and uses the `Read` tool to load the file into its context. The skill content then informs subsequent decisions.

**Key distinction:**
- **Command `Read` instruction** = LLM reads file at runtime (on-demand, costs tokens)
- **Agent `skills:` frontmatter** = skill is preloaded into agent context at spawn (automatic, always present)

### How Commands Dispatch Agents

Commands use the `Agent` tool (formerly `Task` tool) to spawn subagents:

```markdown
**DISPATCH AGENT: @backend-agent**
Prompt: You are implementing ${TASK_DESCRIPTION} for feature ${FEATURE_ID}...
```

The LLM interprets this and calls the Agent tool with `subagent_type: "backend-agent"`. If the agent exists in `.claude/agents/`, it spawns with its frontmatter config. If not, the fallback (generic subagent) is used.

**Parallel dispatch pattern** — commands that dispatch multiple agents MUST instruct:
```markdown
**CRITICAL:** Send ALL Agent tool calls in a SINGLE message for parallel execution.
```

### How Scripts Are Invoked

Commands invoke scripts via `Bash` tool:

````markdown
## STEP 1: Run Context Mapper
```bash
node .codeadd/scripts/status.cjs
```
````

`status.cjs` is the most common — returns project context (feature ID, branch, owner profile, etc.) as key-value pairs that commands parse to set variables like `${FEATURE_ID}`, `${OWNER_LEVEL}`.

### Runtime Loading Order (typical command)

```
1. Command prompt loaded into LLM context
2. LLM runs status.cjs via Bash → gets project variables
3. LLM reads skill files via Read → gets domain knowledge
4. LLM dispatches @agents via Agent tool → specialists execute in isolation
5. LLM waits for agent results → continues to next step
6. LLM enforces gates → blocks or proceeds
7. LLM writes output docs via Write/Edit tools
```

---

## 7. Common Errors and How to Prevent Them

### Build Pipeline Errors

| Error | Symptom | Prevention |
|-------|---------|------------|
| Forgot to register in provider-map.json | File exists in `.codeadd/` but never appears in provider dirs | ALWAYS register BEFORE running build |
| Used raw path `.codeadd/commands/add-plan.md` | Works on Claude, breaks on Codex/Gemini/etc. | Use `{{cmd:add-plan}}` variable |
| Used raw path `.codeadd/skills/add-x/SKILL.md` | Works on Claude, breaks on other providers | Use `{{skill:add-x/SKILL.md}}` variable |
| Agent file not named `{name}-agent.md` | build.js can't find the source file | Follow naming convention exactly |
| Skill dir name doesn't match `name:` in frontmatter | Confusion between directory and metadata | Keep them identical |

### Command Authoring Errors

| Error | Symptom | Prevention |
|-------|---------|------------|
| No gates before critical actions | Agent skips validation, produces broken output | Add `**GATE CHECK:**` before every irreversible step |
| No tool prohibitions | Agent uses Write when it should only Read, or edits wrong files | Add `⛔⛔⛔ ABSOLUTE PROHIBITIONS` block |
| No fallback for agent dispatch | Command fails on providers without agentDispatch | Always include fallback table with generic subagent option |
| Dispatching agents without loading docs first | Agent gets no context, produces generic output | Add `**WAIT:**` after doc loading, before dispatch |
| Missing `MANDATORY SEQUENTIAL EXECUTION` block | Agent skips steps or reorders them | Always include the numbered step summary at top |
| No completion/next-steps section | User doesn't know what to do after command finishes | Reference `add--ecosystem` skill for flow guidance |

### Skill Authoring Errors

| Error | Symptom | Prevention |
|-------|---------|------------|
| No "When NOT to Use" section | Skill triggers in wrong contexts, wastes tokens | Always list anti-patterns with delegation to correct skill |
| Skill tries to execute (has steps/gates) | Conflicts with command orchestration | Skills teach patterns; commands execute workflows |
| No anti-rationalization section (complex skills) | LLM finds excuses to skip rules | Add `Common Rationalizations (BLOCKED)` table |
| Tier 3 skill with everything in one file | Too many tokens loaded for simple queries | Split into SKILL.md dispatcher + reference subdocs |
| No structured data (inline JSON) for lookup tables | Verbose markdown wastes tokens | Use minified JSON for checklists, scores, configs |

### Agent Authoring Errors

| Error | Symptom | Prevention |
|-------|---------|------------|
| Giving Write/Edit to a read-only agent | Reviewer modifies code (anti-pattern) | Use `disallowedTools: Write, Edit, NotebookEdit` |
| No `skills:` in frontmatter | Agent has no domain knowledge, gives generic responses | Always preload relevant skills |
| Using `model: haiku` for tasks needing deep reasoning | Shallow analysis, missed edge cases | Use `inherit` or `opus` for architecture/implementation |
| Agent prompt duplicates skill content | Wastes tokens; content drifts out of sync with skill | Keep prompt minimal; let preloaded skills provide knowledge |
| No `memory: project` for agents that should learn | Agent rediscovers same patterns every session | Add memory for agents that benefit from project context |

---

## 8. Patterns to Enforce

### Token Efficiency (MANDATORY for all artefacts)

- JSON minified for structured data: `{"key":"value"}` not formatted
- No decorative formatting (ASCII art, excessive dashes, emoji headers)
- Reference don't repeat — use `{{skill:}}` and `{{cmd:}}` variables
- Compress examples: 1 excellent > 3 mediocre
- HTML comments `<!-- -->` for source-only notes (stripped by build)

### Anti-Rationalization (MANDATORY for commands and complex skills)

LLMs rationalize skipping steps. Every command/skill that controls agent behavior MUST include:
- Explicit tool prohibitions: `⛔ DO NOT USE: [tool] for [context]`
- Gate checks that STOP execution: `**GATE CHECK:** [condition]? IF NO -> STOP.`
- Rules section with `ALWAYS:` and `NEVER:` lists
- For complex skills: `Common Rationalizations (BLOCKED)` table

**Reference:** Load `building-commands` skill for detailed prompt engineering patterns.

### Documentation Style Cache (MANDATORY for skills that produce documents)

Read → Identify existing content → Preserve → Complement → Update metadata.
NEVER recreate a document from scratch — always extend what exists.

### Named Agent Dispatch (MANDATORY for commands that dispatch agents)

Always include fallback table for providers without agent support:
```markdown
| Area | Named Agent | Fallback |
|------|-------------|----------|
| [area] | @[name]-agent | Generic subagent + skill add-[area]-development |
```

## 9. Declaring Relationships — the `<!-- uses: -->` Block

Every artefact declares what it uses, in a source-only HTML comment near the top. The build reads
it with `extractUses()` **before** `stripHtmlComments()`, so it ships to nobody in the product
layer and is build metadata only.

**The shape.** An HTML comment whose first body line is `uses:` — the `<!--` opener, then one
`- <kind>: <target>` per line, then the closing marker. Opener and closer each sit alone on their
own line; the build ignores any occurrence embedded in a sentence, which is why this paragraph can
name them without declaring anything.

Body lines:

```
- skill: <skill-name>
- agent: <agent-name>
- command: /<command-name>
- handoff: <next-stage-name>
- script: <script-name>.cjs
- mention: <name-the-prose-points-away-from>
```

Real names, not placeholders — the placeholders above are only so this example declares nothing.

Six kinds. Five are real dependencies. **`mention:` is not** — it marks prose that names an
artefact while pointing away from it ("use X instead"). It emits a `MENTIONS` edge, so the target
is still validated, but `impact` and `dependencies` exclude it.

**`handoff:` names the next stage when that stage is not a command.** `command:` resolves to a command
node only, so a skill that hands off to a skill — the internal pipeline, brainstorm → plan → build →
done — has no other way to mark which out-edge is the next stage. It emits `HANDS_OFF_TO`, and its
target resolves by the sigils `mention:` uses: `/name` is a command, `@name` an agent, a bare name a
skill. At runtime it changes nothing; it is the edge label that tells the graph which dependency is
the hand-off.

**A catalogue is not a consumer.** `add--ecosystem` maps the ecosystem and consumes none of it, so
every row in its block is `mention:`. Declaring them as dependencies is not cosmetic: eight
commands load that skill, so everything it lists would inherit ~82 transitive dependants and
`impact` would degrade into a constant.

### Three gates fail the build, one warns

| Condition | Result |
|---|---|
| A declaration names an artefact that does not exist | **fails** |
| An artefact on disk is absent from `provider-map.json` — built for no provider | **fails** |
| A name appears in prose with no declared relationship to it | **fails** |
| Declared but never named in prose | warns — that direction is sometimes a real load that is not greppable |

`ADD_GRAPH_WARNINGS=1` lists warnings instead of summarising them.

**Cross-layer names are skipped by the prose gate.** A `uses:` target resolves inside the
declaring artefact's own layer, so an internal file naming a product script must NOT declare it —
the declaration would dangle and fail the build, while the prose mention costs nothing.

### Node identity

A node id is `<layer>/<kind>/<name>` — the layer prefix exists because `add-commit` lives in both.
Identity is **what the build can transform, never directory position**: a skill is a directory
*containing* `SKILL.md`.

### Querying it

**`add-artefact-graph` owns this.** Load it. It carries all eleven verbs, the two interfaces that
answer them identically, and — the part a five-row table could never hold — the standing list of what
the graph cannot see.

The table that used to sit here named five verbs and omitted `neighbors`, which is the one that
answers "what does this relate to". A partial list in a second place is how the two drifted.

### Cross-Artefact Impact (MANDATORY for any change)

When renaming a product command or skill, load `add-product-artefact-renaming` before touching its source. It owns the checked preview/apply procedure and the separation of product and internal names.

When creating or modifying any artefact, check:
1. `provider-map.json` — is it registered? description accurate?
2. `add--ecosystem` skill — does the ecosystem map reflect the change?
3. Commands that reference it — do dispatch tables, skill loads, or script calls need updating?
4. Agents that preload it — does the `skills:` array need updating?
5. Run `node scripts/build.js` — any LINT warnings?