/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
phase matches where you left off
- If
phase is ahead of where you think you are, trust the file — you may have compacted
- Conflict resolution (crash-mid-update): If
phase_history contains an entry for the current phase with a completed timestamp, treat that phase as done and advance to the next phase — phase_history wins over the phase field when they disagree.
- Resume from the resolved phase. Do NOT re-ask mode selection, re-run spec, or re-discover
- Worktree recovery: If
worktree_name is set in pipeline state:
- Check if worktree still exists:
git worktree list | grep "{worktree_name}"
- If exists:
cd into the worktree path to continue work
- If not found: worktree was cleaned up externally — abort orbit with warning, set
"status": "aborted"
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
- 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 from skills/spec/SKILL.md (step 3) on it, settle every GAP: from the request and codebase yourself, record each as GAP: … → settled: … (assumption) under the spec's ## Readiness Gate, then write status: approved. If a gap cannot be settled without the user, downgrade to council mode 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 every GAP: from the council output and record each under ## Readiness Gate, then write status: 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-*.md with status: 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_name and original_cwd in 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_report field
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.yaml
benchmarks/baselines/latest.json in CWD (in-repo baseline)
benchmarks/eval_runner.py in CWD (auto-detected benchmark)
- If eval is active, run
epic eval --json via 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.
- Git hygiene: conventional commits, rebase, squash fixups
- Create PR via
gh pr create with spec + audit report in body
- Record the URL in pipeline state as
pr_url. epic orbit unlock warns
when a pipeline reaches complete without it.
- 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_history entry
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).
- 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 reflect
This triggers the Ring 3 loop: observe → analyze → seed evolved skills → update metrics.
If $HARNESS_DIR/projects/{slug}/pending_synth.jsonl has records with status: "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 1
and 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 run epic 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)
1---2name: orbit3description: "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."4metadata:5 source: https://skillmd.com/skills/hashgraph-online/orbit6---78# /orbit — Complete Orbit910**CRITICAL**: Run `HARNESS_DIR=$(epic path)` first. NEVER use `.harness/` in the project directory.1112You are entering **Orbit** mode — the full autonomous pipeline from spec to PR in one shot.1314## Phase Recovery Protocol1516At the start of **every response** during an active orbit:17181. Run `ls $HARNESS_DIR/orbit/PIPELINE-*.json 2>/dev/null`192. Find the file with `"status": "running"`203. Read it. Verify `phase` matches where you left off214. **If `phase` is ahead of where you think you are, trust the file** — you may have compacted225. **Conflict resolution (crash-mid-update)**: If `phase_history` contains an entry for the current `phase` with a completed timestamp, treat that phase as done and advance to the next phase — `phase_history` wins over the `phase` field when they disagree.236. Resume from the resolved phase. Do NOT re-ask mode selection, re-run spec, or re-discover247. **Worktree recovery**: If `worktree_name` is set in pipeline state:25 - Check if worktree still exists: `git worktree list | grep "{worktree_name}"`26 - If exists: `cd` into the worktree path to continue work27 - If not found: worktree was cleaned up externally — abort orbit with warning, set `"status": "aborted"`2829If no file with `"status": "running"` exists, orbit was not started or has completed. Do not invent one.3031**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.3233## Step 0: Preflight3435**Concurrent-orbit guard** — before starting, run:3637```bash38epic orbit lock # exit 1 + "another orbit is running" if one is active → STOP39```4041On success you own the guard; run `epic orbit unlock` when the pipeline reaches42a terminal state (complete/aborted). If a crashed orbit left the lock behind,43`lock` reclaims it automatically once no PIPELINE-*.json is `running`.4445Initialize pipeline state at `$HARNESS_DIR/orbit/PIPELINE-{timestamp}.json`:46```json47{48 "id": "{timestamp}",49 "mode": null,50 "phase": "auto_detect",51 "status": "running",52 "spec_file": null,53 "goal_slug": null,54 "branch": null,55 "worktree_name": null,56 "original_cwd": null,57 "audit_fail_count": 0,58 "max_retries": 3,59 "audit_report": null,60 "pr_url": null,61 "deadline": "{ISO-8601, now + 30 minutes}",62 "started_at": "{ISO-8601}",63 "updated_at": "{ISO-8601}",64 "phase_history": []65}66```6768## Step 1: Auto-Detect Mode6970**DO NOT ask the user for mode selection.** Auto-detect the best path:7172### Detection Logic7374| Signal | Mode | Reason |75|--------|------|--------|76| PRD / detailed requirements doc exists in project | `council` | Rich input → council synthesizes best approach |77| User request is specific and actionable (clear goal, defined scope) | `direct` | No need for discovery — spec directly |78| User request is vague, unfocused, or "I want to..." without specifics | `council` | Council frames the problem better than guessing |79| User explicitly says "interactive" or "let me discover first" | `interactive` | Respect explicit preference |8081### Detection Process82831. Check for PRD/requirements docs: `ls {project}/PRD*.md {project}/docs/PRD*.md {project}/requirements*.md 2>/dev/null`842. Evaluate user request clarity:85 - **Specific**: contains concrete feature descriptions, acceptance criteria, or technical constraints → `direct`86 - **Vague**: "build X", "improve Y", "add Z" without details → `council`873. Record detected mode in pipeline state (`"mode": "direct|council|interactive"`)884. Report mode choice to user as a **notification**, not a question: `"Orbit mode: {mode} (auto-detected)"`895. Proceed immediately to the matching step below — **do not wait for confirmation**9091## Step 2A: Direct Mode (clear request → auto-spec)9293**Use when**: Request is specific and actionable.94951. Read the user's request + any existing docs (PRD, README, AGENTS.md)962. Generate spec directly at `$HARNESS_DIR/specs/SPEC-{timestamp}.md`, run the **Readiness gate** from `skills/spec/SKILL.md` (step 3) on it, settle every `GAP:` from the request and codebase yourself, record each as `GAP: … → settled: … (assumption)` under the spec's `## Readiness Gate`, then write `status: approved`. If a gap cannot be settled without the user, downgrade to `council` mode instead of guessing.973. Record via `epic mem add --title "Orbit: {mode} mode decision" --type decision --importance 0.9 --body "CONTEXT"`984. **Proceed immediately to Step 3** — no approval gate99100## Step 2B: Council Auto-Spec (complex/vague request → council)101102**Use when**: PRD exists or request needs framing.1031041. Gather the user's request from conversation context1052. Launch 4 parallel sub-agents (Architect, Skeptic, Pragmatist, Critic) — each receives ONLY the request + codebase context, NOT the full conversation (anti-anchoring)1063. Synthesize: list agreement/disagreement, produce recommended approach1074. Generate spec at `$HARNESS_DIR/specs/SPEC-{timestamp}.md`, run the **Readiness gate** (spec skill step 3), settle every `GAP:` from the council output and record each under `## Readiness Gate`, then write `status: approved`1085. Record via `epic mem add --title "Orbit: council decision" --type decision --importance 0.9 --body "CONTEXT"`1096. **Proceed immediately to Step 3** — no approval gate, no "orbit go"110111## Step 2C: Interactive Mode (explicit user choice only)112113**Use when**: User explicitly requested interactive mode.1141151. Tell user to run `/discover` → `/spec`, then say "orbit go". STOP and wait.1162. On resume: load latest `SPEC-*.md` with `status: approved`. Proceed to Step 3.117118**This mode is never auto-selected.** It requires explicit user opt-in.119120## Step 3: Build (Go)1211221. Load spec, extract `goal_slug`1232. **Git preflight**: verify clean working tree and not on detached HEAD:124 ```bash125 [ -z "$(git status --porcelain)" ] || (echo "ERROR: Dirty working tree or untracked files. Commit or stash first." && exit 1)126 git symbolic-ref -q HEAD || (echo "ERROR: Detached HEAD. Checkout a branch first." && exit 1)127 ```1283. **Worktree isolation**: Create an isolated git worktree:129 ```bash130 git worktree add .harness/worktrees/orbit-{goal_slug} -b orbit-{goal_slug} origin/{default-branch}131 cd .harness/worktrees/orbit-{goal_slug}132 ```133 - `.harness/worktrees/` is host-neutral. Do NOT use `.claude/worktrees/` —134 it is meaningless on Codex and Antigravity.135 - Record `worktree_name` and `original_cwd` in pipeline state1364. Plan tasks from Requirements (R1, R2...)1375. Execute with sub-agents — TDD, debug on failure, verify before done1386. Handle states: DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / BLOCKED1397. Integrate: full test suite, verify ACs140141## Step 4: Audit1421431. Gather scope via `git diff --stat`1442. Classify changed files (API, Frontend, DB, Backend, Tests, Infra)1453. Launch parallel sub-agents: Reviewer, Auditor, Test runner (+ scope-specific)1464. Synthesize Audit Report: Quality/Security/Performance PASS/WARN/FAIL + Spec Coverage1475. **PRESERVE audit report** in pipeline state `audit_report` field148149## Step 5: Verdict150151- **All PASS + all AC verified** → proceed to Eval (if eval.yaml exists) or Ship152- **WARN** → log, auto-proceed153- **FAIL** → increment `audit_fail_count`:154 - `< 3`: plan fixes from action items, execute, return to Step 4155 - `≥ 3`: **PAUSE** — ask user "continue or abort?"156157## Step 5.5: Eval (optional — only if eval.yaml or benchmarks exist)1581591. Check for eval config — eval is active if ANY of these exist:160 - `$HARNESS_DIR/eval/eval.yaml`161 - `benchmarks/baselines/latest.json` in CWD (in-repo baseline)162 - `benchmarks/eval_runner.py` in CWD (auto-detected benchmark)1632. If eval is active, run `epic eval --json` via the **eval** skill1643. **Eval PASS** → proceed to Ship1654. **Eval FAIL (regression detected)** → increment `audit_fail_count`:166 - `< 3`: plan fixes, execute, return to Step 4167 - `≥ 3`: **PAUSE** — ask user "continue or abort?"1685. If no eval config and no benchmarks detected, skip this step entirely169170## Step 6: Ship1711721. **Gate**: verify PASS audit report exists1732. **Integration verification** — run directly in worktree:174 - Clean build artifacts first: `cargo clean` / `npm run clean` / equivalent175 - Full build from scratch · complete test suite · linter + formatter176 - Fail → STOP. Do NOT create PR.1773. **Git hygiene**: conventional commits, rebase, squash fixups1784. **Create PR** via `gh pr create` with spec + audit report in body179 - Record the URL in pipeline state as `pr_url`. `epic orbit unlock` warns180 when a pipeline reaches `complete` without it.1815. **CI watch** — probe first, then watch:182 ```bash183 gh pr checks <PR_NUMBER> --json name,state184 ```185 - Checks exist → run `gh pr checks <PR_NUMBER> --watch`, auto-fix failures.186 - Empty result (no CI configured on the repo) → **skip the watch**. Log187 "No CI configured, skipping CI watch", append a `phase_history` entry188 recording `"ci_watch": "skipped"`, and proceed to Step 7 (evolve runs189 regardless of CI outcome, so the pipeline must never wait on checks190 that will never appear).1916. **Exit worktree**: Return to original directory and keep the worktree192193## Step 7: Evolve194195Run the evolution engine to analyze this session and generate/improve skills.1961971. **Always run** — regardless of CI outcome:198 ```bash199 epic-harness reflect200 ```201 This triggers the Ring 3 loop: observe → analyze → seed evolved skills → update metrics.202203 If `$HARNESS_DIR/projects/{slug}/pending_synth.jsonl` has records with `status: "pending"`,204 synthesize each — launch one subagent per manifest (use your host's subagent205 mechanism; do NOT name a model or CLI), then apply the body it produced:206 ```bash207 epic-harness evolve accept-synth --skill <name> --file <body.md>208 ```209 Unconsumed manifests leave the template skill body in place.2102112. **If CI green** (all checks passed): additionally run212 ```bash213 epic-harness reflect --context --days 1214 ```215 and record the successful orbit pattern into memory:216 ```bash217 epic mem add --title "Orbit: {goal_slug} succeeded" \218 --type pattern --importance 0.7 \219 --body "Orbit completed. Mode: {mode}. AC: all verified. PR: {url}. Stack: {stack}."220 ```2212223. Report the evolution outcome in the final summary (evolved skills generated, score trend).2232244. Update pipeline state: `"phase": "evolve"`, `"status": "complete"`, then run `epic orbit unlock`.225226## Step 8: Report227228```229## Orbit Complete230- Pipeline: PIPELINE-{id}231- Mode: {direct|council|interactive} (auto-detected)232- Spec: SPEC-{timestamp} ({goal_slug})233- Branch: orbit-{goal_slug}234- Worktree: orbit-{goal_slug} (preserved for PR)235- PR: {URL}236- Audit retries: {count}237238### Phase Summary239| Phase | Status | Retries |240|-------|--------|---------|241| Spec | approved | 0 |242| Go | complete | 0 |243| Audit | PASS | {count} |244| Eval | {PASS|SKIPPED} | 0 |245| Ship | complete | 0 |246| Evolve | complete | 0 |247248### Evolution249- Skills evolved: {count}250- Score trend: {improving|stable|declining}251```252253## Red Flags254- Interactive mode proceeding without spec approval (direct and council modes auto-approve)255- Continuing after 3 audit failures without user consent256- Skipping isolated integration test257- Shipping with FAIL in security audits258- Losing audit report between phases259- Creating branch with dirty working tree260- Losing worktree reference between phases261- Skipping evolve step after ship (evolve must always run, even if CI fails)