Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity

feat: replace intake workflow state with planning

Browse Source
This commit is contained in:
Hare
2026-06-08 18:00:23 +09:00
parent cb234b86ad
commit ada6db99d8
11 changed files with 292 additions and 272 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.yoi/workflow/multi-agent-workflow.md
+5 -5
View File
@@ -8,9 +8,9 @@ requires: []
yoi を yoi で開発する際の、worktree + coder Pod + 外部 reviewer Pod + orchestrator Pod の標準フロー。これは **最上位 Pod が細かい code review を抱えず、下位 orchestrator が実装と外部レビューの loop を完了状態まで運ぶためのフロー** である。
worktree の機械的作成手順は `$user/worktree-workflow`、ユーザー依頼の Ticket 化は `$user/ticket-intake-workflow`、Ticket の next action 分類は `$user/ticket-orchestrator-routing`、実装前の要件同期・反証 preflight は `$user/ticket-preflight-workflow` に分ける。
worktree の機械的作成手順は `$user/worktree-workflow`、ユーザー依頼の Ticket 化は `$user/ticket-intake-workflow`、Ticket の next action 分類は `$user/ticket-orchestrator-routing`、実装前の要件同期・反証 planning sync は `$user/ticket-planning sync-workflow` に分ける。
この Workflow は、対象 ticket が implementation-ready であることを前提にする。implementation-ready は full implementation plan ではなく、recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions に基づいて coder が bounded investigation を進め、reviewer が判断できる状態を指す。設計境界・仕様・authority boundary が未同期の場合は、worktree 作成や coder Pod 起動の前に `ticket-preflight-workflow` を通す。
この Workflow は、対象 ticket が implementation-ready であることを前提にする。implementation-ready は full implementation plan ではなく、recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions に基づいて coder が bounded investigation を進め、reviewer が判断できる状態を指す。設計境界・仕様・authority boundary が未同期の場合は、worktree 作成や coder Pod 起動の前に `ticket-planning sync-workflow` を通す。
## 目的
@@ -61,9 +61,9 @@ reviewer Pod
- worktree 作成と git 書き込み操作について、人間の許可がある。
- main workspace の unrelated dirty changes を把握している。
- 下位 orchestrator に渡す binding decisions / invariants、implementation latitude、escalation conditions を短く書ける。
- 設計境界・仕様・authority boundary に不確定要素がある場合、`ticket-preflight-workflow` の結果が ticket thread に記録されている。
- 設計境界・仕様・authority boundary に不確定要素がある場合、`ticket-planning sync-workflow` の結果が ticket thread に記録されている。
product / API / UX / authority / design-boundary 方針が複数自然に導ける場合、protocol / scope / permission / history persistence に触れる場合、ticket 自体の再定義が必要な場合は、実装委譲前に `ticket-preflight-workflow` を通し、必要なら人間へ戻す。実装ファイルの探索、既存コード読解、局所的な構成選択のような bounded implementation uncertainty は、intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions が明確なら coder に委ねてよい。
product / API / UX / authority / design-boundary 方針が複数自然に導ける場合、protocol / scope / permission / history persistence に触れる場合、ticket 自体の再定義が必要な場合は、実装委譲前に `ticket-planning sync-workflow` を通し、必要なら人間へ戻す。実装ファイルの探索、既存コード読解、局所的な構成選択のような bounded implementation uncertainty は、intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions が明確なら coder に委ねてよい。
## Intent packet
@@ -106,7 +106,7 @@ reviewer には coder の実装方針ではなく、この intent packet と dif
- `git status --short --branch`
- 対象 ticket / ticket 群
- 関連 TODO / docs / 既存 worktree
- preflight が必要な ticket では、`ticket-preflight-workflow` の分類・要件同期・critical risks
- planning sync が必要な ticket では、`ticket-planning sync-workflow` の分類・要件同期・critical risks
2. worktree 作成
- `$user/worktree-workflow` に従い `./.worktree/<task-name>` を作る。
.yoi/workflow/ticket-intake-workflow.md
+9 -10
View File
@@ -17,7 +17,7 @@ User request / conversation
-> Ticket Intake Workflow
-> TicketCreate / TicketComment
-> Orchestrator routing
-> preflight / spike / implementation / review / blocked / close
-> planning sync / spike / implementation / review / blocked / close
```
- `Ticket` は durable orchestration record。
@@ -41,7 +41,7 @@ Intake は以下を行う。
- background / requirements / acceptance criteria / escalation conditions を整理する。
- binding decisions / invariants と implementation latitude を分けて書く。
- 具体的な除外や触れてはいけない境界が binding decision である場合は、generic な除外リストではなく invariant / escalation condition として明記する。
- readiness / needs_preflight / risk flags を明示する。
- readiness / open questions / risk flags を明示する。
- ユーザー合意後に Ticket を作成する。
- 既存 Ticket の refinement を求められた場合は、TicketComment で経緯を残す。
@@ -136,9 +136,9 @@ unspecified:
- どうしても分類不能な時だけ使う。理由を Ticket に書く。
```
### 5. needs_preflight / risk flags を付ける
### 5. open questions / risk flags を付ける
以下に触れる Ticket は `needs_preflight: true` 相当として扱い、Ticket body に明記する。
以下に触れる Ticket は risk flags と reviewer/orchestrator focus を Ticket body に短く明記する。これは stop gate ではない。具体的な未決定 decision / information がある場合だけ、blocking open question として記録する。
- profile / manifest / scope / permission。
- session / history / Pod metadata / persistence。
@@ -149,7 +149,7 @@ unspecified:
- 複数の自然な設計方針があるもの。
- reviewer が diff だけでは見落としやすい設計リスク。
risk flags は短い語でよい。`needs_preflight: true` と risk flags は強い signal だが、missing boundary がすでに人間/Orchestrator の Ticket-recorded decision で補われている場合は、その decision を根拠に Orchestrator が routing できる。preflight は、実装が product / API / UX / authority boundary / explicit design constraint を silently 決める場合には mandatory のままである。
risk flags は短い語でよい。missing boundary がすでに人間/Orchestrator の Ticket-recorded decision で補われている場合は、その decision を根拠に Orchestrator が routing できる。単に risk があるだけなら Orchestrator は Ticket を戻さず、IntentPacket に escalation / reviewer focus を明記して進める。
例:
@@ -170,7 +170,7 @@ Kind:
Priority:
Labels:
Readiness:
Needs preflight:
Needs planning sync:
Risk flags:
Background:
@@ -207,7 +207,7 @@ Related tickets/docs:
- `TicketCreate` を使う。
- title / slug / kind / priority / labels / body を指定する。
- body に readiness / needs_preflight / risk flags と、binding decisions / invariants、implementation latitude、escalation conditions を Markdown で明記する。
- body に readiness / open questions / risk flags と、binding decisions / invariants、implementation latitude、escalation conditions を Markdown で明記する。
既存 Ticket refinement の場合:
@@ -221,7 +221,7 @@ Related tickets/docs:
- 作成/更新した Ticket id / slug / title。
- readiness。
- needs_preflight / risk flags。
- open questions / risk flags。
- 次に Orchestrator が取るべき routing 候補。
- 未決定点があれば、そのまま明示する。
@@ -243,7 +243,6 @@ Intake はここで止まる。implementation / worktree / coder / reviewer 起
## Readiness
- readiness: implementation_ready | requirements_sync_needed | spike_needed | blocked | unspecified
- needs_preflight: true | false
- risk_flags: [...]
## Escalation conditions
@@ -277,6 +276,6 @@ Ticket の body は Markdown/freeform を維持する。すべてを strict sche
## 他 Workflow への接続
- `ticket-preflight-workflow`: needs_preflight が true、または implementation_ready か不安な場合に接続する。
- `ticket-planning sync-workflow`: legacy slug の互換入口。新規 routing は standalone planning sync ではなく planning return/requirements sync として扱う。
- `multi-agent-workflow`: Orchestrator が implementation_ready と判断した後に接続する。
- `ticket-orchestrator-routing`: この Workflow が作った Ticket を routing する後続 Workflow。
.yoi/workflow/ticket-orchestrator-routing.md
+33 -31
View File
@@ -1,5 +1,5 @@
---
description: Ticket を読み、Orchestrator が preflight / spike / implementation / review / blocked / close へ明示的に routing する workflow
description: Ticket を読み、Orchestrator が planning return / spike / implementation / review / blocked / close へ明示的に routing する workflow
model_invokation: true
user_invocable: true
requires: []
@@ -19,13 +19,13 @@ Panel Queue / queued notification は、人間が Orchestrator に routing を
```text
TicketCreate / TicketComment
-> Ticket Orchestrator Routing Workflow
-> requirements sync / preflight / spike / implementation / review / blocked / close / pending
-> planning return / requirements sync / spike / implementation / review / blocked / close / pending
-> 必要に応じて他 Workflow へ接続
```
- Intake は Ticket の materialization を担当する。
- Orchestrator は Ticket の next action を分類する。
- `ticket-preflight-workflow` は実装前の設計・要件 gate。
- Intake は Ticket の materialization と planning/clarification を担当する role であり、workflow_state 名ではない。
- workflow_state は `planning -> ready -> queued -> inprogress -> done` を基本遷移とする。
- `ticket-preflight-workflow` は legacy slug 互換の planning/requirements sync entry であり、`preflight` を独立 state / lane / long-lived operation として扱わない。
- `ready -> queued` は人間が Orchestrator routing を許可した状態であり、worktree 作成や Pod 起動の許可そのものではない。
- `multi-agent-workflow` は coder / reviewer Pod と worktree を使う実装・レビュー loop。
- この Workflow は自動 scheduler / lease / unattended maintainer ではない。
@@ -43,7 +43,7 @@ Orchestrator は以下を行う。
- routing decision を `TicketComment` で Ticket thread に記録する。
- implementation-ready の場合は `multi-agent-workflow` に渡す `IntentPacket` を作る。
- implementation-ready かつ Ticket が `queued` の場合は、worktree 作成 / implementation Pod `SpawnPod` / coder routing などの side effect の前に、既存の typed Ticket backend/tool path で `queued -> inprogress` を記録する。
- preflight-needed の場合は coder Pod に直投げせず、`ticket-preflight-workflow` に接続する。
- `ready` または `queued` に具体的な不足 decision / information がある場合だけ、typed state-change/routing event 付きで `planning` に戻す。
## Orchestrator がしないこと
@@ -55,6 +55,7 @@ Orchestrator は以下を行う。
- merge / close / cleanup 権限を持たない場面で勝手に完了処理しない。
- Ticket tools があるからといって arbitrary filesystem write を行わない。
- Notification だけを完了証拠にしない。Pod output / diff / validation / Ticket evidence を確認する。
- 具体的な不足項目を言語化できない場合に、単に risky という理由だけで `planning` に戻さない。その場合は IntentPacket に escalation / reviewer focus を明記して進める。
## 使用する Ticket tools
@@ -64,7 +65,7 @@ Orchestrator は以下を行う。
- `TicketShow`: 対象 Ticket の body / thread / artifacts / resolution 確認。
- `TicketComment`: routing decision / intent packet / blocked reason / next question の記録。
- `TicketStatus`: pending/open などの状態整理が明示的に許可された場合だけ使う。
- `TicketWorkflowState`: `queued -> inprogress` acceptance など、workflow_state 遷移が明示的に許可・必要な場合だけ使う。
- `TicketWorkflowState`: `queued -> inprogress` acceptance、`inprogress -> done`、または concrete missing decision/information reason を伴う `ready|queued -> planning` に使う。
- `TicketClose`: 完了権限と resolution が揃っている場合だけ使う。
- `TicketDoctor`: routing 前後の整合性確認。
@@ -75,7 +76,8 @@ Orchestrator は以下を行う。
`workflow_state = queued` は、Ticket が routing 対象として人間により Orchestrator へ渡された状態である。Orchestrator は queued notification を受けたら、Ticket と workspace state を読んで、次のどちらかを行う。
- unblocked と判断する場合: `queued -> inprogress` を記録してから worktree 作成、implementation/review Pod spawn、その他の implementation side effect に進む。
- blocked / not-ready と判断する場合: concise な理由を Ticket thread に記録し、queued のまま待つか、既存の Ticket status/state mechanism で明示的に defer/block する。
- concrete missing decision / information がある場合: `TicketWorkflowState` で `queued -> planning` を記録し、reason/body に不足項目を残す。既存の claimed live/restorable Intake/Planning Pod があり、既存通知経路が使える場合は同じ理由を通知する。
- external action 待ちなど planning では解決しない blocker の場合: concise な理由を Ticket thread に記録し、queued のまま待つか、既存の Ticket status/state mechanism で明示的に defer/block する。
Invariant:
@@ -86,11 +88,11 @@ Invariant:
## Routing classification
Orchestrator は対象 Ticket を以下のいずれかに分類する。
Orchestrator は対象 Ticket を以下のいずれかに分類する。複数に見える場合は、次に必要な action が最も早いものを選ぶ。
### `requirements_sync_needed`
仕様・用語・UX・責務境界・受け入れ条件が未同期。
まだ `planning` に留めるべき、または `planning -> ready` に進める前に clarification が必要な状態。
条件:
@@ -101,27 +103,27 @@ Orchestrator は対象 Ticket を以下のいずれかに分類する。
Action:
- Intake / human に戻す。
- Intake / human / Planning sync に戻す。
- `TicketComment` で不足情報と質問を記録する。
- coder Pod は起動しない。
### `preflight_needed`
### `return_to_planning`
実装前に設計境界・要件・反証観点を同期すべき状態。
`ready` または `queued` とされているが、実装 side effect 前に具体的な不足 decision / information が見つかった状態。
条件:
- profile / manifest / scope / permission / session / history / Pod metadata / prompt context に触れる。
- public API / plugin / feature boundary / storage migration / security / secrets に触れる。
- 複数の自然な product / API / UX / authority / design-boundary 方針があり、human / Orchestrator decision なしでは固定できない。
- implementation-ready に見えるが、reviewer が diff だけでは見落としやすい設計リスクがある。
- `needs_preflight: true` または同等の記述が Ticket にある。ただし、missing boundary がすでに Ticket/thread の explicit human/Orchestrator decision で補われている場合は、その decision を binding として扱い、残る不確実性が実装 tactic に閉じているかを確認して routing できる。
- product / API / UX / authority boundary / storage migration / security / secrets などについて、実装前に決めなければならない具体項目がある。
- 複数の自然な方針があり、human / Orchestrator decision なしでは固定できない。
- acceptance criteria、binding decisions、または escalation conditions に、実装可否を左右する具体的欠落がある。
Action:
- `ticket-preflight-workflow` に接続する。
- `TicketComment` で preflight reason を記録する。
- preflight が implementation-ready にするまで coder Pod は起動しない。
- `TicketWorkflowState` で `ready -> planning` または `queued -> planning` を記録する。
- reason/body に具体的な不足項目を含める。
- `TicketComment` で routing decision と質問を記録する。
- 既存の claimed live/restorable Intake/Planning Pod があり、既存通知経路が使える場合は同じ理由を通知する。実用的な経路がない場合は follow-up として report する。
- planning が再度 `ready` にするまで coder Pod は起動しない。
### `spike_needed`
@@ -151,7 +153,7 @@ Action:
- binding decisions / invariants と implementation latitude が区別されている。
- reviewer が判断する basis と escalation conditions が明確。
- validation が書ける。
- design / authority boundary の未決定がない、または preflight / human decision で補われている。
- design / authority boundary の未決定がない、または planning return / human decision で補われている。
- 残る不確実性が bounded implementation investigation / local tactic selection に閉じている。
- IntentPacket を短く書ける。
@@ -184,7 +186,7 @@ Action:
条件:
- design/product/security 判断が必要。
- design/product/security 判断が必要だが、planning で同期すれば進められる種類ではない。
- credential / secret / environment / external service が必要。
- 別 Ticket / branch / upstream change の完了待ち。
- scope/permission が不足している。
@@ -262,7 +264,7 @@ Action:
- Acceptance criteria
- Binding decisions / invariants
- Implementation latitude
- Readiness / needs_preflight / risk flags
- Readiness / open questions / risk flags
- Escalation conditions
- Validation
- Thread の plan / decision / implementation_report / review
@@ -270,11 +272,10 @@ Action:
### 3. Classification を決める
1つに決める。複数に見える場合は、次に必要な action が最も早いものを選ぶ。
例:
- implementation-ready に見えるが authority boundary の explicit decision がない → `preflight_needed`; explicit decision が Ticket/thread にあるなら binding として IntentPacket に載せる。
- implementation-ready に見えるが authority boundary の explicit decision がない → concrete missing decision として `return_to_planning`; explicit decision が Ticket/thread にあるなら binding として IntentPacket に載せる。
- implementation-ready に見えるが単に risk が高い → `implementation_ready` とし、IntentPacket に escalation / reviewer focus を明記する。
- 実装済みだが review がない → `review_needed`
- 要件が曖昧で spike も必要そう → `requirements_sync_needed` を優先し、調査問いを明確化する
- 完了しているが close 権限がない → `close_ready` として dossier を返す
@@ -335,12 +336,12 @@ Critical risks / reviewer focus:
- reviewer にも見てほしい失敗パターン。reviewer は recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / explicit escalation conditions に照らして判断し、不記録の preferred tactic を基準にしない。
```
IntentPacket が短く書けない場合、`implementation_ready` ではなく `preflight_needed` または `requirements_sync_needed` に戻す。
IntentPacket が短く書けない場合、`implementation_ready` ではなく `return_to_planning` または `requirements_sync_needed` に戻す。
### 6. 後続 Workflow へ接続する
- `requirements_sync_needed` → `ticket-intake-workflow` / human
- `preflight_needed` → `ticket-preflight-workflow`
- `requirements_sync_needed` → `ticket-intake-workflow` / human / planning sync
- `return_to_planning` → `ticket-preflight-workflow`（legacy compatibility slug の planning sync entry）
- `spike_needed` → read-only investigation plan / Pod（許可後）
- `implementation_ready` → `multi-agent-workflow`
- `review_needed` → reviewer Pod / review workflow
@@ -353,8 +354,9 @@ IntentPacket が短く書けない場合、`implementation_ready` ではなく `
この Workflow の完了条件は次のいずれかである。
- routing decision が Ticket に記録され、次に接続する Workflow / human action が明確である。
- `ready` / `queued` を `planning` に戻した場合、typed state-change/routing event に concrete missing decision / information reason が残っている。
- implementation-ready Ticket について IntentPacket が Ticket に記録され、`multi-agent-workflow` に渡せる。
- requirements-sync / preflight / spike / blocked / review / close-ready の理由と次 action が Ticket に記録されている。
- requirements-sync / planning return / spike / blocked / review / close-ready の理由と次 action が Ticket に記録されている。
- routing 不要と判断され、その理由が明確である。
## この Workflow で固定しないもの
.yoi/workflow/ticket-preflight-workflow.md
+46 -144
View File
@@ -1,172 +1,74 @@
---
description: ticket を実装委譲する前に、要件・前提・設計境界・反証観点を同期し、Ticket thread に記録する preflight フロー
description: 互換 slug を残した Ticket planning / requirements sync workflow。preflight を独立 lane や workflow_state として扱わない。
model_invokation: true
user_invocable: true
requires: []
---
# Ticket Preflight Workflow
yoi プロジェクトで ticket を実装に渡す前に、要件・前提・設計境界・反証観点を同期するための Workflow。これは **実装前の gate** であり、worktree 作成や coder / reviewer Pod の起動は `multi-agent-workflow` / `worktree-workflow` 側で扱う。
# Ticket Planning / Requirements Sync Workflow
目的は「ticket があるから実装する」状態を避け、ticket が **実装可能な intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions** を持つのか、**調査 ticket** なのか、**人間との仕様同期が必要な未決定 ticket** なのかを明確にすることである。実装 tactic をすべて事前固定する必要はないが、product / API / UX / authority boundary / explicit design constraint を coder が silently 決める余地は残さない。
このファイル名は既存の workflow discovery / durable references 互換のために残す。新しい概念としての `preflight` state / lane / long-lived operation は作らない。ここで扱う作業は、Ticket を `planning` に戻して不足している決定・情報・受け入れ条件を同期するための planning activity である。
## 適用する場面
## 目的
以下のいずれかに当てはまる ticket は、実装委譲前にこの Workflow を通す。
実装に入る前または Orchestrator routing 中に、具体的な未決定事項が見つかった Ticket を planning に戻し、Ticket thread に監査可能な形で同期内容を残す。
- profile / manifest / scope / permission / session / history / pod-store / prompt context など authority boundary に触れる。
- ticket の文面から複数の自然な product / API / UX / authority / design-boundary 方針が導け、人間/Orchestrator decision なしでは固定できない。
- 「どう実装するか」以前に「何を仕様とするか」が曖昧である。
- 既存 implementation plan があるが、抽象化・責務境界・ユーザー体験に疑問がある。
- 過去 decision / memory / docs / ticket thread と矛盾しそうである。
- coder Pod に渡す intent packet で、binding decisions / invariants、implementation latitude、escalation conditions を区別して短く書けない。
この workflow は次をしてはいけない。
小さなバグ修正や仕様が明確な局所変更では、この Workflow は省略してよい。ただし省略理由が曖昧な場合は preflight する。`needs_preflight: true` や risk flags は強い signal だが、missing boundary がすでに Ticket/thread の explicit human/Orchestrator decision で補われている場合は、その decision を binding として扱い、残る不確実性が実装 tactic に閉じているかを確認して実装へ進められる。
- `preflight` を workflow_state として扱う。
- `needs_preflight` を stop gate として新規に書く。
- 「リスクがある」だけで Ticket を戻す。
- Coder / Reviewer / worktree mechanics を再設計する。
## Ticket 記録方針
## 適用条件
作業管理の authority は `.yoi/tickets/` に保存される Ticket と git history である。preflight の結果は、口頭の会話だけで終わらせず、Ticket tool または `yoi ticket ...` で ticket の `thread.md` または `item.md` に残す。
次のいずれかを満たす場合に使う。
- 新規の前提・要件・受け入れ条件は、必要に応じて `item.md` を更新する。
- 調査結果・実装前 plan は `TicketComment` または `yoi ticket comment <ticket> --role plan --file <file>` で残す。
- 採用/却下した設計判断、実装停止判断、仕様同期の結論は `--role decision` で残す。
- 実装に入ってよい状態になったら、その根拠を intent packet として ticket thread に残す。
- 仕様が未決定なら、実装 ticket にせず requirements-sync / spike / design ticket として切り分ける。
- ticket の timestamp/frontmatter が更新される場合は、関連変更と一緒に commit する。
- ticket 作成・更新・レビュー・完了は git commit で記録する。push はしない。
- `planning` Ticket の要件・受け入れ条件・制約を明確化する。
- `ready` または `queued` Ticket について、Orchestrator が実装開始前に具体的な不足情報・未決定事項を特定した。
- 既存 Ticket に legacy `intake` / `needs_preflight` 表記があり、planning terminology へ整理する必要がある。
適用しない条件:
- Orchestrator が具体的な不足項目を言語化できない。
- 単に変更範囲が広い、リスクが高い、またはレビュー観点が多いだけである。
- すでに `queued -> inprogress` が記録され、実装 side effect が始まっている。
この場合は Ticket を戻さず、IntentPacket に escalation / reviewer focus を明記して進める。
## 手順
### 1. 状態確認
1. Ticket の current frontmatter と recent thread を読む。
2. 不足している decision / information / acceptance condition を箇条書きで特定する。
3. `ready` または `queued` から戻す場合は、typed state change で `to = planning` を記録する。reason/body には具体的な不足項目を含める。
4. 既存の claimed live/restorable Intake/Planning Pod があり、利用可能な通知経路がある場合は、その Pod に同じ不足理由を通知する。実用的な経路が無い場合は follow-up として report する。
5. Ticket body または thread に requirements sync 結果を残す。
6. Ticket が queue 可能になったら `planning -> ready` を typed state change / `TicketIntakeReady` で記録する。
- `git status --short --branch`
- 対象 ticket の `item.md` / `thread.md` / artifacts
- 関連 ticket / docs / workflow / Knowledge / memory decision
- 既存 worktree / branch / running Pod の有無
## 記録テンプレート
この段階で unrelated dirty changes がある場合は、preflight の記録だけを行うか、人間に確認してから進める。
```markdown
## Planning sync
### 2. ticket の種類を分類する
Missing decisions / information:
- ...
以下のどれかに分類する。
Decisions made:
- ...
```text
implementation-ready:
- intent / binding decisions / invariants / implementation latitude / acceptance criteria / reviewer judgment basis が明確。
- binding decisions / invariants と implementation latitude が区別されている。
- bounded implementation investigation や local tactic 選択は残っていてよい。
- product / API / UX / authority boundary / explicit design constraint を coder が silently 決める余地がない。
- validation と escalation conditions が明確。
Acceptance criteria changes:
- ...
requirements-sync-needed:
- ticket の目的は見えているが、仕様・用語・責務境界・ユーザー体験の同期が必要。
Risk / reviewer focus:
- ...
spike-needed:
- 技術的実現性・依存関係・ライセンス・性能・diagnostics などを先に調べる必要がある。
blocked-needs-human-decision:
- 複数方針があり、AI が勝手に決めると設計境界や product API を固定してしまう。
Readiness:
- Keep in planning because ...
- or mark ready because ...
```
`implementation-ready` 以外は、coder Pod に実装を委譲しない。`implementation-ready` は full implementation plan ではなく、Orchestrator / coder / reviewer が同じ recorded intent と制約に基づいて判断できる状態である。
### 3. 要件同期
最低限、以下を確認する。
- 完了時に observable に何が変わるか。
- ticket の主語は何か: user-facing behavior / internal architecture / cleanup / investigation。
- 用語が既存設計と一致しているか。
- binding decision として残す具体的な除外・authority boundary は何か。
- 後方互換が必要か、不要な互換層を作ろうとしていないか。
- 既存の authority boundary を変えるか。
- runtime state / persisted state / config / profile / manifest / session log / pod metadata のどれが authority か。
必要なら ticket `item.md` の Background / Requirements / Acceptance criteria を更新する。
### 4. 現行コードと過去判断の map を作る
実装前に、少なくとも関連する current code paths を列挙する。
```text
Current code map:
- file/function: 現在の責務
- file/function: 変更候補
- file/function: 触ってはいけない境界
```
この map は簡潔でよい。目的は coder Pod が blind に探しながら設計を固定するのを防ぐこと。
### 5. 批判的 preflight
実装戦術の候補を一度疑う。以下の問いに答える。目的は tactic の固定ではなく、実装が product/API/authority/design-boundary decision を隠れて固定しないことを確認することである。
- この ticket は本当に実装 ticket か、それとも仕様同期 ticket か。
- 最も自然に見える実装が失敗するとしたらどこか。
- 抽象化に失敗して「別名の同じもの」を作っていないか。
- runtime-bound な値を reusable config に混ぜていないか。
- profile / manifest / scope / session / pod-store などの authority を逆転させていないか。
- user-facing API を安易に public contract 化していないか。
- external dependency / license / portability / packaging の問題はないか。
- reviewer が diff だけ読んでも見落とす設計リスクは何か。
この問いへの答えを `plan` または `decision` として ticket thread に残す。
### 6. intent packet を作る
実装に入ってよい場合だけ、`multi-agent-workflow` に渡す intent packet を作る。
```text
Intent:
- 何を実現するか。
Binding decisions / invariants:
- 人間/Orchestrator/Ticket に記録済みで coder / reviewer が従うべき decision と、壊してはいけない authority boundary / design boundary。
- 具体的な除外・触れてはいけない場所が binding decision である場合はここに書く。
Requirements / acceptance criteria:
- observable な完了条件と reviewer が判断できる基準。
Implementation latitude:
- Coder が調査しながら選んでよい local tactic / file-local organization / bounded uncertainty。
Escalate if:
- 親/人間に戻す判断条件。特に product / API / UX / authority boundary / explicit design constraint を変える必要が出た場合。
Validation:
- focused test / broader check / doctor / docs 更新。
Current code map:
- 実装対象と触ってはいけない場所。
Critical risks / reviewer focus:
- reviewer にも見てほしい失敗パターン。reviewer は recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / explicit escalation conditions に照らして判断し、不記録の preferred tactic を基準にしない。
```
この intent packet が短く書けない場合は、実装委譲せず requirements-sync-needed とする。
## review への引き継ぎ
preflight で出た critical risks は reviewer Pod にも渡す。reviewer は diff だけでなく、ticket の recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / explicit escalation conditions と preflight の反証観点を読む。reviewer は不記録の preferred tactic ではなく、記録済みの intent / binding decisions / invariants / implementation latitude / acceptance criteria に対して実装が十分かを判断する。
reviewer に期待すること:
- 実装が preflight の intent に対応しているか。
- 抽象化失敗や authority boundary 違反がないか。
- preflight で挙げた失敗パターンに落ちていないか。
- validation がリスクに対して十分か。
## 完了条件
この Workflow 自体の完了条件は、次のいずれかである。
- ticket が `implementation-ready` になり、intent packet が thread に記録されている。
- ticket が `requirements-sync-needed` / `spike-needed` / `blocked-needs-human-decision` として整理され、次に人間へ戻す問いまたは follow-up ticket が明確になっている。
- ticket 自体が不要/誤りと判断され、理由が decision として記録されている。
## この Workflow でしないこと
- worktree を作成しない。
- coder Pod に実装を委譲しない。
- merge / close しない。
- 仕様未決定のまま「小さく実装してみる」ことで public API を固定しない。
- Ticket に具体的な不足項目または解決済み decision が記録されている。
- `planning` に戻した場合、state_changed event に from/to/reason/body が残っている。
- `ready` に進める場合、未解決の blocking attention/action が残っていない。