paseo-epic

Paseo Epic

重量級のセレモニー型オーケストレーターです。調査 → 計画 → 実装 → 納品を、再開可能な1つのフローとして実行します。~/.paseo/plans/<slug>.md にある計画ファイルが信頼できる情報源であり、コンテキスト圧縮後も保持されます。

通常、この処理は数時間、場合によっては一晩中続きます。エージェントが作業を始める頃には、ユーザーと意図を再検討することはできません。会話の中でユーザーがすでに伝えた要件（動作、「そうする理由」、UX のルール、制約）を記録し、計画エージェントが起動する前に、不変のものとして計画に書き込んでください。以降のすべての作業（プランナー、敵対的レビュー担当者、実装担当者）は、それらの要件を前提に最適化します。要件を再検討することはありません。

ユーザーの依頼： $ARGUMENTS

前提条件

これは Paseo スキルです。最初に paseo スキルを読み込んでください。作業環境（worktree、エージェント、待機、ハートビート、設定）が含まれています。起動するすべてのエージェントもこのスキルを読み込みます。

プロバイダーを選ぶ前に、~/.paseo/orchestration-preferences.json を読んでください。読み終えるまでは、プランナー、レビュー担当者、リサーチ担当者、実装担当者、監査担当者のエージェントを作成しないでください。

独自のサブエージェントは使用しないでください。 このスキルのエージェントはすべて、Paseo MCP を通じて起動する Paseo エージェントです。ハーネスに備わっているネイティブなサブエージェントの仕組みは使用しません。

役割とフェーズの種類に関する用語は、このスキルに同梱されている役割リファレンス（references/roles.md）に記載されています。

モード

• デフォルト：対話型です。要件を詳しく確認し、フェーズ間にゲートを設け、納品前に確認します。
• --autopilot：詳しい確認もゲートもなく、納品まで進めます。一晩中作業するときに使用します。
• --worktree：新しい worktree で作業を分離します。

厳守事項

• 計画ファイルが信頼できる情報源です。 各フェーズの前に必ず読み直してください。
• 計画ファイルに書き込めるのは自分だけです。 エージェントは計画ファイルを編集しません。
• 要件は不変です。 ユーザーが示した動作、UX、「その仕組みになっている理由」、受け入れ条件は、プランナーを起動する前に計画の Requirements ブロックに記載し、その後変更しないでください。技術計画（フェーズ、順序、アプローチ）は要件に合わせて調整します。プランナーとレビュー担当者が検討するのは HOW であり、WHAT や WHY ではありません。
• すべての要件を満たすまで、エピックは完了ではありません。 計画の最後には、Requirements ブロックのすべての項目を納品されたコードと照合する、簡易チェックを設けてください。未達の項目があれば、納品前にオーケストレーターが作業に戻って修正します。--autopilot でも同様です。
• 各エージェントのプロバイダーはオーケストレーション設定から選びます。 役割のカテゴリーに合わせてください。
• worktree の作成には Paseo だけを使用してください。 自分で git worktree add を実行してはいけません。
• エージェントはコミットしません。 納品フェーズでコミットします。
• 解決策ではなく問題を説明してください。 エージェントには何が壊れているか、何が必要かを伝え、解決方法はエージェントに任せてください。プロンプトに具体的な行番号やコードスニペットを含めないでください。
• フェーズごとにエージェントは1つです。 1つのフェーズに2つ必要なら、プランナーがフェーズの分割を誤っています。
• エージェントに何度も状況確認をしないでください。 適切な方法で完了を待ってください。

フロー

Preferences → [Worktree] → Research → Capture intent → [Grill] → Plan → Adversarial review → [Confirm] → Implement → Deliver
onboard if                            always           ^^^^^^^                               ^^^^^^^^^
missing                                                default mode                          default mode

---

0. 設定（開始前）

~/.paseo/orchestration-preferences.json を読み込んでください。/epic では、以下のプロバイダーカテゴリーに作業を振り分けます。

• planning — 技術計画の作成とレビュー
• research — 計画前のコード調査
• impl — コードの作成（リファクタリング、実装）
• ui — スタイリングやレイアウトの実装
• audit — 最終的な簡易要件チェックを含む、読み取り専用の検証

ファイルが存在しない場合、またはいずれかのカテゴリーが未設定の場合は、ユーザーを案内して一度だけ設定してください。list_providers と list_models を使って候補を提示し、各カテゴリーを1行で説明してから、AskUserQuestion を使ってカテゴリーごとのプロバイダーを収集してください。選択内容は ~/.paseo/orchestration-preferences.json に直接保存します。

/epic が使用するすべてのカテゴリーが設定されるまで、このステップの先へ進まないでください。これは --autopilot にも適用されます。既知のプロバイダーがなければ、オートパイロットを開始できません。

ファイルがすべて設定済みなら、何も言わずに続行してください。

---

1. 自分で調査する

まずコードを読みます。関連箇所を grep し、重要なファイルを2～4個読んで、現在の構成を把握します。

3つ以上のパッケージにまたがる変更、またはアーキテクチャの変更では、リサーチャーエージェントを1～2つ起動します。それぞれ担当領域を1つに絞ります。research 設定で指定されたプロバイダーを使います。各リサーチャーには、担当範囲に関する指示を得るためにロールリファレンスを読み、割り当てられた領域を調査して、ファイル、型、パターン、注意点を報告するよう伝えます。解決策は求めません。編集もさせません。

自分が理解した内容を、2～3文でユーザーに伝えます。

2. ワークツリー（--worktree の場合）

Paseo 経由でワークツリーを作成します。返されたパスとブランチを記録し、プランのフロントマターに記載します。

3. 意図を記録する（必ず実施）

プランニングエージェントを起動する前に、ユーザーがすでに伝えた内容を具体的な要件リストにまとめます。この手順は --autopilot の場合も実施します。これは、要件の掘り下げで拡張される土台であり、その代わりではありません。

このスキルが呼び出されるに至った会話から、説明された動作、UX のルール、「なぜこのように動作するのか」、制約、変更してはならないこと、ユーザーが明示的に承認または却下した内容、そして受け入れ基準（作業の完了を判断できる具体的でテスト可能な条件）を抽出します。それぞれを短い命令形の箇条書きで記述します。網羅的に拾います。ユーザーが動作、制約、成功条件として言及したものは、すべて含めます。

手順6でファイルを作成する際、これらの箇条書きをプランの ## Requirements (immutable) ブロックにそのまま記載します。これらは以降のすべてのエージェントが固定事項として読み、最終チェックで照合する基準になります。

ユーザーがプロダクトやUXの要件のみを伝え、技術的な方針を示していない場合も問題ありません。プロダクト要件と受け入れ基準を不変の要件として記録します。技術的なプランは、プランナーが設計し、レビュアーが検証する対象です。

4. 要件を掘り下げる（--autopilot でない場合）

AskUserQuestion を使います。一度に質問は1つにし、おすすめの選択肢を示して、分岐を深さ優先で解決します。コードを調べれば答えられる質問はしません。3～4問ごとに、確定した決定事項をまとめます。

ここでユーザーが決めた内容は要件に加え、不変のブロックに追加します。

分岐が解決するか、ユーザーが「go」と言うまで続けます。

5. 反証的レビューを含めてプランを作成する

プランナーを起動する

プランナーは継続して使い、最初の回答後にアーカイブせず、反復してプランを詰めます。planning 設定で指定されたプロバイダーを使います。

次の内容を指示します。

• 用語を確認するためにロールリファレンスを読む。
• Objective と Requirements (immutable) ブロックを固定の入力として扱う。技術的なプランはそれらに合わせて最適化し、再設計してはなりません。要件に問題があると思われる場合は、黙って回避せず、チャットで指摘します。
• リファクタリングを優先して考える。既存コードが変更に対応できない場合は、機能を追加する前に構造を整える計画を立てます。「接続する」「糊付けする」「統合する」といったフェーズがある場合、先行するリファクタリングを見落としていることが多いです。
• フェーズごとに1行で簡潔に、チャットで回答する。ファイルには書き込みません。

プランに異議を唱える

追加の質問を送ります。エッジケース、別の順序、最小限の出荷可能な範囲、リファクタリングにすべき後付けのフェーズについて掘り下げます。検討対象はHOW、つまりフェーズ、順序、技術的なアプローチに限ります。Requirements ブロックは議論の対象にしません。プランが十分に明確になるまで反復します。

プランレビュアーを起動する

planning 設定で指定されたプロバイダーを使います。次の内容を指示します。

• ロールリファレンスを読む。
• プランナーのドラフトと Requirements ブロックを読む。
• 技術的なプランに異議を唱える。後付けの対応、見落とされたエッジケース、過剰な設計、誤った順序、隠れた依存関係を指摘し、別案を掘り下げます。トレードオフを明らかにします。
• Requirements ブロックを固定事項として扱います。要件に問題があると思われる場合は、指揮役に警告として伝えます。要件を暗黙に削除または弱める代替プランを提案してはなりません。

トレードオフの選択肢をユーザーに提示する

プランナーの出力をそのまま提示してはいけません。選択肢を示します。

プランナーは A → B → C を提案しています（動作する範囲を最速で完成させ、リファクタリングは後回しにします）。 レビュアーは B → A → C を提案しています（リファクタリングを先に行うため時間はかかりますが、よりすっきりします）。 どちらにしますか？

AskUserQuestion を使用します。ユーザーが別の案を選んだ場合は、プランナーを再実行します。

計画が確定したら、プランナーとプランレビュアーをアーカイブします。

6. 計画を書く

~/.paseo/plans/<slug>.md に保存します。

---
task: <slug>
status: not-started
worktree: <abs path or null>
branch: <branch or null>
pr: null
created: <ISO>
updated: <ISO>
---

# <Title>

## Objective

<one paragraph>

## Requirements (immutable)

What the user has stated. Behaviors, UX rules, the "why," constraints,
and acceptance criteria (testable conditions for "done").
Captured in step 3 (and extended by the grill in step 4).
This block does not change during planning, review, or implementation.
The final check before deliver audits every bullet here.

- <bullet>
- <bullet>

## Notes

- <ISO> orchestrator: <freeform>

## Phases

- [ ] **Phase 1** · <type> · <short name>
      Acceptance: <one line>

- [ ] **Phase N** · verify · requirements + acceptance audit
- [ ] **Phase N+1** · gate · user smoke test
- [ ] **Phase N+2** · deliver · <commit | PR + merge | cherry-pick>

フェーズの種類：refactor、implement、verify、gate、deliver。検証のバリエーションはインラインで記述します：verify · qa、verify · spec、verify · review。役割リファレンスを参照してください。

ステータスマーカー：[ ] 未着手、[~] 進行中、[x] 完了、[!] ブロック中。

7. 確認する（デフォルトモード）

フェーズの一覧を表示します（ファイルの内容は表示しません。ユーザーが読みます）。2～3文で説明し、待ちます。

--autopilot の場合はスキップします。

---

8. 実装する

次の未完了フェーズを見つける → [~] にする → 種類に応じてディスパッチする → 完了を待つ → 検証する → [x] にする → 繰り返します。

次のいずれかに該当したら停止します：gate フェーズに到達した、すべてのフェーズが [x] になった、またはフェーズが [!] でブロックされ、解決できない。

フェーズの種類に応じたディスパッチ

refactor

リファクタリング担当を起動します。プロバイダーは impl（スタイルのみの再構成の場合は ui）から選びます。cwd = 設定されている場合はワークツリーのパス。次のように指示します。

• 役割リファレンスを読み、そこで指定されているスキルを読み込む。
• Requirements（不変）ブロックを含めて計画ファイルを読む。対象範囲はフェーズ N。受け入れ条件はそこに固定されている。
• 機能追加ではなく、構造を変更する。変更前後で動作は同一にする。既存のテストをすべて成功させる。パリティテストがなければ追加する。
• 完了時：型チェックに合格し、関連テストがすべて成功していること。コミットしない。計画を更新しない。

implement

実装エージェントを起動します。プロバイダーは impl（スタイルのみの場合は ui）から選びます。cwd = 設定されている場合はワークツリーのパス。次のように指示します。

• 役割リファレンスを読み、そこで指定されているスキルを読み込む。
• Requirements（不変）ブロックを含めて計画ファイルを読む。対象範囲はフェーズ N。要件は提案ではなく制約であり、それに従って実装する。
• 計画に関連するリポジトリのドキュメントを、パスを指定して読む。
• TDD：まず失敗するテストを書き、それから成功させる。
• 既存の構造では変更に対応できない場合、無理に継ぎ足さずに異議を申し立てる。先にリファクタリングフェーズを設けるべきだった。
• 完了時：型チェックに合格し、変更したすべてのテストが成功していること。コミットしない。計画を更新しない。

verify

verify · の後にあるバリエーションに対応する監査担当を起動します。プロバイダーは audit から選びます。監査担当が読み込む内容と出力内容は、役割リファレンスのバリエーション表に記載されています。読み取り専用で、編集はしません。

gate

エージェントは起動しません。ユーザーに引き継ぎます。

1. このフェーズを [x] にする。
2. 引き継ぎ内容をまとめる：ワークツリーのパス（設定されている場合）、テストする内容（次のフェーズの受け入れ条件、またはこのフェーズの Notes）、再開方法（条件が満たされたら /epic <slug> を実行するか、先に計画を編集する）。
3. 正常に終了する。次のフェーズを開始しない。ポーリングしない。

deliver

インラインで処理します。セクション 9 を参照してください。

エージェントの出力を検証する

refactor と implement の場合：

1. エージェントの最後のアクティビティを読む。
2. 受け入れ条件を確認する：型チェックとテストが成功していること、変更内容がフェーズの範囲に合致していること。
3. 問題がある → 同じエージェントにフォローアップを送る。修正のために新しいエージェントを起動しない。
4. 問題がない → アーカイブする。

verify の場合：

• 問題なし → 監査対象のフェーズを [x] にし、次に進む。
• 問題あり → 指摘事項を Notes に追記する。フェーズを完了にしない。指摘事項を新たな受け入れ条件として実装エージェントに送るか、判断が曖昧な場合はユーザーに提示する。

ユーザーが途中で割り込んだ場合

• 実行中のエージェントへのフィードバック → エージェントに転送する。
• 計画の変更 → 計画ファイルを編集する（追加／削除／並べ替え）。変更内容を伝えて続行する。
• 「停止」／「終了」 → 実行中のエージェントをアーカイブし、状況を要約して待つ。
• 新しい質問 → 簡潔に回答して続行する。

ユーザーがあなたを終了させて再度呼び出した場合でも、新しいオーケストレーターが作業を引き継げるよう、計画ファイルに重要な情報をすべて記録してください。重要な情報はすぐに Notes に書き込みます。

---

9. 納品する

フロントマターを読んでモードを選びます。

worktree: null   → Mode A: main commit
worktree: <path> → Mode B (PR) or Mode C (cherry-pick); ask if not specified

main に直接プッシュしてはいけません。明示的な許可なしに強制プッシュしてはいけません。CI が成功する前にマージしてはいけません。ワークツリーのアーカイブには Paseo を使用し、git worktree remove は使用しないでください。

モード A — メインへのコミット

1. git status — 関連する変更を確認します。
2. git diff — 内容を確認します。
3. コミットメッセージを作成します。タイトルは70文字未満の命令形、本文は理由を説明する1〜3文にします。リポジトリのスタイルに合わせます（git log --oneline -20）。
4. git add <specific files> — -Aや.は使わないでください。
5. git commit -m "..."（HEREDOC）。
6. 計画を更新します：status: delivered。Notes の行を追加します。
7. ユーザーにハッシュと概要を伝え、プッシュするか尋ねます。

モード B — worktree → PR ＋ マージ

1. worktree 内でクリーンにコミットします。 論理的な変更ごとに、整理されたコミットを1つ作成します。リポジトリのスタイルに合わせます。
2. main より遅れている場合はリベースします。 エージェントを起動します。プロバイダーは impl から取得します。origin/main へのリベース、変更の意図に沿ったコンフリクト解消（片方を一括採用しない）、型チェックとテストが引き続き成功することの確認、プッシュしないことを指示します。
3. ブランチをプッシュします — git -C <worktree> push -u origin <branch-from-frontmatter>。
4. PR を作成します — 計画の Objective ＋ Phases を概要に、acceptance の各行をテスト計画に使って gh pr create を実行します。URL を記録し、frontmatter の pr: に設定します。Status を pr-open にします。
5. PR の対応を続けます。 エージェントを起動し、PR をグリーンにします。プロバイダーは impl から取得します。/babysit-pr を読み込み、ポーリングの代わりに create_heartbeat によるウェイクアップを使い、作業の一環として PR のレビューを読み、誤りや古い内容でない限り Greptile の自動レビューコメントに対応し、すべてのチェックがグリーンになるまで修正・プッシュ・再監視するよう指示します。マージはしないでください。判断するのはあなたです。 CI がグリーンになり、対応が必要なレビューに対処できたら、Notes を追加し、frontmatter の status: ready-to-merge を設定します。
6. グリーンになったらマージします — ユーザーに確認します（AskUserQuestion: squash / rebase / merge / wait）。最近マージされた PR からリポジトリの規約を読み取ります（gh pr list --state merged -L 5 --json mergeCommit,title）。

   gh pr merge <n> --squash --delete-branch
   

7. Paseo 経由で worktree をアーカイブします。 frontmatter：status: delivered、worktree: null。Notes の行を追加します。

モード C — worktree → cherry-pick

1. worktree 内でクリーンにコミットします（論理的な変更ごとに、クリーンなコミットを1つ作成します）。
2. メインのチェックアウトから（cdは使わずに）：git cherry-pick <sha>。複数の場合：git cherry-pick <oldest>..<newest>。
3. コンフリクトが発生したら停止し、ユーザーに伝えます。自動で解消しないでください。
4. Paseo 経由で worktree をアーカイブします。frontmatter：status: delivered、worktree: null。プッシュするか尋ねます。

---

再開可能性

ユーザーはどのフェーズでも中断または強制終了できます。新たに実行したときは：

1. slug（または最終更新日時が最も新しいもの）で計画を探します。
2. frontmatter の status と、最初の未完了フェーズを読み取ります。
3. 該当するフェーズから再開します。

デリバリー途中からの再開：

• status: pr-open ＋ pr: <url> → CI の監視を再開します。
• status: ready-to-merge → ユーザーに再度マージするか尋ねます。
• status: delivered ＋ worktree: <path> → worktree がまだアーカイブされていないため、アーカイブします。

失敗パターン

• grilling を省略したために capture-intent を省略する。Requirements ブロックが最低限の要件であり、grilling はそれを拡張します。
• 対立的なレビューによって、ユーザーがすでに確定した要件を損なう。レビュアーは技術計画を改善しますが、意図を蒸し返すものではありません。
• フェーズを順にこなすチェックリストとして扱う。フェーズはゲートです。先へ進む前に確認してください。
• worktree モードでエージェントの cwd を worktree のパスに設定し忘れる。
• 計画をユーザーに説明し直す。ユーザーはあなたと一緒に計画を作成しています。フェーズ番号を参照してください。
• 適切に待機せず、エージェントをポーリングする。
• 自分でコードを編集する。あなたの役割はオーケストレーションです。実装はエージェントが行います。
• worktree が実際にアーカイブされる前に status: delivered に設定する。
• main に直接プッシュする。