# Style Docs

> Generate standardized project documentation using the 5-style system. Use when asked to create plans, specs, skills, RFCs, ADRs, or other project documentation. Ensures consistent, high-quality documentation across the codebase.

- Skill: `thrashr888-thrashr888-agent-kit/style-docs` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add thrashr888-thrashr888-agent-kit/style-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/thrashr888-thrashr888-agent-kit/style-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: thrashr888 (https://skillmd.com/u/thrashr888-thrashr888-agent-kit)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/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

| 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:**
```bash
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

| 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