@orchestrator-claude/definitions 3.33.0 → 3.34.0

package/skills/release/SKILL.md

@@ -36,6 +36,7 @@ O script atualiza automaticamente:
 - `packages/mcp-server/package.json`
 - `packages/sdk/package.json`
 - `packages/definitions/package.json`
+- `packages/definitions/manifest.json` (regenerado da versao bumped — TD-193)
 - `packages/cli/src/index.ts` (CLI_VERSION constant)
 - `src/infrastructure/templates/base/package.json.hbs` (template versions)
 
@@ -78,13 +79,13 @@ git describe --tags --abbrev=0
 Sempre faca dry-run primeiro:
 
 ```bash
-./scripts/release.sh --dry-run patch
+.claude/skills/release/release.sh --dry-run patch
 ```
 
 ### 3. Executar Release
 
 ```bash
-./scripts/release.sh patch
+.claude/skills/release/release.sh patch
 ```
 
 ### 4. Monitorar CI/CD
@@ -101,9 +102,9 @@ User: "Faca release do fix que acabamos de fazer"
 
 Claude:
 1. Verifico pre-requisitos
-2. Executo: ./scripts/release.sh --dry-run patch
+2. Executo: .claude/skills/release/release.sh --dry-run patch
 3. Confirmo com usuario
-4. Executo: ./scripts/release.sh patch
+4. Executo: .claude/skills/release/release.sh patch
 5. Reporto URL do pipeline
 ```
 
@@ -114,9 +115,9 @@ User: "Release da nova feature de dashboard"
 
 Claude:
 1. Verifico CHANGELOG atualizado
-2. Executo: ./scripts/release.sh --dry-run minor
+2. Executo: .claude/skills/release/release.sh --dry-run minor
 3. Confirmo com usuario
-4. Executo: ./scripts/release.sh minor
+4. Executo: .claude/skills/release/release.sh minor
 ```
 
 ### Release de Major (Breaking Change)
@@ -126,10 +127,10 @@ User: "Precisamos fazer release 2.0.0"
 
 Claude:
 1. Verifico CHANGELOG com breaking changes documentados
-2. Executo: ./scripts/release.sh --dry-run 2.0.0
+2. Executo: .claude/skills/release/release.sh --dry-run 2.0.0
 3. ALERTA sobre breaking changes
 4. Confirmo DUAS vezes com usuario
-5. Executo: ./scripts/release.sh 2.0.0
+5. Executo: .claude/skills/release/release.sh 2.0.0
 ```
 
 ## Output Esperado
@@ -157,6 +158,7 @@ Files to update:
   - packages/mcp-server/package.json
   - packages/sdk/package.json
   - packages/definitions/package.json
+  - packages/definitions/manifest.json (regenerated from bumped version)
   - packages/cli/src/index.ts (CLI_VERSION)
   - src/infrastructure/templates/base/package.json.hbs (templates)
 
@@ -234,21 +236,30 @@ O push da tag dispara automaticamente:
 
 ## Definitions Manifest Sync
 
-Se houve alteracao em ficheiros de definitions (`packages/definitions/` ou `.claude/agents/`, `.claude/skills/`, `.claude/hooks/`, `.claude/workflows/`, `.claude/kb-docs/`), o `packages/definitions/manifest.json` DEVE ser regenerado **antes** do release.
+O `packages/definitions/manifest.json` e o indice unico de todas as built-in definitions
+com checksums SHA256 e o campo `version`. E consumido pela CLI (seed, sync) e MCP server, e
+o seu campo `version` e asserido pelo `ManifestLoader.test.ts`. Se ficar dessincronizado do
+`package.json`, o build regenera-o em CI para a versao nova e o teste falha — foi o que deixou
+`main` vermelho a cada release ate v3.32.1 (TD-193).
 
-O manifest e o indice unico de todas as built-in definitions com checksums. E consumido pela CLI (seed, sync) e MCP server. Se os checksums estiverem desactualizados, projectos scaffolded vao receber definitions stale.
+**Automatizado (TD-193):** o `release.sh` regenera o manifest **depois** do bump de versao
+(`regenerate_definitions_manifest`, via `npm run generate-manifest -w packages/definitions`),
+valida que `manifest.version === package.version`, e inclui `packages/definitions/manifest.json`
+no commit do bump. Como `generate-manifest` reescanea todas as definitions, isto tambem cobre
+mudancas de conteudo em `.claude/agents/`, `.claude/skills/`, `.claude/hooks/`, `.claude/kb/` —
+os checksums ficam sempre frescos. **Nao e mais necessario regenerar o manifest manualmente
+antes do release.**
 
-```bash
-# Verificar se definitions mudaram desde ultimo release
-git diff $(git describe --tags --abbrev=0) -- packages/definitions/ .claude/
+Para regenerar/inspeccionar o manifest fora de um release (debug):
 
-# Se houve mudancas, regenerar manifest
-npm run manifest:generate   # ou o comando equivalente do projecto
-git add packages/definitions/manifest.json
-git commit -m "chore: sync definitions manifest checksums"
+```bash
+npm run generate-manifest -w packages/definitions
+node -p "require('./packages/definitions/manifest.json').version"   # deve == package.json
 ```
 
-**REGRA:** Nunca faca release com definitions alteradas sem manifest actualizado. Isso causa uma release extra desnecessaria (como aconteceu no v3.9.3 -> v3.9.4).
+**REGRA (historica):** antes do TD-193 uma release com definitions alteradas sem manifest
+actualizado causava uma release extra desnecessaria (v3.9.3 -> v3.9.4) ou `main` vermelho
+(v3.32.1). O `release.sh` agora fecha esse gap; nao contorne o script fazendo bump manual.
 
 ## Secret Audit (Quarterly — TD-S188-003)
 

package/skills/release/release.sh

@@ -17,6 +17,10 @@ set -euo pipefail
 #   - packages/cli/package.json
 #   - packages/mcp-server/package.json
 #   - packages/sdk/package.json
+#   - packages/definitions/package.json
+#   - packages/definitions/.claude-plugin/plugin.json (native plugin manifest — RFC-040 §18, TD-212)
+#   - packages/definitions/manifest.json (regenerated from bumped version — TD-193)
+#   - packages/project-root-resolver/package.json (published dep of mcp-server — S387)
 #   - packages/cli/src/index.ts (CLI_VERSION constant)
 #   - src/infrastructure/templates/base/package.json.hbs (template versions)
 #
@@ -315,6 +319,18 @@ update_all_versions() {
   # Update SDK package
   update_package_version "packages/sdk/package.json" "$version"
 
+  # Update definitions package (ADR-003)
+  update_package_version "packages/definitions/package.json" "$version"
+
+  # Update native plugin manifest (RFC-040 §18). Keeps the Claude Code plugin
+  # version in lockstep with the definitions package; without this the plugin
+  # manifest stalls at its scaffold version (TD-212). plugin.json is a plain
+  # JSON with a top-level "version" field, so the generic JSON bump applies.
+  update_package_version "packages/definitions/.claude-plugin/plugin.json" "$version"
+
+  # Update project-root-resolver package (published dependency of mcp-server — S387)
+  update_package_version "packages/project-root-resolver/package.json" "$version"
+
   # Update CLI_VERSION constant
   update_cli_version_constant "$version"
 
@@ -345,6 +361,37 @@ run_build() {
   log_success "Build completed - dist/ updated with latest templates"
 }
 
+# Regenerate packages/definitions/manifest.json AFTER the version bump (TD-193).
+# run_build already regenerates the manifest, but it runs BEFORE update_all_versions,
+# so at that point the manifest still carries the OLD version. generate-manifest sources
+# packages/definitions/package.json, which is now bumped — regenerating here keeps the
+# committed manifest.json in lockstep with package.json and prevents ManifestLoader test
+# drift (root cause of main going red on every release, TD-193).
+regenerate_definitions_manifest() {
+  echo "🧾 Regenerating definitions manifest from bumped version..."
+
+  if [ "$DRY_RUN" = true ]; then
+    echo "  [dry-run] Would run: npm run generate-manifest -w packages/definitions"
+    return
+  fi
+
+  if ! npm run generate-manifest -w packages/definitions > /dev/null 2>&1; then
+    log_error "Manifest regeneration failed. Fix errors before releasing."
+    exit 1
+  fi
+
+  # Guard: the committed manifest version must now equal the bumped package version.
+  local manifest_version pkg_version
+  manifest_version=$(node -p "require('./packages/definitions/manifest.json').version")
+  pkg_version=$(node -p "require('./packages/definitions/package.json').version")
+  if [ "$manifest_version" != "$pkg_version" ]; then
+    log_error "Manifest version ($manifest_version) != package version ($pkg_version) after regen"
+    exit 1
+  fi
+
+  log_success "Manifest regenerated and version-synced to $manifest_version"
+}
+
 # ============================================================================
 # Git Functions
 # ============================================================================
@@ -362,6 +409,10 @@ commit_version_bump() {
     packages/cli/package.json \
     packages/mcp-server/package.json \
     packages/sdk/package.json \
+    packages/definitions/package.json \
+    packages/definitions/.claude-plugin/plugin.json \
+    packages/definitions/manifest.json \
+    packages/project-root-resolver/package.json \
     packages/cli/src/index.ts \
     src/infrastructure/templates/base/package.json.hbs
 
@@ -372,6 +423,10 @@ Updates:
 - packages/cli/package.json
 - packages/mcp-server/package.json
 - packages/sdk/package.json
+- packages/definitions/package.json
+- packages/definitions/.claude-plugin/plugin.json (native plugin manifest, RFC-040 §18)
+- packages/definitions/manifest.json (regenerated, TD-193)
+- packages/project-root-resolver/package.json (published dependency of mcp-server, S387)
 - packages/cli/src/index.ts (CLI_VERSION)
 - src/infrastructure/templates/base/package.json.hbs (templates)
 
@@ -446,16 +501,21 @@ main() {
   echo "  - packages/cli/package.json"
   echo "  - packages/mcp-server/package.json"
   echo "  - packages/sdk/package.json"
+  echo "  - packages/definitions/package.json"
+  echo "  - packages/definitions/.claude-plugin/plugin.json (native plugin manifest, RFC-040 §18)"
+  echo "  - packages/definitions/manifest.json (regenerated from bumped version)"
+  echo "  - packages/project-root-resolver/package.json (published dep of mcp-server, S387)"
   echo "  - packages/cli/src/index.ts (CLI_VERSION)"
   echo "  - src/infrastructure/templates/base/package.json.hbs (templates)"
   echo ""
   echo "Actions:"
   echo "  1. Build project (update dist/ with latest templates)"
   echo "  2. Update version in all files"
-  echo "  3. Commit version bump"
-  echo "  4. Create git tag $tag"
-  echo "  5. Push main + tag to origin"
-  echo "  6. CI/CD pipeline will publish npm + Docker"
+  echo "  3. Regenerate definitions manifest from bumped version (TD-193)"
+  echo "  4. Commit version bump"
+  echo "  5. Create git tag $tag"
+  echo "  6. Push main + tag to origin"
+  echo "  7. CI/CD pipeline will publish npm + Docker"
   echo ""
 
   if [ "$FORCE" = false ] && [ "$DRY_RUN" = false ]; then
@@ -470,6 +530,7 @@ main() {
   # Execute release steps
   run_build
   update_all_versions "$new_version"
+  regenerate_definitions_manifest
   commit_version_bump "$new_version"
   create_and_push_tag "$new_version"
 

package/skills/storybook-validated-loop/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: storybook-validated-loop
+description: Loop de prototipagem React component-driven usando Storybook como superfície de validação visual — a alternativa local (zero tokens SaaS, zero deploy) a loops de render SaaS (Bolt/v0/Lovable). Load when "storybook story", "component story", "nova tela react", "DSVL React", "canary para react", "validação visual component-driven", ou quando o frontend-engineer implementa telas. NÃO use para markdown-driven LLM-render (use design-system-validated-loop) nem slide decks (presentation-engineer).
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Storybook Validated Loop — Prototipagem React component-driven
+
+## When to Use This Skill
+
+Load this skill when:
+- Vai construir/refinar **telas React** de um app-alvo seguindo um design já aprovado.
+- A request contém: "storybook story", "component story", "nova tela react", "DSVL React", "canary para react", "validação visual component-driven".
+- O agent `frontend-engineer` é despachado para a fase React de um workflow.
+
+**Scope boundary — o que esta skill NÃO cobre:**
+- Patches markdown que dirigem LLM-render (Bolt/v0/Lovable) → use `design-system-validated-loop`.
+- Slide decks Slidev → use `presentation-engineer`.
+- Backend/infra (mock-first; sem APIs, sem deploy de servidor).
+
+## Contexto: por que Storybook (local) sobre loops de render SaaS
+
+Ferramentas de render SaaS (Bolt/v0/Lovable) cobram tokens por re-ingest/re-render e dependem de deploy externo. O **Storybook** assume o mesmo papel na ponta React do DSVL — superfície de desenvolvimento e validação visual **component-driven** — mas rodando **local** (zero tokens SaaS, zero deploy infra). Esta skill é a versão React-nativa do DSVL: reusa o esqueleto canary HTML e o protocolo de validação Playwright, mas troca "re-ingest/publish no SaaS" por "stories locais no Storybook".
+
+| Camada | Loop SaaS (Bolt/v0) | Storybook (local) |
+|---|---|---|
+| Superfície de componente | re-ingest no SaaS | `*.stories.tsx` local |
+| Validação visual | screenshot do render publicado | Playwright sobre Storybook local |
+| Custo | tokens SaaS + re-render | zero (build local) |
+| Audit trail | deploy URL | story + screenshot em `.cobaia-evidence/` |
+
+## O Loop (7 passos)
+
+> Anchor: um **design aprovado** (spec + wireframe). Ex: `docs/specs/2026-06-03-entrega-epi-design.md`.
+
+### Passo 0 — Ancorar no design aprovado
+Read o spec + o wireframe aprovado. Confirme escopo (telas, estados, critérios de aceitação). NÃO comece sem design aprovado (HARD GATE — herdado do brainstorming).
+
+### Passo 1 — Auditoria do Design System (Verify-Before-Assert)
+Antes de criar qualquer token/componente, **verifique empiricamente** no working tree:
+- Tokens → `Grep`/`Read` `src/index.css`; confirme cores/raios/tipografia citados no spec. NÃO assuma que um token existe.
+- Componentes → `Glob`/`Read` `src/components/` e `src/layouts/`; confirme reuso vs novo.
+- Se o design-system do projeto for **só `.md`** (não é lib instalável), os componentes reais vivem em `src/components/`.
+Liste patches de token necessários (novos aliases CSS) com justificativa. Divergência spec↔código = sinal: PARE e reporte.
+
+### Passo 2 — Canary HTML ("wire-frame")
+Preview auto-contido HTML dos frames, com os tokens reais, nos viewports (foco **375px**; conferir shell centralizado 768/1920). Reusa o esqueleto canary do DSVL. **Gate 1 (humano):** validação visual antes de virar React. Zero tokens downstream.
+
+### Passo 3 — Build component-driven (React + CSF3)
+Para **cada componente** do inventário:
+1. Implemente o componente em `src/components/<Global>.tsx` (global) ou `src/screens/<feat>/components/<Local>.tsx` (local), fiel aos tokens do DS.
+2. Escreva uma **story CSF3** `<Componente>.stories.tsx` cobrindo todos os estados/variantes (default + exceções, ex: EPI válido / a-vencer / bloqueado).
+3. Use `args`/`argTypes` para controles interativos; `parameters.viewport` para mobile 375px; addon-a11y deve passar.
+Componente isolado na story = contrato visual + sandbox de debug (o que o loop SaaS fazia, agora local).
+
+### Passo 4 — Validação visual no Storybook
+Suba o Storybook (`npm run storybook`) e use Playwright para screenshot de cada story nos viewports relevantes. Salve em `.cobaia-evidence/baseline/` e `.cobaia-evidence/fixed/`. **Gate 2 (humano):** revisão visual das stories antes de compor as telas. addon-a11y sem violações críticas.
+
+### Passo 5 — Composição de telas + rotas + mocks
+Componha os componentes validados nas telas/wizard. Adicione rota(s) em `src/App.tsx` (e shell novo se aplicável). Fixtures em `*.mock.ts` (mock-first: sem backend; integrações externas facial/PDF/hardware simuladas).
+
+### Passo 6 — Playwright E2E do fluxo
+Testes `*.spec.ts` cobrindo o fluxo ponta-a-ponta + estados de exceção, no **viewport 375px** (+ tablet/desktop p/ shell). Adicione um projeto `Mobile` no `playwright.config.ts` SEM remover os existentes. **Gate 3:** todos passam.
+
+### Passo 7 — Evidência + encerramento
+Screenshots de antes/depois, contagem de testes, cobertura. Memórias (RFC-027) sobre gotchas. Commit só quando o humano pedir.
+
+## Convenções de story (CSF3)
+
+```tsx
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { EpiItemCard } from './EpiItemCard';
+
+const meta: Meta<typeof EpiItemCard> = {
+  title: 'EntregaEPI/EpiItemCard',
+  component: EpiItemCard,
+  parameters: { viewport: { defaultViewport: 'mobile1' }, layout: 'centered' },
+  tags: ['autodocs'],
+};
+export default meta;
+type Story = StoryObj<typeof EpiItemCard>;
+
+export const Valido: Story    = { args: { statusCA: 'valido' } };
+export const AVencer: Story   = { args: { statusCA: 'a_vencer' } };
+export const Bloqueado: Story = { args: { statusCA: 'vencido', bloqueado: true } };
+```
+
+- `title` agrupa por feature (`EntregaEPI/...`).
+- Uma story por estado relevante (inclua exceções).
+- `parameters.viewport` para mobile; importe `src/index.css` no `.storybook/preview.tsx` (tokens do DS).
+
+## Gates (resumo)
+
+| Gate | Quando | Quem |
+|---|---|---|
+| HARD GATE design | antes do Passo 1 | design aprovado existe? |
+| Gate 1 | após canary HTML | humano valida visual |
+| Gate 2 | após stories | humano valida componentes isolados + a11y |
+| Gate 3 | após E2E | Playwright 375px verde |
+
+## O que esta skill substitui do DSVL
+
+- Etapa 2.5 Storybook (era validação SaaS-paralela) → vira o **núcleo** do loop React.
+- Etapa 4 "humano sincroniza SaaS + publica" → **removida** (Storybook local; sem SaaS).
+- Etapa 6.5 "route-around-SaaS + F5 manual" → **removida** (edição direta no repo + HMR do Vite).
+- Mantém: esqueleto canary (Etapa 1), protocolo Playwright de validação, estrutura de evidência/memória.
+
+## Token economy
+
+Storybook roda local: **zero tokens SaaS**, zero deploy. O custo desloca para build/HMR local (segundos). Substitui o burn de re-ingest/re-render de loops SaaS. Esta é a razão da migração para component-driven local.

package/skills/tdd-discipline/SKILL.md

@@ -11,6 +11,22 @@ description: TDD protocol for the implementer agent. Use when implementing tasks
 3. Refactor if needed (Refactor)
 4. Verify coverage >= 80%
 
+### Commit cadence (git-auditability)
+
+The RED→GREEN→REFACTOR cycle MUST be reflected in commit history — not collapsed into a single "scaffold" commit. Future reviewers walking `git log` should be able to see:
+
+- One commit per RED step (failing tests only — `raise NotImplementedError` stubs or absent impl is fine)
+- One commit per GREEN step (minimum impl that turns tests green)
+- (Optional) One commit per REFACTOR step (no behavior change)
+
+**Prohibited:** a single commit that contains BOTH failing tests AND their working implementation. This destroys TDD-discipline evidence post-merge — `git show <sha>` reveals nothing about whether tests were authored first.
+
+**Conventional Commits mapping:**
+- `test(<scope>): <TD-or-task-id> RED <one-line description>` — RED commit
+- `feat(<scope>): <TD-or-task-id> GREEN <one-line description>` (or `fix(...)` / `refactor(...)` as appropriate) — GREEN commit
+
+**Origin:** S226 wave-3e reviewer LOW-002 (commit `95f9b7c` merged tests+impl in scaffold). Promoted from TD-S226-016.
+
 ### Test File Location
 - Unit: tests/unit/<layer>/<domain>/<file>.test.ts
 - Integration: tests/integration/<feature>.integration.test.ts

package/skills/workflow-coordination/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workflow-coordination
-description: Teaches the orchestrator how to coordinate workflows via MCP tools. Use when starting, advancing, or managing workflows.
+description: Teaches how to coordinate workflows via MCP tools. Use when starting, advancing, or managing workflows. Aligned with RFC-022 skill-based orchestration.
 ---
 
 ## Workflow Coordination Protocol
@@ -14,10 +14,19 @@ You have access to MCP tools via deferred loading. To use any mcp__* tool:
 Note: ToolSearch results are cached — you only need to fetch each tool once per session.
 
 ### Starting a Workflow
-1. Call ToolSearch to load startWorkflow schema
-2. Call startWorkflow with: { name, type, projectId }
-3. startWorkflow automatically creates the workflow AND sets the first pendingAction
-4. Return the nextStep instruction to the main agent
+1. Call ToolSearch to load detectWorkflow + startWorkflow schemas
+2. Call detectWorkflow with: { prompt: "user request" }
+3. Call startWorkflow with: { name, type, projectId }
+4. startWorkflow automatically creates the workflow AND sets the first pendingAction
+5. Dispatch the first phase sub-agent via Agent tool from the main conversation
+
+### Orchestration Model (RFC-022)
+
+The **main conversation is the orchestrator**. There is no orchestrator sub-agent.
+
+- Phase sub-agents (specifier, planner, implementer, etc.) are dispatched via `Agent(subagent_type: "...")` directly from the main conversation
+- Gates between phases use `AskUserQuestion` — never auto-approve
+- The `/orchestrator` skill is the universal entry point
 
 ### Deterministic Hooks (ADR-013)
 
@@ -25,16 +34,17 @@ Orchestration governance is enforced by hooks, not by prompt instructions:
 
 | Hook | When | Effect |
 |------|------|--------|
-| `ping-pong-enforcer` | After every Agent call | Auto-calls getNextAction, injects result |
-| `gate-guardian` | Before advancePhase | Auto-evaluates gate, blocks if fails |
-| `dangling-workflow-guard` | On session Stop | Warns and completes dangling workflows |
-
-You do NOT need to manually call getNextAction or evaluateGate — hooks handle this.
+| `gate-guardian` | Before advancePhase | Blocks IMPLEMENT phase without approval |
+| `workflow-guard` | Before Write/Edit on src/ | Blocks code writes without active workflow |
+| `dangling-workflow-guard` | On session Stop | Warns about dangling workflows |
+| `session-orchestrator` | On session Start | Injects workflow status context |
+| `prompt-orchestrator` | On user prompt Submit | Injects workflow hints |
 
 ### Phase Advancement
-1. Call advancePhase — the gate-guardian hook evaluates the gate automatically
-2. If gate PASSES: advancePhase proceeds, set pendingAction for next agent
-3. If gate FAILS: hook blocks the call and returns failure reasons
+1. Present artifact summary to user via AskUserQuestion
+2. If user approves: call advancePhase
+3. If user requests changes: re-dispatch the same sub-agent with feedback
+4. The gate-guardian hook provides an additional safety check
 
 ### Phase → Agent Mapping
 
@@ -51,8 +61,99 @@ You do NOT need to manually call getNextAction or evaluateGate — hooks handle
 - SPECIFY: spec.md exists in MinIO, has required sections
 - PLAN: plan.md exists, references spec, has architecture section
 - TASKS: tasks.md exists, tasks are atomic, has acceptance criteria
-- IMPLEMENT: requires human approval (status: awaiting_approval)
+- IMPLEMENT: requires human approval via AskUserQuestion
 
 ### Observability
-After EVERY action, call startAgentInvocation/completeAgentInvocation
-to track your own execution in PostgreSQL.
+Hooks automatically track agent invocations via SubagentStart/SubagentStop events.
+Git checkpoints are created automatically after phase completion.
+
+---
+
+### Starting a Sprint from Parent Document
+
+Use this algorithm when the user asks to "start Sprint N of RFC-XXX" or when a sprint decomposition table exists in a parent document.
+
+#### Step 1 — Identify the Target Sprint
+
+1. Read the parent RFC or ADR file (e.g. `project-guidelines/rfcs/RFC-027-*.md`)
+2. Find the **Sprint Decomposition** table
+3. Identify the target sprint row by index (S1, S2, ... SN)
+4. Extract: scope, estimate, status, deliverables
+
+#### Step 2 — Choose Phase Pipeline
+
+Based on the sprint scope, select the appropriate phase pipeline:
+
+| Condition | Phase Pipeline |
+|-----------|---------------|
+| Exploration needed before specifying (novel design) | `research → specify → plan → tasks → implement` |
+| Design is clear enough for a spec but not a plan | `specify → plan → tasks → implement` |
+| Scope is well-defined, plan can be derived directly | `plan → tasks → implement` |
+
+Default for new sprints: start with `specify` unless the sprint explicitly says "research first".
+
+#### Step 3 — Start the Workflow with Sprint Metadata
+
+When calling `startWorkflow`, include sprint metadata:
+
+```
+mcp__orchestrator-tools__startWorkflow({
+  type: "feature_development",
+  prompt: "[Sprint N scope from the parent document]",
+  metadata: {
+    parentDocument: "project-guidelines/rfcs/RFC-NNN-TITLE.md",
+    sprintIndex: N
+  }
+})
+```
+
+The `metadata` fields are stored with the workflow for observability and sprint-context seed.
+
+#### Step 4 — Seed Sprint Context
+
+After the workflow is created, seed `.claude/sprint-context/{workflowId}.json`:
+
+```json
+{
+  "schema": "1.0",
+  "parentDocument": "project-guidelines/rfcs/RFC-NNN-TITLE.md",
+  "sprintIndex": N,
+  "sprintScope": "[Sprint N scope]",
+  "previousSprints": [
+    { "index": 1, "status": "complete", "deliverables": ["..."] },
+    { "index": 2, "status": "complete", "deliverables": ["..."] }
+  ],
+  "workflowId": "{workflowId from startWorkflow response}",
+  "createdAt": "{ISO-8601 UTC timestamp}"
+}
+```
+
+Only include sprints with `status: "complete"`, `"skipped"`, or `"in_progress"` (if a prior sprint was abandoned) in `previousSprints`. Omit the current sprint.
+
+#### Step 5 — Per-Sprint Brainstorm Context
+
+When dispatching a researcher or specifier agent for a sprint that involves brainstorming:
+
+1. Read the parent document excerpt relevant to this sprint
+2. Include in the agent prompt:
+   - The parent document path
+   - The Sprint Decomposition table row for this sprint
+   - A summary of `previousSprints` (completed deliverables)
+3. The `user-prompt.ts` hook will automatically inject `[PARENT-DOC-CONTEXT]` if the sprint context file exists and the prompt contains "brainstorm"
+
+Example agent prompt structure:
+```
+Execute Sprint N of {parentDocument}.
+Sprint scope: {sprintScope}
+Previous sprints: {previousSprints summary}
+[Read {parentDocument} for full context before starting]
+```
+
+#### Step 6 — Update Sprint Context After Completion
+
+When a sprint workflow completes:
+1. Update `.claude/sprint-context/{workflowId}.json` with the next sprint's data
+2. Move the completed sprint to `previousSprints` with `status: "complete"`
+3. Update `sprintIndex` to N+1 and `sprintScope` to the next sprint row scope
+
+This ensures the next sprint brainstorm automatically receives full history context.