§ reference · skill
annotate-inline
Documents a project's architecture for AI assistants by writing compact `CLAUDE.md` files inline next to the source they describe.
§ 01 · purpose
Purpose
Same end goal as annotate-guidance — onboards AI agents to a brownfield codebase via per-directory architecture notes — but places CLAUDE.md files next to the source they describe instead of in a shadow tree. Choose this when teams prefer guidance to live beside the code.
§ 02 · when to use
When to use it
- The project should keep architecture docs adjacent to source.
- You need first-time AI onboarding for a codebase that already uses inline
CLAUDE.mdconventions. - Pick
annotate-guidanceinstead for shadow-tree (.rpiv/guidance/) layout. - Pick
migrate-to-guidancewhen existing inline files need to move into the shadow tree.
§ 03 · inputs
Inputs
| Name | Required | Source |
|---|---|---|
target-directory | no | CLI argument or current working directory |
existing CLAUDE.md / READMEs | no | Paths mentioned inline |
- existing CLAUDE.md / READMEs
- Read fully before agents dispatch.
§ 04 · outputs
Outputs
| Artifact | Path | Format |
|---|---|---|
| Root project guidance | CLAUDE.md (project root) | markdown |
| Per-layer guidance | <layer>/CLAUDE.md (next to source) | markdown |
§ 05 · key steps
Key steps
- Read directly-mentioned files first Why: Existing docs lock in team-level decisions before any subagent runs, so later passes don't contradict what's already documented.
- Pass 1 — map tree and detect architecture (parallel) Why: One locator agent maps the tree; one identifies the architecture from folder shape and manifest files. Running both concurrently halves discovery time.
- Apply guidance-depth rules; propose targets Why: A two-pass selection (top-level layers, then opt-in decomposition) keeps the target list grounded in folder shape and is shown to the user for confirmation before any analysis spend.
- Pass 2 — analyzer + pattern-finder per target (parallel) Why: Per-target
codebase-analyzeranswers "what is this for";codebase-pattern-finderextracts idiomatic code shapes. Both run concurrently for depth per token. - Developer checkpoint on findings Why: One question at a time surfaces deprecated patterns, undocumented conventions, and migrations-in-progress that code reading alone cannot reveal.
- Batch-write CLAUDE.md files Why: Files are written in a single emission pass after the checkpoint, so the inline-guidance set lands internally consistent.
§ 06 · related skills