zf-harness-design-handoff

Files (1)

• SKILL.md

SKILL.md (first lines)

# ZaoFu Design Handoff (arch ↔ critic ↔ orchestrator)

## Why this skill exists

Stage ② design (arch) and stage ③ design_critique (critic) feed stage ④
backlog (orchestrator). Arch may create rich **candidate** plan/backlog
artifacts, but only orchestrator accepts/merges them into final task
contracts. If arch and critic don't agree on the event payload shape,
orchestrator can't deterministically synthesize the 6
`required_backlog_refs` (`docs/impl/22-zaofu-canonical-dag.md` §4.2.1)
and `task.contract.invalid` blocks dev dispatch.

This skill is the contract between three roles.

## Ref channels (do not mix)

ZaoFu accepts planning output from any content skill pack, but lifecycle event
payloads use a stable adapter contract:

- `artifact.manifest.published.artifact_refs` is the **structured manifest**
  channel: object refs with `kind/path/sha256/summary/status`.
- `arch.proposal.done` / `design.critique.done` / terminal gate events use
  `artifact_refs` as a **string path list** only. If you need structured
  metadata, publish a manifest first and reference its event id.
- `artifact_manifest_event_id` links the lifecycle event back to the structured
  manifest. This keeps ZaoFu independent from whether the content came from
  `agent-skills`, yoke, a project-local skill pack, or a different provider.

## Schema arch MUST emit (arch.proposal.done)

```json
{
  "summary": "<one-sentence behavior statement; goes into contract.behavior verbatim>",
  "file_plan": [
    "packages/foo/src/bar.ts",
    "test/unit/foo/bar.test.ts",
    "packages/foo/package.json"
  ],
  "test_plan": {
    "framework": "vitest" or "pytest" or "...",
    "location": "test/unit/foo/bar.test.ts",
    "cases": [
      "happy_path",
      "boundary_zero",
      "boundary_max",
      "invalid_input_throws"
    ],
    "min_required": 4
  },
  "verification_command": "PATH=... pnpm install --frozen-lockfile && pnpm exec vitest run test/unit/foo/bar.test.ts",
  "scope_compliance": {
    "respects_exclusions": true,
    "touches_only_listed_files": true
  },
  "risks_and_clarifications": [
    "RISK-1: <thing reviewer should check>",
    "..."
  ],
  "evidence_refs": [
    "packages/foo/package.json",
    "docs/specs/phase-1/...",
    "CLAUDE.md §6"
  ],
  "artifact_manifest_event_id": "evt-<artifact.manifest.published id>",
  "artifact_refs": [
    "docs/plans/foo-implementation-plan.md",
    "docs/plans/foo-backlog.md"
  ],
  "dispatch_id": "<from briefing>"
}
```

**Required fields**: `summary`, `file_plan`, `test_plan` (or `verification_command`), `dispatch_id`.

**Optional but strongly recommended**: `risks_and_clarifications`, `scope_compliance`,
`evidence_refs`, `artifact_manifest_event_id`, `artifact_refs`. These reduce
critic's auditing effort and let orchestrator pre-populate
`contract.exclusions` and `contract.evidence_contract`.

If arch created rich artifact metadata, it MUST be published in
`artifact.manifest.published` before `arch.proposal.done`. Do not paste object
refs into `arch.proposal.done.artifact_refs`; that field is a replayable string
path list for evidence gates.

Arch-authored planning artifacts are normally `status=draft` or
`status=proposed`. That status means "candidate input for critic and
orchestrator", not accepted runtime truth. Orchestrator may accept the candidate
as-is, merge several candidate artifacts into a new final artifact, or reject
the package and re-dispatch arch.

## Schema critic MUST emit (design.critique.done OR gate.failed)

### Success path (critic approves arch's plan)

```json
{
  "verdict": "approve",
  "summary": "<one-line: what was reviewed and what conclusion>",
  "risks": [],   // empty or low-severity informational risks
  "fix_items": [],   // empty — nothing to fix
  "evidence_refs": [
    "arch event evt-...",
    "packages/foo/package.json",
    "docs/specs/..."
  ],
  "dispatch_id": "<from briefing>"
}
```

### Reject path — TWO event-type options (same semantic after P1/K2):

**Option A — `design.critique.done verdict=reject`** (preferred default):

```json
{
  "verdict": "reject",
  "summary": "<reason in one sentence>",
  "risks": [
    "BLOCKER-1: <hard issue arch must fix>",

From uisee-ai/zaofu, Apache-2.0.

More from uisee-ai/zaofu