common-design-docs-k

What this skill does

> **Knowledge skill** — Design documentation system: doc types, folder structure, frontmatter conventions, agent roles.

# Agent Documentation System

Agent docs are design documentation that agents create and maintain — plans, living docs, architecture maps, and principles. They live in `design-docs/` folders, separate from external docs (API references, generated documentation, user-facing guides).

## Core Doctrine

**Visual-first, prose-second.** Diagrams, tables, and code blocks over paragraphs. Prose explains *why*; visuals show *what* and *how*. Every sentence must be precise and information-dense.

**Watch doc size.** When a single doc exceeds ~1000 lines, it's a sign it should be split. Monolithic specs that grow to thousands of lines exceed agent read limits and mix concerns that belong in separate files. Split by logical boundary — per-block plans, per-component living docs, per-concern sections into their own files.

**Code in plans — minimize.**
- Design plans: **no code snippets.** Describe interfaces, contracts, data shapes — not implementation.
- Implementation plans: code is expected but surgical. Show signatures, key types, critical algorithms. Not full implementations.

**Documentation is every agent's duty.** Not the planner's job. Not "someone else will update this." Every agent — planner, builder, verifier, gardener — treats documentation health as a core output of their work. The next session's agent inherits what you leave behind. Stale docs, missing context, undocumented decisions — these are bugs you're shipping to the next version of yourself. Treat them with the same severity as broken tests.

**Reflect before you finish.** Before completing any documentation task, step back: Does this doc make the system more legible to an agent starting cold? Would you understand this if you had no prior context? If not, fix it.

## Foresight vs Hindsight

**Plans are foresight.** Written before building. "Here's what we're going to do."

**Everything else is hindsight.** Written after building. "Here's how it works now."

Never write living docs about code that doesn't exist yet. Never plan in hindsight.

## Doc Types

### Plans
Bounded work with a lifecycle: `draft → active → complete`. Plans have milestones, acceptance criteria, and a defined end state. Once complete, they become historical records.

There are two kinds of plans:
- **Design plans** — system design, architecture, how components interact. Higher-level. How things should work.
- **Implementation plans** — code-level. What the code looks like, what to build, in what order. Milestones, steps, acceptance criteria.

Small features may combine both in one document. Larger efforts separate them — a design plan at a higher level, implementation plans nested beneath for each buildable piece.

Plans live centralized at `design-docs/plans/`. Plans can nest — a parent plan defines vision and ordering, child plans are independently buildable. Sibling plans are parallel efforts (different services, different components). Nested plans are phases of the same effort (blocks within a service).

**Plans are never condensed, summarized, or rewritten.** Every diagram, rejected alternative, and reasoning chain is part of the decision trail. When reorganizing or moving plans, use `cp` — not "summarize and rewrite." An agent's instinct to tidy by condensing destroys the very context that makes plans valuable as historical records.

### Living Docs
Describe how things work *now*. Staleness is a bug. Living docs emerge from implementation — created after building, not before.

- **System docs** — how a service/module/component works
- **Integration docs** — how things connect, contracts, boundaries
- **Data docs** — models, schemas, state machines
- **Test docs** — test strategy, fixture guides, integration setup

Living docs live near what they describe — distributed, not centralized:
- System-level: `design-docs/` at repo root
- Package-level: `{package}/design-docs/`
- Test-level: `{test-dir}/design-docs/`

### ARCHITECTURE.md
The entry point. System map at `design-docs/ARCHITECTURE.md`. Links to deeper living docs. An agent starting a fresh session reads this first.

### PRINCIPLES.md
Golden rules at `design-docs/PRINCIPLES.md`. Short, opinionated, evolved through experience.

## Folder Structure

```
design-docs/                            # System-level (repo root)
├── plans/                              # ALL plans — centralized
│   └── {name}/
│       ├── {name}_plan.md              # The plan (foresight)
│       ├── {name}_decisions.md         # Decisions made during execution
│       ├── {name}_verification.md      # Verifier's report
│       └── {sub-plan}/                 # Nested child plans
│           └── {sub-plan}_plan.md
│
├── ARCHITECTURE.md                     # System map — the entry point
├── PRINCIPLES.md                       # Golden rules
└── {topic}.md                          # System-level living docs (hindsight)

{package}/
├── design-docs/                        # Package-level living docs
│   └── {topic}.md
└── tests/
    └── design-docs/                    # Test-level living docs
```

Use semantic file names — every file should be identifiable by name alone. No generic `plan.md` or `decisions.md` that require reading the parent folder to understand.

## Frontmatter

### Plans
```yaml
---
status: draft | active | complete
created: YYYY-MM-DD
updated: YYYY-MM-DD
scope: system | package-name
parent: parent-plan-name        # if nested
related:                        # sibling or influencing plans
  - other-plan-name
---
```

### Living Docs
```yaml
---
created: YYYY-MM-DD
updated: YYYY-MM-DD
plans:                          # traceability — what plans shaped this
  - plan-that-created-this
  - plan-that-modified-this
---
```

### Decision Logs
```yaml
---
plan: plan-name
created: YYYY-MM-DD
---
```

Entries within docs use `[YYYY-MM-DD]` or `[YYYY-MM-DD HH:MM]` timestamps. Update the `updated` field on meaningful changes.

## Agent Roles in Documentation

Every agent owns documentation quality. The table below shows the *minimum* — go beyond it when you see gaps.

```
Agent     │ Creates              │ Maintains                  │ Flags
──────────┼──────────────────────┼────────────────────────────┼──────────────────────
Planner   │ Plans, decisions     │ Seeds ARCHITECTURE.md,     │ Missing context,
          │                      │ PRINCIPLES.md if absent    │ stale entry points
──────────┼──────────────────────┼────────────────────────────┼──────────────────────
Builder   │ Living docs after    │ Updates plans (progress,   │ Drift between plan
          │ implementation       │ surprises), ARCHITECTURE   │ and reality
──────────┼──────────────────────┼────────────────────────────┼──────────────────────
Verifier  │ Verification report  │ Validates doc accuracy     │ Stale docs, missing
          │                      │ alongside code quality     │ coverage, doc drift
──────────┼──────────────────────┼────────────────────────────┼──────────────────────
Gardener  │ —                    │ Audits all docs against    │ Orphaned plans,
          │                      │ reality, prunes, cross-    │ broken links, gaps
          │                      │ links, marks complete      │
```

If you see a stale doc while doing other work, fix it or flag it. Don't walk past it.

## Lifecycle

1. Planner creates plan (draft → active)
2. Builder implements, updates plan (progress, surprises, decisions), creates living docs
3. Verifier reviews, writes `{name}_verification.md`
4. Plan marked complete — historical record
5. Gardener maintains living doc accuracy over time