Runloop

Runtime-first task lifecycle for agent work.

This project stores task state in JSON and uses a Rust CLI to list tasks, select context, update lifecycle state, and validate completion evidence. Markdown is intentionally minimal: README.md for humans and AGENTS.md for agents.

The CLI entrypoint is intentionally thin. Core completion rules live in rust/src/run_policy.rs, schema/config/run validation lives in rust/src/runtime_validation.rs, run-file IO and target resolution live in rust/src/run_store.rs, command mutations live in rust/src/run_commands.rs, and shared command enums live in rust/src/runtime_constants.rs.

Project flow

The diagram below shows how a user request moves through an active run, worker slices, evidence, review, closeout, and completion.

Structure

runloop/
├─ README.md
├─ AGENTS.md
├─ runloop.config.json
├─ .agents/
│  └─ skills/
├─ rust/
│  ├─ Cargo.toml
│  └─ src/
│     ├─ schema.rs
│     ├─ runtime_constants.rs
│     ├─ run_store.rs
│     ├─ run_commands.rs
│     ├─ runtime_validation.rs
│     ├─ run_policy.rs
│     ├─ main.rs
│     └─ tests.rs
└─ runs/
   ├─ active/
   │  └─ <task-id>.json
   ├─ archive/
   │  └─ <task-id>.json
   └─ examples/
      └─ example-task.json

Build

cd rust && cargo build --release

The binary will be at rust/target/release/runloop (or runloop.exe on Windows).

Install

Recommended install:

npx @kirakas/runloop@latest

This installs the Rust runloop CLI with Cargo, copies the bundled Codex skills into ~/.codex/skills, verifies the command and skill files, and then prints a reminder to restart Codex so the new skills are loaded.

Cargo-only install from GitHub without cloning:

cargo install --git https://github.com/KiraKas-Tr/RunLoop.git runloop-cli --force

Or install from a local checkout:

cargo install --path rust --force

This installs runloop (or runloop.exe on Windows) into Cargo's user bin directory.

Initialize Runloop in a project before using lifecycle commands there:

cd path/to/your/project
runloop init

runloop init creates runloop.config.json plus runs/active, runs/archive, and runs/examples. It refuses to overwrite an existing runloop.config.json.

After initialization, run commands from that project root so the CLI can read runloop.config.json.

Commands

Common commands:

runloop init
runloop active
runloop status
runloop create <task-id> [--goal <goal>] [--strictness <light|standard|strict>] [title]
runloop context <task-id-or-path>
runloop add-evidence <task-id-or-path> <criterion-id> --type <type> --detail <detail>
runloop validate [task-id-or-path|--all]
runloop dry-run [--all]
runloop complete <task-id-or-path> --summary <summary> --evidence <item>

Coordination commands:

runloop slice <task-id-or-path> --id <id> [--goal <goal>] [--owner <owner>]
runloop assign <task-id-or-path> --slice <id> --type <main|sub-agent|reviewer|automation|agent|squad> --id <assignee>
runloop worker once --id <worker-id> [--task <task-id-or-path>]
runloop review-pass <task-id-or-path> --status <pass|fail> --context <fresh|same> --detail <detail>
runloop closeout <task-id-or-path> --check-type <type> --check-detail <detail>

Project/runtime commands:

runloop list [--all]
runloop doctor [--all]
runloop pack <quick|runtime|task> [task-id-or-path]
runloop workspace list
runloop workspace current

Run runloop --help for the full command surface, including agents, runtimes, skills, squads, blockers, gates, and workspace migration.

Command semantics

| Command | Default scope | Mutates state | Notes | | --- | --- | --- | --- | | list | runs/active/ only | No | Use list --all to include archive and examples. | | active | runs/active/ only | No | Shows every JSON run in the active directory, including blocked and user-decision states. | | workspace | runloop.config.json | Yes for create/migrate/use/clear | Creates isolated workspace run directories, migrates flat-layout JSON runs, switches current workspace explicitly, or returns to the default flat layout. | | status | runs/active/ only | No | Compact goal-health summary; use status --all for full scope. | | doctor | runs/active/ only | No | Same goal-health checks as status, but exits nonzero on unhealthy goals. | | context <task> | Explicit target | No | Prints the task file and declared context files with existence markers. | | start <task> | Explicit target | Yes | Marks a draft task in progress and records start metadata. | | add-evidence <task> <criterion> | Explicit target | Yes | Appends evidence to one success criterion. | | criterion <task> | Explicit target | Yes | Creates or updates success criterion text without hand-editing JSON. | | add-iteration <task> | Explicit target | Yes | Appends one plan/work/check/decision record. | | gate <task> | Explicit target | Yes | Records a harness gate result for quality, security, validation, or classification. | | design <task> | Explicit target | Yes | Records the design gate: problem, options, tradeoffs, selected option, decision, and accepted debt notes. | | ledger <task> | Explicit target | Yes | Appends a main/sub-agent/reviewer worklog entry so interrupted work can resume from evidence. | | debt <task> | Explicit target | Yes | Upserts debt register entries when a faster or less optimal path is deliberately accepted. | | review-pass <task> | Explicit target | Yes | Appends one review-loop pass and a review activity event; completion requires consecutive fresh-context passes. | | closeout <task> | Explicit target | Yes | Records closeout checks such as tests, benchmarks, affected areas, and heuristic inspection evidence. | | blocker <task> | Explicit target | Yes | Adds or resolves goal blockers and decisions needed before completion. | | agent <task> | Explicit target | Yes | Creates, updates, lists, or changes status for agent profiles in the run roster. | | skill <task> | Explicit target | Yes | Registers reusable skills, stores inputs/commands/evidence templates, and records skill applications. | | comment <task> | Explicit target | Yes | Appends an agent comment to the activity stream, optionally linked to a slice. | | squad <task> | Explicit target | Yes | Registers squads, updates membership, and lists squad routing metadata. | | route <task> | Explicit target | Yes | Records a squad leader routing decision from a slice to a member agent. | | worker once | Active run or --task | Yes | Claims the first queued slice assigned to the worker, starts it, and can complete or fail it with activity events. | | slice <task> | Explicit target | Yes | Records a bounded work slice for main/sub-agent/reviewer/automation/agent/squad coordination without auto-spawning agents. | | complete <task> | Explicit target | Yes | Writes final report fields and marks the task complete when validation passes. | | block <task> | Explicit target | Yes | Marks the task blocked with an explicit reason. | | archive <task> | Explicit target | Yes | Moves an active completed/stopped/blocked task to archive. | | validate | runs/active/ only | No | Prints SKIP when no active runs exist; enforces configured active-run rules. | | validate --all | active, archive, examples | No | Explicit full validation. | | dry-run | runs/active/ only | No | Trial run for runtime/task state: lists then validates without mutating state. | | dry-run --all | active, archive, examples | No | Explicit full-scope dry run. | | create <task> | active directory | Yes | Creates a structurally valid draft run; use --goal to set a real goal immediately. Missing or omitted strictness defaults to strict. | | report <task> | Explicit target | No | Prints success criteria, evidence details, latest iteration, and final report details. |

Workspace migration

runloop workspace migrate --id <id> --name <display> [--switch true|false] copies JSON runs from the configured flat active, archive, and examples directories into workspaces/<id>/runs/*, creates workspaces/<id>/settings.json, and registers the workspace in runloop.config.json. Migration is copy-only: the original flat layout remains available after runloop workspace clear. Existing workspace IDs or destination JSON files are refused instead of overwritten.

Workflow

1. Create or select a task in runs/active/*.json.
2. Use runloop context <task> to get the minimal files to read.
3. Keep attention on the goal, blockers, directly affected code, and current slice. Keep process in runtime state instead of long prompt rituals.
4. Run normal tests for code-level correctness.
5. Record the design gate before deep implementation: at least two options with tradeoffs, exactly one selected option, and the decision.
6. Keep a ledger entry for meaningful coordinator, sub-agent, reviewer, or automation steps. Use slice when the main agent coordinates and a sub-agent owns a bounded slice.
7. Record debt explicitly when choosing the fastest acceptable path over the long-term best path.
8. Run review in fresh context until the configured number of consecutive pass results is reached.
9. Run closeout checks for tests, benchmarks, affected areas, or heuristic inspection.
10. Run the dry-run phase (runloop dry-run) as a runtime/task-state trial run; this is separate from code tests and does not mutate state.
11. Add evidence and gate results through runtime commands.
12. Only mark complete when validation passes and the final report is filled with status, summary, and evidence.

Strictness

Missing strictness is treated as strict for compatibility.

• strict: full completion contract: success evidence, no blockers, clear gates, design decision, ledger, review loop, closeout, and final report.
• standard: success evidence, no blockers, clear gates, ledger, review loop, closeout, and final report.
• light: success evidence, no blockers, clear gates, and final report.

Use strict by default for shared runtime, high-risk, ambiguous, or architecture-changing work. Use standard when the task is implementation work that still needs coordinator evidence and fresh review but does not need an explicit design decision. Use light for small, local, low-risk tasks where success evidence and clear blocker state are enough.

Blockers

blocker records goal state inside an active run. Use it when work can continue after a missing input, owner, or decision is resolved:

runloop blocker <task> --add "Need API owner."
runloop blocker <task> --decision "Choose retry policy."
runloop blocker <task> --resolve "Need API owner." --resolve-decision "Choose retry policy."

block changes the run status to blocked with a reason. Use it when the task should stop rather than continue through the lifecycle.

Slices

A slice is a bounded record of work and evidence. It is not an orchestration engine and does not spawn agents. The main agent coordinates the goal and integrates evidence; a sub-agent, reviewer, automation, or main agent may own a slice.

Use owner: "sub-agent" and contextPolicy: "fresh" when a slice should be reviewed or implemented from a narrow context. Keep the slice goal specific enough that its evidence can be checked without reading the whole run history.

Examples

• runs/examples/example-task.json: strict run-file shape.
• runs/examples/harness-lifecycle-task.json: strict lifecycle and gate evidence.
• runs/examples/standard-slice-task.json: standard run with a sub-agent-owned slice.
• runs/examples/light-blocker-decision-task.json: light run with blockers and decisions resolved before completion.

Context rule

Default context comes from runtime commands and JSON run files. Default runtime commands do not read runs/archive/ or runs/examples/; use explicit targets or --all only when you need history or examples.