cloud-agent-lifecycle

# Cloud Agent Lifecycle スキル ## 概要 このスキルは、GitHub Cloud Agent で `gh` CLI または GitHub API が readonly として動作し、Issue / PR の作成・編集・コメント投稿ができない場合の代替運用を定義する。 ### 主要なポイント | 項目 | 内容 | |------|------| | 適用条件 | Issue / PR への書き込みができない Cloud Agent 実行環境 | | 状態の正本 | `.github/lifecycle/<work-id>/state.yaml` | | 仕様の正本 | `.github/lifecycle/<work-id>/spec.md` | | Agent 間ログ | `.github/lifecycle/<work-id>/log.md` | | E2E テスト | Tester が Playwright MCP server で実行し、結果を `e2e-report.md` に保存する | | GitHub 投稿 | Agent は行わず、必要な本文案を outbox に生成する | --- ## 適用条件 以下のいずれかを満たす場合、このスキルを使用する: - GitHub Cloud Agent 上で `gh issue create/edit/comment` または `gh pr create/edit/comment` が失敗する - `gh auth status` や環境説明から GitHub CLI が readonly と判断できる - ユーザーが「Cloud Agent」「github cli readonly」「Issue に書き込めない」等を明示した ローカル VS Code 環境で GitHub 書き込みが可能な場合は、既存の `feature-lifecycle` と `github-flow` を通常どおり使用してよい。 --- ## Agent と transport の責務分離 Agent 定義は Product Manager / Developer / Reviewer などの役割と出力形式だけを持つ。GitHub に投稿するか、ローカルファイルへ保存するかは、このスキルの transport ルールで決める。 | 責務 | 所有者 | |------|--------| | 仕様・設計・実装・レビュー・テスト判断 | 各 Agent | | 状態台帳の保存先 | `cloud-agent-lifecycle` | | Agent 出力の保存先 | `cloud-agent-lifecycle` | | GitHub 投稿予定本文の生成 | `cloud-agent-lifecycle` | | 実際の GitHub 投稿・PR 作成・マージ | 人間または write 権限を持つ仕組み | Orchestrator は、各 Agent の出力に含まれる構造化メタデータを読み取り、`state.yaml`、`log.md`、outbox を更新する。Agent 自身に GitHub Cloud Agent 固有の分岐を書かない。 --- ## 基本方針 GitHub の Issue / PR を状態ストアとして使わず、リポジトリ内のファイルを正本として扱う。 | 従来の保存先 | Cloud Agent での保存先 | |-------------|------------------------| | SPEC Issue body | `.github/lifecycle/<work-id>/spec.md` | | Issue / PR コメント | `.github/lifecycle/<work-id>/log.md` | | Issue / PR body の lifecycle-state | `.github/lifecycle/<work-id>/state.yaml` | | 実装計画コメント | `.github/lifecycle/<work-id>/implementation-plan.md` | | PR 本文 | `.github/lifecycle/<work-id>/pull-request.md` | | E2E テスト結果 | `.github/lifecycle/<work-id>/e2e-report.md` | | GitHub 投稿待ち本文 | `.github/lifecycle/<work-id>/outbox/*.md` | `<work-id>` は、Issue 番号がある場合は `issue-<number>`、Issue 番号がない場合は `request-<yyyyMMddHHmm>-<slug>` とする。 --- ## Cloud Agent フロー ### エントリモード | モード | 起動条件 | Step 1.1 の挙動 | |--------|---------|----------------| | `cloud-new` | ユーザーが自然文で要件を指示 | Product Manager の出力を基に `spec.md` と Issue 作成用 outbox を生成 | | `cloud-draft` | ユーザーがドラフト Issue 番号を指定（例: `draft_issue: 123`） | 既存 Issue を readonly で参照できる場合は読み取り、`spec.md` と Issue 更新用 outbox を生成 | | `cloud-pr` | 既存 PR ブランチ上で起動 | `state.yaml` と差分から Phase 3 を復元 | ### 共通出力ルール 各 Agent の出力は、`feature-lifecycle/references/communication-protocol.md` と同じヘッダーと遷移メタデータを使用する。Cloud Agent では、その出力を GitHub コメントとして投稿せず、`log.md` に追記する。 ### Phase 1: 仕様策定 1. Orchestrator は work-id を決定する。 2. Product Manager は仕様書本文を出力する。 3. Orchestrator は Product Manager の出力から `spec.md`、`state.yaml`、`log.md`、必要な outbox を作成または更新する。 4. Reviewer は `spec.md` をレビューし、Orchestrator は結果を `log.md` に追記する。 5. 仕様承認が必要な場合、Orchestrator は `state.yaml` の `status` を `WAITING_HUMAN` にする。 ### Phase 2: 設計・計画 1. Architect は設計方針を出力し、Orchestrator は `design.md` に保存する。 2. Developer は実装計画を出力し、Orchestrator は `implementation-plan.md` に保存する。 3. Documentation は必要な docs 骨子を更新する。 4. Reviewer は設計・計画・docs 骨子をレビューし、結果を `log.md` に追記する。 ### Phase 3: 実装 1. Developer は Cloud Agent が作業中のブランチ上で実装する。`gh pr create` は実行しない。 2. Developer は PR 本文案を出力し、Orchestrator は `pull-request.md` に保存する。 3. Reviewer がコードと docs 更新をレビューする。 4. Reviewer が APPROVE した後、Orchestrator は Tester に E2E テストを委譲する。 5. Tester は Playwright MCP server 由来のブラウザ操作ツールを使用して E2E テストを実行し、結果を `e2e-report.md` と `log.md` に記録する。 6. 実装、テスト、docs 更新、レビュー、E2E 結果を `log.md` と `state.yaml` に記録する。 7. Ready for Review、マージ、Issue コメント投稿は人間または別の write 権限を持つ仕組みが行う。 ### Cloud Agent E2E テスト Cloud Agent で `cloud-agent-lifecycle` を使用する場合、E2E テストは Tester の責務とする。Tester は `e2e-test` スキルと Tester agent の手順に従い、Playwright MCP server 由来のツールを最優先で使用する。 | 状況 | 扱い | |------|------| | Playwright MCP server が利用可能 | Tester が MCP ツールで E2E テストを実行する | | MCP ツールで必要な操作を実行できない | Tester が理由を `e2e-report.md` に記録し、`ENV_FAILED` または `FAIL` を返す | | MCP server が未提供 | 原則として `ENV_FAILED` とし、Orchestrator が `state.yaml` と `log.md` に記録する | Cloud Agent では `playwright-cli` を通常の実行経路にしない。CLI フォールバックは、ユーザーが明示的に許可した場合、または実行環境に Playwright MCP server が提供されていないことを承知でフォールバックを求めた場合のみ使用する。 Tester の E2E 完了出力には、少なくとも以下を含める: - 使用したツール（Playwright MCP server / フォールバック時のみ `playwright-cli`） - 実行したシナリオ一覧 - PASS / FAIL / ENV_FAILED / FLAKY_TEST の判定 - スクリーンショットや追加成果物のパス - フォールバックまたは未実行がある場合の理由 --- ## GitHub 書き込みの扱い Cloud Agent モードでは、以下の操作を実行しない: - `gh issue create` - `gh issue edit` - `gh issue comment` - `gh pr create` - `gh pr edit` - `gh pr comment` - `gh pr merge` 必要な投稿内容は `.github/lifecycle/<work-id>/outbox/` に Markdown として生成する。ファイル名は `NN-agent-step-target.md` の形式とする。 ```text .github/lifecycle/issue-42/outbox/ 01-product-manager-step-1.1-issue-body.md 02-reviewer-step-1.2-issue-comment.md 03-developer-step-2.2-plan-comment.md 04-pr-body.md 05-tester-step-3.7-e2e-result.md ``` --- ## 状態復元 セッション開始時やコンテキスト喪失後は、次の順で状態を復元する: 1. `.github/lifecycle/**/state.yaml` を探す。 2. 対象 work-id が複数ある場合は、ユーザー指定の Issue / PR / ブランチに最も近いものを選ぶ。 3. `state.yaml` の `phase`、`step`、`status`、`last_decision` を読み、次のアクションを決める。 4. `log.md` の末尾を確認し、直近の Agent 出力と遷移メタデータを照合する。 --- ## 参照リファレンス - `references/file-transport.md` — ファイルベースの通信・outbox ルール - `references/state-ledger.yaml.md` — Cloud Agent 用状態台帳スキーマ - `../feature-lifecycle/references/communication-protocol.md` — Agent 出力フォーマット - `../feature-lifecycle/references/state-transitions.md` — 状態遷移