§ reference · skill
annotate-guidance
Documents a project's architecture for AI assistants by writing compact architecture.md files into a .rpiv/guidance/ shadow tree alongside the source.
§ 01 · purpose
Purpose
Onboards Claude, Cursor, or any Pi-aware AI agent to a brownfield codebase by emitting a parallel .rpiv/guidance/ tree of small, scannable architecture.md files. The guidance system later injects these on demand when an agent touches the matching directory, so context cost stays proportional to what the agent actually reads.
§ 02 · when to use
When to use it
- The project should keep
CLAUDE.mdout of the source tree (shadow-tree layout). - You need first-time AI onboarding or want to refresh stale guidance after a refactor.
- Pick
annotate-inlineinstead if you wantCLAUDE.mdfiles next to the code. - Pick
migrate-to-guidanceinstead if inlineCLAUDE.mdfiles already exist and only need to be moved.
§ 03 · inputs
Inputs
| Name | Required | Source |
|---|---|---|
target-directory | no | CLI argument or current working directory |
existing architecture docs | no | Any README.md, CLAUDE.md, or architecture.md the user mentions inline |
- target-directory
- Defaults to CWD when omitted.
- existing architecture docs
- Read fully before agents are dispatched.
§ 04 · outputs
Outputs
| Artifact | Path | Format |
|---|---|---|
| Root overview | .rpiv/guidance/architecture.md | markdown |
| Per-layer guidance | .rpiv/guidance/<sub>/architecture.md | markdown |
| Decomposed sub-layer guidance | .rpiv/guidance/<sub>/<child>/architecture.md | markdown |
§ 05 · key steps
Key steps
- Read directly-mentioned files first Why: Locks domain knowledge from existing docs into the main context before any subagent runs, so later passes do not contradict what the team already wrote down.
- Pass 1 — map tree and detect architecture in parallel Why: Two locator agents — one tree-mapper, one architecture-sniffer — run side by side so layout discovery costs one round-trip instead of two.
- Apply guidance-depth rules; propose targets Why: A two-pass selection (top-level layers, then opt-in decomposition of composite layers) keeps the target list grounded in folder shape rather than guesswork, and is shown to the user for confirmation before any analysis spend.
- Pass 2 — analyzer + pattern-finder per target (parallel) Why: One
codebase-analyzeranswers the "what is this layer for" questions; onecodebase-pattern-finderextracts idiomatic code shapes. Running both per target in parallel produces the deepest signal per token. - Developer checkpoint on findings Why: Surfaces deprecated patterns, migrations-in-progress, and cross-layer rules that code reading alone cannot reveal. Asked one question at a time so each answer can steer the next.
- Batch-write architecture.md files Why: All files are written in a single emission pass after the checkpoint, so the guidance tree is internally consistent and never left half-populated mid-session.
§ 06 · related skills