Sdd Orchestrate Flow

---
name: sdd-orchestrate-flow
description: SDD flow for conducting a feature in session with read-only explorers, review delegated to a subagent, and HIL, or resuming its checkpoint in a new session; does not replace a standalone stage.
argument-hint: "[--prd feature-name]"
---

# 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.

1. **Prepare or resume.** Read [references/hil-state.md](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 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.
   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](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.

## 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.

| Available input | Responsible skill | Artifact/result | Session |
| --- | --- | --- | --- |
| New request without a checkpoint | `sdd-triage` | level decided at HIL 0, line in `tasks/triage-log.jsonl` | any |
| Request | `sdd-create-prd` | `prd.md` | any |
| Request with more than one primary outcome | `sdd-orchestrate-prds` | one `prd.md` per slice under a shared prefix | any |
| Requested refactoring | `sdd-plan-refactoring` | `prd.md`, `techspec.md` | any |
| `architectural-analysis` report | `sdd-plan-audit` | one folder per workstream with `prd.md`, `techspec.md`, `tasks.md`; destination map in `.audits/` | any |
| Approved PRD | `sdd-create-techspec` | `techspec.md` | any |
| PRD + TechSpec | `sdd-plan-tasks` | `tasks.md`, `task_*.md` | any |
| Approved plan | `sdd-orchestrate-tasks` following `sdd-execute-task` | implementation, handoffs, `context-snapshot.md` | any |
| Implementation | `sdd-review-code` | `codereview_[num]/codereview.md` | fresh-context delegated reviewer or non-authoring session |
| Review with authorized findings | `sdd-plan-corrections` | tasks in the report folder | any |
| Planned corrections | `sdd-execute-corrections` | corrections and handoffs; return to review | any; re-review delegated or in a new session |