Idea は contract になってから code になります。

Short version#

/hapo:specs                  # requirements, research, design, tasks
  -> approve task packet     # scope と evidence の contract
  -> /hapo:develop           # unblocked task を1つずつ
  -> /hapo:test              # real commands と runtime proof
  -> /hapo:code-review       # spec, quality, security, regression
  -> /hapo:sync              # task_registry と task markdown を同期

重要なのは command list そのものではありません。重要なのは chat が source of truth ではない という点です。永続的な contract は specs/<feature>/spec.json, requirements.md, research.md, design.md, tasks/task-R*.md にあります。

Optional pre-spec clarification#

request がまだ粗い場合は /hapo:brainstorm を使います。product direction が未確定、architecture の選択肢が残っている、risk が不明、最初の質問を repo reality に基づけたい場合です。

Brainstorm は scout-first で、delivery path の前にあります。この phase では implementation code を書きません。出力は spec-ready な decision set です: 何を解くか、何を out of scope にするか、どの architecture が最も単純か、どの risk を spec に持ち込むか。

request が requirements に変換できるほど具体的な場合だけ、この phase を skip します。

1. Request を spec にする#

/hapo:specs は intent を永続 artifact に変換します。健全な spec には以下があります:

Spec は paperwork ではありません。drift を防ぐ層です。assistant が named technology を置き換える、hidden scope を増やす、placeholder behavior を complete と呼ぶことを防ぎます。

2. Task packet を approve する#

CafeKit implementation は、assistant の頭の中にある feature 全体から始めません。1つの active task packet から始めます。

Task packet は次を答えられる必要があります:

• どの behavior が正確に in scope か？
• どの file / surface が related か？
• どの requirement を満たす task か？
• どの design contract を守る必要があるか？
• done を証明する evidence は何か？
• 何を guess せず blocker として扱うべきか？

これらが不足している場合は /hapo:specs または /hapo:sync audit <feature> に戻します。implementation guess で gap を埋めません。

3. Boundary を1つずつ実装する#

Full-spec execution は /hapo:develop <feature>、surgical task は /hapo:develop <feature> <task-file> を使います。

CafeKit の implementation rule は単純です: 1つの unblocked task、1つの scout、1つの implementation loop、1つの proof set。

Code の前に task を in_progress にします。assistant は real entrypoints, callers, adjacent patterns, previous task outputs, blast radius を inspect する必要があります。runtime-facing work は、実際の route, command, UI mount, worker, service, API boundary から reachable になるまで incomplete です。

Named contract を黙って差し替えません。spec が Next.js route, Better Auth, Redis, Drizzle, S3, OpenCode command, その他 concrete runtime choice を指定している場合、それは contract です。spec が明示しない限り、local placeholder はそれを満たしません。

4. Optimism ではなく evidence で verify する#

Implementation 後に /hapo:test <feature> または /hapo:test --full を使います。Test phase は runner を detect し、real commands を実行し、results を集め、requirements, design contracts, task evidence, reachability obligations と比較します。

NO_TESTS は pass ではありません。command が 0 で終了しても zero tests なら pass ではありません。Build success だけでは runtime-facing task の proof になりません。task には completion criteria に合う evidence が必要です。

5. Production を壊そうとしている change として review する#

/hapo:code-review --pending、feature scope、PR、commit target を使います。

Review は3層を確認します:

Critical finding は completion を block します。Review は polish step ではなく Definition of Done の一部です。

6. State と documentation を sync する#

Proof が存在してから /hapo:sync <feature> <task> done を使います。State drift が疑われる場合は /hapo:sync audit <feature> を使います。CafeKit は machine state と human state が一緒に進むことを期待します:

Task が done になるとき、spec.json.task_registry と該当 task markdown は一致している必要があります。Task には readable verification receipt が必要です: 実行した commands、outcomes、artifact proof、runtime proof、または recorded blocker。

Verified task の後は docs checkpoint を考慮します。Source behavior が変わり、docs や onboarding が嘘になるなら release 前に更新します。

Main workflow が分岐する場合#

Core flow は planned feature delivery 用です。作業タイプが違う場合は別 route を使います:

OpenCode equivalent#

OpenCode は prefix-free commands を使いますが、同じ CafeKit skill bundle を読みます:

/specs -> /develop -> /test -> /code-review

Contract は同じです: source-backed spec、1 task at a time、real evidence、adversarial review、synchronized state。

Definition of Done#

CafeKit task は以下がすべて true のときだけ done です:

• Approved task packet が hidden scope change なしに実装された。
• Runtime-facing work が real entrypoint に wired された。
• Completion criteria が満たされた。
• Verification evidence に exact commands と outcomes が記録された。
• Code review に blocking correctness, security, regression issue がない。
• spec.json と task markdown が一致している。
• Docs impact が処理済み、または明示的に記録されている。