Feature: CLI parity with MCP + first-class plain markdown SKILL.md, so agents can use Gortex without paying the 175-tool context tax

[grantcarthew]

Summary

gortex install is the documented path to use Gortex from a coding agent. It wires the MCP server in and — by default — eagerly publishes 175 tool definitions into tools/list. Every one of those JSON schemas sits in the agent's context every turn, used or not. For agents that don't want a constantly-loaded MCP surface, there is no first-class alternative: the CLI exposes only a fraction of the daemon's capabilities, and there is no shipped, low-cost markdown skill for on-demand use.

This issue asks for two things together:

1. A plain-markdown SKILL.md shipped with Gortex, designed to be dropped into ~/.claude/skills/gortex/ (or any agent's user-level skill surface) and loaded on demand — no MCP transport, no install step, no permanent context cost.
2. CLI parity with the MCP surface for the edit-safety and memory tool families, so the skill above can actually orchestrate the workflows the project already documents as mandatory in CLAUDE.md.

The two are inseparable: a markdown skill is only useful to the extent the CLI underneath can do the work it describes.

Context cost problem

tools/list carries the full schema of every registered tool. With 175 tools eagerly published, that's a substantial baseline token cost on every turn, regardless of whether any Gortex tool is called.

The project already acknowledges this — GORTEX_LAZY_TOOLS=1 exists precisely to defer registration and let the agent discover tools on demand via tools_search. That helps, but:

• It still requires the MCP transport and the install step.
• It still requires the host to honour notifications/tools/list_changed.
• It is a workaround inside the MCP model, not an alternative to it.

For agents that don't want any MCP surface mounted, or that want to load Gortex capabilities only for the subset of sessions that need them, the cheap option today is to shell gortex from a markdown skill. That works — until you hit the coverage gap.

CLI coverage gap

The CLI is already daemon-backed. cmd/gortex/query.go shows the pattern: requireDaemonTool(repoPath, \"<mcp-tool>\", args) shells the daemon's executor and calls the same MCP tool handler the server uses. There is no architectural reason every MCP tool can't have a matching CLI verb.

Today's CLI covers roughly 25 verbs — read-side queries (query symbol/usages/callers/deps/dependents/implementations/calls/stats) plus rendered verdicts (review, audit, wakeup, context, docs, prs). The MCP surface is ~175 tools. The workhorses the CLAUDE.md "MANDATORY workflow" instructs the agent to call are CLI-missing:

Edit-safety pipeline (none of these have CLI verbs):

• smart_context — the entry point for every new task
• get_editing_context — required before editing a file
• verify_change — required before changing a function signature
• get_edit_plan — dependency-ordered refactor plan
• batch_edit — atomic multi-file apply
• preview_edit / simulate_chain — speculative execution
• check_guards — required after every edit
• get_test_targets — required after every edit
• change_contract — pre-commit verdict
• safe_delete_symbol

Memory layer (none of these have CLI verbs):

• save_note / query_notes / distill_session — session memory
• store_memory / query_memories / surface_memories — durable memory

Other high-value tools without CLI parity:

• analyze (61 kinds) — only fragments are reachable via audit / review
• flow_between, taint_paths
• find_clones, find_co_changing_symbols
• Overlay sessions (overlay_push / overlay_list / overlay_drop)
• feedback — required by the documented workflow to improve future context

So the trade today is binary: pay the 175-def context tax for the full surface, or use the CLI and lose every guardrail and memory step the project itself calls mandatory.

Ask

1. Add CLI verbs for the edit-safety, memory, and analysis tools listed above. They can be thin shells over the same handlers — the executor plumbing already exists. Reasonable groupings: gortex edit ... (context / verify / plan / preview / batch / guards / test-targets), gortex memory ... (note / memory / distill / surface), gortex analyze --kind <one-of-61>.

2. Ship a plain-markdown SKILL.md alongside the existing per-community generated skills — a single user-level skill that drives Gortex via the CLI, loaded on demand. Frontmatter triggers on Gortex-related work; body walks the same workflow CLAUDE.md documents (stats → smart_context → surface_memories → get_editing_context → verify_change → batch_edit → check_guards → get_test_targets → feedback), with every step expressed as a gortex shell command. No MCP transport required.

3. Document the skill+CLI path as a first-class consumption pattern in docs/skills.md, alongside the MCP/install path. Make the trade explicit: full surface via MCP (high context baseline, push notifications, overlay sessions) vs. on-demand surface via skill+CLI (zero baseline, no push channels, no overlays).

Why this is worth doing

• Lowers the barrier for any coding agent that doesn't support MCP, or where MCP is impractical.
• Gives MCP-capable agents a low-context fallback for sessions that don't need the full surface.
• Closes the gap between what CLAUDE.md says is mandatory and what is reachable without MCP.
• Aligns with the project's own framing in the README — "access via CLI, MCP Server, and API" — by making the CLI path actually competitive with the MCP one.

Out of scope

• Push notifications (subscribe_*) — fundamentally streaming, don't fit a CLI shape.
• Overlay sessions tied to MCP session lifecycle — can be CLI-exposed but require explicit session-id handling and are a separate design.

[caioribeiroclw-pixel]

I like this framing: the real unit is not “MCP vs CLI”, it is whether the agent paid a permanent capability-discovery cost before the task needed Gortex.

One acceptance test I would add: make the low-cost path emit a small context budget receipt for the session, so the tradeoff is measurable instead of just architectural.

Something like:

gortex_context_budget:
  transport: skill_cli # or mcp_full, mcp_lazy
  repo: <path-or-hash>
  advertised_tools: 175
  registered_tool_schemas: 0
  registered_schema_bytes: 0
  registered_schema_hash: null
  skill_bytes: 4200
  skill_hash: sha256:...
  cli_verbs_used:
    - query stats
    - edit smart-context
    - edit get-editing-context
    - edit verify-change
    - edit check-guards
  deferred_capabilities:
    count: 170
    reason: not needed for this task
  unavailable_capabilities:
    - subscribe_*
    - overlay session lifecycle
  model_reported_context_pct_before: <optional>
  model_reported_context_pct_after: <optional>
  decision: full_surface_not_mounted

Then the fixture can compare three paths for the same edit-safety workflow:

1. full MCP install: registered_tool_schemas > 0, high baseline, full surface;
2. lazy MCP: smaller initial list, requires tools_search/list-changed support;
3. SKILL.md + CLI: no mounted MCP surface, but the receipt proves which safety/memory steps were actually run.

That would make the issue easier to validate because “175-tool context tax avoided” becomes an artifact reviewers can inspect. It also prevents the opposite failure mode: a cheap skill path that silently skips verify_change, check_guards, or feedback and only feels equivalent because the prompt says it is.

[zzet]

@grantcarthew @caioribeiroclw-pixel with the fe50eda the default tool set limited to end-to-end code and analysis (~30 tools). However, the CLI parity is what was planned but wasn't implemented yet.

Overall, the main issue was in the 'context' where MCP initially was a stateful session store, however it is not a problem/blocker anymore after the implementation a new MCP standard. Said that, the CLI parity and configurations options are going to be wired soon.

The core idea around the Gortex is not tell users how to do their job, but provide stable and flexible tooling they can integrate into their workflow with a full flexibility. The CLI surface giving the most flexibility (but sometimes hardest to navigate models to use it properly, or harder than in case of tools).