g4borg
f1de89e869
Standalone plugin with one skill: when to use orbit and when grep, a mandatory preflight for stale indexes and blind regions (cfg(test), features, macros, dyn dispatch), a scripted review pass over isolated worktree DBs, and a JSONL feedback log for mining real usage later. Registered in the marketplace as a prototype.
84 lines
5.4 KiB
Markdown
84 lines
5.4 KiB
Markdown
# orbit (prototype)
|
|
|
|
This plugin is a skill for **structural review of Rust changes** with the GitLab [orbit](https://gitlab.com/gitlab-org/orbit/knowledge-graph) code graph. It reports changed definitions, blast radius, trait-impl coverage, crate and module boundary guards, and a cfg-blindness preflight that decides how far to trust the rest. It complements grep and does not replace it.
|
|
|
|
It is an early prototype built from the 2026-09-29 research in `docs/workpad/research/2026-09-29-17-orbit/`, for orbit CLI **0.133**. It expects `orbit`, `git` and `python3` on PATH. No compilation is involved.
|
|
|
|
## Contents
|
|
|
|
| Path | What |
|
|
|---|---|
|
|
| `skills/orbit/SKILL.md` | When to use orbit rather than grep, the mandatory preflight, the review pass, reporting rules, feedback, and how to brief a subagent |
|
|
| `skills/orbit/references/review-recipes.md` | Per-recipe detail, the gap-class table with grep fallbacks, and the rules-file format |
|
|
| `skills/orbit/references/cookbook.md` | Ad-hoc CLI and SQL for Rust, and gotchas |
|
|
| `skills/orbit/scripts/review-pass.sh` | End-to-end pass: setup, then preflight, defdiff, blast, traits, boundary and context (about 25 s) |
|
|
| `skills/orbit/scripts/review-setup.sh`, `review-teardown.sh` | Detached worktrees for base and tip in an **isolated** `--db`, and their cleanup |
|
|
| `skills/orbit/scripts/*.py` | The recipes (`ob.py` and `regions.py` are libraries) |
|
|
| `skills/orbit/scripts/freshness.sh` | Read-only index freshness check for ad-hoc questions |
|
|
| `skills/orbit/scripts/fb.sh` | Appends one feedback record |
|
|
| `skills/orbit/scripts/rules/*.rules` | Boundary rules for spacecraft and dirigent (hand-derived, may drift) |
|
|
| `skills/orbit/scripts/sql/*.sql` | Standalone SQL templates |
|
|
|
|
Review scratch (worktrees, DBs, outputs) goes to `$ORBIT_REVIEW_HOME` (default `~/.cache/orbit-review`), never `/tmp`. Always run `review-teardown.sh` afterwards: orbit has no command to delete an index entry, so nothing review-related may go into the shared `~/.gitlab/orbit/graph.duckdb`.
|
|
|
|
## Enabling locally (spacecraft, dirigent)
|
|
|
|
Both projects already declare the `reliquary` marketplace in their committed `.claude/settings.json` (`extraKnownMarketplaces`). That marketplace is fetched from **git** (`git@git.g4b.org:dirigence/reliquary.git`), so `orbit@reliquary` only resolves after this plugin is committed and pushed, and the marketplace has refreshed (`/plugin marketplace update reliquary`).
|
|
|
|
**Per project, not committed.** Run this in the project root:
|
|
|
|
```bash
|
|
claude plugin install orbit@reliquary --scope local
|
|
```
|
|
|
|
`--scope local` writes to `.claude/settings.local.json`, which is meant to stay uncommitted (confirm with `git check-ignore .claude/settings.local.json`). To do it by hand, add this to `<project>/.claude/settings.local.json` (create it if missing, and merge with any existing keys):
|
|
|
|
```json
|
|
{
|
|
"enabledPlugins": {
|
|
"orbit@reliquary": true
|
|
}
|
|
}
|
|
```
|
|
|
|
**Before pushing** (trying out this working copy), load the plugin for one session only:
|
|
|
|
```bash
|
|
cd ~/Projects/spacecraft # or ~/Projects/dirigent
|
|
claude --plugin-dir ~/Projects/reliquary/plugins/orbit
|
|
```
|
|
|
|
Check it with `/plugin` (orbit should be listed as enabled) or by asking "review this branch with orbit". Also useful:
|
|
- `claude plugin validate ~/Projects/reliquary/plugins/orbit`
|
|
- Rules files: `rules/spacecraft.rules` and `rules/dirigent.rules` ship with the plugin. Pass one as the 5th argument to `review-pass.sh`.
|
|
|
|
## Feedback log
|
|
|
|
While this is a prototype, the skill asks agents to append **one JSONL line per orbit result that informed a decision** (or should have, and turned out wrong):
|
|
|
|
```bash
|
|
ORBIT_AGENT=search skills/orbit/scripts/fb.sh blast grep-needed "callers of format_token_title" "blast.py dg-tokens" 0 "both call sites inside rsx!" rsx
|
|
```
|
|
|
|
- File: `~/.local/share/orbit-skill/feedback.jsonl`. Set `ORBIT_FEEDBACK` to override it. It is outside every repo and shared across projects.
|
|
- Fields: `ts, repo, commit, dirty, orbit` (automatic), `agent` (`$ORBIT_AGENT`), `recipe, purpose, cmd, rows, verdict`, and optionally `note, gap`. `verdict` is one of `useful | wrong | incomplete | grep-needed | noise | unused`.
|
|
|
|
To read or mine it:
|
|
|
|
```bash
|
|
F=~/.local/share/orbit-skill/feedback.jsonl
|
|
jq -s 'group_by(.recipe, .verdict) | map({recipe: .[0].recipe, verdict: .[0].verdict, n: length})' $F # value per recipe
|
|
jq -s '[.[] | select(.gap != "")] | group_by(.gap) | map({gap: .[0].gap, n: length}) | sort_by(-.n)' $F # which blind spots bite
|
|
jq -c 'select(.verdict == "wrong" or .verdict == "incomplete") | {repo, recipe, purpose, note}' $F # failures to learn from
|
|
jq -s 'group_by(.repo) | map({repo: .[0].repo, n: length, dirty: map(select(.dirty)) | length})' $F # per project, dirty-tree usage
|
|
```
|
|
|
|
Summaries of mined data (not raw logs) belong in `docs/workpad/research/…`. The open questions the log is meant to answer (whether the pass changes outcomes, the preflight thresholds, token budget, agent fit) are listed in §11 of `phase-2-review-workflows.md`.
|
|
|
|
## Known rough edges
|
|
|
|
- Tested only on orbit 0.133.0, spacecraft and dirigent. The preflight thresholds (25 % and 60 %) are guesses.
|
|
- Uncommitted review uses `git stash create`, so **untracked files are not reviewed**.
|
|
- `review-setup.sh` briefly registers two worktrees in the target repo's `.git` (removed by teardown). If teardown is skipped, they linger. Check with `git worktree list`.
|
|
- Rust only. The shell scripts need bash (they work when called from fish).
|