Spec Driven Documentation

Spec-Driven Documentation

Automated documentation generation, auditing, and remediation integrated into the DevForgeAI SDLC workflow.

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 00 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 00 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 - devforgeai-validate CLI commands cannot be forged by LLM
3. Hook enforcement - Shell scripts in .claude/hooks/ run outside LLM control
4. Step registry + artifact verification - Phase checkpoint files track 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.

Workflow Modes

Parameter Extraction

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

Command Integration

Phase 00: Initialization [INLINE]

Generate Session ID:

SESSION_ID = "DOC-{YYYY-MM-DD}-{NNN}"
# Example: DOC-2026-03-18-001
# NNN increments per day based on existing state files

Determine Workflow Type:

IF $AUDIT_MODE is set (dryrun):
    WORKFLOW_TYPE = "audit"
    WORKFLOW_FLAG = "--workflow=doc-audit"
ELIF $AUDIT_FIX is true:
    WORKFLOW_TYPE = "fix"
    WORKFLOW_FLAG = "--workflow=doc-fix"
ELSE:
    WORKFLOW_TYPE = "generation"
    WORKFLOW_FLAG = "--workflow=doc-gen"

CLI Initialization:

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

Display Session Banner:

Display: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
Display: "  Documentation Workflow: {WORKFLOW_TYPE}"
Display: "  Session: {SESSION_ID}"
Display: "  Story: {STORY_ID or 'N/A'}"
Display: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

Phase Orchestration Loop

# Select phase list based on WORKFLOW_TYPE
IF WORKFLOW_TYPE == "generation":
    PHASE_LIST = ["01", "02", "G03", "G04", "G05", "G06", "G07", "G08", "G09", "G10"]
ELIF WORKFLOW_TYPE == "audit":
    PHASE_LIST = ["01", "02", "A03", "A04", "A05", "A06", "A07"]
ELIF WORKFLOW_TYPE == "fix":
    PHASE_LIST = ["01", "02", "F03", "F04", "F05", "F06", "F07", "F08"]

EXPECTED_COUNT = len(PHASE_LIST)
completed_count = 0

FOR phase_id in PHASE_LIST starting from CURRENT_PHASE:
    prev_id = previous phase in PHASE_LIST (or "00" for first)

    1. ENTRY GATE: devforgeai-validate phase-check ${SESSION_ID} --from={prev_id} --to={phase_id} ${WORKFLOW_FLAG}
       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-RECORD 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 ${SESSION_ID} --phase={phase_id} ${WORKFLOW_FLAG}

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

    completed_count += 1

Phase Tables

Generation Workflow (10 phases)

Audit Workflow (7 phases)

Fix Workflow (8 phases)

Required Subagents Per Phase

Deviation Protocol: Any skip requires explicit user consent via AskUserQuestion.

State Persistence

Location: devforgeai/workflows/${SESSION_ID}-${WORKFLOW_TYPE}-phase-state.json Checkpoints: devforgeai/workflows/${SESSION_ID}-checkpoint.json

Workflow Completion Validation

IF completed_count < EXPECTED_COUNT:
    HALT "WORKFLOW INCOMPLETE - {completed_count}/{EXPECTED_COUNT} phases"
IF completed_count == EXPECTED_COUNT:
    "All {EXPECTED_COUNT} phases completed - {WORKFLOW_TYPE} workflow validation passed"

Success Criteria

Generation Workflow

• Documentation files generated/updated
• All required sections present
• Documentation coverage >= 80% (quality gate)
• Mermaid diagrams render correctly (if architecture type)
• Framework constraints respected
• Story file updated (if story-based)
• Export formats created (if requested)

Audit Workflow

• All docs files inventoried
• 4 dimensions scored with evidence
• Findings classified and prioritized
• devforgeai/qa/audit/doc-audit.json written
• Summary report displayed

Fix Workflow

• Audit file loaded and findings filtered
• User consent obtained before execution
• Fixes applied (automated + interactive)
• Verification passed (orphans, links, facts)
• Fix session appended to doc-audit.json
• Summary report displayed

Reference Files Index

Phase Files (phases/ directory)

See Phase Tables above for complete listing.

Supporting References (references/ directory)

Template Files (assets/templates/ directory)

Integration Points

From:

• spec-driven-stories (story specifications)
• spec-driven-architecture (context files)
• spec-driven-dev (completed implementations)

To:

• spec-driven-release (documentation quality gate)
• Documentation files (README, guides, API docs)

Auto-invokes:

• documentation-writer subagent (prose generation, Phase G04)
• code-analyzer subagent (codebase analysis, Phase G03, brownfield only)

Created: 2026-03-18 Migrated from: spec-driven-documentation v1.1.0 Status: Production Ready Version: 1.0.0