orbit
State-persisted autonomous pipeline: spec → go → audit → eval → ship → evolve in one command. Auto-detects direct/council/interactive mode. Crash-recoverable via PIPELINE-*.json. Hands-off until PR.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- orbit
- description
- State-persisted autonomous pipeline: spec → go → audit → eval → ship → evolve in one command. Auto-detects direct/council/interactive mode. Crash-recoverable via PIPELINE-*.json. Hands-off until PR.
03 SKILL.md 正文
/orbit — Complete Orbit
CRITICAL: Run HARNESS_DIR=$(epic path) first. NEVER use .harness/ in the project directory.
You are entering Orbit mode — the full autonomous pipeline from spec to PR in one shot.
Phase Recovery Protocol
At the start of every response during an active orbit:
- Run
ls $HARNESS_DIR/orbit/PIPELINE-*.json 2>/dev/null - Find the file with
"status": "running" - Read it. Verify
phasematches where you left off - If
phaseis ahead of where you think you are, trust the file — you may have compacted - Conflict resolution (crash-mid-update): If
phase_historycontains an entry for the currentphasewith a completed timestamp, treat that phase as done and advance to the next phase —phase_historywins over thephasefield when they disagree. - Resume from the resolved phase. Do NOT re-ask mode selection, re-run spec, or re-discover
- Worktree recovery: If
worktree_nameis set in pipeline state:- Check if worktree still exists:
git worktree list | grep "{worktree_name}" - If exists:
cdinto the worktree path to continue work - If not found: worktree was cleaned up externally — abort orbit with warning, set
"status": "aborted"
- Check if worktree still exists:
If no file with "status": "running" exists, orbit was not started or has completed. Do not invent one.
Crash recovery: If updated_at is older than 45 minutes and the pipeline is in status: running, assume a crash occurred. Read the state, determine the last completed phase from phase_history (rule 5 above applies), and resume from there. Report the recovery to the user.
Step 0: Preflight
Concurrent-orbit guard — before starting, run:
epic orbit lock # exit 1 + "another orbit is running" if one is active → STOP
On success you own the guard; run epic orbit unlock when the pipeline reaches
a terminal state (complete/aborted). If a crashed orbit left the lock behind,
lock reclaims it automatically once no PIPELINE-*.json is running.
Initialize pipeline state at $HARNESS_DIR/orbit/PIPELINE-{timestamp}.json:
{
"id": "{timestamp}",
"mode": null,
"phase": "auto_detect",
"status": "running",
"spec_file": null,
"goal_slug": null,
"branch": null,
"worktree_name": null,
"original_cwd": null,
"audit_fail_count": 0,
"max_retries": 3,
"audit_report": null,
"pr_url": null,
"deadline": "{ISO-8601, now + 30 minutes}",
"started_at": "{ISO-8601}",
"updated_at": "{ISO-8601}",
"phase_history": []
}
Step 1: Auto-Detect Mode
DO NOT ask the user for mode selection. Auto-detect the best path:
Detection Logic
| Signal | Mode | Reason |
|---|---|---|
| PRD / detailed requirements doc exists in project | council |
Rich input → council synthesizes best approach |
| User request is specific and actionable (clear goal, defined scope) | direct |
No need for discovery — spec directly |
| User request is vague, unfocused, or "I want to..." without specifics | council |
Council frames the problem better than guessing |
| User explicitly says "interactive" or "let me discover first" | interactive |
Respect explicit preference |
Detection Process
- Check for PRD/requirements docs:
ls {project}/PRD*.md {project}/docs/PRD*.md {project}/requirements*.md 2>/dev/null - Evaluate user request clarity:
- Specific: contains concrete feature descriptions, acceptance criteria, or technical constraints →
direct - Vague: "build X", "improve Y", "add Z" without details →
council
- Specific: contains concrete feature descriptions, acceptance criteria, or technical constraints →
- Record detected mode in pipeline state (
"mode": "direct|council|interactive") - Report mode choice to user as a notification, not a question:
"Orbit mode: {mode} (auto-detected)" - Proceed immediately to the matching step below — do not wait for confirmation
Step 2A: Direct Mode (clear request → auto-spec)
Use when: Request is specific and actionable.
- Read the user's request + any existing docs (PRD, README, AGENTS.md)
- Generate spec directly at
$HARNESS_DIR/specs/SPEC-{timestamp}.md, run the Readiness gate fromskills/spec/SKILL.md(step 3) on it, settle everyGAP:from the request and codebase yourself, record each asGAP: … → settled: … (assumption)under the spec's## Readiness Gate, then writestatus: approved. If a gap cannot be settled without the user, downgrade tocouncilmode instead of guessing. - Record via
epic mem add --title "Orbit: {mode} mode decision" --type decision --importance 0.9 --body "CONTEXT" - Proceed immediately to Step 3 — no approval gate
Step 2B: Council Auto-Spec (complex/vague request → council)
Use when: PRD exists or request needs framing.
- Gather the user's request from conversation context
- Launch 4 parallel sub-agents (Architect, Skeptic, Pragmatist, Critic) — each receives ONLY the request + codebase context, NOT the full conversation (anti-anchoring)
- Synthesize: list agreement/disagreement, produce recommended approach
- Generate spec at
$HARNESS_DIR/specs/SPEC-{timestamp}.md, run the Readiness gate (spec skill step 3), settle everyGAP:from the council output and record each under## Readiness Gate, then writestatus: approved - Record via
epic mem add --title "Orbit: council decision" --type decision --importance 0.9 --body "CONTEXT" - Proceed immediately to Step 3 — no approval gate, no "orbit go"
Step 2C: Interactive Mode (explicit user choice only)
Use when: User explicitly requested interactive mode.
- Tell user to run
/discover→/spec, then say "orbit go". STOP and wait. - On resume: load latest
SPEC-*.mdwithstatus: approved. Proceed to Step 3.
This mode is never auto-selected. It requires explicit user opt-in.
Step 3: Build (Go)
- Load spec, extract
goal_slug - Git preflight: verify clean working tree and not on detached HEAD:
[ -z "$(git status --porcelain)" ] || (echo "ERROR: Dirty working tree or untracked files. Commit or stash first." && exit 1) git symbolic-ref -q HEAD || (echo "ERROR: Detached HEAD. Checkout a branch first." && exit 1) - Worktree isolation: Create an isolated git worktree:
git worktree add .harness/worktrees/orbit-{goal_slug} -b orbit-{goal_slug} origin/{default-branch} cd .harness/worktrees/orbit-{goal_slug}.harness/worktrees/is host-neutral. Do NOT use.claude/worktrees/— it is meaningless on Codex and Antigravity.- Record
worktree_nameandoriginal_cwdin pipeline state
- Plan tasks from Requirements (R1, R2...)
- Execute with sub-agents — TDD, debug on failure, verify before done
- Handle states: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED
- Integrate: full test suite, verify ACs
Step 4: Audit
- Gather scope via
git diff --stat - Classify changed files (API, Frontend, DB, Backend, Tests, Infra)
- Launch parallel sub-agents: Reviewer, Auditor, Test runner (+ scope-specific)
- Synthesize Audit Report: Quality/Security/Performance PASS/WARN/FAIL + Spec Coverage
- PRESERVE audit report in pipeline state
audit_reportfield
Step 5: Verdict
- All PASS + all AC verified → proceed to Eval (if eval.yaml exists) or Ship
- WARN → log, auto-proceed
- FAIL → increment
audit_fail_count:< 3: plan fixes from action items, execute, return to Step 4≥ 3: PAUSE — ask user "continue or abort?"
Step 5.5: Eval (optional — only if eval.yaml or benchmarks exist)
- Check for eval config — eval is active if ANY of these exist:
$HARNESS_DIR/eval/eval.yamlbenchmarks/baselines/latest.jsonin CWD (in-repo baseline)benchmarks/eval_runner.pyin CWD (auto-detected benchmark)
- If eval is active, run
epic eval --jsonvia the eval skill - Eval PASS → proceed to Ship
- Eval FAIL (regression detected) → increment
audit_fail_count:< 3: plan fixes, execute, return to Step 4≥ 3: PAUSE — ask user "continue or abort?"
- If no eval config and no benchmarks detected, skip this step entirely
Step 6: Ship
- Gate: verify PASS audit report exists
- Integration verification — run directly in worktree:
- Clean build artifacts first:
cargo clean/npm run clean/ equivalent - Full build from scratch · complete test suite · linter + formatter
- Fail → STOP. Do NOT create PR.
- Clean build artifacts first:
- Git hygiene: conventional commits, rebase, squash fixups
- Create PR via
gh pr createwith spec + audit report in body- Record the URL in pipeline state as
pr_url.epic orbit unlockwarns when a pipeline reachescompletewithout it.
- Record the URL in pipeline state as
- CI watch — probe first, then watch:
gh pr checks <PR_NUMBER> --json name,state- Checks exist → run
gh pr checks <PR_NUMBER> --watch, auto-fix failures. - Empty result (no CI configured on the repo) → skip the watch. Log
"No CI configured, skipping CI watch", append a
phase_historyentry recording"ci_watch": "skipped", and proceed to Step 7 (evolve runs regardless of CI outcome, so the pipeline must never wait on checks that will never appear).
- Checks exist → run
- Exit worktree: Return to original directory and keep the worktree
Step 7: Evolve
Run the evolution engine to analyze this session and generate/improve skills.
-
Always run — regardless of CI outcome:
epic-harness reflectThis triggers the Ring 3 loop: observe → analyze → seed evolved skills → update metrics.
If
$HARNESS_DIR/projects/{slug}/pending_synth.jsonlhas records withstatus: "pending", synthesize each — launch one subagent per manifest (use your host's subagent mechanism; do NOT name a model or CLI), then apply the body it produced:epic-harness evolve accept-synth --skill <name> --file <body.md>Unconsumed manifests leave the template skill body in place.
-
If CI green (all checks passed): additionally run
epic-harness reflect --context --days 1and record the successful orbit pattern into memory:
epic mem add --title "Orbit: {goal_slug} succeeded" \ --type pattern --importance 0.7 \ --body "Orbit completed. Mode: {mode}. AC: all verified. PR: {url}. Stack: {stack}." -
Report the evolution outcome in the final summary (evolved skills generated, score trend).
-
Update pipeline state:
"phase": "evolve","status": "complete", then runepic orbit unlock.
Step 8: Report
## Orbit Complete
- Pipeline: PIPELINE-{id}
- Mode: {direct|council|interactive} (auto-detected)
- Spec: SPEC-{timestamp} ({goal_slug})
- Branch: orbit-{goal_slug}
- Worktree: orbit-{goal_slug} (preserved for PR)
- PR: {URL}
- Audit retries: {count}
### Phase Summary
| Phase | Status | Retries |
|-------|--------|---------|
| Spec | approved | 0 |
| Go | complete | 0 |
| Audit | PASS | {count} |
| Eval | {PASS|SKIPPED} | 0 |
| Ship | complete | 0 |
| Evolve | complete | 0 |
### Evolution
- Skills evolved: {count}
- Score trend: {improving|stable|declining}
Red Flags
- Interactive mode proceeding without spec approval (direct and council modes auto-approve)
- Continuing after 3 audit failures without user consent
- Skipping isolated integration test
- Shipping with FAIL in security audits
- Losing audit report between phases
- Creating branch with dirty working tree
- Losing worktree reference between phases
- Skipping evolve step after ship (evolve must always run, even if CI fails)
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.