thrashr888/style-docs

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, installation
• CLAUDE.md: Agent instructions
• AGENTS.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 template
• spec-template.md - Evergreen spec template
• skill-template.md - Skill document template
• rfc-template.md - RFC template
• adr-template.md - ADR template
• bug-report-template.md - Bug report template
• feature-request-template.md - Feature request template
• pull-request-template.md - PR description template