grahama1970/agent-status

What does agent-status do?

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:

.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

status artifact first → HTML renders artifact → human can inspect proof

Never do this:

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:

passed_scoped_gate != done

Only use done when the final stated goal has an explicit final proof artifact.

Common commands

Initialize a campaign:

./run.sh init \
  --campaign refactor-harness-e2e \
  --goal "Finish scoped refactor harness E2E proof"

Mark a gate as running:

./run.sh update \
  --campaign refactor-harness-e2e \
  --state running \
  --current-step "Run hardened concurrent LLM + OpenCode summarize gate"

Record a scoped passing gate:

./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:

./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:

./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.