forge-agent-report

forge-agent-report — the completion-report contract

Stops the Lead from hand-transcribing a dispatched Boss's final message into the dashboard. Every dispatched agent ends its final message with ONE fenced block; this skill's tool parses, validates, and ingests it.

Naming note: the tool lives at forge-bin/forge-report.cjs. The skill folder is named forge-agent-report (not forge-report) because skills/forge-report/SKILL.md already exists for a different thing — the Lead's own end-of-task delivery report format. Don't confuse the two: this skill is the per-agent machine-checkable contract; forge-report is the Lead's human-readable final report.

The contract (copy-paste into every dispatch prompt)

Include this requirement verbatim (or close to it) in every Agent(...) dispatch prompt:

End your final message with EXACTLY ONE fenced block:

​```forge-report
{
  "status": "completed|partial|blocked|failed",
  "work_package": "WP-…",
  "files_changed": ["path/one", "path/two"],
  "tests_run": "the exact command(s) + result — or \"none\" if honestly nothing ran",
  "evidence": ["what actually proves this — command output, file diff, line count, etc."],
  "blockers": ["only if status is blocked — what's blocking you"],
  "next_action": "the single most useful next step"
}
​```

If you emit more than one such block while thinking out loud, only the LAST one counts — make sure it
reflects your true final status.

When to use

• On every dispatch — the Lead includes the contract requirement above in the prompt of every Agent(...) call, named or not.
• On every return — when a dispatched agent's final message comes back, the Lead runs validate (or ingest directly) before treating the work as done. An agent claiming completed with no real evidence, or blocked with no blockers listed, is not a valid completion — send it back.

How to run

node .claude/forge-bin/forge-report.cjs validate <file|->
  # parse + validate a saved copy of the agent's message; exit 0 valid / 2 invalid

node .claude/forge-bin/forge-report.cjs ingest <run_id> <file|-> --agent "<Boss name>" [--root <projectRoot>]
  # parse + validate, then log ONE agent_output + ONE agent_evidence_added event into
  # <run>/events.jsonl (both already-registered VISIBLE-REASONING event types) — the dashboard
  # renders the report without the Lead re-typing anything. On an invalid report: logs NOTHING,
  # exit 2 — send it back to the agent instead.