mbwsims/claude-universe/orbit

Orbit

High-altitude sweep of the project. Dispatches agents in parallel across selected areas, collects results, and synthesizes a unified report with cross-cutting observations.

Argument Parsing

Parse the user's input to determine mode and scope:

Mode — check keywords in this order:

• pr keyword present → PR mode (diff-aware branch analysis — see PR Mode below)
• deep keyword present → Deep mode (full agent dispatch, ~5-15 minutes)
• quick keyword present → Quick mode (status tools only, ~10 seconds)
• No mode keyword → Standard mode (default: status + primary analysis tools, ~30-60 seconds)

The three modes:

Standard is the daily-driver default. It dispatches a single orchestrator subagent that runs MCP tools across all areas and verifies top findings by reading code. Subagent dispatch gives fresh tool manifest access, bypassing ToolSearch deferral that can affect inline execution.

PR mode arguments (only when pr detected):

• --base {branch} → compare against that branch instead of main
• quick → MCP-only fast scan, skip deep analysis on flagged items
• Scope keywords are ignored in PR mode — it checks all systems based on file type

Scope (for Quick, Standard, and Deep modes) — match any of these keywords (multiple allowed):

If no scope keywords are found, default to all areas. Combined with the default Standard mode, /orbit with no arguments runs status + primary analysis tools across all 5 systems in parallel — the daily-driver dashboard.

PR Mode

Analyzes only the files changed on the current branch vs. a base branch. Runs focused checks through all 5 systems on just the diff. This is the daily-driver command — fast, scoped, answers "is my PR ready?"

Step 1: Gather the diff

Run:

git diff --name-status main...HEAD

(Replace main with the --base value if provided.)

If the command fails (e.g., branch has no common ancestor with base), tell the user and suggest they specify the correct base branch with --base.

Parse the output and classify each file:

Source files — any file not matching test or instruction patterns below.

Test files — match any of: *.test.*, *.spec.*, files under __tests__/, test_*.py, *_test.py, *_test.go, files under tests/ whose name starts with test_.

Instruction files — match any of: CLAUDE.md, .claude.local.md, files under .claude/rules/, .claude/agents/, .claude/skills/.

Filter out deleted files (status D). Treat renamed files (status R) as modified. Ignore copy (C) and type-change (T) statuses if they appear. Track counts of added (A) vs modified (M) for the report header.

If there are no changed files (branch is up to date with base), say so and exit.

Step 2: Quick scan (MCP calls)

For each changed file, run the appropriate MCP tools. Launch all calls in parallel (multiple tool calls in a single message).

After the per-file calls complete, also run:

• testkit_map — to find source files that changed but have NO corresponding test file

changes. Flag untested modifications.

• alignkit_local_check — to check if any changes violate documented rules.

For newly added files (status A), skip timewarp_trends — there is no history to analyze.

If any MCP tool call returns an error, note the specific tool failure in the report and continue with the tools that do work. Never report a bundled MCP as "not installed".

Step 3: Deep analysis (skip if quick)

If the user passed quick, skip this step entirely and go to Step 4.

For items flagged in Step 2, do targeted deeper analysis. This is NOT dispatching full agents — it's inline, file-scoped reads on flagged items only:

• Shield findings → Read the flagged file. Trace the data flow from user input to the

vulnerability site. Is the input actually user-controlled? Is there sanitization upstream? Classify as confirmed, likely, or false positive.

• Test gaps → Inspect the changed production file when tests were not updated. What does it do? Is it

logic that genuinely needs tests, or is it configuration/wiring? Flag business-critical mutation logic as high priority.

• Impact concerns → For files where lenskit_analyze shows high coupling (many

importers), use Grep to find the actual import sites. Are the changes to the file's public interface, or internal-only? Internal changes with high coupling are fine.

• Rule violations → Read the rule that was violated and the code that violates it.

Is the violation real? Does the code need to change, or does the rule need updating?

Step 4: Synthesize the PR readiness report

Produce this output:

# PR Review — {branch-name} → {base-branch}
 
{n} files changed ({added} added, {modified} modified, {deleted} deleted)
 
## Readiness
 
| Check | Status | Finding |
|-------|--------|---------|
| Security | {pass/warn/fail} | {one-line summary or "No issues"} |
| Test coverage | {pass/warn/fail} | {one-line summary or "All changes tested"} |
| Code quality | {pass/warn/fail} | {one-line summary or "No concerns"} |
| Complexity trends | {pass/warn/fail} | {one-line summary or "Stable"} |
| Rule conformance | {pass/warn/fail} | {one-line summary or "All rules followed"} |
 
## Issues
 
{Ordered by severity. Each cites a specific changed file and line.}
 
### Critical
 
1. **{Issue}** — `{file}:{line}`
   {What's wrong and how to fix it}
 
### Warning
 
Use the same entry format as Critical, but for non-blocking issues that still need action.
 
### Info
 
Use the same entry format as Critical, but for observations that are useful context only.
 
{Omit severity sections with no issues.}
 
## Missing Tests
 
{Source files that were modified but have no corresponding test file changes.
Order by criticality:
- HIGH: auth, payment, security, data mutation logic
- MEDIUM: business logic, API handlers
- LOW: config, types, utilities
 
If all modified source files have corresponding test changes, say "All modified source
files have corresponding test changes."}
 
## Good Patterns
 
{What the PR does well — acknowledge secure patterns, thorough tests, good structure.
If nothing stands out, omit this section entirely rather than manufacturing praise.}
 
## Verdict
 
{One sentence: "Ready to merge" / "Ready after addressing N issues" / "Needs work: {what}"}

Status assignment rules:

• pass — no findings, or only informational notes
• warn — findings exist but none are critical/blocking
• fail — critical findings that should be fixed before merge

PR Mode Guidelines

• Scope is the point. Only analyze changed files. Never expand to the full project.
• Parallel MCP calls. Launch all per-file tool calls in a single message, not sequentially.
• Be specific. Every issue must cite a file and line from the diff. No generic advice.
• Deep mode is targeted. Step 3 reads flagged files — it does NOT dispatch agents or

run full project sweeps.

• Acknowledge good work. If the PR is clean, say so. Don't manufacture issues.
• Quick is fast. When quick is passed, produce the report from MCP data alone. Users

run quick to get a 30-second answer, not a 5-minute analysis.

Quick Mode

Quick mode runs ONLY the status tool for each selected area — the fastest possible glance. Triggered by the quick keyword. Launch all status tool calls in parallel (multiple tool calls in a single message). Then synthesize into a minimal dashboard:

# Orbit — {project name} (quick glance)
 
| Area | Status | Top Signal |
|------|--------|-----------|
| Security | {risk level} | {top issue} |
| Tests | {grade} | {coverage ratio} |
| Code | {avg risk} | {file count + risk summary} |
| Evolution | {trend} | {commit frequency} |
| Instructions | {issue count} | {top diagnostic} |
 
Run `/orbit` for a fuller dashboard with detailed findings, or `/orbit deep` for a full audit.

Quick mode runs inline in the user's current turn. If some MCP tools aren't in the tool manifest (deferred by ToolSearch), attempt the calls anyway — if they fail, fall back to native tools (git, Grep, Read) for those areas. Be transparent about which areas used MCP vs native. Never report bundled MCPs as "not installed" — they ship with claude-universe.

For a more thorough analysis that guarantees fresh MCP tool access, use /orbit (Standard mode, dispatches the orchestrator subagent) or /orbit deep (full agent audit).

Standard Mode

Standard mode is the default when users run /orbit with no arguments. It dispatches the orbit-orchestrator subagent to run MCP tools and do inline verification in a fresh context. Expected runtime: 30-90 seconds on a medium project.

Why subagent dispatch?

When Claude Code has many plugins installed, MCP tool schemas can be deferred by ToolSearch, and the current turn's tool manifest may not include every bundled claude-universe MCP tool. Dispatching orbit-orchestrator as a subagent gives it a fresh tool manifest initialized from its own frontmatter — all bundled MCP tools are available to the orchestrator regardless of what's in the parent turn's manifest.

Dispatch

Use the Agent tool to launch universe:orbit-orchestrator with a prompt describing the user's scope. Example:

• No arguments → prompt: "Run Standard mode orbit across all 5 areas (security,

tests, code, evolution, instructions). Return the full dashboard."

• /orbit security tests → prompt: "Run Standard mode orbit scoped to security

and tests only. Return the dashboard covering just those areas."

The orchestrator runs the 4-step process (gather → verify → cross-reference → synthesize) autonomously and returns a complete dashboard. Your job is to dispatch it once and render its output directly — do NOT reformat or condense the orchestrator's response, it's already been synthesized for the user.

If the orchestrator agent is unavailable

If universe:orbit-orchestrator can't be dispatched for any reason (agent not registered, Agent tool unavailable, etc.), fall back to running the MCP tools inline yourself: