workflow

ワークフロー

⚠️ このスキルを最初に呼び出してください。参照資料はこのスキルを通じて読み込み、単独では読み込まないでください。

4つのフェーズと締めくくりで構成されます：ブレインストーミング → 計画 → 実行 → レビュー → 締めくくり。各フェーズは、成果物の契約を持つ業務上の役割である席であり、その時点で適任のモデルが担当します。独立性を保つため、ライターとレビュアーには意図的に異なるベンダーのモデルを割り当てます。ROUTING.md で、各席に割り当てるベンダー、モデル、作業量を定義します。

呼び出し： workflow <command> [slug]。カードのコマンド行に、CLI 独自のスキルプレフィックスがある場合はそれを含めます。

チェックアウト： 実行内容を読む前に、references/worktrees.md に従ってください。各フェーズとステータスを実行対象のチェックアウトに対応付けます。実行フェーズでは隔離環境を開き、締めくくりで変更を反映します。

実行内容 — .workflow/<slug>/

1つの実行内容は1つのフォルダーにまとめられ、Git で追跡され、永続的に保持されます。そのファイルがステートマシンを構成します。

成果物	作成者	内容
brainstorm.md	ブレインストーミング	概要：問題、振る舞い（B#）、決定事項、テストの接点、対象外の事項 — 実行内容の公式ステータス
plan.md	計画、続いて実行	調査結果とチケット（T#）。各チケットには受け入れ条件と検証コマンドを記載し、実行状況も管理します
patch_plan.md	レビュー	現在のパッチサイクルにおける修正チケット
review.md	レビュー	対応範囲、現在のサイクルでの指摘事項と判定、過去のサイクルをまとめた ## Resolved テーブル
learnings.md、wrap.md	任意／締めくくり	タグ付きの教訓。締めくくりのチェックポイントと、その後に記す実行内容の要約（約40行以内）

構成。 最上位には上記の成果物のみを置きます。それ以外は種類ごとのサブフォルダーに格納し、初めて必要になった時点で作成します：receipts/（検証出力、差分、引き継ぎ資料：t3-verification.md） · screens/（UI の変更前／変更後：t3-topic-page-before.jpg） · notes/（調査、監査、ランブック、下書き） · scripts/（単発コード。他のコードと同様にレビューします） · data/（小規模で固定された *.json／*.csv。大量データはリポジトリの外に置きます） · prototypes/（使い捨てのスケッチ） · understand/（understand スキルのみが書き込みます）。

すべての成果物のヘッダーに Status: を記載します。ステータスは drafting（そのフェーズを再開） · complete · parked · done です。brainstorm.md のステータスが parked または done の実行内容は、進行中ではありません。

進行中の実行内容の状態	次の作業
brainstorm.md のみ	計画
plan.md に awaiting-human のチケットがあり、他に着手可能なチケットがない	そのチケットで指定された人間の作業を行い、その後に実行
plan.md に done ではないチケットがある	実行
すべてのチケットが完了しており、review.md がない、または Base 以降にコードが変更されている	レビュー
patch_plan.md に done ではないチケットがある	実行（パッチ計画を実施）
未解決の指摘事項がなく、Base 以降にコードが変更されていない review.md がある	締めくくり

スラッグ： コマンドで指定するか、進行中の実行内容が1つだけの場合はそれを使います。それ以外の場合は、進行中の実行内容をアルファベット順に一覧表示し、選択を求めます。解決済みの各チェックアウトでの進行中の実行内容：grep -l 'Status: *\(drafting\|complete\)' .workflow/*/brainstorm.md。workflow status は、完了していない実行内容ごとに1行を出力します — slug · フェーズ · ブロッカーまたはなし · 次のコマンド（awaiting-human のチケットは、その実行内容をブロッカーとして扱い、対応する作業も表示します）。実行内容の状態に合わないコマンドが指定された場合は、その旨を示して確認を求めます。

根拠 — 段階的な読み込み

• 常に読むもの： 実行中の成果物（brainstorm.md、plan.md、patch_plan.md、review.mdの現在の サイクルと、その## Resolvedテーブル）；ROUTING.md（カードの行）；AGENTS.md； MEMORY.mdのインデックス — 「Applies when」が一致する場合に限り、memory/<slug>.mdのページを開く； git log --oneline -15；git status。
• 対象を絞って読む — PRODUCT.md、DESIGN.md： プロダクトまたはUIが対象の場合：見出しを確認し、作業に関係するセクションのみを読み、 Docs read: PRODUCT.md §Vocabulary · DESIGN.md §Tablesのように記録します。 これらは方針のずれを防ぐガードです。新たなプロダクト方針、realign、デザインからの逸脱提案、および内容がこれらに反する可能性のあるチケットでは、全体を読みます。
• 対象を絞って読む — TODO.md、ROADMAP.md： brainstorm、wrap、todoの場合のみ。
• デフォルトでは読まないもの： *_ARCHIVE.md、最新のエントリより後のWORKLOG.md、ほかの実行のフォルダー、.workflow/archive/：grepで検索し、一致した行のみ読みます。doneの実行では、そのwrap.mdだけを読みます。

人間への伝え方（すべてのフェーズ）

成果物が記録で、チャットは受領書です（人間はスマートフォンで読みます）。人間が読む内容にはすべてplainスキルのルールを適用します。記述を始める前に、各フェーズで一度実行してください。ID、コマンド、パス、固定の行形式はそのままにします。最後のカードの前は最大約12行です。

• 結果 — フェーズで行ったことを、平易な文で最大3行。

• 必要な決定 — 番号を付け、1つにつき決定事項は1つにします。質問はすべて次の形式にし、選択肢ごとに1行使います。文章をつなげて1段落にしてはいけません。

  **1. <title>** <the question, ≤2 plain sentences>
  - ➡️ **a) <option>** — recommended: <why it wins, in the reader's terms>
  - b) <option> — <what it costs or risks, why it is the weaker pick>
  - c) <option> — <same>
  

  ➡️の行を最初に置き、太字にします。先を読まなくても推奨案がわかるようにしてください。すべての選択肢に理由を添えます。推奨案には選ぶ理由を、それ以外の案には選ばない理由を示します。「どちらでもよい」は理由になりません。2つの案が本当に同等なら、その旨と、判断を分ける条件を示します。各行は1〜2行に収め、質問の間には空行を1つ入れます。「2b以外はすべてデフォルト」という返答で済むようにしてください。

• 否定的な結果は1行で示します（「PRODUCT.md — 変更なし」）。

確認ゲート（brainstormを除くすべてのフェーズ）：最初の編集前に、誤読によるコストが大きい場合 — スコープが曖昧、コマンドと状態が一致しない、スキーマ／契約／削除に関する作業、明示されていない前提がある場合 — 質問を一度に最大3つまで行い、回答を待ちます。

分量の上限 — 思考に上限はありませんが、ファイルにはあります。brainstorm.mdは約80行以内、behaviourは8件まで；plan.mdは約120行以内、チケットは8件まで、受け入れ条件は20行まで；review.mdは約100行以内；完了時のwrap.mdは約40行以内です。上限を超える場合は、2回に分けて実行する案を提示し、確認してください。拒否された場合はSplit declined by human: <when>と記録します。 文章を削り、受け入れ条件やチェック項目は削らないでください。

担当枠

ブレインストーミングの相手役（グリル。todo、wrap も担当） · デフォルトの実行担当（ロジック関連のチケット、P1～P3 の修正） · 大規模作業の実行担当（スキーマ／SQL／契約関連のチケット、P0 の修正、最も難しい複数ファイルの作業） · 機械的作業レーン（期待されるテキスト結果が明示されたチケット） · オペレーター（ライブまたは不可逆な書き込み、認可、ホスト型コンソール。人間が実行するか、承認後にエージェントが実行） · 厳格なレビュアー（懐疑的な立場で、計画、レビュー、パッチ計画、realign を担当。realign を除き読み取り専用）。

不変条件：

• ベンダーをまたぐレビュー。 厳格なレビュアーはコードの作成者とは異なるベンダーを使います。同じベンダーによるレビューは品質が低下するため、その旨を review.md に記載します。1つのステップは1つのセッション内でのみ実行します。
• 可用性を最優先。 セッション開始時にモデルピッカーを開き、ROUTING.md のフォールバックチェーンを順番にたどり、切り替えた場合はその旨を明記します。
• 実行中のモデルは記憶ではなく記録から特定します（references/phase-3-execute.md）。
• 人間が作業するのは、人間が何かを加えられる場合のみです（対応表は ROUTING.md）。コードはテストとベンダー横断レビューで確認し、差分の読み込みでは確認しません。ユーザーに見える変更は、コミット前に人間が実際に試します。チケットの重大度ではなく、レーンによって担当枠が決まります。
• サブエージェントは読み取り専用で作業範囲を広げるために使い、その調査結果を検証します。書き込みはメインセッションで実行します。

各フェーズは毎回新しく開始し、実行フォルダーと git から改めて状況を確認します。モデルの切り替えはハンドオフ時に行い、その方法はコンパクションではなく リセット です。CLI の reset、context meter、model picker の正確なコマンドは README.md に記載されています。

クロージングカード — workflow next

各フェーズは、ターンの最後の出力としてこのカードで終了します。チャットの回答を待つターン（UI の確認、確認の質問、計画に含まれるチケット一覧の確認）は、カードを付けずに Decisions リストで終了します。人間がモデルを選ぶためにファイルを開かなくて済むよう、モデルの行には ROUTING.md の行に記載された内容を入力します（Trial のエントリーがある場合は、プライマリの代わりに (trial) と明記して使います）。

---

▶ 次へ： ·

• 理由： <一行、またはパッチサイクルの場合はサイクルと調査結果の ID>
• リセット： はい | いいえ
• モデル： · ·
• フォールバック： ·
• 読み込み対象： 次のフェーズで最初に開くファイル

実行：

workflow <phase> <slug>

---

各項目は、行を詰めず、1行につき1項目の箇条書きにします。Markdown では通常の行が連結されるため、箇条書き記号のない行は段落に埋もれてしまいます。実行： ラベルの前とコードフェンスの前には空行を入れ、カードが短い場合でも、コマンドは必ず専用の text コードブロックに記載します。コピー用ボタンが表示されるようにするためです。

読み込み対象： には実行ファイルとレシートのみを記載します。CLI は AGENTS.md とその関連ファイルをすでに読み込みます。カードを出す前に、references/worktrees.md に従って、解決済みのチェックアウトからコミットしてプッシュします。予期しない check-run.py のワークツリーまたはブランチに関する警告があれば、まず解決するか、確認を求めてください。ハンドオフ時の リセット は常に はい、同じ担当枠で作業を続ける場合のみ いいえ です。人間のみが行うステップ（オペレーターのチケット、エスカレーション）では、- **モデル：** human · <the one action> とし、読み込み対象： にはハンドオフ先を記載します。実行が完了したら、wrap の ✅ カードを使います（references/wrap.md）。

基本ルール

• コードとデータで検証します。 各フェーズが依存するすべてのインターフェース、シグネチャ、カラムを実際のコードで確認します。ブリーフの主張は、確認するまでは仮説です。実データに依存する成果については、動作を確認する前に読み取り専用クエリを実行します。
• 出所ヘッダー — すべての実行成果物は次の5行で始まります。Command:、Created:（ブリーフまたは計画には · <model> を追加）、Base:（git sha）、Inputs:（<artifact> @ <its Base> または none）、Status:。フェーズ開始時には、入力の Status: complete が最新である必要があります。git diff --stat <Base>..HEAD -- <files it names> の結果が、この実行自体のチケットコミットのみであることを確認します。古くなっている場合は、その旨を記し、再実行が必要なフェーズへ回します。
• レシートとコード。 レシートは *.md、*.txt、および実行ごとの screens/、prototypes/、understand/ 全体です。それ以外のファイルはすべてコードです。「X以降にコードが変更された」とは、git diff --stat X..HEAD -- . ':(exclude)*.md' ':(exclude)*.txt' ':(exclude,glob).workflow/*/screens/**' ':(exclude,glob).workflow/*/prototypes/**' ':(exclude,glob).workflow/*/understand/**' の結果が空でないことを意味します。これをレシートルールの差分と呼びます。.workflow/ の外にあるコードが、その中のファイルを読み込むことはありません。
• 人間による編集。 実行コミットで変更されていない未コミットのパス（git diff --name-only <plan Base>..HEAD に含まれないパス）は、アプリが保存時に書き換える設定ファイルなど、人間自身の作業です。コミットせず、フェーズ報告で一度だけ明記します。ゲートを止めることも、作業ツリーをクリーンでない状態にすることもありません。
• シンプルさ。 合格に必要な最小限の差分を目指します。追加する行はすべて、レビュー時に読む対象、次回の実行で維持する対象を増やします。新しいヘルパーを書く前にリポジトリ内で既存のものを検索し、検索結果をチケット報告に記載します。新しい抽象化には、実際に使用する呼び出し元が2つ必要です。
• 検証済みのチケットごとにコミットします。 Wrap は実行をアーカイブします（Status: done）。フォルダーは残します。
• プッシュ前に毎回シークレットをスキャンします。 gitleaks git --log-opts="@{u}..HEAD" --redact -v --no-banner（upstream がない場合：origin/<primary>..HEAD）。--redact によって値がトランスクリプトに残りません。通常、レシートがシークレットの出所です。トークンを含むライブクエリやログなどが該当します。終了コードが0ならプッシュします。検出結果があればプッシュせず、ファイル名、行番号、ルールを明記し、次を確認します。➡️ a 未プッシュのコミットから削除してローテーションする（実際の値がすでにセッションに含まれています） · b 誤検知：フィンガープリントを .gitleaksignore に追加します。再発するパターン（IDフィールドや公開トークンなど）は、代わりに .gitleaks.toml の許可リストに追加し、デフォルトルールを拡張します。再スキャンでそのパターンが検出されず、テスト用に仕込んだキーが検出されることを確認します。スキャナーがない場合はプッシュせず、次を確認します。➡️ a インストールする · b スキャンなしでプッシュし、その旨をカードに記録する。
• 実行成果物をコミットするのは、チェックに合格した場合のみです。 次のようにつなげて実行します。python3 <skill>/scripts/check-run.py <slug> && git commit ...。| tail などのパイプを使うと check-run の終了コードが隠れてしまいます。実在しないファイルやshaを参照したレビューが一度公開されたことがあります。成果物は、報告対象の読み取り処理が完了した後にのみ作成します。

コマンド一覧

コマンドのリファレンスを1つ読んでください。status と next にはこのファイルと ROUTING.md だけが必要です。

コマンド	references/ 内のリファレンス
brainstorm <slug>、improve <feature> - goal: <goal>、park [slug]	phase-0-brainstorm.md
plan	phase-2-plan.md
execute	phase-3-execute.md（+ tests.md）
review（+ パッチサイクル）	phase-4-review.md
wrap	wrap.md
learn、log	learning-worklog.md
todo [idea]	todo.md
bootstrap [PRD.md]	bootstrap.md
realign	realign.md

このスキルのメンテナンスについては MAINTAINING.md を参照してください。