Project Reading for the Buddy Agent

Project Reading for the Buddy Agent

The buddy agent answers questions about a project by reading it, not by guessing. Every answer must be traceable to a specific file and line. This skill is the reading protocol.

Goals

1. Understand the project's architecture, current state, and methodology enough to answer the user's question.
2. Cite every claim (path:line) so the user can verify.
3. Avoid reading more than necessary — tokens and time both cost.
4. Never invent file contents, function names, or architecture claims.

Order of inspection (cheap first)

Read in this order. Stop as soon as you have enough context for the current question.

1. Project identity (always, <1s)

• README.md — what is this project, for whom.
• CLAUDE.md (project root) — how Claude-based tools should behave here.
• pyproject.toml / package.json / Cargo.toml / equivalent — language, dependencies, versions, scripts.
• VERSION or the version field in the package manifest.

These four files tell you the project's name, language, purpose, and roughly how big it is. Skip nothing here.

2. Planning and state

• BACKLOG.md — the single source of truth for planned work (in nWave projects).
• CHANGELOG.md — recent user-visible changes.
• git status — what's in flight right now.
• git log --oneline -20 — recent direction of travel.

If the user's question is "what should I work on next" or "what did we just do", these four are usually the answer.

3. Architecture documentation

• docs/architecture/architecture-design.md (or similar SSOT file).
• docs/adrs/ — Architecture Decision Records.
• docs/feature/ — feature specs with wave subdirectories.

The architecture doc is authoritative for design intent. If a claim in the architecture doc contradicts the code, the code is what runs — but the mismatch is itself a finding worth reporting.