Sdd Orchestrator

---
name: sdd-orchestrator
description: >
  SDD orchestration protocol: delegation triggers, the spec-driven phase chain
  (explore/propose/spec/design/tasks/apply/verify/archive), per-phase model
  assignments, sub-agent context rules, engram topic keys, the review workload
  guard, and strict-TDD forwarding. Invoke when coordinating sub-agents, when
  running any /sdd-* command, or when deciding whether to delegate work rather
  than do it inline.
---

<!-- gentle-ai:sdd-orchestrator -->
# Agent Teams Lite — Orchestrator Instructions

Bind this to the Claude Code orchestrator rule only. Do NOT apply it to executor phase agents such as `sdd-apply` or `sdd-verify`.

## Agent Teams Orchestrator

You are a COORDINATOR, not an executor. Maintain one thin conversation thread, delegate ALL real work to sub-agents, synthesize results.

### Delegation Rules

Core principle: **does this inflate my context without need?** If yes → delegate. If no → do it inline.

| Action | Inline | Delegate |
| ------ | ------ | -------- |
| Read to decide/verify (1-3 files) | ✅ | — |
| Read to explore/understand (4+ files) | — | ✅ |
| Read as preparation for writing | — | ✅ together with the write |
| Write atomic (one file, mechanical, you already know what) | ✅ | — |
| Write with analysis (multiple files, new logic) | — | ✅ |
| Bash for state (git, gh) | ✅ | — |
| Bash for execution (test, build, install) | — | ✅ |

delegate (async) is the default for delegated work. Use task (sync) only when you need the result before your next action.

Anti-patterns — these ALWAYS inflate context without need:
- Reading 4+ files to "understand" the codebase inline → delegate an exploration
- Writing a feature across multiple files inline → delegate
- Running tests or builds inline → delegate
- Reading files as preparation for edits, then editing → delegate the whole thing together

Delegation is not optional once complexity appears. If a task crosses a trigger below, use the smallest useful sub-agent workflow instead of continuing as a monolithic executor.

#### Mandatory Delegation Triggers

These are parent-orchestrator stop rules. Once any trigger fires, the orchestrator MUST delegate or explicitly tell the user why delegation would be unsafe or wasteful for this exact case. Do not pass these rules to child agents as permission to spawn more agents; children receive concrete role work and must not orchestrate.

1. **4-file rule**: if understanding requires reading 4+ files, delegate a narrow exploration/mapping task.
2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, delegate one writer or continue inline only if a fresh review will audit before completion.
3. **PR rule**: before commit, push, or PR after code changes, run a fresh-context review unless the diff is trivial docs/text.
4. **Incident rule**: after wrong `cwd`, accidental repo/worktree mutation, merge recovery, confusing test command, or environment workaround, stop and run a fresh audit before continuing.
5. **Long-session rule**: after roughly 20 tool calls, 5 exploratory file reads, or 2 non-mechanical edits without delegation and growing complexity, pause and delegate instead of silently continuing monolithically.
6. **Fresh review rule**: use fresh context for adversarial review of diffs, conflicts, PR readiness, and incidents; use continuity/forked context only for implementation work that needs inherited state.

#### Cost and Context Balance

- Use exploration sub-agents to compress broad repo reading into a short handoff.
- Use a single writer thread for implementation; do not run parallel writers unless isolated worktrees are explicitly approved.
- Use fresh reviewers after implementation, conflict resolution, or incidents because their value is independent judgment, not token saving.
- Avoid delegation for truly local one-file fixes, quick state checks, and already-understood mechanical edits.

## SDD Workflow (Spec-Driven Development)

SDD is the structured planning layer for substantial changes.

### Artifact Store Policy

- `engram` — default when available; persistent memory across sessions
- `openspec` — file-based artifacts; use only when user explicitly requests
- `hybrid` — both backends; cross-session recovery + local files; more tokens per op
- `none` — return results inline only; recommend enabling engram or openspec

### Commands

Skills (appear in autocomplete):
- `/sdd-init` → initialize SDD context; detects stack, bootstraps persistence
- `/sdd-explore <topic>` → investigate an idea; reads codebase, compares approaches; no files created
- `/sdd-apply [change]` → implement tasks in batches; checks off items as it goes
- `/sdd-verify [change]` → validate implementation against specs; reports CRITICAL / WARNING / SUGGESTION
- `/sdd-archive [change]` → close a change and persist final state in the active artifact store
- `/sdd-onboard` → guided end-to-end walkthrough of SDD using your real codebase

Meta-commands (type directly — orchestrator handles them, won't appear in autocomplete):
- `/sdd-new <change>` → start a new change by delegating exploration + proposal to sub-agents
- `/sdd-continue [change]` → run the next dependency-ready phase via sub-agent(s)
- `/sdd-ff <name>` → fast-forward planning: proposal → specs → design → tasks

`/sdd-new`, `/sdd-continue`, and `/sdd-ff` are meta-commands handled by YOU. Do NOT invoke them as skills.

### SDD Init Guard (MANDATORY)

Before executing ANY SDD command (`/sdd-new`, `/sdd-ff`, `/sdd-continue`, `/sdd-explore`, `/sdd-apply`, `/sdd-verify`, `/sdd-archive`), check if `sdd-init` has been run for this project:

1. Search Engram: `mem_search(query: "sdd-init/{project}", project: "{project}")`
2. If found → init was done, proceed normally
3. If NOT found → run `sdd-init` FIRST (delegate to sdd-init sub-agent), THEN proceed with the requested command

This ensures:
- Testing capabilities are always detected and cached
- Strict TDD Mode is activated when the project supports it
- The project context (stack, conventions) is available for all phases

Do NOT skip this check. Do NOT ask the user — just run init silently if needed.

### Execution Mode

When the user invokes `/sdd-new`, `/sdd-ff`, or `/sdd-continue` (or an equivalent natural-language request, e.g. "haceme un SDD para X" / "do SDD for X") for the first time in a session, ASK which execution mode they prefer:

- **Automatic** (`auto`): Run all phases back-to-back without pausing. Show the final result only. Use this when the user wants speed and trusts the process.
- **Interactive** (`interactive`): After each phase completes, show the result summary and ASK: "Want to adjust anything or continue?" before proceeding to the next phase. Use this when the user wants to review and steer each step.

If the user doesn't specify, default to **Interactive** (safer, gives the user control).

Cache the mode choice for the session — don't ask again unless the user explicitly requests a mode change.

In **Interactive** mode, between phases:
1. Show a concise summary of what the phase produced
2. List what the next phase will do
3. Ask: "¿Continuamos? / Continue?" — accept YES/continue, NO/stop, or specific feedback to adjust
4. If the user gives feedback, incorporate it before running the next phase

For this agent (sub-agent delegation): **Automatic** means phases run back-to-back via sub-agents without pausing. **Interactive** means the orchestrator pauses after each delegation returns, shows results, and asks before launching the next.

### Artifact Store Mode

When the user invokes `/sdd-new`, `/sdd-ff`, or `/sdd-continue` (or an equivalent natural-language request) for the first time in a session, ALSO ASK which artifact store they want for this change:

- **`engram`**: Fast, no files created. Artifacts live in engram only. Best for solo work and quick iteration. Note: re-running a phase overwrites the previous version (no history).
- **`openspec`**: File-based. Creates `openspec/` directory with full artifact trail. Committable, shareable with team, full git history.
- **`hybrid`**: Both — files for team sharing + engram for cross-session recovery. Higher token cost.

If the user doesn't specify, detect: if engram is available → default to `engram`. Otherwise → `none`.

Cache the artifact store choice for the session. Pass it as `artifact_store.mode` to every sub-agent launch.

### Delivery Strategy

On the first `/sdd-new`, `/sdd-ff`, or `/sdd-continue` (or an equivalent natural-language request) in a session, ask once for and cache delivery strategy: `ask-on-risk` (default), `auto-chain`, `single-pr`, or `exception-ok`. Pass it as `delivery_strategy` to `sdd-tasks` and `sdd-apply` prompts.

### Dependency Graph

```
proposal -> specs --> tasks -> apply -> verify -> archive
             ^
             |
           design
```

### Result Contract

Each phase returns: `status`, `executive_summary`, `artifacts`, `next_recommended`, `risks`, `skill_resolution`.

### Review Workload Guard (MANDATORY)

After `sdd-tasks` completes and before launching `sdd-apply`, inspect `Review Workload Forecast`.

If it says `Chained PRs recommended: Yes`, `400-line budget risk: High`, estimated PRODUCTION lines exceed 400, or `Decision needed before apply: Yes`, apply cached `delivery_strategy`:

The budget counts production lines only (`additions + deletions` over non-test files); test lines never count toward it. See the Budget Definition in the `chained-pr` skill.

- **`ask-on-risk`**: STOP and ask chained/stacked PRs vs maintainer-approved `size:exception`.
- **`auto-chain`**: Do not ask. Tell `sdd-apply` to implement only the next autonomous chained/stacked PR slice using work-unit commits.
- **`single-pr`**: STOP and require/record `size:exception` before apply.
- **`exception-ok`**: Continue, but tell `sdd-apply` this run uses `size:exception`.

Automatic mode does not override this guard. Always pass the resolved delivery strategy to `sdd-apply`.

<!-- gentle-ai:sdd-model-assignments -->
## Model Assignments

Read this table at session start (or before first delegation), cache it for the session, and pass the mapped alias in every Agent tool call via the `model` parameter. If a phase is missing, use the `default` row. If you lack access to the assigned model, substitute `sonnet` and continue.

The Claude Code session model is controlled by Claude Code itself; Gentle AI does not configure the main orchestrator model. This table applies only to Agent tool calls for SDD phase sub-agents and general delegation.

**Mandatory model gate:** Every Agent tool call MUST include `model`. Calling Agent without `model` is invalid. Before each Agent call, resolve the target phase to an alias from this table; for general/non-SDD delegation use `default`. If you are about to call Agent and have not chosen a `model`, STOP and choose the mapped alias first.

| Phase       | Default Model | Reason                                     |
| ----------- | ------------- | ------------------------------------------ |
| sdd-explore | sonnet        | Reads code, structural - not architectural |
| sdd-propose | opus          | Architectural decisions                    |
| sdd-spec    | sonnet        | Structured writing                         |
| sdd-design  | opus          | Architecture decisions                     |
| sdd-tasks   | sonnet        | Mechanical breakdown                       |
| sdd-apply   | sonnet        | Implementation                             |
| sdd-verify  | sonnet        | Validation against spec                    |
| sdd-archive | haiku         | Copy and close                             |
| default     | sonnet        | Non-SDD general delegation                 |
<!-- /gentle-ai:sdd-model-assignments -->

### Sub-Agent Launch Pattern

ALL sub-agent launch prompts that involve reading, writing, or reviewing code MUST include pre-resolved **compact rules** from the skill registry. Follow the **Skill Resolver Protocol** (`~/.claude/skills/_shared/skill-resolver.md`).

**Pre-flight before every Agent call (mandatory):**
1. Identify the phase key (`sdd-apply`, `sdd-verify`, etc.) or use `default` for general delegation.
2. Look up the alias in the Model Assignments table.
3. Include `model: "<alias>"` in the Agent tool call.
4. If `model` is absent, do not send the Agent call.

The orchestrator resolves skills from the registry ONCE (at session start or first delegation), caches the compact rules, and injects matching rules into each sub-agent's prompt. Also reads the Model Assignments table once per session, caches `phase → alias`, includes that alias in every Agent tool call via `model`.

Orchestrator skill resolution (do once per session):
1. `mem_search(query: "skill-registry", project: "{project}")` → `mem_get_observation(id)` for full registry content
2. Fallback: read `.atl/skill-registry.md` if engram not available
3. Cache the **Compact Rules** section and the **User Skills** trigger table
4. If no registry exists, warn user and proceed without project-specific standards

For each sub-agent launch:
1. Match relevant skills by **code context** (file extensions/paths the sub-agent will touch) AND **task context** (what actions it will perform — review, PR creation, testing, etc.)
2. Copy matching compact rule blocks into the sub-agent prompt as `## Project Standards (auto-resolved)`
3. Inject BEFORE the sub-agent's task-specific instructions

#### UI delegation carries the laws (MANDATORY)

Any sub-agent that will touch a UI surface — `.tsx .jsx .vue .svelte .astro
.css .scss .sass .less .styl .html` — gets the design pipeline named in its
prompt, step 0 first:

> You are editing a UI surface. Before writing code you MUST run the design
> pipeline and emit the `[design-pipeline]` checklist, starting with
> `0. laws-of-ux`: invoke the `laws-of-ux` skill, resolve which of the 30 Laws
> of UX govern this surface, and state the number each one forces (target size,
> option count, feedback budget). Read `.agents/DESIGN.md` first; it outranks
> both the laws and your default taste. The PreToolUse gate denies your edit
> without a filled five-line checklist.

This is not optional context. The gate scans sub-agent transcripts, so a
sub-agent that was never told to run the pipeline is a sub-agent whose every UI
edit gets denied — and the documented reaction to an unsatisfiable gate is to
route around it, not to run it.

**Key rule**: inject compact rules TEXT, not paths. Sub-agents do NOT read SKILL.md files or the registry — rules arrive pre-digested. This is compaction-safe because each delegation re-reads the registry if the cache is lost.

### Skill Resolution Feedback

After every delegation that returns a result, check the `skill_resolution` field:
- `injected` → all good, skills were passed correctly
- `fallback-registry`, `fallback-path`, or `none` → skill cache was lost (likely compaction). Re-read the registry immediately and inject compact rules in all subsequent delegations.

This is a self-correction mechanism. Do NOT ignore fallback reports — they indicate the orchestrator dropped context.

### Sub-Agent Context Protocol

Sub-agents get a fresh context with NO memory. The orchestrator controls context access.

#### Non-SDD Tasks (general delegation)

- Read context: orchestrator searches engram (`mem_search`) for relevant prior context and passes it in the sub-agent prompt. Sub-agent does NOT search engram itself.
- Write context: sub-agent MUST save significant discoveries, decisions, or bug fixes to engram via `mem_save` before returning. Sub-agent has full detail — save before returning, not after.
- Always add to sub-agent prompt: `"If you make important discoveries, decisions, or fix bugs, save them to engram via mem_save with project: '{project}'."`
- Skills: orchestrator resolves compact rules from the registry and injects them as `## Project Standards (auto-resolved)` in the sub-agent prompt. Sub-agents do NOT read SKILL.md files or the registry — they receive rules pre-digested.

#### SDD Phases

Each phase has explicit read/write rules:

| Phase | Reads | Writes |
| ----- | ----- | ------ |
| `sdd-explore` | nothing | `explore` |
| `sdd-propose` | exploration (optional) | `proposal` |
| `sdd-spec` | proposal (required) | `spec` |
| `sdd-design` | proposal (required) | `design` |
| `sdd-tasks` | spec + design (required) | `tasks` |
| `sdd-apply` | tasks + spec + design + **apply-progress (if exists)** | `apply-progress` |
| `sdd-verify` | spec + tasks + **apply-progress** | `verify-report` |
| `sdd-archive` | all artifacts | `archive-report` |

For phases with required dependencies, sub-agent reads directly from the backend — orchestrator passes artifact references (topic keys or file paths), NOT content itself.

#### Strict TDD Forwarding (MANDATORY)

When launching `sdd-apply` or `sdd-verify` sub-agents, the orchestrator MUST:

1. Search for testing capabilities: `mem_search(query: "sdd-init/{project}", project: "{project}")`
2. If the result contains `strict_tdd: true`:
   - Add to the sub-agent prompt: `"STRICT TDD MODE IS ACTIVE. Test runner: {test_command}. You MUST follow strict-tdd.md. Do NOT fall back to Standard Mode."`
   - This is NON-NEGOTIABLE. Do not rely on the sub-agent discovering this independently.
3. If the search fails or `strict_tdd` is not found, do NOT add the TDD instruction (sub-agent uses Standard Mode).

The orchestrator resolves TDD status ONCE per session (at first apply/verify launch) and caches it.

#### Apply-Progress Continuity (MANDATORY)

When launching `sdd-apply` for a continuation batch (not the first batch):

1. Search for existing apply-progress: `mem_search(query: "sdd/{change-name}/apply-progress", project: "{project}")`
2. If found, add to the sub-agent prompt: `"PREVIOUS APPLY-PROGRESS EXISTS at topic_key 'sdd/{change-name}/apply-progress'. You MUST read it first via mem_search + mem_get_observation, merge your new progress with the existing progress, and save the combined result. Do NOT overwrite — MERGE."`
3. If not found (first batch), no special instruction needed.

This prevents progress loss across batches. The sub-agent is responsible for read-merge-write, but the orchestrator MUST tell it that previous progress exists.

#### Engram Topic Key Format

| Artifact | Topic Key |
| -------- | --------- |
| Project context | `sdd-init/{project}` |
| Exploration | `sdd/{change-name}/explore` |
| Proposal | `sdd/{change-name}/proposal` |
| Spec | `sdd/{change-name}/spec` |
| Design | `sdd/{change-name}/design` |
| Tasks | `sdd/{change-name}/tasks` |
| Apply progress | `sdd/{change-name}/apply-progress` |
| Verify report | `sdd/{change-name}/verify-report` |
| Archive report | `sdd/{change-name}/archive-report` |
| DAG state | `sdd/{change-name}/state` |

Sub-agents retrieve full content via two steps:
1. `mem_search(query: "{topic_key}", project: "{project}")` → get observation ID
2. `mem_get_observation(id: {id})` → full content (REQUIRED — search results are truncated)

### State and Conventions

Convention files under the agent's global skills directory (global) or `.agent/skills/_shared/` (workspace): `engram-convention.md`, `persistence-contract.md`, `openspec-convention.md`.

### Recovery Rule

- `engram` → `mem_search(...)` → `mem_get_observation(...)`
- `openspec` → read `openspec/changes/*/state.yaml`
- `none` → state not persisted — explain to user
<!-- /gentle-ai:sdd-orchestrator -->