HANDOFF.json Schema

HANDOFF.json is the single state file that carries context between pipeline stages. Each agent reads the current version and writes the next — never writing a lower version number than it found. The file lives at artifacts/pipeline/HANDOFF.json.

v1 — Discovery Output

Written by Agent 1 (Discovery) after !compile.

{
  "version": 1,
  "project_name": "InvoiceFlow",
  "spec_hash": "sha256:a1b2c3...",
  "spec_path": "artifacts/discovery/feature-spec.md",
  "platforms": ["web"],
  "complexity_tier": "Standard",
  "tech_stack": {
    "web": "Next.js 15 + Prisma + NextAuth v5 + Stripe"
  },
  "open_questions": [],
  "design_contract_path": "artifacts/discovery/design-contract.md",
  "cia_completed": true
}

v2 — Planning Output

Written by Agent 2 (Planning) after planning completes.

{
  "version": 2,
  // ...v1 fields preserved...
  "task_count": 24,
  "task_graph_path": "artifacts/build/TASK-GRAPH.md",
  "tdd_path": "artifacts/build/TDD.md",
  "schema_hash": "sha256:d4e5f6...",
  "contracts_path": "artifacts/build/contracts/",
  "file_ownership_map_path": "artifacts/build/FILE_OWNERSHIP_MAP.md",
  "patterns_applied": ["PATTERN-001", "PATTERN-002", "PATTERN-003"],
  "change_log_path": "artifacts/pipeline/CHANGE_LOG.md"
}

v3 — Builder Output

Written by Agent 3 (Builder) on SHIP declaration.

{
  "version": 3,
  // ...v2 fields preserved...
  "tasks_completed": 24,
  "tasks_stale": 0,
  "tasks_blocked": 0,
  "patterns_used": ["PATTERN-001", "PATTERN-002", "PATTERN-003"],
  "decisions_log_path": "artifacts/pipeline/DECISIONS.md",
  "checkpoint_path": "artifacts/pipeline/CHECKPOINT.md",
  "perf_budget_path": ".agent/PERF_BUDGET.json",
  "cross_task_regressions_detected": 0
}

v4 — Critic Output

Written by Agent 4 (Critic) after completing the full product review.

{
  "version": 4,
  // ...v3 fields preserved...
  "scorecard_mean": 3.7,
  "scorecard_verdict": "CONDITIONAL",
  "dimensions_at_risk": ["D9"],
  "auto_hold_triggers": [],
  "critical_flaws": [],
  "top_priority_fix": "D9: Empty states on 3 screens show raw no-data messages with no CTA or guidance",
  "overall_verdict": "CONDITIONAL",
  "criticism_path": "artifacts/critique/CRITICISM.md",
  "next_action": "Add guided empty states with CTA to Bookings, Invoices, and Clients screens"
}

v5 — Security Output

Written by Agent 5 (Security) after completing the domain review.

{
  "version": 5,
  // ...v4 fields preserved...
  "security_tier": "Standard",
  "domains_reviewed": 12,
  "critical_findings": 0,
  "high_findings": 1,
  "medium_findings": 3,
  "low_findings": 5,
  "blockers": [],
  "accepted_risks": [
    {
      "id": "SEC-H01",
      "finding": "Rate limiting not implemented on /api/auth/login",
      "rationale": "Accepted for MVP; tracked in TASK-GRAPH for v1.1",
      "accepted_by": "human"
    }
  ],
  "security_report_path": "artifacts/security/SECURITY_REPORT.md"
}

v6 — Verifier Output

Written by Agent 6 (Verifier) after all verification phases complete.

{
  "version": 6,
  // ...v5 fields preserved...
  "ship_verdict": "SHIP",
  "spec_compliance_pct": 100,
  "tc_pass_rate": 1.0,
  "contract_verdict": "CONFORMANT",
  "perf_verdict": "PERF_PASS",
  "perf_report_path": "artifacts/verification/PERF_REPORT.md",
  "visual_baseline_path": "artifacts/verification/screenshots/baselines/",
  "design_contract_score": 94,
  "accessibility_violations": 0,
  "verification_report_path": "artifacts/verification/VERIFICATION_REPORT.md",
  "conditional_notes": []
}

Field Reference