Skip to main content
skillspec run-loop batches sensemake, decide, plan, and act into a single spec load. Instead of calling each command separately — which each parses and validates the spec independently — run-loop reads the file once and returns all four artifacts in one structured report. This is the preferred entry point for guided agent runs. Use it with --guide agent --json to start a stateful run that writes guide-state.json and guide-summary.md, and emits machine-readable --- START ---, --- CURRENT ---, and --- END --- anchors so the agent can compact the context and resume without re-reading a human checklist parade. Use --resume <run-dir> to continue an existing guided run. The command reads the run directory’s guide-state.json, determines the current phase and open requirements, and emits an updated checklist from that state.

​
Synopsis

--input and --resume are mutually exclusive.

​
Options

​
Examples

Start a new guided run and write machine-readable anchors:
Resume an existing guided run from its directory:
Non-guided batch report for scripting — summary view, no anchors:
Target a specific phase when the current phase is already known:

​
Output

Without --guide, run-loop emits a RunLoopReport containing sensemake, decision, act, and an optional trace block. The batched_commands field lists which commands were combined: ["sensemake", "decide", "plan", "act"]. With --guide agent --json, the output also includes the guide report and the command writes two files in the run directory:
  • guide-state.json — machine-readable current state: spec id, run id, current phase, open requirements, allowed commands, forbids, repeat-until condition, and exit proof commands. The agent reads this file to resume without context loss.
  • guide-summary.md — human-readable summary of the same state, suitable for run summaries and issue comments.
The anchors printed to stdout wrap the guide output so the agent can locate the boundaries for compaction-safe resume:
The --- END --- anchor in a proof-bearing run includes the quiet token-stats, final-response, and alignment commands the agent should run before closing the run.

​
Guide State and Resume

When --guide agent is active, every invocation updates guide-state.json in the trace run directory. The state records:
  • The spec id and current spec fingerprint
  • The run id and run directory path
  • The selected route and matched rules
  • The current phase and open requirements
  • The allowed commands for the current gate
  • The forbid set
  • The repeat-until condition for the loop
  • The exit proof commands (quiet trace align, compact, etc.)
To resume, pass the same spec path and the run directory with --resume:
The command reads guide-state.json, re-evaluates the current phase against the execution ledger, and emits a fresh checklist anchored to the current state.
  • skillspec run checklist <skill.spec.yml-or-run-dir> --stage entry|loop|exit --json — generate a concrete execution checklist from a spec file or an existing guided run directory. For run directories, reads guide-state.json and emits the current phase, open requirements, allowed commands, forbids, repeat-until condition, and exit proof commands. Read-only; exits non-zero when guide state is missing or exit is requested before remaining phases are complete.
  • skillspec act — expand a single phase without batching.
  • skillspec progress show — inspect phase and requirement progress for an existing run.