Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

feat(agents): add the Basic tier and an Indexing column (#3169)

Raghav Chamadiya03e00bb0e09e
diff --git a/README.md b/README.md
index 9bddf58b7..d078e193b 100644
--- a/README.md
+++ b/README.md
@@ -537,16 +537,19 @@ paste away.**
</p>
<p>
<strong>Good tier &nbsp;</strong>
- <img src="https://img.shields.io/badge/VS_Code-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white" alt="VS Code" />
<img src="https://img.shields.io/badge/Cursor-000000?style=flat-square&logo=cursor&logoColor=white" alt="Cursor" />
<img src="https://img.shields.io/badge/OpenCode-000000?style=flat-square&logo=opencode&logoColor=white" alt="OpenCode" />
<img src="https://img.shields.io/badge/Hermes-000000?style=flat-square&logoColor=white" alt="Hermes" />
</p>
+<p>
+ <strong>Basic tier &nbsp;</strong>
+ <img src="https://img.shields.io/badge/VS_Code-007ACC?style=flat-square&logo=visualstudiocode&logoColor=white" alt="VS Code" />
+</p>
**Full** is every surface Repowise has: MCP tools, skills, slash commands, a managed
instructions file, hook-level interception of tool calls, and transcript mining after
-the session. **Good** is MCP tools and the config to reach them, without hooks or
-transcript mining. Anything else that speaks MCP is one snippet away:
+the session. **Good** is MCP tools plus an instructions file or skills, without hooks
+or transcript mining. **Basic** is the MCP config alone. Anything else that speaks MCP is one snippet away:
`repowise agents print-config claude-code` prints a server entry for Cline, Windsurf,
Zed, Gemini CLI or any host that reads `mcpServers`.
[Integration matrix →](docs/agent/INTEGRATIONS.md)
diff --git a/docs/agent/INTEGRATIONS.md b/docs/agent/INTEGRATIONS.md
index 4ccf56061..f5be9b10f 100644
--- a/docs/agent/INTEGRATIONS.md
+++ b/docs/agent/INTEGRATIONS.md
@@ -10,33 +10,37 @@ every breadth claim in this space gets wrong.
## Tiers
The tier is **derived from the code, never declared**. A descriptor reaches
-Full only by naming both a hook adapter and a transcript adapter, so no
-document can claim a depth the integration does not have.
+Full only by naming both a hook adapter and a transcript adapter, and Good
+only by wiring instructions or skills beside MCP, so no document can claim
+a depth the integration does not have.
- **Full.** MCP tools, a managed instructions file, skills, slash commands, hook-level interception of tool calls, and transcript mining after the fact. Every surface repowise has.
-- **Good.** MCP tools, and a managed instructions file or skills where the host reads them. **No hook-level interception and no transcript mining.** The agent can ask repowise questions; repowise cannot see or annotate what the agent does in between.
+- **Good.** MCP tools plus a managed instructions file or skills, so the agent is told when to reach for them. **No hook-level interception and no transcript mining.** The agent can ask repowise questions; repowise cannot see or annotate what the agent does in between.
+- **Basic.** repowise writes the MCP server config and nothing else. The tools are there; no instructions file or skill tells the agent when to use them.
- **Paste-config.** `repowise agents print-config <id>` emits the MCP server snippet and we write nothing. Zero code and zero maintenance per host.
## The matrix
`Yes` means repowise wires it. `Plugin` means the host's own plugin ships
it and repowise does not write it. `No` means the surface does not exist
-for that agent.
-
-| Agent | Tier | MCP | Hooks | Skills | Commands | Instructions | Transcripts |
-|---|---|---|---|---|---|---|---|
-| [Claude Code](https://docs.claude.com/en/docs/claude-code) | Full | Yes | Yes | Plugin | Plugin | Yes | Yes |
-| [Codex CLI](https://developers.openai.com/codex/cli) | Full | Yes | Yes | Plugin | Yes | Yes | Yes |
-| [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Good | Yes | No | No | No | No | No |
-| [Cursor](https://cursor.com/docs/context/mcp) | Good | Yes | No | No | No | Yes | No |
-| [OpenCode](https://opencode.ai/docs/mcp-servers/) | Good | Yes | No | No | No | Yes | No |
-| [Hermes](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Good | Yes | No | No | No | Yes | No |
+for that agent. `Indexing` is `Yes` when the agent's own CLI can run as the
+LLM that writes the index, selected by its provider id (`claude_cli`, for
+example). It is separate from the tier: it says nothing about the session.
+
+| Agent | Tier | MCP | Hooks | Skills | Commands | Instructions | Transcripts | Indexing |
+|---|---|---|---|---|---|---|---|---|
+| [Claude Code](https://docs.claude.com/en/docs/claude-code) | Full | Yes | Yes | Plugin | Plugin | Yes | Yes | Yes |
+| [Codex CLI](https://developers.openai.com/codex/cli) | Full | Yes | Yes | Plugin | Yes | Yes | Yes | Yes |
+| [VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) | Basic | Yes | No | No | No | No | No | No |
+| [Cursor](https://cursor.com/docs/context/mcp) | Good | Yes | No | No | No | Yes | No | No |
+| [OpenCode](https://opencode.ai/docs/mcp-servers/) | Good | Yes | No | No | No | Yes | No | Yes |
+| [Hermes](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Good | Yes | No | No | No | Yes | No | No |
Target ids for `--target=`: `claude-code`, `codex`, `vscode`, `cursor`, `opencode`, `hermes`.
### What Good tier does not include
-VS Code, Cursor, OpenCode and Hermes sit at Good, and the honest version of that is worth stating
+Cursor, OpenCode and Hermes sit at Good, and the honest version of that is worth stating
plainly. These agents get the MCP tools and the config repowise writes.
They do **not** get hook-level interception: repowise never sees a tool
call before it runs, never rewrites a noisy command, and never annotates
@@ -47,6 +51,12 @@ That is a real integration and it is most of the value. It is not the
same product Full-tier agents get, and breadth that overclaims depth is
worse than narrower breadth.
+### Basic tier
+
+VS Code sits at Basic. repowise writes
+no instructions file or skills there, so the MCP tools are reachable but
+nothing tells the agent when to use them.
+
## Paste-config
Every other MCP host is served without writing a descriptor for it. Print
@@ -83,20 +93,33 @@ Per-tool detail: [MCP_TOOLS.md](MCP_TOOLS.md).
## Adding an agent
-**Adding an agent takes one descriptor file and one registry line.**
+**Adding an agent takes one identity record, one descriptor file and one
+registry line.**
-1. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`
+1. Add an `AgentIdentity` to
+ [`identity.py`](../../packages/core/src/repowise/core/agents/identity.py):
+ its slug, display name, `executable` and, if its CLI can index,
+ `indexing_provider`.
+2. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`
exporting a `TARGET` that satisfies the `AgentTarget` protocol in
[`types.py`](../../packages/cli/src/repowise/cli/agent_targets/types.py).
`vscode.py` is the smallest working example, at one install method and
one config file.
-2. Add one line to `_TARGET_MODULES` in
+3. Add one line to `_TARGET_MODULES` in
[`registry.py`](../../packages/cli/src/repowise/cli/agent_targets/registry.py).
Order there is the order agents appear in prompts, in `--target=all` and
in listings, so keep it stable.
-3. Run `python scripts/gen_agent_matrix.py` to add the row here.
+4. Run `python scripts/gen_agent_matrix.py` to add the row here.
+
+An indexing backend adds three more pieces: a `ProviderSpec` in
+[`specs.py`](../../packages/core/src/repowise/core/providers/llm/specs.py),
+an `AgentCliProvider` subclass in
+[`agent_cli.py`](../../packages/core/src/repowise/core/providers/llm/agent_cli.py),
+and one `Backend` entry in
+`tests/unit/test_providers/test_agent_cli_contract.py`, which runs the shared
+provider contract against it.
-There is no third file for anything derived. The tier, this matrix and the
+There is no further file for anything derived. The tier, this matrix and the
`repowise agents` listing all read the descriptor, and the contract tests in
`tests/unit/cli/test_agent_targets.py` are parameterized over the registry,
so a new target inherits them.
diff --git a/docs/agent/VSCODE.md b/docs/agent/VSCODE.md
index 0a281c64f..ca8682932 100644
--- a/docs/agent/VSCODE.md
+++ b/docs/agent/VSCODE.md
@@ -106,9 +106,10 @@ assistants query the index through purpose-built tools instead of guessing from
open files. For editors that read a config file, run **Repowise: Configure MCP
for this Workspace** to write `.vscode/mcp.json`.
-VS Code sits at the **Good** support tier, and the honest version of that is
+VS Code sits at the **Basic** support tier, and the honest version of that is
worth knowing before you compare it to the Claude Code or Codex setup. You get
-the MCP tools and the config to reach them. You do not get hook-level
+the MCP tools and the config to reach them, but no managed instructions file or
+skills telling the agent when to use them. You do not get hook-level
interception: repowise never sees a tool call before it runs, never rewrites a
noisy command, and never annotates a result afterwards, and there is no
transcript mining after the session. What the extension itself surfaces in the
diff --git a/packages/cli/src/repowise/cli/agent_targets/targets/vscode.py b/packages/cli/src/repowise/cli/agent_targets/targets/vscode.py
index 190d1b6f7..48197c8d3 100644
--- a/packages/cli/src/repowise/cli/agent_targets/targets/vscode.py
+++ b/packages/cli/src/repowise/cli/agent_targets/targets/vscode.py
@@ -1,10 +1,10 @@
"""VS Code as an agent target.
-Good tier, and the descriptor makes that structural rather than editorial: it
-names neither a hook adapter nor a transcript adapter, so :func:`derive_tier`
-cannot place it at Full however many files it writes. VS Code gets the MCP
-server and an extension recommendation; it has no hook protocol for repowise to
-intercept tool calls through, and no transcript format to mine.
+Basic tier, and the descriptor makes that structural rather than editorial: it
+names neither a hook adapter nor a transcript adapter, and wires MCP without
+instructions or skills, so :func:`derive_tier` places it at Basic. VS Code gets
+the MCP server and an extension recommendation; it has no hook protocol for
+repowise to intercept tool calls through, and no transcript format to mine.
The distinguishing quirk is that both files it writes may legally contain
comments — VS Code accepts JSONC throughout ``.vscode/``. So this target is the
diff --git a/packages/cli/src/repowise/cli/agent_targets/types.py b/packages/cli/src/repowise/cli/agent_targets/types.py
index 0c12303da..b4f3f97b1 100644
--- a/packages/cli/src/repowise/cli/agent_targets/types.py
+++ b/packages/cli/src/repowise/cli/agent_targets/types.py
@@ -108,6 +108,7 @@ class Tier(StrEnum):
FULL = "full"
GOOD = "good"
+ BASIC = "basic"
PASTE_CONFIG = "paste-config"
@@ -459,8 +460,10 @@ def derive_tier(target: AgentTarget) -> Tier:
faked by writing a config file. Requiring both is what makes it
structurally impossible for the docs to claim Full while the session
adapter is missing.
- * Everything else is **Good**: a real integration, MCP and instructions and
- possibly skills, but no hook-level interception.
+ * A target that wires MCP plus managed instructions or skills is **Good**:
+ the agent is told repowise exists, but nothing intercepts its tool calls.
+ * Everything else is **Basic**: repowise writes the MCP config and nothing
+ that tells the agent when to use it.
Deliberately strict about Full. Breadth that overclaims depth is worse than
narrower breadth, and the tier is the thing the README badges repeat.
@@ -469,4 +472,7 @@ def derive_tier(target: AgentTarget) -> Tier:
return Tier.PASTE_CONFIG
if target.hook_adapter and target.session_adapter:
return Tier.FULL
- return Tier.GOOD
+ caps = capabilities_of(target)
+ if Capability.MCP in caps and caps & {Capability.INSTRUCTIONS, Capability.SKILLS}:
+ return Tier.GOOD
+ return Tier.BASIC
diff --git a/scripts/gen_agent_matrix.py b/scripts/gen_agent_matrix.py
index 7c27cfad1..5e3ab86a9 100644
--- a/scripts/gen_agent_matrix.py
+++ b/scripts/gen_agent_matrix.py
@@ -73,10 +73,15 @@ TIER_BLURBS: dict[str, tuple[str, str]] = {
),
"good": (
"Good",
- "MCP tools, and a managed instructions file or skills where the host "
- "reads them. **No hook-level interception and no transcript mining.** "
- "The agent can ask repowise questions; repowise cannot see or annotate "
- "what the agent does in between.",
+ "MCP tools plus a managed instructions file or skills, so the agent is "
+ "told when to reach for them. **No hook-level interception and no "
+ "transcript mining.** The agent can ask repowise questions; repowise "
+ "cannot see or annotate what the agent does in between.",
+ ),
+ "basic": (
+ "Basic",
+ "repowise writes the MCP server config and nothing else. The tools are "
+ "there; no instructions file or skill tells the agent when to use them.",
),
"paste-config": (
"Paste-config",
@@ -102,6 +107,7 @@ def agent_rows() -> list[dict]:
"""
from repowise.cli.agent_targets import registry
from repowise.cli.agent_targets.types import Capability, derive_tier
+ from repowise.core.agents.identity import identity_for_target_id
rows: list[dict] = []
for target in registry.all_targets():
@@ -113,6 +119,7 @@ def agent_rows() -> list[dict]:
for method in target.methods:
key = "host" if method.managed_by == "host" else "repowise"
by_manager[key] |= set(method.provides)
+ identity = identity_for_target_id(target.id)
rows.append(
{
"id": target.id,
@@ -123,6 +130,7 @@ def agent_rows() -> list[dict]:
"host": by_manager["host"],
"hook_adapter": target.hook_adapter,
"session_adapter": target.session_adapter,
+ "indexing_provider": identity.indexing_provider if identity else None,
}
)
return rows
@@ -219,21 +227,23 @@ def spell(count: int) -> str:
# Render
# ---------------------------------------------------------------------------
-#: Column caption, and the capability it reads. ``None`` means the column is
-#: derived from an adapter name rather than from a declared capability.
-_COLUMNS: tuple[tuple[str, str | None], ...] = (
+#: Column caption, and the capability it reads. A row key instead means the
+#: column is derived from that field (an adapter or provider name), not from a
+#: declared capability.
+_COLUMNS: tuple[tuple[str, str], ...] = (
("MCP", "mcp"),
("Hooks", "hooks"),
("Skills", "skills"),
("Commands", "commands"),
("Instructions", "instructions"),
- ("Transcripts", None),
+ ("Transcripts", "session_adapter"),
+ ("Indexing", "indexing_provider"),
)
-def _cell(row: dict, capability: str | None) -> str:
- if capability is None:
- return "Yes" if row["session_adapter"] else "No"
+def _cell(row: dict, capability: str) -> str:
+ if capability in row:
+ return "Yes" if row[capability] else "No"
from repowise.cli.agent_targets.types import Capability
wanted = Capability(capability)
@@ -282,6 +292,7 @@ def render() -> str:
counts = tool_counts()
ids = ", ".join(f"`{row['id']}`" for row in rows)
good = [row["display_name"] for row in rows if row["tier"] == "good"]
+ basic = [row["display_name"] for row in rows if row["tier"] == "basic"]
parts = [
"# Agent integrations",
@@ -296,8 +307,9 @@ def render() -> str:
"## Tiers",
"",
"The tier is **derived from the code, never declared**. A descriptor reaches",
- "Full only by naming both a hook adapter and a transcript adapter, so no",
- "document can claim a depth the integration does not have.",
+ "Full only by naming both a hook adapter and a transcript adapter, and Good",
+ "only by wiring instructions or skills beside MCP, so no document can claim",
+ "a depth the integration does not have.",
"",
_tier_list(),
"",
@@ -305,7 +317,9 @@ def render() -> str:
"",
"`Yes` means repowise wires it. `Plugin` means the host's own plugin ships",
"it and repowise does not write it. `No` means the surface does not exist",
- "for that agent.",
+ "for that agent. `Indexing` is `Yes` when the agent's own CLI can run as the",
+ "LLM that writes the index, selected by its provider id (`claude_cli`, for",
+ "example). It is separate from the tier: it says nothing about the session.",
"",
_matrix_table(rows),
"",
@@ -331,6 +345,16 @@ def render() -> str:
"",
]
+ if basic:
+ parts += [
+ "### Basic tier",
+ "",
+ f"{_join_names(basic)} {'sits' if len(basic) == 1 else 'sit'} at Basic. repowise writes",
+ "no instructions file or skills there, so the MCP tools are reachable but",
+ "nothing tells the agent when to use them.",
+ "",
+ ]
+
parts += [
"## Paste-config",
"",
@@ -375,20 +399,33 @@ def render() -> str:
"",
"## Adding an agent",
"",
- "**Adding an agent takes one descriptor file and one registry line.**",
+ "**Adding an agent takes one identity record, one descriptor file and one",
+ "registry line.**",
"",
- "1. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`",
+ "1. Add an `AgentIdentity` to",
+ " [`identity.py`](../../packages/core/src/repowise/core/agents/identity.py):",
+ " its slug, display name, `executable` and, if its CLI can index,",
+ " `indexing_provider`.",
+ "2. Write `packages/cli/src/repowise/cli/agent_targets/targets/<id>.py`",
" exporting a `TARGET` that satisfies the `AgentTarget` protocol in",
" [`types.py`](../../packages/cli/src/repowise/cli/agent_targets/types.py).",
" `vscode.py` is the smallest working example, at one install method and",
" one config file.",
- "2. Add one line to `_TARGET_MODULES` in",
+ "3. Add one line to `_TARGET_MODULES` in",
" [`registry.py`](../../packages/cli/src/repowise/cli/agent_targets/registry.py).",
" Order there is the order agents appear in prompts, in `--target=all` and",
" in listings, so keep it stable.",
- "3. Run `python scripts/gen_agent_matrix.py` to add the row here.",
+ "4. Run `python scripts/gen_agent_matrix.py` to add the row here.",
+ "",
+ "An indexing backend adds three more pieces: a `ProviderSpec` in",
+ "[`specs.py`](../../packages/core/src/repowise/core/providers/llm/specs.py),",
+ "an `AgentCliProvider` subclass in",
+ "[`agent_cli.py`](../../packages/core/src/repowise/core/providers/llm/agent_cli.py),",
+ "and one `Backend` entry in",
+ "`tests/unit/test_providers/test_agent_cli_contract.py`, which runs the shared",
+ "provider contract against it.",
"",
- "There is no third file for anything derived. The tier, this matrix and the",
+ "There is no further file for anything derived. The tier, this matrix and the",
"`repowise agents` listing all read the descriptor, and the contract tests in",
"`tests/unit/cli/test_agent_targets.py` are parameterized over the registry,",
"so a new target inherits them.",
diff --git a/tests/unit/cli/test_agent_identity.py b/tests/unit/cli/test_agent_identity.py
index 3a4afa7c7..8f7b8019a 100644
--- a/tests/unit/cli/test_agent_identity.py
+++ b/tests/unit/cli/test_agent_identity.py
@@ -5,8 +5,8 @@ same reason ``test_agent_targets.py`` is: the property under test is that the
seam holds for *every* registered target, and a per-agent test file would
quietly not have that property for the next one added.
-``INTEGRATIONS.md`` promises adding an agent costs one descriptor file and one
-registry line. The tests at the bottom are what stops savings attribution from
+``INTEGRATIONS.md`` promises adding an agent costs one identity record, one
+descriptor file and one registry line. The tests at the bottom are what stops savings attribution from
silently not being included in that promise.
"""
diff --git a/tests/unit/cli/test_agent_matrix.py b/tests/unit/cli/test_agent_matrix.py
index edbf30da0..ea696d2a7 100644
--- a/tests/unit/cli/test_agent_matrix.py
+++ b/tests/unit/cli/test_agent_matrix.py
@@ -190,6 +190,16 @@ def test_the_readme_agent_headline_counts_the_registry() -> None:
)
+def test_the_indexing_column_matches_the_identities() -> None:
+ """Indexing is derived from ``indexing_provider``, never declared per row."""
+ from repowise.core.agents.identity import identity_for_target_id
+
+ for row in GEN.agent_rows():
+ identity = identity_for_target_id(row["id"])
+ expected = "Yes" if identity and identity.indexing_provider else "No"
+ assert GEN._cell(row, "indexing_provider") == expected, row["id"]
+
+
def test_the_hooks_column_cannot_lie() -> None:
"""A target's declared HOOKS capability agrees with its hook adapter.
diff --git a/tests/unit/cli/test_agent_targets.py b/tests/unit/cli/test_agent_targets.py
index 905a24867..38713272d 100644
--- a/tests/unit/cli/test_agent_targets.py
+++ b/tests/unit/cli/test_agent_targets.py
@@ -122,7 +122,7 @@ def test_tiers_are_derived_from_the_adapters_a_target_names() -> None:
"""Full requires both deep surfaces; VS Code has neither, so it cannot claim it."""
assert tier_of("claude-code") is Tier.FULL
assert tier_of("codex") is Tier.FULL
- assert tier_of("vscode") is Tier.GOOD
+ assert tier_of("vscode") is Tier.BASIC
assert tier_of("cursor") is Tier.GOOD
assert tier_of("opencode") is Tier.GOOD
assert tier_of("hermes") is Tier.GOOD
@@ -147,6 +147,35 @@ def test_a_target_cannot_reach_full_without_a_session_adapter() -> None:
assert derive_tier(_HooksOnly()) is Tier.GOOD
+ ("provides", "tier"),
+ [
+ ({"mcp"}, Tier.BASIC),
+ ({"mcp", "instructions"}, Tier.GOOD),
+ ({"mcp", "skills"}, Tier.GOOD),
+ ],
+)
+def test_good_needs_instructions_or_skills_beside_mcp(provides: set[str], tier: Tier) -> None:
+ """MCP alone is Basic; the capability set decides, not having methods at all."""
+ from repowise.cli.agent_targets.types import Capability, InstallMethod
+
+ class _Wired:
+ id = "wired"
+ display_name = "Wired"
+ docs_url = None
+ hook_adapter = None
+ session_adapter = None
+ methods = (
+ InstallMethod(
+ id="direct",
+ provides=frozenset(Capability(c) for c in provides),
+ managed_by="repowise",
+ ),
+ )
+
+ assert derive_tier(_Wired()) is tier
+
+
def test_a_target_that_writes_nothing_is_paste_config() -> None:
class _Snippet:
id = "snippet"
diff --git a/tests/unit/cli/test_agents_cmd.py b/tests/unit/cli/test_agents_cmd.py
index 1a02b033d..879142c3c 100644
--- a/tests/unit/cli/test_agents_cmd.py
+++ b/tests/unit/cli/test_agents_cmd.py
@@ -82,7 +82,7 @@ def test_bare_agents_lists_every_registered_target_as_json(repo: Path) -> None:
# The keys the table renders, so a dropped one is a broken table.
assert set(row) >= {"id", "tier", "present", "registrations", "method"}
assert payload["agents"][0]["tier"] == "full"
- assert payload["agents"][2]["tier"] == "good"
+ assert payload["agents"][2]["tier"] == "basic"
def test_list_reports_registrations_as_a_list_not_a_boolean(repo: Path) -> None: