/docs — Project Documentation

You are managing an agent-first documentation architecture. Your goal is to keep project documentation accurate, useful, and minimal.

Determine mode

1. If the user explicitly says "init" or "setup", use Init mode.
2. If the project is missing core doc files (no ROADMAP.md, no design-docs/), suggest Init mode.
3. Otherwise, use Update mode.

---

Init mode

Scaffold the documentation structure for this project. Work with the user to flesh out each file — don't just create empty templates.

Steps

1. Assess what exists. Check for existing README.md, CLAUDE.md, ARCHITECTURE.md, etc. Don't overwrite existing content — integrate with it using these rules:

   • README.md: Preserve existing content. Reorganize into template sections if the structure is loose, but keep the substance.
   • CLAUDE.md: Never modify existing instructions. If there's no existing documentation section, append one using the template. If there's already a documentation section (or similar conventions like "work log" or "commit" instructions), show the user both the existing rules and the template rules, and ask which to keep or how to merge them. Existing project conventions take precedence over template defaults.
   • ARCHITECTURE.md: If one exists, adopt its structure and fill gaps from the template. If not, create from template.
   • Other files (ROADMAP, IDEAS, MARKETING): Create fresh from templates — these are unlikely to exist already.

2. Discuss scope with the user. Not every project needs every file. At minimum, most projects benefit from:

   • README.md (what is this project?)
   • ROADMAP.md (what needs to happen?)
   • CLAUDE.md additions (agent maintenance instructions)

   Larger projects may also want:

   • ARCHITECTURE.md (system design)
   • IDEAS.md (brainstorming backlog)
   • MARKETING.md (go-to-market notes)
   • design-docs/ and logs/ directories

3. Create files using the templates in references/ as starting points. Each template is a separate file:

   • references/roadmap.md — ROADMAP.md template
   • references/ideas.md — IDEAS.md template
   • references/architecture.md — ARCHITECTURE.md template
   • references/marketing.md — MARKETING.md template
   • references/design-doc.md — design doc template
   • references/log.md — daily log template
   • references/claude-md.md — CLAUDE.md documentation section

   Read only the templates you need. Adapt them to the project — don't use verbatim. Work with the user to fill in real content rather than leaving placeholders.

4. Add maintenance instructions to CLAUDE.md. Create CLAUDE.md if it doesn't exist. Use references/claude-md.md as the base. Adapt to what files were actually created (e.g., omit the IDEAS.md instruction if that file wasn't created).

5. Create initial log entry in logs/ for today, noting the documentation setup.

---

Update mode

Review recent work and bring documentation up to date.

Steps

1. Scan recent activity. Check:

   • git log for recent commits since the last log entry. Find the newest file in logs/ to determine the cutoff date. If no prior log exists, scan the last ~20 commits for context.
   • Current state of ROADMAP.md — are items stale? Anything done but not checked off?
   • Existing design-docs — any need status updates?
   • If logs/ doesn't exist yet, create it and start the first entry.

2. Update ROADMAP.md. Check off completed items with dates and commit hashes. Add any new work that's emerged. Move items between sections as needed.

3. Update or create today's log entry in logs/. Summarize what was done, link to relevant design-docs or commits. Focus on narrative — surprises, debugging insights, decisions made. Don't duplicate information that's already in design-docs.

4. Update design-docs if any active ones need status changes or new decisions recorded.

5. Surface gaps. Let the user know if you notice:

   • Work that doesn't have a corresponding ROADMAP entry
   • Decisions that aren't documented anywhere
   • Stale items that might need to be moved to wontdo

Keep updates concise. The goal is accurate docs, not comprehensive prose.

---

File reference

When creating or updating these files, read the corresponding template from references/ for the expected structure.

File	Template	Purpose	When to update
README.md	—	Project goal, what this is	When the project scope changes
ARCHITECTURE.md	references/architecture.md	System design, components	When architecture changes
ROADMAP.md	references/roadmap.md	Status, active work, done, wontdo	After completing or starting work
IDEAS.md	references/ideas.md	Brainstorming, not-yet-ready	When ideas come up
MARKETING.md	references/marketing.md	Positioning, distribution, content	When marketing strategy evolves
design-docs/YYYY-MM-DD-*.md	references/design-doc.md	Feature specs and plans	When planning or after key decisions
logs/YYYY-MM-DD.md	references/log.md	Daily narrative	After each work session
CLAUDE.md (docs section)	references/claude-md.md	Agent maintenance instructions	During init