Turn a request into a contract, then into verified code.
CafeKit keeps the important truth outside chat. The assistant first writes the contract, then implements one approved task packet, then proves and syncs the result.
A human asks for a change.
Scope, requirements, design, and tasks become durable files.
The assistant implements one approved task packet.
Real commands and runtime proof check the result.
A separate pass checks compliance and risk.
State moves only after evidence exists.
The simple version#
Spec-driven development means the spec is the boss, not the chat.
In normal AI coding, the assistant often works from conversation memory. That is fragile. The request may be summarized incorrectly, scope may shift, and the next session may not know why a decision was made.
CafeKit changes the center of gravity. Before code changes, the work is written into specs/<feature>/. That folder becomes the shared contract for the human, assistant, reviewer, and future sessions.
Write down what should happen before code changes.
Implement only the approved task boundary.
Run commands and record exact evidence.
Update spec.json and task markdown after proof.
What the assistant is allowed to trust#
The assistant should trust durable repo artifacts first:
Machine state: phase, scope lock, task registry, approvals.
User-visible behavior and acceptance criteria.
Source-backed findings and decisions.
Architecture, contracts, data flow, invariants.
One implementation packet with files, steps, criteria, evidence.
The important point is not that CafeKit creates more files. The point is that each file answers a different question:
| Artifact | Question it answers |
|---|---|
requirements.md | What should the product do? |
research.md | What source-backed facts or decisions matter? |
design.md | How should the system be shaped? |
tasks/task-R*.md | What exact implementation unit is approved now? |
spec.json | What is the machine-readable state of the feature? |
Daily working rule#
When a feature is meaningful, use this rule:
Use /hapo:brainstorm first only when the request is not ready for specs. The delivery path itself starts here:
- Run
/hapo:specswhen the goal is clear enough to become a contract. - Do not develop until the spec has approved task packets.
- Run
/hapo:developfor one task packet at a time. - Verify with
/hapo:testand review with/hapo:code-review. - Run
/hapo:synconly after proof exists, or use/hapo:sync audit <feature>to repair drift.
When to use the full SDD path#
Use the full path when the work changes product behavior, touches multiple files, crosses runtime boundaries, changes data/auth/package contracts, affects users, needs review evidence, or may be handed to another assistant or teammate.
For tiny copy edits or clearly isolated one-line fixes, the full spec flow may be too heavy. But even then, the same habit still applies: state the boundary, change only that boundary, verify the result, and avoid hidden scope growth.
Where to go next#
Read Core workflow to see the full command path. Read Spec lifecycle when you need the deeper rules for spec.json, task packets, validation, and readiness.