5-Style Documentation System
Use this skill when creating project documentation, planning features, or organizing technical decisions.
The 5 Documentation Styles
| Style | Purpose | Location | Update Trigger |
|---|---|---|---|
| 1. Plan Mode | Deep exploration before coding | plans/ | Per feature |
| 2. Issues | Track work across sessions | .beads/ or GH | Throughout feature |
| 3. Evergreen Specs | System truth ("how it works") | specs/ | Architecture changes |
| 4. Skills | Agent guides ("how to implement") | .claude/skills/ | Pattern changes |
| 5. User Docs | Human communication | README, CLAUDE.md | Major features |
When to Use Each Style
Style 1: Plan Mode (plans/)
Purpose: Explore and design before coding
When to use:
- Starting a non-trivial feature
- Making architectural decisions
- Complex refactoring
File naming: plans/YYYY-MM-DD-feature-name.md
Template: See references/plan-template.md
Style 2: Issues (.beads/ or GitHub)
Purpose: Track work items and dependencies
When to use:
- Work spans multiple sessions
- Feature has dependencies
- Need to track blockers
Commands:
bd create --title="..." --type=task|bug|feature --priority=2
bd update <id> --status=in_progress
bd close <id>
Style 3: Specs (specs/)
Purpose: Document architectural truth - WHAT the system does
When to use:
- Architecture changes
- New subsystems added
- Core patterns established
Characteristics:
- Declarative, not prescriptive
- Evergreen (rarely becomes stale)
- Describes constraints and invariants
Template: See references/spec-template.md
Style 4: Skills (.claude/skills/)
Purpose: Guide agents on HOW to implement
When to use:
- New implementation patterns
- Workflow documentation
- Agent guidance needed
Characteristics:
- Prescriptive (step-by-step)
- Code examples
- Tool allowlists
Template: See references/skill-template.md
Style 5: User Docs (README, CLAUDE.md)
Purpose: Human-facing communication
When to use:
- Public-facing changes
- Getting started guides
- API documentation
Files:
README.md: Project overview, installationCLAUDE.md: Agent instructionsAGENTS.md: Compiled agent instructions
Decision Framework
| Situation | Action |
|---|---|
| Starting new feature | Enter plan mode → write to plans/ |
| Feature spans sessions | Create beads issue |
| New architectural pattern | Update spec in specs/ |
| New implementation pattern | Update skill in .claude/skills/ |
| Public-facing change | Update README.md |
| Agent guidance needed | Update CLAUDE.md |
Additional Templates
For specific use cases:
- RFC (
references/rfc-template.md): Formal proposals needing team input - ADR (
references/adr-template.md): Architecture decision records - Bug Report (
references/bug-report-template.md): Bug documentation - Feature Request (
references/feature-request-template.md): Feature proposals - Pull Request (
references/pull-request-template.md): PR descriptions
Anti-Patterns
DON'T:
- Write RFC-style docs that get stale ("We plan to add X")
- Document temporary decisions in specs (use issues)
- Put implementation details in specs (use skills)
- Put architectural constraints in skills (use specs)
DO:
- Keep specs declarative and evergreen
- Keep skills prescriptive and code-focused
- Track multi-session work in issues
- Update docs when patterns change
Resources
All templates available in references/:
plan-template.md- Plan mode templatespec-template.md- Evergreen spec templateskill-template.md- Skill document templaterfc-template.md- RFC templateadr-template.md- ADR templatebug-report-template.md- Bug report templatefeature-request-template.md- Feature request templatepull-request-template.md- PR description template