docs-keeper

Maintain project documentation with clear human/agent separation. Includes planning workflow.

Project Structure

project/
  README.md              ← project entrypoint (human-facing)
  AGENTS.md              ← agent instructions (project-specific)
  CLAUDE.md              ← symlink → AGENTS.md
  docs/
    ARCHITECTURE.md      ← human: high-level design, domain concepts
    *.md                 ← human: guides, ADRs, onboarding
    agents/
      PLAN.md            ← agent: living project plan
      ASSUMPTIONS.md     ← agent: tracked assumptions
      notes/             ← agent: session notes
        YYYYMMDD-HHMM-slug.md

Project root

• README.md — canonical project entrypoint (setup, usage, status).
• AGENTS.md — project-specific agent instructions. Tech stack, commands, conventions, gotchas. Keep under 150 lines.
• CLAUDE.md — always a symlink to AGENTS.md. Ensure this exists: ln -sf AGENTS.md CLAUDE.md

Human zone (docs/*.md)

Written by humans, maintained by humans. Agents read these but don't edit unless explicitly asked.

• README.md at project root is the primary project overview.
• docs/ARCHITECTURE.md — high-level design. Describe capabilities and domain concepts, not file paths.
• Other docs as needed: ADRs, API guides, onboarding.

Agent zone (docs/agents/)

Written and maintained by agents. Committed to git. Survives context windows and agent rotations.

• PLAN.md — the living project plan (see Planning below)
• ASSUMPTIONS.md — document assumptions before acting. Update as confirmed or invalidated.
• notes/ — timestamped session notes (see Session Notes below)

---

Planning

Before any multi-step work, create or update docs/agents/PLAN.md.

Brainstorming (before the plan)

Don't jump into planning. Understand first:

1. Explore context — read existing docs, code, recent commits
2. Ask clarifying questions — one at a time, understand purpose/constraints/success criteria
3. Propose 2-3 approaches — with trade-offs and your recommendation
4. Present design in sections — scaled to complexity, get approval after each section
5. Save design — write validated design to docs/agents/PLAN.md

Do NOT write code until the design is approved. Every project goes through this, even "simple" ones. Simple projects are where unexamined assumptions waste the most work.

Plan format

Plans are bite-sized tasks. Each task is one action (2-5 minutes):

# [Feature] Implementation Plan

**Goal:** One sentence.
**Approach:** 2-3 sentences.
**Tech:** Key technologies/libraries.

---

### Task 1: [Component]

**Files:**
- Create: `exact/path/to/file.go`
- Modify: `exact/path/to/existing.go`
- Test: `exact/path/to/file_test.go`

**Steps:**
1. Write failing test
2. Run test, verify it fails
3. Write minimal implementation
4. Run test, verify it passes
5. Commit

**Verify:** `go test ./... -run TestSpecificThing`

Rules:

• Exact file paths, always
• Complete code in plan (not "add validation")
• Exact commands with expected output
• Each step is one action, not a paragraph

Execution

Execute plans in batches (3 tasks at a time):

1. Follow each step exactly
2. Run verifications as specified
3. After each batch: report what was done, show verification output, wait for feedback
4. Apply feedback, continue next batch

Stop and ask when:

• Hit a blocker (missing dep, test fails, instruction unclear)
• Plan has gaps
• Verification fails repeatedly
• Don't guess through blockers

---

Session Notes

Write notes to docs/agents/notes/YYYYMMDD-HHMM-slug.md when you learn something worth preserving:

• Lessons learned from debugging
• Architecture decisions and rationale
• Failed approaches and why they didn't work
• Investigation findings (API quirks, library gotchas)
• Mistakes and how to avoid them

Keep notes concise. Future agents read these for context.

---

Session Discipline

Start: Read docs/agents/PLAN.md and AGENTS.md.

End: Update plan if anything changed. Write a note if you learned something.

---

Keeper Behavior

When invoked as docs-keeper (or when documentation is stale):

1. Ensure structure — AGENTS.md exists, CLAUDE.md is symlinked, docs/agents/ exists
2. Audit — check all docs exist, are accurate, aren't contradicting code
3. Fix — update what you can (agents zone only, unless asked for human zone)
4. Flag — report what needs human attention
5. Trim — AGENTS.md should stay under 150 lines. Move overflow to docs/

Rules

• One code example beats three paragraphs
• Describe capabilities, not file paths (paths go stale)
• Don't document what agents already know (language syntax, common patterns)
• Create docs/agents/ and subdirectories if they don't exist
• Never edit human zone docs without explicit permission