diff --git a/.context/DECISIONS.md b/.context/DECISIONS.md index 94da0b42d..957d4aef4 100644 --- a/.context/DECISIONS.md +++ b/.context/DECISIONS.md @@ -3,6 +3,7 @@ | Date | Decision | |----|--------| +| 2026-05-23 | Skill body text uses capability-first language with canonical tools as examples; install-guide docs name canonical implementations; `allowed-tools` frontmatter stays MCP-specific | | 2026-05-23 | MCP gateway not worth the coupling cost; companion tools stay peer-MCP and remain not-vouched-for-by-ctx | | 2026-05-23 | Keep `i18n.Fold` strict; add `i18n.MatchKey` as the separate diacritic-insensitive primitive | | 2026-05-22 | OpenCode plugin: agent shell tool not anchored to project root under cwd-anchored | @@ -150,6 +151,48 @@ For significant decisions: --> +## [2026-05-23-030000] Skill body text uses capability-first language with canonical tools as examples; install-guide docs name canonical implementations; `allowed-tools` frontmatter stays MCP-specific + +**Status**: Accepted + +**Context**: The 2026-05-23 "MCP gateway not worth the coupling cost" decision rejected pluggable abstraction over companion tools at the code/protocol layer (no gateway, no plugin registry). But that decision left an open question: skill body text was still hard-coding specific tool names (GitNexus, Gemini Search), and so were several `docs/` pages. The hard-coding is *its own* form of vouching — just static prescription instead of dynamic dispatch. A user with Firecrawl / sourcegraph-cody / vLLM read the skill and saw instructions naming tools they don't have; the agent couldn't self-route because the skill text told it to use specific MCP server names. + +Three rule choices were considered for the body-text layer: + +1. Pluggable abstraction with `.ctxrc`-declared capability mapping — rejected by the prior decision (it IS the interface-contract ownership cost we ruled out). +2. Per-tool skill variants (`ctx-architecture-enrich-gitnexus`, `…-sourcegraph`, …) — explodes the skill count without removing the prescription, just sliced thinner. +3. **Capability-first body text with canonical tools as examples** — chosen. + +A parallel question existed for `docs/`: an install guide LEGITIMATELY names tools (its job is "tell me what to install"). Genericizing install commands would harm newcomers. The right split: operational/descriptive docs use the same capability-first phrasing as skills; install-guide docs name canonical implementations explicitly, with a one-liner noting equivalents work. + +The `allowed-tools` frontmatter is a separate concern. Genericizing to `mcp__*` would grant skills access to EVERY connected MCP — a permission expansion, not a cosmetic change. Operators with different toolchains edit `allowed-tools` in their local skill copy or fork. A separate spec can revisit if needed. + +**Decision**: Three layered rules. + +1. **Skill body text** uses capability-first language ("a code-intelligence MCP", "a web-search-with-citations MCP") with the canonical implementation listed as an example ("canonical: GitNexus; equivalents include sourcegraph-cody"). Operational example calls (e.g. `mcp__gitnexus__impact({…})`) stay as canonical-impl illustrations. +2. **Install-guide docs** (`docs/home/getting-started.md`, `docs/recipes/multi-tool-setup.md`) name canonical implementations directly and provide concrete setup commands. A preamble notes that equivalents work for non-canonical toolchains. +3. **`allowed-tools` frontmatter** stays MCP-specific. Skills ship with `mcp__gitnexus__*`, `mcp__gemini-search__*` in the allowlist. Operators using different MCP servers edit the allowlist in their local skill copies. + +**Rationale**: Three reinforcing properties: + +- **Manifesto-aligned.** ctx no longer prescribes specific tools in skill bodies. Agents self-route based on what's connected. +- **No new abstraction layer.** Pure text rewrite. Zero code change, zero interface contract, zero coupling. +- **Discoverability preserved.** Canonical tools stay first-listed in every section so newcomers immediately learn what to install if they're starting from zero. + +Alternatives explicitly rejected: code-level pluggability (2026-05-23 MCP-gateway decision); per-tool skill variants (maintenance explosion without solving the smell); "remove all tool names" (loses discoverability for new users who do want a recommendation). + +**Consequence**: + +- Eight skill files updated (commit f554f758): ctx-refactor, ctx-explain, ctx-code-review, ctx-remember (claude + copilot-cli), ctx-architecture, ctx-architecture-enrich, ctx-architecture-failure-analysis. Prescriptive references to specific tools rewritten as capability-first with canonical examples. +- Six docs updated alongside (this commit): architecture-exploration runbook, architecture-deep-dive recipe, skills.md reference, cli/index.md schema, getting-started.md install guide, multi-tool-setup.md recipe. +- `specs/skill-audit-companion-tool-neutrality.md` documents the per-file rewrites and the install-guide-vs-operational split for future contributors. +- New skill authors follow this rule: describe the capability, name the canonical implementation as an example, leave `allowed-tools` MCP-specific. +- If a real second-viable graph-tool ecosystem emerges and operators consistently ask for pluggable `allowed-tools`, the prior MCP-gateway decision can be revisited; the present decision doesn't preclude that future evolution. + +See also: `specs/skill-audit-companion-tool-neutrality.md`, `specs/ctx-remember-silent-companion-fallback.md` (the install-nag fix that preceded this audit), the 2026-05-23 "MCP gateway not worth the coupling cost" decision above. + +--- + ## [2026-05-23-020000] MCP gateway not worth the coupling cost; companion tools stay peer-MCP and remain not-vouched-for-by-ctx **Status**: Accepted diff --git a/docs/cli/index.md b/docs/cli/index.md index 5882d69d5..041a4317d 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -198,7 +198,7 @@ hooks: # Hook system configuration | `archive_after_days` | `int` | `7` | Days before completed tasks are archived | | `scratchpad_encrypt` | `bool` | `true` | Encrypt scratchpad with AES-256-GCM | | `event_log` | `bool` | `false` | Enable local hook event logging to `.context/state/events.jsonl` | -| `companion_check` | `bool` | `true` | Check companion tool availability (Gemini Search, GitNexus) during `/ctx-remember` | +| `companion_check` | `bool` | `true` | Check companion tool availability (canonical: Gemini Search, GitNexus; equivalents work) during `/ctx-remember`| | `entry_count_learnings` | `int` | `30` | Drift warning when `LEARNINGS.md` exceeds this count | | `entry_count_decisions` | `int` | `20` | Drift warning when `DECISIONS.md` exceeds this count | | `convention_line_count` | `int` | `200` | Line count warning for `CONVENTIONS.md` | diff --git a/docs/home/getting-started.md b/docs/home/getting-started.md index 28debe7e0..df35bc45f 100644 --- a/docs/home/getting-started.md +++ b/docs/home/getting-started.md @@ -314,18 +314,22 @@ or previous session topics. ### 7. Set Up Companion Tools (Highly Recommended) -`ctx` works on its own, but two companion MCP servers unlock significantly -better agent behavior. The investment is small and the benefits compound -over sessions: - -* **[Gemini Search](https://github.com/nicobailon/gemini-code-search-mcp)** -: grounded web search with citations. Skills like `/ctx-code-review` - and `/ctx-explain` use it for up-to-date documentation lookups instead - of relying on training data. - -* **[GitNexus](https://github.com/nicobailon/gitnexus-mcp)**: code - knowledge graph with symbol resolution, blast radius analysis, and - domain clustering. Skills like `/ctx-refactor` and `/ctx-code-review` +`ctx` works on its own, but two MCP capabilities unlock significantly +better agent behavior. ctx names canonical implementations below as +its tested defaults; if your toolchain provides the same capabilities +through different MCP servers (Firecrawl / Exa / Tavily for web +search; sourcegraph-cody for the code graph), use those instead. +The investment is small and the benefits compound over sessions: + +* **Web search with citations** — canonical: + **[Gemini Search](https://github.com/nicobailon/gemini-code-search-mcp)**. + Skills like `/ctx-code-review` and `/ctx-explain` use it for + up-to-date documentation lookups instead of relying on training data. + +* **Code knowledge graph** — canonical: + **[GitNexus](https://github.com/nicobailon/gitnexus-mcp)**. + Provides symbol resolution, blast radius analysis, and domain + clustering. Skills like `/ctx-refactor` and `/ctx-code-review` use it for impact analysis and dependency awareness. ```bash @@ -333,8 +337,11 @@ over sessions: npx gitnexus analyze ``` -Both are optional MCP servers: if they are not connected, skills degrade -gracefully to built-in capabilities. See +(For non-GitNexus code-intelligence MCPs, apply that tool's own +indexing step instead.) + +Both capabilities are optional: if no compatible MCP is connected, +skills degrade gracefully to built-in capabilities. See [Companion Tools](../recipes/multi-tool-setup.md#companion-tools-highly-recommended) for setup details and verification. diff --git a/docs/operations/runbooks/architecture-exploration.md b/docs/operations/runbooks/architecture-exploration.md index 29652c6a9..191864a72 100644 --- a/docs/operations/runbooks/architecture-exploration.md +++ b/docs/operations/runbooks/architecture-exploration.md @@ -27,7 +27,8 @@ workspace directory (e.g., `~/WORKSPACE/`). **Companion skills**: - `/ctx-architecture`: structural baseline and principal analysis -- `/ctx-architecture-enrich`: code intelligence enrichment via GitNexus +- `/ctx-architecture-enrich`: code intelligence enrichment via a + code-intelligence MCP (canonical: GitNexus) - `/ctx-architecture-failure-analysis`: adversarial failure analysis --- @@ -109,7 +110,7 @@ Each repo progresses through these phases in order: |-------|-------|-------------| | `bootstrap` | `ctx init` + `/ctx-architecture` | None | | `principal` | `/ctx-architecture principal` | bootstrap done | -| `enriched` | `/ctx-architecture-enrich` | principal done, GitNexus indexed | +| `enriched` | `/ctx-architecture-enrich` | principal done, code-intelligence MCP indexed (canonical: GitNexus) | | `frontier-N` | `/ctx-architecture` (re-run) | enriched done | **`bootstrap` is a single composite unit:** `ctx init` followed by @@ -166,10 +167,12 @@ focus as input upfront. - Run `/ctx-architecture` (add `principal` argument for principal phase). - The skill will read existing artifacts and build on them. 5. If phase is `enriched`: - - Verify GitNexus is connected: call `mcp__gitnexus__list_repos`. + - Verify a code-intelligence MCP is connected. Canonical + smoke test: `mcp__gitnexus__list_repos` (or the equivalent + smoke test for your configured tool). - Success = non-empty list returned with no error. - - If GitNexus unavailable, log as `enriched-skipped` and advance - to `frontier-1`. + - If no code-intelligence MCP is available, log as + `enriched-skipped` and advance to `frontier-1`. - Run `/ctx-architecture-enrich`. 6. If phase is a lens run (`lens-security`, etc.): - Run `/ctx-architecture` with lens focus prepended as instruction @@ -255,8 +258,9 @@ it, produce no further output. Execution is complete. already recorded as completed, skip it. 4. **Log everything.** Every run gets a run-log entry, even failures and skips. -5. **Fail gracefully.** If a skill fails (missing GitNexus, broken repo, - etc.), log the failure with reason and advance to the next phase or +5. **Fail gracefully.** If a skill fails (no code-intelligence MCP + connected, broken repo, etc.), log the failure with reason and + advance to the next phase or repo. Don't retry in the same invocation. 6. **Respect `ctx` conventions.** Each repo gets its own `.context/` directory. Never write architecture artifacts outside `.context/`. @@ -326,9 +330,10 @@ right project root. - **Start small**: list 1-2 repos in the manifest first. Add more once you're confident in the output quality. -- **GitNexus is optional**: the enrichment phase is skipped - gracefully if GitNexus isn't connected. You still get structural - and principal analysis. +- **The code-intelligence MCP is optional**: the enrichment phase + is skipped gracefully if no such MCP is connected (canonical: + GitNexus; equivalents work). You still get structural and + principal analysis. - **Review between batches**: check the run-log and generated artifacts between batch runs. The agent is additive-only, but early course correction saves wasted runs. diff --git a/docs/recipes/architecture-deep-dive.md b/docs/recipes/architecture-deep-dive.md index 272f92ea5..4a83fda74 100644 --- a/docs/recipes/architecture-deep-dive.md +++ b/docs/recipes/architecture-deep-dive.md @@ -84,7 +84,8 @@ dependencies). ``` Takes the Pass 1 artifacts as baseline and layers on verified, -graph-backed data from GitNexus: +graph-backed data from a code-intelligence MCP (canonical: +GitNexus; equivalents include sourcegraph-cody): - Blast radius numbers for key functions - Execution flow traces through hot paths @@ -99,7 +100,9 @@ Z would affect 12 downstream consumers." **When to run**: After Pass 1, when you need quantified confidence for refactoring decisions or risk assessment. -**Requires**: GitNexus MCP server connected. +**Requires**: a code-intelligence MCP connected (canonical: +GitNexus; equivalents work if they expose symbol-index, +blast-radius, and execution-flow queries). ### Pass 3: Hunt for Failure Modes diff --git a/docs/recipes/multi-tool-setup.md b/docs/recipes/multi-tool-setup.md index a0ec60b8e..bf6d48dbf 100644 --- a/docs/recipes/multi-tool-setup.md +++ b/docs/recipes/multi-tool-setup.md @@ -403,6 +403,14 @@ benefits compound. Skills like `/ctx-code-review`, `/ctx-explain`, and `/ctx-refactor` all become noticeably better with these tools connected. +The two sections below name **canonical implementations** that ctx has +tested against — Gemini Search for web-search-with-citations and +GitNexus for the code knowledge graph. If your toolchain provides +equivalent capabilities through different MCP servers (Firecrawl, +Exa, Tavily for web search; sourcegraph-cody for code graph), use +those instead. ctx skills describe capabilities, not specific tools — +the agent self-routes based on what's connected. + ### Gemini Search Provides grounded web search with citations. Used by skills and the diff --git a/docs/reference/skills.md b/docs/reference/skills.md index 49034e760..8e449d756 100644 --- a/docs/reference/skills.md +++ b/docs/reference/skills.md @@ -618,8 +618,10 @@ Produces `.context/DANGER-ZONES.md` with ranked findings split into Critical (risk >= 7, silent/cascading) and Elevated tiers. **Wraps**: reads architecture artifacts, source code; writes -`DANGER-ZONES.md`. Optionally uses GitNexus for blast radius -and Gemini Search for cross-referencing known failure patterns. +`DANGER-ZONES.md`. Optionally uses a code-intelligence MCP +(canonical: GitNexus) for blast radius and a +web-search-with-citations MCP (canonical: Gemini Search) for +cross-referencing known failure patterns. **Relationship**: diff --git a/internal/assets/claude/skills/ctx-architecture-enrich/SKILL.md b/internal/assets/claude/skills/ctx-architecture-enrich/SKILL.md index 84d729bfd..aae9dd552 100644 --- a/internal/assets/claude/skills/ctx-architecture-enrich/SKILL.md +++ b/internal/assets/claude/skills/ctx-architecture-enrich/SKILL.md @@ -30,8 +30,10 @@ to questions never asked. - After `/ctx-architecture` or `/ctx-architecture principal` has produced artifacts -- After `npx gitnexus analyze --embeddings` completes on a project - that already has architecture artifacts +- After a code-intelligence MCP has indexed the project + (canonical: GitNexus via `npx gitnexus analyze --embeddings`; + equivalents apply their own indexing step) and architecture + artifacts already exist - When the user says "enrich the architecture", "run enrichment pass", "add graph data", "quantify the danger zones" - When DANGER-ZONES.md exists but lacks blast radius numbers @@ -42,8 +44,8 @@ to questions never asked. - As a substitute for `/ctx-architecture` - if no architecture artifacts exist, run `/ctx-architecture` first -- When GitNexus MCP is not connected or the index is stale - - preflight will catch this +- When no code-intelligence MCP is connected, or the index is + stale — preflight will catch this - Immediately after `/ctx-architecture` in the same session without user request - let the user review the base artifacts first @@ -83,25 +85,36 @@ to generate the baseline, then run this skill to enrich it. ### 1.2 Verify Code Intelligence Tools -Check each tool silently: +Check each capability silently: -**GitNexus** (required): -- Call `mcp__gitnexus__list_repos` to verify connection -- Check that the current project is indexed -- Compare the index timestamp against the latest git commit to - detect staleness +**Code-intelligence MCP** (required for this skill): -If GitNexus is not connected or the project is not indexed: +This skill's entire purpose is code-graph-verified enrichment, +so it cannot run without a code-intelligence MCP. The canonical +implementation is GitNexus (`mcp__gitnexus__list_repos`, +`mcp__gitnexus__impact`, etc.); equivalents that expose the +same capabilities (symbol index, blast-radius queries, indexed +repo state) work equally well. + +- Attempt the smoke-test call for whichever code-intelligence + MCP your toolchain provides +- For GitNexus specifically: also check that the current + project is indexed and compare the index timestamp against + the latest git commit to detect staleness + +If no code-intelligence MCP is connected: ``` -GitNexus is not connected (or this project is not indexed). -This skill requires a code intelligence graph. +This skill requires a code-intelligence MCP (e.g., GitNexus, +sourcegraph-cody, or equivalent). None is connected. -To set up: add the GitNexus MCP server, then run: +If you have GitNexus, configure the MCP and run: npx gitnexus analyze --embeddings +If you use a different code-intelligence MCP, configure it +per its docs and re-run this skill. ``` -If the index is stale (commits after last index): +For GitNexus, if the index is stale (commits after last index): - **≤ 5 commits behind**: warn and proceed. ``` @@ -117,10 +130,17 @@ If the index is stale (commits after last index): Run `npx gitnexus analyze` to update, then re-run this skill. ``` -**Gemini Search** (optional): -- Attempt a simple query to verify connection +(For non-GitNexus code-intelligence MCPs, apply the same +staleness check using whatever the underlying tool exposes.) + +**Web-search-with-citations MCP** (optional): + +- Canonical example: Gemini Search + (`mcp__gemini-search__search_with_grounding`) +- Equivalents: Firecrawl, Exa, Tavily, or any MCP that + returns grounded results with citations - If available: note silently, use for upstream pattern lookups -- If not available: note silently, proceed without it +- If not available: silently fall back to built-in web search ### 1.3 Read Baseline Artifacts diff --git a/internal/assets/claude/skills/ctx-architecture-failure-analysis/SKILL.md b/internal/assets/claude/skills/ctx-architecture-failure-analysis/SKILL.md index 13872ce31..e0c35dd32 100644 --- a/internal/assets/claude/skills/ctx-architecture-failure-analysis/SKILL.md +++ b/internal/assets/claude/skills/ctx-architecture-failure-analysis/SKILL.md @@ -53,8 +53,11 @@ If they don't exist, stop and tell the user to run - `.context/DANGER-ZONES.md`: existing danger zones from `/ctx-architecture` principal mode (used as starting points, not as the final word) -- GitNexus MCP: blast radius estimation, shared-state detection -- Gemini Search: cross-reference against known failure patterns +- Code-intelligence MCP (canonical: GitNexus; equivalents include + sourcegraph-cody): blast radius estimation, shared-state detection +- Web-search-with-citations MCP (canonical: Gemini Search; + equivalents include Firecrawl, Exa, Tavily): cross-reference + against known failure patterns ## Process @@ -237,8 +240,9 @@ This phase is mandatory. Skipping it produces smart fiction. For each surviving finding: 1. **Blast radius**: If this fails, what breaks? - - If GitNexus is available, use `impact` to get caller - chains and dependency graphs + - If a code-intelligence MCP is available (canonical: + GitNexus's `impact`; equivalents include sourcegraph-cody), + use it to get caller chains and dependency graphs - Otherwise, estimate from the architecture dependency graph 2. **Detection gap**: Would existing tests catch this? @@ -261,10 +265,13 @@ For each surviving finding: - **Critical**: Total >= 7 AND failure is silent or cascading - **Elevated**: All others -5. **Cross-reference**: If Gemini Search is available, search - for the pattern in known incident databases, blog posts, - and similar project post-mortems. This grounds findings in - real-world evidence. +5. **Cross-reference**: If a web-search-with-citations MCP is + available (canonical: Gemini Search; equivalents include + Firecrawl, Exa, Tavily), search for the pattern in known + incident databases, blog posts, and similar project + post-mortems. This grounds findings in real-world evidence. + If no such MCP is connected, fall back to built-in web + search. ### Phase 5: Write DANGER-ZONES.md @@ -380,7 +387,9 @@ Before writing DANGER-ZONES.md, verify: - [ ] Each finding names the triggering precondition explicitly - [ ] Summary report includes confidence breakdown and challenge drop count -- [ ] If GitNexus available: blast radius was verified with - impact analysis -- [ ] If Gemini available: findings were cross-referenced +- [ ] If a code-intelligence MCP is available (canonical: + GitNexus): blast radius was verified with its impact-analysis + surface +- [ ] If a web-search-with-citations MCP is available + (canonical: Gemini Search): findings were cross-referenced against known patterns diff --git a/internal/assets/claude/skills/ctx-architecture/SKILL.md b/internal/assets/claude/skills/ctx-architecture/SKILL.md index e2b7cb025..535083db2 100644 --- a/internal/assets/claude/skills/ctx-architecture/SKILL.md +++ b/internal/assets/claude/skills/ctx-architecture/SKILL.md @@ -79,30 +79,29 @@ Then stop. ### Phase 0.25: Companion Tool Check -Check if **Gemini Search** MCP is available by attempting a -simple query. Gemini is used for upstream documentation, design -rationale, KEPs, peer-project patterns - anything outside the -local codebase that helps understand *why* the code is shaped -the way it is. - -**If available**: note it silently. Use Gemini throughout the -analysis for upstream lookups. Prefer it over built-in web search. - -**If not available**: ask the user once: - -``` -Gemini Search is not connected. It helps me look up upstream -design docs, KEPs, and peer-project patterns during analysis. - -Want to set it up now, or proceed without it? -``` - -Respect the answer and continue either way. - -**Important**: Gemini is for *upstream* and *external* context -only. Do not use it to understand the local codebase - read the -code directly. The depth of analysis comes from forced reading, -not from search shortcuts. +Check if a **web-search-with-citations MCP** is available by +attempting a simple query. The canonical implementation is +Gemini Search (`mcp__gemini-search__search_with_grounding`); +if your toolchain provides the same capability via a different +server (Firecrawl, Exa, Tavily, etc.), use whatever is +connected. This capability is for upstream documentation, +design rationale, KEPs, peer-project patterns — anything +outside the local codebase that helps understand *why* the +code is shaped the way it is. + +**If available**: note it silently. Use it throughout the +analysis for upstream lookups. Prefer it over built-in web +search. + +**If not available**: silently fall back to built-in web search +for upstream lookups. Do not prompt the user to install +anything — ctx does not vouch for companion-tool install +paths (see DECISIONS.md, 2026-05-23). + +**Important**: this capability is for *upstream* and *external* +context only. Do not use it to understand the local codebase — +read the code directly. The depth of analysis comes from forced +reading, not from search shortcuts. ### Phase 0.5: Quick Structure Scan + Focus Areas @@ -553,14 +552,16 @@ you. second, ADRs third - Maximum ~10 phrases total; fewer sharp ones beat many vague ones - Default: do NOT run the searches yourself -- Exception: if Gemini Search is available, you MAY run upstream - searches for KEPs, design docs, peer-project patterns, and ADRs - - but only for concepts the codebase shows clear dependency on. - Note what you searched and what you found. This applies in any +- Exception: if a web-search-with-citations MCP is available + (Gemini Search is the canonical example; equivalents include + Firecrawl, Exa, Tavily), you MAY run upstream searches for + KEPs, design docs, peer-project patterns, and ADRs — but only + for concepts the codebase shows clear dependency on. Note + what you searched and what you found. This applies in any mode, not just principal mode. -- If Gemini is not available and the user requested principal-mode - depth, you may fall back to built-in web search for the same - purpose +- If no such MCP is available and the user requested + principal-mode depth, fall back to built-in web search for + the same purpose --- diff --git a/internal/assets/claude/skills/ctx-code-review/SKILL.md b/internal/assets/claude/skills/ctx-code-review/SKILL.md index 9b70fe67f..15ebb27d4 100644 --- a/internal/assets/claude/skills/ctx-code-review/SKILL.md +++ b/internal/assets/claude/skills/ctx-code-review/SKILL.md @@ -14,8 +14,9 @@ Review the specified code change focusing on substance over style. ## When NOT to Use -- User wants a full PR review with GitHub integration (use - `/gitnexus-pr-review` instead) +- User wants a full PR review with GitHub integration — if + you have an external PR-review skill (the GitNexus suite + ships `/gitnexus-pr-review`), invoke it instead - User wants an architecture-level review (use `/ctx-architecture`) ## Review Checklist diff --git a/internal/assets/claude/skills/ctx-explain/SKILL.md b/internal/assets/claude/skills/ctx-explain/SKILL.md index 878979159..63f4ba0d0 100644 --- a/internal/assets/claude/skills/ctx-explain/SKILL.md +++ b/internal/assets/claude/skills/ctx-explain/SKILL.md @@ -16,8 +16,14 @@ depth to the user's expertise if known from context. ## When NOT to Use - User wants deep architectural analysis (use `/ctx-architecture`) -- User wants to trace a bug (use `/gitnexus-debugging`) -- User wants execution flow tracing (use `/gitnexus-exploring`) +- User wants to trace a bug — if you have an external + debugging-aware skill (the GitNexus suite ships + `/gitnexus-debugging`), invoke it; otherwise proceed with + built-in reasoning +- User wants execution flow tracing — if you have an external + flow-tracing skill (the GitNexus suite ships + `/gitnexus-exploring`), invoke it; otherwise reason from + the source ## Explanation Structure diff --git a/internal/assets/claude/skills/ctx-refactor/SKILL.md b/internal/assets/claude/skills/ctx-refactor/SKILL.md index cd54803ad..ddcd7455d 100644 --- a/internal/assets/claude/skills/ctx-refactor/SKILL.md +++ b/internal/assets/claude/skills/ctx-refactor/SKILL.md @@ -16,9 +16,10 @@ Refactoring changes structure, not outcomes. ## When NOT to Use - User wants to add new behavior (that's a feature, not a refactor) -- User wants a rename across the codebase (prefer - `/gitnexus-refactoring` if GitNexus is available; otherwise - use grep-based search to find all references before renaming) +- User wants a rename across the codebase (if you have an + external rename-aware skill, e.g. the GitNexus suite ships + `/gitnexus-refactoring`, invoke it; otherwise use grep-based + search to find all references before renaming) ## Rules diff --git a/internal/assets/claude/skills/ctx-remember/SKILL.md b/internal/assets/claude/skills/ctx-remember/SKILL.md index 2e8b46639..791ff3958 100644 --- a/internal/assets/claude/skills/ctx-remember/SKILL.md +++ b/internal/assets/claude/skills/ctx-remember/SKILL.md @@ -132,29 +132,34 @@ Skip this section entirely if `companion_check: false` is set in the field value. **Companion tools** enhance ctx skills with web search and code -intelligence. They are optional but recommended: +intelligence. They are optional but recommended. ctx names canonical +implementations below; if your MCP toolchain provides equivalent +capabilities through different servers (e.g. Firecrawl / Exa / +Tavily for web search; sourcegraph-cody for code graph), use +whatever you have connected. -| Tool | Purpose | Smoke test | -|---------------|--------------------------------------------------------|----------------------------------------------------------------------| -| Gemini Search | Grounded web search with citations | Call `mcp__gemini-search__search_with_grounding` with a simple query | -| GitNexus | Code knowledge graph (symbols, blast radius, clusters) | Call `mcp__gitnexus__list_repos` | +| Capability | Canonical example | Smoke test for the canonical example | +|---------------------------|-------------------|----------------------------------------------------------------------| +| Web search with citations | Gemini Search | Call `mcp__gemini-search__search_with_grounding` with a simple query | +| Code knowledge graph | GitNexus | Call `mcp__gitnexus__list_repos` | **Check procedure:** 1. Attempt each smoke test silently 2. For tools that respond: note as available (no output needed) -3. For tools that fail or are not connected: append a brief note - after the readback: - > "Companion tools: Gemini Search is not connected (web search - > will fall back to built-in). Install via MCP settings if - > needed." +3. For tools that fail or are not connected: silently fall back + to built-in capabilities. Emit no output. ctx does not vouch + for companion-tool install paths (see DECISIONS.md, + 2026-05-23 "MCP gateway not worth the coupling cost"). 4. For GitNexus specifically: if it responds but the current repo is not indexed or the index is stale, suggest: > "GitNexus index is stale: run `npx gitnexus analyze` to > rehydrate." -Present companion status as a one-line note after the readback, -not a separate section. If everything is healthy, say nothing. +Present companion status as a one-line note after the readback +only when there's something actionable (stale index). Absent +tools produce no output; the agent uses its built-in capabilities +transparently. ## Quality Checklist diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md index 4c947b202..c7450a022 100644 --- a/internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md +++ b/internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md @@ -131,29 +131,34 @@ Skip this section entirely if `companion_check: false` is set in the field value. **Companion tools** enhance ctx skills with web search and code -intelligence. They are optional but recommended: +intelligence. They are optional but recommended. ctx names canonical +implementations below; if your MCP toolchain provides equivalent +capabilities through different servers (e.g. Firecrawl / Exa / +Tavily for web search; sourcegraph-cody for code graph), use +whatever you have connected. -| Tool | Purpose | Smoke test | -|---------------|--------------------------------------------------------|----------------------------------------------------------------------| -| Gemini Search | Grounded web search with citations | Call `mcp__gemini-search__search_with_grounding` with a simple query | -| GitNexus | Code knowledge graph (symbols, blast radius, clusters) | Call `mcp__gitnexus__list_repos` | +| Capability | Canonical example | Smoke test for the canonical example | +|---------------------------|-------------------|----------------------------------------------------------------------| +| Web search with citations | Gemini Search | Call `mcp__gemini-search__search_with_grounding` with a simple query | +| Code knowledge graph | GitNexus | Call `mcp__gitnexus__list_repos` | **Check procedure:** 1. Attempt each smoke test silently 2. For tools that respond: note as available (no output needed) -3. For tools that fail or are not connected: append a brief note - after the readback: - > "Companion tools: Gemini Search is not connected (web search - > will fall back to built-in). Install via MCP settings if - > needed." +3. For tools that fail or are not connected: silently fall back + to built-in capabilities. Emit no output. ctx does not vouch + for companion-tool install paths (see DECISIONS.md, + 2026-05-23 "MCP gateway not worth the coupling cost"). 4. For GitNexus specifically: if it responds but the current repo is not indexed or the index is stale, suggest: > "GitNexus index is stale: run `npx gitnexus analyze` to > rehydrate." -Present companion status as a one-line note after the readback, -not a separate section. If everything is healthy, say nothing. +Present companion status as a one-line note after the readback +only when there's something actionable (stale index). Absent +tools produce no output; the agent uses its built-in capabilities +transparently. ## Quality Checklist diff --git a/specs/ctx-remember-silent-companion-fallback.md b/specs/ctx-remember-silent-companion-fallback.md new file mode 100644 index 000000000..47c59eb66 --- /dev/null +++ b/specs/ctx-remember-silent-companion-fallback.md @@ -0,0 +1,135 @@ +# ctx-remember: Silent Fallback for Absent Companion Tools + +`/ctx-remember`'s Companion Tool Check tells the agent to +surface an install hint to the user when a companion tool +(Gemini Search, GitNexus) is absent. This contradicts the +peer-MCP / not-vouched-for-by-ctx position recorded in +`DECISIONS.md` on 2026-05-23. Fix: silently fall back to +built-in capabilities; emit nothing for absent tools. + +## Problem + +`internal/assets/claude/skills/ctx-remember/SKILL.md` +(lines 142-150, with identical copies in the copilot-cli +and opencode skill variants) instructs the agent: + +``` +**Check procedure:** + +1. Attempt each smoke test silently +2. For tools that respond: note as available (no output needed) +3. For tools that fail or are not connected: append a brief note + after the readback: + > "Companion tools: Gemini Search is not connected (web search + > will fall back to built-in). Install via MCP settings if + > needed." +4. For GitNexus specifically: if it responds but the current repo + is not indexed or the index is stale, suggest: + > "GitNexus index is stale: run `npx gitnexus analyze` to + > rehydrate." +``` + +Step 3 surfaces "Install via MCP settings if needed" — a +soft pointer at an install path for a third-party tool ctx +doesn't ship. That's the same coupling pattern today's +DECISIONS.md entry rules out: + +> An MCP gateway through ctx would couple ctx to the +> lifecycle of every gatewayed tool. […] That coupling +> is a tax we don't want to pay for a tool we don't ship. + +A skill text that tells the user to install a specific +companion tool is a *softer* form of the same coupling: +ctx is implicitly vouching for the install path, the +version compatibility, and (when the install fails) the +support burden. The graceful fallback in steps 1-2 already +handles the functional case; step 3 adds noise that +contradicts the architectural stance. + +Step 4 is different: it triggers only when the tool IS +connected (the smoke test passed) and addresses a +working-tool's state. Refreshing a present tool is +operationally part of using it, not vouching for its +install. Step 4 stays. + +## Solution + +Two identical edits, one per skill copy that contains +the Companion Tool Check section: + +1. `internal/assets/claude/skills/ctx-remember/SKILL.md` +2. `internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md` + +(The opencode variant at +`internal/assets/integrations/opencode/skills/ctx-remember/SKILL.md` +is a shorter form that doesn't include the Companion Tool +Check section at all — nothing to fix there.) + +Each block becomes: + +``` +**Check procedure:** + +1. Attempt each smoke test silently +2. For tools that respond: note as available (no output needed) +3. For tools that fail or are not connected: silently fall + back to built-in capabilities. Emit no output. ctx does + not vouch for companion-tool install paths (see + DECISIONS.md, 2026-05-23 "MCP gateway not worth the + coupling cost"). +4. For GitNexus specifically: if it responds but the current + repo is not indexed or the index is stale, suggest: + > "GitNexus index is stale: run `npx gitnexus analyze` + > to rehydrate." + +Present companion status as a one-line note after the readback +only when there's something actionable (stale index). Absent +tools produce no output; the agent uses its built-in +capabilities transparently. +``` + +The closing paragraph also updates: "If everything is +healthy, say nothing" loses the implicit "say something if +anything is absent" reading. + +## Behavioral consequence + +Operators who currently see "Companion tools: Gemini +Search is not connected (web search will fall back to +built-in). Install via MCP settings if needed." after +each `/ctx-remember` invocation will stop seeing it. Their +sessions get quieter without losing capability — the +fallback to built-in search was already happening; only +the suggestion to install goes away. + +Operators who *want* the hint can re-enable companion +checks broadly via `companion_check: true` in `.ctxrc` +(the flag controls the entire section). The default of +"hint absent → silent" is the new contract. + +## Out of Scope + +- **Tool-agnostic skill language.** The skill still names + Gemini Search and GitNexus as the canonical companions. + Making skill language tool-agnostic (so a user with + Firecrawl + vLLM gets first-class treatment) is the + broader "skills hard-code specific tools" smell flagged + by the user — out of scope here, addressed via a + separate design pass. +- **Doctor / preflight changes.** `ctx doctor` and similar + diagnostic surfaces remain free to report companion-tool + availability; this spec is about the per-invocation + in-skill nag, not the diagnostic command surface. +- **`companion_check` semantics.** The flag still controls + whether the entire Companion Tool Check section runs. + No change to its default or meaning. + +## Verification + +- `grep -r "Install via MCP" internal/assets/` returns + zero matches. +- The three SKILL.md files have identical Check Procedure + blocks, all with the silent-fallback wording. +- `make lint` clean; no Go code changes. +- `go test ./...` clean (no test depends on the install-nag + text). diff --git a/specs/skill-audit-companion-tool-neutrality.md b/specs/skill-audit-companion-tool-neutrality.md new file mode 100644 index 000000000..a89819b79 --- /dev/null +++ b/specs/skill-audit-companion-tool-neutrality.md @@ -0,0 +1,208 @@ +# Skill Audit: Companion-Tool Neutrality in Body Text + +Rewrite the prescriptive references to GitNexus and Gemini +Search in the embedded skill bodies as capability-first +descriptions with the canonical tools listed as examples. +Honors the manifesto's "ctx is unopinionated about the +agent's toolchain" stance without contradicting the +2026-05-23 anti-MCP-gateway decision. + +## Problem + +Eight skill files name GitNexus and Gemini Search directly: + +- `claude/skills/ctx-refactor/SKILL.md` +- `claude/skills/ctx-explain/SKILL.md` +- `claude/skills/ctx-code-review/SKILL.md` +- `claude/skills/ctx-remember/SKILL.md` +- `claude/skills/ctx-architecture/SKILL.md` +- `claude/skills/ctx-architecture-enrich/SKILL.md` +- `claude/skills/ctx-architecture-failure-analysis/SKILL.md` +- `integrations/copilot-cli/skills/ctx-remember/SKILL.md` + +The references span three shapes: + +1. **External slash-command prescriptions** (e.g., + `/gitnexus-refactoring`) — assume the user has the + specific upstream skill suite installed. +2. **Tool-name prescriptions in instructions** (e.g., + "Use Gemini throughout the skill", "GitNexus MCP: + blast radius estimation") — assume one specific MCP + server is the chosen implementation of a capability. +3. **`allowed-tools` frontmatter listing specific MCP + server names** (`mcp__gitnexus__*`, `mcp__gemini-search__*`) + — Claude Code permission system; scopes which tools + the skill can invoke. + +Shapes 1 and 2 are pure text and prescribe specific +tools. A user with Firecrawl + sourcegraph-cody (or vLLM, +or Exa, or Tavily — pick your stack) reads the skill and +sees instructions naming tools they don't have. The +skill's capability-level intent is identical regardless +of which underlying MCP server provides it; only the +text is opinionated. + +Shape 3 is a real permission boundary and a different +problem class. Out of scope for this pass (see Out of +Scope below). + +## Solution + +Capability-first language with canonical tools as +examples. The pattern: + +| Prescriptive (before) | Capability-first (after) | +|---|---| +| "Use Gemini Search to look up …" | "Use a web-search-with-citations MCP if available (Gemini Search is the typical choice; equivalents include Firecrawl, Exa, Tavily) …" | +| "GitNexus MCP: blast radius estimation" | "A code-intelligence MCP (GitNexus is the canonical choice; equivalents include sourcegraph-cody) provides blast-radius estimation …" | +| "Use `/gitnexus-refactoring` if available" | "If you have an external refactoring-aware skill (e.g., the GitNexus suite ships `/gitnexus-refactoring`), invoke it; otherwise proceed with built-in reasoning." | +| "Install via MCP settings if needed" | (removed — covered by the companion-fallback fix that preceded this commit) | + +Per-file rewrite notes: + +### ctx-refactor (1 line) + +Replace `/gitnexus-refactoring` slash command with an +"if you have an external refactoring-aware skill, invoke +it" phrasing that names the GitNexus suite as the +canonical example. + +### ctx-explain (2 lines) + +Replace `/gitnexus-debugging` and `/gitnexus-exploring` +references with the same pattern. + +### ctx-code-review (1 line) + +Replace `/gitnexus-pr-review` reference with the same +pattern. + +### ctx-remember (tool table + companion check) + +Replace the prescriptive Gemini/GitNexus tool table with +a capability-first version. The Companion Tool Check +section already had its install-nag removed in the +preceding commit; this pass updates the table headers +above it. + +### ctx-architecture + +Rewrite the "Check if **Gemini Search** MCP is available" +section to "Check if a web-search-with-citations MCP is +available (Gemini Search is the typical choice)". Same +treatment for the principal-mode section that prescribes +Gemini specifically. + +### ctx-architecture-enrich + +Rewrite the GitNexus-required preamble and the install +procedure as "a code-intelligence MCP is required for +this skill (GitNexus is the typical choice; equivalents +work). If absent, the skill cannot run — its purpose IS +the code-graph verification pass." Keeps the +required-tool stance (the skill's purpose is unchanged) +while removing the GitNexus-specific install command. + +### ctx-architecture-failure-analysis + +Rewrite the "GitNexus MCP: blast radius" / "Gemini +Search: cross-reference" lines to name the capabilities, +list the canonical tools as examples, and let the agent +self-route based on what's connected. + +## Doc updates (follow-on within scope) + +After the SKILL.md rewrites landed, a check across `docs/` +surfaced six files that also named GitNexus and Gemini +Search prescriptively. Two categories: + +**Operational / descriptive docs** (rewritten to +capability-first matching the SKILL.md tone): + +- `docs/operations/runbooks/architecture-exploration.md` — + "via GitNexus" → "via a code-intelligence MCP (canonical: + GitNexus)"; preflight smoke-test wording; graceful-fail + rationale. +- `docs/recipes/architecture-deep-dive.md` — "graph-backed + data from GitNexus"; "Requires: GitNexus MCP server". +- `docs/reference/skills.md` — failure-analysis skill + description. +- `docs/cli/index.md` — `companion_check` field + parenthetical. + +**Install-guide docs** (kept concrete; added one-liner +naming equivalents): + +- `docs/home/getting-started.md` — Section 7's companion + tool sublist gains a "canonical examples; equivalents + work" preamble. The install commands stay because the + doc's purpose IS install guidance. +- `docs/recipes/multi-tool-setup.md` — Companion Tools + section preamble similarly clarifies that named tools + are canonical examples. Individual tool sections still + give concrete setup steps for the canonical impls. + +This split is intentional: when a doc's job is "tell me +how to install something," that doc names specific tools. +When a doc's job is "describe what a skill does," it +describes capabilities. The decision recorded in +`DECISIONS.md` (2026-05-23 "Skill body text uses +capability-first language; install-guide docs name +canonical implementations") captures the rule for +future contributors. + +## Out of Scope + +- **`allowed-tools` frontmatter genericization.** The + frontmatter at the top of each affected skill lists + specific MCP server name patterns (`mcp__gitnexus__*`, + `mcp__gemini-search__*`) to scope Claude Code's + permission grant. Replacing with `mcp__*` would grant + the skill access to *every* MCP server the user has — + a permission expansion, not just a cosmetic change. + Operators who use a different toolchain (sourcegraph, + vLLM, Firecrawl, etc.) need to edit `allowed-tools` + in their local skill copy or fork. A separate spec can + consider whether to template the allowlist; this pass + is body-text only. + +- **Tested-companions catalog in docs.** Option C from + the design discussion (a docs page listing known-good + third-party MCP tools by capability) is a follow-up + and out of this pass. Skills should be unopinionated + first; the catalog informs without prescribing later. + +- **Validating that named alternatives actually work.** + Mentioning Firecrawl, sourcegraph-cody, Exa, etc. as + examples is informational only — ctx does not guarantee + these alternatives have parity with the canonical tool. + Operators evaluate fit. + +## Verification + +- `grep -rE "use.* GitNexus|use.* Gemini" internal/assets/` + returns no prescriptive matches (instances should all be + "if available", "typical choice", or similar + capability-first phrasing). +- The 8 SKILL.md files compile through the existing + embed/audit tests unchanged (no metadata mutated). +- `make lint` clean; no Go code touched. +- `go test ./...` clean — no test depends on the specific + phrasing being audited. + +## Migration consequence + +Existing users with GitNexus + Gemini Search configured +see no behavioral change — the canonical tools are still +the first-listed examples in every section. Users with +different toolchains read the skill text and understand +the capability requirement rather than the tool +prescription. The agent self-routes based on what's +connected. + +For the architecture-enrich skill specifically, the +"required code-intelligence MCP" stance is unchanged — +the skill's entire purpose is code-graph enrichment, so +running it without ANY graph MCP makes no sense. The +text just names the capability instead of the specific +tool.