claude-code-conductor 0.3.0__tar.gz → 0.3.1__tar.gz

{claude_code_conductor-0.3.0 → claude_code_conductor-0.3.1}/.claude/agents/planner.md

@@ -79,6 +79,42 @@ plan-report の YAML フロントマターは `parallel-orchestra` (PO) で並
 - [ ] 同じファイルを書く複数タスクで衝突対策が取られているか
 - [ ] レビュータスク（read_only:true）が全 dev タスクに depends_on を持っているか
 - [ ] `tasks[].id` が一意で、`depends_on` の参照先が全て存在するか
+- [ ] `depends_on` を空配列（`[]`）で書いていないか（無依存ならフィールド自体を省略）
+
+### タスクあたりの所要時間制約
+
+PO は内部で **タスクごとのタイムアウトを 900 秒（15 分）でハードコード** している（`_INTERNAL_TIMEOUT_SEC = 900`、フロントマター側からは上書き不可）。1 タスクが 15 分を超えると PO 側で kill されて failure 扱いになる。
+
+11. **1 タスクは 15 分以内に終わる粒度で分解する** — `tdd-develop` の tester→developer→tester ループでも 15 分を上限の目安にする。長くなりそうな機能は (a) ファイル境界でタスク分割、(b) MVP と機能拡張で別タスク化、のいずれかで時間を切る
+- 自己チェックリストに追加: `[ ] 想定実行時間が 15 分を超えるタスクがないか`
+
+### YAML フロントマターの落とし穴
+
+実装時に踏みやすい入力ミス。dry-run で検出できるが、出力前に planner 側で潰しておく:
+
+9. **`depends_on: []` を空配列で書かない** — `c3 po dry-run` が「`depends_on` must be a list of strings」で fail する（非空のときだけ list として扱われ、空配列は仕様違反扱い）。依存が無いタスクは `depends_on` フィールド**自体を省略**する
+10. **`writes` の重複は dry-run の `Write-path conflict` で検出される** — 同じファイルを書くタスクが複数あれば必ず (a) タスクをまとめる、(b) `depends_on` で順序付け、(c) `concurrency_group` で同時実行を 1 に制限、のいずれかで解消する（既存ルール 8 の補足。dry-run が落ちるので出力前に必ず確認する）
+
+### 直列・並列交互パターンの取り扱い
+
+ユーザーが **stage 単位で順序を強制したい / 中間状態を確認したい** と要求した場合は、ルール 1（「真の依存だけに絞る」）から逸脱して順序付けの `depends_on` を許容してよい。典型構造:
+
+```
+Stage 1: dev_a, dev_b, dev_c (並列)
+  └─ Stage 2: review_or_sync (依存: dev_a/b/c) ← 中間レビュー / 集約
+      └─ Stage 3: dev_d, dev_e (並列、依存: review_or_sync)
+          └─ Stage 4: review_or_sync_2 (依存: dev_d/e)
+              └─ ...
+```
+
+採用条件:
+
+- ユーザーが明示的に要求している（自己判断で勝手にこの形にしない）
+- 各 stage 内の並列度は **2 以上**を維持する（直列に潰してはいけない）
+- ルール 2（直列化セルフチェック: チェーン長 ≦ タスク数 / 2）は依然として守る
+- 「stage 区切り」自体は plan-report 本文で明文化し、`depends_on` だけに頼らない
+
+詳細な構造例は `.claude/docs/parallel-orchestra-manifest.md` の「並列・直列交互パターン」を参照。
 
 ## Tools & Constraints
 制限:

{claude_code_conductor-0.3.0 → claude_code_conductor-0.3.1}/.claude/docs/parallel-orchestra-manifest.md

@@ -115,6 +115,46 @@ on_failure:
 
 ---
 
+## 並列・直列交互パターン
+
+中間レビューや段階的な動作確認を挟みたい場合の plan-report 構造。stage 内では並列、stage 間は順序を強制する形を取る。C3 の wave-execution でも各 stage 完了後にユーザー承認が入るので、ヒューマン・イン・ザ・ループ前提の中規模実装で有効。
+
+### 用途
+
+- 段階的にユーザー確認・中間レビューを挟みたい
+- 実装ステージごとに動作確認が必要（例: 認証 → 認可 → 監査ログ、と段階的に積み上げる）
+- 後続の dev タスクが前段のレビュー指摘を受けて方針調整する可能性がある
+
+### 構造
+
+```
+Stage 1: dev_a, dev_b, dev_c (並列)
+  └─ Stage 2: review_or_sync (依存: dev_a / dev_b / dev_c)  ← 中間レビュー / 集約
+      └─ Stage 3: dev_d, dev_e (並列、依存: review_or_sync)
+          └─ Stage 4: review_or_sync_2 (依存: dev_d / dev_e)
+              └─ ...
+```
+
+特徴:
+
+- 各 stage 内は **2 件以上の独立タスク**で並列度を維持する
+- stage を区切る `review_or_sync` タスクは `code-reviewer`（read_only: true）か、軽い同期目的のサマライズタスク
+- 中間レビュータスクが次 stage の dev タスクに `depends_on` で繋がる → **stage 間は完全に直列**
+
+### 動作実績
+
+17 tasks / 7 stages 構成（3〜4 並列の dev stage と 1 件の review stage が交互）で動作確認済み。各 stage が wave 1 つに対応し、wave-execution.md の per-wave 承認フローに綺麗に乗る。
+
+### 採用条件（planner 側のルール）
+
+- ユーザーが明示的に要求している（自動でこの形にしない）
+- 各 stage 内の並列度は **2 以上**を維持する（直列に潰さない）
+- 全体のチェーン長 ≦ タスク数 / 2 を依然として守る
+
+詳細は `.claude/agents/planner.md` の「直列・並列交互パターンの取り扱い」を参照。
+
+---
+
 ## アンチパターン（避けるべき書き方）
 
 ### A. 全部直列にしてしまう

{claude_code_conductor-0.3.0 → claude_code_conductor-0.3.1}/.claude/skills/wave-execution.md

@@ -17,6 +17,41 @@ C3 の親 Claude が plan-report の DAG を **wave 単位**で歩く。
 
 ---
 
+## Step 0-pre: ワーキングツリーの事前確認
+
+PO は worktree からの auto-merge で main に成果物を取り込む仕様で、**main 側に未コミット変更や untracked ファイルがあると、worktree が同名ファイルを再生成して必ず衝突する**。実行前に `git status` でクリーンであることを確認する。
+
+1. Bash で `git status --short` を実行する
+2. stdout が空（クリーン）→ Step 0 へ
+3. クリーンでない場合:
+   - 検出された変更ファイルをユーザーに提示する
+   - AskUserQuestion で次を確認する:
+
+     ```json
+     {
+       "questions": [{
+         "question": "PO 実行前に main がクリーンである必要があります。どうしますか？",
+         "options": [
+           { "label": "コミットしてから続行", "description": "親 Claude が変更内容を確認してコミットしてから wave 実行に進む" },
+           { "label": "stash してから続行", "description": "git stash で退避してから wave 実行に進む。完了後に stash pop するかは別途判断" },
+           { "label": "キャンセル", "description": "wave 実行を中止し、ユーザーが自分で整理してから /develop を再実行する" }
+         ]
+       }]
+     }
+     ```
+
+   - 「コミットしてから続行」→ 親 Claude が `git status` / `git diff` を見て妥当な単位でコミットしてから Step 0 へ
+   - 「stash してから続行」→ Bash で `git stash push -u -m "wave-execution pre-clean"` を実行してから Step 0 へ
+   - 「キャンセル」→ スキル終了
+
+**特に注意すべきファイル:**
+
+- `.claude/settings.local.json` — Claude Code が permission 自動追加で勝手に更新する。気付かないうちに dirty になっているケースが多い
+- `package.json` / `vitest.config.js` 等の事前準備（W0）ファイル — 未コミットで PO に入ると worktree でも同ファイルが書き換わって必ず衝突する
+- `.claude/reports/` 配下の中間生成物
+
+---
+
 ## Step 0: 妥当性チェック
 
 1. Glob で `.claude/reports/plan-report-*.md` の最新ファイルパスを取得する
@@ -131,8 +166,11 @@ AskUserQuestion ツール:
 1. Agent ツールで `subagent_type` は指定せず（カスタム agent は subagent_type 不可）、プロンプトに以下を含める:
    - 「`.claude/agents/{agent_name}.md` を Read してペルソナを採用すること」
    - タスクの `prompt` 本文
+   - **「git add / git commit / git push を実行しないこと。コミットは親 Claude がユーザー承認後に行う」を明示**
 2. Agent の返答を 2-D の集約に渡す
 
+**git 禁止ルールの根拠:** 動作確認で developer が独断コミットして Red テストや test-report が untracked のまま実装ファイルだけが main に入る事故が起きた。コミット粒度・承認タイミング・成果物の取りこぼしは親 Claude が一元管理する責務。
+
 ##### 将来 agent を追加する場合
 
 「内部で更に subagent を呼ぶ agent」を新たに作る場合は、A-1 のペルソナ採用パターン側に追加する。判断基準: その agent の定義ファイルが「内部で Agent ツールを使う」前提になっているか。tdd-develop が現状の唯一の例。
@@ -156,12 +194,28 @@ c3 po run-wave <plan-report-path> --wave-index {N} --report .claude/reports/po-r
 | exit code | 意味 | 次のアクション |
 |---|---|---|
 | `0` | wave 内全タスク成功 | 2-D へ |
-| `1` | 1件以上のタスクが失敗 | 2-D へ（失敗一覧を含めて提示） |
+| `1` | 1件以上のタスクが失敗 | 2-D へ（失敗一覧を含めて提示）。**注:** PO は 1 タスクあたり 15 分（`_INTERNAL_TIMEOUT_SEC = 900`、ハードコード上書き不可）でタイムアウトする。15 分超で failure 扱いになっていれば planner の粒度を見直す |
 | `2` | マニフェストエラー（Step 0 をすり抜けた）| エラー内容を提示しスキル終了 |
-| `3` | runner エラー（claude バイナリ不在等）| `c3 doctor` の結果を提示してスキル終了 |
+| `3` | auto-merge 衝突（worktree → main の取り込みに失敗）| 下記「auto-merge が衝突した場合」のリカバリ手順へ |
 
 実行完了後、生成された `po-run-report-wave-{N}-{ts}.json` を Read してタスクごとのステータスを取得する。
 
+##### auto-merge が衝突した場合（exit code 3）
+
+PO は worktree でタスクを実行したあと main に auto-merge する。Step 0-pre をすり抜けて main にダーティな状態が残っていたり、複数 worktree が同じ周辺ファイル（CLAUDE.md / settings.local.json 等）を触っていると衝突する。selective checkout でコア成果物だけ救う:
+
+1. 残っている PO ブランチを列挙する: `git branch --list "parallel-orchestra/*"`
+2. 各ブランチを個別に確認する: `git log --stat parallel-orchestra/<task>-<hash>`
+3. **コア成果物のみ**を抽出する: `git checkout parallel-orchestra/<task>-<hash> -- <files>`
+   - 取り込むのはタスクの `writes` フィールドに列挙されたファイルのみ
+   - **取り込まない**: worktree が touch したが本タスクの責務でない周辺ファイル
+     - `CLAUDE.md` / `package.json` / `vitest.config.js` 等の事前準備系ファイル
+     - `.claude/settings.local.json`（permission 自動追加で worktree 側でも更新されている）
+     - `.claude/reports/` 配下の中間生成物
+4. PO ブランチを削除する: `git branch -D parallel-orchestra/<task>-<hash>` を全ブランチに対して実行
+5. 抽出した成果物 + 既存の main 変更分を親 Claude が確認のうえコミットする
+6. `git status --short` で main がクリーンになったことを確認してから次の wave に進む
+
 ### 2-D: 結果を集約してユーザーに提示する
 
 ランナー種別ごとに以下の形式で結果を提示する。
@@ -203,6 +257,8 @@ case A で TDD ループが不合格のまま終わった、または case B で
 
 全タスク成功した wave のみ、セッションファイルの `- [ ] Wave {N} (M tasks)` を `- [x] Wave {N} (M tasks)` に Edit する。
 
+**次の wave に進む前に main をコミットしてクリーンに保つ。** wave 成果物を未コミットのまま次の wave で PO に入ると、worktree が同名ファイルを再生成して必ず auto-merge 衝突が起きる（Step 0-pre と同じ理由）。親 Claude が wave の成果物を確認のうえ「Wave {N}: {要約}」のメッセージでコミットしてから 2-A の次のループに戻る。
+
 ---
 
 ## Step 3: フェーズ E への遷移

{claude_code_conductor-0.3.0 → claude_code_conductor-0.3.1}/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## [0.3.1] - 2026-05-01
+
+### Docs
+- Operational rules captured from a 17-tasks / 7-stages C3+PO verification
+  run in `c3_pip_test`:
+  - `.claude/skills/wave-execution.md`: new **Step 0-pre** that requires a
+    clean working tree before invoking PO (PO's auto-merge re-creates
+    same-named files in worktrees and conflicts on dirty main — most
+    commonly via `.claude/settings.local.json`, which Claude Code auto-edits
+    when granting permissions). Adds an explicit **"do not git
+    add/commit/push"** rule to case A-2 Agent-tool prompts (a developer
+    sub-agent was committing implementation files while leaving Red tests
+    and test-reports untracked). Adds an **auto-merge conflict (exit code
+    3) recovery** sub-section under case B with a selective-checkout
+    procedure that rescues only declared `writes` and discards worktree-
+    side edits to surrounding files. Adds a per-wave commit reminder under
+    Step 2-F. Notes PO's hardcoded 15-minute per-task timeout
+    (`_INTERNAL_TIMEOUT_SEC = 900`, no manifest-level override) so the
+    parent Claude can route exit-code-1 timeouts back to planner sizing
+    rather than agent debugging.
+  - `.claude/agents/planner.md`: documents the `depends_on: []` pitfall
+    (`c3 po dry-run` rejects empty arrays — omit the field instead) and
+    the `writes` collision detection. Adds a per-task time budget rule
+    (≤15 min, matching PO's internal timeout) with a self-check item.
+    Adds an **"alternating parallel/serial pattern"** section that
+    authorises ordering `depends_on` between stages when the user
+    explicitly wants intermediate review/sync points, while preserving
+    in-stage parallelism ≥ 2.
+  - `.claude/docs/parallel-orchestra-manifest.md`: adds an "alternating
+    parallel/serial pattern" section describing the structure with a
+    pointer to the planner rule.
+
+No code changes — `c3 update` after `pip install -U claude-code-conductor`
+brings these into existing projects.
+
 ## [0.3.0] - 2026-04-30
 
 ### Changed (breaking)

{claude_code_conductor-0.3.0 → claude_code_conductor-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-code-conductor
-Version: 0.3.0
+Version: 0.3.1
 Summary: Multi-agent orchestration framework for Claude Code (C3)
 Project-URL: Homepage, https://github.com/satoh-y-0323/claude-code-conductor
 Project-URL: Repository, https://github.com/satoh-y-0323/claude-code-conductor

{claude_code_conductor-0.3.0 → claude_code_conductor-0.3.1}/src/c3/__init__.py

@@ -1,3 +1,3 @@
 """Claude Code Conductor (C3) - multi-agent orchestration framework for Claude Code."""
 
-__version__ = "0.3.0"
+__version__ = "0.3.1"