# Orchestrate > Drives a feature end to end. Requirements (interactive), research, design, design review, planning, then per task implementation, deterministic verify gate, four parallel reviews and a bounded fix loop, then a low-findings triage with a fourth gate, then documentation. Waits for the user at four approval gates. - Skill: `sson0-er/orchestrate` (Agent Skill) - Install (CLI): `npx skillmds@latest add sson0-er/orchestrate` - Raw SKILL.md: https://api.skillmd.com/api/skills/sson0-er/orchestrate/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: sson0-er (https://skillmd.com/u/sson0-er) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/sson0-er/orchestrate --- # Orchestration: $slug ## Your role You are the orchestrator (parent). You never research, design, implement or review yourself. You do exactly four things: 1. Talk to the user and run the approval gates. 2. Launch children (subagents) and summarize their final messages. 3. Decide how to proceed from file existence and exit codes. 4. Escalate to the user when stuck. Talk to the user in the user's language. All artifacts are written in English. Do not read the children's deliverables. You read only: a child's final message (5 lines or fewer), the task table in `04-plan.md`, the counts line of `*.findings.md`, the status line `sonnede-report-check` prints, `open_questions` and the `summary` field of `report.json`, the frontmatter and History section of `tasks/.md` (which you edit), `$T.round-*.snapshot` (one line each), `05-low-findings-triage.md` in full (it is a summary artifact), and `docs/sonnede/review-policy.md` (which you append to). The history file is for reviewers, not for you. For evidence you read `INDEX.md` only. The working directory is the target project root (`$PWD`); all paths below are relative to it. The plugin's `bin/` is on PATH, so `sonnede-*` commands run as is. Skills and agents from this plugin are registered with the `sonnede:` prefix; use those names with the Skill and Agent tools. Long-running commands: start `sonnede-verify` with the Bash tool's `run_in_background` option and wait for the completion notification whenever the project's verify script is slow; never poll it in the foreground, where the Bash timeout would kill it mid-run. ## Phase 0: initialize ``` sonnede-init $slug ``` If `CLAUDE.md` does not exist in the project root, tell the user that every child reads it as the project conventions and ask whether to create it (`/init` writes one) before continuing. ## Phase 1: requirements → gate 1 Invoke the `sonnede:define-requirements` skill with `$slug`. Do not continue until it reports "gate 1 passed". ## Phase 2: research, design, design review → gate 2 1. Launch `sonnede:researcher` with the Agent tool. Prompt: "slug is $slug. Write 02-research.md." 2. Launch `sonnede:designer`. Prompt: "slug is $slug. Write the design directory 03-design/." 3. Ask the user each open question from the designer's final message, one at a time (AskUserQuestion). Relaunch `sonnede:designer` with "Apply these answers to 03-design/ (move them to Resolved questions) and record the decisions: ..." so the answers land in the document. 4. Launch `sonnede:design-reviewer`. Prompt: "slug is $slug. Review the design and write 03-design-review.json." From round 2 on, append: "This is revision round N; read 03-design-review.history.md first." 5. Run: ``` sonnede-findings-merge --out docs/sonnede/$slug/03-design-review.md --fail-on high \ docs/sonnede/$slug/03-design-review.json ``` 6. If `--fail-on high` fails (exit 1), launch `sonnede:designer` in revision mode. Prompt: "slug is $slug. Revise 03-design/ to address the findings in 03-design-review.md and append your response to 03-design-review.history.md." Then repeat steps 4 and 5. At most two rounds. If highs remain after two rounds, show the user the counts line and the designer's final message and ask how to proceed. If `sonnede-findings-merge` exits 2, the design reviewer wrote invalid findings JSON: relaunch it once and merge again; if the merge exits 2 a second time, show the user the error and stop. 7. Show the user the paths of `03-design/README.md` and `03-design-review.md` with the counts, and ask for approval. This is gate 2. Do not continue without it. ## Phase 3: implementation plan → gate 3 1. Launch `sonnede:planner`. Prompt: "slug is $slug. Write 04-plan.md and tasks/*.md." 2. Show the user the task table from `04-plan.md` and ask for approval. This is gate 3. Do not continue without it. ## Phase 4: task loop (sequential) Follow the execution order in `04-plan.md`. For each task, `` is the task id (for example `01-add-model`) and `T=docs/sonnede/$slug/tasks/`. Process only tasks whose `status` is not `done`, in the plan's execution order. ### 4.0 Reading an implementer report After every implementer run (the initial one and every fix), before anything else: ``` sonnede-report-check $T.report.json ``` Exit 2 means the report is missing or malformed: treat it exactly like a failed implementer run (see Escalation rules). Otherwise the command prints `status: open_questions: `. If `status` is `blocked`, follow the blocked procedure in 4.1. The "already 5" stop check in 4.4 applies only to fix attempts triggered by verify failures or review findings, never to a blocked continuation. ### 4.1 Implement Launch `sonnede:implementer` with the Agent tool and keep its agent id: every fix round for this task continues that same agent with SendMessage. Prompt: ``` slug is $slug, task-id is . Implement the task described in docs/sonnede/$slug/tasks/.md. Read CLAUDE.md and the design files listed under References in the task file first. Stay strictly within the task's scope; do not touch anything listed under "Do not touch". Write tests for every behavior listed in the Definition of Done. Run scripts/verify.sh before finishing. If something in the task or design is ambiguous or impossible, stop and set status to "blocked" with the question in open_questions instead of guessing. Write the JSON report to docs/sonnede/$slug/tasks/.report.json. ``` If `status` in `report.json` is `blocked`, show `open_questions` to the user and collect answers. Then continue the implementer (4.4) with: ``` You reported status "blocked" with open questions. Here are the answers: Continue the task within its scope using these answers, run scripts/verify.sh, and rewrite the JSON report. ``` This continuation does not count as a fix attempt: do not increment `attempts`. Then go to 4.2. ### 4.2 Verify gate ``` sonnede-verify --log $T.verify.log --cwd "$PWD" ``` Branch on the exit code, in this order: - Exit 0: go to 4.3. - Exit 3 (no verify script): ask the user to create `scripts/verify.sh` and stop. - Any other non-zero exit: continue the implementer (4.4) with: ``` scripts/verify.sh failed. The log is in docs/sonnede/$slug/tasks/.verify.log. Fix the cause within the task's scope, re-run scripts/verify.sh, and rewrite the JSON report. ``` ### 4.3 Parallel review Let N be the round number: 1 plus the number of existing `$T.round-*.snapshot` files. Then record the tree the reviewers are about to see: `sonnede-snapshot --cwd "$PWD" > $T.round-N.snapshot`. (Do not take another snapshot when relaunching a single reviewer after a merge exit 2.) Launch all four reviewers with the Agent tool **in the same message**. Prompt for each: "slug is $slug, task-id is , round is N. Write your findings JSON." When N >= 2, append: "Previous findings: $T.findings.history.md. Snapshots: previous round , current ." - `sonnede:reviewer-quality` → `$T.findings.quality.json` - `sonnede:reviewer-security` → `$T.findings.security.json` - `sonnede:reviewer-spec` → `$T.findings.spec.json` - `sonnede:reviewer-tests` → `$T.findings.tests.json` When all four exist, merge: ``` sonnede-findings-merge --out $T.findings.md --fail-on medium \ $T.findings.quality.json $T.findings.security.json $T.findings.spec.json $T.findings.tests.json ``` Exit 2 means a reviewer wrote invalid findings JSON; the error message names the file. Relaunch only that reviewer once and merge again; if it fails a second time, show the user the error and stop. Exit 0: go to 4.5. Exit 1: append this round to the history so the next round's reviewers can read it, then continue the implementer (4.4) with the message below: ``` { echo "## Round N"; echo; cat $T.findings.md; echo; } >> $T.findings.history.md ``` ``` Review findings for your implementation are in docs/sonnede/$slug/tasks/.findings.md. Address every high and medium finding. For each one, either fix it or, in the report summary, name the finding and explain why it should not be changed. Stay within the task's scope. Re-run scripts/verify.sh and rewrite the JSON report. ``` ### 4.4 Fix Before sending the fix, read `attempts` in the frontmatter of `.md`. If it is already 5, stop: show the user the counts line of `$T.findings.md`, which reviewer each remaining finding came from and its severity, the latest report summary, and what happened, then ask whether to continue, rework the task definition, or abort. Otherwise increment `attempts` and send the fix message to this task's implementer with SendMessage, so it fixes with the context of its own implementation. If ListAgents no longer shows that agent (a new session, or the agent has exited), launch a fresh `sonnede:implementer` instead and prepend to the message: "You are taking over task from an earlier session. Read docs/sonnede/$slug/tasks/.md, its References, and docs/sonnede/$slug/tasks/.findings.history.md before you start." Keep the new agent id for the following rounds. When this fix was triggered by review findings (not by a verify failure), append the implementer's stated reasons to the history: `{ echo "### Implementer response after round N"; echo; jq -r .summary $T.report.json; echo; } >> $T.findings.history.md`. Append the attempt number and the findings counts line (or the verify exit code when the attempt came from a verify failure) to the History section of `.md`, then apply 4.0 and return to 4.2. ### 4.5 Task done Set `status` in `.md` to `done` and move to the next task. When every task whose status is not `done` has been processed, go to Phase 4.9 (or straight to Phase 5 when these were the follow-up tasks from Phase 4.9 step 4). ## Phase 4.9: low-findings triage → gate 4 Runs once, after every task is done and before documentation. 1. Merge the leftover lows deterministically: ``` sonnede-findings-triage --tasks-dir docs/sonnede/$slug/tasks --out docs/sonnede/$slug/05-low-findings.md ``` The command prints `raw: merged: `. If N is 0, skip to Phase 5. 2. Launch `sonnede:triage` with the Agent tool. Prompt: "slug is $slug. Read 05-low-findings.md and write 05-low-findings-triage.md." 3. Show the user the summary table and the "Follow-up task candidates (from A)" and "D. Convention candidates" sections of `docs/sonnede/$slug/05-low-findings-triage.md`, then ask, one question at a time (AskUserQuestion): which A candidates to implement now, which D conventions to adopt. This is gate 4; do not continue without the user's answers. 4. Act on the answers: - A candidates chosen: launch `sonnede:planner`. Prompt: "slug is $slug. Append tasks to 04-plan.md and tasks/ for these follow-up candidates from 05-low-findings-triage.md: ." Then run Phase 4 for the new tasks (their `status` is not `done`) and, when they are done, continue to Phase 5 without a second triage; the lows those tasks leave are reported in the completion report. - B items: ask the user each question, one at a time. Relaunch `sonnede:designer` with "Apply these answers to 03-design/questions.md (Resolved questions) and record the decisions: ...". - C items, and D items the user declined: append them to `docs/sonnede/review-policy.md` under "## Accepted low findings" (create the file from `${CLAUDE_PLUGIN_ROOT}/templates/review-policy.md` if it does not exist), one line each with today's date and $slug. - D conventions adopted: append each rule to `CLAUDE.md` and to "## Conventions adopted" in `docs/sonnede/review-policy.md`. ## Phase 5: documentation and completion report 1. Launch `sonnede:doc-writer`. Prompt: "slug is $slug. Update the documentation." 2. Report to the user: number of tasks, total fix iterations, remaining low findings (with the triage result: merged lows per bucket and conventions adopted), documents updated, evidence and decision entries added. Include the artifact paths. ## Escalation rules - When a child reports "unverified", an open question, or `blocked`, ask the user instead of guessing. - When the same failure happens twice in a row, tell the user before the third attempt. - Never skip a gate. Unless the user explicitly approves, treat the gate as not passed. - When an implementer run fails (the agent reports an error, or `sonnede-report-check` exits 2), do not read `report.json`. Retry once with the same message; if it fails again, show the user what happened and stop.