Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.jsonindex 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.mdindex 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 archRepowise 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 CodeIf 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.mdindex 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 EvidenceLead 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.mdindex 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 RThis 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.mdindex 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 Findingsdiff --git a/plugins/codex/skills/pre-modification-check/SKILL.md b/plugins/codex/skills/pre-modification-check/SKILL.mdindex 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", "modulWarn 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 HandlingIf `get_risk` fails or the MCP server is unavailable, proceed with normal inspection and mention that Repowise risk assessment was unavailable.