sdd-pilot: Instructions file for Codex

SDD Pilot — Agent Context

Apply the Spec-Driven Development rules below during feature delivery. Enforce the lifecycle order, phase gates, conventions, and execution policy. If any rule here conflicts with project-instructions.md, follow project-instructions.md.

Lifecycle

Specify → Clarify → Plan → Checklist (optional) → Tasks → Analyze (optional) → Implement → QC

Treat this order as strict. If a required artifact for the next phase is missing, stop and return the work to the phase that owns it.

Runtime Preflight

Every public /sddp-* command must run this preflight exactly once before reading or writing any SDD Pilot artifact, delegating a phase, or running another SDD Pilot script. Nested phases inherit the successful in-turn result and must not run it again:

if ! command -v node >/dev/null 2>&1; then
  printf '%s\n' 'SDD Pilot requires Node.js 22 or newer available as node. Detected: not found. Install a supported Node.js LTS release: https://github.com/attilaszasz/sdd-pilot#prerequisites. No SDD Pilot artifact was modified.'
  exit 1
fi
node scripts/runtime-preflight.mjs

On a non-zero result, halt without reading or modifying SDD Pilot artifacts. Do not install Node or use an editor-bundled runtime.

Phase Gates

Each phase boundary runs a mandatory structural validator before the next phase may start. A FAIL blocks the next phase: in autopilot the pipeline halts; interactively the user may override with "Proceed anyway" (the bypass is recorded in the conversation only — no persistent marker is written).

• spec.md must exist before Clarify or Plan.
• Spec → Plan gate: /sddp-plan delegates the Spec Validator (_spec-validator.md) — allows 0–3 unresolved [NEEDS CLARIFICATION: ...] markers and fails at 4+, independently fails any unresolved CRITICAL/HIGH stress-test finding, and enforces concrete acceptance criteria for all P1 stories and frontmatter completeness. FAIL blocks Plan.
• plan.md must exist before Tasks.
• Plan → Tasks gate: /sddp-tasks delegates the Plan Validator (_plan-validator.md) — enforces 100% P1 requirement coverage in the Requirement Coverage Map, no orphaned Architecture Decisions, and all declared dependencies installable. FAIL blocks Tasks.
• tasks.md must exist before Implement.
• Tasks → Implement gate: /sddp-implement (via references/gates.md) delegates the Tasks Validator (_tasks-validator.md) — enforces complete task parsing, ≤40 tasks, every P1 requirement has ≥1 task, no circular after: chains, tasks.md ≤ 6 KB, valid phase structure, and semantic reconciliation of checked task provenance against current spec/plan requirements, coverage, imports/exports, and dependencies. FAIL blocks Implement.
• If checklists/ exists, all checklist items must be complete before Implement unless the user explicitly overrides.
• .completed must exist before QC.
• Do not treat a feature as release-ready until .qc-passed exists and its report/evidence SHA-256 digests, Git baseline, and repository-state digest validate.
• Any project-instructions.md violation is CRITICAL severity.