skilld
All skills
simota avatar

/orbit

@35ffd55
by shingo imotasimota/agent-skills85 stars
15

Running autonomous loops for nexus-autoloop. Generates script sets from goals, designs operation contracts, audits live loops, and recovers state — runners that complete reliably.

Ask your Agent

Use this Skill: https://skilld.dev/gh/simota/agent-skills/orbit

This session only. Nothing lands on disk.

referencescript-flow.md

≈1.3k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Orbit Script Processing Flow

Purpose: load this when debugging loop behavior or explaining how the generated scripts interact. It summarizes lifecycle flow without repeating the full templates.

Contents

  1. Overall lifecycle
  2. Recovery flow
  3. Verification structure
  4. Inter-script relationships
  5. Key design points

Overall Lifecycle

Stage Main actions Key guardrails
Bootstrap create loop directory, goal.md, progress.md, state.env, optional verify.sh, always run-loop.sh and notify.sh do not overwrite existing goal.md, progress.md, or state.env
Pre-flight disk >= 100MB, lock liveness, git health, log rotation, checksum validation abort on [PREFLIGHT:FAIL] unless an explicit bypass exists
Branch setup record ORIGIN_BRANCH, prepare ITER_BRANCH, stash and restore dirt when needed only when BRANCH_ISOLATION=true and AUTOCOMMIT=true
Main loop external-terminator gates (wall-clock / budget / goal-drift / convergence), health check, executor run, verification, scoped auto-commit, DONE gate, signature record, state write, notify bounded retry, triple DONE gate (done.md + verify + placeholder-clean), atomic state.env writes, external termination by LOOP_TIMEOUT / USD_*_CAP
Post-loop squash move from iteration branch to summary branch and squash if configured only when STATUS=DONE, BRANCH_ISOLATION=true, SQUASH_ON_DONE=true
Footer emit NEXUS_LOOP_STATUS and NEXUS_LOOP_SUMMARY non-DONE states collapse to footer CONTINUE

Recovery Flow (recover.sh)

Usage: recover.sh [--reset-circuit] [--repin-goal] [--clear-stall] [--migrate] [LOOP_DIR]

  1. parse flags + LOOP_DIR; preserve resumable fields (ORIGIN_BRANCH, ITER_BRANCH, CONTRACT_VERSION, cost) from the existing state.env
  2. apply targeted flags (--reset-circuit → delete .circuit-state; --clear-stall → delete .action-sig.log; --repin-goal → re-pin .goal.sha256; --migrate → bump CONTRACT_VERSION)
  3. read latest iteration from progress.md; infer recovered status from recent evidence
  4. rebuild state.env atomically with preserved fields, then refresh state.env.sha256 so the runner does not re-trigger recovery on resume
  5. append a recovery note (incl. which flags ran) to progress.md

Source-of-truth order:

  1. progress.md
  2. runner.log
  3. existing state.env

Class → flag mapping: CIRCUIT_OPEN → --reset-circuit; CONVERGENCE_STALL/OSCILLATION_LOOP → --clear-stall (after disambiguation); GOAL_DRIFT → --repin-goal (after confirming the baseline).

Verification Check Structure (verify.sh)

  1. initialize PASS=0, FAIL=0
  2. run each acceptance check through run_check
  3. print pass/fail lines
  4. exit 1 if no checks ran or any check fails, else exit 0

Effect on DONE:

  • PASS allows done.md to promote the loop to DONE
  • FAIL forces CONTINUE
  • no verify.sh means SKIP, which is tolerated but weaker evidence

Inter-Script Relationships

Producer Consumer Contract
bootstrap.sh goal.md, progress.md, state.env, optional verify.sh, run-loop.sh, notify.sh bootstrap initializes the loop contract
run-loop.sh reads state.env, goal.md, optional verify.sh, optional notify.sh, optional done.md main execution loop
run-loop.sh writes progress.md, runner.log, state.env, state.env.sha256, .run-loop.lock, .goal.sha256, .action-sig.log, optional .iter-timings.log; reads optional .cost-usd resumable execution state + stall/budget/immutability evidence
run-loop.sh creates loop/iter-{name} and loop/summary-{name} branch isolation and final squash
recover.sh reads progress.md and rewrites state.env evidence-based recovery
notify.sh reads commit metadata and writes notification logs/audio non-fatal notification hook

Key Design Points

  • DONE is a triple gate: done.md plus verify PASS/SKIP plus placeholder-clean changed src (PLACEHOLDER_GREP, AP-12)
  • termination is enforced externally: MAX_ITERATIONS (count), LOOP_TIMEOUT (wall clock), USD_PER_RUN_CAP / USD_PER_ITER_CAP (budget, via executor-emitted .cost-usd)
  • semantic-stall guard: identical change-signature over CONVERGENCE_WINDOW iterations → CONVERGENCE_STALL and stop
  • goal.md is sha256-pinned at loop start; mid-run change ABORTs (GOAL_IMMUTABLE, AP-16)
  • retry is bounded by RETRY_LIMIT
  • executor attempts, retry delays, and verification share the remaining LOOP_TIMEOUT budget through run_with_budget; portable_timeout terminates the process group at the limit
  • dirty baseline uses NUL-delimited paths; scoped commits preserve pre-existing staged work and exclude loop runtime files
  • state.env is written atomically and protected by checksum
  • the runner traps shutdown signals and writes resumable state
  • only READY, CONTINUE, and DONE are valid footer statuses
  • pre-flight uses 100MB; iteration health uses 50MB
  • adaptive timeout uses median of the last 5 executions times 2, bounded to [EXEC_TIMEOUT, EXEC_TIMEOUT x 3]

For exact script bodies, use script-templates.md.

Source: SKILL.md on GitHub

Third-party checks

1 alert13d5 checks · Risk SAFE
  • Gen Agent Trust Hub13d

    The orbit skill is a comprehensive framework for engineering and managing autonomous agent loops. It generates and audits shell scripts designed to execute tasks via various AI engines (Codex, Claude, Gemini). While the skill enables high-autonomy behaviors—including arbitrary command execution and bypassing tool permissions—it incorporates extensive safety controls such as budget caps, wall-clock timeouts, circuit breakers, and mandatory independent critic reviews to mitigate potential risks.

  • Socket13d

    2 alerts: gptAnomaly

  • Snyk13d

    Risk: LOW · No issues

  • Runlayer6mo

    5/11 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at 35ffd55. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 2 weeks ago

README badge

README badge for simota/agent-skills/orbit