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(codex): bring skill guidance to Claude parity (#1016)

Felix-Ayush4f85a02ffd2a
diff --git a/plugins/codex/.codex-plugin/plugin.json b/plugins/codex/.codex-plugin/plugin.json
index 5c4a1cce6..103624a40 100644
--- a/plugins/codex/.codex-plugin/plugin.json
+++ b/plugins/codex/.codex-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "codex",
- "version": "0.2.1",
+ "version": "0.2.2",
"description": "Repowise codebase intelligence for Codex.",
"author": {
"name": "Repowise",
diff --git a/plugins/codex/skills/architectural-decisions/SKILL.md b/plugins/codex/skills/architectural-decisions/SKILL.md
index 9808c49b0..48bf79b4c 100644
--- a/plugins/codex/skills/architectural-decisions/SKILL.md
+++ b/plugins/codex/skills/architectural-decisions/SKILL.md
@@ -7,9 +7,24 @@ description: Use when a task asks why code is built a certain way, proposes arch
Repowise captures architectural decisions: the rationale behind how code is built.
+`get_why` has four modes — pick by what you pass:
+
+1. `get_why(query="why is auth using JWT?")` — keyword + semantic decision search.
+2. `get_why(query="src/auth/service.py")` — decisions governing that file, plus
+ its origin story and an alignment score (does the file still follow its own ADRs?).
+3. `get_why(query="why was caching added?", targets=["src/auth/cache.py"])` —
+ target-anchored search; decisions touching the targets get boosted.
+4. `get_why()` — the decision-health dashboard.
+
+Decisions are mined from eight sources (ADR files, CHANGELOG, PR/commit bodies,
+inline markers, git archaeology, README/docs, code comments, and the doc pass)
+and linked by `supersedes` / `refines` / `relates_to` / `conflicts_with` edges,
+so a single answer can return a whole lineage chain. When no decision exists for
+a path, `get_why` falls back to git archaeology so the call is never empty.
+
## When The User Asks Why Something Exists
-Call `get_why(query="specific area or decision")` to search captured decisions. This covers inline decision markers, git-derived rationale, and decisions mined from documentation.
+Call `get_why(query="specific area or decision")`.
## Before Architectural Changes
@@ -21,6 +36,9 @@ Call `get_why(query="specific area or decision")` to search captured decisions.
Call `get_why()` to inspect decision health: stale decisions, conflicts, and ungoverned hotspots.
+The same signals surface in the CLI via `repowise decision health`, and you can
+review auto-proposed decisions with `repowise decision confirm`.
+
## When Decision Markers Appear In Code
If a file contains `WHY:`, `DECISION:`, `TRADEOFF:`, or `ADR:`, call `get_context(targets=["path/to/file"])` to retrieve the full file context and related decisions.
diff --git a/plugins/codex/skills/change-review/SKILL.md b/plugins/codex/skills/change-review/SKILL.md
index be27cd6f5..8185cde96 100644
--- a/plugins/codex/skills/change-review/SKILL.md
+++ b/plugins/codex/skills/change-review/SKILL.md
@@ -5,11 +5,34 @@ description: Use when reviewing a set of changes before they merge in a Repowise
# Change Review With Repowise
-When a diff is on the table, Repowise turns "what files changed" into "what does this change put at risk", fusing git history (churn, ownership, co-change) with graph topology (dependents, impact surface), test gaps, and the decisions that govern the touched code. Use two complementary signals.
+When a diff is on the table, Repowise turns "what files changed" into "what does this change put at risk", fusing git history (churn, ownership, co-change) with graph topology (dependents, impact surface), test gaps, security signals, and the architectural decisions that govern the touched code. Use two complementary signals.
+
+- **`get_change_risk(revspec=…)` (MCP)** scores the *whole change as one unit* (a
+ commit or a `base..head` range) from its diff shape: a single 0-10 defect-risk
+ score with drivers (lines added/deleted, files, directories, subsystems,
+ change entropy, author familiarity). No LLM, no network. Prefer this in-MCP
+ tool; it takes a revspec and diffs server-side, so you never shell out. Lead
+ with `risk_percentile` (this change ranked against sampled recent commits),
+ summarized by `review_priority` and `classification`; `score` / `level` are
+ the corpus-calibrated fallback. This is the pre-merge gate: "how risky is this
+ change overall?" The `repowise risk <revspec>` CLI is the identical scorer for
+ when you are already in a terminal.
+- **`get_risk(changed_files=…)` (MCP)** works *per file* and returns the
+ `directive` block, the specific things to check inside the diff.
## Score The Whole Change First
-Call `get_change_risk(revspec="main..HEAD")`. It scores the whole change as one unit (a commit or a `base..head` range) from its diff shape, no LLM and no network. Lead with `risk_percentile` (this change ranked against sampled recent commits), summarized by `review_priority` and `classification`; `score` and `level` are the corpus-calibrated fallback. `extensions=[".py"]` counts only certain suffixes and `exclude_patterns=["tests/"]` omits paths. A `warning` field means the revspec or filters matched no files, so an all-zero score there is not a clean bill of health. The identical scorer from a terminal is `repowise risk <revspec>`.
+```
+get_change_risk(revspec="main..HEAD") # HEAD, a commit SHA, or base..head
+```
+
+Read `risk_percentile` and the top drivers: a high score from large diffusion
+(many dirs/subsystems) or low author familiarity tells you where to look
+hardest. `extensions=[".py", ".ts"]` counts only certain file types;
+`exclude_patterns=["tests/"]` omits paths. A `warning` field means the revspec
+or filters matched no files, so an all-zero score there is not a clean bill of
+health. The equivalent from a terminal is `repowise risk <revspec>` (add
+`--ext .py,.ts` or `--format json`).
## Then Drill Into The Directive Block
@@ -20,7 +43,12 @@ Call `get_risk(targets=<changed files>, changed_files=<same files>)` in PR mode.
- `missing_tests`: changed code with a test gap. Flag for new or updated tests.
- `tests_to_run`: the coverage-backed complement of `missing_tests`, the tests the per-test map proves execute the changed files (pytest-runnable ids). Empty means unknown (no coverage map ingested), never "no tests exist".
-For the line-precise version from a terminal, `repowise impacted-tests <revspec>` maps each changed line to its covering tests and prints the ids (`--format list | xargs pytest` runs exactly them).
+`pr_blast_radius` holds the fuller dossier behind those lists (including the
+per-changed-file `guarding_tests` breakdown behind `tests_to_run`).
+
+For the line-precise version from a terminal, `repowise impacted-tests <revspec>`
+maps each changed line to the tests whose recorded coverage touches it, then
+prints the ids (`--format list | xargs pytest` runs exactly them).
## Then Go Deeper Where It Matters
@@ -28,10 +56,18 @@ For the line-precise version from a terminal, `repowise impacted-tests <revspec>
2. Call `get_health(targets=<changed files>, include=["biomarkers"])` to catch new complexity, deep nesting, or duplication the diff introduced.
3. Use the `get_risk` ownership and co-change signals to suggest who should review.
+## Getting The Diff
+
+- A GitHub PR: `gh pr diff <number>` (or `gh pr view <number> --json files`).
+- A branch: `git diff --name-only main...HEAD`.
+- Working tree: `git status --porcelain`.
+- CLI shortcut for a range: `repowise risk main..HEAD` scores a branch/PR range
+ for defect risk directly.
+
## Write The Review Around Evidence
Lead with a risk level and the `directive` findings, each tied to a concrete file. Distinguish "will break" (a dependent outside the diff) from "worth a look" (a co-change or health regression). Do not pad with findings the tools did not support.
## Error Handling
-If `get_risk` or `get_change_risk` errors or returns nothing, the MCP server may be down or the repo unindexed. Say so, review from the raw diff, and suggest running `repowise init --yes` if the repo is not indexed.
+If `get_risk` or `get_change_risk` errors or returns nothing, the MCP server may be down or the repo unindexed. Say so, review from the raw diff, and suggest running `repowise init` if the repo is not indexed.
diff --git a/plugins/codex/skills/codebase-exploration/SKILL.md b/plugins/codex/skills/codebase-exploration/SKILL.md
index 96450e006..eb1984b74 100644
--- a/plugins/codex/skills/codebase-exploration/SKILL.md
+++ b/plugins/codex/skills/codebase-exploration/SKILL.md
@@ -7,22 +7,46 @@ description: Use when exploring, understanding, or answering questions about a R
This project has a Repowise intelligence layer. Use Repowise MCP tools before broad source browsing so the answer starts from indexed docs, ownership, graph structure, git signals, and decisions.
-## Starting A New Exploration Task
+## Which Tool For Which Question
-Call `get_overview()` first. It returns the architecture summary, module map, entry points, and tech stack.
+| You want… | Call |
+|---|---|
+| First orientation in an unfamiliar repo | `get_overview()` — architecture summary, key modules, entry points, git health, knowledge map. Skip it once you have the map. |
+| A direct answer to "how/where/why does X work" | `get_answer(question="…")` — synthesised answer with citations + a `retrieval_quality` signal. Collapses the search → read → reason loop. |
+| Find a symbol, file, or fuzzy concept | `search_codebase(query="…")` — hybrid search. `mode="auto"` routes an identifier to indexed symbol hits (`symbol_id`/line bounds → pipe into `get_symbol`), a path to file pages (→ `get_context`), and prose to semantic wiki search (each hit reports `search_method`: `embedding` vs `bm25`). Force a branch with `mode=symbol\|path\|concept\|hybrid`; narrow symbols with `symbol_kind`. |
+| A triage card for specific files/symbols | `get_context(targets=[…])` — title, summary, signatures, hotspot bit, top callers, decision titles, symbol_ids. Batch many targets in one call. |
+| The actual source of one symbol | `get_symbol("path/to/file.py::Name")` — exact bytes with line bounds. Cheaper than a raw read + offset math. Use a `symbol_id` from `get_context`. |
-## Answering How Or Where Questions
+## Recommended Flow
-1. Call `search_codebase(query="topic, symbol, or path")`. It auto-routes: an identifier returns indexed symbol hits (`symbol_id` + line bounds — pipe into `get_symbol`), a path returns file pages, and prose runs semantic search. Force a branch with `mode=symbol|path|concept|hybrid`.
-2. Call `get_context(targets=[...])` with all relevant files from the search results in one batch.
-3. Read raw source only after the indexed context is not specific enough for the user’s question.
+1. New area you don't know → `get_overview()` once.
+2. A specific question → `get_answer(question=…)` first.
+ - High confidence → answer it, cite the paths.
+ - `medium`/`low` confidence → follow `best_guesses[0].file` or
+ `fallback_targets[0]` into `get_context`, then `get_symbol` for bytes.
+3. A named symbol or a path → `search_codebase(query="Name")` /
+ `search_codebase(query="path/to/file.py")`; symbol hits pipe straight into
+ `get_symbol`, file hits into `get_context`.
+4. More files around a concept → `search_codebase`, then `get_context` on the
+ hits (batched), then `get_symbol` only for the bodies you actually need.
-## Understanding Connections Between Modules
+Fall back to raw source reads only when the indexed context doesn't cover the
+specific detail the user asked about.
-Call `get_context(targets=["path/or/symbol"], include=["callers", "callees"])` when the user asks how two areas connect, then follow the callers and callees it returns.
+## Trust Signals — Verify When
+
+- `_meta.stale_warning` is present (the index has diverged from HEAD), or
+- `retrieval_quality` is `partial`/`weak`, or
+- a result's `search_method` is `bm25`.
+
+Otherwise the response is current — act on it.
## Error Handling
-- If tools report that no repositories were found, suggest running `repowise init --yes`.
-- If `search_codebase` has no useful results, the repository may have a template-rendered wiki; fall back to `get_context` with specific paths.
-- If MCP tools are unavailable, proceed with normal source inspection and mention that Repowise context was unavailable.
+- If tools report that no repositories were found, suggest running `repowise init`.
+- If `get_answer`/`search_codebase` come back empty, the repository may have a
+ template-rendered wiki; fall back to `get_context` with specific paths, and note
+ that model-written pages (`repowise generate`, or `repowise init` with an LLM
+ provider) unlock richer docs + semantic search.
+- If MCP tools are unavailable, proceed with normal source inspection and mention
+ that Repowise context was unavailable.
diff --git a/plugins/codex/skills/dead-code-cleanup/SKILL.md b/plugins/codex/skills/dead-code-cleanup/SKILL.md
index 99b66ca1a..76f36b658 100644
--- a/plugins/codex/skills/dead-code-cleanup/SKILL.md
+++ b/plugins/codex/skills/dead-code-cleanup/SKILL.md
@@ -18,6 +18,7 @@ Call `get_dead_code()` to get findings organized by confidence tier. Useful para
- `kind="zombie_package"` for monorepo packages with no consumers.
- `directory="src/old/"` to limit scope.
- `tier="high"` for the highest-confidence band.
+- `group_by="directory"` or `group_by="owner"` to roll up where dead code concentrates and who owns the most of it.
## Presenting Findings
diff --git a/plugins/codex/skills/pre-modification-check/SKILL.md b/plugins/codex/skills/pre-modification-check/SKILL.md
index eebf3a11a..4cf9a4246 100644
--- a/plugins/codex/skills/pre-modification-check/SKILL.md
+++ b/plugins/codex/skills/pre-modification-check/SKILL.md
@@ -9,14 +9,22 @@ Before editing a Repowise-indexed codebase, assess impact with the graph and git
## Before Editing Files
-Call `get_risk(targets=["path/to/file.py"])` to understand:
-
-- Hotspot status and churn trend.
-- Dependents and likely blast radius.
-- Co-change partners that may need updates.
-- Ownership and recommended review context.
-- Bus factor and maintenance concentration.
-- Test gaps or security signals.
+Call `get_risk(targets=["path/to/file.py"])`. Per file it returns
+`hotspot_score`, `trend`, `risk_type`, `impact_surface` (top 3),
+`dependents_count`, `co_change_partners`, `primary_owner`, `bus_factor`,
+`test_gap`, and `security_signals`. Read it for:
+
+- **Bug-fix history** (`defect_profile`) — present only on files with counted
+ fixes: `fix_count` over the trailing 6 months, `last_fix_days_ago`, a
+ `bug_magnet` flag for sustained recent fix pressure, and `top_symbols` (the
+ per-symbol counts are approximate — read them as "mostly here"). A file that
+ keeps getting fixed is the strongest single signal that the next edit breaks
+ something; lead with it.
+- **Hotspot status** (`hotspot_score`, `trend`) — high-churn × complex? Extra care needed.
+- **Dependents** (`dependents_count`, `impact_surface`) — how wide is the blast radius?
+- **Co-change partners** — files that change together with this one (often without an import link); you may need to update them too.
+- **Ownership / bus factor** — who owns it, and whether a single author maintains it.
+- **Test gap & security signals** — flag untested or security-sensitive files before touching them.
## When Editing Multiple Files
@@ -26,8 +34,9 @@ Batch all targets in one call: `get_risk(targets=["file1.py", "file2.py", "modul
Warn before editing when `get_risk` shows:
+- A `defect_profile` with `bug_magnet` set — say so plainly: this file has been fixed repeatedly and recently.
- Hotspot score above the 90th percentile.
-- More than 10 dependents.
+- More than 10 dependents — list the top dependents; API changes here will break consumers.
- Bus factor of 1.
- Risk type such as `bug-prone` or `high-coupling`.
- Missing tests around changed or affected files.
@@ -36,6 +45,10 @@ Warn before editing when `get_risk` shows:
Call `get_context(targets=["path/to/file.py"])` first to understand what uses the file, which decisions govern it, and why it is structured that way.
+For a heavy refactor, also call `get_health(targets=["file.py"])` — the
+marker findings (complexity, deep nesting, low cohesion, duplication) tell
+you *what* to improve while you're in there, and give you a before/after score.
+
## Error Handling
If `get_risk` fails or the MCP server is unavailable, proceed with normal inspection and mention that Repowise risk assessment was unavailable.