Spec Driven Dev

Spec-Driven Development

Implement user stories using strict TDD (Red-Green-Refactor) while enforcing all 6 context file constraints.

Context files are THE LAW: tech-stack.md, source-tree.md, dependencies.md, coding-standards.md, architecture-constraints.md, anti-patterns.md

If ambiguous or conflicts detected: HALT and use AskUserQuestion

Execution Model

This skill expands inline. After invocation, execute Phase State Initialization immediately. Do not wait passively, ask permission, or offer execution options.

Self-Check (if ANY box is true = VIOLATION):

• Stopping to ask about token budget
• Stopping to offer execution options
• Waiting passively for results
• Asking "should I execute this?"

IF any box checked: EXECUTION MODEL VIOLATION. Go directly to Phase State Initialization now.

Anti-Skip Enforcement Contract

This skill enforces 4 independent anti-skip layers. ALL FOUR must fail for a step to be skipped:

1. Fresh-context subagent execution - Subagents run in isolated context without accumulated bias
2. Binary CLI gates - Compiled Rust in src/commands/phase.rs, cannot be forged by LLM
3. Hook enforcement - Shell scripts in .claude/hooks/ run outside LLM control
4. Step registry + artifact verification - .claude/hooks/phase-steps-registry.json tracks every mandatory step

Execute-Verify-Gate Pattern: Every mandatory step in every phase file has three parts:

• EXECUTE: The exact action to perform
• VERIFY: How to confirm the action happened (Glob, Grep, exit code, Task result)
• RECORD: CLI command to record completion (devforgeai-validate phase-record)

Token Optimization Bias is PROHIBITED. Do not skip, compress, or shortcut any step. Every phase step exists because a previous failure proved it necessary. (Reference: RCA-001, RCA-002)

Parameter Extraction

Extract story ID from conversation context. See references/parameter-extraction.md for the extraction algorithm.

Command Integration

Phase State Initialization [MANDATORY FIRST]

devforgeai-validate phase-init ${STORY_ID} --project-root=.

Iteration counter: iteration_count = 1, max_iterations = 5. If resuming, read from phase-state.json.

Phase Orchestration Loop

FOR phase_num in range(CURRENT_PHASE, 11):
    phase_id = format(phase_num)

    1. ENTRY GATE: devforgeai-validate phase-check ${STORY_ID} --from={prev} --to={phase_id}
       IF exit != 0: HALT

    2. LOAD: Read(file_path="phases/{phase_files[phase_id]}")

    3. EXECUTE: Follow every step in the phase file (EXECUTE-VERIFY-GATE triplets)
       - Each step's EXECUTE instruction tells you exactly what to do
       - Each step's VERIFY instruction tells you how to confirm it happened
       - Each step's RECORD instruction tells you what CLI command to call

    4. RECORD: devforgeai-validate phase-record ${STORY_ID} --phase={phase_id} --subagent={name}

    5. EXIT GATE: devforgeai-validate phase-complete ${STORY_ID} --phase={phase_id} --checkpoint-passed
       IF exit != 0: HALT

Required Subagents Per Phase

Deviation Protocol: Any skip requires explicit user consent via AskUserQuestion. See references/workflow-deviation-protocol.md.

Test File Immutability (RCA-046, RCA-047)

After Phase 02, test files are IMMUTABLE until Phase 05. Mismatches = HALT immediately.

Back-to-Red Protocol: If test bugs found in Phase 03/04: mark incomplete, return to Phase 02, re-invoke test-automator, create new snapshot, resume Phase 03.

Remediation Mode

After Phase 01, if $REMEDIATION_MODE == true: Read references/qa-remediation-workflow.md, SKIP Phases 02-08, GOTO Phase 09.

Technical Debt Override Banner

If $DEBT_OVERRIDE_BANNER == true, display at start of each phase:

[DEBT OVERRIDE ACTIVE - Proceeding with elevated debt]

State Persistence

Location: devforgeai/workflows/${STORY_ID}-phase-state.json Session Memory: .claude/memory/sessions/${STORY_ID}-session.md References: references/memory-file-schema.md, references/memory-file-operations.md

Workflow Completion Validation

IF completed_count < 10: HALT "WORKFLOW INCOMPLETE - {completed_count}/10 phases"
IF completed_count == 10: "All 10 phases completed - Workflow validation passed"

IF iteration_count >= 4: Display "Approaching limit" IF iteration_count >= max_iterations: HALT "Maximum iterations reached"

Success Criteria

• All tests pass (100% pass rate)
• Coverage meets thresholds (95%/85%/80%)
• Light QA validation passed
• No context file violations
• All AC implemented
• DoD validation passed
• Changes committed
• Story status = "Dev Complete"

Treelint AST-Aware Search Integration

Phases 02-04 invoke Treelint-enabled subagents for semantic code analysis (40-80% token reduction). Automatic fallback to Grep when unavailable.

Reference: references/treelint-integration.md and .claude/agents/references/treelint-search-patterns.md

Reference Files

Phase Execution (phases/ directory)

Supporting References (references/ directory)