mcpField
T
team-lifecycle

team-lifecycle

github.com/catlog22開発2.1k40 回インストール19 週間前に更新
リポジトリ

team-lifecycle について

Team Lifecycle Orchestratorは、要件整理から仕様作成、実装、テストまでを扱うチーム向けマルチエージェントワークフロースキルです。共有探索キャッシュ、並列タスク、議論の深刻度に応じた振り分けでパイプラインを調整します。

主な機能

  1. 015段階のライフサイクル編成
  2. 02コード探索キャッシュの共有
  3. 03迅速な引き継ぎと並列タスク
  4. 04議論の深刻度に応じた振り分け
  5. 05セッション復旧とタスク再試行

活用シーン

  1. 01要件整理から実装・テストまで進行
  2. 02実装後のテストとレビューを並行実行
  3. 03中断したセッションを再開してタスクを再配置

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/catlog22/claude-code-workflow --skill team-lifecycle

インストール後、Claude Code で/team-lifecycleを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

agents/
analyst.md
architect.md
discuss-agent.md
executor.md
explore-agent.md
fe-developer.md
fe-qa.md
planner.md
reviewer.md
tester.md
writer.md
phases/
01-requirement-clarification.md
02-team-initialization.md
03-task-chain-creation.md
04-pipeline-coordination.md
05-completion-report.md
specs/
document-standards.md
quality-gates.md
templates/
architecture-doc.md
epics-template.md
product-brief.md
requirements-prd.md

詳細

チームライフサイクルオーケストレーター

仕様策定、実装、テストのワークフローにおける、チームのライフサイクル全体をオーケストレーションします。オーケストレーターは、要件の明確化、セッションの初期化、タスクチェーンの作成、パイプラインの調整（起動／待機／終了のループ）、完了報告という5つのフェーズを通じて、マルチエージェントパイプラインを推進します。

主な設計原則：

  • インラインの discuss サブエージェント：成果物を作成するロール（analyst、writer、reviewer）は、専用のディスカッションエージェントを起動する代わりに、内部で discuss サブエージェントを呼び出します。これにより、仕様パイプラインのビート数が12から6に半減します。
  • 共有 explore キャッシュ：すべてのエージェントは、cache-index.json を含む一元化された explorations/ ディレクトリを共有し、コードベースの探索の重複をなくします。
  • 高速な次エージェント起動：エージェントの完了後、オーケストレーターは調整サイクル全体を待たずに、直線的なチェーンの次のエージェントをすぐに起動します。
  • 合意形成の重大度に応じたルーティング：ディスカッションの判定結果を HIGH／MEDIUM／LOW の重大度別に振り分け、それぞれ異なるオーケストレーターの動作（修正、警告して続行、またはそのまま通過）につなげます。
  • ビートモデル：各パイプラインステップは1つのビートです。エージェントを起動し、結果を待ち、出力を処理して、次のエージェントを起動します。オーケストレーターは1サイクルにつき1つのビートを処理した後、制御を返します。

アーキテクチャ

+-------------------------------------------------------------+
|  Team Lifecycle Orchestrator                                  |
|  Phase 1 -> Phase 2 -> Phase 3 -> Phase 4 -> Phase 5         |
|  Require    Init       Dispatch   Coordinate   Report         |
+----------+------------------------------------------------+--+
           |
     +-----+------+----------+-----------+-----------+
     v            v          v           v           v
+---------+ +---------+ +---------+ +---------+ +---------+
| Phase 1 | | Phase 2 | | Phase 3 | | Phase 4 | | Phase 5 |
| Require | | Init    | | Dispatch| | Coord   | | Report  |
+---------+ +---------+ +---------+ +---------+ +---------+
     |            |          |          |||          |
  params       session     tasks     agents      summary
                                    /  |  \
                              spawn  wait  close
                              /        |        \
                       +------+   +-------+   +--------+
                       |agent1|   |agent2 |   |agent N |
                       +------+   +-------+   +--------+
                          |           |            |
                     (may call discuss/explore subagents internally)

フェーズ4のビートサイクル（1ビート）：

  event (phase advance / user resume)
      |
      v
  [Orchestrator]
      +-- read state file
      +-- find ready tasks (pending + all blockers completed)
      +-- spawn agent(s) for ready task(s)
      +-- wait(agent_ids, timeout)
      +-- process results (consensus routing, artifacts)
      +-- update state file
      +-- close completed agents
      +-- fast-advance: immediately spawn next if linear successor
      +-- yield (wait for next event or user command)

エージェントレジストリ

エージェントロールファイル担当内容パターン
analyst~/.codex/agents/analyst.md初期分析、コンテキストの収集、DISCUSS-0012.8 インラインサブエージェント
writer~/.codex/agents/writer.mdドキュメント生成、DISCUSS-002～DISCUSS-0052.8 インラインサブエージェント
planner~/.codex/agents/planner.md多角的な探索、計画の作成2.9 キャッシュされた探索
executor~/.codex/agents/executor.mdコードの実装2.1 標準
tester~/.codex/agents/tester.mdテストと修正のサイクル2.3 深い対話
reviewer~/.codex/agents/reviewer.mdコードレビューと仕様品質、DISCUSS-0062.8 インラインサブエージェント
architect~/.codex/agents/architect.mdアーキテクチャに関するコンサルティング（必要に応じて）2.1 標準
fe-developer~/.codex/agents/fe-developer.mdフロントエンドの実装2.1 標準
fe-qa~/.codex/agents/fe-qa.mdフロントエンドのQA、GCループ2.3 深い対話

使用する前に、すべてのエージェントロールファイルを ~/.codex/agents/ に配置する必要があります。 パターン2.8 = エージェントが多角的な批評のために、内部で discuss サブエージェントを起動します。 パターン2.9 = エージェントが作業前に共有の explore キャッシュを使用します。 パターン2.3 = オーケストレーターが反復的な修正ループに send_input を使用する場合があります。

サブエージェントレジストリ

サブエージェントエージェントファイル呼び出し元目的
discuss~/.codex/agents/discuss-agent.mdanalyst、writer、reviewerCLIツールを使用した多角的な批評
explore~/.codex/agents/explore-agent.mdanalyst、planner、任意のエージェント共有キャッシュを使用したコードベースの探索

サブエージェントを起動するのはオーケストレーターではなく、エージェント自身です。エージェントはサブエージェントの仕様を読み込み、spawn_agent を使用してインラインで起動し、結果を待ってから終了させます。オーケストレーターがサブエージェントのライフサイクルを直接管理することはありません。

高速な次タスクの起動

wait() が完了したエージェントの結果を返した後、オーケストレーターは、次のパイプラインステップが単純な直線的後続タスクかどうか（準備完了になるタスクがちょうど1つ、並列ウィンドウなし、チェックポイントなし）を確認します。

判定表：

条件アクション
準備完了タスクが1つ、単純な直線的後続タスク、チェックポイントなし次のタスクに対して直ちに spawn_agent を実行します（高速起動）
準備完了タスクが複数（並列ウィンドウ）準備完了タスクをまとめてすべて起動し、その後すべてに対して wait を実行します
準備完了タスクなし、ほかのエージェントは実行中制御を譲り、これらのエージェントが完了するまで待機します
準備完了タスクなし、実行中のタスクもなしパイプライン完了。Phase 5 に進みます
チェックポイントタスクが完了（例：QUALITY-001）一時停止し、チェックポイントメッセージを出力して、ユーザーを待ちます

高速起動の失敗からの復旧： 高速起動したエージェントが失敗したことをオーケストレーターが検出した場合（wait がエラーを返す、または結果なしでタイムアウトする場合）：

  1. 状態ファイルに失敗を記録します
  2. 状態内でそのタスクを再び「pending」としてマークします
  3. 同じタスクに対して新しいエージェントを起動します
  4. 同じタスクが3回以上失敗した場合、パイプラインを一時停止してユーザーに報告します

合意形成の重大度に応じた振り分け

生成エージェント（アナリスト、ライター、レビュアー）が discuss の結果を報告すると、オーケストレーターはエージェントの出力から判定結果を解析します。

エージェントの出力形式（成果物に書き込まれ、wait() の結果にも含まれます）：

DISCUSS_RESULT:
- verdict: <consensus_reached | consensus_blocked>
- severity: <HIGH | MEDIUM | LOW>
- average_rating: <N>/5
- divergences: <summary>
- action_items: <list>
- recommendation: <revise | proceed-with-caution | escalate>
- discussion_path: <path-to-discussion-record>

振り分け表：

判定結果重大度オーケストレーターのアクション
consensus_reached-通常どおり進め、次のタスクを高速起動します
consensus_blockedLOW注記付きで合意済みとして扱い、通常どおり進めます
consensus_blockedMEDIUMwisdom/issues.md に警告を記録し、次のタスクのコンテキストに相違点を含めて進めます
consensus_blockedHIGH修正タスクを作成します（下記参照）。またはユーザーの判断を仰ぎます
consensus_blockedHIGH (DISCUSS-006)ユーザーの判断のため、必ず一時停止します（最終承認ゲート）

修正タスクの作成（重大度が HIGH で DISCUSS-006 ではない場合）：

// Add revision entry to state file
const revisionTask = {
  id: "<original-task-id>-R1",
  owner: "<same-agent-role>",
  blocked_by: [],
  description: "Revision of <original-task-id>: address consensus-blocked divergences.\n"
    + "Session: <session-dir>\n"
    + "Original artifact: <artifact-path>\n"
    + "Divergences: <divergence-details>\n"
    + "Action items: <action-items-from-discuss>\n"
    + "InlineDiscuss: <same-round-id>",
  status: "pending",
  is_revision: true
}

// Max 1 revision per task. If already revised once, pause for user.
if (stateHasRevision(originalTaskId)) {
  // Pause pipeline, ask user
} else {
  // Insert revision task into state, spawn agent
}

Phase の実行

Phaseファイル概要
Phase 1phases/01-requirement-clarification.mdユーザー入力を解析し、モードを検出して、フロントエンドを自動検出し、パラメーターを収集します
Phase 2phases/02-team-initialization.mdセッションディレクトリを作成し、状態ファイル、wisdom、探索キャッシュを初期化します
Phase 3phases/03-task-chain-creation.mdモードに基づいてパイプラインのタスクチェーンを構築し、状態ファイルに書き込みます
Phase 4phases/04-pipeline-coordination.md主な spawn/wait/close ループ、高速起動、合意形成の振り分け、チェックポイントを処理します
Phase 5phases/05-completion-report.md結果を要約し、成果物を一覧表示して、次のステップを提案します
Phase 0：セッション再開の確認（Phase 1 の前）

Phase 1 に入る前に、オーケストレーターは中断されたセッションがないか確認します。

  1. .workflow/.team/TLS-*/team-session.json をスキャンし、status: "active" または status: "paused" のファイルを探します
  2. セッションが見つからない場合 -> Phase 1 に進みます
  3. セッションが1つ見つかった場合 -> 再開します（下記のセッション照合を参照）
  4. セッションが複数見つかった場合 -> ユーザーに選択を求めます

セッション照合（再開時）：

  1. 状態ファイルを読み込み、パイプラインの状態を取得します
  2. 状態ファイル内の各タスクについて：
    • ステータスが "in_progress" で、実行中のエージェントが存在しない場合 -> "pending" にリセットします（中断）
    • ステータスが "completed" の場合 -> 成果物が存在することを確認します
  3. 照合済みの状態からタスクの準備状況を再構築します
  4. 照合済みの状態で Phase 4 に進みます（準備完了のタスクを起動）

パイプラインの定義

仕様のみ（6ビート）
RESEARCH-001(+D1) -> DRAFT-001(+D2) -> DRAFT-002(+D3) -> DRAFT-003(+D4) -> DRAFT-004(+D5) -> QUALITY-001(+D6)

各タスクにはインラインの discuss が含まれます。(+DN) = エージェントが内部で実行するインラインの discuss ラウンド N。

実装のみ（並列ウィンドウあり、3ビート）
PLAN-001 -> IMPL-001 -> TEST-001 || REVIEW-001

IMPL-001 の完了後、TEST-001 と REVIEW-001 は並列で実行されます。

全ライフサイクル（9ビート）
[Spec pipeline: RESEARCH-001 -> DRAFT-001 -> ... -> QUALITY-001]
    |
    CHECKPOINT: pause for user confirmation
    |
PLAN-001(blockedBy: QUALITY-001) -> IMPL-001 -> TEST-001 || REVIEW-001
FE 専用（3 ビート）
PLAN-001 -> DEV-FE-001 -> QA-FE-001

GC ループ：QA-FE の判定が NEEDS_FIX の場合、DEV-FE-002 → QA-FE-002 を動的に作成します（最大 2 ラウンド）。

フルスタック（並列処理を含む 4 ビート）
PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001

REVIEW-001 は、TEST-001 と QA-FE-001 の両方が完了するまでブロックされます。

フルライフサイクル FE（12 タスク）
[Spec pipeline] -> PLAN-001 -> IMPL-001 || DEV-FE-001 -> TEST-001 || QA-FE-001 -> REVIEW-001

PLAN-001 は QUALITY-001 によってブロックされます。仕様から実装へのチェックポイントが適用されます。

タスクメタデータレジストリ

タスク IDエージェントフェーズ依存関係説明インラインディスカッション
RESEARCH-001analystspec（なし）初期分析とコンテキストの収集DISCUSS-001
DRAFT-001writerspecRESEARCH-001プロダクトブリーフを生成DISCUSS-002
DRAFT-002writerspecDRAFT-001要件／PRD を生成DISCUSS-003
DRAFT-003writerspecDRAFT-002アーキテクチャドキュメントを生成DISCUSS-004
DRAFT-004writerspecDRAFT-003エピックとストーリーを生成DISCUSS-005
QUALITY-001reviewerspecDRAFT-0045 つの観点による仕様の品質評価と承認DISCUSS-006
PLAN-001plannerimpl（なし、または QUALITY-001）複数の観点からの調査と計画-
IMPL-001executorimplPLAN-001コードの実装-
TEST-001testerimplIMPL-001テストと修正のサイクル-
REVIEW-001reviewerimplIMPL-0014 つの観点によるコードレビュー-
DEV-FE-001fe-developerimplPLAN-001フロントエンドの実装-
QA-FE-001fe-qaimplDEV-FE-0015 つの観点によるフロントエンド QA-

ケイデンス制御

ビートモデル

イベント駆動型のパイプラインです。各ビートでは、オーケストレーターが 1 つのイベントを処理し、エージェントを起動し、完了を待って、結果を処理してから制御を返します。

Beat Cycle (single beat)
======================================================================
  Event                 Orchestrator                  Agents
----------------------------------------------------------------------
  advance/resume --> +- read state file ------+
                     |  find ready tasks       |
                     |  spawn agent(s) --------+--> [Agent A] executes
                     |  wait(ids, timeout) ----+--> [Agent B] executes
                     +- process results -------+         |
                     |  update state file      |         |
                     |  close agents           |         |
                     +- yield -----------------+         |
                                                         |
  next beat <--- result from wait() <-------------------+
======================================================================

  Fast-Advance (skips full yield for linear successors)
======================================================================
  [Agent A] completes via wait()
    +- 1 ready task? simple linear successor?
    |   YES -> spawn Agent B immediately, enter wait() again
    |   NO  -> yield, wait for user/event
======================================================================
パイプラインのビート表示
Spec-only (6 beats, was 12 in v3)
-------------------------------------------------------
Beat  1         2         3         4         5         6
      |         |         |         |         |         |
    R1+D1 --> W1+D2 --> W2+D3 --> W3+D4 --> W4+D5 --> Q1+D6
    ^                                                     ^
  pipeline                                            sign-off
   start                                               pause

R=RESEARCH  W=DRAFT(writer)  Q=QUALITY  D=DISCUSS(inline)

Impl-only (3 beats, with parallel window)
-------------------------------------------------------
Beat  1         2              3
      |         |         +----+----+
      PLAN --> IMPL --> TEST || REVIEW    <-- parallel window
                         +----+----+
                           pipeline
                            done

Full-lifecycle (9 beats)
-------------------------------------------------------
Beat 1-6: [Spec pipeline as above]
                                    |
Beat 6 (Q1+D6 done):      CHECKPOINT -- user confirms then resume
                                    |
Beat 7      8           9
 PLAN --> IMPL --> TEST || REVIEW

Fullstack (with dual parallel windows)
-------------------------------------------------------
Beat  1              2                    3                4
      |         +----+----+         +----+----+           |
      PLAN --> IMPL || DEV-FE --> TEST || QA-FE -->  REVIEW
              ^                ^                   ^
         parallel 1       parallel 2          sync barrier
チェックポイント
トリガータイミング動作
仕様から実装への移行QUALITY-001 の完了時一時停止し、「SPEC PHASE COMPLETE」を出力して、ユーザーの応答を待ちます
GC ループの上限到達QA-FE が最大 2 ラウンドに到達反復を停止し、現在の QA 状態を報告します
パイプラインの停滞実行可能なタスクも実行中のタスクもないタスクの不足を確認し、ユーザーに報告します
DISCUSS-006 の重大度が HIGH最終承認常に一時停止し、ユーザーの判断を待ちます
停滞の検出
確認項目条件解決方法
エージェントが応答しないアクティブなエージェントの wait() がタイムアウトエージェントを終了し、タスクを pending に戻して再起動します
パイプラインのデッドロック実行可能なタスクも実行中のタスクもなく、pending のタスクがあるblocked_by の依存関係を調べ、ブロック状況をユーザーに報告します
GC ループの超過DEV-FE／QA-FE の反復が 2 ラウンドを超過ループを終了し、最新の QA レポートを出力します
高速進行による孤立状態ではタスクが「in_progress」だが、エージェントは終了済みpending に戻して再起動します

エージェント起動テンプレート

オーケストレーターがパイプラインタスクのエージェントを起動するときは、次のテンプレートを使用します。

const agentId = spawn_agent({
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. **Read role definition**: ~/.codex/agents/<agent-role>.md (MUST read first)
2. Read session state: <session-dir>/team-session.json
3. Read wisdom files: <session-dir>/wisdom/*.md (if exists)

---

## Session
Session directory: <session-dir>
Task ID: <task-id>
Pipeline mode: <mode>

## Scope
<scope-description>

## Task
<task-description>

## InlineDiscuss
<discuss-round-id or "none">

## Dependencies
Completed predecessors: <list of completed task IDs and their artifact paths>

## Constraints
- Only process <PREFIX>-* tasks
- All output prefixed with [<agent-role>] tag
- Write artifacts to <session-dir>/<artifact-subdir>/
- Before each major output, read wisdom files for cross-task knowledge
- After task completion, write discoveries to <session-dir>/wisdom/
- If InlineDiscuss is set, call discuss subagent after primary artifact creation

## Completion Protocol
When work is complete, output EXACTLY:

TASK_COMPLETE:
- task_id: <task-id>
- status: <success | failed>
- artifact: <path-to-primary-artifact>
- discuss_verdict: <consensus_reached | consensus_blocked | none>
- discuss_severity: <HIGH | MEDIUM | LOW | none>
- summary: <one-line summary>
`
})

セッションディレクトリ

.workflow/.team/TLS-<slug>-<date>/
+-- team-session.json           # Pipeline state (replaces TaskCreate/TaskList)
+-- spec/                       # Spec artifacts
|   +-- spec-config.json
|   +-- discovery-context.json
|   +-- product-brief.md
|   +-- requirements/
|   +-- architecture/
|   +-- epics/
|   +-- readiness-report.md
|   +-- spec-summary.md
+-- discussions/                # Discussion records (written by discuss subagent)
+-- plan/                       # Plan artifacts
|   +-- plan.json
|   +-- tasks/                  # Detailed task specs
+-- explorations/               # Shared explore cache
|   +-- cache-index.json        # { angle -> file_path }
|   +-- explore-<angle>.json
+-- architecture/               # Architect assessments + design-tokens.json
+-- analysis/                   # Analyst design-intelligence.json (UI mode)
+-- qa/                         # QA audit reports
+-- wisdom/                     # Cross-task knowledge accumulation
|   +-- learnings.md            # Patterns and insights
|   +-- decisions.md            # Architecture and design decisions
|   +-- conventions.md          # Codebase conventions
|   +-- issues.md               # Known risks and issues
+-- .msg/                       # Message bus (UI integration)
|   +-- meta.json               # Pipeline metadata (stages, roles, team_name)
|   +-- messages.jsonl          # NDJSON event log
+-- shared-memory.json          # Cross-agent state

状態ファイルのスキーマ（team-session.json）

状態ファイルは、Claude の TaskCreate／TaskList／TaskGet／TaskUpdate システムに代わるものです。このファイルはオーケストレーターのみが管理します。

{
  "session_id": "TLS-<slug>-<date>",
  "mode": "<spec-only | impl-only | full-lifecycle | fe-only | fullstack | full-lifecycle-fe>",
  "scope": "<project description>",
  "status": "<active | paused | completed>",
  "started_at": "<ISO8601>",
  "updated_at": "<ISO8601>",
  "tasks_total": 0,
  "tasks_completed": 0,
  "pipeline": [
    {
      "id": "RESEARCH-001",
      "owner": "analyst",
      "status": "pending | in_progress | completed | failed",
      "blocked_by": [],
      "description": "...",
      "inline_discuss": "DISCUSS-001",
      "agent_id": null,
      "artifact_path": null,
      "discuss_verdict": null,
      "discuss_severity": null,
      "started_at": null,
      "completed_at": null,
      "revision_of": null,
      "revision_count": 0
    }
  ],
  "active_agents": [],
  "completed_tasks": [],
  "revision_chains": {},
  "wisdom_entries": [],
  "checkpoints_hit": [],
  "gc_loop_count": 0
}

メッセージバス（.msg/）

.msg/ ディレクトリは、フロントエンド UI 用のパイプラインメタデータを提供します。これは、Claude 版の team_msg ツールで type: "state_update" を指定した場合と同じ形式です。

meta.json

フロントエンド表示用に API が読み取るパイプラインメタデータです。

{
  "status": "active",
  "pipeline_mode": "<mode>",
  "pipeline_stages": ["role1", "role2", "..."],
  "roles": ["coordinator", "role1", "role2", "..."],
  "team_name": "lifecycle",
  "role_state": {
    "<role>": {
      "status": "completed",
      "task_id": "TASK-ID",
      "_updated_at": "<ISO8601>"
    }
  },
  "updated_at": "<ISO8601>"
}

モードごとの pipeline_stages：

モードpipeline_stages
spec-only["analyst", "writer", "reviewer"]
impl-only["planner", "executor", "tester", "reviewer"]
fe-only["planner", "fe-developer", "fe-qa"]
fullstack["planner", "executor", "fe-developer", "tester", "fe-qa", "reviewer"]
full-lifecycle["analyst", "writer", "planner", "executor", "tester", "reviewer"]
full-lifecycle-fe["analyst", "writer", "planner", "executor", "fe-developer", "tester", "fe-qa", "reviewer"]
messages.jsonl

NDJSON イベントログ（1 行につき JSON オブジェクト 1 つ）：

{"id":"MSG-001","ts":"<ISO8601>","from":"coordinator","to":"coordinator","type":"state_update","summary":"Session initialized","data":{...}}
{"id":"MSG-002","ts":"<ISO8601>","from":"analyst","to":"coordinator","type":"impl_complete","summary":"RESEARCH-001 completed","data":{...}}

メッセージの種類：state_update、impl_complete、impl_progress、test_result、review_result、error、shutdown

セッションの再開

オーケストレーターが既存のアクティブ／一時停止中のセッションを検出した場合：

  1. セッションディレクトリから team-session.json を読み込む
  2. ステータスが "in_progress" の各タスクについて：
    • 対応するアクティブなエージェントがない場合 -> タスクが中断されているため、"pending" にリセットする
    • 対応するアクティブなエージェントがある場合 -> エージェントがまだ稼働中か確認する（タイムアウト 0 で wait を試行）
  3. 整合：モードに必要なタスクがすべて状態に存在することを確認する
  4. 正しい blocked_by 依存関係を設定して、不足しているタスクを作成する
  5. 依存関係チェーンの整合性を確認する（循環や参照先のない参照がないこと）
  6. 整合した状態で状態ファイルを更新する
  7. Phase 4 に進み、準備ができたタスクを起動する

ユーザーコマンド

パイプラインの実行中、ユーザーは次のコマンドを発行できます：

コマンドアクション
check / status実行ステータスのグラフを出力する（読み取り専用。処理は進めない）
resume / continueエージェントの状態を確認し、パイプラインを進める
新しいセッションのリクエストPhase 0 で検出し、通常の Phase 1-5 のフローに入る

ステータスグラフの出力形式：

[orchestrator] Pipeline Status
[orchestrator] Mode: <mode> | Progress: <completed>/<total> (<percent>%)

[orchestrator] Execution Graph:
  Spec Phase: (if applicable)
    [V RESEARCH-001(+D1)] -> [V DRAFT-001(+D2)] -> [>>> DRAFT-002(+D3)]
    -> [o DRAFT-003(+D4)] -> [o DRAFT-004(+D5)] -> [o QUALITY-001(+D6)]
  Impl Phase: (if applicable)
    [o PLAN-001]
      +- BE: [o IMPL-001] -> [o TEST-001] -> [o REVIEW-001]
      +- FE: [o DEV-FE-001] -> [o QA-FE-001]

  V=completed  >>>=running  o=pending  .=not created

[orchestrator] Active Agents:
  > <task-id> (<agent-role>) - running <elapsed>

[orchestrator] Ready to spawn: <task-ids>
[orchestrator] Commands: 'resume' to advance | 'check' to refresh

ライフサイクル管理

タイムアウトプロトコル
フェーズタイムアウトタイムアウト時の処理
Phase 1（要件）なし（対話型）N/A
Phase 2（初期化）60sエラーで終了
Phase 3（ディスパッチ）60sエラーで終了
Phase 4（エージェントごと）15 分（仕様エージェント）、30 分（実装エージェント）send_input で収束リクエストを送信し、さらに 2 分待ってから終了する
Phase 5（レポート）60s部分的なレポートを出力

収束リクエスト（タイムアウト時に send_input で送信）：

send_input({
  id: <agent-id>,
  message: `
## TIMEOUT NOTIFICATION

Execution timeout reached. Please:
1. Save all current progress to artifact files
2. Output TASK_COMPLETE with status: partial
3. Include summary of completed vs remaining work
`
})
クリーンアッププロトコル

パイプラインが完了したとき（または中止されたとき）：

// Close all active agents
for (const agentEntry of state.active_agents) {
  try {
    close_agent({ id: agentEntry.agent_id })
  } catch (e) {
    // Agent already closed, ignore
  }
}

// Update state file
state.status = "completed"  // or "aborted"
state.updated_at = new Date().toISOString()
// Write state file

エラー処理

シナリオ検出方法解決方法
エージェントのタイムアウトwait() が timed_out を返すsend_input で収束リクエストを送信し、2 分間待って再試行してから、エージェントを終了し、タスクをリセットする
エージェントのクラッシュ／予期しない終了wait() がエラーステータスを返すタスクを pending にリセットし、エージェントを再起動する（最大 3 回再試行）
同じタスクで 3 回以上失敗状態ファイル内の再試行回数パイプラインを一時停止し、ユーザーに報告する
早期進行による孤立タスクタスクが in_progress だがアクティブなエージェントがなく、5 分以上経過pending にリセットし、エージェントを再起動する
コンセンサスが HIGH でブロックエージェント出力から DISCUSS_RESULT を解析修正タスクを作成する（最大 1 回）か、一時停止する
DISCUSS-006 でコンセンサスが HIGH でブロック上記と同様だが、最終承認ラウンド常にユーザーの確認のため一時停止する
修正後もブロック修正タスクが HIGH でブロックを返すパイプラインを一時停止し、ユーザーにエスカレーションする
セッションファイルの破損JSON 解析エラー直近の正常な状態からの復旧を試みるか、エラーを報告する
パイプラインの停滞ready も running もなく、pending があるblocked_by を調べ、ブロックの詳細を報告する
不明なエージェント出力形式wait の結果に TASK_COMPLETE が見つからない警告を記録し、ステータスの抽出を試み、部分完了としてマークする
状態内の重複タスクディスパッチ時にタスク ID がすでに存在する作成をスキップし、警告を記録する
依存関係の欠落blocked_by が存在しないタスクを参照しているエラーを記録し、パイプラインを停止する

フロントエンドの自動検出

Phase 1 では、オーケストレーターがフロントエンド作業の必要性を検出します：

シグナル検出方法パイプラインのアップグレード
説明に FE のキーワードがある一致：component、page、UI、React、Vue、CSS、HTML、Tailwind、Svelte、Next.js、Nuxt、shadcn、design systemimpl-only -> fe-only または fullstack
BE のキーワードも含まれる一致：API、database、server、endpoint、backend、middlewareimpl-only -> fullstack
プロジェクトで FE フレームワークを使用package.json 内の react/vue/svelte/next を検出full-lifecycle -> full-lifecycle-fe

インラインディスカッションプロトコル（エージェント向け）

Produce エージェント（analyst、writer、reviewer）は、主な成果物を完成させた後に discuss サブエージェントを呼び出します。このプロトコルは参照用に記載されています。各エージェントのロールファイルには、具体的な呼び出し方法が記載されています。

ディスカッションラウンドの対応関係：

エージェントタスク完了後ディスカッションラウンド観点
analystRESEARCH-001DISCUSS-001プロダクト、リスク、網羅性
writerDRAFT-001DISCUSS-002プロダクト、技術、品質、網羅性
writerDRAFT-002DISCUSS-003品質、プロダクト、網羅性
writerDRAFT-003DISCUSS-004技術、リスク
writerDRAFT-004DISCUSS-005プロダクト、技術、品質、網羅性
reviewerQUALITY-001DISCUSS-0065 つすべて（プロダクト、技術、品質、リスク、網羅性）

エージェント側の discuss 呼び出し（オーケストレーターではなく、エージェント内で実行）：

// Agent spawns discuss subagent internally
const discussId = spawn_agent({
  message: `
## MANDATORY FIRST STEPS (Agent Execute)
1. **Read agent definition**: ~/.codex/agents/discuss-agent.md (MUST read first)

---

## Multi-Perspective Critique: <round-id>

### Input
- Artifact: <artifact-path>
- Round: <round-id>
- Perspectives: <perspective-list>
- Session: <session-dir>
- Discovery Context: <session-dir>/spec/discovery-context.json

### Execution
Per-perspective CLI analysis -> divergence detection -> consensus determination -> write record.

### Output
Write discussion record to: <session-dir>/discussions/<round-id>-discussion.md
Return verdict summary with: verdict, severity, average_rating, action_items, recommendation.
`
})

const discussResult = wait({ ids: [discussId], timeout_ms: 300000 })
close_agent({ id: discussId })
// Agent includes discuss result in its TASK_COMPLETE output

共有 Explore プロトコル（エージェント向け）

コードベースのコンテキストが必要なエージェントは、explore サブエージェントを呼び出します。結果は explorations/ にキャッシュされます。

エージェント側の explore 呼び出し（オーケストレーターではなく、エージェント内で実行）：

// Agent spawns explore subagent internally
const exploreId = spawn_agent({
  message: `
## MANDATORY FIRST STEPS (Agent Execute)
1. **Read agent definition**: ~/.codex/agents/explore-agent.md (MUST read first)

---

## Explore Codebase

Query: <query>
Focus angle: <angle>
Keywords: <keyword-list>
Session folder: <session-dir>

## Cache Check
1. Read <session-dir>/explorations/cache-index.json (if exists)
2. If matching angle found AND file exists -> return cached result
3. If not found -> proceed to exploration

## Output
Write JSON to: <session-dir>/explorations/explore-<angle>.json
Update cache-index.json with new entry.
Return summary: file count, pattern count, top 5 files, output path.
`
})

const exploreResult = wait({ ids: [exploreId], timeout_ms: 300000 })
close_agent({ id: exploreId })

キャッシュ参照ルール：

条件アクション
cache-index.json に完全一致する観点があるキャッシュ済みの結果を返す
一致するものがない探索を実行し、結果をキャッシュする
インデックスにエントリーがあるが、キャッシュファイルが存在しない古いエントリーを削除し、再探索する

知見の蓄積

タスクをまたいで知識を蓄積します。オーケストレーターはセッション開始時に wisdom/ を作成します。

ディレクトリ：

<session-dir>/wisdom/
+-- learnings.md      # Patterns and insights discovered
+-- decisions.md      # Architecture and design decisions made
+-- conventions.md    # Codebase conventions identified
+-- issues.md         # Known risks and issues flagged

エージェントの責務：

  • 開始時：タスクをまたぐコンテキストとして、すべての wisdom ファイルを読む
  • 作業中：発見した内容を適切な wisdom ファイルに追記する
  • 完了時：重要な発見を TASK_COMPLETE の概要に含める

ロール分離ルール

許可禁止
エージェントは自身のプレフィックスのタスクのみを処理する他のエージェントのタスクを処理する
エージェントは TASK_COMPLETE の出力を通じて結果を伝えるエージェント同士が直接やり取りする
エージェントは内部で discuss／explore サブエージェントを呼び出すエージェントがオーケストレーターの状態ファイルを変更する
エージェントは指定されたディレクトリに成果物を書き込む他のエージェントのディレクトリに書き込む
エージェントは wisdom ファイルと shared-memory.json を読む他のエージェントの成果物を削除または上書きする

オーケストレーターにも、コードを直接記述・変更すること、実装ツールを呼び出すこと、分析／テスト／レビュー作業を実行することを禁止します。

GC ループ（フロントエンド QA）

FE パイプラインでは、QA-FE が修正と再テストのサイクルを開始する場合があります。

Round 1: DEV-FE-001 -> QA-FE-001
  QA-FE verdict: NEEDS_FIX?
    YES -> Round 2: DEV-FE-002(blocked_by: QA-FE-001) -> QA-FE-002(blocked_by: DEV-FE-002)
    QA-FE-002 verdict: NEEDS_FIX?
      YES -> max rounds reached (2), stop loop, report current state
      NO  -> proceed to next pipeline step
    NO -> proceed to next pipeline step

GC ループの反復が必要になると、オーケストレーターは DEV-FE-NNN と QA-FE-NNN のタスクを状態ファイルに動的に追加します。

モードとパイプラインのクイックリファレンス

モードタスク総数最初のタスクチェックポイント
spec-only6RESEARCH-001なし（QUALITY-001 が最終）
impl-only4PLAN-001なし
fe-only3（+GC）PLAN-001なし
fullstack6PLAN-001なし
full-lifecycle10RESEARCH-001QUALITY-001 の後
full-lifecycle-fe12（+GC）RESEARCH-001QUALITY-001 の後

共有仕様リソース

リソースパス（スキルからの相対パス）用途
ドキュメント規約specs/document-standards.mdYAML フロントマター、命名、構成
品質ゲートspecs/quality-gates.mdフェーズごとの品質ゲート
プロダクト概要テンプレートtemplates/product-brief.mdDRAFT-001
要件テンプレートtemplates/requirements-prd.mdDRAFT-002
アーキテクチャテンプレートtemplates/architecture-doc.mdDRAFT-003
エピックテンプレートtemplates/epics-template.mdDRAFT-004

コーディネーターの役割に関する制約（メインエージェント）

重要：このスキルを実行するコーディネーター（メインエージェント）の役割はオーケストレーションのみであり、実装は行いません。

  1. コーディネーターはコードを実行しません：メインエージェントは、コードを直接記述、変更、実装してはなりません。すべての実装作業は、起動したチームエージェントに委任します。コーディネーターが行うのは次の作業のみです。

    • タスクを割り当ててエージェントを起動する
    • エージェントからのコールバックを待つ
    • 結果を統合し、ワークフローを調整する
    • フェーズ間のワークフローの移行を管理する

  2. 辛抱強く待つことが必須です：エージェントの実行にはかなりの時間がかかります（通常、フェーズごとに10～30分、ときにはそれ以上）。コーディネーターは次のことを必ず守ってください。

    • wait() 呼び出しが完了するまで辛抱強く待つ
    • 遅れていると思われることを理由に、ワークフローの手順を省略しない
    • 時間がかかっているというだけで、エージェントが失敗したと判断しない
    • スキルで定義されているタイムアウトの仕組みを信頼する

  3. 確認には send_input を使用します：エージェントが指針を必要としている場合や、行き詰まっているように見える場合、コーディネーターは次のことを必ず守ってください。

    • send_input() を使って質問するか、説明を補足する
    • エージェントを飛ばしたり、次のフェーズに早まって進んだりしない
    • エスカレーションする前に、エージェントが応答する機会を与える
    • 例：send_input({ id: agent_id, message: "Please provide status update or clarify blockers" })

  4. ワークフローの近道は禁止です：コーディネーターは次のことをしてはなりません。

    • ワークフローで定義されたフェーズやステージを省略する
    • 必須の承認またはレビューの手順を回避する
    • 前提条件の完了前に、依存するタスクを実行する
    • エージェントから明示的なコールバックがないまま、タスクが完了したと判断する
    • エージェントの結果を捏造する

  5. 長時間実行されるプロセスを尊重します：これは複雑なマルチエージェントのワークフローであり、辛抱強く進める必要があります。

    • 全体の実行時間は30～90分、またはそれ以上に及ぶ場合があります
    • 複雑さによって、各フェーズに10～30分かかる場合があります
    • コーディネーターは、プロセス全体を通して作業を続け、注意を払わなければなりません
    • 時間が気になることを理由に、プロセスを終了したり、手順を省略したりしないでください

コメント

Markdown 対応