Fix/ctx remember companion install nag#102
Merged
Merged
Conversation
/ctx-remember's Companion Tool Check (step 3) instructed the
agent to surface "Companion tools: Gemini Search is not
connected (web search will fall back to built-in). Install
via MCP settings if needed." to the user when a companion
tool was absent.
That contradicts the peer-MCP / not-vouched-for-by-ctx
position recorded in DECISIONS.md on 2026-05-23 ("MCP gateway
not worth the coupling cost"). Pointing users at "Install via
MCP settings if needed" is a soft form of vouching — ctx is
implicitly recommending an install path, version compatibility,
and (when the install fails) the support burden, for a tool we
don't ship.
Step 3 becomes "silently fall back to built-in capabilities.
Emit no output." The graceful fallback in steps 1-2 already
handles the functional case; removing the nag aligns the
skill text with the architectural stance.
Step 4 (stale-index suggestion) stays — it triggers only when
the tool IS connected, addressing a working-tool's state. That's
operational, not a vouching question.
Two identical SKILL.md copies edited (claude + copilot-cli).
The opencode variant doesn't include the Companion Tool Check
section at all — nothing to fix there.
Operator-facing consequence: /ctx-remember sessions get quieter
when companions are absent. Capability unchanged (the fallback
was already happening). Operators who want the hint can rebuild
it themselves; ctx no longer pushes it.
Spec: specs/ctx-remember-silent-companion-fallback.md
Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Eight skill files prescribed specific MCP tools by name (GitNexus, Gemini Search, /gitnexus-* slash commands). Rewrote each prescription as a capability description with the canonical tool listed as an example. Honors the manifesto's "ctx is unopinionated about the agent's toolchain" stance and aligns the body text with today's 2026-05-23 anti-vouching position recorded in DECISIONS.md. Pattern: - "Use Gemini Search to look up …" becomes "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" becomes "A code-intelligence MCP (canonical: GitNexus; equivalents include sourcegraph-cody) provides blast-radius estimation …" - "Use `/gitnexus-debugging`" becomes "If you have an external debugging-aware skill (the GitNexus suite ships `/gitnexus-debugging`), invoke it; otherwise proceed with built-in reasoning." Files updated: - ctx-refactor: rename-aware skill reference - ctx-explain: debugging + flow-tracing slash command refs - ctx-code-review: PR-review slash command ref - ctx-remember: companion tool table headers (claude + copilot-cli variants) - ctx-architecture: Phase 0.25 Companion Tool Check; the principal-mode "Exception: if Gemini Search is available" rule - ctx-architecture-enrich: tool preflight, install instructions, "When NOT to Use" line - ctx-architecture-failure-analysis: capability descriptions in Inputs, Phase 4 blast-radius/cross-reference steps, quality checklist Out of scope (deliberately): - The `allowed-tools` frontmatter at the top of each skill still lists specific MCP server names (mcp__gitnexus__*, mcp__gemini-search__*). Genericizing to mcp__* would grant the skill 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. - Body lines that name GitNexus operationally (e.g., audit trail "enriched via GitNexus", or `mcp__gitnexus__impact` example call signatures) stay as-is. Those are correct references to the canonical implementation; the audit rewrites prescriptive language, not operational examples. - A docs/companions/ catalog of tested third-party MCPs by capability is a follow-up. Operator-facing consequence: users with GitNexus + Gemini Search see no change (the canonical tools are still first-listed in every section). Users with different toolchains read the skill and understand the capability requirement rather than the tool prescription. The agent self-routes based on what's connected. Spec: specs/skill-audit-companion-tool-neutrality.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Follow-on to f554f75 (SKILL.md audit). Six docs/ files also named GitNexus and Gemini Search prescriptively; rewrote per the same capability-first pattern, with a deliberate split: **Operational / descriptive docs** (capability-first): - 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: Pass 2 inputs + Requires section. - docs/reference/skills.md: ctx-architecture-failure-analysis description. - docs/cli/index.md: companion_check field parenthetical. **Install-guide docs** (kept concrete, added equivalents disclaimer): - docs/home/getting-started.md: Section 7 preamble notes named tools are canonical examples; install commands stay because the doc's job IS install guidance. - docs/recipes/multi-tool-setup.md: Companion Tools section preamble similarly clarifies; individual tool sections still give concrete setup steps for the canonical impls. The split is intentional: when a doc's job is "tell me how to install something," it names specific tools. When a doc's job is "describe what a skill does," it describes capabilities. Genericizing install commands would harm newcomers; describing skills with hard-coded tool names is the smell this audit fixes. DECISIONS.md entry added formalizing the three-layer rule: 1. Skill body text uses capability-first language with canonical tools as examples. 2. Install-guide docs name canonical implementations directly. 3. allowed-tools frontmatter stays MCP-specific (genericizing would expand the permission grant). New skill authors and future contributors inherit the rule via DECISIONS.md without re-deriving it. Pairs with the prior 2026-05-23 MCP-gateway decision. Also amended specs/skill-audit-companion-tool-neutrality.md with a "Doc updates" section so the spec accurately covers the full scope of work done across both commits. Spec: specs/skill-audit-companion-tool-neutrality.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
No description provided.