Every command, subcommand and flag of ak-harness, walked from the program itself.
View raw Markdown · llms.txt · For agents
ak-harness is the harness; ak-verify is an alias of the same binary for the common verification protocol.
Every loop command takes -f <path-to-loop.config.yaml> and defaults to ./loop.config.yaml.
ak-harness doctor
Validate the contract without starting a run.
ak-harness doctor [options]ak-harness plan
Approve the frozen task contract and create a planned run.
ak-harness plan [options] <decision>| Flag | What it does | Default |
|---|---|---|
--by <actor> | approval actor | "human" |
--allow-dirty | allow a human-authorized dirty worktree | |
--context-file <path> | attach a context snapshot JSON file |
ak-harness context
Resolve portable, provenance-bearing context snapshots.
ak-harness context [options] [command]ak-harness context resolve
Resolve a Doc Bridge snapshot from the local index.
ak-harness context resolve [options] <query>| Flag | What it does | Default |
|---|---|---|
--provider <provider> | context provider | "doc-bridge" |
--scope <scope...> | optional search scopes | |
--index <path> | Doc Bridge index path | ".doc-bridge/index.json" |
ak-harness discovery
Assess a structured discovery result before implementation.
ak-harness discovery [options] [command]ak-harness discovery assess
Emit Ready or a human decision packet from a discovery JSON file.
ak-harness discovery assess [options] <input>ak-harness wip
Assess deterministic WIP admission before starting work.
ak-harness wip [options] [command]ak-harness wip assess
Emit an admission decision from WIP ledger JSON.
ak-harness wip assess [options] <input>ak-harness experiment
Select a runtime only from a controlled, comparable experiment.
ak-harness experiment [options] [command]ak-harness experiment select
Select the eligible runtime from experiment JSON.
ak-harness experiment select [options] <input>ak-harness delivery
Assess deterministic G2–G5 gates and prepare idempotent PR handoff.
ak-harness delivery [options] [command]ak-harness delivery preflight
ak-harness delivery preflight [options] <input>ak-harness delivery pr
ak-harness delivery pr [options] <input>ak-harness delivery integration
ak-harness delivery integration [options] <input>ak-harness delivery production
ak-harness delivery production [options] <input>ak-harness delivery acceptance
ak-harness delivery acceptance [options] <input>ak-harness delivery cleanup
ak-harness delivery cleanup [options] <input>ak-harness pilot
Freeze and assess a ten-issue pilot cohort.
ak-harness pilot [options] <input>ak-harness cycle
Run the five-step improvement cycle with explicit adjustment and bounded repetition.
ak-harness cycle [options] [command]ak-harness cycle assess
Assess run → verify → adjust → repeat from a cycle JSON file.
ak-harness cycle assess [options] <input>ak-harness block
Validate and assess a portable execution block manifest.
ak-harness block [options] [command]ak-harness block validate
ak-harness block validate [options] <input>ak-harness block assess
ak-harness block assess [options] <input>| Flag | What it does | Default |
|---|---|---|
--completed <ids...> | completed dependency IDs |
ak-harness preflight
Plan safe, file-scoped validation before commit.
ak-harness preflight [options] [command]ak-harness preflight files
ak-harness preflight files [options] <input>ak-harness snapshot
Create or validate a deterministic status snapshot.
ak-harness snapshot [options] [command] <input>ak-harness snapshot validate
ak-harness snapshot validate [options] <input>ak-harness learning
Parse retrospectives into proposed learnings.
ak-harness learning [options] [command]ak-harness learning parse
ak-harness learning parse [options] <input>| Flag | What it does | Default |
|---|---|---|
--source <source> |
ak-harness coordination
Manage idempotent issue/worktree claims and dispatch records.
ak-harness coordination [options] [command]ak-harness coordination claim
ak-harness coordination claim [options] <input>ak-harness artifacts
Inspect versioned, provenance-bound run artifacts.
ak-harness artifacts [options] [command]ak-harness artifacts inspect
Validate and print one artifact as JSON or Markdown.
ak-harness artifacts inspect [options] <path>ak-harness artifacts list
List artifacts for the latest or selected run.
ak-harness artifacts list [options] [run-id]ak-harness artifacts schema
Print the artifact schema version.
ak-harness artifacts schema [options]ak-harness loop
Keep-pushing SDLC loop: drain one person's Linear queue through Orca worktrees with role-based model routing.
ak-harness loop [options] [command]| Flag | What it does | Default |
|---|---|---|
-f, --file <path> | loop config path | "loop.config.yaml" |
ak-harness loop validate
Validate loop.config.yaml and print the effective configuration.
ak-harness loop validate [options]ak-harness loop doctor
Check Orca, providers, usage, machine slots, routing, and the Linear queue without dispatching.
ak-harness loop doctor [options]| Flag | What it does | Default |
|---|---|---|
--no-probe | skip provider probe commands |
ak-harness loop precheck
Read-only Orca precheck: exit 0 when the stage (tick | deliver) has work.
ak-harness loop precheck [options] <stage>ak-harness loop deliver
Drive dispatched workers to merge: PR detection, CI, review, fix rounds, squash-merge, Linear Done, cleanup.
ak-harness loop deliver [options]| Flag | What it does | Default |
|---|---|---|
--dry-run | decide only; no terminal input, no review, no merge, no Linear write | |
--issue <identifier> | restrict to one issue |
ak-harness loop stage
Run one stage (tick | deliver | retro | observe | release | intake | maintain) as an Orca precheck: prints the JSON report and exits 1 so Orca records the run without launching an agent — except observe, which exits 0 when a human has to look.
ak-harness loop stage [options] <stage>ak-harness loop tick
One keep-pushing tick: intake → admit → contract → dispatch workers into Orca worktrees.
ak-harness loop tick [options]| Flag | What it does | Default |
|---|---|---|
--dry-run | plan only; no worktree, no Linear write, no contract cached | |
--max <n> | max dispatches this tick | |
--issue <identifier> | restrict to one issue | |
--skip-contract | do not call the orchestrator when no contract is cached |
ak-harness loop contract
Freeze (or show) the orchestrator contract for one Linear issue.
ak-harness loop contract [options] <identifier>| Flag | What it does | Default |
|---|---|---|
--refresh | regenerate even when a cached contract exists | |
--dry-run | generate but do not cache |
ak-harness loop init
Grill the essentials and write loop.config.yaml from a preset (web-app | library | monorepo | data-pipeline | mobile). Everything the preset already says is left unsaid.
ak-harness loop init [options]| Flag | What it does | Default |
|---|---|---|
--preset <name> | skip the question and use this preset | |
--repo <owner/name> | GitHub repository | |
--name <name> | project name | |
--team <key> | Linear team key | |
--workspace <id> | Linear workspace id | |
--person <name> | whose queue this machine drains | |
--global | also write ~/.agentskit/harness.yaml when it does not exist | |
--force | replace an existing file | |
--dry-run | print what it would write |
ak-harness loop install
Guided install: doctor + environment checks, optional dry-run tick, then create/update the Orca automations after confirmation (idempotent by name).
ak-harness loop install [options]| Flag | What it does | Default |
|---|---|---|
--yes | accept every prompt (non-interactive) | |
--force | continue past failed checks | |
--skip-rehearsal | do not run the dry-run tick | |
--skip-local-config | do not offer to create loop.config.local.yaml | |
--dry-run | show checks and the exact orca argv; create nothing | |
--provider <agent> | Orca agent id that runs the automation prompt | |
--plain | legacy behaviour: no checks, no prompts, install immediately |
ak-harness loop uninstall
Remove the loop automations from Orca.
ak-harness loop uninstall [options]| Flag | What it does | Default |
|---|---|---|
--dry-run | print what would be removed |
ak-harness loop status
Show the loop automations Orca knows about and their latest runs.
ak-harness loop status [options]ak-harness loop resume
Resume a paused issue (clears its failure counter and removes the pause label) or, with --stage, a paused tick/deliver stage.
ak-harness loop resume [options] [issue]| Flag | What it does | Default |
|---|---|---|
--stage <stage> | resume a paused stage (tick | deliver) instead of an issue |
ak-harness loop paused
List issues the loop has paused after repeated failures (local state, no network calls).
ak-harness loop paused [options]ak-harness loop hook
Status-only line for a SessionStart hook: never installs or changes anything; always exits 0 within a few seconds.
ak-harness loop hook [options]ak-harness loop debrief
Human-facing explanation of what the loop is working on right now (in-flight issues, holds, escalations, cooldowns). Read-only; Markdown by default.
ak-harness loop debrief [options]| Flag | What it does | Default |
|---|---|---|
--issue <identifier> | restrict to one issue | |
--since <window> | how far back to look for escalations/events | "24h" |
ak-harness loop observe
Read-only anomaly scan and operating metrics for the loop (queue, workers, delivery, machine, memory, cache, tokens).
ak-harness loop observe [options]| Flag | What it does | Default |
|---|---|---|
--since <window> | window such as 24h, 7d or an ISO date | "24h" |
--precheck | exit 0 when an action is required, 1 when healthy (for schedulers) |
ak-harness loop watch
Watch delivery.json (+ optional live PR) for in-flight issues; prints DONE / FAILED / ACTION_REQUIRED / PROGRESS. Read-only.
ak-harness loop watch [options]| Flag | What it does | Default |
|---|---|---|
--issue <identifier> | restrict to one issue | |
--interval <seconds> | poll interval | 30 |
--once | single snapshot then exit | |
--timeout <seconds> | stop after N seconds (0 = until terminal) | 0 |
--no-live-pr | do not call gh; filesystem state only |
ak-harness loop retro
Digest of the loop over a window: escalations, dispatches, reviews, merges, cooldowns, Orca runs, and calibration suggestions. Markdown by default, --json for the report.
ak-harness loop retro [options]| Flag | What it does | Default |
|---|---|---|
--since <window> | window such as 7d, 12h, 30m or an ISO date | "7d" |
--learnings | print harness learning records (proposed) instead of the digest | |
--no-orca | skip the Orca run summary | |
--target <target> | only suggestions for one side: project | harness |
ak-harness loop plan
Requirements → PRD → technical design → issues. One question per round, two human gates, and the queue entry stays a human gesture.
ak-harness loop plan [options] [command]ak-harness loop plan start
Start a plan from a vague objective and ask the first question.
ak-harness loop plan start [options] <objective...>ak-harness loop plan answer
Answer the open question and ask the next one. The interview ends when the PRD has no gap left — the machine decides that, not the model.
ak-harness loop plan answer [options] <id> <answer...>ak-harness loop plan show
Show a plan (Markdown by default), or list every plan when no id is given.
ak-harness loop plan show [options] [id]ak-harness loop plan approve
Human gate: approve the PRD, which starts the architect.
ak-harness loop plan approve [options] <id>| Flag | What it does | Default |
|---|---|---|
--by <actor> | who approves | "human" |
ak-harness loop plan architect
Produce the technical design for the whole PRD and put it to a vote (2 of 3 by default).
ak-harness loop plan architect [options] <id>ak-harness loop plan approve-design
Human gate: approve the design after it reached consensus. Everything built afterwards inherits it.
ak-harness loop plan approve-design [options] <id>| Flag | What it does | Default |
|---|---|---|
--by <actor> | who approves | "human" |
ak-harness loop plan decompose
Break the approved design into issues. Without --create nothing is written to the tracker.
ak-harness loop plan decompose [options] <id>| Flag | What it does | Default |
|---|---|---|
--create | create the issues in the tracker, in the queue entry state |
ak-harness loop release
Promote the integration branch to the release branch and run the project deploy — only for a batch a human approved.
ak-harness loop release [options] [command]ak-harness loop release status
What is merged on the integration branch and not yet released, and whether it is approved.
ak-harness loop release status [options]ak-harness loop release approve
Human gate: approve exactly the batch currently on the integration branch. Anything merged afterwards needs its own approval.
ak-harness loop release approve [options]| Flag | What it does | Default |
|---|---|---|
--by <actor> | who approves | "human" |
ak-harness loop release run
Promote and deploy the approved batch (same work as loop stage release, but with a human-readable report).
ak-harness loop release run [options]| Flag | What it does | Default |
|---|---|---|
--dry-run | show what would happen; touch nothing |
ak-harness loop learning
Continuous-improvement learnings ledger and approved memory writes.
ak-harness loop learning [options] [command]ak-harness loop learning list
Show the learnings ledger under stateDir (proposed/promoted/rejected).
ak-harness loop learning list [options]ak-harness loop learning promote
Human-only: promote learning IDs into approved loop memory (token-reducing context for later tickets).
ak-harness loop learning promote [options]| Flag | What it does | Default |
|---|---|---|
--ids <ids> | comma-separated learning ids | |
--by <actor> | must be human | "human" |
--revision <rev> | sourceRevision stamped on memory records (default: unknown) |
ak-harness loop learning reject
Revoke learnings — including any the loop promoted by itself as loop-auto. The record stays in the ledger, marked rejected, and stops reaching worker briefs.
ak-harness loop learning reject [options]| Flag | What it does | Default |
|---|---|---|
--ids <ids> | comma-separated learning ids | |
--by <actor> | who revokes | "human" |
ak-harness loop learning promoted
List the learnings currently promoted, and which of them the loop promoted by itself.
ak-harness loop learning promoted [options]ak-harness start
Move a planned run into implementation.
ak-harness start [options]ak-harness verify
Execute every configured check and record evidence.
ak-harness verify [options]ak-harness run
Alias for verify, compatible with the common protocol.
ak-harness run [options]ak-harness approve
Record human approval or rejection. Use only <decision> to apply it to the latest pending run; run IDs remain an audit detail.
ak-harness approve [options] <run-id-or-decision> [decision-or-run-id]| Flag | What it does | Default |
|---|---|---|
--by <actor> | approval actor | "human" |
ak-harness authorize
Authorize or reject declared external tracking. Use only <decision> to apply it to the latest pending run; run IDs remain an audit detail.
ak-harness authorize [options] <run-id-or-decision> [decision-or-run-id]| Flag | What it does | Default |
|---|---|---|
--by <actor> | approval actor | "human" |
ak-harness retry
Create a new implementation attempt after a blocked or stale run.
ak-harness retry [options]ak-harness cancel
Cancel an active run.
ak-harness cancel [options] [run-id]| Flag | What it does | Default |
|---|---|---|
--by <actor> | cancellation actor | "human" |
--reason <reason> | cancellation reason | "Run cancelled by a human." |
ak-harness status
Show the latest run after reconciling its audit evidence.
ak-harness status [options]ak-harness audit
Reconcile a run projection with its verified lifecycle decisions.
ak-harness audit [options] [run-id]ak-harness events
Inspect the lifecycle audit log.
ak-harness events [options] [command]ak-harness events verify
Verify the latest or selected event log hash chain.
ak-harness events verify [options] [run-id]ak-harness events lock
Inspect the latest or selected event-log lock.
ak-harness events lock [options] [run-id]ak-harness events unlock
Recover an old event-log lock after confirming its owner is dead.
ak-harness events unlock [options] [run-id]| Flag | What it does | Default |
|---|---|---|
--by <actor> | recovery actor | "human" |
--max-age-ms <milliseconds> | minimum lock age | 300000 |
ak-harness events export
Export a reconciled COMPLETE run as a signed evidence bundle.
ak-harness events export [options] [run-id]| Flag | What it does | Default |
|---|---|---|
--output <path> | bundle output path | |
--private-key <path> | Ed25519 private key path | |
--key-id <id> | stable signing key identity |
ak-harness events verify-bundle
Verify an exported signed evidence bundle independently.
ak-harness events verify-bundle [options] <path>| Flag | What it does | Default |
|---|---|---|
--trusted-key-store <path> | JSON trust store with active or revoked public keys |
ak-harness benchmark
Aggregate reproducible metrics from historical runs.
ak-harness benchmark [options] [command]| Flag | What it does | Default |
|---|---|---|
--manifest <path> | benchmark manifest for baseline comparison |
ak-harness benchmark baseline
Record one controlled baseline observation in a benchmark manifest.
ak-harness benchmark baseline [options] <taskId>| Flag | What it does | Default |
|---|---|---|
--manifest <path> | benchmark manifest path | |
--status <status> | passed, failed, blocked, or not-run | |
--source <source> | baseline source or run reference | |
--evidence-file <path> | JSON file with criterion-level baseline evidence | |
--recorded-at <timestamp> | ISO-8601 timestamp | |
--attempts <count> | attempt count | |
--duration-ms <milliseconds> | duration in milliseconds | |
--review-minutes <minutes> | human review time in minutes | |
--escaped-incomplete <count> | incomplete deliveries discovered after handoff |
ak-harness clean
Remove only configured task-owned temporary artifacts.
ak-harness clean [options]