Specification (Stage 2 Orchestrator)

Guide the user through Stage 2 — Specification for a specific phase. Sequences the atomic skills and tracks progress.

If no phase number provided: ask the user which phase to work on. List existing phases by scanning docs/plans/NN-plan-*.md. </on-init>

1. Plan: docs/plans/{NN}-plan-*.md — check for Status: APPROVED
2. Research: docs/research/{NN}-research-*.md — count docs, check for CONTRADICTED findings
3. Spec: docs/specs/{NN}-spec-*.md — check for Status: APPROVED
4. Coherence: check if coherence review passed (3 clean rounds)
5. Beads: bd list --status=open --json — check for epic matching the phase

Display:

Stage 2 — Specification (Phase {NN})
  {check} Plan        {path} ({status})
  {check} Research    {count} doc(s) in docs/research/{NN}-*
  {check} Spec        {path} ({status})
  {check} Coherence   {clean_rounds}/3 clean rounds
  {check} Beads       {epic_id} ({completed}/{total} complete)

Dispatch: Skill(skill="plan")

Wait for completion. Plan must be APPROVED before proceeding. </on-step>

Dispatch: Skill(skill="research")

Wait for completion. Read Smith's report and check for contradictions.

If contradictions found: Present each contradiction clearly with plan-vs-reality comparison.

Ask: "These contradictions affect the plan's assumptions. How do you want to proceed?"

1. Adjust the plan (recommended) — route back to /plan for corrections, then re-research
2. Proceed to spec with known issues — Ada will follow research reality over the plan
3. Cancel — stop and review manually

If user chooses "Adjust the plan":

• Inform: "Routing back to plan. Ada will update the plan to align with research findings."
• Reset the plan step — dispatch Skill(skill="plan") again
• After plan is re-APPROVED, re-dispatch Skill(skill="research") to validate the corrections
• Repeat this loop until either:
  • Research confirms zero contradictions, OR
  • User explicitly chooses to proceed with known issues
• This plan↔research loop ensures both documents are coherent before spec creation.</on-step>

Verify coherence: Read the research doc summary. If it lists CONTRADICTED findings, ask: "Research found contradictions. Were these resolved in the plan? (Check plan status)"

• If resolved → proceed
• If unresolved → route back to plan↔research loop</on-step-skip>

Dispatch: Skill(skill="spec")

Wait for completion. Spec must be APPROVED before proceeding. </on-step>

This gate ensures plan, research, and spec are fully aligned. No tasks are created until coherence is verified.

For each round, dispatch Ada to review coherence:

Agent(
    subagent_type="architect",
    prompt="COHERENCE REVIEW (Round {N}/3 minimum) for Phase {NN}. Read ALL three documents: Plan: {plan_path}. Research: {research_paths}. Spec: {spec_path}. Cross-check for: (1) Spec assumptions that contradict research findings, (2) Plan scope items missing from the spec, (3) Research risks not addressed in the spec design, (4) Spec design decisions that conflict with plan dependencies, (5) Acceptance criteria that reference outdated assumptions. Report format: COHERENCE REVIEW Round {N} — list each discrepancy found with document, section, and what conflicts. If no discrepancies: state COHERENT. Do NOT write files — this is a read-only review."
)

After each round:

1. Present Ada's coherence report to the user
2. If discrepancies found:
   • Ask user: "Fix these in the spec? Or adjust the plan/re-research?"
   • If spec fix → dispatch Skill(skill="spec") for Ada to correct, then re-run coherence
   • If plan fix → route back to plan↔research loop, then re-run spec + coherence
   • Reset round counter to 0 after any fix
3. If COHERENT:
   • Increment clean round counter
   • If < 3 clean rounds → run next round (each round may focus on different aspects)
   • If >= 3 clean rounds → coherence gate passed

Round focus guidance (suggest to Ada):

• Round 1: Structural coherence — scope, requirements coverage, missing sections
• Round 2: Technical coherence — API contracts, data models, dependency assumptions
• Round 3: Acceptance coherence — criteria traceability from PRD → plan → spec

Display progress:

Coherence Review (Phase {NN}):
  Round {N}: {COHERENT|DISCREPANCIES — count}
  Clean rounds: {count}/3 required

Prerequisite: Coherence review must have passed (3 clean rounds).

Dispatch: Skill(skill="tasks")

Wait for completion. </on-step>

Stage 2 — Specification (Phase {NN}): COMPLETE
  [done] Plan        {path} (APPROVED)
  [done] Research    {count} doc(s)
  [done] Spec        {path} (APPROVED)
  [done] Coherence   3/3 clean rounds
  [done] Beads       {epic_id} ({total} issues)