Orchestrate the SDD flow

Coordinate contracts, execution, and acceptance. The coordinator session runs each stage by following its skill, keeps state and human decisions, and writes every artifact and all code; subagents are read-only explorers, except the delegated reviewer. The review runs in a context that did not author the code it judges: the flow delegates it to a fresh-context subagent, reads the report that subagent writes, and moves on by itself; it recommends ending the session at that boundary only when no eligible subagent exists.

SDD artifacts are the feature's contract only while it is in progress, and may be versioned during that time. Once the feature is completed, the source of truth becomes the code, the tests, and durable documentation, and the commit skill offers to remove the artifacts from Git. Therefore, other features' artifacts in tasks/prd-*, completed or not yet started, are neither edited to follow the code nor used as evidence of current behavior: the effort is lost when they are removed, and a pending slice is reconciled with the code by its owning skill when its turn comes.

1. Prepare or resume. Read references/hil-state.md in full and detect tasks/prd-[slug]/checkpoint.json before starting work. With an explicit feature, consult only its folder; without one, select the only pending checkpoint or request a choice if there are several. Automatically resume the valid checkpoint for the selected feature, without requiring a special flag. Without a checkpoint, reconcile the selected feature's existing artifacts before creating state; for a broad request not yet sliced, fix the slugs in step 2 before opening state. For a new request, with no checkpoint or artifacts, first run .agents/skills/sdd-triage/SKILL.md, unless the user has already chosen the level: spot ends this flow and sdd-lean continues with the merged stops the triage recorded. Resolve the mode: an explicit --mode, otherwise the checkpoint's mode, otherwise monitored. In auto, read references/autonomous-mode.md in full: it decides the gates, the questions of every stage skill this flow runs, and the session pause, and it checks ContextBrake. In monitored, the flow runs as described here. Read .agents/skills/sdd-orchestrate-tasks/references/session-continuity.md in full; when context-snapshot.md exists in the feature folder, load it through the Load branch of .agents/skills/sdd-snapshot/SKILL.md after the checkpoint, which wins on conflict. Locate the skills in the table below in .agents/skills/ and read each stage's skill only when that stage starts. Before sending an explorer, read references/delegation.md in full; before delegating a review, read .agents/skills/sdd-review-code/references/delegated-review.md in full. On resume, load only the index, relevant decisions, matching snapshot entries, and sources needed for the next stage. Check the worktree, AGENTS.md, explorer availability, and existing sources. Record the Git base as a resolved commit and pre-existing changes; without Git, record scope limits. Require dependencies for the next phase; a missing skill blocks only that phase, without inventing equivalent execution. Stage skills with implicit invocation disabled are still followed here, by exact path, because the flow names them explicitly. Output: reconciled state, known authorization, and identified next stage. Without subagents, explore with direct searches; that changes cost, not the flow.
2. Product. Create or update the PRD with sdd-create-prd; reuse a valid existing artifact. New feature folders are tasks/prd-[NN]-[name]/, numbered in implementation order. For an explicitly requested refactoring, run sdd-plan-refactoring and use its PRD in the same gate, keeping the TechSpec as a draft until technical HIL. With more than one primary outcome in the request, run sdd-orchestrate-prds first: it approves the slicing with the user and writes one PRD per slice under a shared prefix; record the approved slicing as a decision in workflow.md. For an architectural-analysis report, run sdd-plan-audit: it approves the split into workstreams with the user and writes each workstream's PRD, TechSpec, and tasks through the owning skills. Record the approved workstreams in workflow.md, treat its contract approval as HIL 1, open one checkpoint per workstream, and present each one's plan at the HIL 2 of step 3 without redoing TechSpec or tasks, following the order of the destination map. Check request coverage and present the written PRD at HIL 1, with product decisions and pending items. When sliced, present the whole set at a single HIL 1, open one checkpoint per approved slice, and drive each slice as its own feature from step 3 onward, in dependency order. Reuse existing approval only if it matches current content and scope. Output: approved PRD and recorded decisions; when sliced, every slice has an approved PRD or an explicit deferral. A blocking pending item prevents dependent stages.
3. Design and plan. Write the TechSpec with sdd-create-techspec, check PRD coverage, and then plan tasks with sdd-plan-tasks. TokenHound is a .NET desktop application: omit E2E, keep relevant unit, integration, and manual acceptance, and require commands from AGENTS.md that also exclude E2E from aggregate suites. Preserve product behavior when choosing checks. There is no automated QA stage: manual acceptance is scripted in the TechSpec and presented at HIL 3. If the TechSpec recommends preparatory refactoring, present it at HIL 2 before the plan: minimal scope, the measures that motivated it, and what it makes easy in the feature. Approved, run sdd-plan-refactoring for that scope, drive it as a preceding feature — its own checkpoint and dependency order, as with the slices in step 2 — and only then replan the feature's tasks over the prepared terrain. Refused, record the risk in the TechSpec and proceed; the baseline still applies in either destination. A decided recommendation is not presented again. Present TechSpec + DAG + concrete tasks at HIL 2: architecture, boundaries, required environments, manual acceptance, and authorization for implementation and corrections within those contracts. Correct documents before requesting a decision; intermediate questions are only for indispensable information. Output: approved traceable executable plan, with preparatory refactoring decided exactly once; no code written before the required authorization.
4. Implement. Run sdd-orchestrate-tasks in this session: it implements each task itself, uses subagents only as read-only explorers, and owns the manifest and moves while active. Limit each run to one task and receive its handoff and state before the next. Save the checkpoint, then run the session pause: on the Move on destination, start the next task without asking; when it stops, add the written snapshot to sources.snapshot and next_action.read. After the last task, the next step is the review, which the session pause delegates under the independence rule. Handle deviations through exception HIL. For a feature with a visual interface, after the last task and before delegating the review, ask the human for the visual check of the TechSpec manual acceptance script: an adjustment within the approved contract becomes a task before the review; outside it, an Exception HIL. Output: all tasks approved with integrated evidence or identified blocks; done/ alone does not prove completion.
5. Review and correct. Run the global review with sdd-review-code, the Git base, and current artifacts in a context that authored none of the code under review: delegate it to a delegated reviewer and receive it under the protocol in delegated-review.md; without an eligible subagent, it runs in the session resumed after the pause. If the user continues in the authoring session anyway, record that limitation in workflow.md and in the report's limitations. Read from disk the literal status of the returned codereview.md, record it in review_status, and follow exactly one destination:
   • APPROVED closes the review cycle: proceed to step 6 with that report as acceptance evidence.
   • APPROVED WITH RESERVATIONS closes the automatic cycle and opens the reservations HIL: present each reserved item with impact and effort, and ask whether to correct the chosen items or finalize. Correcting opens a round limited to that scope; finalizing proceeds to step 6 with the items recorded as accepted open items. A reservation that leaves an essential requirement, security, or validation pending is a block and follows the REJECTED destination.
   • REJECTED opens a correction round: run sdd-plan-corrections and then sdd-execute-corrections for the exact review in this session, since the opinion was already issued outside it. Corrections within HIL 2 proceed automatically; new scope, a contract change, or an external action without authorization requires exception HIL on a concrete plan.
   • A missing or unrecognizable status is a report block: request the explicit opinion from the review before choosing a destination. Run corrections one task at a time and run the session pause after each reconciled task. Each round ends in at most one new review, run after the final correction task in a context that did not make the corrections: the coordinator delegates it to a new delegated reviewer; without an eligible subagent, the corrections session ends through the session pause and the resumed coordinator issues the re-review. Compare full finding identity (folder + ID), cause, and evidence. An incomplete original task finding requires reconciling its evidence and manifest by the DAG owner; completing only the correction task does not close the original obligation. Output: the latest review's literal status recorded and routed exactly once; APPROVED or decided reservations proceed to step 6 without a new review. After two rounds without proven reduction or change in blocks, stop the automatic cycle and present diagnosis and decision at exception HIL; no limit turns rejection into approval.
6. Acceptance. Check the complete request, PRD, TechSpec, manifest, corrections, latest review, and validations of the integrated state. Present paths, results, limitations, the manual acceptance script and its pending items, reservations accepted in step 5, and relevant ADR candidates at HIL 3. If the review recorded a suggested escalation, present the skill and the counted trigger as a user decision for after acceptance; a heavy audit does not run inside the cycle. Output: current human acceptance recorded and no blocking obligation open before marking completed. Publish a PR, commit, push, deploy, or promote an ADR only if requested or authorized; flow completion does not require them. A commit goes through the commit skill, which will offer to remove this now completed feature's artifacts from Git, moving its ADR candidates to docs/adr/ first; a candidate rejected at HIL 3 must be recorded in workflow.md so it is not moved.

Stages

Save a checkpoint before each HIL question, after recording its answer, between tasks, before delegating each review, and after receiving it. At these points run the session pause under the state protocol, combined with any pending gate; pausing does not approve a gate or complete the feature. On completion, mark the checkpoint completed and the snapshot closed to prevent automatic resumption of closed work.

Every stage runs in the coordinator session, except the delegated review; the last column of the table below says which context may run it.