HumanBean17 · HumanBean17 · May 25, 2026 · May 25, 2026
@@ -14,7 +14,7 @@ gitignored).
 | Directory | Audience | Purpose |
 |-----------|----------|---------|
 | **`.agents/skills/`** (`.claude/skills/`, `.cursor/skills/`) | Agents **developing** this repo | propose, plan-prompts, pr-open, pr-review |
-| **`skills/`** (project root) | Agents **using** this tool on their own codebase | /callers, /routes, /explain-feature, /impact-of, etc. |
+| **`skills/tier-1/`** + **`skills/tier-2/`** (project root) | Agents **using** this tool on their own codebase | /callers, /routes, /explain-feature, /impact-of, etc. |
 
 `.agents/` skills are loaded by the agent working *on* java-codebase-rag source
 code. `skills/` are shipped to consumers — they instruct an agent to call the
@@ -55,7 +55,7 @@ when needed.
 - `docs/CODEBASE_REQUIREMENTS.md` — Java-repo assumptions and per-file map of
   what to edit when a target tree doesn't match defaults.
 - `tests/README.md` — testing philosophy.
-- **`skills/`** — user-facing skills shipped to java-codebase-rag consumers (navigation, workflow). Developer workflow skills live in **`.agents/skills/`**, not here.
+- **`skills/tier-1/`** + **`skills/tier-2/`** — user-facing skills shipped to java-codebase-rag consumers. Tier 1 are single-intent listings (`/callers`, `/routes`, `/clients`, …); Tier 2 are multi-step workflows (`/explain-feature`, `/impact-of`, `/trace-request-flow`, `/mini-map`). Users opt in per tier. Developer workflow skills live in **`.agents/skills/`**, not here.
 - **`propose/`** — design proposes. **In-flight** proposes live in
   **`propose/active/`**. **`propose/completed/`** — landed work and rationale.
   **List or search this tree** for current filenames; do not rely on enumerated

@@ -17,6 +17,24 @@ For the design rationale, the GPS metaphor, and the full ontology, see [`docs/pa
 
 ---
 
+## Why this exists
+
+Generic code-search tools (grep, ctags, vector-only RAG) hit a ceiling on real Java microservice estates: they find files but lose the structure that makes a Spring/JAX-RS system navigable. This project is built around five choices that target that gap.
+
+- **Hybrid RAG + GraphRAG, not either-or.** Semantic recall (LanceDB chunk vectors) and structural navigation (Kuzu property graph) are composed in one surface. `search` finds candidate nodes by meaning; `neighbors` walks the exact edge you care about (`CALLS`, `IMPLEMENTS`, `INJECTS`, `DECLARES_ROUTE`, …). The agent picks the right primitive per step instead of being forced into pure-vector or pure-symbol search.
+
+- **A Java-tuned role model.** Symbols are labelled with stereotypes inferred from Spring and JAX-RS conventions — `CONTROLLER`, `SERVICE`, `REPOSITORY`, `CLIENT`, `PRODUCER`, `MAPPER`, `DTO`. Agents can ask "list controllers" or "who injects this repository" directly, instead of grep-ing for `@RestController` and hoping for the best. Roles drive both filtering (`find` with a `NodeFilter`) and ranking.
+
+- **Ranking specialized for Java codebases.** The composite ranker is aware of role, microservice, and FQN structure — not a generic BM25. A search for `"chat ingress"` surfaces controllers before utility classes; a search scoped to one microservice doesn't drown in matches from the other 19. Defaults are tuned on the bank-chat fixture and exposed in `docs/CONFIGURATION.md` for per-repo overrides.
+
+- **Cross-service resolution + system-level navigation.** `HTTP_CALLS` and `ASYNC_CALLS` edges connect Clients and Producers in one microservice to Routes and Handlers in another, resolved at index time from URL/topic strings + Spring `@FeignClient` / `RestTemplate` conventions. `/who-hits-route`, `/trace-request-flow`, and `/impact-of` use these to answer questions a single-service tool fundamentally can't — "who calls this REST endpoint from outside this service", "trace this Kafka message end-to-end", "if I change this DTO, which services break".
+
+- **Brownfield annotations as a first-class override.** Real Java estates have hand-rolled HTTP clients, dynamic topic names, reflection-heavy routing. `@CodebaseHttpRoute`, `@CodebaseAsyncRoute`, `@CodebaseHttpClient`, and `@CodebaseProducer` let you pin the truth in source. They have **exclusive priority** — when a symbol is annotated, framework-convention inference is skipped entirely. You get a correct graph on legacy code without rewriting it.
+
+The rest of this README is the install, walkthrough, and tool cheat sheet for putting that to work.
+
+---
+
 ## Install
 
 ```bash

@@ -1,6 +1,20 @@
 # skills/ — Layer 3 navigation and workflow skills
 
-High-level intents over the 5-tool MCP (`search` / `find` / `describe` / `neighbors` / `resolve`). Skills are agent-side prompt scaffolding — they are NOT a second MCP API and NOT CLI subcommands.
+High-level intents over the 5-tool MCP (`search` / `find` / `describe` / `neighbors` / `resolve`). Skills are agent-side prompt scaffolding — they are **not** a second MCP API and **not** CLI subcommands.
+
+## Pick the tier you need
+
+Skills are organized by tier — load only what you use.
+
+```
+skills/
+  tier-1/   ← Navigation. 11 single-purpose skills.
+  tier-2/   ← Workflow. 4 multi-step skills that compose Tier 1 with bounds.
+```
+
+- **Just want to list controllers/routes/clients?** Tier 1 is enough — `skills/tier-1/controllers`, `skills/tier-1/routes`, etc.
+- **Need to trace a request, explain a feature, or analyze blast radius?** Tier 2 — `skills/tier-2/trace-request-flow`, etc.
+- **Don't want skills at all?** Copy the block in `docs/AGENT-GUIDE.md` between `<!-- BEGIN java-codebase-rag MCP guide -->` and `<!-- END … -->` into your project's `AGENTS.md` / `CLAUDE.md`. Skills and the guide are **alternatives**, not complements — pick one.
 
 ## Three-layer architecture
 
@@ -10,9 +24,8 @@ High-level intents over the 5-tool MCP (`search` / `find` / `describe` / `neighb
 │   /trace-request-flow, /callees, /controllers, /routes,      │
 │   /impact-of, /mini-map                                      │
 │   ─────────────────────────────────────────────────────────  │
-│   Implementation: SKILL.md in skills/ at project root.       │
-│   Tier 1 = deterministic chains; Tier 2 = bounded workflows │
-│   + /mini-map heuristics.                                    │
+│   Implementation: SKILL.md files in skills/tier-1/ and       │
+│   skills/tier-2/.                                            │
 ├──────────────────────────────────────────────────────────────┤
 │ Layer 2 — Composable primitives (the MCP API)                │
 │   search, find, describe, neighbors, resolve                 │
@@ -22,58 +35,87 @@ High-level intents over the 5-tool MCP (`search` / `find` / `describe` / `neighb
 └──────────────────────────────────────────────────────────────┘
 ```
 
-## Skill index
-
-### Tier 1 — Navigation (deterministic MCP chains)
-
-| Skill | Purpose |
-| ----- | ------- |
-| [`/nl`](nl/SKILL.md) | Natural-language search into the graph |
-| [`/controllers`](controllers/SKILL.md) | List controller classes |
-| [`/routes`](routes/SKILL.md) | List HTTP and messaging routes |
-| [`/clients`](clients/SKILL.md) | List outbound HTTP clients |
-| [`/producers`](producers/SKILL.md) | List outbound async producers |
-| [`/callers`](callers/SKILL.md) | Who calls this method (in-process CALLS) |
-| [`/callees`](callees/SKILL.md) | What this method calls (in-process CALLS) |
-| [`/handlers`](handlers/SKILL.md) | Method that handles a route |
-| [`/who-hits-route`](who-hits-route/SKILL.md) | All inbound paths to a route |
-| [`/implements`](implements/SKILL.md) | Concrete classes implementing an interface |
-| [`/injects`](injects/SKILL.md) | Where a type is injected |
-
-### Tier 2 — Workflow (bounded multi-step)
-
-| Skill | Purpose |
-| ----- | ------- |
-| [`/explain-feature`](explain-feature/SKILL.md) | Understand how a feature works end-to-end |
-| [`/impact-of`](impact-of/SKILL.md) | What breaks if a symbol changes |
-| [`/trace-request-flow`](trace-request-flow/SKILL.md) | Follow a request from entry to persistence |
-| [`/mini-map`](mini-map/SKILL.md) | Noise-filtered call map for a method |
+## Tier 1 — Navigation (deterministic MCP chains)
+
+11 single-purpose skills. Each one is one MCP call (sometimes preceded by a `resolve`).
+
+| Skill | Purpose | One-shot tool chain |
+| ----- | ------- | ------------------- |
+| [`/nl`](tier-1/nl/SKILL.md) | Natural-language search into the graph | `search` → `describe` |
+| [`/controllers`](tier-1/controllers/SKILL.md) | List controller classes | `find(kind="symbol", role="CONTROLLER")` |
+| [`/routes`](tier-1/routes/SKILL.md) | List HTTP and messaging routes | `find(kind="route")` |
+| [`/clients`](tier-1/clients/SKILL.md) | List outbound HTTP clients | `find(kind="client")` |
+| [`/producers`](tier-1/producers/SKILL.md) | List outbound async producers | `find(kind="producer")` |
+| [`/callers`](tier-1/callers/SKILL.md) | Who calls this method (in-process CALLS) | `resolve` → `neighbors(in, CALLS)` |
+| [`/callees`](tier-1/callees/SKILL.md) | What this method calls (in-process CALLS) | `resolve` → `neighbors(out, CALLS)` |
+| [`/handlers`](tier-1/handlers/SKILL.md) | Method that handles a route | `resolve` → `neighbors(in, EXPOSES)` |
+| [`/who-hits-route`](tier-1/who-hits-route/SKILL.md) | All inbound paths to a route | `resolve` → `neighbors(in, [HTTP_CALLS, ASYNC_CALLS, EXPOSES])` |
+| [`/implements`](tier-1/implements/SKILL.md) | Concrete classes implementing an interface | `resolve` → `neighbors(in, IMPLEMENTS)` |
+| [`/injects`](tier-1/injects/SKILL.md) | Where a type is injected | `resolve` → `neighbors(in, INJECTS)` |
+
+## Tier 2 — Workflow (bounded multi-step)
+
+4 multi-step skills. Each one composes Tier 1 calls with explicit depth, recursion, and stop conditions.
+
+| Skill | Purpose | Shape |
+| ----- | ------- | ----- |
+| [`/explain-feature`](tier-2/explain-feature/SKILL.md) | Understand how a feature works end-to-end | `search` → `describe` → bounded `neighbors` walks |
+| [`/impact-of`](tier-2/impact-of/SKILL.md) | What breaks if a symbol changes | `resolve` → `describe` → recursive inbound `neighbors` ≤ depth 2 |
+| [`/trace-request-flow`](tier-2/trace-request-flow/SKILL.md) | Follow a request from entry to persistence | `resolve(route)` → handler → forward CALLS walk ≤ depth 4 + boundary hops |
+| [`/mini-map`](tier-2/mini-map/SKILL.md) | Noise-filtered call map for a hot method | `resolve` → `edge_filter`'d CALLS + skill heuristics ≤ depth 4 |
 
 ## Layout
 
 ```
 skills/
-  <skill-name>/
-    SKILL.md          ← frontmatter (name + description) + markdown body
-  README.md           ← this file
+  README.md              ← this file
+  tier-1/
+    nl/SKILL.md
+    controllers/SKILL.md
+    routes/SKILL.md
+    clients/SKILL.md
+    producers/SKILL.md
+    callers/SKILL.md
+    callees/SKILL.md
+    handlers/SKILL.md
+    who-hits-route/SKILL.md
+    implements/SKILL.md
+    injects/SKILL.md
+  tier-2/
+    explain-feature/SKILL.md
+    impact-of/SKILL.md
+    trace-request-flow/SKILL.md
+    mini-map/SKILL.md
 ```
 
-## Skill structure
+## SKILL.md structure
 
-Every SKILL.md follows this structure:
+Every SKILL.md is self-sufficient — load one skill, get a single working scaffolded prompt:
 
-1. **Frontmatter** — `name` and `description` (used by skill discovery)
-2. **MCP required** — declares the MCP server dependency and enforces tool usage
-3. **Argument contract** — what the skill accepts
-4. **Steps** — imperative MCP call chain (each step names the tool to call)
-5. **Worked example** — concrete walk-through
-6. **Do not** — guardrails against bypassing MCP tools
-7. **Out of scope** — boundaries for when to use a different skill
+1. **Frontmatter** (`name` + `description`) — used by Claude Code / Cursor / Qwen Code for auto-discovery.
+2. **When to use** — concrete triggers and when to prefer a different skill.
+3. **Tools used** — exactly which of `search` / `find` / `describe` / `neighbors` / `resolve` this skill calls.
+4. **Reasoning preamble** — the mandatory `Q-class: <semantic|structured|inspect|walk>` line before each MCP call, with the taxonomy defined inline.
+5. **Argument contract** — what the skill takes.
+6. **Steps** — exact MCP calls with parameters.
+7. **Recovery / stop conditions / recursion limit** (Tier 2: required; Tier 1: short).
+8. **Worked example** — end-to-end on the `tests/bank-chat-system` fixture.
+9. **Do not / Out of scope** — guardrails and pointers to neighboring skills.
+10. **Going deeper** — pointer to `docs/AGENT-GUIDE.md` for the full reference.
 
-## Relationship to developer skills
+## Versioning
 
-Developer workflow skills (propose, pr-review, etc.) live in `.agents/skills/` — they are for contributors working **on** java-codebase-rag. Skills in this directory are for **consumers** using java-codebase-rag to explore their own codebases.
+Skills are versioned lockstep with the MCP. When `NodeFilter` keys, `edge_filter` axes, `edge_types`, or `kind` values change, skills are updated in the same PR. The static validator (`tests/test_agent_skills_static.py`) checks every SKILL.md against the live MCP allowlists.
 
-## Versioning
+## Relationship to `docs/AGENT-GUIDE.md`
+
+Skills and `docs/AGENT-GUIDE.md` are **alternatives**. Pick one:
+
+- **Skills** — load on demand by name. Lower context cost per query. Best for hosts that natively support skills (Claude Code, Cursor, Qwen Code).
+- **AGENT-GUIDE block** — paste once into your project's `AGENTS.md` / `CLAUDE.md`. Always-on. Best for hosts without skill loading, or when you want one persistent guide for everything.
+
+Do not mix the two — duplicate context confuses tool selection. The static validator (`TestAgentGuideConsistency`) verifies the AGENT-GUIDE copy-paste block does not reference `skills/`.
+
+## Relationship to developer skills
 
-Skills are versioned lockstep with the MCP. When `NodeFilter` keys, `edge_filter` axes, `edge_types`, or `kind` values change, skills are updated in the same PR.
+Developer workflow skills (propose-doc-author, cursor-task-prompt, cursor-pr-review, etc.) live in `.agents/skills/` — they are for contributors working **on** java-codebase-rag. Skills under `skills/` are for **consumers** using java-codebase-rag to explore their own codebases.