ARCHITECTURE.md Writer

Write architecture docs that give contributors a fast mental model of system shape, starting points, and non-negotiable constraints. Prefer stable structure over implementation trivia, and prefer editing existing ARCHITECTURE.md files over creating new ones unless the scope is wrong.

Workflow

1. Determine scope and document topology.

• Inspect whether the task is for the repo root, a subsystem, or both.
• Treat the root ARCHITECTURE.md as the system map, not the full encyclopedia.
• Add nested ARCHITECTURE.md files only when a subtree has enough independent structure, lifecycle, or constraints to justify its own page.
• When adding a nested doc, update the parent doc to link to it and explain its scope in one line.
• Read references/progressive-disclosure.md when deciding where to split content.

2. Build context from stable code structure.

• Read existing docs only to recover boundaries, terminology, and decision history.
• Inspect entry points, package boundaries, long-lived directories, interfaces, background jobs, storage seams, and external integrations.
• Trace one or two important flows end to end so the document reflects how the system actually moves.
• Capture responsibilities, interactions, and invariants before drafting prose.