# Init > Scaffold or repair the Orient docs system (STATE.md, decisions/, architecture.md) in this repo. Run once per project. - Skill: `chaitanya299/init` (Agent Skill) - Install (CLI): `npx skillmds@latest add chaitanya299/init` - Raw SKILL.md: https://api.skillmd.com/api/skills/chaitanya299/init/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: Chaitanya299 (https://skillmd.com/u/chaitanya299) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/chaitanya299/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 `` and `` 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: ```markdown --- 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.