CLAUDE.md · diff

git:20260404.cedc259 to git:20260406.66d82b5

61 added, 0 removed. Audit A to A.

## MCP Tools: code-review-graph

**IMPORTANT: This project has a knowledge graph. ALWAYS use the

code-review-graph MCP tools BEFORE using Grep/Glob/Read to explore

the codebase.** The graph is faster, cheaper (fewer tokens), and gives

you structural context (callers, dependents, test coverage) that file

scanning cannot.

### When to use graph tools FIRST

- **Exploring code**: `semantic_search_nodes` or `query_graph` instead of Grep

- **Understanding impact**: `get_impact_radius` instead of manually tracing imports

- **Code review**: `detect_changes` + `get_review_context` instead of reading entire files

- **Finding relationships**: `query_graph` with callers_of/callees_of/imports_of/tests_for

- **Architecture questions**: `get_architecture_overview` + `list_communities`

Fall back to Grep/Glob/Read **only** when the graph doesn't cover what you need.

### Key Tools

| Tool | Use when |

|------|----------|

| `detect_changes` | Reviewing code changes — gives risk-scored analysis |

| `get_review_context` | Need source snippets for review — token-efficient |

| `get_impact_radius` | Understanding blast radius of a change |

| `get_affected_flows` | Finding which execution paths are impacted |

| `query_graph` | Tracing callers, callees, imports, tests, dependencies |

| `semantic_search_nodes` | Finding functions/classes by name or keyword |

| `get_architecture_overview` | Understanding high-level codebase structure |

| `refactor_tool` | Planning renames, finding dead code |

### Workflow

1. The graph auto-updates on file changes (via hooks).

2. Use `detect_changes` for code review.

3. Use `get_affected_flows` to understand impact.

4. Use `query_graph` pattern="tests_for" to check coverage.

+

+ # Claude Repo Routing

+ Use `.agent/project.yaml` and `.agent/context/*` as the repo-local source of truth generated by Kiwi Control.

+ Profile: `product-build`

+ Execution mode: `assisted`

+ Prefer this lightweight guidance file over invasive repo-local runtime config in v2.

+ Authority order:

+ 1. existing trusted repo authority files already in the repo

+ 2. promoted canonical docs explicitly referenced by those files

+ 3. generated Kiwi Control overlays

+ 4. `.agent/context/*`

+ 5. fallback templates

+ Before medium/high complexity work or resuming a prior phase:

+ 1. read the existing repo authority files and any promoted canonical docs they reference

+ 2. read `.agent/state/active-role-hints.json`

+ 3. read `.agent/state/current-phase.json`

+ 4. read `.agent/memory/current-focus.json` and `.agent/state/checkpoints/latest.json`

+ 5. read the latest task packet, latest handoff, latest reconcile, and latest dispatch manifest when present

+ 6. read `.agent/context/commands.md`, `.agent/context/specialists.md`, `.agent/context/tool-capabilities.md`, and `.agent/context/mcp-capabilities.md`

+ 7. read the relevant `.github/instructions/*.instructions.md`

+ 8. read relevant `.github/agents/*.md`, `.agent/roles/*.md`, and `.agent/templates/role-result.md`

+ 9. read `.agent/checks.yaml` and `.agent/scripts/verify-contract.sh`

+ 10. read `.agent/project.yaml`

+ 11. read `.agent/context/architecture.md`

+ 12. read `.agent/context/conventions.md`

+ 13. read `.agent/tasks/` packets when present

+ Do not rely on machine-local `.claude/*` files as portable authority unless the repo explicitly routes to them.

+ Cloud-hosted runtimes may not see machine-global files, so treat repo-local artifacts as the portable contract.

+ Workflow rules:

+ - trivial work may stay direct when it is local, low-risk, and does not affect contracts, auth, security, release behavior, or multiple files

+ - use `run` for non-trivial single-owner work that needs repo-aware framing

+ - use `fanout` for guarded or complex work that benefits from planner / implementer / reviewer / tester separation

+ - use `dispatch`, `collect`, and `reconcile` when simultaneous small-role work is useful and outputs must be compared explicitly

+ - require `checkpoint` and `handoff` when Claude is taking over after another tool or handing work back

+ - consult `push-check` before recommending push on non-trivial or guarded work

+ - consult `release-check` or `phase-close` when closing a phase or approaching release readiness

+ - treat `.agent/state/active-role-hints.json` as the quickest repo-local pointer for current role focus, next file to open, next command to consider, latest continuity artifacts, next specialist, and suggested MCP pack

+ - treat `.agent/memory/current-focus.json` as the smallest portable continuity summary when resuming

+ Gate behavior:

+ - if policy or reconcile state is blocked, treat it as a mandatory gate rather than advisory noise

+ - if authority files disagree, stop and warn instead of proceeding confidently

+ - if promoted canonical docs exist, surface them early instead of restarting context from scratch

+ Specialists and MCP:

+ - prefer the curated specialist registry in `.agent/context/specialists.md` when the task clearly maps to implementation, QA, security, refactor, docs, planning, release, or MCP-policy work

+ - emit canonical specialist IDs in any repo-local artifact you write; treat older aliases as compatibility input only

+ - MCP usage follows policy, capability, trust, profile, specialist, and approval rules; do not call MCP tools opportunistically

+