orchestrate

name	orchestrate
description	Orchestrate the full SDLC pipeline from a product brief
claude	{"argument-hint":"<product brief>","disable-model-invocation":true}
cursor	{"disable-model-invocation":true}

SDLC Pipeline

Product brief: $ARGUMENTS

You are the SDLC pipeline orchestrator. You hold all artifacts, coordinate agents, and drive the pipeline from brief to shipped code. Each phase feeds directly into the next with no manual intervention.

---

Setup

Derive a short kebab-case feature slug from the product brief (e.g. "url-shortener", "task-management-app").

Resolve the artifact root using the Bash tool:

REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
ARTIFACT_ROOT="${ORCHESTRATE_OUT_DIR:-$REPO_ROOT/.orchestrate}"

The default location is .orchestrate/ at the repo root. Users can override it by setting the ORCHESTRATE_OUT_DIR environment variable to an absolute path (useful when the repo's .orchestrate/ collides with something else, or when artifacts should live outside the repo).

Create the artifact folder for this feature:

{ARTIFACT_ROOT}/{feature-slug}/
{ARTIFACT_ROOT}/{feature-slug}/phases/
{ARTIFACT_ROOT}/{feature-slug}/walkthroughs/
{ARTIFACT_ROOT}/{feature-slug}/verification/
{ARTIFACT_ROOT}/{feature-slug}/revisions/

Use the Bash tool to create these directories. All agents will read from and write to this folder. Refer to the resolved per-feature path as {docs_folder} throughout (e.g. .orchestrate/url-shortener).

Initialize {docs_folder}/stack.json as an empty stub:

{
  "feature_slug": "<feature-slug>",
  "phases": []
}

The engineer appends commit entries to this file as it works; the orchestrator updates each phase's status, started_at, completed_at, and verification block as the per-phase loop progresses.

Optional: launch the walkthrough viewer

If the orchestrate-walkthrough desktop viewer is installed and on $PATH, launch it pointed at this run so the user can watch artifacts populate live as each phase completes. This is best-effort — if the binary isn't installed, just continue.

if command -v orchestrate-walkthrough >/dev/null 2>&1; then
  orchestrate-walkthrough "$REPO_ROOT" --run "{feature-slug}" >/dev/null 2>&1 &
  disown
fi

The viewer lives in app/ in this repo — see app/README.md for build instructions.

---

Phase 1: Requirements

Spin up the product-manager subagent. Pass:

• The product brief
• The docs folder path ({docs_folder})

The agent will write {docs_folder}/requirements.md.

---

Phase 2: Context Curation

Spin up the context-curator subagent. Pass:

• The docs folder path ({docs_folder})

The agent will read requirements.md, scan the target repo's docs and code, and write {docs_folder}/context.md — a focused, scope-aware briefing the downstream agents will read.

---

Phase 3: Architecture & Test Plan

Spin up the architect and qa-analyst subagents in parallel. Pass each:

• The docs folder path ({docs_folder})

Both will read requirements.md (and the architect also reads context.md). The architect writes {docs_folder}/architecture.md. The qa-analyst writes {docs_folder}/test-plan.md.

---

Phase 4: Planning

Spin up the task-planner subagent. Pass:

• The docs folder path ({docs_folder})

The agent will read all prior documents and write:

• {docs_folder}/phases/phase-N.md — one file per implementation phase
• {docs_folder}/task-index.md — ordered phase list with dependency summary

---

Phase 5: Plan Brief & Review Gate

This phase compiles the full pre-implementation planning bundle into a single HTML brief that the user reviews before any code is written. If the user requests changes, the architect, qa-analyst, task-planner, and plan-explainer all re-run with the steering input until the user approves.

Step 1: Generate the brief

Spin up the plan-explainer subagent. Pass:

• The docs folder path ({docs_folder})
• mode: initial (for v1) or mode: revision with revision: N and a steering input path (for v2+)

The agent writes {docs_folder}/plan.html (or overwrites it, on revisions).

Step 2: Review gate

The review gate is on by default. The user can disable it by setting ORCHESTRATE_REVIEW_GATE=0 in the environment before invoking the orchestrator; if it's disabled, skip to Phase 6.

Check the env var with the Bash tool:

echo "${ORCHESTRATE_REVIEW_GATE:-1}"

If the value is 0, log "review gate disabled — proceeding to implementation" and continue to Phase 6.

Otherwise, open the brief in the user's default browser. Use the Bash tool with a cross-platform shim — best-effort, do not block on failure:

PLAN="{docs_folder}/plan.html"
case "$(uname -s)" in
  Darwin)               open "$PLAN" >/dev/null 2>&1 || true ;;
  Linux)                xdg-open "$PLAN" >/dev/null 2>&1 & disown ;;
  CYGWIN*|MINGW*|MSYS*) start "" "$PLAN" >/dev/null 2>&1 || true ;;
esac

On macOS, if the file is already open in a tab, open reuses it. The Tauri walkthrough viewer launched at the start of the run (if installed) will also detect the new plan.html and surface it — see the app integration note below.

Then send a single short message to the user:

I've opened the implementation plan in your browser:

file://{absolute path to plan.html}

Reply ok (or any affirmative — "looks good", "proceed", etc.) to start implementation. Otherwise describe what you'd like changed, and the architect and task-planner will revise the plan. If you're reviewing a revised version, refresh the browser tab to see the new content.

Then wait for the user's next message before proceeding.

Step 3: Interpret the response

When the user replies:

• Affirmative (ok, looks good, approved, proceed, ship it, etc.) — proceed to Phase 6.
• Steering input (anything else that describes desired changes) — proceed to Step 4.

If the response is ambiguous (e.g. a question), answer the question and ask again, rather than guessing approval.

Step 4: Capture the steering input and revise

Determine the next revision number N:

ls "{docs_folder}/revisions/" 2>/dev/null | grep -oE 'plan-v[0-9]+\.html' | sed -E 's/plan-v([0-9]+)\.html/\1/' | sort -n | tail -1

If the directory is empty, the current plan is v1 and the next revision will be v2 — so N=2. Otherwise add 1 to the highest existing version.

Snapshot the current plan to history:

cp "{docs_folder}/plan.html" "{docs_folder}/revisions/plan-v{N-1}.html"

Write the user's steering input verbatim to {docs_folder}/revisions/v{N}-input.md using the Write tool. Include a short header so the file is self-describing:

# Steering input for revision v{N}

> Submitted: {ISO 8601 timestamp}
> Prior plan: revisions/plan-v{N-1}.html

{user's message verbatim}

Re-run the planning agents with the steering context:

1. Spin up the architect and qa-analyst subagents in parallel. Pass each:
   • The docs folder path ({docs_folder})
   • The steering input path (revisions/v{N}-input.md)
   • An instruction to incorporate the steering input as a hard requirement; both will overwrite architecture.md and test-plan.md in place.
2. After both complete, spin up the task-planner subagent. Pass:
   • The docs folder path ({docs_folder})
   • The steering input path
   • An instruction to review and update existing phase files and task-index.md to reflect the revised architecture and test plan. Phases that no longer make sense should be reshaped, not appended.
3. Spin up the plan-explainer subagent in revision mode. Pass:
   • The docs folder path ({docs_folder})
   • mode: revision
   • revision: N
   • The steering input path (revisions/v{N}-input.md)
   • The prior plan path (revisions/plan-v{N-1}.html)

The agent overwrites {docs_folder}/plan.html as v{N}, with the "What changed in v{N}" callout and version-aware §02 decision table.

Return to Step 2 with the new plan. The loop continues until the user approves.

---

Phase 6: Implementation + Per-Phase Verification + Walkthrough

Read {docs_folder}/task-index.md to get the ordered list of phases.

Execute phases one at a time in order. For each phase, run the steps below. Verification (qa + code review + security) happens inside this loop, per phase, with an in-place fix loop. The walkthrough is generated only after the phase passes verification.

Maximum fix iterations per phase: 3. If a phase still fails after 3 fix cycles, mark it failed in stack.json, surface findings to the user, and stop the pipeline.

Step 1: Initialize the phase entry in stack.json

Append a new phase entry to stack.json:

{
  "n": N,
  "title": "<phase title from task-index.md>",
  "status": "in_progress",
  "started_at": "<ISO 8601 timestamp>",
  "commits": []
}

Step 2: Implement

Spin up one engineer subagent in implementation mode. Pass:

• The path to the phase file: {docs_folder}/phases/phase-N.md
• The docs folder path ({docs_folder})

Wait for the engineer to respond.

• If the engineer reports blocked: mark the phase failed in stack.json, stop the pipeline, and surface the blocker to the user.
• If the engineer reports complete: proceed to Step 3. The engineer will have made one commit per work item and appended each to stack.json.

Step 3: Verify (per-phase)

Spin up the following agents in parallel, passing each:

• The docs folder path ({docs_folder})
• phase: N
• An explicit report_path:
  • qa-verifier → {docs_folder}/verification/phase-N/qa-report.md
  • code-reviewer → {docs_folder}/verification/phase-N/code-review-report.md
  • security-reviewer → {docs_folder}/verification/phase-N/security-report.md

Create {docs_folder}/verification/phase-N/ if it does not exist.

manual-tester does not run here — it runs once at the end of the pipeline (Phase 7) because partial features cannot be browser-tested in isolation.

Read each report and check the Result line.

• If all PASS: proceed to Step 5.
• If any FAIL and iterations remain (cap 3 per phase): proceed to Step 4.
• If any FAIL and no iterations remain: mark phase failed in stack.json, surface all findings, stop the pipeline.

Step 4: Fix in place

Spin up one engineer subagent in fix mode. Pass:

• The docs folder path ({docs_folder})
• The failed verification report paths from Step 3

The engineer will append fix-up commits (never amend) and update stack.json. When they report complete, return to Step 3.

Step 5: Generate the walkthroughs

Spin up walkthrough-author and walkthrough-explainer in parallel. Pass each:

• The docs folder path ({docs_folder})
• phase: N

walkthrough-author writes {docs_folder}/walkthroughs/phase-N.md — the commit-by-commit markdown narration.

walkthrough-explainer writes {docs_folder}/walkthroughs/phase-N.html — the per-phase HTML walkthrough with one rich page per atomic commit (intent header, scope check, per-commit diagram, risk badge, edge-case prompts, error-handling and test-quality counts, cumulative-context aside, decision buttons) plus a final cross-commit synthesis page. The two outputs are complementary: the markdown is the canonical narration, the HTML is the higher-fidelity review surface.

Wait for both to complete.

Step 6: Mark the phase validated

Update the phase entry in stack.json:

{
  "n": N,
  "status": "validated",
  "completed_at": "<ISO 8601 timestamp>",
  "verification": {
    "qa": "pass",
    "code_review": "pass",
    "security": "pass",
    "iterations": <number of fix cycles run>
  }
}

Continue to the next phase. After all phases complete, open the first phase's HTML walkthrough in the user's default browser so they have an entry point into the reviewer surface. Use the Bash tool with a cross-platform shim — best-effort, do not block on failure:

WALK="{docs_folder}/walkthroughs/phase-1.html"
case "$(uname -s)" in
  Darwin)               open "$WALK" >/dev/null 2>&1 || true ;;
  Linux)                xdg-open "$WALK" >/dev/null 2>&1 & disown ;;
  CYGWIN*|MINGW*|MSYS*) start "" "$WALK" >/dev/null 2>&1 || true ;;
esac

The Tauri walkthrough viewer (if installed) will also surface every phase's HTML walkthrough via its artifact watcher. Then proceed to Phase 7.

---

Phase 7: Final Integration Pass

By this point every phase has passed qa-verifier, code-reviewer, and security-reviewer in isolation. The remaining check is end-to-end behavior across the integrated feature, which only manual-tester can do.

Step 1: Manual test

Spin up manual-tester. Pass:

• The docs folder path ({docs_folder})

The agent writes {docs_folder}/verification/manual-test-report.md.

• If PASS: proceed to Phase 8.
• If FAIL: proceed to Step 2.

Step 2: Remediation phase (only if manual-tester fails)

When manual-tester finds issues that span phases (the kind of cross-phase integration bug that wouldn't show up in per-phase verification), create a remediation phase:

1. Spin up task-planner in fix mode. Pass the failed manual-tester report and the docs folder path. It will append a new fix phase to task-index.md.
2. Run the new phase through the full Phase 6 loop (initialize stack.json entry → engineer implements → per-phase verifiers → walkthrough-author).
3. Re-run manual-tester.

Cap remediation at 2 attempts. If manual-tester still fails after that, surface all findings and stop.

---

Phase 8: Summary & Handoff

Read all artifacts produced during the pipeline and present a single comprehensive summary directly in the conversation.

---

## [Feature Name] — Implementation Summary

### What Was Built A plain-language description of the feature as implemented, tied back to the original brief. Call out anything that was scoped down, deferred, or decided differently than the brief implied.

### Architecture Decisions The key technical decisions made by the architect that will have lasting impact on the codebase — new patterns introduced, dependencies added, schema changes, anything that future engineers will need to understand.

### Files Changed A grouped summary of all files created or modified across all phases. Group by area (e.g. data layer, API, UI, tests) rather than listing every file flat.

### Verification Results

• QA: [pass/fail summary, test count, coverage] — aggregated across verification/phase-*/qa-report.md
• Code review: [pass/fail summary, total findings] — aggregated across verification/phase-*/code-review-report.md
• Security: [pass/fail, any Medium findings worth knowing even if not blocking] — aggregated across verification/phase-*/security-report.md
• Manual: [pass/fail, any issues worth noting] — verification/manual-test-report.md

### Reviewing this work List each phase's walkthrough with a one-line summary, in order. Link both formats — the HTML walkthrough is the richer review surface (per-commit pages with diagrams, scope-check flags, risk badges, decision buttons, and a cross-commit synthesis page); the markdown walkthrough is the canonical narration:

• Phase 1 — Foundation: HTML · markdown — [one-line summary of what's in it]
• Phase 2 — …: HTML · markdown — [...]

Tell the user the walkthroughs are the entry point for review: each one narrates the phase's atomic commits with "what to look for" guidance, and trouble-spot stops flag commits where the engineer needed a fix-up. The single PR for this feature can be reviewed phase-by-phase using these walkthroughs alongside the diffs.

### Decisions & Assumptions Notable assumptions agents made, open questions that were deferred, or trade-offs that were resolved during implementation.

### Suggested Next Steps What the user might reasonably do from here — open a PR, run the app locally, review a specific file, address deferred open questions, etc.