reliquary/docs/workpad/research/2026-09-29-17-orbit/phase-1-review-fit.md

phase, topic, depends-on, status

phase	topic	depends-on	status
1	review-fit	phase-0-field-guide-python-django.md	findings

Phase 1: How orbit fits Spire's review stage

TL;DR

• Spire's development cycle (docs/workpad/designs/2026-09-22-development-cycle.md) has a Review stage (Stage 6): "a fresh Opus reviewer measures output against plan and design," fed the Athanor's diff + plan reference. There is no dedicated reviewer agent file yet — Stage 6 is currently a generic Opus subagent dispatch, not a pinned agent like search/scout/researcher/adept/athanor. This is the single biggest opening for an orbit skill: it can be the thing that turns "a fresh Opus reviewer" into "a fresh Opus reviewer with a code-graph."
• Orbit is a strong fit for exactly the questions review asks and grep answers poorly: what did this diff touch structurally, what else depends on it (blast radius), does it break a trait contract, does it cross a module boundary it shouldn't, how does the branch's graph differ from main's. All five map to concrete orbit subcommands per the phase-0 field guide's §8/§12/§13.
• search (read-only, Sonnet) is the natural agent to carry orbit calls during review — it already has Bash and no write tools, matching orbit's "call from the shell, not MCP" guidance (guide §13). researcher would use orbit for one-off deep investigations (e.g., an architecture-survey-style review). adept could keep a running "blast radius" map for a domain across sessions. athanor decomposes review work but shouldn't itself be the one running orbit queries — it should dispatch a search (or a future reviewer) subagent to do so.
• Skills in this marketplace are per-plugin folders (plugins/<name>/skills/<skill>/SKILL.md, optional references/); no central registry — a plugin just needs the file to exist under skills/, and agents preload skills via a skills: frontmatter list (as adept.md, athanor.md, zathras.md do).
• Recommendation: standalone plugin plugins/orbit/ with one skill (orbit:review or similar), not folded into Spire. Reasons in §4. Spire agents pick it up the same way they already pick up tome (an optional sibling plugin): check for it, use it if present, degrade gracefully (grep) if absent.
• .claude/spire/project.md (scaffolded by plugins/spire/skills/init/SKILL.md) already has a "Domain skills to route to subagents when relevant" field — this is the natural place to flag "orbit available for this project," no new mechanism needed.

---

1. How review works in Spire today

The development cycle is documented in docs/workpad/designs/2026-09-22-development-cycle.md and mirrored into plugins/spire/skills/igor/SKILL.md (§"Development Cycle", lines 91–110). Six stages, review is the decision point:

docs/workpad/designs/2026-09-22-development-cycle.md:30 | 6. Review | fresh Opus reviewer (never the Athanor that cooked it) | diff + plan | reports/ — findings with severity |

docs/workpad/designs/2026-09-22-development-cycle.md:42 Review measures output against the plan and design, not taste. Severity: low (nits), medium (wrong but contained), high (load-bearing, or plan not fulfilled).

The review decision tree (same file, lines 44–52; repeated in igor/SKILL.md:99-106) routes findings: none/low → done, medium/high → new plan (short loop back to Stage 4), wrong approach → back to design (Stage 3), unresearched unknown → back to research (Stage 2), wrong goal → stop, user's call.

Inputs to review, per the table: the diff produced by the Athanor, plus the plan it was given. The design doc is implicitly in scope too ("wrong approach... back to design"), though the table only lists "diff + plan" as formal input.

Who reviews: "fresh Opus reviewer (never the Athanor that cooked it)" — athanor.md reinforces this from the producer's side:

plugins/spire/agents/athanor.md:39 Output goes to a fresh reviewer. Your deliverable (diff + plan reference) is reviewed by an independent agent in Stage 6 — never by you. Do not self-review.

Searching the whole plugins/spire tree for "reviewer" turns up exactly three hits — the two above plus one in plugins/spire/skills/implementation/SKILL.md:10:

"Its output (diff + plan reference) goes to a fresh reviewer for Stage 6 (Review)."

There is no plugins/spire/agents/reviewer.md. The full agent roster is adept.md, athanor.md, igor.md, researcher.md, scout.md, search.md, zathras.md — no reviewer. Stage 6 today means Igor dispatching a plain Opus subagent (per the delegation table in igor/SKILL.md:76-85, closest match is "Complex summaries, git fixes, small code changes → Sonnet subagent" or an ad-hoc Opus dispatch; none of the pinned tiers is explicitly "review"). This is a gap, not a hidden agent — worth flagging back to the goal owner if a reviewer agent is ever formalized, since that would be the natural place to pin orbit as a preloaded skill (the same pattern adept.md/athanor.md/zathras.md use for spire:workpad, spire:project, etc.).

There's also no dedicated "review skill" in plugins/spire/skills/ — review is described entirely in igor/SKILL.md and the design doc, not factored into its own skill file the way implementation is (plugins/spire/skills/implementation/SKILL.md).

2. Which Spire agents benefit from orbit, and where

Agent	Benefit	Concrete review question orbit answers
search (plugins/spire/agents/search.md)	Highest-value integration point. Already Bash + read-only, no Agent tool — matches orbit's own guidance ("call orbit from the shell," guide §13). Igor already dispatches search for "code/file search, symbol tracing" (igor/SKILL.md:80); during review this becomes "what does the diff touch, structurally."	Changed-definitions inventory: for each file in the diff, orbit repo-map class/api <file> to get the shape instead of eyeballing a raw diff.
the (future) reviewer / current ad-hoc Opus reviewer at Stage 6	This is where orbit's value concentrates — reviewing a diff against a plan is exactly "did this change reach further than the plan said, and correctly."	Blast radius: orbit repo-map extends <Trait/Class> and CALLS-edge SQL joins to answer "what depends on the code this diff changed" before signing off severity. Trait implementor coverage: repo-map extends <Trait> lists every impl — check the diff didn't leave one impl un-updated after a trait method signature change. Module boundary violations: orbit repo-map imports <path> / orbit sql over gl_imported_symbol to check a diff didn't introduce a downward or cross-boundary import it shouldn't have. Branch-vs-main structural diff: orbit indexes per-worktree snapshots (guide §7/§13 "orbit indexes snapshots, not history"); indexing both the branch worktree and main and diffing repo-map api/class output for the touched modules gives a structural diff a text diff can't — new/removed public surface, changed method signatures — directly answering "does this diff fulfill the plan" (Stage 6's stated job).
researcher (plugins/spire/agents/researcher.md)	Has Edit/Write and does deep multi-source investigation; a good fit for the rarer "review found the approach is wrong, back to design" loop, where an architecture-survey-style orbit workflow (guide §12.3) is warranted rather than a quick diff check.	E.g., "is the new trait actually a good abstraction boundary" — inventory of existing implementors and their shape before recommending a design change.
adept (plugins/spire/agents/adept.md)	Long-lived, domain-scoped, accumulates key-files.md/architecture.md. Could keep a standing note of a domain's key trait hierarchies or module boundaries (from a one-time orbit survey), refreshed via its existing "drift check" (git log <verified-at>..HEAD -- <covers paths>, adept.md:30-34) rather than re-running orbit every consultation. Orbit would seed the doc; the drift check already tells the adept when to re-verify.	Not a review-question answerer directly, but a place blast-radius/boundary knowledge could live between review sessions instead of being recomputed each time.
athanor (plugins/spire/agents/athanor.md)	Should not itself run orbit — it dispatches. But when decomposing a large implementation brief, it could dispatch a search subagent with an orbit query to establish blast radius before implementing, feeding the plan rather than only the post-hoc review (implementation-support use case, explicitly deferred per the plan's "Direction" note: "First use case: review... Implementation support comes later"). Flag this as later-phase, not now.	—
scout (plugins/spire/agents/scout.md)	Too lightweight/Haiku-tier for orbit's multi-step index→query workflow; orbit's own guide (§13) stresses re-indexing discipline and hypothesis-then-grep-verify, which doesn't fit scout's "one grep, one read, done" scope (scout.md:27-29). Not a good fit.	—
igor	Never runs tools directly (igor/SKILL.md:15-23, Core Directive) — it routes. Igor's role re: orbit is purely: know an orbit skill exists, and brief search/a reviewer with it when the task is structural.	—

Net: search for the diff-touches-what step, the Stage-6 reviewer (ad-hoc today, ideally its own pinned agent later) for blast-radius/trait-coverage/boundary/branch-diff, researcher for the rarer redesign-triggering deep dive, adept as a place to cache the results across a session.

3. Skill structure in this marketplace

Confirmed by inventory (find plugins -iname SKILL.md, 25 hits across bevy, dioxus, g4b_ai, gitea, project-uv, spire, tome). Structure:

plugins/<plugin-name>/
  .claude-plugin/plugin.json      # name, version, description, author — no skill list needed
  skills/
    <skill-name>/
      SKILL.md                    # required: YAML frontmatter + body
      references/                 # optional: longer supporting docs, loaded on demand
        *.md
      scripts/ (or *.sh at skill root, e.g. spire/skills/adepts/roster.sh)
  agents/
    <agent-name>.md                # frontmatter can preload skills via `skills:`

.claude-plugin/plugin.json (e.g. plugins/spire/.claude-plugin/plugin.json, plugins/tome/.claude-plugin/plugin.json) is just plugin metadata — name, version, description, author. No per-skill registration — any skills/<name>/SKILL.md under the plugin directory is auto-discovered. Enabling the plugin ("spire@reliquary": true in .claude/settings.json → enabledPlugins) is what exposes all its skills/agents to a project.

SKILL.md frontmatter fields observed (from plugins/spire/skills/*/SKILL.md):

• name (required)
• description (required — long, keyword-dense, written to match model-invocation triggers; see svg/SKILL.md:2 or workpad/SKILL.md:2 for the house style — enumerates trigger phrases explicitly)
• allowed-tools — restricts what the skill may invoke, e.g. project/SKILL.md: allowed-tools: Bash(cat:*); init/SKILL.md: a longer allowlist
• disable-model-invocation: true — for human-triggered-only skills (init/SKILL.md)
• Skill bodies can contain a leading !command`` line that runs and injects output before the harness even shows the skill body — project/SKILL.md does this to cat project.md inline.

How agents load skills: agent frontmatter has an optional skills: list of <plugin>:<skill> names, preloaded at agent spawn:

plugins/spire/agents/adept.md:12-14

skills:
  - spire:workpad
  - spire:adepts

plugins/spire/agents/athanor.md:14-20

skills:
  - spire:project
  - spire:workpad
  - spire:implementation
  - superpowers:using-superpowers
  - superpowers:subagent-driven-development
  - superpowers:dispatching-parallel-agents

Cross-plugin skill references work fine (superpowers:* skills loaded into athanor, tome:navigate referenced conditionally in athanor.md:25 and igor boot). This is the precedent for a standalone plugins/orbit/ plugin whose skill gets referenced from Spire agents without merging code.

Minimal template matching house style:

---
name: <skill-name>
description: >
  <One paragraph, keyword-dense, states WHEN to use it — enumerate trigger
  phrases and situations explicitly, the way workpad/SKILL.md and svg/SKILL.md
  do, so model-invocation matches reliably. State what it is NOT for too,
  if there's a nearby skill it could be confused with (e.g. "not a
  replacement for grep").>
---

# <Skill Title>

<One-paragraph statement of what decision or workflow this skill governs —
not "how to write code," but "how to decide X" (cf. workpad/SKILL.md's
opening: "This skill answers two questions only...").>

## <first decision point / section>

...

## Composition with other skills

- **`<related-skill>`** governs <adjacent concern>; defer to it for that.

References subfolder is used for material too long to inline (svg/skills/references/inline-svg.md, layout-legibility.md; igor/skills/references/mindset.md, model-tiers.md, harness-notes.md, journal-template.md) — the SKILL.md stays a decision-routing document and @references/foo.md is inlined via the @-include syntax seen in igor/SKILL.md:56 (@references/mindset.md).

4. Placement options for an orbit skill

(a) Inside Spire (plugins/spire/skills/orbit/SKILL.md or similar):

• Pro: zero extra enablement step for anyone who already has Spire; trivially preloadable into search/athanor/a future reviewer via their existing skills: frontmatter lists, same as spire:workpad.
• Con: orbit is an external tool, not every project has it, and not every Spire project is Rust (the plan's own framing: first use case is "Rust projects that use Spire," implementation support later — implying non-Rust and non-Spire uses exist too). Bundling it into Spire ties an optional, project-conditional capability to a plugin that's supposed to be broadly applicable orchestration machinery. It also means every Spire user who doesn't have orbit installed carries dead skill-description weight in their agents' trigger-matching search space.
• Con: mixes concerns — Spire's own CLAUDE.md frames it as "agent orchestration," not "a place for tool-specific integrations." tome was split out as a separate plugin for exactly this reason (knowledge navigation is optional per project, and it's referenced conditionally — athanor.md:25: "If the project has the tome plugin installed, use tome:navigate... otherwise orient via direct file reads").

(b) Standalone plugin plugins/orbit/ (mirroring tome's shape):

• Pro: matches the tome precedent exactly — an optional capability plugin, enabled per-project (enabledPlugins: {"orbit@reliquary": true} only where orbit is installed and useful), referenced conditionally from Spire agents ("if the project has the orbit plugin installed, use orbit:review; otherwise fall back to grep" — same sentence shape as the tome line above).
• Pro: reusable outside Spire entirely — any project/agent setup in this marketplace could enable orbit@reliquary without pulling in Spire's orchestration machinery. Matches the plan's stated aim that implementation support (non-review) comes later and might have a different consumer than the review skill.
• Pro: can iterate/version independently — this is explicitly an "early prototype" (plan.md), and a standalone plugin can be broken or rewritten without touching Spire's stability.
• Con: one more plugin to enable per project; Spire agents need an explicit conditional check (cheap — same pattern already used for tome).

(c) Other (e.g., a project-level skill under .claude/skills/ outside the marketplace, or folding into an existing plugin like gitea): no evidence in the repo of a per-project (non-plugin) skill mechanism being used anywhere; gitea is a different concern (ticket workflow) and not a natural home. Not recommended — no structural precedent for it in this marketplace, whereas (a)/(b) both have precedent (Spire itself, and the tome/Spire split).

Recommendation: (b), standalone plugins/orbit/. It mirrors the one existing precedent in this exact repo for "optional, tool-dependent, project-conditional capability that Spire agents use if present" — tome. A Spire agent picks it up the same way athanor.md:25 already picks up tome: a conditional line ("if .claude/spire/project.md (or plugin.json availability) flags orbit, use orbit:review; otherwise use grep/read"), with the actual availability fact recorded once per project rather than re-detected every session (see §5).

5. Per-project facts and orbit availability

.claude/spire/project.md is scaffolded by plugins/spire/skills/init/SKILL.md (Phase 3, "Scaffold project.md"). It is read at agent startup by the tiny spire:project skill:

plugins/spire/skills/project/SKILL.md

---
name: project
description: Loads per-project Spire configuration (override or bundled template).
allowed-tools: Bash(cat:*)
---
!`cat "${CLAUDE_PROJECT_DIR}/.claude/spire/project.md" 2>/dev/null || echo "No project config found. Run /spire:init to set up this project."`

The scaffolded template (init/SKILL.md, Phase 3.2) already includes exactly the right slot:

- **Tome skill**: <detected tome skill or "none detected...">
...
- **Domain skills to route to subagents when relevant**: <!-- detect and list, or leave as placeholder -->

This is the natural, zero-new-mechanism place to flag orbit: extend init's Phase 2 detection (2.5, "Tome presence" — init/SKILL.md, section 2.5) with a parallel "2.6 — Orbit presence" check (e.g. which orbit, or a .orbit/ index directory in the repo root, or an orbit@reliquary entry in enabledPlugins), and populate the "Domain skills to route to subagents when relevant" field (or add a dedicated "Orbit" line next to "Tome skill") with either the detected skill name or "none detected — fall back to grep." Agents (search during review, a future reviewer) then read this fact for free via the existing spire:project preload — no new per-project config file or convention needed, just one more detection phase in init and one more line in the template it writes.

Sources

• docs/workpad/designs/2026-09-22-development-cycle.md
• plugins/spire/skills/igor/SKILL.md
• plugins/spire/agents/athanor.md, adept.md, researcher.md, search.md, scout.md, zathras.md
• plugins/spire/skills/implementation/SKILL.md, workpad/SKILL.md, research-tree/SKILL.md, project/SKILL.md, init/SKILL.md, svg/SKILL.md
• plugins/spire/.claude-plugin/plugin.json, plugins/tome/.claude-plugin/plugin.json, plugins/tome/skills/navigate/SKILL.md
• .claude/settings.json (enabledPlugins)
• docs/workpad/goals/orbit-skill.md, docs/workpad/research/2026-09-29-17-orbit/plan.md
• docs/workpad/research/2026-09-29-17-orbit/phase-0-field-guide-python-django.md (§1, §7, §8, §12, §13)