parallel-dev-cycle

並列開発サイクル

4 つの専門ワーカーを使用する、Codex のサブエージェントパターンによるマルチエージェント並列開発サイクル：

1. 要件分析と拡張（RA）- 要件分析と自己拡張
2. 調査と計画（EP）- コードベースの調査と実装計画の策定
3. コード開発（CD）- デバッグ戦略のサポートを含むコード開発
4. 検証とアーカイブ要約（VAS）- 検証とアーカイブ要約

オーケストレーションロジック（フェーズ管理、状態更新、フィードバック調整）はメインフロー内でインライン実行されます。独立したオーケストレーターエージェントは起動されません。割り当てられるのは 4 つのワーカーエージェントのみです。

各エージェントはメインドキュメントを 1 つ維持します（例：requirements.md、plan.json、implementation.md）。このドキュメントはイテレーションごとに完全に書き換えられ、補助ログ（changes.log、debug-log.ndjson）は追記専用です。

アーキテクチャ概要

┌─────────────────────────────────────────────────────────────┐
│                    User Input (Task)                        │
└────────────────────────────┬────────────────────────────────┘
                             │
                             v
              ┌──────────────────────────────┐
              │  Main Flow (Inline Orchestration)  │
              │  Phase 1 → 2 → 3 → 4              │
              └──────────────────────────────┘
                             │
        ┌────────────────────┼────────────────────┐
        │                    │                    │
        v                    v                    v
    ┌────────┐         ┌────────┐         ┌────────┐
    │  RA    │         │  EP    │         │  CD    │
    │Agent   │         │Agent   │         │Agent   │
    └────────┘         └────────┘         └────────┘
        │                    │                    │
        └────────────────────┼────────────────────┘
                             │
                             v
                         ┌────────┐
                         │  VAS   │
                         │ Agent  │
                         └────────┘
                             │
                             v
              ┌──────────────────────────────┐
              │    Summary Report            │
              │  & Markdown Docs             │
              └──────────────────────────────┘

主な設計原則

1. メインドキュメントと補助ログ：各エージェントはメインドキュメントを 1 つ（イテレーションごとに書き換え）と補助ログ（追記専用）を維持します
2. バージョンベースの上書き：メインドキュメントはバージョンごとに完全に書き換え、ログは追記専用です
3. 自動アーカイブ：古いメインドキュメントのバージョンは history/ ディレクトリに自動的にアーカイブされます
4. 完全な監査証跡：changes.log（NDJSON）にすべての変更履歴が保持されます
5. 並列調整：4 つのエージェントを同時に起動し、共有状態とインラインのメインフローを介して調整します
6. ファイル参照：内容を受け渡す代わりに、短いファイルパスを使用します
7. 自己拡張：RA エージェントは、コンテキストに基づいて要件を積極的に拡張します
8. 共有発見ボード：すべてのエージェントは discoveries.ndjson を介して調査結果を共有します。開始時に読み込み、発見した内容を書き込むことで、コードベース調査の重複をなくします

引数

Arg	必須	説明
TASK	TASK または --cycle-id のいずれか	タスクの説明（新しいサイクルの場合。--cycle-id とは同時に指定できません）
--cycle-id	TASK または --cycle-id のいずれか	続行する既存のサイクル ID（API または前回のセッションから取得）
--extend	いいえ	拡張の説明（--cycle-id と併用する場合のみ有効）
--auto	いいえ	自動サイクルモード（ユーザーの確認なしで全フェーズを順次実行）
--parallel	いいえ	並列エージェント数（デフォルト：4、最大：4）

自動モード

--auto を指定すると、イテレーション間のユーザー確認なしで全フェーズを順次実行します。すべての判断で推奨されるデフォルトを使用します。テストに合格するか、最大イテレーション数に達するまで、イテレーションループを自動的に続行します。

準備パッケージとの連携

{projectRoot}/.workflow/.cycle/prep-package.json に prep-package.json が存在する場合、フェーズ 1 では次のように使用します：

• 生の TASK の代わりに、詳細化されたタスクの説明を使用する
• 自動イテレーション設定（収束条件、フェーズゲート）を適用する
• イテレーションごとのエージェントの重点指示（0→1 対 1→100）を注入する

準備パッケージは対話型プロンプト /prompts:prep-cycle によって生成されます。スキーマについては phases/00-prep-checklist.md を参照してください。

実行フロー

Input Parsing:
   └─ Parse arguments (TASK | --cycle-id + --extend)
   └─ Convert to structured context (cycleId, state, progressDir)
   └─ Initialize progress tracking: functions.update_plan([...phases])

Phase 1: Session Initialization
   └─ Ref: phases/01-session-init.md
      ├─ Create new cycle OR resume existing cycle
      ├─ Initialize state file and directory structure
      └─ Output: cycleId, state, progressDir

Phase 2: Agent Execution (Parallel)
   └─ Ref: phases/02-agent-execution.md
      ├─ Tasks attached: Spawn RA → Spawn EP → Spawn CD → Spawn VAS → Wait all
      ├─ Spawn RA, EP, CD, VAS agents in parallel
      ├─ Wait for all agents with timeout handling
      └─ Output: agentOutputs (4 agent results)

Phase 3: Result Aggregation & Iteration
   └─ Ref: phases/03-result-aggregation.md
      ├─ Parse PHASE_RESULT from each agent
      ├─ Detect issues (test failures, blockers)
      ├─ Decision: Issues found AND iteration < max?
      │   ├─ Yes → Send feedback via followup_task, loop back to Phase 2
      │   └─ No → Proceed to Phase 4
      └─ Output: parsedResults, iteration status

Phase 4: Completion & Summary
   └─ Ref: phases/04-completion-summary.md
      ├─ Generate unified summary report
      ├─ Update final state
      ├─ Sync session state: $session-sync -y "Dev cycle complete: {iterations} iterations"
      ├─ Close all agents
      └─ Output: final cycle report with continuation instructions

フェーズ参照ドキュメント（フェーズの実行時に必要に応じて読み込みます）：

Phase	Document	Purpose
1	phases/01-session-init.md	セッションの作成／再開と状態の初期化
2	phases/02-agent-execution.md	エージェントの並列起動と実行
3	phases/03-result-aggregation.md	結果の解析、フィードバックの生成、イテレーションの処理
4	phases/04-completion-summary.md	最終要約の生成とクリーンアップ

データフロー

User Input (TASK | --cycle-id + --extend)
    ↓
[Parse Arguments]
    ↓ cycleId, state, progressDir

Phase 1: Session Initialization
    ↓ cycleId, state, progressDir (initialized/resumed)

Phase 2: Agent Execution
    ├─ All agents read coordination/discoveries.ndjson on start
    ├─ Each agent explores → writes new discoveries to board
    ├─ Later-finishing agents benefit from earlier agents' findings
    ↓ agentOutputs {ra, ep, cd, vas} + shared discoveries.ndjson

Phase 3: Result Aggregation
    ↓ parsedResults, hasIssues, iteration count
    ↓ [Loop back to Phase 2 if issues and iteration < max]
    ↓ (discoveries.ndjson carries over across iterations)

Phase 4: Completion & Summary
    ↓ finalState, summaryReport

Return: cycle_id, iterations, final_state

セッション構造

{projectRoot}/.workflow/.cycle/
├── {cycleId}.json                                 # Master state file
├── {cycleId}.progress/
    ├── ra/
    │   ├── requirements.md                        # Current version (complete rewrite)
    │   ├── changes.log                            # NDJSON complete history (append-only)
    │   └── history/                               # Archived snapshots
    ├── ep/
    │   ├── exploration.md                         # Codebase exploration report
    │   ├── architecture.md                        # Architecture design
    │   ├── plan.json                              # Structured task list (current version)
    │   ├── changes.log                            # NDJSON complete history
    │   └── history/
    ├── cd/
    │   ├── implementation.md                      # Current version
    │   ├── debug-log.ndjson                       # Debug hypothesis tracking
    │   ├── changes.log                            # NDJSON complete history
    │   └── history/
    ├── vas/
    │   ├── summary.md                             # Current version
    │   ├── changes.log                            # NDJSON complete history
    │   └── history/
    └── coordination/
        ├── discoveries.ndjson                     # Shared discovery board (all agents append)
        ├── timeline.md                            # Execution timeline
        └── decisions.log                          # Decision log

状態管理

マスター状態ファイル：{projectRoot}/.workflow/.cycle/{cycleId}.json

{
  "cycle_id": "cycle-v1-20260122T100000-abc123",
  "title": "Task title",
  "description": "Full task description",
  "status": "created | running | paused | completed | failed",
  "created_at": "ISO8601", "updated_at": "ISO8601",
  "max_iterations": 5, "current_iteration": 0,
  "agents": {
    "ra":  { "status": "idle | running | completed | failed", "output_files": [] },
    "ep":  { "status": "idle", "output_files": [] },
    "cd":  { "status": "idle", "output_files": [] },
    "vas": { "status": "idle", "output_files": [] }
  },
  "current_phase": "init | ra | ep | cd | vas | aggregation | complete",
  "completed_phases": [],
  "requirements": null, "plan": null, "changes": [], "test_results": null,
  "coordination": { "feedback_log": [], "blockers": [] }
}

復旧：状態が破損した場合は、.progress/ 内の Markdown ファイルと changes.log から再構築します。

進捗の追跡

初期化（必須）

// Initialize progress tracking after input parsing
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Session Initialization", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Agent Execution", status: "pending" },
  { id: "phase-3", title: "Phase 3: Result Aggregation", status: "pending" },
  { id: "phase-4", title: "Phase 4: Completion & Summary", status: "pending" }
])

フェーズの遷移

// After Phase 1 completes
functions.update_plan([
  { id: "phase-1", status: "completed" },
  { id: "phase-2", status: "in_progress" }
])

// After Phase 2 completes
functions.update_plan([
  { id: "phase-2", status: "completed" },
  { id: "phase-3", status: "in_progress" }
])

// After Phase 3 — iterate or complete
// If iterating back to Phase 2:
functions.update_plan([
  { id: "phase-3", status: "completed" },
  { id: "phase-2", title: "Phase 2: Agent Execution (Iteration N)", status: "in_progress" }
])
// If proceeding to Phase 4:
functions.update_plan([
  { id: "phase-3", status: "completed" },
  { id: "phase-4", status: "in_progress" }
])

// After Phase 4 completes
functions.update_plan([{ id: "phase-4", status: "completed" }])

バージョン管理

• 1.0.0：初回サイクル → 1.x.0：各イテレーション（マイナーバージョンを更新）
• 各イテレーション：古いファイルをアーカイブ → 全面書き換え → changes.log に追記

Archive: copy requirements.md → history/requirements-v1.0.0.md
Rewrite: overwrite requirements.md with v1.1.0 (complete new content)
Append:  changes.log ← {"timestamp","version":"1.1.0","action":"update","description":"..."}

エージェントの出力	書き換え（イテレーションごと）	追記のみ
RA	requirements.md	changes.log
EP	exploration.md, architecture.md, plan.json	changes.log
CD	implementation.md, issues.md	changes.log, debug-log.ndjson
VAS	summary.md, test-results.json	changes.log

調整プロトコル

実行順序：RA → EP → CD → VAS（依存関係の連鎖。すべて並列で起動しますが、依存関係の完了を待ちます）

共有ディスカバリーボード

すべてのエージェントは、coordination/discoveries.ndjson にあるリアルタイムのディスカバリーボードを共有します。各エージェントは開始時にボードを読み取り、作業中に調査結果を追記します。これにより、コードベースの調査の重複を防ぎます。

ライフサイクル：

• 最初に調査結果を書き込むエージェントが作成します（ファイルは最初は存在しない場合があります）
• イテレーションをまたいで引き継がれます。消去または再作成されることはありません
• エージェントは Bash の echo '...' >> discoveries.ndjson を使ってエントリーを追記します

形式：NDJSON。各行は自己完結型の JSON で、必須のトップレベルフィールド ts、agent、type、data を含みます：

{"ts":"2026-01-22T10:00:00+08:00","agent":"ra","type":"tech_stack","data":{"language":"TypeScript","framework":"Express","test":"Jest","build":"tsup"}}

ディスカバリーの種類：

type	重複排除キー	書き込み元	読み取り元	必須の data フィールド
tech_stack	singleton	RA	EP, CD, VAS	language、framework、test、build
project_config	data.path	RA	EP, CD	path、key_deps[]、scripts{}
existing_feature	data.name	RA, EP	CD	name、files[]、summary
architecture	singleton	EP	CD, VAS	pattern、layers[]、entry
code_pattern	data.name	EP, CD	CD, VAS	name、description、example_file
integration_point	data.file	EP	CD	file、description、exports[]
similar_impl	data.feature	EP	CD	feature、files[]、relevance
code_convention	singleton	CD	VAS	naming、imports、formatting
utility	data.name	CD	VAS	name、file、usage
test_command	singleton	CD, VAS	VAS, CD	unit、integration（任意）、coverage（任意）
test_baseline	singleton	VAS	CD	total、passing、coverage_pct、framework、config
test_pattern	singleton	VAS	CD	style、naming、fixtures
blocker	data.issue	any	all	issue、severity、impact

プロトコルのルール：

1. 独自の調査を始める前にボードを読む → 記載済みの領域は調査を省略する（ファイルが存在しない場合は省略）
2. Bash の echo >> で調査結果をすぐに書き込む → まとめて書き込まない
3. 重複を排除する — 既存のエントリーを確認し、同じ type と重複排除キーの値がすでにある場合は省略する
4. 追記のみ — 既存の行は変更も削除もしない

エージェント → メインフローの通信

PHASE_RESULT:
- phase: ra | ep | cd | vas
- status: success | failed | partial
- files_written: [list]
- summary: one-line summary
- issues: []

メインフロー → エージェントの通信

followup_task を使ってフィードバックを伝えます（ファイル参照と問題の要約のみ。全内容は含めません）：

## FEEDBACK FROM [Source]
[Issue summary with file:line references]
## Reference
- File: .progress/vas/test-results.json (v1.0.0)
## Actions Required
1. [Specific fix]

ルール：状態ファイルを書き込むのはメインフローのみです。エージェントは状態を読み取り、自身の .progress/{agent}/ ディレクトリにのみ書き込みます。

コアルール

1. すぐに開始する：最初のアクションは functions.update_plan の初期化とし、その後フェーズ 1 を実行します
2. フェーズごとに段階的に読み込む：フェーズのドキュメントは、そのフェーズを実行する直前にのみ読み取ります
3. すべての出力を解析する：各エージェントから PHASE_RESULT データを抽出し、次のフェーズで使用します
4. 自動で続行する：各フェーズの後、保留中の次のフェーズを自動的に実行します
5. 進捗を追跡する：各フェーズの移行時に functions.update_plan を更新します
6. 単一の書き込み元：マスター状態ファイルに書き込むのはメインフローのみです。エージェントは PHASE_RESULT を通じて報告します
7. ファイル参照：エージェント間では内容ではなくファイルパスを渡します
8. 停止しない：すべてのフェーズが完了するか、最大イテレーション数に達するまで実行を続けます

エラー処理

エラーの種類	復旧方法
エージェントのタイムアウト	収束を求める followup_task を送信してから再試行します
状態の破損	進捗を記録した Markdown ファイルと changes.log から再構築します
エージェントの失敗	前回のコンテキストを使ってエージェントを再起動します
結果の競合	メインフローから調整を依頼します
ファイルの欠落	RA/EP エージェントが特定し、確認を依頼します
最大反復回数への到達	残りの問題を記録した要約を生成します

コーディネーターのチェックリスト（メインフロー）

各フェーズの開始前

• フェーズの参照ドキュメントを読みます
• 現在の状態を確認し、依存関係を確認します
• functions.update_plan を更新し、フェーズの状態を記録します

各フェーズの終了後

• エージェントの出力（PHASE_RESULT）を解析します
• マスター状態ファイルを更新します
• functions.update_plan を更新し、フェーズの完了を記録します
• 次のアクション（続行／反復／完了）を決定します

参照ドキュメント

ドキュメント	目的
roles/	エージェントの役割定義（RA、EP、CD、VAS）

使用方法

# Start new cycle
/parallel-dev-cycle TASK="Implement real-time notifications"

# Continue cycle
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123

# Iteration with extension
/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Also add email notifications"

# Auto mode
/parallel-dev-cycle --auto TASK="Add OAuth authentication"