octocode-documentation-writer

リポジトリドキュメント生成ツール

インテリジェントなオーケストレーション、調査を優先した検証、競合のないファイル所有権を備えた、本番環境対応の6フェーズパイプラインです。

このコマンドは、6つのフェーズで専門のAIエージェントをオーケストレーションし、コードリポジトリを分析して包括的なドキュメントを生成します。 ## ランタイムの互換性

• Opus、Sonnet、Haikuなどのモデルラベルは役割の目安であり、必須条件ではありません。タスクに最適な、利用可能なホストモデルに割り当ててください。
• Taskは、ホストランタイムの並列サブエージェント機構を意味します。IFホストで真の並列サブエージェントを実行できない場合 → THEN同じ作業を順番に実行し、ファイルの所有権が重複しないようにしてください。
• このドキュメント内の擬似コードブロックは、動作を示すテンプレートです。文字どおりの API として扱うのではなく、使用中のランタイムに合わせてヘルパー名、ファイル API、再試行用ヘルパーを調整してください。
• セッション成果物は .octocode/documentation/{session-name}/ の下に保存されます。特に指定がない限り、以下の analysis.json のような短縮名は、そのセッションディレクトリ内のファイルを指します。

**調査＋分析**（フェーズ 1） エージェントの役割：高性能な推論モデル 並列実行：4 つの並列エージェント 内容：言語、アーキテクチャ、フロー、API を分析 入力：リポジトリのパス 出力：`analysis.json`

<phase_2> エンジニア向けの質問（フェーズ 2） エージェントの役割：高性能な推論モデル 内容：分析に基づいて包括的な質問を生成 入力：analysis.json 出力：questions.json </phase_2>

<phase_3> 調査エージェント（フェーズ 3）🆕 エージェントの役割：高速な調査・実行モデル 並列実行：動的（質問の量に応じて調整） 内容：コードを詳細に調査し、証拠を添えて質問に回答 入力：analysis.json + questions.json 出力：research.json </phase_3>

<phase_4> オーケストレーター（フェーズ 4） エージェントの役割：高性能な推論モデル 内容：質問を対象ファイルごとにグループ化し、ライターにファイルの排他的な所有権を割り当てる 入力：questions.json + research.json 出力：work-assignments.json（並列ライター向けのファイル単位の割り当て） </phase_4>

<phase_5> ドキュメント作成者（フェーズ 5） エージェントの役割：高速な執筆モデル 並列実行：1～8 個の並列エージェント（作業量に応じて動的に調整） 内容：調査結果を統合し、ファイルの排他的な所有権を守りながら包括的なドキュメントを作成 入力：analysis.json + questions.json + research.json + work-assignments.json 出力：documentation/*.md（中核ドキュメント 16 件、必須ドキュメント 5 件、およびライターが所有する補足ファイル。QA-SUMMARY.mdはフェーズ 6 で生成されます） </phase_5>

<phase_6> QA バリデーター（フェーズ 6） エージェントの役割：高速な検証モデル 内容：LSP を利用した検証により、ドキュメントの品質を検証 入力：documentation/*.md + analysis.json + questions.json + research.json 出力：qa-results.json + QA-SUMMARY.md </phase_6>

ホストのサブエージェント機構を使い、MCP ツール（`localSearchCode`、`lspGotoDefinition`、`lspCallHierarchy`、`lspFindReferences`）でコードを調査してください。モデルのティアは、ハードコードされたモデル名ではなく、能力に基づいて選んでください。

<mcp_discovery> 開始前に、利用可能な調査ツールを検出してください。

確認事項：octocode-mcpが MCP サーバーとして利用可能かどうか。 Octocode MCP ツール（例：localSearchCode、lspGotoDefinition、githubSearchCode、packageSearch）を探してください。

Octocode MCP は存在するが、ローカルツールから結果が返らない場合：

次のように提案します：「ローカルコードベースを調査するには、Octocode MCP の設定に ENABLE_LOCAL=true を追加してください。」

Octocode MCP がインストールされていない場合：

次のように提案します：「より詳細な調査を行うには、Octocode MCP をインストールしてください：

{
  "mcpServers": {
    "octocode": {
      "command": "npx",
      "args": ["-y", "octocode-mcp"],
      "env": {"ENABLE_LOCAL": "true"}
    }
  }
}

その後、エディターを再起動してください。」

利用可能なツールで作業を進め、セットアップが完了するまで待たないでください。 </mcp_discovery>

ドキュメント作成フロー： analysis.json → questions.json → research.json → work-assignments.json → documentation（競合なし！）

---

⚠️ 重要：並列エージェントの実行

<parallel_execution_critical importance="maximum">

停止してください。これを 2 回読んでください。

1. ルール

ホストがサポートする最も強力な並列化方式を使用してください。 ランタイムが Task 呼び出しの並行実行をサポートしている場合は、1 回のメッセージでファンアウトする方法を優先してください。

2. 禁止事項

禁止： ホストが実際には逐次実行した作業を、並列実行したと主張すること。 理由： 実行していない並列処理を主張すると、ランタイムの制限が隠され、障害の原因を特定しにくくなります。

3. 必須のフォールバック

ランタイムが真の並列ファンアウトを実行できない場合：

• 同じ作業範囲のワーカーを逐次実行します
• ファイルの排他的な所有権を維持します
• 同じフェーズの境界と集約手順を維持します
• 実行が逐次フォールバックモードであることをユーザーに伝えます

4. 必須の確認

並列フェーズ（1、3、5）を開始する前に、必ず次の項目を確認してください。

• ホストが選択したファンアウト方式を実行できる
• 並列に実行するエージェント間に依存関係がない
• 各エージェントの作業範囲が排他的である（ファイルの競合がない）

<correct_pattern title="✅ 正しい例：1 回の応答で全エージェントを同時に起動">

// In ONE assistant message, include ALL Task tool invocations when the host supports it:
Task(description="Discovery 1A-language", subagent_type="general-purpose", prompt="...", model="opus")
Task(description="Discovery 1B-components", subagent_type="general-purpose", prompt="...", model="opus")
Task(description="Discovery 1C-dependencies", subagent_type="general-purpose", prompt="...", model="opus")
Task(description="Discovery 1D-flows", subagent_type="general-purpose", prompt="...", model="opus")
// ↑ All 4 execute SIMULTANEOUSLY

</correct_pattern>

<wrong_pattern title="❌ 誤った例：逐次呼び出しでは並列性が失われる">

// DON'T DO THIS when the host supports concurrency - each waits for previous to complete
Message 1: Task(description="Discovery 1A") → wait for result
Message 2: Task(description="Discovery 1B") → wait for result
Message 3: Task(description="Discovery 1C") → wait for result
Message 4: Task(description="Discovery 1D") → wait for result
// ↑ 4x slower! No parallelism achieved

</wrong_pattern>

</parallel_execution_critical>

---

実行フロー図

flowchart TB
    Start([/octocode-documentation-writer PATH]) --> Validate[Pre-Flight Validation]
    Validate --> Init[Initialize Workspace]

    Init --> P1[Phase 1: Discovery+Analysis]

    subgraph P1_Parallel["🔄 RUN IN PARALLEL (4 agents)"]
        P1A[Agent 1A:<br/>Language & Manifests]
        P1B[Agent 1B:<br/>Components]
        P1C[Agent 1C:<br/>Dependencies]
        P1D[Agent 1D:<br/>Flows & APIs]
    end

    P1 --> P1_Parallel
    P1_Parallel --> P1Agg[Aggregation:<br/>Merge into analysis.json]
    P1Agg --> P1Done[✅ analysis.json created]

    P1Done -->|Reads analysis.json| P2[Phase 2: Engineer Questions<br/>Single High-Capability Agent]
    P2 --> P2Done[✅ questions.json created]

    P2Done -->|Reads questions.json| P3[Phase 3: Research 🆕<br/>Parallel Research Agents]
    
    subgraph P3_Parallel["🔄 RUN IN PARALLEL"]
       P3A[Researcher 1]
       P3B[Researcher 2]
       P3C[Researcher 3]
    end
    
    P3 --> P3_Parallel
    P3_Parallel --> P3Agg[Aggregation:<br/>Merge into research.json]
    P3Agg --> P3Done[✅ research.json created<br/>Evidence-backed answers]

    P3Done -->|Reads questions + research| P4[Phase 4: Orchestrator<br/>Single High-Capability Agent]
    P4 --> P4Group[Group questions<br/>by file target]
    P4 --> P4Assign[Assign file ownership<br/>to writers]
    P4Assign --> P4Done[✅ work-assignments.json]

    P4Done --> P5[Phase 5: Documentation Writers]
    P5 --> P5Input[📖 Input:<br/>work-assignments.json<br/>+ research.json]
    P5Input --> P5Dist[Each writer gets<br/>exclusive file ownership]

    subgraph P5_Parallel["🔄 RUN IN PARALLEL (1-8 agents)"]
        P5W1[Writer 1]
        P5W2[Writer 2]
        P5W3[Writer 3]
        P5W4[Writer 4]
    end

    P5Dist --> P5_Parallel
    P5_Parallel --> P5Verify[Verify Structure]
    P5Verify --> P5Done[✅ documentation/*.md created]

    P5Done --> P6[Phase 6: QA Validator<br/>Single Validation Agent]
    P6 --> P6Done[✅ qa-results.json +<br/>QA-SUMMARY.md]

    P6Done --> Complete([✅ Documentation Complete])

    style P1_Parallel fill:#e1f5ff
    style P3_Parallel fill:#e1f5ff
    style P5_Parallel fill:#ffe1f5
    style P4 fill:#fff3cd
    style Complete fill:#28a745,color:#fff

並列実行ルール

<execution_rules> 停止してください。 並列起動の要件を確認してください。 必須： 利用可能な場合は、ホストの並列処理機能を使用してください。 フォールバック： ホストが真の並列処理を実行できない場合に限り、逐次実行が許可されます。 <agent_count>4</agent_count> 調査と分析 <spawn_instruction>1 回の応答でのファンアウトを優先してください。それができない場合は、排他的な作業範囲を維持しながら逐次フォールバックを実行してください</spawn_instruction> ホストがサポートしている場合は、4 つすべてのエージェントを同時に実行してください。それ以外の場合は逐次フォールバックを使用してください 集約の前に、4 つすべての完了を待ってください 4 つの部分的な JSON を analysis.json に集約する必要があります

<phase name="2-questions" type="single" critical="true" spawn="sequential">
    <agent_count>1</agent_count>
    <description>エンジニア向け質問の生成</description>
    <spawn_instruction>単一のエージェントを使用し、完了を待ちます</spawn_instruction>
</phase>

<phase name="3-research" type="parallel" critical="true" spawn="single_message">
    <gate>
    **停止してください。** 並列起動の要件を確認してください。
    **必須：** 利用可能な場合は、ホストの並列処理機能を使用してください。
    **フォールバック：** ホストが真の並列処理を実行できない場合に限り、逐次実行が許可されます。
    </gate>
    <agent_count_logic>
        <case condition="questions &lt; 10">エージェント 1 名</case>
        <case condition="questions &gt;= 10">切り上げ（質問数 / 15）</case>
    </agent_count_logic>
    <description>根拠の収集</description>
    <spawn_instruction>1 回の応答でのファンアウトを優先してください。それができない場合は、バッチの境界を維持しながら逐次フォールバックを実行してください</spawn_instruction>
    <rules>
        <rule>起動する前に、質問をバッチに分割してください</rule>
        <rule>ホストがサポートしている場合は、すべての調査担当者を同時に実行してください。それ以外の場合は逐次フォールバックを使用してください</rule>
        <rule>調査結果を research.json に集約してください</rule>
    </rules>
</phase>

<phase name="4-orchestrator" type="single" critical="true" spawn="sequential">
    <agent_count>1</agent_count>
    <description>オーケストレーションと割り当て</description>
    <spawn_instruction>単一のエージェントを使用し、完了を待ちます</spawn_instruction>
    <rules>
        <rule>ライターにファイルの排他的な所有権を割り当ててください</rule>
        <rule>調査結果を関連するライターに配布してください</rule>
    </rules>
</phase>

**停止してください。** 並列起動の要件を確認してください。 **必須：** 利用可能な場合は、ホストの並列実行機能を使用してください。 **フォールバック：** ホストで真の並列作業を実行できない場合に限り、逐次実行が許可されます。 1 エージェント 2-4 エージェント 4-8 エージェント 1 回の応答での一括起動を優先してください。それができない場合は、排他的な担当範囲を維持して逐次的にフォールバックしてください 各ライターには競合が起こらないよう、排他的なファイルを割り当ててください ホストが対応している場合はすべてのライターを同時に実行し、それ以外の場合は逐次的にフォールバックしてください 主な情報源として、提供された research.json を使用してください

<phase name="6-qa" type="single" critical="false" spawn="sequential">
    <agent_count>1</agent_count>
    <description>品質検証</description>
    <spawn_instruction>単一のエージェントを起動し、完了を待ってください</spawn_instruction>
</phase>

</execution_rules>

事前チェック

<pre_flight_gate> 停止してください。先に以下の要件を完了してください。

必須チェック

1. パスの存在を確認
   • repository_path が存在しない場合 → その場合 エラーを出して終了
2. ディレクトリの状態を確認
   • ディレクトリでない場合 → その場合 エラーを出して終了
3. ソースコードを確認
   • ソースファイルが 3 個未満の場合 → その場合 警告を出してユーザーに確認（いいえの場合は終了）
4. ビルドディレクトリを確認
   • node_modules または dist が含まれている場合 → その場合 エラーを出して終了
5. サイズを推定
   • 200k LOC を超える場合 → その場合 警告を出してユーザーに確認（いいえの場合は終了）

ゲートを通過するまで禁止：

• エージェントの起動
• ワークスペースの初期化 </pre_flight_gate>

開始する前に、リポジトリのパスを検証し、エッジケースを確認してください。

1. パスの存在を確認

   • repository_path が存在することを確認します。
   • 存在しない場合は、ERROR: "Repository path does not exist: " + path を発生させて終了します。

2. ディレクトリの状態を確認

   • repository_path がディレクトリであることを確認します。
   • ディレクトリでない場合は、ERROR: "Path is not a directory: " + path を発生させて終了します。

3. ソースコードを確認

   • .ts、.js、.py、.go、または .rs で終わるファイルを数えます。
   • node_modules、.git、dist、build ディレクトリは除外します。
   • ソースファイルが 3 個未満の場合：
     • WARN: "Very few source files detected ({count}). This may not be a code repository."
     • 呼び出し元が厳格な検証を明示的に要求していない限り、信頼度の低いモードで自動的に続行します。

4. ビルドディレクトリを確認

   • パスに node_modules、dist、または build が含まれていないことを確認します。
   • 含まれている場合は、ERROR: "Repository path appears to be a build directory. Please specify the project root." を発生させて終了します。

5. サイズを推定

   • リポジトリのサイズを推定します。
   • 200,000 LOC を超える場合：
     • WARN: "Large repository detected (~{size} LOC)."
     • 自動的に続行しますが、慎重に調査し、バッチ処理を優先してください。

ワークスペースを初期化

<init_gate> 停止してください。初期化前に状態を確認してください。

必須アクション

1. ディレクトリを定義（CONTEXT_DIR、DOC_DIR）
   • 必須： まず安定した SESSION_NAME を決定します（呼び出し元から指定されている場合はそれを使用し、指定されていない場合はリポジトリ名に基づく短い名前を使用します）
2. 既存の状態を処理
   • 非終端フェーズにある state.json が存在する場合 → その場合 自動的に再開
   • 呼び出し元が新規実行を明示的に要求している場合 → その場合 状態をリセット
3. ディレクトリを作成
4. 新しい状態を初期化（再開しない場合）

禁止事項：

• 状態を初期化する前にフェーズ 1 を開始すること。 </init_gate>

### ワークスペースの初期化 パイプラインを開始する前に、作業環境をセットアップし、既存の状態を処理します。

1. ディレクトリを定義する

   • セッションディレクトリ（CONTEXT_DIR）：${REPOSITORY_PATH}/.octocode/documentation/${SESSION_NAME}
   • ドキュメントディレクトリ（DOC_DIR）：${REPOSITORY_PATH}/documentation

2. 既存の状態を処理する

   • ${CONTEXT_DIR}/state.json が存在するか確認します。
   • 存在し、フェーズが「complete」または「failed」ではない場合：
     • デフォルトの動作：保存されたチェックポイントから再開します。
     • RESUME_MODE = true に設定します。
     • 保存された状態から START_PHASE を設定します。
     • 呼び出し元が明示的に再起動／新規生成を要求した場合のみ：
       • 警告：「最初から再起動します。以前の進捗は上書きされます。」
       • RESUME_MODE = false に設定します。
       • START_PHASE = "initialized" に設定します。
   • state.json が存在しない場合、または前回の実行が完了／失敗している場合は、新規に開始します（RESUME_MODE = false）。

3. ディレクトリを作成する

   • CONTEXT_DIR が存在することを確認します（存在しない場合は作成します）。
   • DOC_DIR が存在することを確認します（存在しない場合は作成します）。

4. 新しい状態を初期化する（再開しない場合）

   • schemas/state-schema.json で定義されたスキーマを使用して、新しい state.json を作成します。

進捗トラッカー

リアルタイムの進捗を表示します。

📊 Documentation Generation Progress v3.1
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Repository: {REPOSITORY_PATH}
Mode: {RESUME_MODE ? "Resume" : "New"}

{if RESUME_MODE}
Resuming from: {START_PHASE}
{end}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

エージェントパイプラインの実行

フェーズ 1：発見・分析エージェント

<phase_1_gate> ゲート：フェーズ 1 の開始 必須： 1 つのメッセージで 4 つのエージェントを起動します。 禁止： 順次呼び出し。 </phase_1_gate>

エージェント仕様：references/agent-discovery-analysis.md タスクスキーマ／設定：schemas/discovery-tasks.json

プロパティ	値
並列エージェント	4（1a-language、1b-components、1c-dependencies、1d-flows-apis）
重要	はい
出力	.octocode/documentation/{session-name}/analysis.json

実装の詳細については、references/agent-discovery-analysis.md の Orchestrator Execution Logic セクションを参照してください。

フェーズ 2：エンジニア質問エージェント

エージェント仕様：references/agent-engineer-questions.md

プロパティ	値
エージェントタイプ	単一（高性能な推論モデル）
重要	はい
入力	.octocode/documentation/{session-name}/analysis.json、schemas/documentation-structure.json
出力	.octocode/documentation/{session-name}/questions.json

実装の詳細については、references/agent-engineer-questions.md の Orchestrator Execution Logic セクションを参照してください。

フェーズ 3：リサーチエージェント 🆕

<phase_3_gate> ゲート：フェーズ 3 の開始 必須： 1 つのメッセージで N 個のエージェントを起動します。 禁止： 順次呼び出し。 </phase_3_gate>

エージェント仕様：references/agent-researcher.md

プロパティ	値
エージェントタイプ	並列（リサーチ対応の実行モデル）
重要	はい
入力	.octocode/documentation/{session-name}/analysis.json、.octocode/documentation/{session-name}/questions.json
出力	.octocode/documentation/{session-name}/research.json

実装の詳細については、references/agent-researcher.md の Orchestrator Execution Logic セクションを参照してください。

フェーズ 4：オーケストレーターエージェント

エージェント仕様：references/agent-orchestrator.md

プロパティ	値
エージェントタイプ	単一（高性能な推論モデル）
重要	はい
入力	.octocode/documentation/{session-name}/analysis.json、.octocode/documentation/{session-name}/questions.json、.octocode/documentation/{session-name}/research.json、schemas/documentation-structure.json
出力	.octocode/documentation/{session-name}/work-assignments.json

実装の詳細については、references/agent-orchestrator.md の Orchestrator Execution Logic セクションを参照してください。

フェーズ 5：ドキュメント作成者

<phase_5_gate> ゲート：フェーズ 5 を開始 必須： すべての作成者を1 つのメッセージで起動してください。 禁止： 順次呼び出し。 </phase_5_gate>

エージェント仕様：references/agent-documentation-writer.md

プロパティ	値
エージェントの種類	並列（文章作成が可能なエージェント 1～8 個）
重要な作成者	主要なコアファイル（01～08）の大部分を担当する作成者
非主要	部分的な失敗は許容
再試行ロジック	失敗した作成者ごとに最大 2 回再試行
入力	.octocode/documentation/{session-name}/analysis.json、.octocode/documentation/{session-name}/questions.json、.octocode/documentation/{session-name}/research.json、.octocode/documentation/{session-name}/work-assignments.json、schemas/documentation-structure.json
出力	documentation/*.md（コア 16 個、必須 5 個、および作成者が担当する補足ファイル。QA-SUMMARY.md はフェーズ 6 の出力）
ファイルの所有権	排他的（競合なし）

作成者の規模拡大戦略

戦略	エージェント数	使用する状況
sequential	1	質問数が 25 未満
parallel-core	2～4	質問数が 25～49
parallel-all	4～8	質問数が 50 以上

実装の詳細については、references/agent-documentation-writer.md の オーケストレーター実行ロジック セクションを参照してください。

フェーズ 6：QA 検証者

エージェント仕様：references/agent-qa-validator.md

プロパティ	値
エージェントの種類	単一（検証が可能なモデル）
重要性	なし（失敗すると警告を出力）
入力	.octocode/documentation/{session-name}/analysis.json、.octocode/documentation/{session-name}/questions.json、.octocode/documentation/{session-name}/research.json、documentation/*.md、schemas/documentation-structure.json
出力	.octocode/documentation/{session-name}/qa-results.json、documentation/QA-SUMMARY.md
スコア範囲	0～100
品質評価	excellent（≥90）、good（≥75）、fair（≥60）、needs-improvement（<60）

実装の詳細については、references/agent-qa-validator.md の オーケストレーター実行ロジック セクションを参照してください。

完了

update_state({
  phase: "complete",
  completed_at: new Date().toISOString(),
  current_agent: null
})

DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
DISPLAY: "✅ Documentation Complete!"
DISPLAY: ""
DISPLAY: "📁 Location: {DOC_DIR}/"
DISPLAY: "📊 QA Report: {DOC_DIR}/QA-SUMMARY.md"
DISPLAY: ""

if (parsed_qa && parsed_qa.overall_score):
  DISPLAY: "Quality Score: {parsed_qa.overall_score}/100 ({parsed_qa.quality_rating})"

  if (parsed_qa.overall_score >= 90):
    DISPLAY: "Status: Excellent ✅ - Ready for release"
  else if (parsed_qa.overall_score >= 75):
    DISPLAY: "Status: Good ✅ - Minor improvements recommended"
  else if (parsed_qa.overall_score >= 60):
    DISPLAY: "Status: Fair -️ - Address gaps before release"
  else:
    DISPLAY: "Status: Needs Work -️ - Major improvements required"

  if (parsed_qa.gaps && parsed_qa.gaps.length > 0):
    DISPLAY: ""
    DISPLAY: "Next Steps:"
    for (i = 0; i < Math.min(3, parsed_qa.gaps.length); i++):
      gap = parsed_qa.gaps[i]
      DISPLAY: "  {i+1}. {gap.fix}"

DISPLAY: ""
DISPLAY: "📝 Documentation Coverage:"
DISPLAY: "   {parsed_questions.summary.total_questions} questions researched"
DISPLAY: "   {parsed_qa.question_coverage.answered} questions answered in docs"
DISPLAY: ""
if (exists(DOC_DIR + "/index.md")):
  DISPLAY: "View documentation: {DOC_DIR}/index.md"
else:
  DISPLAY: "View documentation: {DOC_DIR}/01-project-overview.md"
DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

EXIT code 0

エラーからの復旧

エージェントが致命的なエラーで失敗した場合：

function handle_critical_failure(phase, error):
  DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  DISPLAY: "❌ Documentation Generation Failed"
  DISPLAY: ""
  DISPLAY: "Phase: {phase}"
  DISPLAY: "Error: {error.message}"
  DISPLAY: ""

  if (error.recoverable):
    DISPLAY: "This error is recoverable. Run /octocode-documentation-writer again to resume."
    DISPLAY: "State saved in: {CONTEXT_DIR}/state.json"
  else:
    DISPLAY: "This error is not recoverable. Please check the error and try again."
    DISPLAY: "You may need to fix the issue before retrying."

  DISPLAY: ""
  DISPLAY: "Logs: {CONTEXT_DIR}/state.json"
  DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"

  EXIT code 1

ヘルパー関数

重要：状態の同期 state.json を更新するのは、メインのオーケストレータープロセスのみです。個々の並列エージェント （Discovery 1A-1D、Researchers、Writers）は、競合状態を避けるため、state.json を直接変更しては なりません。並列エージェントは、フェーズ固有の契約パス（たとえば partial-1a-language.json や research-results/partial-research-0.json）を使用して、.octocode/documentation/{session-name}/ 内の 割り当てられた部分結果ファイルにのみ書き込んでください。オーケストレーターはこれらの結果を集約し、 すべての並列エージェントが完了した後に state.json を更新します。

// NOTE: This function should ONLY be called by the main orchestrator process,
// never by parallel sub-agents. Parallel agents use their designated partial-result path instead.
function update_state(updates):
  current_state = Read(CONTEXT_DIR + "/state.json")
  parsed = JSON.parse(current_state)

  for key, value in updates:
    parsed[key] = value

  Write(CONTEXT_DIR + "/state.json", JSON.stringify(parsed, null, 2))

function estimate_repo_size(path):
  // Quick estimate: count source files
  files = count_files(path, ["*.ts", "*.js", "*.py", "*.go", "*.rs", "*.java"], excludeDir=["node_modules", ".git", "dist", "build"])
  // Assume ~200 LOC per file average
  return files * 200

function count_files(path, patterns, excludeDir):
  // Use localFindFiles MCP tool (mcp__octocode__localFindFiles)
  // Return count of matching files

再試行とデータ保持のロジック

重要： 部分的な作業を決して失わないでください。すべてのエージェントは、状態を保持したまま再試行できます。

const RETRY_CONFIG = {
  discovery_analysis: { max_attempts: 3, backoff_ms: 2000 },
  engineer_questions: { max_attempts: 3, backoff_ms: 2000 },
  research:           { max_attempts: 3, backoff_ms: 3000 },
  orchestrator:       { max_attempts: 3, backoff_ms: 2000 },
  documentation:      { max_attempts: 3, backoff_ms: 5000 },  // per writer
  qa:                 { max_attempts: 2, backoff_ms: 1000 }
}

// === RETRY WRAPPER FOR ALL AGENTS ===
function retry_agent(phase_name, agent_fn, options = {}):
  config = RETRY_CONFIG[phase_name]
  state = get_retry_state(phase_name)

  while (state.attempts < config.max_attempts):
    state.attempts++
    update_retry_state(phase_name, state)

    DISPLAY: `⟳ ${phase_name} attempt ${state.attempts}/${config.max_attempts}`

    try:
      result = agent_fn(options)

      // Success - clear retry state
      clear_retry_state(phase_name)
      return { success: true, result }

    catch (error):
      state.last_error = error.message
      update_retry_state(phase_name, state)

      DISPLAY: `⚠️ ${phase_name} failed: ${error.message}`

      if (state.attempts < config.max_attempts):
        DISPLAY: `   Retrying in ${config.backoff_ms}ms...`
        sleep(config.backoff_ms * state.attempts)  // Exponential backoff
      else:
        DISPLAY: `❌ ${phase_name} exhausted all ${config.max_attempts} attempts`
        return { success: false, error, attempts: state.attempts }

  return { success: false, error: state.last_error, attempts: state.attempts }

// === PARALLEL AGENT RETRY (for Discovery, Research, Writers) ===
function retry_parallel_agents(phase_name, agent_tasks, options = {}):
  config = RETRY_CONFIG[phase_name]
  results = {}
  failed_tasks = []

  // First attempt - run all in parallel
  parallel_results = Task_Parallel(agent_tasks)

  for (task_id, result) in parallel_results:
    if (result.success):
      results[task_id] = result
      save_partial_result(phase_name, task_id, result)
    else:
      failed_tasks.push({ id: task_id, task: agent_tasks[task_id], attempts: 1 })

  // Retry failed tasks individually
  for failed in failed_tasks:
    while (failed.attempts < config.max_attempts):
      failed.attempts++
      DISPLAY: `⟳ Retrying ${phase_name}/${failed.id} (attempt ${failed.attempts}/${config.max_attempts})`

      try:
        result = Task(failed.task)
        if (result.success):
          results[failed.id] = result
          save_partial_result(phase_name, failed.id, result)
          break
      catch (error):
        DISPLAY: `⚠️ ${phase_name}/${failed.id} failed: ${error.message}`
        if (failed.attempts < config.max_attempts):
          sleep(config.backoff_ms * failed.attempts)

    if (failed.attempts >= config.max_attempts && !results[failed.id]):
      DISPLAY: `❌ ${phase_name}/${failed.id} failed after ${config.max_attempts} attempts`
      // Load any partial result saved during attempts
      results[failed.id] = load_partial_result(phase_name, failed.id) || { success: false, partial: true }

  return results

// === PARTIAL RESULT PRESERVATION ===
// Uses atomic writes to prevent corruption from concurrent access
function resolve_partial_result_path(phase_name, task_id):
  if (phase_name == "discovery-analysis"):
    discovery_paths = {
      "agent-1a-language": CONTEXT_DIR + "/partial-1a-language.json",
      "agent-1b-components": CONTEXT_DIR + "/partial-1b-components.json",
      "agent-1c-dependencies": CONTEXT_DIR + "/partial-1c-dependencies.json",
      "agent-1d-flows-apis": CONTEXT_DIR + "/partial-1d-flows-apis.json"
    }
    return discovery_paths[task_id] || (CONTEXT_DIR + "/partials/" + phase_name + "/" + task_id + ".json")

  if (phase_name == "research"):
    index = task_id.replace("researcher-", "")
    return CONTEXT_DIR + "/research-results/partial-research-" + index + ".json"

  return CONTEXT_DIR + "/partials/" + phase_name + "/" + task_id + ".json"

function save_partial_result(phase_name, task_id, result):
  target_path = resolve_partial_result_path(phase_name, task_id)
  partial_dir = dirname(target_path)
  mkdir_p(partial_dir)
  temp_path = target_path + ".tmp." + random_uuid()

  // Atomic write: write to temp file, then rename (rename is atomic on POSIX)
  Write(temp_path, JSON.stringify(result))
  rename(temp_path, target_path)  // Atomic operation

function load_partial_result(phase_name, task_id):
  path = resolve_partial_result_path(phase_name, task_id)
  if (exists(path)):
    return JSON.parse(Read(path))
  return null

function load_all_partial_results(phase_name):
  partial_dir = CONTEXT_DIR + "/partials/" + phase_name
  if (!exists(partial_dir)):
    return {}
  files = list_files(partial_dir, "*.json")
  results = {}
  for file in files:
    task_id = file.replace(".json", "")
    results[task_id] = JSON.parse(Read(partial_dir + "/" + file))
  return results

// === RETRY STATE MANAGEMENT ===
function get_retry_state(phase_name):
  state = Read(CONTEXT_DIR + "/state.json")
  parsed = JSON.parse(state)
  return parsed.retry_state?.[phase_name] || { attempts: 0 }

function update_retry_state(phase_name, retry_state):
  update_state({
    retry_state: {
      ...current_state.retry_state,
      [phase_name]: retry_state
    }
  })

function clear_retry_state(phase_name):
  state = JSON.parse(Read(CONTEXT_DIR + "/state.json"))
  if (state.retry_state):
    delete state.retry_state[phase_name]
    Write(CONTEXT_DIR + "/state.json", JSON.stringify(state, null, 2))

フェーズ固有の再試行動作

フェーズ	再試行戦略	保持される部分データ
Discovery	失敗したサブエージェント（1A～1D）のみを個別に再試行	partials/discovery/*.json
Questions	フェーズ全体を再試行	成功するまで以前の questions.json を保持
Research	失敗したバッチのみを再試行	partials/research/batch-*.json
Orchestrator	フェーズ全体を再試行	以前の work-assignments.json を保持
Writers	失敗した作成者のみを再試行	partials/writers/writer-*.json と完了済みファイル
QA	1 回再試行し、その後警告	partials/qa/partial-results.json

重要なデータ保護ルール

// RULE 1: Never overwrite successful output until new output is validated
function safe_write_output(path, content):
  backup_path = path + ".backup"
  if (exists(path)):
    copy(path, backup_path)

  try:
    Write(path, content)
    validate_json(path)  // Ensure valid JSON
    delete(backup_path)  // Only delete backup after validation
  catch (error):
    // Restore from backup
    if (exists(backup_path)):
      copy(backup_path, path)
    throw error

// RULE 2: Aggregate partial results even on failure
// Uses file locking to prevent race conditions during aggregation
function aggregate_with_partials(phase_name, new_results):
  lock_file = CONTEXT_DIR + "/partials/" + phase_name + "/.aggregate.lock"

  // Acquire exclusive lock before aggregation
  lock_fd = acquire_file_lock(lock_file, timeout_ms=5000)
  if (!lock_fd):
    throw new Error("Failed to acquire lock for aggregation: " + phase_name)

  try:
    existing = load_all_partial_results(phase_name)
    merged = { ...existing, ...new_results }
    return merged
  finally:
    release_file_lock(lock_fd)
    delete(lock_file)

// RULE 3: Resume-aware execution
function should_skip_task(phase_name, task_id):
  partial = load_partial_result(phase_name, task_id)
  return partial?.success === true

---

主な機能

<key_features>

#	機能	説明
1	ホスト対応の並列実行	フェーズ 1、3、5 では、サポートされている場合は真の並列ファンアウトを使用し、サポートされていない場合は逐次実行にフォールバックします
2	誠実な並行処理	並列実行を優先しますが、スキルが逐次処理を並行処理であるかのように装うことはありません
3	エビデンスに基づく	リサーチエージェントは、回答を書く前にコードの追跡によって内容を証明します
4	エンジニア主導の質問	フェーズ 2 では、包括的な質問を生成します
5	競合のない執筆	オーケストレーターは、各ライターに排他的なファイル所有権を割り当てます
6	LSP を活用	セマンティック分析によるインテリジェントな検証を行います
7	状態の復旧	中断された場合、どのフェーズからでも再開できます
8	統合ツールセット	すべてのエージェントが octocode ローカルツールと LSP ツールを使用します
9	動的なスケーリング	エージェント数は質問の量に応じて拡張します

</key_features>

<efficiency_summary>

効率の最大化

Phase 1: 4 agents × parallel = ~4x faster than sequential
Phase 3: N agents × parallel = ~Nx faster than sequential
Phase 5: M agents × parallel = ~Mx faster than sequential

Total speedup: Significant when host parallelism is available

覚えておいてください：ホストがサポートする最も強力なファンアウトを使用してください。真の並列処理が利用できない場合は、逐次実行にフォールバックし、同じ所有権の境界を維持してください。 </efficiency_summary>

---