stellar-code-quality-review — Claude Code skill: overview and install
The stellar-code-quality-review Claude Code skill audits maintainability, abstraction quality, and file growth. Its staged review examines changes and related code units.
Apache-2.0 ★ 423 updated 2026-11-16
npx skills add relatedb/relate --skill stellar-code-quality-review -a claude-codeWhat stellar-code-quality-review does
The skill reviews implementation quality and maintainability, looking for weak abstractions, oversized files, and tangled branching. Scripts gather facts and prepare focused briefs; the model judges those prepared units rather than reading a raw diff.
For a local run, execute .github/scripts/stellar-prep.sh local [--quick] [PR_NUMBER] from the repository root on the branch under review. A full round includes earlier findings and dependency-related units, and is required before every push. --quick checks only changed units, so it is a mid-work filter, not a replacement for the full round. The scripts use Python 3 standard-library modules and write results under .stellar/.
What it helps with
- spot weak abstractions in an implementation
- find oversized files and tangled branches
- revisit changed units alongside earlier findings
Example prompts for the agent
- Run a strict maintainability review of this branch.
- Audit the abstractions and find files that have grown too large.
- Run a quick interim check of the current changes.
How to install stellar-code-quality-review
1Skills CLI (Vercel)
npx skills add relatedb/relate --skill stellar-code-quality-review -a claude-code2Manually: put the files in place
~/.claude/skills/stellar-review/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/stellar-review/
1Skills CLI (Vercel)
npx skills add relatedb/relate --skill stellar-code-quality-review -a codex2Manually: put the files in place
.agents/skills/stellar-review/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add relatedb/relate --skill stellar-code-quality-review -a cursor2Manually: put the files in place
.cursor/skills/stellar-review/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install relatedb/relate .agents/skills/stellar-review2Manually: put the files in place
.github/skills/stellar-review/SKILL.md1Skills CLI (Vercel)
npx skills add relatedb/relate --skill stellar-code-quality-review -a gemini-cli2Platform CLI
gemini skills install https://github.com/relatedb/relate --path .agents/skills/stellar-reviewManually: put the files in place
.devin/skills/stellar-review/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add relatedb/relate --skill stellar-code-quality-review -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about stellar-code-quality-review
How do I install stellar-code-quality-review in Claude Code?
Run npx skills add relatedb/relate --skill stellar-code-quality-review -a claude-code. The skill file is located at ~/.claude/skills/stellar-review/SKILL.md.
What does stellar-code-quality-review do?
It reviews maintainability, abstraction quality, file size, and branching structure. Scripts prepare the review inputs and focused briefs for model judgment.
What does stellar-code-quality-review need to run?
Its scripts require Python 3 with the standard library. Start local preparation from the repository root with .github/scripts/stellar-prep.sh local [--quick] [PR_NUMBER].
Source text
SKILL.md · Apache-2.0
---
name: stellar-code-quality-review
description: Strict maintainability review — abstraction quality, file size, spaghetti growth. Runs as a deterministic incremental pipeline (facts → ledger scope → briefs → focused passes → scripted verdict) so every blocker and medium surfaces in round 1 and untouched code never re-produces findings. Use for a stellar code quality review, deep quality audit, or harsh maintainability review.
disable-model-invocation: true
---
# Stellar Review
Unusually strict review of implementation quality, maintainability, and abstraction health. Push for **ambitious** restructurings — "code judo" moves that preserve behavior while making the code dramatically simpler, smaller, and more direct. Delete complexity; don't rearrange it.
This review is a **pipeline** (ADR-0271), not a reading. Scripts own everything mechanical — what changed, how big things are, where the branches/casts/fallbacks are, which units look alike, what was already decided. Model tokens buy exactly one thing: per-unit judgment over pre-digested briefs. Do not improvise around the steps, and never review a raw diff — that is the low-recall mode this pipeline replaced.
The tools live next to this file: `tools/facts.py` (git-side extraction), `tools/units.py` (language machinery), `tools/similar.py` (near-duplicates), `tools/ledger.py` (cross-round state), `tools/incremental.py` (stale-ledger-proof anchoring diff, ADR-0292), `tools/nightshift.py` (night-shift queue planner), `tools/briefs.py` (pass briefs), `tools/pass_models.py` (CI per-pass model config, ADR-0302), `tools/post.py` (GitHub posting) — pure Python 3 stdlib. Pass mandates live in `passes/`, doctrine in `references/`. Runtime state lives in `.stellar/` (gitignored).
## Step 0 — facts, ledger, scope, briefs (scripts only)
**Local pre-push rounds ALWAYS run the script — never a hand-rolled subset of these steps.** The abbreviated hand-copy (facts → scope → briefs, skipping the ledger fetch and the dependency-dirty expansion) is exactly the divergence that let CI keep finding findings the local round never saw. One command, from the repository root, on the branch to review:
```sh
.github/scripts/stellar-prep.sh local [--quick] [PR_NUMBER]
```
`PR_NUMBER` is optional: given → that PR's ledger is fetched from its summary comment; absent → the PR for the current branch, if one exists; no PR at all → round-1 semantics (no ledger fetch, empty ledger). The script derives the inputs CI's `model` mode reads from its env — base per the SCOPE RULE below, head = HEAD — and runs the identical pipeline body (ledger → facts → docs-only gate → scope → dependency-dirty expansion → incremental diff → briefs), writing `.stellar/facts.json`, `.stellar/scope.json`, `.stellar/briefs/`. CI's `model` mode and the local round are the same code path: `stellar-prep.sh` is the one entry point. Then dispatch the four passes over `.stellar/briefs/` (Step 2).
`--quick` is the cheap mid-work sanity check: delta-only scope (the dependency-dirty expansion is skipped) and one brief per pass (no sharding, however big the round). Model tiers are unchanged — the tier guidance and `STELLAR_MODEL_*` overrides below apply as-is; the script never configures models. **Quick is a PRE-FILTER, never a gate — quick catches what the delta touches; the full round (carried ledger + expansion + shards) is still mandatory before every push.**
What each mode catches:
- **Full round (the mandatory pre-push gate)** reviews the delta PLUS the carried ledger's earlier-round units PLUS the dependency-dirty expansion (callers/callees of changed units) — approximately what CI's round will judge. Cost: more units, sharded briefs, all four passes at their configured tiers — the expensive but CI-faithful shape.
- **Quick round (mid-work pre-filter)** reviews ONLY the delta's changed units, one shard per pass — it catches what your own edit touches (structure/branching shape in the code you just wrote) and misses anything CI anchors via earlier rounds or dependency expansion (the observed failure class: findings on pre-existing callers pulled into scope). Cheap, fast, NOT a gate.
A clean quick round does NOT predict a clean CI round; a clean full round is the best local predictor of CI's verdict — and even the full round differs from CI by model pinning (CI's `STELLAR_MODEL_*` secrets), so a local green is strong, not identical.
The rest of this section is the manual reference — the expansion of exactly what the script runs (and what CI's env-driven `model`/`post` modes do with workflow-provided inputs), kept for reading, not for hand-copying:
```sh
TOOLS=.agents/skills/stellar-review/tools
mkdir -p .stellar
# facts (CI passes --base/--head from the PR payload; locally they default
# to merge-base HEAD origin/main → HEAD)
#
# SCOPE RULE (anti-balloon): when .stellar/ledger.json exists and its
# last_head is an ancestor of HEAD, ALWAYS pass --base <last_head> --head
# HEAD. The main merge-base default is for round 1 (no ledger) only — using
# it on an existing PR re-judges the entire PR diff and balloons the scope
# (891+ units, hours of pass time). After a force-push/rebase (last_head
# not an ancestor of HEAD), pass --base <merge-base HEAD origin/main> — never
# the merge-base of the old and new heads, which re-includes main's advance.
python3 $TOOLS/facts.py --out .stellar/facts.json
# ledger: CI fetches it from the PR summary comment; locally it is a file
# CI: python3 $TOOLS/post.py fetch-ledger --repo $REPO --pr $PR --out .stellar/ledger.json
# local: .stellar/ledger.json already exists from the last round, or not (round 1)
python3 $TOOLS/ledger.py scope --facts .stellar/facts.json --ledger .stellar/ledger.json --out .stellar/scope.json
# dependency expansion: if scope.json lists dependency_dirty_files, rerun
# facts with them included, then rerun scope:
jq -r '.dependency_dirty_files[]' .stellar/scope.json > .stellar/expand.txt
# (if non-empty) python3 $TOOLS/facts.py --out .stellar/facts.json --include-units-file .stellar/expand.txt
# (and rerun the scope command above)
# briefs: incremental rounds embed the since-last-round diff; round 1 omits it
LAST=$(jq -r '.last_head // empty' .stellar/ledger.json)
HEAD=$(jq -r '.head' .stellar/facts.json)
if [ -n "$LAST" ] && [ "$LAST" != "$HEAD" ]; then
# never raw `git diff $LAST $HEAD`: after a force-push/rebase LAST is stale
python3 $TOOLS/incremental.py --facts .stellar/facts.json --ledger .stellar/ledger.json --out .stellar/diff-incremental.patch
python3 $TOOLS/ledger.py brief --facts .stellar/facts.json --scope .stellar/scope.json --diff .stellar/diff-incremental.patch --out .stellar/briefs
else
python3 $TOOLS/ledger.py brief --facts .stellar/facts.json --scope .stellar/scope.json --out .stellar/briefs
fi
```
## Step 1 — gates (no model tokens)
- `facts.has_code_changes` is `false` → docs/CI-only diff. Stop. (CI: the workflow already ran `post.py noop`.)
- `scope.stats.units_in_scope` is `0` **and** `scope.resolve_checks` is empty → nothing new to judge. Write `{"version": 1, "findings": [], "resolutions": [], "coverage": [], "notes": "nothing changed since last round"}` to `.stellar/findings.json` and go to Step 4. Open findings from earlier rounds are carried by the ledger — the poster re-states them; you do not.
## Step 2 — dispatch the passes (parallel sub-agents)
For **each** file in `.stellar/briefs/` (`brief-structure[-N].md`, `brief-branching[-N].md`, `brief-boundaries[-N].md`, `brief-comparison.md`), dispatch one sub-agent — the `stellar-structure`, `stellar-branching`, `stellar-boundaries`, `stellar-comparison` agents are defined in this repository (`.opencode/agents/` / `.claude/agents/`). Dispatch all of them in parallel. Prompt per agent:
> Stellar review round <N>. Your brief is `.stellar/briefs/<file>` — read it fully, then follow your standing instructions (mandate + doctrine + JSON output). Return only your JSON document.
Never merge two briefs into one dispatch, and never dispatch a pass without its brief — the isolated contexts and pre-digested inputs are what make the passes exhaustive and fast.
If a pass agent fails to dispatch or errors, stop and report the failure — never assemble or post a partial review; a missing pass is not an empty pass.
MODEL TIERS (cost/speed): the passes are mechanical checklist reads against pre-digested briefs.
Per-pass model overrides (ADR-0302): `STELLAR_MODEL_<PASS>` (`STELLAR_MODEL_STRUCTURE`, `STELLAR_MODEL_BRANCHING`, `STELLAR_MODEL_BOUNDARIES`, `STELLAR_MODEL_COMPARISON`) overrides that pass's sub-agent model; unset or empty = no override — locally the tier guidance below applies, in CI the pass inherits the run-level model.
- **CI**: the workflow applies each non-empty value as per-agent OpenCode config before the run — `tools/pass_models.py` writes it verbatim (an OpenCode `provider/model`) to `agents.stellar-<pass>.model` in `~/.config/opencode/opencode.json` — so the CI dispatcher takes no model action.
- **Local**: a dispatcher that can set a per-dispatch model runs `printenv STELLAR_MODEL_<PASS>` before dispatch and passes a non-empty value as that pass's model, in the dispatcher's own model syntax (OpenCode `provider/model`, a Claude Code alias such as `haiku`).
Tier guidance: dispatch `stellar-boundaries` and `stellar-comparison` on the cheapest fast model your dispatcher supports (e.g. `model: haiku`); `stellar-branching` on the mid model (e.g. `model: sonnet`); keep `stellar-structure` on the default/strong model — decomposition and 1k-line judgment is the one pass that genuinely needs it. A finding dropped by a cheap pass is usually caught by its siblings or by CI's full-strength round; the cost asymmetry favors cheap local passes.
## Step 3 — assemble findings.json
Collect each agent's JSON document. Concatenate `findings`, `resolutions`, and `coverage` arrays. Write exactly one file, `.stellar/findings.json`:
```json
{"version": 1, "findings": [...], "resolutions": [...], "coverage": [...], "notes": ""}
```
Sanity-check before writing: every finding has `area`, `severity` (`blocker|medium|nit`), `path`, `start_line`, `quote`, `why`, `remedy`; every finding's `unit` (when present) is a unit the scope actually assigned; no finding quotes code from a sealed unit; in incremental rounds, every finding's lines intersect the incremental diff hunks. Drop violations — they are process errors, not findings (the poster drops them anyway: scope membership and incremental anchoring are script-enforced, ADR-0275). This file is the **only** file you may write.
## Step 4 — hand off
- **CI**: stop here. The workflow runs `post.py`, which rolls the ledger, posts one review with all inline comments, derives the verdict, and updates the summary comment.
- **Local**: roll the ledger and print the report yourself:
```sh
python3 $TOOLS/ledger.py update --facts .stellar/facts.json --ledger .stellar/ledger.json \
--findings .stellar/findings.json --scope .stellar/scope.json
```
Then print: round number, scope stats, findings grouped by severity (blocker → medium → nit, with `path:lines`, why, remedy), resolution outcomes, and the approval-bar verdict (`references/full-checklist.md`). Direct, serious, demanding tone; a small set of well-evidenced findings beats a wall of nits — but nothing medium or higher is ever held back.
## What changed from the old skill (for anyone surprised)
- No `git diff` reading, ever. Facts and briefs are pre-digested and identical every round for the same code.
- The verify pass is gone; the **comparison** pass catches the same defect class (inconsistency between similar sites) from similarity groups instead of a fifth full read.
- Round 2+ reviews only what changed since round 1 (plus signature-affected dependents and resolution checks). Everything else is sealed — new findings on untouched code are a process violation.
- Posting and verdict are scripts. The model writes `.stellar/findings.json` and nothing else.
© relatedb · Apache-2.0 · relatedb/relate