ensemble-claude 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

ensemble/issue_provider.py

@@ -0,0 +1,97 @@
+"""Abstract base class for issue providers (GitHub, GitLab, etc.)."""
+
+import re
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass
+class Issue:
+    """Represents an issue from a code hosting platform."""
+
+    number: int
+    title: str
+    body: str
+    url: str
+    state: str
+    labels: list[str]
+
+    def branch_slug(self, max_length: int = 50) -> str:
+        """Generate a git branch name slug from the issue.
+
+        Format: issue/<number>-<slugified-title>
+
+        Args:
+            max_length: Maximum length of the slug portion (excluding prefix).
+
+        Returns:
+            A valid git branch name.
+        """
+        # Convert title to lowercase
+        slug = self.title.lower()
+
+        # Replace special characters with spaces
+        slug = re.sub(r"[^a-z0-9\s-]", "", slug)
+
+        # Replace whitespace with hyphens
+        slug = re.sub(r"\s+", "-", slug)
+
+        # Remove consecutive hyphens
+        slug = re.sub(r"-+", "-", slug)
+
+        # Trim hyphens from ends
+        slug = slug.strip("-")
+
+        # Truncate to max length
+        if len(slug) > max_length:
+            # Try to cut at a word boundary
+            slug = slug[:max_length].rsplit("-", 1)[0]
+
+        return f"issue/{self.number}-{slug}"
+
+
+class IssueProvider(ABC):
+    """Abstract base class for issue providers.
+
+    Implementations should handle specific platforms like GitHub, GitLab, etc.
+    """
+
+    @abstractmethod
+    def list_issues(self, state: str = "open") -> list[Issue]:
+        """List issues in the repository.
+
+        Args:
+            state: Filter by issue state ('open', 'closed', 'all').
+
+        Returns:
+            List of Issue objects.
+
+        Raises:
+            RuntimeError: If the operation fails.
+        """
+        pass
+
+    @abstractmethod
+    def get_issue(self, identifier: str) -> Issue:
+        """Get a specific issue by number or URL.
+
+        Args:
+            identifier: Issue number (as string) or full URL.
+
+        Returns:
+            Issue object.
+
+        Raises:
+            ValueError: If the issue is not found.
+            RuntimeError: If the operation fails.
+        """
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if the provider's CLI tool is available.
+
+        Returns:
+            True if the CLI tool is installed and accessible.
+        """
+        pass

ensemble/providers/__init__.py

@@ -0,0 +1,5 @@
+"""Issue providers for different code hosting platforms."""
+
+from ensemble.providers.github import GitHubProvider
+
+__all__ = ["GitHubProvider"]

ensemble/providers/github.py

@@ -0,0 +1,103 @@
+"""GitHub issue provider using gh CLI."""
+
+import json
+import shutil
+import subprocess
+from typing import Any
+
+from ensemble.issue_provider import Issue, IssueProvider
+
+
+class GitHubProvider(IssueProvider):
+    """Issue provider for GitHub using the gh CLI."""
+
+    def is_available(self) -> bool:
+        """Check if gh CLI is installed.
+
+        Returns:
+            True if gh is available in PATH.
+        """
+        return shutil.which("gh") is not None
+
+    def list_issues(self, state: str = "open") -> list[Issue]:
+        """List issues using gh CLI.
+
+        Args:
+            state: Filter by issue state ('open', 'closed', 'all').
+
+        Returns:
+            List of Issue objects.
+
+        Raises:
+            RuntimeError: If gh command fails.
+        """
+        cmd = [
+            "gh", "issue", "list",
+            "--state", state,
+            "--json", "number,title,body,url,state,labels",
+        ]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to list issues: {result.stderr}")
+
+        data = json.loads(result.stdout)
+        return [self._parse_issue(item) for item in data]
+
+    def get_issue(self, identifier: str) -> Issue:
+        """Get a specific issue by number or URL.
+
+        Args:
+            identifier: Issue number (as string) or full URL.
+
+        Returns:
+            Issue object.
+
+        Raises:
+            ValueError: If the issue is not found.
+            RuntimeError: If gh command fails.
+        """
+        cmd = [
+            "gh", "issue", "view", identifier,
+            "--json", "number,title,body,url,state,labels",
+        ]
+
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+        )
+
+        if result.returncode != 0:
+            if "not found" in result.stderr.lower() or "could not find" in result.stderr.lower():
+                raise ValueError(f"Issue not found: {identifier}")
+            raise RuntimeError(f"Failed to get issue: {result.stderr}")
+
+        data = json.loads(result.stdout)
+        return self._parse_issue(data)
+
+    def _parse_issue(self, data: dict[str, Any]) -> Issue:
+        """Parse issue data from gh JSON output.
+
+        Args:
+            data: Dictionary from gh JSON output.
+
+        Returns:
+            Issue object.
+        """
+        # Labels come as list of dicts with 'name' key
+        labels = [label["name"] for label in data.get("labels", [])]
+
+        return Issue(
+            number=data["number"],
+            title=data["title"],
+            body=data.get("body", ""),
+            url=data["url"],
+            state=data["state"].lower(),
+            labels=labels,
+        )

ensemble/templates/agents/conductor.md

@@ -45,14 +45,15 @@ model: opus
 
 ## パターン別実行方法
 
-### パターンA: takt方式（subagent直接）
+### パターンA: 単一Worker実行
 
-Taskツールでsubagentを起動して直接実行する。Dispatchは不要。
+軽量タスクでもDispatch経由で実行する。Conductorは計画・判断・委譲のみ。
 
 ```
-1. Task(subagent_type="general-purpose")でタスク実行
-2. 結果を確認
-3. 必要に応じてレビュー
+1. queue/conductor/dispatch-instruction.yaml に指示を書く
+2. worker_count: 1 で単一Workerを指定
+3. Dispatchに通知し、Workerが実行
+4. 完了報告を待機
 ```
 
 ### パターンB: shogun方式（tmux並列）
@@ -201,13 +202,25 @@ Claude Max 5並列制限を考慮:
 |---------|--------|-----------|
 | `/go` または タスク依頼 | ユーザー | 計画立案・パターン選択・実行 |
 
-### 完了確認方法（Dispatchからのsend-keysは来ない）
+### 完了確認方法（ポーリング）
 
-Dispatchはsend-keysでConductorに報告しない。以下の方法で完了を確認:
-1. `status/dashboard.md` を定期的に確認
-2. `queue/reports/` にファイルが揃ったら完了
+Dispatchへの委譲後、以下のポーリング処理を実行:
 
-これにより、send-keysの信頼性問題を回避する。
+```bash
+# 完了待機ループ（30秒間隔、最大30分）
+for i in $(seq 1 60); do
+  if [ -f "queue/reports/completion-summary.yaml" ]; then
+    echo "タスク完了を検知"
+    break
+  fi
+  sleep 30
+done
+```
+
+完了検知後:
+1. `queue/reports/completion-summary.yaml` を読み込む
+2. 結果をユーザーに報告
+3. completion-summary.yaml を削除（次回の検知のため）
 
 ## 自律判断チェックリスト
 
@@ -227,6 +240,47 @@ Dispatchはsend-keysでConductorに報告しない。以下の方法で完了を
 - [ ] 未完了タスクの棚卸し
 - [ ] queue/ 内の古いファイル削除
 
+## セッション構成
+
+Ensembleは2つの独立したtmuxセッションで動作する:
+
+```
+セッション1: ensemble-conductor
++------------------+------------------+
+|   Conductor      |   dashboard      |
++------------------+------------------+
+
+セッション2: ensemble-workers
++------------------+----------+
+|                  | worker-1 |
+|   dispatch       +----------+
+|                  | worker-2 |
++------------------+----------+
+```
+
+### 2つのターミナルで同時表示
+
+別々のターミナルウィンドウで各セッションをアタッチすることで、
+Conductor（+dashboard）とWorkers（dispatch+workers）両方を同時に監視できる:
+
+```bash
+# ターミナル1
+tmux attach -t ensemble-conductor
+
+# ターミナル2
+tmux attach -t ensemble-workers
+```
+
+### セッション間通信
+
+セッションが分かれていてもsend-keysで通信可能:
+
+```bash
+source .ensemble/panes.env
+tmux send-keys -t "$CONDUCTOR_PANE" 'message' Enter
+tmux send-keys -t "$DISPATCH_PANE" 'message' Enter
+```
+
 ## 禁止事項
 
 - 自分でコードを書く

ensemble/templates/agents/dispatch.md

@@ -78,13 +78,35 @@ ls queue/reports/*.yaml
 ```
 通信ロストした他ワーカーの報告も拾える。
 
-## Conductor への報告方法（send-keys禁止）
+## Conductor への報告方法（ファイルベース + 通知）
 
-**Conductorにsend-keysを送ってはならない**。結果は以下の方法で報告:
-1. `status/dashboard.md` を更新（全タスク完了時）
-2. `queue/reports/` に報告ファイルを配置
+### 1. ファイル報告（プライマリ）
+**Conductorにsend-keysを送らない**。結果はファイルで報告:
+1. `status/dashboard.md` を更新（完了ステータスに）
+2. `queue/reports/completion-summary.yaml` に集約結果を記載
 
-Conductorは自分でダッシュボードまたはファイル監視で状況を把握する。
+### 2. 通知（セカンダリ）
+completion-summary.yaml作成後、Conductorに完了を通知:
+
+#### 通知手順
+```bash
+# panes.envを読み込む
+source .ensemble/panes.env
+
+# Conductorに通知（2回分割）
+tmux send-keys -t "$CONDUCTOR_PANE" '全タスク完了。queue/reports/completion-summary.yamlを確認してください'
+sleep 1
+tmux send-keys -t "$CONDUCTOR_PANE" Enter
+```
+
+#### 通知失敗時
+- send-keysが失敗してもエラーにしない
+- Conductorがポーリングでフォールバック
+- ファイル報告が最優先（通知は補助）
+
+### 3. ポーリング（フォールバック）
+Conductorは `queue/reports/completion-summary.yaml` の存在を検知して完了を把握する。
+通知は効率化のための補助機能。
 
 ---
 
@@ -155,22 +177,46 @@ workflow: default
 pattern: B
 ```
 
-## ペイン構成
+## ウィンドウ・ペイン構成
+
+Ensembleは2ウィンドウ構成で動作する:
+
+```
+ウィンドウ1: conductor（Conductorがいる場所）
++----------------------------------+
+|           Conductor              |
++----------------------------------+
+
+ウィンドウ2: workers（あなたがいる場所）
++------------------+----------+
+|    dispatch      | worker-1 |
+|    (あなた)      +----------+
++------------------+ worker-2 |
+|    dashboard     +----------+
+|                  | ...      |
++------------------+----------+
+```
 
 ペイン番号ではなくペインIDで管理する。`.ensemble/panes.env` を参照。
 
 ```
+ウィンドウ名:
+  $CONDUCTOR_WINDOW: conductor
+  $WORKERS_WINDOW: workers
+
 初期状態:
-  $CONDUCTOR_PANE: Conductor
+  $CONDUCTOR_PANE: Conductor（別ウィンドウ）
   $DISPATCH_PANE: Dispatch（自分）
   $DASHBOARD_PANE: Dashboard
+  $WORKER_AREA_PANE: ワーカー用プレースホルダー
 
 ワーカー追加後（例: 2ワーカー）:
-  $CONDUCTOR_PANE: Conductor
+  $CONDUCTOR_PANE: Conductor（別ウィンドウ）
   $DISPATCH_PANE: Dispatch（自分）
+  $DASHBOARD_PANE: Dashboard
   $WORKER_1_PANE: Worker-1 (WORKER_ID=1)
   $WORKER_2_PANE: Worker-2 (WORKER_ID=2)
-  $DASHBOARD_PANE: Dashboard
+  $WORKER_COUNT: 2
 ```
 
 ## タスク配信の具体手順
@@ -218,13 +264,39 @@ done
 
 ## 完了報告の収集
 
+### プライマリ: 通知ベース
+Workerから「タスク${TASK_ID}完了」の通知を受けたら、
+queue/reports/${TASK_ID}-completed.yaml を確認する。
+
+### フォールバック: ポーリング
+タイムアウト（例: 3分）後、Workerから通知がない場合:
+1. queue/reports/ を全スキャン
+2. 新しい完了報告ファイルを検出
+3. 未検出のタスクは「進行中」と判断し、追加で2分待機
+4. 再度タイムアウト → エスカレーション
+
+### 実装例
 ```bash
-# 完了報告の確認
-ls queue/reports/*.yaml
+# タイムアウト後のスキャン
+echo "⏰ タイムアウト。完了報告をスキャン中..."
+ls queue/reports/*.yaml | grep -v escalation | grep -v completion-summary
+
+# 各タスクの完了状態を確認
+for task_id in task-001 task-002 ...; do
+  if [ -f "queue/reports/${task_id}-completed.yaml" ]; then
+    echo "✅ ${task_id}: 完了済み（通知なしで検出）"
+  else
+    echo "⏳ ${task_id}: 未完了"
+  fi
+done
+```
 
-# 報告内容の読み取り
-cat queue/reports/${TASK_ID}.yaml
+### 報告の全確認原則（既存ルールを強調）
+Workerから起こされたら、起こした1人だけでなく**全ワーカーの報告ファイルをスキャン**:
+```bash
+ls queue/reports/*.yaml
 ```
+通信ロストした他ワーカーの報告も拾える。
 
 ## 完了判定と報告フロー
 
@@ -232,8 +304,11 @@ cat queue/reports/${TASK_ID}.yaml
 1. Workerから「タスク${TASK_ID}完了」の通知を受ける
 2. queue/reports/${TASK_ID}.yaml を確認
 3. 全タスクの完了を待つ
-4. 結果を集約してstatus/dashboard.mdを更新（Conductorへのsend-keys禁止）
+4. 結果を集約:
+   - status/dashboard.md を「完了」に更新
+   - queue/reports/completion-summary.yaml を作成（Conductorがポーリングで検知）
 5. queue/conductor/dispatch-instruction.yaml を削除（処理済み）
+6. 「待機中」と表示して次の指示を待つ
 ```
 
 ## 結果集約フォーマット
@@ -340,6 +415,45 @@ worker_id と executed_by が不一致の場合:
 - [ ] ワーカーが異常終了した
 - [ ] 指示ファイルのフォーマットが不正
 
+## /clear プロトコル（Worker コンテキスト管理）
+
+Workerのコンテキスト蓄積を防ぐため、タスク完了後に `/clear` を送信する。
+
+### いつ /clear を送るか
+- **タスク完了報告受信後、次タスク割当前** に送る
+- Worker完了報告 → dashboard更新 → **/clear送信** → 次タスク指示
+
+### /clear 送信手順
+```bash
+# 1. 次タスクYAMLを先に書き込む（Worker復帰後にすぐ読めるように）
+# queue/tasks/worker-{N}-task.yaml に次タスクを書く
+
+# 2. /clear を send-keys で送る
+source .ensemble/panes.env
+tmux send-keys -t "$WORKER_{N}_PANE" '/clear'
+sleep 1
+tmux send-keys -t "$WORKER_{N}_PANE" Enter
+
+# 3. Worker復帰を待つ（約5秒）
+sleep 5
+
+# 4. タスク読み込み指示を送る
+tmux send-keys -t "$WORKER_{N}_PANE" 'queue/tasks/にタスクがあります。確認して実行してください。'
+sleep 1
+tmux send-keys -t "$WORKER_{N}_PANE" Enter
+```
+
+### /clear をスキップする場合
+以下の条件ではスキップ可:
+- 短タスク連続（推定5分以内）
+- 同一ファイル群の連続タスク
+- Workerのコンテキストがまだ軽量（タスク2件目以内）
+
+### Conductor / Dispatch は /clear しない
+- **Dispatch**: 全Worker状態を把握する必要がある
+- **Conductor**: プロジェクト全体像・計画を維持する必要がある
+- コンテキスト逼迫時は `/compact` を自己判断で実行
+
 ## 禁止事項
 
 - タスクの内容を判断する

ensemble/templates/agents/worker.md

@@ -115,6 +115,31 @@ errors: []  # エラーがあれば記載
 completed_at: "2026-02-03T10:30:00Z"
 ```
 
+## 完了報告後の通知プロトコル
+
+完了報告ファイル（queue/reports/task-XXX-completed.yaml）を作成した後、
+必ずDispatchペインに通知せよ:
+
+### 通知手順
+1. panes.envを読み込む
+2. DISPATCH_PANEにsend-keysで通知（2回分割）
+3. フォーマット: 「タスク${TASK_ID}完了。queue/reports/をご確認ください」
+
+### 実装例
+```bash
+# panes.envを読み込む
+source .ensemble/panes.env
+
+# Dispatchに通知（2回分割）
+tmux send-keys -t "$DISPATCH_PANE" 'タスク${TASK_ID}完了。queue/reports/をご確認ください'
+sleep 1
+tmux send-keys -t "$DISPATCH_PANE" Enter
+```
+
+### 通知失敗時
+- send-keysが失敗してもエラーにしない（Dispatchがポーリングでフォールバック）
+- 完了報告ファイルが最優先（通知は補助）
+
 ## エラー発生時
 
 1. エラー内容を完了報告に記載
@@ -172,6 +197,36 @@ completed_at: "2026-02-03T10:30:00Z"
 4. 報告時に `executed_by: worker-{自分のID}` を必ず記載
 5. 元のワーカーの報告ファイルに書き込む（ファイル名は変えない）
 
+## /clear 後の復帰手順
+
+Dispatchから `/clear` を受けた後、以下の手順で最小コストで復帰する。
+
+### 復帰フロー（約3,000トークンで復帰）
+```
+/clear 実行
+  │
+  ▼ CLAUDE.md 自動読み込み
+  │
+  ▼ Step 1: 自分のWorker IDを確認
+  │   echo $WORKER_ID
+  │   → 出力例: 1 → 自分はWorker-1
+  │
+  ▼ Step 2: 自分のタスクYAML読み込み
+  │   queue/tasks/worker-{N}-task.yaml を読む
+  │   → タスクがあれば作業開始
+  │   → なければ次の指示を待つ
+  │
+  ▼ Step 3: 必要に応じて追加コンテキスト読み込み
+  │   タスクYAMLに files フィールドがあれば対象ファイルを読む
+  │
+  ▼ 作業開始
+```
+
+### /clear 復帰の注意事項
+- /clear前のタスクの記憶は消えている。タスクYAMLだけを信頼せよ
+- instructions（エージェント定義）は初回は読まなくてよい（CLAUDE.mdで十分）
+- 2タスク目以降で詳細な手順が必要なら worker.md を読む
+
 ## 禁止事項
 
 - 担当外のファイルを編集する