thrashr888/thrashr888-agent-kit/style-docs

5-Style Documentation System

Use this skill when creating project documentation, planning features, or organizing technical decisions.

Agent-Ready Documentation

Document intent, constraints, and rationale that code alone cannot reveal. Agents can inspect implementation details, but they cannot infer requirements discussed in meetings, external contracts, business rules, or the reason a non-obvious decision was made. Put those facts in the narrowest durable artifact:

• requirements and plans define observable acceptance criteria and non-goals;
• specs record invariants, external constraints, and architectural boundaries;
• ADRs record a significant decision and its rationale; and
• skills record a repeatable implementation or verification workflow.

Do not write documentation that merely paraphrases code. Before publishing a document, ask whether a future engineer or agent could learn why this behavior exists and how to prove it still meets its constraints.

The 5 Documentation Styles

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 intent, constraints, and invariants
• States the rationale behind non-obvious boundaries

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

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