manage-run

name: manage-run description: | Use when: User wants to INSPECT, MONITOR, START, APPROVE, or CONTROL Archon workflow RUNS in the current project — driven through the archon CLI over bash. Triggers (inspect): "what's running", "list runs", "show recent runs", "run status", "did the review pass", "check run ", "show me run ", "what happened in that run". Triggers (control): "approve the plan", "approve run ", "reject that run", "cancel that run", "abandon run ", "resume run ", "continue that run". Triggers (start): "start in the background", "kick off detached". Capability: Drives archon workflow runs/get/status/run --detach/approve/reject/abandon/resume with machine-readable --json output, scoped to the current project by cwd. NOT for: Authoring workflows/commands, or Archon setup/config — use the broader archon skill.

argument-hint: "[run-id or workflow] [comment]"

Manage Archon Runs

A focused skill for managing workflow runs through the archon CLI. It assumes Archon is already installed and you are working inside the project repo — the current directory scopes every command to that project automatically. For authoring workflows, setup, or config, use the broader archon skill instead.

Recent runs (live)

!archon workflow runs --limit 10 2>&1 || echo "Archon CLI not installed. (This skill needs the archon CLI on PATH.)"

How output works

• Add --json to any command for a single clean JSON object on stdout (logs are suppressed automatically in --json mode). Prefer --json when you will parse the result.
• Without --json you get human-readable text. Diagnostics/warnings always go to stderr.
• The current directory (cwd) determines which project's runs you see. Run from the repo.

Verbs

There is no separate cancel verb — abandon cancels a non-terminal run by id.

Patterns

Monitor a run to completion

archon workflow runs --json                 # find the run id
archon workflow get <run-id> --json         # poll status: running | completed | failed | paused

A run is finished when status is completed, failed, or cancelled.

Start work without blocking

archon workflow run archon-assist "Investigate the flaky test" --detach
# returns immediately; the run then appears in `archon workflow runs`

--detach runs the workflow in a background child. The parent can't print the new run id (it's created in the child) — find it with archon workflow runs. If the run never appears, check the child log path printed by the command (or the logPath field in --detach --json).

Console UI note: a detached run appears in the web console's Workflow dock (the dock lists runs by project) and updates live — even though it executes in a separate process. A server-side poller tails the workflow-event table and replays new rows to the console's live feed (on PostgreSQL a NOTIFY trigger pushes them within the same second; on SQLite the poller picks them up on its short interval). No refresh is needed.

Approve or reject a paused run (two steps)

--json approve/reject/resume record the decision (the run becomes resumable) but do not execute the workflow — execution streams output that would corrupt the JSON. So:

archon workflow approve <run-id> "ship it" --json   # records the approval (resumable: true)
archon workflow resume <run-id>                      # execute it — run this as a BACKGROUND task
archon workflow get <run-id> --json                  # poll until completed/failed

If you only need to record the decision (e.g. cancel via reject) and don't need to drive the run forward, the --json step alone is enough. To approve and continue in one blocking call, drop --json: archon workflow approve <run-id> "ship it" auto-resumes (run it as a background task).

Reference

For the full flag list and JSON shapes of each verb: read references/commands.md.