Create high-quality technical documentation faster with a spec-first workflow for Claude Code.
Most documentation projects fail because teams jump straight into writing, then discover gaps in scope, voice, structure, and consistency late in review. This framework prevents that by making planning mandatory, generating from explicit specs, and enforcing quality gates before promotion.
In 5 minutes, plan a document, generate a draft, and run quality review using built-in slash commands.
- Define requirements before generation to reduce rewrites
- Standardize output across all document types
- Catch issues early with automated quality gates
- Scale work with specialized AI agents
1. PLAN → /doc-plan creates a specification from your topic
2. WRITE → /doc-write generates the document from the spec
3. REVIEW → /doc-review validates quality and consistency
4. ITERATE → Fix issues or regenerate until approved
5. PROMOTE → /doc-promote moves the document through workflow stages
The specification-first approach ensures quality by defining requirements before generation and validating at every step.
For a one-command shortcut through the full pipeline, use /doc-flow "Topic" --type api --auto-promote — it runs plan → write → review → promote in sequence with smart model selection and daily caching of spec analysis. New users can start with /doc-interactive for a guided walkthrough.
This preview shows the typical workflow: plan a specification, generate a draft, review it against quality gates, then promote it through the workflow.
- Claude Code CLI installed and configured
- A project directory for your documentation
Copy the framework files to your project:
# Copy the .claude configuration directory
cp -r .claude /path/to/your/project/
# Copy the specs directory for document specifications
cp -r specs /path/to/your/project/If you cloned this repository directly to evaluate it, install the dev dependencies before running tests:
npm install # required before npm test (installs markdownlint-cli)
npm test # runs the smoke suite (JSON, hooks, markdown lint)-
Plan your document:
/doc-plan "User Authentication API" --type api -
Generate the document:
/doc-write specs/docs/user-authentication-api-spec.md
-
Review the output:
/doc-review spec_driven_docs/rough_draft/api/user-authentication.md
-
Promote the document through the workflow:
/doc-promote spec_driven_docs/rough_draft/api/user-authentication.md --to pending_approval
Run /doc-status to see your documentation dashboard. If you see status output, the system is ready.
For a local clone-based end-to-end check, run npm run test:e2e. This test clones the repository into a temporary
directory, installs dependencies, runs the smoke suite, generates three sample documents, runs the hooks, and verifies
promotion into pending_approval/.
| Document | Purpose |
|---|---|
| User Guide | Comprehensive guide to all features |
| FAQ | Common questions about setup, workflow, and quality gates |
| Contributing | Contribution workflow, standards, and quality expectations |
| Document | Purpose |
|---|---|
| DIRECTIVES.md | Mandatory anti-shortcut directives for complete implementation |
| CLAUDE.md | Project guidance for Claude Code sessions |
| AGENTS.md | Repository guidelines and agent coordination |
| Concept | Description |
|---|---|
| Commands | 11 slash commands for the full workflow |
| Agents | 4 specialized AI agents with distinct roles |
| Templates | 6 document types: API docs, design docs, user manuals, ADRs, RFCs, OpenAPI |
| Quality system | 4 gates with A-F grading and consistency enforcement |
| Suites | Group docs for batch operations |
| Command | Purpose | Example |
|---|---|---|
/doc-flow |
Auto pipeline | /doc-flow "REST API" --type api --auto-promote |
/doc-interactive |
Guided creation | /doc-interactive |
/doc-plan |
Create specification | /doc-plan "REST API" --type api |
/doc-write |
Generate from spec | /doc-write specs/docs/api-spec.md |
/doc-review |
Validate quality | /doc-review spec_driven_docs/rough_draft/api/users.md |
/doc-sync |
Sync suite consistency | /doc-sync my-suite |
/doc-batch |
Batch operations | /doc-batch my-suite generate |
/doc-status |
View dashboard | /doc-status my-suite |
/doc-improve |
Learn patterns | /doc-improve |
/doc-promote |
Promote document | /doc-promote <path> --to pending_approval |
/doc-config |
Manage configuration | /doc-config get quality_profiles.api.min_score |
Single document:
/doc-plan "Feature X" --type manual
/doc-write specs/docs/feature-x-spec.md
/doc-review spec_driven_docs/rough_draft/guides/feature-x.md
/doc-promote spec_driven_docs/rough_draft/guides/feature-x.md --to pending_approvalSuite batch processing:
/doc-batch api-docs generate --parallel
/doc-batch api-docs review
/doc-sync api-docs --fix ┌──────────────┐
│ /doc-plan │
│(Orchestrator)│
└──────┬───────┘
│
▼
┌──────────────┐
│Specification │
│(specs/docs/) │
└──────┬───────┘
│
▼
┌──────────────┐
│ /doc-write │
│ (Writer) │
└──────┬───────┘
│
▼
┌──────────────┐
│ Document │
│(rough_draft/)│
└──────┬───────┘
│
▼
┌──────────┐ ┌──────────────┐ ┌────────────────┐
│/doc-sync │◄│/doc-review │►│ /doc-improve │
│(Librarian)│ │(Reviewer) │ │(Orchestrator) │
└──────────┘ └──────────────┘ └────────────────┘
The system uses specialized Claude agents to scale document processing:
| Agent | Model | Purpose |
|---|---|---|
| doc-orchestrator | Opus | Strategy & multi-document coordination |
| doc-writer | Sonnet | Generate docs from specifications |
| doc-reviewer | Sonnet | Quality & consistency validation |
| doc-librarian | Haiku | Cross-reference & consistency checks |
/doc-planspawns doc-orchestrator for requirement gathering/doc-writespawns doc-writer for content generation/doc-reviewspawns doc-reviewer for quality validation/doc-syncspawns doc-librarian for cross-reference checks/doc-batchcoordinates agents for parallel processing/doc-promotevalidates gates and moves documents:rough_draft/→pending_approval/→approved_final/
| Agent | Model | Purpose |
|---|---|---|
| workspace-cleanup | Haiku | Maintenance & file organization |
| prompt-enhance-agent | Sonnet | Clarify and structure prompts |
Utility agents handle development hygiene and prompt engineering tasks.
| Grade | Score | Status |
|---|---|---|
| A | 90-100 | Approved |
| B | 80-89 | Approved with notes |
| C | 70-79 | Iteration recommended |
| D | 60-69 | Iteration required |
| F | <60 | Blocked |
.
├── .claude/ # Commands, agents, hooks, templates, and quality rules
├── specs/docs/ # Input specifications
├── spec_driven_docs/ # Generated output by workflow stage
│ ├── rough_draft/
│ ├── pending_approval/
│ └── approved_final/
├── app_docs/ # End-user documentation
│ └── User-Guide/ # Framework user guide
├── prompt/ # Prompt engineering resources
└── README.md # This file
MIT. See LICENSE.