Documentation Structure

Michi projects organize documentation by what you’re building (epics), not by document type. The epic is the essential unit — plans, verification, and journals are structure within it.

Core documents

Document	Purpose	Size	Always loaded?
`CLAUDE.md`	Agent rules, conventions, build/test commands, `@`-references	M	Yes
`PROJECT.md`	Goals, users, key features, success criteria	M	Yes
`STATUS.md`	Current state, active work, what’s next	S	Yes
`ARCHITECTURE.md`	Design overview, component relationships, data flow	M-L	On demand

File naming convention: UPPERCASE.md files are top-level, always-read, project-wide. lowercase.md files are working documents scoped to an epic or milestone. Capitalization signals importance — the filesystem communicates priority.

Epic structure

Epics are the universal unit of named work — anything substantive enough to track gets one, from research spikes to multi-milestone features. Multiple concurrent epics is normal; the “main thrust” is signaled in STATUS.md, not by a separate doc tier.

docs/
  epics/
    my-feature/                  # Subdirectory for multi-milestone or accumulating work
      spec.md                    # What to build
      verification/
        scenarios.md             # Stories about users getting benefits
        test-plan.md             # How to verify (tooling, auth, strategy)
      journal.md                 # Learnings, gotchas, open questions
      plans/
        m1-data-model.md         # Milestone plan (the implementation contract)
        m2-api-services.md
    tool-evaluation.md           # Flat-file epic — short-arc research or single-workshop output
  reference/                     # Cross-epic, long-lived
    code-style.md                # Applied coding principles
    patterns.md                  # Patterns and anti-patterns

Each epic contains everything about that effort. When it’s done, archive the whole directory (or file). No hunting across docs/plans/, docs/verification/, docs/learnings/.

Document types

Essential (the what and why)

Specs — what to build, features, user stories, constraints
Verification scenarios — how to know it’s delivered (the other side of specs)

Incidental (the how)

Plans — tactical implementation steps for a milestone
Journals — execution record: learnings, open questions, gotchas
Test plans — tooling, auth strategy, environment prerequisites

Progressive detail (S-M-L-XL)

Not every reader needs every detail at every moment:

Level	Purpose	Who reads	Examples
S	Orientation — what exists	Everyone, every session	`STATUS.md`
M	Working context — enough to act	Agent at session start	`CLAUDE.md`, `PROJECT.md`, current plan
L	Full detail — implementation depth	During implementation	`ARCHITECTURE.md`, verification scenarios
XL	Posterity — minimize loss	Retrospectives	Journals, archived plans

The @-reference mechanism in CLAUDE.md controls what loads at session start. Point it at the current milestone’s plan, and the agent has the context it needs without loading everything.

Information flow

During a session

The agent writes to one place: the current milestone’s plan doc. Decisions, notes, surprises, discussion items — all in the plan doc. One place to write, zero filing decisions during implementation.

During debrief

The debrief curates what was captured:

From plan doc	Promoted to	When it’s worth promoting
`## Decisions`	`CLAUDE.md` or patterns.md	Decision reveals a reusable pattern
`## Notes`	`journal.md`	Domain-specific gotcha worth preserving
`## Discussion`	Resolved, deferred, or promoted	Triaged during debrief
`## Scenarios`	Epic’s scenario catalog	Scenario has ongoing regression value

Between sessions

Update CLAUDE.md @-refs for the next milestone
Move completed epics to docs/archive/
Review STATUS.md for staleness

Scaling

Start with files. Split to directories when a file gets unwieldy:

Small epic: spec.md, journal.md, plans/m1-thing.md
Large epic: specs/feature-a.md, journal/service-gotchas.md, verification/scenarios/submit-flow.md

The structure grows with the work. Don’t pre-build what you don’t need yet.