Init

/orient:init

Scaffold a small, context-cheap documentation system into this repo, or repair an existing one. This writes files, so it is user-invoked only and every write is a proposal the user approves — never a silent write. Show the drafted content before writing it.

Work through these steps in order.

1. Resolve the docs directory

Read CLAUDE_PLUGIN_OPTION_DOCS_DIR from the environment. If unset or empty, use docs. Call this $DOCS_DIR for the rest of the run. Every path below is relative to the repo root.

The one artifact every future session depends on is the CLAUDE.md pointer block (step 6) — it carries the triggers that make decision-capture work. If there's any chance you won't finish every step, write that block first; the rest of this flow only refines the docs it points to.

2. Detect an existing setup (repair mode)

If $DOCS_DIR/STATE.md or $DOCS_DIR/decisions/ already exists, switch to repair mode: report what exists, propose only additions, and never overwrite an existing file. init must be safe to run repeatedly.

3. Survey the repo with a subagent

Say one line first so the wait is expected, not a suspected hang: Surveying the repo (runs in a subagent, ~30-60s on large repos)... Then dispatch the repo-cartographer agent. Do not read the repo yourself — the point is that the survey burns the subagent's context window, not this one.

4. Draft the core docs

From the survey, draft (do not write yet):

• $DOCS_DIR/STATE.md — from the templates/STATE.md shape, ## Current focus first. Fill the ## Shape mermaid diagram from the survey: the major components and how they connect, 6 nodes max. Not a call graph.
• $DOCS_DIR/architecture.md — from templates/architecture.md: entry points, module boundaries, the three or four critical paths. Not a call graph, not a file listing.
• $DOCS_DIR/decisions/0001-record-architecture-decisions.md — the ADR that establishes the practice, from templates/adr.md.

Never write a secret value into any doc. If the survey surfaced credentials, name the file, not its contents — these docs get committed and pushed.

5. Seed candidate ADRs from git history

Read git log --oneline -n 200. Identify commits that look like real architectural decisions — dependency additions, framework or database choices, auth or API redesigns, migrations. Draft these as candidate ADRs with the commit SHA in the Context section. Present the candidate list and write only the ones the user approves. Never bulk-generate ADRs unattended.

6. Write the CLAUDE.md block

Use templates/claude-md-block.md, substituting {{DOCS_DIR}} with $DOCS_DIR.

• No CLAUDE.md → create it with the block.
• CLAUDE.md has both <!-- ORIENT:START --> and <!-- ORIENT:END --> markers → replace only the text between them.
• Markers absent → append the block.
• Missing or duplicated end marker, or CRLF line endings → report it and stop rather than corrupt the file; let the user fix or confirm. Never touch content outside the markers.

7. Offer a path-scoped rule (do not create without a yes)

Offer, but do not create without approval, a starter rule at .claude/rules/, showing the paths: frontmatter form so conventions cost nothing until a matching file is touched. Example to show:

---
paths:
  - "src/**"
---
Conventions that apply when editing files under src/.

8. Print a summary

Files created, files skipped (repair mode), and the exact next commands to run.

The whole flow is a proposal the user approves, not a silent write.