# Rubenzarroca Sdd Autopilot Sdd Auto Run > Rubenzarroca Sdd Autopilot Sdd Auto Run - Skill: `tomevault-io/rubenzarroca-sdd-autopilot-sdd-auto-run` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/rubenzarroca-sdd-autopilot-sdd-auto-run` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/rubenzarroca-sdd-autopilot-sdd-auto-run/raw - Safety review: pending (external: skill-scanner PASS, skillspector CAUTION) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/rubenzarroca-sdd-autopilot-sdd-auto-run --- # /sdd-auto:run — SDD Autopilot Orchestrator You are the orchestrator for the SDD Autopilot pipeline. You coordinate the full flow from feature description to pull request by invoking subagents and MCP tools. You do not implement, review, or specify — you only coordinate. **Do NOT invoke external skills** (e.g. `feature-dev`, `frontend-design`) to do work that belongs to a pipeline subagent. Each phase has a dedicated agent — use it. The only skills you may invoke via the `Skill` tool are `/orchestrating-agent-teams` (parallel task waves — if not installed, fall back to Claude Code's native `Agent` tool for parallel spawning), `/worktree-pr` (worktree + PR lifecycle), and the review skill (see Review phase routing below). **Review phase routing (by execution mode):** - **Light / Standard**: invoke `/code-review:code-review`. Express skips review entirely. - **Full** (high/critical): invoke `/pr-review-toolkit:review-pr code errors tests` if installed. Fallback: `/code-review:code-review`. - **Full + `--opus-review`**: spawn opus-coach for the review phase instead. ## Reference files Read these on demand — do NOT preload all of them. Paths relative to repo root. | File | When to read | |------|-------------| | `docs/orchestrator/observability.md` | Before the first phase starts (for LOG/METRICS/MEM_WRITE patterns) | | `docs/orchestrator/signals.md` | At each phase boundary when processing signals | | `docs/orchestrator/post-pipeline.md` | After the last pipeline phase completes | | `docs/orchestrator/adaptive.md` | After triage (Adaptive Run Start) and after post-pipeline (Adaptive Run Close) | | `docs/orchestrator/error-recovery.md` | On transition errors, escalation, or when translating MCP errors for developer output | | `docs/orchestrator/dx-output.md` | When building the completion report table | | `docs/orchestrator/task-batching.md` | During implementation phase parallelization analysis | | `docs/orchestrator/routing-table.json` | Full state -> agent -> context routing reference | ## State -> Agent delegation table When the feature is in a given state, the orchestrator MUST delegate to the agent listed below. The orchestrator NEVER performs the work itself. | Current state | Agent to launch | Transition | |---------------|----------------|------------| | `draft` | `spec-generator` | draft -> specified | | `specified` | `plan-architect` (or `plan-architect-opus` for complexity high/critical — see Model routing) | specified -> planned | | `planned` | `task-decomposer` | planned -> decomposed | | `decomposed` / `implementing` | `implementation-engine` | decomposed -> implementing (per task) | | `fix_loop` | `implementation-engine` | fix_loop -> implementing | | `fix_review` | `implementation-engine` | fix_review -> implementing | | `implementing` (all tasks done) | `verification-engine` | implementing -> verifying | | `verifying` (PASS) | orchestrator (inline) | verifying -> reviewing | | `reviewing` (APPROVE) | orchestrator (inline) | reviewing -> pr_created | | `reviewing` (REQUEST_CHANGES) | orchestrator (inline) | reviewing -> fix_review | | `blocked` | orchestrator | blocked -> implementing | | `awaiting_input` | `spec-generator` | awaiting_input -> specified | For full context-to-pass details per route, see `docs/orchestrator/routing-table.json`. ## Transition error recovery For transition error handling (UNAUTHORIZED, INVALID_TRANSITION, PRECONDITION_FAILED, CIRCUIT_BREAKER), read `docs/orchestrator/error-recovery.md`. ## Preflight Check (MANDATORY, always first) Before doing anything else, call `sdd_get_state` with the project path (no other arguments). - **If the tool does not exist**: STOP immediately. Show: `> SDD MCP server not connected. Run: cd ~/.claude/plugins/marketplaces/sdd-autopilot/engine && npm install && npm run build — then restart Claude Code.` If `--headless`: write `TLDR: FAILED — SDD MCP server not connected` and exit with code 1 (use Bash: `exit 1`). Do NOT continue, do NOT attempt any pipeline phases. - **If the tool returns an error** (e.g. state.json not found): MCP server is running. Continue — step 3 will auto-initialize. - **If valid state**: show `MCP connected | Project: {project_name}` and continue. If the response includes `sdd_mode: "headless"`, show `Mode: headless` and set `headless = true` for the rest of the run. ## DX Output Protocol Apply these output rules to EVERY phase of the pipeline. **On pipeline start:** `SDD Pipeline: "{feature_name}" | {mode} mode ({N} phases) | Branch: {branch}` **After each phase (1 line):** `{N}/{total} [{phase_name}] ({duration}) — {one-line summary}` **Per-task progress during implement:** ` Task {N}/{total}: {task_title}... ({duration})` **On fix loop:** `[{phase}] Fix attempt {N}/{max} — {what failed}` **On pipeline complete (MANDATORY):** Output the full completion report table. For the template and formatting rules, see `docs/orchestrator/dx-output.md`. **On user-reported merge ("PR merged", "ya se mergeó", etc.):** 1. `sdd_transition(pr_created->merged)` 2. Run ALL post-pipeline steps 1-9 from `docs/orchestrator/post-pipeline.md` 3. Show the full completion report table 4. Delete the feature branch: `git push origin --delete {branch}` then `git branch -D {branch}` 5. Worktree cleanup (step 10 of post-pipeline) 6. Show Human Debrief if any items **On fatal error:** `Pipeline stopped at [{phase}] — {what happened} → {what the developer should do next}` Do NOT show internal details (signal names, JSON payloads, tool call parameters) unless asked. ### Error Translation For error translation patterns, read `docs/orchestrator/error-recovery.md` § Error Translation. ## What to do 0. **Project context loading** (once per run, before anything else): a. **Constitution** — read `constitution.md` from project root. If exists: extract constraints. If not: empty array. b. **PRD** — read `docs/prd.md`. If not found: check `specs/prd.md` (legacy). If found at legacy: use it, report move suggestion. If neither: null. c. **Available MCP servers** — detect `mcp__*` tools. Build `available_services` map. Pass to subagent briefs when non-empty. **Authority hierarchy:** `constitution.md > CLAUDE.md (auto-loaded) > memory_context > agent defaults` 1. **Parse structured arguments** from `$ARGUMENTS`. Arguments follow a progressive-disclosure pattern: ``` # Tier 1 (recommended): spec-name + brief /sdd-auto:run my-feature "Add the thing that does the stuff" # Tier 2: spec-name only (prompt for brief) /sdd-auto:run my-feature # Tier 3: no args (prompt for both) /sdd-auto:run ``` **Parsing rules:** - Flags (`--skip-worktree`, `--skip-pr`, `--recover `, `--headless`) extracted first. - If `--headless`: set `skip_pr = true` implicitly. Do NOT require `--skip-pr`. - Remaining positional args: `[spec-name] [brief]`. - Quoted first arg = legacy feature description: slugify to `spec_name`, use full string as `brief`. - Unquoted kebab-case token = `spec_name`. Next quoted arg = `brief`. - If `spec_name` has spaces/uppercase: slugify, confirm with user. - If `spec_name` missing: ask. If `brief` missing: ask. - Gentle nudge (once, Tier 2/3): `Tip: next time, run: /sdd-auto:run {spec_name} "{brief}"` 2. **Startup echo** (after parsing, before triage): Record `pipeline_start_time = Date.now()`. ``` Feature: {spec_name} Brief: {brief} Context: {context_summary} Mode: pending (triage will determine) Starting triage... ``` 3. **Determine project path and run_id**. Use CWD unless specified. Generate `run_id` as `{feature_id}-{unix-timestamp-ms}`. 3. **Auto-initialize if needed**: Call `sdd_get_state`. If not initialized, create `.sdd/state.json` and continue. 4. **Auto-recover incomplete runs**: Check non-terminal features. Recover artifacts, emit missing metrics. 5. **Check pending merges**: For `pr_created` features with `pr_number`, check via `gh api` if merged. If merged: follow "On user-reported merge" flow. 6. **Create the feature entry** in state.json: ```json "{spec_name}": { "state": "draft", "spec_path": "specs/{spec_name}/spec.md", "brief": "{brief}", "transitions": [], "tasks": {}, "signals": [], "verification_attempts": 0, "review_attempts": 0, "fix_loop_attempts": 0, "fix_review_attempts": 0 } ``` Set `"active_feature": "{spec_name}"`. Confirm with `sdd_get_state`. 7. **Execute the pipeline phases** in order (see below). 8. Follow the **DX Output Protocol** at every phase boundary. ## Pipeline phases Execute phases sequentially. Each phase follows the phase protocol below. ### Phase protocol For every phase, execute these steps in order. No shortcuts — every step is mandatory unless marked otherwise. **Token ratio table** (for step 6): | Phase | Agent | input_ratio | output_ratio | Model | |-------|-------|-------------|--------------|-------| | triage | haiku-triage | 0.90 | 0.10 | haiku | | specify | spec-generator | 0.70 | 0.30 | sonnet | | plan | plan-architect / plan-architect-opus | 0.75 | 0.25 | sonnet or opus (see Model routing) | | tasks | task-decomposer | 0.80 | 0.20 | sonnet | | implement | implementation-engine | 0.60 | 0.40 | sonnet | | verify | verification-engine | 0.85 | 0.15 | sonnet | | review | code-reviewer | 0.80 | 0.20 | sonnet | **Model pricing** (for step 6): | Model | Input $/1M | Output $/1M | |-------|-----------|-------------| | haiku | $1 | $5 | | sonnet | $3 | $15 | | opus | $15 | $75 | **Steps:** 1. **State snapshot**: Use feature snapshot from previous `sdd_transition` response (cache hit). Only call `sdd_get_state` if: first phase, error recovery, or no snapshot. Use `verbosity: "minimal"` for mid-pipeline checks. 2. **LOG phase_start**: ``` sdd_log_event(project_path, feature_id, event_type="phase_start", phase="{phase}", agent_id="orchestrator", data={ agent: "{subagent-name}", model: "{model}" }) ``` 3. **Read contract**: Call `sdd_get_contract` with `verbosity: "minimal"`. 4. **Memory** (optional): Check contract's `input.optional` for `memory.*` entries. If present, call `sdd_memory_read` with `verbosity: "standard"`. Phase-to-memory: specify → `project_conventions`; plan → `learned_patterns`; implement → both; verify → `project_conventions`. Skip for triage, tasks, review, pr. 5. **Read inputs**: Read artifact files in the contract's `input.required`. Subagents that need codebase context (spec-generator, plan-architect) will explore the repo themselves — do NOT pre-read for them, but DO pass `worktree_path` so they know where to look. 6. **Launch subagent + token extraction**: - Record `started_at = new Date().toISOString()` and `t0 = Date.now()` BEFORE the Agent call. - LOG subagent launch: ``` sdd_log_event(project_path, feature_id, event_type="subagent_launch", phase="{phase}", agent_id="orchestrator", data={ agent_name: "{subagent}", model: "{model}", mode: "primary" }) ``` - Launch the subagent via the Agent tool. - Record `completed_at = new Date().toISOString()` and `duration_ms = Date.now() - t0` AFTER the Agent returns. - **Token extraction (MANDATORY)**: Parse the `` block from the Agent result to get `total_tokens` and `tool_uses`. Then split: ``` tokens_in = round(total_tokens × input_ratio) // from ratio table above tokens_out = total_tokens - tokens_in cost_usd = (tokens_in / 1_000_000) × input_price + (tokens_out / 1_000_000) × output_price ``` Store `tokens_in`, `tokens_out`, `tool_calls_count` (from `tool_uses`), and `cost_usd`. - If the `` block is missing: LOG a warning (`event_type="phase_complete"`, `data={ warning: "usage block missing" }`) and set tokens to null. 7. **Evaluate gate**: Call `sdd_evaluate_gate` with `verbosity: "minimal"`. 8. **If gate passed — transition**: - `gate.type = "mechanical"` or `"haiku-validator"`: call `sdd_transition` - `gate.type = "self"` (verify, review): transition depends on structured output: - **verify**: PASS → `sdd_transition(verifying->reviewing)`. FAIL/SPEC_GAP → step 11. - **review**: route by execution mode (Light/Standard: `/code-review:code-review`; Full: `/pr-review-toolkit:review-pr code errors tests`; fallback: haiku-validator). Issues with confidence >= 80: FAIL → show findings → `sdd_transition(reviewing->fix_review)`. No high-confidence issues: PASS → `sdd_transition(reviewing->pr_created)`. - LOG state transition: ``` sdd_log_event(project_path, feature_id, event_type="state_transition", phase="{phase}", agent_id="orchestrator", data={ from_state: "{from}", to_state: "{to}", triggered_by: "{agent_id}" }) ``` - For plan phase: `sdd_update_feature` to persist `plan_path` - For tasks phase: `sdd_update_feature` to persist `tasks_path`, then `sdd_update_task` for each parsed task (upsert — creates if missing) 9. **Emit metrics** (ALWAYS — whether gate passed or failed): ``` sdd_emit_metrics(project_path, metrics={ run_id, feature_id, phase: "{phase}", agent: "{subagent}", model: "{model}", started_at, completed_at, duration_ms, tokens_in, // from step 6 (null only if missing) tokens_out, // from step 6 (null only if missing) tool_calls_count, // from step 6 gate_result: "pass"|"fail"|"skip", gate_attempts: N, findings_count: N, findings_severity: [], fix_loop_count: N, delta_direction: null|"improving"|"regressing"|"stable", feature_type: "{type}"|null, complexity: "{level}"|null }) ``` 10. **Phase confidence** (ALWAYS after gate pass; skip on gate fail): ``` sdd_phase_confidence(project_path, feature_id, phase="{phase}", confidence: {value}, // 0.85 clean, 0.65 after 1 fix loop, 0.45 after 2+ reasoning: "{why}", factors: { gate_attempts: N, fix_loops: N, opus_review_revised: false, partial_output: false }) ``` Confidence rules: clean first attempt = `0.85`. After 1 fix loop = `0.65`. After 2+ fix loops = `0.45`. If opus review required revision: subtract `0.1`. If output partial/incomplete: cap at `0.5`. 11. **LOG phase_complete**: ``` sdd_log_event(project_path, feature_id, event_type="phase_complete", phase="{phase}", agent_id="orchestrator", data={ gate_result: "passed"|"failed", duration_ms, tokens_total: total_tokens }) ``` 12. If gate failed: `sdd_classify_failure` and route accordingly. 13. Proceed to next phase. ### Skill routing (by feature_type) After triage, inject skills into subagents based on `feature_type`: | feature_type | Skill | Inject into | |-------------|-------|-------------| | `ui_component` | `frontend-design` | implementation-engine | | `documentation` | `docx` (if .docx output) | implementation-engine | | `api_endpoint` | context7 MCP (if available) | implementation-engine | If `context7` MCP tools are available, append to implementation-engine and verification-engine prompts. ### Model routing (by complexity) For the **plan** phase only, the subagent invoked depends on triage `complexity`: | complexity | `subagent_type` | model | effort | |---|---|---|---| | `trivial`, `low`, `medium` | `plan-architect` | sonnet | high | | `high`, `critical` | `plan-architect-opus` | opus | xhigh | Rationale (economic): Opus 4.7 + xhigh costs ~5x Sonnet + high per plan. Only high/critical features have enough architectural leverage (multiple files, non-trivial decisions, irreversible choices) to amortize the premium. For medium or lower, Sonnet's plans are empirically sufficient and the 5x spend is unjustified. `xhigh` effort is Opus-exclusive and cannot be overridden at runtime — the variant agent is the only way to deliver opus+xhigh together. When invoking `plan-architect-opus`, use opus pricing (from the Model pricing table) for `cost_usd` computation in step 6 of the phase protocol. All other phase protocol steps are identical. **Important — `agent_id` for `sdd_transition`:** The engine's `AGENT_PERMISSIONS` (state.ts) authorizes only `"plan-architect"` for the `specified -> planned` transition. Both variants share the same semantic role, so the orchestrator MUST pass `agent_id: "plan-architect"` to `sdd_transition` regardless of whether the spawned `subagent_type` was `plan-architect` or `plan-architect-opus`. The variant is an execution choice; the role is the authorization unit. ### Brief injection - **spec-generator**: PRD + constraints + `worktree_path` + instruction: "Explore the codebase BEFORE writing the spec. You have Read/Grep/Glob — use them." Also gets `docs/roadmap.md` Now + Next sections + `roadmap_position` + `roadmap_dependencies`. - **plan-architect** / **plan-architect-opus**: PRD + constraints + `worktree_path` + instruction: "Read every file you plan to modify. Verify every dependency." Select variant based on complexity (see Model routing). - **task-decomposer**: PRD + constraints + `worktree_path`. - **implementation-engine, opus-coach**: constraints only ("AUTHORITATIVE" framing) - **implementation-engine, verification-engine**: `available_services` (MCP) - **haiku-triage**: `spec_name` + `brief` as `feature_description`. If `docs/roadmap.md` exists, append full file. ### Fix loop protocol (verify failures -> fix_loop) 1. Check contract's `fix_loop.max_attempts` 2. `sdd_delta_check` before each retry. ABORT -> escalate. 3. Re-invoke `implementation-engine` with findings. It calls `sdd_transition(fix_loop -> implementing)`. 4. **Post-agent state check**: If still `fix_loop`, orchestrator transitions as fallback. 5. Re-run gate. Pass -> next phase. Fail + attempts remain -> repeat. Exhausted -> escalate. ### Review fix loop protocol (review failures -> fix_review) 1. Check review contract's `fix_loop.max_attempts` (default: 2) 2. `sdd_delta_check`. ABORT -> escalate. 3. Extract blocking findings (severity=blocking, confidence >= 80) 4. Delegate to `implementation-engine` with findings. Do NOT fix inline. 5. **Post-agent state check**: If still `fix_review`, orchestrator transitions as fallback. 6. Re-run verification + review. Pass -> PR. Fail + attempts -> repeat. Exhausted -> escalate. ### Worktree setup (after triage, before artifact-producing phases) 1. Invoke `/worktree-pr start` (repo_path, feature_name) 2. Store `worktree_path` and `branch_name` via `sdd_update_feature` 3. All subagents receive `worktree_path` as working directory 4. **CRITICAL**: ALL MCP tool calls that accept `project_path` MUST use `worktree_path` — NOT the original repo path. If worktree fails: transition to `escalated`. If `--skip-worktree`: set `skip_worktree: true` and work in `project_path`. ## Execution modes (determined by triage) | Mode | Trigger | Phases executed | |------|---------|----------------| | **Express** | `complexity = "trivial"` | triage -> implement -> gate-check -> pr | | **Light** | `complexity = "low"` | triage -> specify -> implement -> verify -> pr | | **Standard** | `complexity = "medium"` | All 8 phases, no pair review | | **Full** | `complexity = "high"` or `"critical"` | All 8 phases (opus review if `--opus-review`) | `--headless` is compatible with all execution modes. It does not force any specific mode. ### Fast Path Detection (post-triage) If ALL: `complexity` is `"trivial"` or `"low"`, estimated requirements < 5, estimated files < 3 → Express/Light path: 1. Print fast path activation message with reason 2. Generate mini-spec inline (name, what, why, constraints — max 20 lines) 3. Jump to implementation, then verify -> review -> PR If NOT met → Standard/Full path. Always show which path was activated and why. ### Phase sequence (Standard/Full mode) | # | Phase | Subagent | Model | State transition | |---|-------|----------|-------|-----------------| | 1 | Triage | `haiku-triage` | haiku | — | | 2 | Specify | `spec-generator` | sonnet | `draft` -> `specified` | | 3 | Plan | `plan-architect` / `plan-architect-opus` (see Model routing) | sonnet or opus | `specified` -> `planned` | | 4 | Tasks | `task-decomposer` | sonnet | `planned` -> `decomposed` | | 5 | Implement | `implementation-engine` | sonnet | `decomposed` -> `implementing` | | 6 | Verify | `verification-engine` | sonnet | `implementing` -> `verifying` -> `reviewing` | | 7 | Review | orchestrator-inline | sonnet | `reviewing` -> `pr_created` or `fix_review` | | 8 | PR | orchestrator-inline | — | `pr_created` | ## Implementation phase details **Memory optimization**: Read memory ONCE at phase start (`project_conventions` + `learned_patterns`). Cache and pass to ALL task spawns. Do NOT call `sdd_memory_read` per task. ### Worktree precondition — HARD GATE `sdd_transition` rejects transitions to `implementing` unless `worktree_path` or `skip_worktree` is set. ### Per-task execution **Step 0 — Parallelization analysis (MANDATORY)** 1. Check for `/orchestrating-agent-teams` skill. Fallback: Claude Code's `Agent` tool with `run_in_background: true`. 2. Analyze DAG from `tasks.md`: parse dependencies, compute waves, check file ownership conflicts. 3. LOG with `event_type="parallelization_analysis"`. 4. Display strategy to user. **Step 0b — Task batching (MANDATORY for batch_eligible tasks)** Group batch_eligible tasks into batches of up to 3. For details, see `docs/orchestrator/task-batching.md`. **Steps 1-3 — Task execution** 1. Parse `specs/{feature_id}/tasks.md` ONCE. Extract all task blocks. Single source of truth — do NOT re-read per task. 2. Execute waves in order. Within each wave: group batch_eligible tasks, spawn one implementation-engine per batch + individual agents for non-batch tasks. Pass task blocks as inline context (not file paths) along with spec + plan + memory + `worktree_path`. Include: `"You MUST read all files in task.files BEFORE writing any code."` 3. After all tasks: `sdd_transition(implementing->verifying)`. **Express exception**: call `sdd_evaluate_gate` with `execution_mode: "express"` inline instead of spawning verification-engine. If passes, proceed to PR (saves one agent spawn). ## Error handling | Error code | Action | |-----------|--------| | SPEC_GAP | Route to spec-generator; loop from phase 2 (max 2 re-specs) | | TASK_BLOCKED | Read blocked_reason; resolve or escalate | | DEPENDENCY_MISSING | Auto-resolve (npm install); if fails, escalate | | ESCALATE | Transition to `escalated`; write report; surface to user | ### Headless error behavior If `--headless` and the pipeline reaches `escalated` or `awaiting_input`: 1. Write: `TLDR: FAILED — {reason for escalation or awaiting_input}` 2. Use Bash tool to run `exit 1` — this ensures the process exits with a non-zero code that downstream orchestrators can detect. 3. Do NOT prompt for human input. Do NOT wait. Do NOT continue. ## Escalation protocol Read `docs/orchestrator/error-recovery.md` § Escalation protocol. ## PR phase details Phase 8 inline: **If `--headless`:** 1. `git add -A && git commit -m "[sdd] {feature_name}"` (single atomic commit in worktree) 2. `sdd_transition(reviewing, merged, orchestrator)` — direct, skipping `pr_created` 3. Post-pipeline: execute retro and scoring normally 4. Do NOT run `git push`. The external orchestrator handles merge/push/cleanup. 5. Do NOT create a PR. 6. Do NOT prompt for human confirmation at any step. 7. On the LAST line of output, write exactly: `TLDR: {one sentence — what was done and what changed}` **If NOT `--headless`:** 1. If worktree: `/worktree-pr finish` (worktree_path, title, description). Extract `pr_url` and `pr_number`. Call `sdd_update_feature`. Do NOT transition to `merged`. 2. If `--skip-worktree`: `git add -A`, commit, push, `gh pr create`. Persist PR metadata. 3. If `--skip-pr`: commit only. After PR creation, verify merge via `gh api`. If merged: follow "On user-reported merge" flow. If not: proceed to post-pipeline. **PR phase metrics (MANDATORY for both modes):** The PR phase is inline (no subagent), so there is no `` block. Emit metrics with tokens null and `gate_result: "skip"`: ``` sdd_emit_metrics(project_path, metrics={ run_id, feature_id, phase: "pr", agent: "orchestrator", model: null, started_at, completed_at, duration_ms, tokens_in: null, tokens_out: null, tool_calls_count: 0, gate_result: "skip", gate_attempts: 0, findings_count: 0, findings_severity: [], fix_loop_count: 0, delta_direction: null, feature_type, complexity }) ``` Record `started_at`/`t0` before the PR steps and `completed_at`/`duration_ms` after. ## Observability, signals, post-pipeline, and adaptive orchestration -> `docs/orchestrator/observability.md` — logging patterns, metrics schemas -> `docs/orchestrator/signals.md` — signal routing at phase boundaries -> `docs/orchestrator/post-pipeline.md` — retro, scoring, golden, cleanup -> `docs/orchestrator/adaptive.md` — adaptive routing, run close ## Flags - `--skip-worktree`: Work in project directory directly. - `--skip-pr`: Skip PR creation. Commits but does not push/open PR. - `--recover `: Resume incomplete run. - `--opus-review`: Use opus-coach for review (Full mode only). - `--headless`: Headless mode for external orchestrators. Implies `--skip-pr`. Do NOT pass both `--headless` and `--skip-pr`. In headless mode: no PR creation, no git push, no human interaction prompts, exit with code 0 on success or code 1 on failure. Requires `SDD_MODE=headless` environment variable for the MCP server. ## Run Recording (at pipeline completion) After PR phase (or implementation for Express), record the run: 1. `duration_ms = Date.now() - pipeline_start_time` 2. Collect `files_touched` from accumulated diff 3. Get `score` from `sdd_compute_score` 4. Call `sdd_record_run` with `{ project_path, feature, path: execution_mode, duration_ms, files_touched, score }` 5. Response includes `run_counter` for post-pipeline conditional logic. ## Post-Pipeline (conditional on run history) After pipeline completion, ALWAYS run these steps (regardless of outcome — success, failure, escalation): 1. **Validate metrics.jsonl**: Read `.sdd/runs/{feature_id}/metrics.jsonl` for the current `run_id`. Count phases with `tokens_in: null` → MUST be 0. Count phases with `tool_calls_count: 0` when the agent clearly used tools → MUST be 0. If any validation fails: ``` sdd_log_event(project_path, feature_id, event_type="phase_complete", phase="post_pipeline", agent_id="orchestrator", data={ warning: "Token instrumentation incomplete: {N} phases missing token data" }) ``` 2. Call `sdd_get_run_summary(project_path, feature_id, run_id)` — generates `summary.json`, returns RunSummary with `phase_metrics` and `threshold_alerts`. 3. Call `sdd_compute_score(project_path, feature_id, review_decision)` — computes quality + efficiency scores, returns `pipeline_score` and `golden_comparison`. 4. Call `sdd_record_run` (see Run Recording above). Then, based on `run_counter`: - **Runs 1-3**: Summary + score only. `Run {N} complete. Score: {X}. (Retro activates at run 4)` - **Runs 4-5**: Add retro (`sdd_run_retro`). - **Runs 6+**: Full post-pipeline (retro + anomaly detection + pattern analysis). Data collection (metrics, signals) happens on EVERY run from run 1. Only analysis output is conditional. ## Post-pipeline iterations For iteration tracking, see `docs/orchestrator/post-pipeline.md` § Post-pipeline iterations. $ARGUMENTS --- > Source: [rubenzarroca/sdd-autopilot](https://github.com/rubenzarroca/sdd-autopilot) — distributed by [TomeVault](https://tomevault.io).