| name | spec-driven-documentation |
| description | Automated documentation generation, auditing, and remediation with structural anti-skip enforcement. Supports 3 workflows: Generation (greenfield/brownfield), Audit (4-dimension DevEx scoring), and Fix (automated/interactive remediation). Uses Execute-Verify-Gate pattern at every step. Designed to prevent token optimization bias through lean orchestration, fresh-context subagent delegation, per-phase reference loading, and binary CLI gate enforcement. Use when generating project documentation, updating docs after story completion, or analyzing documentation coverage.
|
| allowed-tools | ["Read","Write","Edit","Glob","Grep","AskUserQuestion","Task","Bash(devforgeai-validate:*)","Bash(git:*)","Bash(pandoc:*)","Bash(wkhtmltopdf:*)","Bash(mkdir:*)","Skill"] |
| model | claude-opus-4-7 |
| effort | High |
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):
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:
- Fresh-context subagent execution - Subagents run in isolated context without accumulated bias
- Binary CLI gates -
devforgeai-validate CLI commands cannot be forged by LLM
- Hook enforcement - Shell scripts in
.claude/hooks/ run outside LLM control
- 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
| Mode | Trigger | Phase Sequence | Phase Count |
|---|
| Generation | Story ID provided OR --mode=greenfield/brownfield | 01, 02, G03-G10 | 10 |
| Audit | --audit=dryrun | 01, 02, A03-A07 | 7 |
| Fix | --audit-fix | 01, 02, F03-F08 | 8 |
Parameter Extraction
Extract parameters from conversation context. See references/parameter-extraction.md for the extraction algorithm.
Command Integration
| Context Marker | Set By | Description |
|---|
$STORY_ID | /document | Story identifier (STORY-NNN) or empty |
$DOC_TYPE | /document | readme, api, architecture, roadmap, all |
$MODE | /document | greenfield, brownfield |
$EXPORT_FORMAT | /document | markdown, html, pdf |
$AUDIT_MODE | /document | dryrun or null |
$AUDIT_FIX | /document | true or false |
$FINDING_FILTER | /document | F-NNN or all |
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=.
| Exit Code | Meaning | Action |
|---|
| 0 | New workflow | State file created. Set CURRENT_PHASE = "01". |
| 1 | Existing workflow | Resume. Run devforgeai-validate phase-status ${SESSION_ID} to get CURRENT_PHASE. |
| 2 | Invalid session ID | HALT. Must match DOC-YYYY-MM-DD-NNN pattern. |
| 127 | CLI not installed | Continue without enforcement (backward compatibility). |
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)
| Phase | Name | File |
|---|
| 01 | Preflight & Mode Detection | phases/phase-01-preflight.md |
| 02 | Workflow Dispatch | phases/phase-02-dispatch.md |
| G03 | Discovery & Analysis | phases/phase-G03-discovery.md |
| G04 | Content Generation | phases/phase-G04-content-generation.md |
| G05 | Template Application | phases/phase-G05-template-application.md |
| G06 | Section Integration | phases/phase-G06-section-integration.md |
| G07 | Post-Generation Integration | phases/phase-G07-post-generation.md |
| G08 | Validation & Quality Check | phases/phase-G08-validation.md |
| G09 | Export & Finalization | phases/phase-G09-export.md |
| G10 | Completion Summary | phases/phase-G10-completion.md |
Audit Workflow (7 phases)
| Phase | Name | File |
|---|
| 01 | Preflight & Mode Detection | phases/phase-01-preflight.md |
| 02 | Workflow Dispatch | phases/phase-02-dispatch.md |
| A03 | Audit Discovery | phases/phase-A03-audit-discovery.md |
| A04 | Audit Analysis | phases/phase-A04-audit-analysis.md |
| A05 | Audit Prioritization | phases/phase-A05-audit-prioritization.md |
| A06 | Audit Output | phases/phase-A06-audit-output.md |
| A07 | Audit Display | phases/phase-A07-audit-display.md |
Fix Workflow (8 phases)
| Phase | Name | File |
|---|
| 01 | Preflight & Mode Detection | phases/phase-01-preflight.md |
| 02 | Workflow Dispatch | phases/phase-02-dispatch.md |
| F03 | Load Findings | phases/phase-F03-load-findings.md |
| F04 | Classify Findings | phases/phase-F04-classify.md |
| F05 | Preview Changes | phases/phase-F05-preview.md |
| F06 | Execute Fixes | phases/phase-F06-execute.md |
| F07 | Verify Fixes | phases/phase-F07-verify.md |
| F08 | Fix Report | phases/phase-F08-report.md |
Required Subagents Per Phase
| Phase | Required Subagents | Enforcement |
|---|
| G03 | code-analyzer | CONDITIONAL (brownfield only) |
| G04 | documentation-writer | BLOCKING |
| All others | (none) | N/A |
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)
| File | Purpose | Loaded By |
|---|
| parameter-extraction.md | Parameter extraction algorithm | Phase 01 |
| documentation-standards.md | Style guide, formatting, conventions | Phase G04, G08 |
| greenfield-workflow.md | Story extraction, content generation | Phase G03 |
| brownfield-analysis.md | Codebase scanning, gap identification | Phase G03 |
| diagram-generation-guide.md | Mermaid syntax, validation | Phase G04 |
| template-customization.md | Variable substitution, custom templates | Phase G05 |
| post-generation-workflow.md | Module name, section insertion, README/CHANGELOG | Phase G06, G07 |
| anti-aspirational-guidelines.md | Prohibited language, content quality | Phase G04, G08 |
| document-help.md | Quick reference for /document command | On-demand |
| audit-workflow.md | Full 4-dimension scoring rubric | Phase A03, A04 |
| audit-fix-catalog.md | Fix actions per finding type | Phase A05, F03, F04, F06 |
Template Files (assets/templates/ directory)
| File | Doc Type |
|---|
| readme-template.md | README |
| developer-guide-template.md | Developer Guide |
| api-docs-template.md | API Reference |
| troubleshooting-template.md | Troubleshooting |
| contributing-template.md | Contributing |
| changelog-template.md | Changelog |
| architecture-template.md | Architecture |
| roadmap-template.md | Roadmap |
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
