agent-status

# agent-status Use this skill whenever a project agent is doing multi-step work and the human needs to know what is actually happening. This skill is intentionally **not a dashboard generator**. It produces a truth surface backed by machine-readable artifacts: ```text .plan-iterate/<campaign-id>/status/ status.json events.jsonl proof_manifest.json STATUS.html ``` The HTML only renders the current status artifact. It must not invent progress, percentages, or completion claims. ## Core principle ```text status artifact first → HTML renders artifact → human can inspect proof ``` Never do this: ```text pretty page first → vague green language → human infers progress ``` ## Required first-viewport answers A generated status page must answer: 1. What is the agent trying to finish? 2. Where exactly are we? 3. What just passed? 4. What is still not proven? 5. What is the next action? 6. Is the agent running, blocked, idle, or waiting for the human? 7. What proof backs the current claim? 8. What should the agent not do next? ## State model Allowed states: - `not_started` - `running` - `needs_attention` - `blocked` - `failed` - `passed_scoped_gate` - `done` - `idle` Important distinction: ```text passed_scoped_gate != done ``` Only use `done` when the final stated goal has an explicit final proof artifact. ## Common commands Initialize a campaign: ```bash ./run.sh init \ --campaign refactor-harness-e2e \ --goal "Finish scoped refactor harness E2E proof" ``` Mark a gate as running: ```bash ./run.sh update \ --campaign refactor-harness-e2e \ --state running \ --current-step "Run hardened concurrent LLM + OpenCode summarize gate" ``` Record a scoped passing gate: ```bash ./run.sh gate-passed \ --campaign refactor-harness-e2e \ --label "A01-A18 hardened concurrent LLM + OpenCode summarize" \ --verdict PASS_SPEC \ --proof ".plan-iterate/refactor-harness-e2e/proof/refactor-concurrent-mixed.json" \ --next-action "Start reviewer packet + reviewer fan-in phase" \ --not-proven "Transport Room B1 UI" \ --not-proven "build_review_packet reviewer fan-in" \ --not-proven "Full OpenCode message delivery" ``` Ask the human for a decision: ```bash ./run.sh needs-human \ --campaign refactor-harness-e2e \ --question "Which next campaign should the agent run?" \ --option "A=Continue harness: reviewer packet + reviewer fan-in" \ --option "B=Transport UI: start Transport Room B1" \ --option "C=Stabilize only: checkpoint and stop" ``` Render the status page again: ```bash ./run.sh render --campaign refactor-harness-e2e ``` ## Anti-dashboard-theater rules 1. No percentages. 2. No green “complete” unless final goal proof exists. 3. Every PASS must name its proof artifact. 4. Every status must show what is not proven. 5. Every idle state must say why the agent is idle. 6. Every human-wait state must include a decision menu. 7. Every blocked state must name the missing artifact, service, gate, or decision. 8. Auto-refresh is allowed only if the page reads `status.json`. 9. If `status.json` is stale, the page must say stale. 10. Reviewer verdicts are receipts, not completion proof. ## When to use Use this for: - `/plan-iterate` - `/orchestrate` - `/review-design` - `/review-code` - `/debugger` - `/ask deep-review` - `/code-runner` - `/subagent-runner` - any multi-step project-agent work lasting more than one focused command ## Artifact expectations `status.json` is the source of truth. `events.jsonl` is append-only and records state transitions. `proof_manifest.json` lists proof artifacts named by status claims. `STATUS.html` is generated, stale-aware, and safe to open in a browser. ## Completion standard A final answer for long-running agent work should summarize the current status artifact and link or quote the `STATUS.html` path when available. Do not claim completion unless: - state is `done`; - `last_completed.proof_path` points to a final proof artifact; - `not_proven` is empty or explicitly out of scope; - blockers are empty.