Process-first specifications

A plan is the durable contract between intent and code.

CafeKit confirms scope at C1, writes plan.md and flat tasks, reviews findings at C2, and leaves completion to the user at C3.

Spec-driven development loop

CafeKit keeps the assistant moving through persistent contracts instead of relying on chat memory.

/cf:specs

C1 scope

Scout proportionally, resolve ambiguity, and record the user-approved scope and exclusions.

plan.md

Plan

Record accepted scope, constraints, decisions, ownership, dependencies, acceptance mapping, and C3 boundary.

task-NN-*.md

Task packets

Split work into flat packets with Outcome, Scope, Ownership, Acceptance, Dependencies, and Verification Plan.

adversarial findings

C2 review

The user accepts, rejects, or revises bounded findings before implementation handoff.

/cf:develop

Develop

Implement one unblocked task after task-aware inspection of real entrypoints and blast radius.

/cf:test + /cf:code-review

Proof

Run exact evidence commands, prove reachability, and reject scope drift or hidden placeholders.

/cf:sync

Sync

Write Status and inline Receipt only after proof, then present evidence and limitations for C3.

Lifecycle #

request
  -> C1: confirm outcome, scope, exclusions, constraints
  -> plan.md + flat task-NN-*.md files
  -> adversarial review
  -> C2: accept, revise, or KEEP named findings
  -> stop planning
  -> new explicit /cf:develop invocation
  -> exact verification + final inline Receipt
  -> C3: user decides whether proof and limitations are sufficient

Planning never starts implementation. No command, hook, reviewer, or host state may invent C1, C2, C3, or execution proof.

Artifact contract #

specs/<feature>/
├── plan.md
├── task-01-<slug>.md
└── task-NN-<slug>.md

plan.md records the C1 decision, acceptance criteria, exclusions, findings decisions, dependencies, and task map. Each flat task owns one outcome and exactly one Status: field.

Every task should state:

outcome and explicit boundaries
owned files or surfaces
dependencies and blockers
acceptance criteria mapped to the plan
exact planned verification command
final inline ## Receipt

Human decisions #

Gate	Question	Effect
C1	What exactly are we planning?	Locks outcome, scope, exclusions, constraints, and unresolved choices.
C2	What material gaps or risks remain?	The user accepts, requests revision, or keeps a named limitation.
C3	Is the current result good enough to close?	The user evaluates current receipts and unresolved limitations.

Execution and proof #

/cf:develop <feature> selects one unblocked task, scouts the real integration path, implements only that boundary, and runs the task's exact proof command. The controller is the sole writer of task state and proof.

A done task requires a current final inline Receipt containing:

exact command
Exit: 0
Verification: PASS
runtime-derived Base and Head
non-empty fenced current output

NO_TESTS, zero executed tests, stale output, or a green command unrelated to acceptance does not pass.

Sync boundary #

/cf:sync performs surgical updates to observed task Status and inline Receipts. It does not invent execution, approval, readiness, or completion.

Legacy compatibility #

Existing packets with spec.json, nested tasks/task-R*.md, task registries, or separate receipts stay on the installed legacy adapter. Those artifacts are not authored for new process-first Specs and must not redefine the default workflow.