nt8-sdk/docs/02-runbooks/spec_to_build_workflow.md

Spec-to-Build Workflow

Purpose

Convert an approved spec into implementation-ready work with explicit tool handoffs and verifiable artifacts.

Roles

• Planner: decomposes spec into implementable tasks.
• Implementer: edits code within scope.
• Verifier: runs required build and tests.

Tool Handoffs and Artifact Passing

1. Spec Intake (Planner)
   • Tool: Archon task/project view.
   • Input artifact: approved spec text.
   • Output artifact: Task Brief containing objective, scope, constraints, acceptance criteria.
2. Task Breakdown (Planner)
   • Tool: Archon task board.
   • Input artifact: Task Brief.
   • Output artifact: ordered subtasks with file scope and done criteria.
3. Implementation (Implementer)
   • Tool: repository editor + scoped files.
   • Input artifact: ordered subtasks.
   • Output artifact: minimal code/doc diffs limited to allowed files.
4. Build Verification (Verifier)
   • Tool: ./verify-build.bat.
   • Input artifact: working tree changes.
   • Output artifact: pass/fail result with error details if failed.
5. Focused Tests (Verifier)
   • Tool: dotnet test with area filter.
   • Input artifact: verified build output.
   • Output artifact: test evidence (command + pass/fail + failing test IDs).
6. Task State Update (Planner/Implementer)
   • Tool: Archon task board.
   • Input artifact: verification evidence.
   • Output artifact: task moved doing -> review with implementation notes and evidence links.

Required Artifact Bundle for Review

• Task Brief (objective/scope/constraints/acceptance criteria).
• Subtask list with scoped files.
• Diff summary (files changed + why).
• Verification evidence:
  • ./verify-build.bat result.
  • Relevant dotnet test result.
• Known limitations or follow-up items.

Exit Criteria

• Acceptance criteria are satisfied.
• Evidence bundle is complete.
• Task status is review.