From 0967ea2b9f03590898bc9225c6d311dd20ab847d Mon Sep 17 00:00:00 2001 From: Dmitry Teryaev Date: Sun, 24 May 2026 18:12:25 +0300 Subject: [PATCH] =?UTF-8?q?chore:=20refresh=20agent-skills=20propose=20?= =?UTF-8?q?=E2=80=94=20skills/=20at=20project=20root,=20delete=20docs/skil?= =?UTF-8?q?ls/?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rewrite propose doc (revision 5): skills/ at project root instead of agent-skills/ + compile pipeline. No compile step, no multi-host copy. - Move propose from propose/ root to propose/active/ per new folder structure. - Delete docs/skills/ (java-codebase-explore.md, .zip) and scripts/build-explore-skill.sh. - Add hints_structured awareness (principle #10, decision #17). - Collapse 5-PR → 4-PR migration. - Update README, AGENTS.md, test.yml, tests/README, automation README. Co-Authored-By: Claude Opus 4.7 --- .github/workflows/test.yml | 2 +- AGENTS.md | 1 + README.md | 4 +- automation/cursor_propose_only/README.md | 22 +- docs/skills/java-codebase-explore.md | 249 ------------------ docs/skills/java-codebase-explore.zip | Bin 14512 -> 0 bytes .../AGENT-SKILLS-AND-COMMANDS-PROPOSE.md | 191 ++++++-------- scripts/build-explore-skill.sh | 54 ---- tests/README.md | 2 +- 9 files changed, 101 insertions(+), 424 deletions(-) delete mode 100644 docs/skills/java-codebase-explore.md delete mode 100644 docs/skills/java-codebase-explore.zip rename propose/{ => active}/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md (71%) delete mode 100755 scripts/build-explore-skill.sh diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index 5ac1100..c124436 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -23,7 +23,7 @@ jobs: - 'docs/**' - 'propose/**' - 'plans/**' - - 'reports/**' + - 'skills/**' - '.agents/**' - 'AGENTS.md' - 'README.md' diff --git a/AGENTS.md b/AGENTS.md index baa36c7..56ba68a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -42,6 +42,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. - **`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 diff --git a/README.md b/README.md index 57c333c..8762f1d 100644 --- a/README.md +++ b/README.md @@ -98,7 +98,7 @@ See [`mcp.json.example`](./mcp.json.example) for the same shape in `.mcp.json` ( ### Driving the MCP from an agent - **[`docs/AGENT-GUIDE.md`](./docs/AGENT-GUIDE.md)** — standalone MCP operating manual (copy-paste into `QWEN.md` / `CLAUDE.md` / `AGENTS.md`): five tools, `NodeFilter`, edge taxonomy, required `neighbors` arguments, ontology glossary, recovery playbook, slash-style aliases. -- **[`docs/skills/java-codebase-explore.md`](./docs/skills/java-codebase-explore.md)** — exploration **strategy** (missions, fallbacks, anti-capabilities, stopping rules); `AGENT-GUIDE.md` remains the **operating manual** for tool shapes and recovery. +- **[`skills/`](./skills/)** — user-facing navigation and workflow skills for java-codebase-rag consumers. Skills are `SKILL.md` files; agents discover them via slash-names (`/callees`, `/routes`, etc.). See [`propose/active/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](./propose/active/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md) for the full Tier 1 + Tier 2 skill set. - **[`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md)** — 7-phase agent-driven verification you run after indexing your real project. --- @@ -156,7 +156,7 @@ Run `java-codebase-rag --help` to list grouped subcommands. Operator playbook wi | [`docs/CONFIGURATION.md`](./docs/CONFIGURATION.md) | Environment variables, project YAML, graph ontology, brownfield overrides, ignore patterns. | | [`docs/JAVA-CODEBASE-RAG-CLI.md`](./docs/JAVA-CODEBASE-RAG-CLI.md) | CLI operator playbook: workflows, exit codes, env alignment. | | [`docs/EDGE-NAVIGATION.md`](./docs/EDGE-NAVIGATION.md) | MCP-traversable edges, directions, dot-key composition. | -| [`docs/skills/java-codebase-explore.md`](./docs/skills/java-codebase-explore.md) | Agent exploration skill (strategy, missions, fallbacks); packaged zip [`docs/skills/java-codebase-explore.zip`](./docs/skills/java-codebase-explore.zip) for Perplexity-style hosts. | +| [`skills/`](./skills/) | User-facing skills for java-codebase-rag consumers. Navigation and workflow skills (Tier 1 + Tier 2) planned — see [`propose/active/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md`](./propose/active/AGENT-SKILLS-AND-COMMANDS-PROPOSE.md). | | [`docs/MANUAL-VERIFICATION-CHECKLIST.md`](./docs/MANUAL-VERIFICATION-CHECKLIST.md) | 7-phase agent-driven verification after indexing your project. | | [`docs/CODEBASE_REQUIREMENTS.md`](./docs/CODEBASE_REQUIREMENTS.md) | Assumptions about your Java repo + per-file edit map for non-conforming codebases. | | [`automation/cursor_propose_only/README.md`](./automation/cursor_propose_only/README.md) | Optional proposal orchestration workflow (single-command autopilot, planning bundles, automated execution/review loops). | diff --git a/automation/cursor_propose_only/README.md b/automation/cursor_propose_only/README.md index 4483bbc..98e2d61 100644 --- a/automation/cursor_propose_only/README.md +++ b/automation/cursor_propose_only/README.md @@ -21,7 +21,7 @@ If you only want a subset, pass `--proposal` multiple times: .venv/bin/python automation/cursor_propose_only/cli.py prepare \ --repo-root . \ --proposal-dir propose \ - --output-dir reports/propose_automation_selected \ + --output-dir .agents/reports/propose_automation_selected \ --proposal HTTP-ROUTE-METHOD-ENUM-PROPOSE.md \ --proposal ENHANCED-ROLE-RECOGNITION-PROPOSE.md \ --rounds 3 \ @@ -40,18 +40,18 @@ Notes: .venv/bin/python automation/cursor_propose_only/cli.py prepare \ --repo-root . \ --proposal-dir propose \ - --output-dir reports/propose_automation \ + --output-dir .agents/reports/propose_automation \ --rounds 3 \ --min-severity medium ``` Generated artifacts: -- `reports/propose_automation/workflow.json` -- `reports/propose_automation/jobs//planner_prompt.md` -- `reports/propose_automation/jobs//reviewer_prompt_round1.md` -- `reports/propose_automation/jobs//reviewer_prompt_round2.md` -- `reports/propose_automation/jobs//reviewer_prompt_round3.md` +- `.agents/reports/propose_automation/workflow.json` +- `.agents/reports/propose_automation/jobs//planner_prompt.md` +- `.agents/reports/propose_automation/jobs//reviewer_prompt_round1.md` +- `.agents/reports/propose_automation/jobs//reviewer_prompt_round2.md` +- `.agents/reports/propose_automation/jobs//reviewer_prompt_round3.md` ## Evaluate each reviewer response @@ -60,7 +60,7 @@ then evaluate it with severity gating. ```bash .venv/bin/python automation/cursor_propose_only/cli.py evaluate \ - --workflow reports/propose_automation/workflow.json \ + --workflow .agents/reports/propose_automation/workflow.json \ --job-id \ --round 1 \ --review-file /path/to/review_round1.md \ @@ -83,7 +83,7 @@ tasks as `ready_to_merge` / `merged`. ```bash .venv/bin/python automation/cursor_propose_only/execute.py \ --repo-root . \ - --workflow reports/propose_automation/workflow.json \ + --workflow .agents/reports/propose_automation/workflow.json \ --rounds 3 \ --min-severity medium \ --implementation-command 'cursor-agent run --model auto --prompt-file {task_prompt_file}' \ @@ -97,7 +97,7 @@ Notes: - without `--run`, `execute.py` performs a dry-run and only stages prompts/state - command templates support placeholders such as `{task_prompt_file}`, `{review_prompt_file}`, `{pr_url}`, `{branch}`, `{base}`, `{round}` -- workflow state is persisted in `reports/propose_automation/workflow.json` +- workflow state is persisted in `.agents/reports/propose_automation/workflow.json` ## Fully automated (single command) @@ -108,7 +108,7 @@ use `autopilot.py`. .venv/bin/python automation/cursor_propose_only/autopilot.py \ --repo-root . \ --proposal-dir propose \ - --output-dir reports/propose_automation_selected \ + --output-dir .agents/reports/propose_automation_selected \ --proposal TIER2-INCREMENTAL-REBUILD-PROPOSE.md \ --planning-rounds 2 \ --planning-min-severity medium \ diff --git a/docs/skills/java-codebase-explore.md b/docs/skills/java-codebase-explore.md deleted file mode 100644 index 2bab500..0000000 --- a/docs/skills/java-codebase-explore.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -name: java-codebase-explore -title: Explore a Java microservices codebase with the java-codebase-rag MCP -description: | - Use when exploring an unfamiliar Java microservices estate indexed by the - java-codebase-rag MCP. Activates on "explore this codebase", "help me - understand this system", "map the call graph", "plan a change to service", - "onboard onto this code", "write a propose doc for redesign". Teaches - exploration *strategy* — when to call MCP vs fall back to rg/file reads/CLI, - how to read staleness and confidence, and a catalogue of named missions - (understand / plan / onboard / trace / propose / debug) with stopping rules. - Complements but does not require docs/AGENT-GUIDE.md. -when_to_load: - - "explore this codebase / repo / service" - - "help me understand this microservices system" - - "map the call graph for " - - "plan a change to " - - "onboard onto this code" - - "write a propose doc for redesign of " -when_not_to_load: - - routine PR review (use the **`pr-review`** project skill at `.cursor/skills/pr-review/` in this repo, or your own review checklist) - - single-question lookups answerable by one MCP call - - editing existing code where the agent is already oriented ---- - -# java-codebase-explore - -## Activation - -This skill is **`java-codebase-explore`**: use it when the user’s intent matches the activation phrases in the YAML metadata above (explore the estate, understand the system, map call paths, plan a change, onboard, draft a propose, or debug a symptom). It is the **strategy guide** (when to use MCP versus other tools, how to sequence exploration, stopping rules, and anti-capabilities). **[`docs/AGENT-GUIDE.md`](https://github.com/HumanBean17/java-codebase-rag/blob/master/docs/AGENT-GUIDE.md)** remains the **operating manual** for exact JSON argument shapes, recovery moves, and slash-style aliases—open or link it when you need those details; this document does not duplicate them. Cross-links below use **GitHub `blob/master` URLs** (not `../` paths) so they still resolve when this skill is installed from the Perplexity zip without a full repo checkout. - -## Pre-flight: is the index built? - -Before any mission, establish whether the project is indexed and whether graph and vector layers are aligned. - -1. Run **`java-codebase-rag meta`** (with the same `--source-root` / `--index-dir` / env as the operator setup). Parse the JSON payload: ontology version, counts, `edge_counts`, paths, and any `success: false` outcome (see [`docs/JAVA-CODEBASE-RAG-CLI.md`](https://github.com/HumanBean17/java-codebase-rag/blob/master/docs/JAVA-CODEBASE-RAG-CLI.md) for `meta` semantics and exit codes). -2. **Unindexed or missing graph:** if there is no usable index or `meta` indicates failure, do not pretend the MCP can see the repo. Stop MCP-driven missions until **`java-codebase-rag init`** (or **`reprocess`** where appropriate) has been run per the CLI guide; meanwhile use **`rg`**, README, and build files to orient. -3. **Lance vs Kuzu after `increment`:** **`increment`** refreshes the CocoIndex / Lance side **without** rebuilding Kuzu. Expect **stale graph navigation** until **`reprocess`** (full Lance reprocess + full Kuzu rebuild). Treat `meta` (and last `reprocess` / provenance fields there) as the source of truth for how fresh the graph is; if graph and source disagree, prefer the **open file** and report staleness. - -## Map the seams first - -On any new estate, **enumerate before you search-hunt**: - -1. **`find(kind="route", …)`** — list HTTP seams (paths, methods, microservices). -2. **`find(kind="client", …)`** — list outbound clients (Feign, `RestTemplate`, Kafka, etc.) and targets. -3. Optionally **`find(kind="symbol", filter={"role":"CONTROLLER"})`** (or equivalent `NodeFilter`) to anchor web entrypoints. - -**Identifier-shaped** strings (FQN, `sym:` / `route:` / `client:` id, route path, client target): start with **`resolve`**, then **`describe(id=…)`**. Use **`search`** / **`find`** for discovery when you do not have a concrete identifier yet — not as the primary chain for identifier disambiguation. - -You cannot reason reliably about cross-service behaviour until these surfaces exist in your working mental model (or you have consciously fallen back to non-MCP discovery). - -## Mission catalogue - -### Mission: Understand a feature - -**When it applies:** The user asks how a feature, flow, or implementation detail works (for example “how does X work?” or “explain Y in service Z”). - -**Goal:** A coherent story: entrypoints (routes/controllers), core symbols, and principal callees/callers, with explicit gaps where the graph is silent. - -**Opening move:** `java-codebase-rag meta` if not yet done this session, then **`search`** with a tight query **or** `find` when you already know a symbol/route id. - -**Sequence:** - -1. From `search` hits or `find`, pick the best anchor id; **`describe(id)`** for full node + `edge_summary`. -2. Walk **one hop at a time** with **`neighbors`**: e.g. outbound `CALLS` / `EXPOSES` / cross-service `HTTP_CALLS` / `ASYNC_CALLS` as the question requires; inbound `CALLS` / `INJECTS` to see who drives a method. -3. If the feature spans services, pivot through **`find(kind="client", …)`** and matching routes on the callee side rather than deep blind `search` loops. - -**Stopping rule:** You can name the main controller/handler, the core service methods, and the outbound/inbound seams relevant to the question; you have called out anything unresolved (dynamic dispatch, unindexed paths) per anti-capabilities. - -**Fallbacks:** If `search` is empty or vague, use **`rg`** on distinctive strings, read files directly, then return to `find`/`describe` with ids you discovered. - -### Mission: Plan a change - -**When it applies:** The user will modify code and needs blast radius, touched routes, or dependency direction (for example renames, API changes, or refactors). - -**Goal:** Bounded sets: callers, callees, injected collaborators, exposed routes, and cross-service consumers/producers touched by the change. - -**Opening move:** **`find(kind="symbol", …)`** to resolve the target symbol **or** `search` if the qualified name is unknown—then **`describe`**. - -**Sequence:** - -1. **`neighbors(direction="in", edge_types=["CALLS","INJECTS",…])`** from the target method(s); repeat one hop at a time until diminishing returns. -2. For API or route changes: **`find(kind="route", filter={…})`** on the owning microservice; **`neighbors`** with `EXPOSES` / `HTTP_CALLS` / `ASYNC_CALLS` as needed. -3. For PR-shaped work, use **`java-codebase-rag analyze-pr`** (CLI only) with a diff when the user has a branch or patch—see [`docs/JAVA-CODEBASE-RAG-CLI.md`](https://github.com/HumanBean17/java-codebase-rag/blob/master/docs/JAVA-CODEBASE-RAG-CLI.md). - -**Stopping rule:** You can list concrete symbols/routes/clients at risk and say what is **not** knowable from static graph alone (reflection, unindexed services). - -**Fallbacks:** **`rg`** for string literals and annotations; **`git log` / `git blame`** for ownership and recency; README / `pom.xml` / `build.gradle` for module boundaries. - -### Mission: Onboard onto an unfamiliar service - -**When it applies:** The user is new to a service and wants orientation (for example “I’m new to billing-service; orient me.”). - -**Goal:** A map of that service’s **outward HTTP API**, **inbound dependencies** (other services calling it), and **outbound clients** it uses to call others. - -**Opening move:** **`find(kind="route", filter={"microservice":""})`** then **`find(kind="client", filter={"microservice":""})`** (adjust filter keys to match live `NodeFilter` / tool schema in the MCP client). - -**Sequence:** - -1. Cluster routes by path prefix; **`describe`** on representative `route:` ids. -2. For each major route, **`neighbors(direction="in", edge_types=["EXPOSES"])`** to land on handler symbols; for inbound **`HTTP_CALLS`**, expect **Client** callers (then **`DECLARES_CLIENT` inbound** to the declaring method); for inbound **`ASYNC_CALLS`**, expect **Producer** callers (then **`DECLARES_PRODUCER` inbound** to the declaring method). -3. Use **`find(kind="client", …)`** and **`find(kind="producer", …)`** with the same microservice filter to list outbound integration points; follow outbound **`HTTP_CALLS`** from each Client and **`ASYNC_CALLS`** from each Producer. - -**Stopping rule:** You can summarize how traffic enters the service, what modules/controllers own key paths, and what external systems it calls—**without** claiming tests, runtime config, or unindexed siblings exist in MCP. - -**Fallbacks:** If the service **does not appear** in `meta` / `find`, assume **unindexed or wrong root**—verify with `meta`, then **`rg`** + README + adjacent services’ `find` results; do not assert absence from an empty MCP result alone. - -### Mission: Trace a cross-service flow - -**When it applies:** The user asks what happens when a route is invoked or how control moves from an entrypoint to clients/async boundaries (for example “POST /orders …” or “from controller A to client B”). - -**Goal:** A directed chain (or tree) of nodes linked by **`EXPOSES`**, **`CALLS`**, and resolver-backed **`HTTP_CALLS` / `ASYNC_CALLS`**, with explicit notes on confidence and dead ends. - -**Opening move:** **`find(kind="route", filter={path/http_method/microservice…})`** to resolve the `route:` id. - -**Sequence:** - -1. **`neighbors(direction="in", edge_types=["EXPOSES"])`** onto the handling symbol; walk **`CALLS`** outbound method-by-method. -2. When a method makes outbound HTTP, **`neighbors(..., out, ["DECLARES_CLIENT"])`** then outbound **`HTTP_CALLS`** from each Client id; for async, **`neighbors(..., out, ["DECLARES_PRODUCER"])`** then outbound **`ASYNC_CALLS`** from each Producer id. -3. Stop at leaves, framework boundaries, or unresolved edges; read **`edge.attrs`** (`attrs.confidence`, `attrs.strategy`, `attrs.match`) and report low-confidence segments as resolver gaps, not as facts. - -**Stopping rule:** You reach a stable leaf (external IO, message publish, clear terminal layer) **or** you document every unresolved hop with a concrete next non-MCP check. - -**Fallbacks:** **`rg`** for string-built URLs; **`git log`** on suspect handlers; runtime logs are out of MCP scope—say so. - -### Mission: Prepare to write a propose doc - -**When it applies:** The user is about to author a design/propose document and needs scoped evidence from the codebase (for example a cross-cutting redesign). - -**Goal:** An evidence inventory: affected routes/clients/symbols, dependency direction, and known unknowns suitable for a propose’s “scope / risks / alternatives” sections. - -**Opening move:** **`java-codebase-rag meta`**, then **`find(kind="client", …)`** or **`find(kind="route", …)`** scoped to the hypothesis (e.g. all `feign_method` clients if replacing Feign). - -**Sequence:** - -1. Enumerate candidates with **`find`**; **`describe`** representatives. -2. Use **`neighbors`** to measure **fan-in / fan-out** and cross-service edges. -3. Capture **staleness** (`increment` vs `reprocess`) and **confidence** (`attrs.*`) limitations explicitly for the propose’s risk section. - -**Stopping rule:** You have a bullet list of graph-backed facts vs gaps, enough that a propose author can write without further blind exploration. - -**Fallbacks:** Repo **`propose/`** and **`plans/`** examples via file reads; **`java-codebase-rag analyze-pr`** when there is an existing diff to ground scope. - -### Mission: Debug a specific symptom - -**When it applies:** The user has a symptom (error string, latency on a path, unexpected behaviour) and wants likely code loci. - -**Goal:** Short ranked hypotheses tied to symbols/routes, each with a suggested verification step (read file, log line, metric, or reindex). - -**Opening move:** If tied to an HTTP path, **`find(kind="route", …)`** for that path/method/service; otherwise **`search`** on distinctive error tokens **then** `describe`/`neighbors`. - -**Sequence:** - -1. From the route/handler, **`neighbors`** for **`HTTP_CALLS`**, **`ASYNC_CALLS`**, **`CALLS`** as the symptom suggests (sync slowness vs fan-out vs messaging). -2. Read **`edge.attrs.confidence`** / **`attrs.strategy`** / **`attrs.match`** on cross-service edges before blaming a downstream. -3. **`git log` / `git blame`** on the hot handler or client when the graph looks stale or incomplete. - -**Stopping rule:** You can point to a small set of files/methods worth inspecting and you have separated **MCP-backed** claims from **speculation**. - -**Fallbacks:** **`rg`** across logs strings and config; read **`application*.yml`**, feature flags, and build/CI files; **`java-codebase-rag`** CLI help for commands (`analyze-pr`, `diagnose-ignore`) when the question is operational—see CLI doc, not MCP tools. - -## When MCP is the wrong layer - -Use non-MCP work **first-class**, not as a last resort: - -| Layer | Rule of thumb | -| ----- | ------------- | -| **`rg` / grep** | Fastest for exact strings, stack traces, config keys, test code (**tests are not indexed**). | -| **File reads** | Single-file truth for logic the graph has not ingested or when **`increment`** left Kuzu stale. | -| **`git log` / `git blame`** | History, ownership, “when did this regress”—never MCP. | -| **README, `pom.xml`, `build.gradle`, Docker, workflows** | Build/run/deploy and module structure—never MCP. | -| **`java-codebase-rag` CLI** | Lifecycle (`init` / `increment` / `reprocess`), **`meta`**, **`tables`**, **`analyze-pr`**, **`diagnose-ignore`**—per [`docs/JAVA-CODEBASE-RAG-CLI.md`](https://github.com/HumanBean17/java-codebase-rag/blob/master/docs/JAVA-CODEBASE-RAG-CLI.md). | - -If answering the question would require runtime truth (live traffic, actual DB rows, dynamic classpath), say so and stop relying on MCP. - -## What this MCP cannot see, cannot do, and cannot guarantee - -If you find yourself surprised by an empty result, a missing edge, or a stale -fact, read this section first. The MCP is a static graph + vector index over -indexed Java production code. The following are out of frame: - -- **Test files.** Not indexed. Use `rg` for test discovery. -- **Build, deploy, runtime story.** Not indexed. Read `README.md`, `pom.xml`, - `build.gradle`, `Dockerfile`, `docker-compose.yml`, `.github/workflows/`. -- **When something changed.** Use `git log` / `git blame`. -- **Reflection and dynamic dispatch.** `CALLS` edges resolve static method - calls; reflective invocations, SPI lookups, and dynamic proxies are - invisible. Treat the resolved caller set as a lower bound, not a complete - set. -- **Unindexed services.** A service that was never `init`'d does not exist - from MCP's point of view. Verify with `java-codebase-rag meta` before - claiming absence. -- **Cross-service edge completeness.** `HTTP_CALLS` / `ASYNC_CALLS` depend on - the resolver matching a client invocation to a route. Low `confidence` in - `edge.attrs` (`attrs.confidence`, `attrs.strategy`, `attrs.match`) is a resolver gap signal, not a hallucination. Report it - as such. -- **Stale graph after `increment`.** `increment` updates Lance but not Kuzu. - A graph older than the source tree is normal mid-development. Check the - last `reprocess` time via `meta`; when in doubt, the open file wins. - -When MCP and the open file disagree, **the file wins.** Report the -disagreement as evidence of staleness, not as a contradiction. - -## Confidence and staleness - -- **Wire fields:** Cross-service and resolver-heavy edges carry **`edge.attrs`** (same map surfaced as `attrs` in payloads). Treat **`attrs.confidence`**, **`attrs.strategy`**, and **`attrs.match`** as structured hints: low confidence means “resolver could not pin this cleanly,” not “definitely false.” -- **MCP vs editor:** If the open buffer contradicts graph edges (deleted method, renamed class), **trust the file** and treat MCP as stale until **`reprocess`** (or at least acknowledge incremental lag after **`increment`**). -- **Operational check:** Use **`java-codebase-rag meta`** to compare index health, ontology version (currently **14** in this repo’s README), and recency signals—then decide whether to re-run **`reprocess`** before continuing a mission. - -## Anti-patterns - -1. **Fishing with `search`.** Repeated broad `search` without `find`/`describe` anchors burns context and hides the real seam structure. -2. **Unbounded graph walks.** Hopping `neighbors` without a stopping rule; you must terminate with a stated evidence bar from the mission template. -3. **Empty result = proof of absence.** Could be unindexed, wrong table, stale Kuzu, or not in Java production scope—verify per **What this MCP cannot see** before claiming “does not exist.” -4. **Ignoring `attrs.confidence` / `attrs.strategy` / `attrs.match`.** Especially on **`HTTP_CALLS` / `ASYNC_CALLS`**, low confidence is a **gap signal**, not noise to omit from the answer. -5. **Using MCP for CLI-only or repo-meta questions.** `analyze-pr` shape, exit codes, ignore diagnostics → **CLI doc + `--help`**, not `search`. -6. **Treating the graph as runtime telemetry.** Throughput, live queues, and prod-only config are out of scope—say so and switch tools. -7. **Over-trusting post-`increment` navigation.** If users ran **`increment`** without **`reprocess`**, expect **stale Kuzu**; prefer **`meta`**, file reads, or queue **`reprocess`** before high-stakes conclusions. -8. **Asking the user for JSON shapes** that already ship in MCP tool descriptions and **[`docs/AGENT-GUIDE.md`](https://github.com/HumanBean17/java-codebase-rag/blob/master/docs/AGENT-GUIDE.md)**—read those surfaces instead of inventing parameters. - -## Cheat sheet (inline reference) - -Five MCP tools: - -- `resolve(identifier, hint_kind)` — identifier-shaped lookup (`one` / `many` / `none`). -- `search(query, table, hybrid, limit, filter)` — fuzzy locate. -- `find(kind, filter, limit)` — structured listing; `filter` is required. -- `describe(id)` — full node + `edge_summary`. -- `neighbors(ids, direction, edge_types, limit, offset, filter)` — one hop; - `direction` and `edge_types` are required. - -*Shorthand:* MCP calls are always **named JSON** arguments per the live tool schema, not positional Python. The lines above are mnemonic; for pagination and optional filters, match the tool surface (e.g. `neighbors` exposes `limit`, then `offset`, then optional `filter`). - -Three node kinds: `symbol`, `route`, `client`. Ids carry a prefix -(`sym:`, `route:` / `r:`, `client:` / `c:`). - -Ten edge types: - -| Group | Edges | -| ----- | ----- | -| Type wiring | `EXTENDS`, `IMPLEMENTS`, `INJECTS` | -| Containment | `DECLARES`, `DECLARES_CLIENT`, `DECLARES_PRODUCER` | -| Method overrides | `OVERRIDES` | -| Method calls | `CALLS` | -| Service boundary | `EXPOSES` | -| Cross-service | `HTTP_CALLS` (Client→Route), `ASYNC_CALLS` (Producer→Route) | - -For exact argument shapes, recovery playbook, and slash aliases see -[`docs/AGENT-GUIDE.md`](https://github.com/HumanBean17/java-codebase-rag/blob/master/docs/AGENT-GUIDE.md) in the java-codebase-rag repo. diff --git a/docs/skills/java-codebase-explore.zip b/docs/skills/java-codebase-explore.zip deleted file mode 100644 index 2ff7e75ace4c28595ffa0391ee4f09cf94c816ec..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 14512 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 UA}ZQ{BS`/SKILL.md` (Claude Code), `.qwen/skills//SKILL.md` (Qwen Code), and **`.cursor/skills//SKILL.md`** (Cursor — same format as the other hosts). **Same SKILL.md body on every host** (YAML frontmatter + markdown body); only the install path differs. +- Ship skills as `skills//SKILL.md` at the **project root**. All hosts read from this single directory. No compile step, no multi-host copy pipeline. Developer workflow skills (propose, pr-review, etc.) remain in `.agents/skills/` — `skills/` is for **consumer-facing** navigation and workflow skills only. - Tier 1 (high-leverage, low cost): 10 navigation skills covering the 10 most common query patterns from the existing `AGENT-GUIDE.md` slash-style alias section — **graph-accurate one-hop chains**, identifier resolution via **`resolve`**. - Tier 2 (polish): 4 **bounded workflow** skills (`/explain-feature`, `/impact-of`, `/trace-request-flow`, `/mini-map`) — explicit depth/stop rules; `/mini-map` composes optional MCP `edge_filter` on `CALLS` with skill-layer accessor/semantic labeling (not a strict chain). - Tier 3 (deferred): `java-codebase-rag dump-*` CLI helpers — out of scope here. -- Migration is **5 PRs**: (1) propose lock, (2) shared `agent-skills/` source + compile script, (3) Tier 1 skills, (4) Tier 2 workflow skills, (5) AGENT-GUIDE rewrite to point at the shipped skills instead of duplicating prose templates. +- Migration is **4 PRs**: (1) propose lock, (2) `skills/` directory + Tier 1 skills, (3) Tier 2 workflow skills, (4) AGENT-GUIDE rewrite to point at the shipped skills instead of duplicating prose templates. ## §1 Frame: what is this thing, really? @@ -26,20 +26,20 @@ This frame rules things out: - **Skills are not a second MCP.** They contain no new graph queries, no new vector backends, no new edge types. Every Tier 1 skill is a **deterministic** chain of existing MCP calls; Tier 2 skills add **bounded** recursion and (for `/mini-map` only) heuristic post-processing on top of those calls. - **Skills are not CLI subcommands.** The `java-codebase-rag` CLI is for ops (`init` / `increment` / `reprocess` / `meta` / `tables` / `diagnose-ignore` / `analyze-pr`). Adding `java-codebase-rag list-routes` would give the same query three homes (MCP + skill + CLI) — pick one. - **Skills are not the AGENT-GUIDE.** The guide is reference doc that the agent reads once. Skills are *invokable* — the user types `/callees ChatController#joinOperator(JoinOperatorRequest)` and the model executes a known chain. Same intents, different actuation. -- **Skills are not the exploration strategy skill.** [`docs/skills/java-codebase-explore.md`](../docs/skills/java-codebase-explore.md) teaches *when and why* to explore (missions, fallbacks, anti-capabilities). Navigation skills here teach *exact MCP chains* for frequent intents. See §4b. - **Skills are not free.** Each one is recurring tokens in the agent's context once invoked, plus maintenance cost when the MCP surface evolves. The set must be small and earn its place. ## §2 Design principles -1. **Single source of truth.** One markdown file per skill in `agent-skills//SKILL.md`. Build step copies to `.claude/skills/`, `.qwen/skills/`, and `.cursor/skills/`. No drift between hosts. -2. **Identical format across Claude Code, Qwen Code, and Cursor.** All three accept `SKILL.md` with YAML frontmatter (`name` + `description`) and a markdown body. Verified May 2026 for Claude/Qwen — see Appendix A; Cursor already ships project skills under `.cursor/skills/` in this repo. +1. **Single source of truth.** One markdown file per skill in `skills//SKILL.md` at the project root. No compile step — all hosts read from `skills/` directly. +2. **Identical SKILL.md format across Claude Code, Qwen Code, and Cursor.** All three accept `SKILL.md` with YAML frontmatter (`name` + `description`) and a markdown body. Verified May 2026 for Claude/Qwen — see Appendix A. Developer workflow skills (`propose`, `pr-review`, etc.) live separately in `.agents/skills/`. 3. **Tier 1 = deterministic MCP chains.** No prose like "consider running `find` if appropriate" — the body must say exactly which calls to make and in what order. **Tier 2 = bounded workflows** with explicit recursion depth, stop conditions, and (for `/mini-map` only) documented heuristic filtering — not fully deterministic output. 4. **Skills wrap MCP, never replace it.** A skill body always names the underlying MCP tools used. This keeps the agent able to drop into raw MCP if the skill doesn't fit. -5. **Slash-name = skill-name = filename.** `/callees` ↔ `agent-skills/callees/SKILL.md`. No alias indirection. (Hosts derive the slash-name from the directory name.) +5. **Slash-name = skill-name = filename.** `/callees` ↔ `skills/callees/SKILL.md`. No alias indirection. (Hosts derive the slash-name from the directory name.) 6. **Identifier-shaped arguments → `resolve` first.** Each skill's body specifies positional arguments and calls `resolve(identifier=…)` (optional `hint_kind`) when the input is not already a `sym:` / `route:` / `client:` / `producer:` id. Use `find` only for structured listing (`/controllers`, `/routes`, …), not for FQN disambiguation. 7. **Graph-accurate edge sets.** One-hop `neighbors` must respect `EDGE_SCHEMA` endpoint types (see `docs/EDGE-NAVIGATION.md`). Do not pass `HTTP_CALLS` or `ASYNC_CALLS` on a bare method `sym:` id — those edges are **Client→Route** and **Producer→Route**; reach them via `DECLARES_CLIENT` / `DECLARES_PRODUCER` (or composed dot-keys) from the declaring method. 8. **Skills are versioned with the MCP, not separately.** When `NodeFilter` keys, `edge_filter` axes, `edge_types`, or `kind` values change, skills get updated in the same PR. Lockstep with `AGENT-GUIDE.md` and `README.md`. 9. **No skill ships without a working example.** Every SKILL.md ends with a worked example using the bank-chat-system fixture, so a maintainer can verify the chain still works after MCP changes. +10. **Skills compose with `hints_structured`.** MCP responses now include `hints_structured` — machine-parseable suggested next-tool calls with `tool`, `args`, `actionable`, `label`, and `reason` fields. Skills define the *intent-to-chain* mapping; `hints_structured` provides runtime *step-to-step* guidance within a chain. Skills should not duplicate what `hints_structured` already provides. ## §3 The three layers @@ -51,10 +51,9 @@ This diagram lives at the top of the resulting README and is the canonical menta │ /trace-request-flow, /callees, /controllers, /routes, │ │ /impact-of, /mini-map │ │ ───────────────────────────────────────────────────────── │ -│ Implementation: skills shipped as SKILL.md files in │ -│ .claude/skills/, .qwen/skills/, .cursor/skills/ (same │ -│ source). Tier 1 = deterministic MCP chains; Tier 2 adds │ -│ bounded recursion + light post-processing (/mini-map). │ +│ Implementation: SKILL.md files in skills/ at project root. │ +│ Tier 1 = deterministic MCP chains; Tier 2 adds bounded │ +│ recursion + light post-processing (/mini-map). │ ├──────────────────────────────────────────────────────────────┤ │ Layer 2 — Composable primitives (the MCP API) │ │ search, find, describe, neighbors, resolve │ @@ -68,10 +67,10 @@ This diagram lives at the top of the resulting README and is the canonical menta **Why Layer 3 is the right home for `/list_routes` and friends:** -- It's per-host (Claude Code, Qwen Code, Cursor) — compile targets share one source; host-specific tuning stays in skill `description` trigger words only. +- It's host-agnostic — one directory, no compile step, no host-specific tuning. - It doesn't pollute the MCP surface — the 5-tool count stays load-bearing for tool-selection on weak models. - It doesn't duplicate the CLI's audience — CLI is ops; skills are queries. -- It compiles from one source, so all hosts stay in sync without N× edits. +- It's a single `skills/` directory — no N× edits to keep hosts in sync. ## §4 Audit by call site (who actually invokes these?) @@ -88,17 +87,16 @@ Before deciding to ship a skill at all, list realistic callers. If the dominant Result: **14 skills total** — 10 Tier 1 + 4 Tier 2. No CLI work in this proposal. -## §4b Relationship to `java-codebase-explore` and existing Cursor skills +## §4b Relationship to existing developer skills -This repo already ships two adjacent agent artefacts — this propose must not fork a third parallel ontology copy. +This repo ships developer workflow skills in `.agents/skills/` (propose, pr-review, plan-prompts, etc.) — those are for contributors working **on** java-codebase-rag. Navigation skills in `skills/` are for **consumers** using java-codebase-rag to explore their own codebases. The two directories must not be confused. | Artefact | Role | Relationship to Layer 3 navigation skills | |---|---|---| -| [`docs/skills/java-codebase-explore.md`](../docs/skills/java-codebase-explore.md) | **Strategy guide** — missions, pre-flight `meta`, when MCP is the wrong layer, confidence/staleness, anti-capabilities | **Complements** navigation skills. Exploration skill links to AGENT-GUIDE for argument shapes; navigation skills link back to exploration skill for "understand this system" sessions. No duplicate cheat-sheet tables — exploration skill keeps strategy/mission content; navigation skills name exact MCP chains only. | -| [`docs/AGENT-GUIDE.md`](../docs/AGENT-GUIDE.md) | **Operating manual** — decision tree, recovery, edge taxonomy, `resolve` flow | PR-S-5 turns slash-alias bullets into pointers to `agent-skills/`; decision tree and taxonomy **stay** in AGENT-GUIDE. | -| [`.cursor/skills/`](../.cursor/skills/) (`propose`, `pr-review`, `plan-prompts`, …) | **Repo workflow skills** (Cursor-native) | Same `SKILL.md` format. `compile.py` emits **`.cursor/skills//SKILL.md`** alongside Claude/Qwen outputs so MCP navigation skills are slash-invokable in Cursor without maintaining a separate prose path. | +| [`.agents/skills/`](../../.agents/skills/) (`propose`, `pr-review`, `plan-prompts`, …) | **Repo workflow skills** for contributors | Same `SKILL.md` format, different audience. Navigation skills do **not** compile into `.agents/skills/`. | +| [`docs/AGENT-GUIDE.md`](../../docs/AGENT-GUIDE.md) | **Operating manual** — decision tree, recovery, edge taxonomy, `resolve` flow | PR-S-4 turns slash-alias bullets into pointers to `skills/`; decision tree and taxonomy **stay** in AGENT-GUIDE. | -**Activation split:** use `java-codebase-explore` when the user is orienting on an unfamiliar estate; use `/routes`, `/callees`, etc. when the intent is a single structural question with a known chain. +**Activation split:** use navigation skills (`/routes`, `/callees`, etc.) when the intent is a single structural question with a known chain; use AGENT-GUIDE when the agent needs to reason about *which* tools to call. ## §5 The proposed skill set @@ -140,7 +138,7 @@ Multi-step intents that compose Tier 1 with explicit bounds. Bodies must specify #### `/mini-map` — detailed design -**Motivation.** [#177](https://github.com/HumanBean17/java-codebase-rag/issues/177) documented CALLS-edge noise on service methods. **Server-side remediation landed** ([`CALLS-NOISE-AND-RESOLUTION`](completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md)): true receiver-failure sites moved off `CALLS`, `callee_declaring_role` is on the edge, and `neighbors` supports `edge_filter`, source ordering, `dedup_calls`, and `include_unresolved`. Default `neighbors(out, ["CALLS"])` on a high-fanout method (pinned fixture: `ClientMessageProcessor#process`) is **~49 rows** after re-index (was **57** pre–PR-3) — still dominated by entity accessors and known-external JDK rows that stereotype filters alone cannot label (`DELEGATES` / `PERSISTS` / `READS`). `/mini-map` is the **skill-layer** remedy for that remainder (Decision 39 in CALLS-NOISE): compose MCP projection first, then accessor/semantic heuristics, return a 10–20 line skeleton. +**Motivation.** [#177](https://github.com/HumanBean17/java-codebase-rag/issues/177) documented CALLS-edge noise on service methods. **Server-side remediation landed** ([`CALLS-NOISE-AND-RESOLUTION`](../completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md)): true receiver-failure sites moved off `CALLS`, `callee_declaring_role` is on the edge, and `neighbors` supports `edge_filter`, source ordering, `dedup_calls`, and `include_unresolved`. Default `neighbors(out, ["CALLS"])` on a high-fanout method (pinned fixture: `ClientMessageProcessor#process`) is **~49 rows** after re-index (was **57** pre–PR-3) — still dominated by entity accessors and known-external JDK rows that stereotype filters alone cannot label (`DELEGATES` / `PERSISTS` / `READS`). `/mini-map` is the **skill-layer** remedy for that remainder (Decision 39 in CALLS-NOISE): compose MCP projection first, then accessor/semantic heuristics, return a 10–20 line skeleton. **Designed for subagent invocation (preferred).** The subagent runs the MCP + heuristic pipeline per hop in its own context and returns a compact map. The main agent drills in with file reads. **Graceful degradation:** on hosts without subagents (or tight context budgets), run in the main agent with **`depth` default 1** and cap total raw edges examined; if the map has fewer than 3 signal lines after filtering, fall back to raw `/callees` (optionally with `edge_filter`) and note that stereotype roles may be `OTHER`. @@ -201,13 +199,13 @@ The `[filtered …]` line is transparency — offer raw `/callees` or `neighbors Out of scope. If the user later wants `java-codebase-rag dump-routes` for scripting, that's a separate proposal. Frame: "graph debug helper for CI/scripts," not "list_routes for users." -## §6 Layout and build +## §6 Layout ### Source layout ``` java-codebase-rag/ ← repo root (not a package prefix) - agent-skills/ ← source of truth + skills/ ← user-facing skills (Layer 3) callees/ SKILL.md callers/ @@ -223,8 +221,12 @@ java-codebase-rag/ ← repo root (not a package prefix) SKILL.md trace-request-flow/ SKILL.md - README.md ← layout, layer diagram, compile, host precedence probe - compile.py ← copies to .claude / .qwen / .cursor skills dirs + README.md ← layout, layer diagram, skill index + .agents/ ← developer workflow skills (NOT for consumers) + skills/ + propose/SKILL.md + pr-review/SKILL.md + ... ``` ### SKILL.md template (verified compatible with Claude Code, Qwen Code, and Cursor) @@ -271,27 +273,17 @@ You: → resolve(identifier="ChatController#joinOperator", hint_kind="symbol") - Filtering by microservice (compose with `/controllers` if needed). ``` -### Compile step +### Where skills live -`agent-skills/compile.py` reads `agent-skills/*/SKILL.md` and writes (copy mode; symlink mode optional in PR-S-3): +All hosts read from the same `skills/` directory at the project root. No per-host copies, no compile step. -- `.claude/skills//SKILL.md` -- `.qwen/skills//SKILL.md` -- `.cursor/skills//SKILL.md` - -Each output is prefixed with `# AUTOGENERATED — edit agent-skills//SKILL.md and run java-codebase-rag compile-skills`. Compile is idempotent. Invoked via **`java-codebase-rag compile-skills`** (new CLI subcommand) or `make skills` (deferred to plan). - -**Git policy:** source under `agent-skills/` is canonical; compiled host dirs are **checked in** for zero-setup clones, with CI verifying banner + hash match. Teams that prefer source-only git may switch in the plan — default here is checked-in outputs for Claude/Qwen/Cursor parity with existing `.cursor/skills/` practice. - -### Where they install for users - -| Host | Project-scoped | User-scoped | -|---|---|---| -| Claude Code | `.claude/skills//SKILL.md` | `~/.claude/skills//SKILL.md` | -| Qwen Code | `.qwen/skills//SKILL.md` | `~/.qwen/skills//SKILL.md` | -| Cursor | `.cursor/skills//SKILL.md` | (user rules / global skills — out of scope; copy manually if needed) | +| Host | Skill location | +|---|---| +| Claude Code | `skills//SKILL.md` (project root) | +| Qwen Code | `skills//SKILL.md` (project root) | +| Cursor | `skills//SKILL.md` (project root) | -This proposal ships **project-scoped** skills checked into the repo. +Developer workflow skills (propose, pr-review, etc.) live in `.agents/skills/` — a separate directory for repo contributors, not consumers. ## §7 Use-case re-walk @@ -327,17 +319,16 @@ UC15 deliberately has no skill. UC16 is the canonical mini-map case (pinned in C | Add skills for every possible filter combination | Long tail belongs in raw MCP. Skills are for high-frequency intents only. | | Per-user customization of skill chains | Out of scope — ship one canonical chain per skill. Users can override at host user-scope dirs. | | Skill versioning independent of MCP | Skills track MCP. Lockstep updates only. | -| Duplicate `java-codebase-explore` content | Strategy stays in `docs/skills/java-codebase-explore.md`; navigation chains stay in `agent-skills/`. | +| Compile step or multi-host copy pipeline | Single `skills/` directory at project root. All hosts read from it directly. | | `/git-blame`, `/who-changed-this` | Requires VCS data not yet in the ontology. Out of scope until that's modeled. | -| Extra compile hosts (VS Code, Continue) | Three hosts (Claude, Qwen, Cursor) match current repo practice. Add hosts when there is a fourth real consumer. | | Skills that reach into the CLI | Skills run at the agent layer; the agent calls MCP. CLI is for humans. Don't cross the streams. | | One-hop `HTTP_CALLS` / `ASYNC_CALLS` on bare `sym:` ids | Graph endpoints are Client→Route and Producer→Route; use `/who-hits-route` on routes or DECLARES_* chains from methods (decision #13). | | `/callers-direct` / `/callees-direct` as separate shipped skills | `/callers` and `/callees` **are** CALLS-only on method symbols (matches AGENT-GUIDE). Transport-wide "who hits this route" is `/who-hits-route`. Optional HTTP/async steps live in `/callees` step 3 and `/trace-request-flow`. | -| Re-implement CALLS-NOISE in skill prose only | `edge_filter`, phantom/chained removal, and `callee_declaring_role` **landed** ([`CALLS-NOISE-AND-RESOLUTION`](completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md)). `/mini-map` **composes** MCP filters; skill heuristics cover accessor noise and semantic labels only (Decision 39). | +| Re-implement CALLS-NOISE in skill prose only | `edge_filter`, phantom/chained removal, and `callee_declaring_role` **landed** ([`CALLS-NOISE-AND-RESOLUTION`](../completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md)). `/mini-map` **composes** MCP filters; skill heuristics cover accessor noise and semantic labels only (Decision 39). | | Port `/mini-map` classification into the indexer | Intentional skill-layer split; server closes stereotype + receiver-failure buckets. | | `include_unresolved=True` together with `edge_filter` on the same `neighbors` call | MCP fail-loud mutual exclusivity (CALLS-NOISE Decision 25); skill must pick one mode per hop. | -## §9 Migration plan — 5 PRs +## §9 Migration plan — 4 PRs ### PR-S-1 — Lock the propose @@ -345,76 +336,63 @@ Open this propose as a draft PR. Iterate. When merged, status flips to `locked` **Test summary**: N/A. -### PR-S-2 — Shared `agent-skills/` source + compile script - -Add `agent-skills/` with `README.md` (architecture + Layer-3 diagram + compile + host precedence probe), a **minimal-working `compile.py`** (≤ 100 lines: walk `agent-skills/*/SKILL.md`, write to `.claude/skills/`, `.qwen/skills/`, and `.cursor/skills/` with the `# AUTOGENERATED` banner; copy mode only — symlink mode lands in PR-S-3 if needed), and the **`java-codebase-rag compile-skills`** CLI subcommand. Skip SKILL.md bodies — those land in PR-S-3/4. - -The compile script must be functional from this PR onwards (not stubbed). **No `NotImplementedError` placeholders.** +### PR-S-2 — `skills/` directory + Tier 1 navigation skills (10 skills) -**Acceptance criterion (manual, both Claude Code and Qwen Code):** project-scoped install takes precedence over user-scoped when names collide. Document procedure and **record results for each host** in `agent-skills/README.md` and the PR description. +Add `skills/` directory with `README.md` (architecture + Layer-3 diagram + skill index). Add `skills//SKILL.md` for each Tier 1 entry. Each SKILL.md includes worked example + graph-accurate chains from §5. -**Test summary**: 3 tests — (1) idempotent on empty source dir, (2) copies one fixture skill to all three output trees with banner, (3) `java-codebase-rag compile-skills` invokes the same code path. - -### PR-S-3 — Tier 1 navigation skills (10 skills) - -Add `agent-skills//SKILL.md` for each Tier 1 entry. Run compile. Commit `.claude/skills/`, `.qwen/skills/`, and `.cursor/skills/` outputs. Each SKILL.md includes worked example + graph-accurate chains from §5. - -**Test summary**: 10 frontmatter tests + 1 compile integration test + **1 static MCP-call validator** (`tests/test_agent_skills_static.py`, ~80 lines) that imports allowlists from code — not hand-maintained lists: +**Test summary**: 10 frontmatter tests + **1 static MCP-call validator** (`tests/test_agent_skills_static.py`, ~80 lines) that imports allowlists from code — not hand-maintained lists: - **Tools:** `search`, `find`, `describe`, `neighbors`, `resolve` (same set as `server.py` navigation tools). - **`find` `kind`:** `symbol`, `route`, `client`, `producer` — from `mcp_v2` / `NodeKind` (see `_NODEFILTER_APPLICABLE_FIELDS` keys). - **`direction`:** `in`, `out`. - **`edge_types`:** `mcp_v2.EdgeType` literals plus `mcp_v2.ComposedEdgeType` dot-keys (11 stored labels + 3 composed keys today). -### PR-S-4 — Tier 2 workflow skills (4 skills) +### PR-S-3 — Tier 2 workflow skills (4 skills) Add `/explain-feature`, `/impact-of`, `/trace-request-flow`, `/mini-map`. `/mini-map` requires `## MCP pre-filter (optional)`, `## Classification rules`, and `## Output shape`; all Tier 2 require `## Stop conditions` and `## Recursion limit`. Skill examples assume ontology **15** graph (re-indexed `bank-chat-system`). **Test summary**: 4 frontmatter + 4 body-structure tests; **extend the static validator to all 14 skills**. -### PR-S-5 — `AGENT-GUIDE.md` rewrite +### PR-S-4 — `AGENT-GUIDE.md` rewrite -Slash-style aliases become a pointer to `agent-skills/` (and compiled host paths). Forced reasoning preamble, decision tree, edge taxonomy, and **`resolve` flow stay** in AGENT-GUIDE. README gets Layer-3 diagram from §3. Cross-link `docs/skills/java-codebase-explore.md` in §4b style (strategy vs navigation). +Slash-style aliases become a pointer to `skills/`. Forced reasoning preamble, decision tree, edge taxonomy, and **`resolve` flow stay** in AGENT-GUIDE. README gets Layer-3 diagram from §3. -**Test summary:** add `tests/test_agent_guide_consistency.py` with an assertion that the slash-aliases section references `agent-skills/` (or compiled skills) rather than embedding the full bullet chains. +**Test summary:** add `tests/test_agent_guide_consistency.py` with an assertion that the slash-aliases section references `skills/` rather than embedding the full bullet chains. -**5 PRs total.** No ontology bump, no schema delta, no MCP surface change. +**4 PRs total.** No ontology bump, no schema delta, no MCP surface change. ## §10 Decisions taken (no longer open) 1. **Skills live at Layer 3, not Layer 2 (MCP) or ops CLI.** -2. **Single source at `agent-skills//SKILL.md`.** Compile to `.claude/skills/`, `.qwen/skills/`, `.cursor/skills/`. -3. **Identical SKILL.md format on all three hosts** — frontmatter `name` + `description` only (Appendix A). -4. **Project-scoped install by default** — checked into repo. +2. **Skills live in `skills//SKILL.md` at the project root.** No compile step, no multi-host copy pipeline. All hosts read from `skills/` directly. +3. **Identical SKILL.md format across all hosts** — frontmatter `name` + `description` only (Appendix A). +4. **Project-scoped install by default** — checked into repo in `skills/`. 5. **Slash name = skill name = directory name.** 6. **No CLI query subcommands** in this proposal. 7. **No new MCP tools** as part of skill rollout. -8. **Cursor is in scope via `.cursor/skills/` compile target** — same artefact as Claude/Qwen; not deferred to AGENT-GUIDE prose only. +8. **Developer workflow skills stay in `.agents/skills/`** — they are for repo contributors, not consumers. Navigation skills do not compile into `.agents/skills/`. 9. **Skill set = 10 Tier 1 + 4 Tier 2 = 14 total.** 10. **Lockstep versioning with MCP** — skills + AGENT-GUIDE + README in the same PR when navigation semantics change. -11. **`agent-skills/compile.py` + `java-codebase-rag compile-skills`.** +11. **No compile step.** Skills are authored directly in `skills/`. No `compile.py`, no `java-codebase-rag compile-skills` subcommand. 12. **Three test levels:** (a) schema/frontmatter, (b) static MCP-call validation against `mcp_v2` allowlists, (c) NOT full host E2E. 13. **Graph-accurate `/callers` and `/callees` on method symbols use `CALLS` only** — matches `docs/AGENT-GUIDE.md` and ontology **15**. Cross-service inbound to a **route** is `/who-hits-route` (`HTTP_CALLS`, `ASYNC_CALLS`, `EXPOSES`). Outbound HTTP/async from a **method** uses optional `DECLARES_CLIENT` → `HTTP_CALLS` or `DECLARES_PRODUCER` → `ASYNC_CALLS` steps documented in `/callees` and `/trace-request-flow`, not one-hop `HTTP_CALLS` on `sym:`. 14. **`/mini-map` = optional MCP `edge_filter` + skill-layer accessor/semantic heuristics over ordered `CALLS` hops**, subagent-preferred; complements CALLS-NOISE Decision 39 — does not replace `edge_filter` or re-filter phantom/chained on `CALLS` (those strategies are gone post–PR-3). 15. **`resolve` is the default identifier path** for Tier 1 skills; `find` is for structured listing only. -16. **`java-codebase-explore` stays the strategy guide**; navigation skills do not duplicate its missions or anti-capability sections (§4b). -17. **Skill worked examples assume ontology 15** — maintainers verify against a fresh `bank-chat-system` graph build after CALLS-NOISE; no ontology bump from this propose alone. +16. **Skill worked examples assume ontology 15** — maintainers verify against a fresh `bank-chat-system` graph build after CALLS-NOISE; no ontology bump from this propose alone. +17. **Skills compose with `hints_structured`.** MCP responses include `hints_structured` (machine-parseable next-tool calls with `tool`, `args`, `actionable`, `label`, `reason`). Skills define intent-to-chain mapping; `hints_structured` provides runtime step-to-step guidance. Skills should not duplicate what `hints_structured` already provides. ## §11 Risks and how we mitigate | Risk | Mitigation | |---|---| | Skills drift from MCP behaviour | Lockstep (decision #10) + static validator importing `mcp_v2` allowlists (decision #12) | -| Compile produces stale output | `# AUTOGENERATED` banner; CI compile + consistency check | | Tier 2 workflows blow context | Fixed depth caps; `/mini-map` subagent + thin-map fallback to `/callees` | -| Host precedence ambiguity | Manual probe **per host** documented in PR-S-2 (Claude + Qwen; Cursor noted separately) | | Weak models pick wrong skill | Rich `description` trigger phrases per skill | | Users expect v1 `callers_of` to include HTTP on methods | Decision #13 + skill docs: CALLS on `sym:`; transport via `/who-hits-route` or optional DECLARES_* steps | | `/mini-map` misclassifies signal as noise | `[filtered N edges]` line; fallback to raw `/callees` or `neighbors` with a narrower `edge_filter` when map < 3 lines | | Subagent unavailable | `/mini-map` runs in main agent with lower default depth (decision #14) | -| Skill body drifts from CALLS-NOISE MCP knobs | PR-S-4 `/mini-map` documents MCP pre-filter step; static validator does not parse `edge_filter` dicts — AGENT-GUIDE cross-link + manual re-verify on re-index | +| Skill body drifts from CALLS-NOISE MCP knobs | PR-S-3 `/mini-map` documents MCP pre-filter step; static validator does not parse `edge_filter` dicts — AGENT-GUIDE cross-link + manual re-verify on re-index | | `exclude_callee_declaring_roles: ["OTHER"]` drops known-external JDK rows | Document in `/mini-map` output transparency; prefer `min_confidence` when JDK rows must stay visible | -| Overlap with `java-codebase-explore` | §4b activation split; no duplicated cheat-sheet ownership | | Maintenance cost (14 skills) | Static validator + lockstep rule | ## Appendix A — Concrete artefacts @@ -430,13 +408,11 @@ description: --- ``` -**Cursor** uses the same `SKILL.md` under `.cursor/skills//` (this repo already ships `propose`, `pr-review`, `plan-prompts`, etc.). - Sources: - Claude Code: [code.claude.com/docs/en/skills](https://code.claude.com/docs/en/skills) - Qwen Code: [qwenlm.github.io/qwen-code-docs/en/users/features/skills](https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/) -Decision: source uses only `name` + `description`. Host-specific optional fields stay out of source unless all three hosts accept them. +Decision: source uses only `name` + `description`. Host-specific optional fields stay out of source unless all hosts accept them. ### A.2 Layer diagram (canonical, copy verbatim into README §1) @@ -446,9 +422,9 @@ Decision: source uses only `name` + `description`. Host-specific optional fields │ /trace-request-flow, /callees, /controllers, /routes, │ │ /impact-of, /mini-map │ │ ───────────────────────────────────────────────────────── │ -│ Implementation: SKILL.md in .claude/.qwen/.cursor/skills │ -│ (one agent-skills/ source). Tier 1 = deterministic chains; │ -│ Tier 2 = bounded workflows + /mini-map heuristics. │ +│ Implementation: SKILL.md in skills/ at project root. │ +│ Tier 1 = deterministic chains; Tier 2 = bounded workflows │ +│ + /mini-map heuristics. │ ├──────────────────────────────────────────────────────────────┤ │ Layer 2 — Composable primitives (the MCP API) │ │ search, find, describe, neighbors, resolve │ @@ -464,17 +440,16 @@ See §6 — `/callees` is the canonical Tier 1 template. Tier 2 adds `## Stop co ## Appendix B — What changed (traceability) -### What stayed unchanged (through revision 4) +### What stayed unchanged (through revision 5) - 3-layer mental model + ASCII diagram (updated labels only). -- 10 Tier 1 + 4 Tier 2 skill **names** and overall 5-PR migration. -- Single `agent-skills/` source with multi-host compile. -- Lockstep versioning + static validator (now imports `mcp_v2` allowlists). +- 10 Tier 1 + 4 Tier 2 skill **names** and overall migration scope. +- Lockstep versioning + static validator (imports `mcp_v2` allowlists). - `/mini-map` as the skill-layer complement to CALLS-NOISE (accessor + semantic labels). ### Revision 1 (2026-05-08) -Working `compile.py` in PR-S-2; manual host precedence probe; static MCP-call validator; decision #12 three test levels. (See prior Appendix B in git history.) +Initial draft. (See prior Appendix B in git history.) ### Revision 2 (2026-05-17) @@ -482,26 +457,30 @@ Added `/mini-map`, skill count 13→14, decision #14, [#177](https://github.com/ ### Revision 3 (2026-05-19) — critical review fixes -1. **5-tool MCP** — `resolve` added everywhere; diagram, validator, and decisions updated (was incorrectly frozen at 4 tools post-`resolve` ship). +1. **5-tool MCP** — `resolve` added everywhere; diagram, validator, and decisions updated. 2. **`java-codebase-rag` naming** — replaced stale `user-rag` paths and CLI subcommand name. -3. **Graph-accurate chains** — reverted incorrect one-hop `HTTP_CALLS`/`ASYNC_CALLS` on `sym:` for `/callers`/`/callees`; rewrote `/trace-request-flow`, `/impact-of`, and `/mini-map` hops; decision #13 replaced with graph-accurate decision #13–#16. -4. **`resolve` first** — Tier 1 template and shared resolution rule; dropped `find({fqn_prefix})` as primary disambiguation. -5. **§4b** — relationship to `java-codebase-explore`, AGENT-GUIDE, and existing `.cursor/skills/`. -6. **Cursor compile target** — `.cursor/skills/` is a first-class output (decision #8); removed incorrect "Cursor has no slash skills" claim. -7. **Static validator** — allowlists sourced from `mcp_v2` (`EdgeType`, `ComposedEdgeType`, find kinds including `producer`); removed bogus `text` kind. -8. **Principle split** — Tier 1 deterministic vs Tier 2 bounded/heuristic. -9. **Diagram / UC table** — slash names aligned with §5; UC15 column fix; 16 use cases. -10. **PR-S-5 test** — `test_agent_guide_consistency.py` specified as new file. -11. **Appendix B** — validator span corrected to 14 skills; revision 3 traceability. +3. **Graph-accurate chains** — reverted incorrect one-hop `HTTP_CALLS`/`ASYNC_CALLS` on `sym:`. +4. **`resolve` first** — Tier 1 template and shared resolution rule. +5. **Static validator** — allowlists sourced from `mcp_v2`. ### Revision 4 (2026-05-20) — align with CALLS-NOISE on `master` -Rebased onto `master` after [`CALLS-NOISE-AND-RESOLUTION`](completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md) landed (#179–#185, ontology **15**). +Rebased onto `master` after [`CALLS-NOISE-AND-RESOLUTION`](../completed/CALLS-NOISE-AND-RESOLUTION-PROPOSE.md) landed (ontology **15**). + +1. **Removed #177 blocker** — replaced with **Related** cross-link. +2. **`/mini-map` pipeline** — MCP `edge_filter` / `dedup_calls` / `include_unresolved` first. +3. **Evidence** — pinned `ClientMessageProcessor#process` (~49 default `CALLS` post–PR-3). + +### Revision 5 (2026-05-24) — refresh for master drift + skill architecture simplification + +Rebased onto `master` (26 commits ahead of revision 4). Structural and content changes: -1. **Removed #177 blocker** — replaced with **Related** cross-link; server-side work landed; `/mini-map` scope narrowed to accessor heuristics + semantic labels (Decision 39). -2. **`/mini-map` pipeline** — MCP `edge_filter` / `dedup_calls` / `include_unresolved` first; dropped obsolete `strategy in (phantom, chained_receiver)` on `CALLS`; documented mutual exclusivity of `include_unresolved` + `edge_filter`. -3. **Evidence** — pinned `ClientMessageProcessor#process` (~49 default `CALLS` post–PR-3); UC16 updated. -4. **Ontology v14 → v15** — Tier 1, decisions #13 and #17, PR-S-4 re-index note. -5. **§8 out-of-scope** — removed stale "server-side filtering is a future propose"; added rows for indexer port and `include_unresolved` + `edge_filter` compose. -6. **Decision #14 rewritten**; decision **#17** (skill examples assume ontology 15 graph). -7. **Risks** — `edge_filter` drift and `OTHER` role filter bluntness. +1. **`skills/` at project root replaces `agent-skills/` + compile pipeline.** No `compile.py`, no `java-codebase-rag compile-skills` subcommand, no AUTOGENERATED banner, no multi-host copy. All hosts read from `skills/` directly. (Decisions #2, #11 rewritten.) +2. **`.cursor/` → `.agents/`** — developer workflow skills reference updated (PR #203 on master). +3. **`hints_structured` awareness** — MCP responses now carry `hints_structured` (machine-parseable next-tool calls). New principle #10: skills compose with `hints_structured`, don't duplicate it. New decision #17. +4. **5-PR → 4-PR migration** — compile step PR removed; Tier 1 skills PR absorbs the `skills/` directory creation. +5. **Moved to `propose/active/`** — per PR #218's new folder structure. +6. **Deleted `docs/skills/`** — removed `java-codebase-explore.md`, `.zip`, and `scripts/build-explore-skill.sh`. The explore skill's content is removed; its strategy/mission concepts may re-emerge as a future Layer 3 skill. +7. **§4b rewritten** — removed `docs/skills/java-codebase-explore.md` and `.cursor/skills/` rows; added clear consumer vs developer skill directory split. +8. **Decision #8 rewritten** — `.agents/skills/` for developer workflow skills only; consumer skills never go there. +9. **Appendix B traceability** — preserved revisions 1–4 history; added revision 5. diff --git a/scripts/build-explore-skill.sh b/scripts/build-explore-skill.sh deleted file mode 100755 index e2b330a..0000000 --- a/scripts/build-explore-skill.sh +++ /dev/null @@ -1,54 +0,0 @@ -#!/usr/bin/env bash -# build-explore-skill.sh — rebuild Perplexity-format java-codebase-explore.zip -# -# Prerequisites: -# - bash 3.2+ -# - cp, mktemp, rm, touch (POSIX); zip(1) in PATH -# -# Usage (from repo root): -# ./scripts/build-explore-skill.sh -# -# When to run: -# - After editing docs/skills/java-codebase-explore.md (keeps zip in sync). -# - As release / ontology-bump hygiene alongside README + cheat sheet updates. -# -# Output: -# docs/skills/java-codebase-explore.zip (overwritten; commit the result) -# -# Determinism: file mtimes inside the archive are normalized so repeated runs -# on the *same* machine / zip(1) build usually yield identical bytes. Do not -# treat a checksum from another maintainer or CI image as a portable contract: -# zip implementations and extra fields can still differ across OS releases. -set -euo pipefail - -ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" -SRC_MD="$ROOT/docs/skills/java-codebase-explore.md" -OUT_ZIP="$ROOT/docs/skills/java-codebase-explore.zip" - -if ! command -v zip >/dev/null 2>&1; then - echo "error: zip(1) is required but not found in PATH" >&2 - exit 1 -fi - -if [[ ! -f "$SRC_MD" ]]; then - echo "error: missing skill source: $SRC_MD" >&2 - exit 1 -fi - -TMP="$(mktemp -d "${TMPDIR:-/tmp}/explore-skill.XXXXXX")" -cleanup() { - rm -rf "$TMP" -} -trap cleanup EXIT - -# Perplexity bundle: canonical body + SKILL.md manifest (same body + §3.5 YAML). -cp "$SRC_MD" "$TMP/java-codebase-explore.md" -cp "$SRC_MD" "$TMP/SKILL.md" - -# Normalized member mtimes for reproducible archives (portable: BSD/GNU touch). -touch -t 200001010000 "$TMP/java-codebase-explore.md" "$TMP/SKILL.md" - -rm -f "$OUT_ZIP" -( cd "$TMP" && zip -X -q "$OUT_ZIP" java-codebase-explore.md SKILL.md ) - -echo "wrote $OUT_ZIP" diff --git a/tests/README.md b/tests/README.md index 8c1fb0f..3c65ab7 100644 --- a/tests/README.md +++ b/tests/README.md @@ -41,7 +41,7 @@ cd /path/to/java-codebase-rag ## CI merge gate and fixture tiers -**Merge gate (mechanical):** [`.github/workflows/test.yml`](../.github/workflows/test.yml) always runs the `test` job on every pull request and on every push to `master`. When any **source** path changes (Python, deps, `pytest.ini`, `mcp.json.example`, `.gitignore`, workflows, non-markdown under `tests/` or `automation/`), it runs `pytest tests` with `JAVA_CODEBASE_RAG_RUN_HEAVY=0`. Documentation-only changes (`propose/`, `plans/`, `reports/`, `.agents/`, `docs/`, `**/*.md`, etc.) still produce a green `test` check but skip pytest. Branch protection on `master` requires the `test` status check to pass before merge and disables force-push. Break-glass policy: `enforce_admins: false` so the sole maintainer can bypass for emergency hotfixes — explain the bypass in the merge commit. +**Merge gate (mechanical):** [`.github/workflows/test.yml`](../.github/workflows/test.yml) always runs the `test` job on every pull request and on every push to `master`. When any **source** path changes (Python, deps, `pytest.ini`, `mcp.json.example`, `.gitignore`, workflows, non-markdown under `tests/` or `automation/`), it runs `pytest tests` with `JAVA_CODEBASE_RAG_RUN_HEAVY=0`. Documentation-only changes (`propose/`, `plans/`, `skills/`, `.agents/`, `docs/`, `**/*.md`, etc.) still produce a green `test` check but skip pytest. Branch protection on `master` requires the `test` status check to pass before merge and disables force-push. Break-glass policy: `enforce_admins: false` so the sole maintainer can bypass for emergency hotfixes — explain the bypass in the merge commit. **Iteration subset (convention):** During implementation, authors name a `pytest` file subset inside each per-PR execution prompt (for example in `plans/AGENT-PROMPTS-*.md`). The repo **[`plan-prompts`](../.agents/skills/plan-prompts/SKILL.md)** skill (`.agents/skills/plan-prompts/`) requires a **`## Tests to run (iteration loop)`** section in that scaffold, placed **after Deliverables and before Tests**. Reviewers follow the repo **[`pr-review`](../.agents/skills/pr-review/SKILL.md)** skill (`.agents/skills/pr-review/`): pasted subset command + exit code, plus a green `test` CI link from the merge gate documented above (full pytest for code changes; pytest skipped for docs-only PRs). Canonical skill sources live under `.agents/skills/` (symlink as `.cursor` or `.claude` locally if your editor expects those paths); you may copy them into `~/.cursor/skills/` if your Cursor setup loads personal skills only. See [`propose/completed/TEST-SUITE-FAST-LOOP-PROPOSE.md`](../propose/completed/TEST-SUITE-FAST-LOOP-PROPOSE.md) and [`plans/completed/PLAN-TEST-SUITE-FAST-LOOP.md`](../plans/completed/PLAN-TEST-SUITE-FAST-LOOP.md).