• User runs

  plan

  command
• User wants to break a spec into tasks
• A unified

  docs/specs/

  artifact's Design & Rationale section needs decomposition
• User says "plan the implementation" or similar
• Auto-chained from

  ideate

  after the Design & Rationale section is written
• Run directly (no prior

  ideate

  ): at thin/standard depth, author the whole unified spec — light/standard Design & Rationale section plus Decomposition — in one pass
• Auto-chained from plan-review with

  --revise

  flag (gaps found)

1. Set

   planReview.revisionsExhausted = true

2. Output: "Plan revision failed after 3 attempts. Design may be incomplete."
3. Escalate: Suggest

   ideate --redesign

   to revisit design

MANDATORY: Before accepting any rationalization for skipping tests, planning, or TDD steps, consult

references/rationalization-refutation.md

. Every common excuse is catalogued with a counter-argument and the correct action.

check_test_adequacy

riskTier

boundaryTouching

1. Cover the new/changed behavior with scoped tests that pin its contract
2. Let the

   check_test_adequacy

   kill-probe prove the tests can actually fail (it reverts your source and asserts at least one test goes red)
3. Add real-collaborator integration coverage across the seam

check_tdd_compliance

exarchos_orchestrate({
  action: "check_test_adequacy",
  featureId: "<featureId>",
  taskId: "<taskId>",
  branch: "feature/<name>",
  riskTier: "high"
})

• passed: true

  — Reverting the task's source makes at least one new/changed test fail: the tests are not vacuous

• passed: false

  — A test still passes against the reverted source; strengthen it

## Design & Rationale

ideate

references/spec-template.md

• Problem Statement — Context (no tasks, but informs scope)
• Chosen Approach — Architectural decisions to implement
• Requirements (DR-N) — the provenance anchors every task must trace to
• Technical Design — Core implementation requirements
• Integration Points — Integration and glue code tasks
• Open Questions — Decisions to resolve or explicitly defer

DR-N

references/spec-tracing-guide.md

docs/specs/

designFile

planFile

## Design & Rationale

## Decomposition

exarchos_orchestrate({
  action: "generate_traceability",
  designFile: "docs/specs/<date>-<feature>.md",
  planFile: "docs/specs/<date>-<feature>.md",
  outputFile: "docs/specs/<date>-<feature>-traceability.md"
})

• passed: true

  — Matrix generated; review and fill in "Key Requirements" column

• passed: false

  — Parse error; the spec may lack expected

  ##

  /

  ###

  headers

references/task-template.md

• Each task: 2-5 minutes of focused work
• One test = one behavior
• Prefer many small tasks over few large ones

testingStrategy

references/testing-strategy-guide.md

propertyTests

benchmarks

1. Foundation first (types, interfaces, data structures)
2. Core behaviors second
3. Edge cases and error handling third
4. Integration and glue code last

## Decomposition

docs/specs/YYYY-MM-DD-<feature>.md

references/spec-template.md

## Decomposition

## Design & Rationale

The legacy two-file split (

references/plan-document-template.md

→

docs/plans/

) is retained only for in-flight workflows already on the old path; new features author the one

docs/specs/

artifact.

docs/specs/

designPath

planPath

exarchos_orchestrate({
  action: "check_plan_coverage",
  featureId: "<id>",
  designPath: "docs/specs/<date>-<feature>.md",
  planPath: "docs/specs/<date>-<feature>.md"
})

• passed: true — All requirements covered; proceed to 5a-ii
• passed: false — Gaps found; add tasks for uncovered requirements or defer with rationale
• error — Usage error or empty spec; check arguments

Implements:

exarchos_orchestrate({
  action: "check_provenance_chain",
  featureId: "<id>",
  designPath: "docs/specs/<date>-<feature>.md",
  planPath: "docs/specs/<date>-<feature>.md"
})

• passed: true — All DR-N requirements traced; proceed to 5b
• passed: false — Block: gaps or orphan references found. Add

  **Implements:** DR-N

  to tasks for each uncovered requirement before proceeding. Every DR-N requirement MUST trace to at least one task.
• error — No DR-N identifiers in design (exit 2); if design doesn't use DR-N identifiers, this check is skipped (exempt)

exarchos_orchestrate({
  action: "check_task_decomposition",
  featureId: "<id>",
  planPath: "docs/specs/<date>-<feature>.md"
})

• passed: true — All tasks well-decomposed; proceed to 5b
• passed: false — Findings recorded as D5 gate events for the ConvergenceView. Present findings to the user for awareness but do not block plan approval.
• error — Input error (missing file, no task headers); check arguments

exarchos_orchestrate({
  action: "spec_coverage_check",
  planFile: "docs/specs/<date>-<feature>.md",
  repoRoot: "."
})

• passed: true

  — All planned tests found and passing; plan verification complete

• passed: false

  — Missing test files or test failures; create missing tests or fix failures

references/spec-tracing-guide.md

• Design document read and understood
• Spec traceability table created (

  exarchos_orchestrate({ action: "generate_traceability" })

  )
• Scope declared (full or partial with rationale)
• Tasks decomposed to 2-5 min granularity
• Each task carries a

  riskTier

  (and

  boundaryTouching

  ) stamp; medium/high-tier tasks carry adequacy-judged tests (test-after), high-tier adds the integration suite
• Dependencies mapped
• Parallel groups identified
• Plan verification passed —

  exarchos_orchestrate({ action: "check_plan_coverage" })

  returns passed: true
• Provenance chain checked —

  exarchos_orchestrate({ action: "check_provenance_chain" })

  passed (blocking; gaps must be resolved before proceeding)
• Task decomposition checked —

  exarchos_orchestrate({ action: "check_task_decomposition" })

  run (advisory; findings presented but non-blocking)
• Spec coverage check passed —

  exarchos_orchestrate({ action: "spec_coverage_check" })

  passed: true
• Coverage thresholds met —

  exarchos_orchestrate({ action: "check_coverage_thresholds" })

  passed: true:

exarchos_orchestrate({
  action: "check_coverage_thresholds",
  coverageFile: "coverage/coverage-summary.json",
  lineThreshold: 80,
  branchThreshold: 70,
  functionThreshold: 100
})

• Unified spec saved to

  docs/specs/

  (Design & Rationale + Decomposition in one doc)
• State file updated with

  artifacts.plan

  = unified spec path and tasks

plan-review

overhaul-plan-review

designDepth

exarchos_orchestrate({ action: "prepare_review", scope: "plan", artifact: "docs/specs/<...>", designDepth: "<frozen>" })

• Refuted (gaps): set

  .planReview.gaps

  , auto-loop back to

  plan --revise

• Survives: present to user for approval (the single human checkpoint)
• On approval: set

  .planReview.approved = true

  , invoke

  delegate

exarchos_orchestrate({ action: "check_plan_coverage" })

plan --revise

delegate

• Complete each step fully before advancing — quality over speed
• Do not skip validation checks even when the change appears trivial
• Trace every design section to at least one task. Do not leave uncovered sections without explicit rationale.