Step Result Block — Handoff Contract

Every sub-agent MUST include a structured result block at the end of their response. The Boss parses this block to extract status, artifacts, and metrics without reading the full report.

Format

<!-- STEP-RESULT
step: <step-number>
agent: <agent-name>
status: SUCCESS | FAILED
feature-id: <feature-id>
module-id: <mod-id>
artifacts:
  <key>: <file-path>
metrics:
  <key>: <value>
verdict: APPROVED | APPROVED_WITH_CONDITIONS | REJECTED | N/A
critical-issues: []
next-inputs:
  <key>: <file-path>
/STEP-RESULT -->

Examples

STEP 1 — okr.srs

<!-- STEP-RESULT
step: 1
agent: okr.srs
status: SUCCESS
feature-id: 001-xxx
module-id: mod01
artifacts:
  srs: docs/output/ipa-docs/srs/srs-mod01-xxx.md
  report: docs/output/output_logs/001-xxx/reports/01-srs-report.md
metrics:
  fea-count: 12
  tbc-count: 3
verdict: N/A
critical-issues: []
next-inputs:
  srs-path: docs/output/ipa-docs/srs/srs-mod01-xxx.md
/STEP-RESULT -->

STEP 5 — okr.reviewspec (with rejection)

<!-- STEP-RESULT
step: 5
agent: okr.reviewspec
status: SUCCESS
feature-id: 001-xxx
module-id: mod01
artifacts:
  report: docs/output/output_logs/001-xxx/reports/05-review-spec-report.md
metrics:
  critical-count: 2
  minor-count: 3
verdict: REJECTED
critical-issues:
  - "Missing BR-KR-002 boundary validation in spec §5"
  - "SCR-mod01-02 wireframe missing target field"
next-inputs: {}
/STEP-RESULT -->

Boss Parsing Rule

After each sub-agent returns, the Boss:

Extracts  block
Parses YAML content
ARTIFACT VERIFICATION (mandatory before step-3): For every path listed under artifacts:, use the Glob tool to confirm the file exists on disk.
- If ANY artifact file is missing → treat the step as FAILED, do NOT update pipeline-context.yaml with status: COMPLETE, and re-invoke the sub-agent with an explicit instruction to write the missing file(s).
- Log: [ARTIFACT GATE] STEP N — missing: <path>. Re-invoking agent.
Updates pipeline-context.yaml with artifacts and metrics — only after step-3 passes
Checks verdict for gate decisions — no need to read the full report file
If critical-issues is non-empty and verdict is REJECTED → invoke gate retry protocol

Artifact Verification Table

Steps with primary artifacts that MUST be verified on disk:

Step	Agent	Artifact key	Expected path pattern
1	okr.srs	`srs`	`docs/output/ipa-docs/srs/srs-*.md`
2	okr.bd	`bd`	`docs/output/ipa-docs/bd/bd-*.md`
3	speckit.specify	`spec`	`specs/*/spec.md`
6	speckit.plan	`plan`	`specs/*/plan.md`
8	okr.dd	`dd`	`docs/output/ipa-docs/dd/dd-*.md`
8b	okr.testkit	`testcases`	`docs/output/ipa-docs/testcase/testcase-*.md`
9	speckit.tasks	`tasks`	`specs/*/tasks.md`

Review steps (5, 7, 11) and the launch step (13) produce reports only — no primary artifact to verify beyond the report file itself.

3.1 KiB Raw Blame History