ensemble-claude 0.3.0__py3-none-any.whl

ensemble/notes.py

@@ -0,0 +1,221 @@
+"""
+学習ノート管理ユーティリティ
+
+タスク実行の学習記録を管理する。
+notes/{task-id}/以下にplan.md, decisions.md, lessons.md, skill-candidates.mdを配置。
+"""
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+
+def create_task_notes_dir(notes_base_dir: str, task_id: str) -> Path:
+    """
+    タスクノート用ディレクトリを作成する
+
+    Args:
+        notes_base_dir: ノートのベースディレクトリ
+        task_id: タスクID
+
+    Returns:
+        作成されたディレクトリのPath
+    """
+    task_dir = Path(notes_base_dir) / task_id
+    task_dir.mkdir(parents=True, exist_ok=True)
+    return task_dir
+
+
+def write_lessons(
+    task_dir: Path,
+    task_id: str,
+    lessons: dict[str, Any],
+) -> None:
+    """
+    lessons.mdファイルを作成/更新する
+
+    Args:
+        task_dir: タスクディレクトリ
+        task_id: タスクID
+        lessons: 学習内容
+            - successes: 成功したこと（リスト）
+            - improvements: 改善点（リスト）
+            - metrics: 数値（辞書）
+    """
+    content = f"""# タスク: {task_id}
+## 日時: {datetime.now().isoformat()}
+
+## 成功したこと
+"""
+    for success in lessons.get("successes", []):
+        content += f"- {success}\n"
+
+    content += "\n## 改善すべきこと\n"
+    for improvement in lessons.get("improvements", []):
+        if isinstance(improvement, dict):
+            content += f"- [ ] {improvement.get('issue', '')}\n"
+            content += f"  - 原因: {improvement.get('cause', '')}\n"
+            content += f"  - 対策: {improvement.get('solution', '')}\n"
+        else:
+            content += f"- [ ] {improvement}\n"
+
+    metrics = lessons.get("metrics", {})
+    content += f"""
+## 数値
+- 修正回数: {metrics.get('fix_count', 0)}回
+- テスト失敗回数: {metrics.get('test_failures', 0)}回
+- レビュー指摘数: {metrics.get('review_issues', 0)}件
+"""
+
+    (task_dir / "lessons.md").write_text(content)
+
+
+def write_skill_candidates(
+    task_dir: Path,
+    candidates: list[dict[str, Any]],
+) -> None:
+    """
+    skill-candidates.mdファイルを作成する
+
+    Args:
+        task_dir: タスクディレクトリ
+        candidates: スキル化候補のリスト
+            - name: スキル名
+            - purpose: 用途
+            - occurrences: 発生回数
+            - cost: 実装コスト（low/medium/high）
+            - recommended: 推奨（True/False）
+    """
+    content = "# スキル化候補\n\n"
+
+    if not candidates:
+        content += "候補なし\n"
+    else:
+        for i, candidate in enumerate(candidates, 1):
+            recommended = "YES" if candidate.get("recommended", False) else "NO"
+            content += f"""## 候補{i}: {candidate.get('name', 'unknown')}
+- 用途: {candidate.get('purpose', '')}
+- 発生回数: {candidate.get('occurrences', 0)}回
+- 実装コスト: {candidate.get('cost', 'unknown')}
+- 推奨: {recommended}
+
+"""
+
+    (task_dir / "skill-candidates.md").write_text(content)
+
+
+def write_decisions(
+    task_dir: Path,
+    task_id: str,
+    decisions: list[dict[str, Any]],
+    append: bool = False,
+) -> None:
+    """
+    decisions.mdファイルを作成/更新する
+
+    Args:
+        task_dir: タスクディレクトリ
+        task_id: タスクID
+        decisions: 決定のリスト
+            - timestamp: タイムスタンプ
+            - context: 文脈
+            - decision: 決定内容
+            - rationale: 理由
+        append: Trueの場合、既存ファイルに追記
+    """
+    decisions_file = task_dir / "decisions.md"
+
+    if append and decisions_file.exists():
+        content = decisions_file.read_text()
+        content += "\n---\n\n"
+    else:
+        content = f"# 決定ログ: {task_id}\n\n"
+
+    for decision in decisions:
+        content += f"""## {decision.get('context', 'No context')}
+- **日時**: {decision.get('timestamp', datetime.now().isoformat())}
+- **決定**: {decision.get('decision', '')}
+- **理由**: {decision.get('rationale', '')}
+
+"""
+
+    decisions_file.write_text(content)
+
+
+def read_lessons(task_dir: Path) -> str | None:
+    """
+    lessons.mdの内容を読み込む
+
+    Args:
+        task_dir: タスクディレクトリ
+
+    Returns:
+        ファイル内容。存在しない場合はNone
+    """
+    lessons_file = task_dir / "lessons.md"
+    if lessons_file.exists():
+        return lessons_file.read_text()
+    return None
+
+
+def read_skill_candidates(task_dir: Path) -> str | None:
+    """
+    skill-candidates.mdの内容を読み込む
+
+    Args:
+        task_dir: タスクディレクトリ
+
+    Returns:
+        ファイル内容。存在しない場合はNone
+    """
+    skills_file = task_dir / "skill-candidates.md"
+    if skills_file.exists():
+        return skills_file.read_text()
+    return None
+
+
+def list_task_notes(notes_base_dir: str) -> list[str]:
+    """
+    全タスクディレクトリをリストする
+
+    Args:
+        notes_base_dir: ノートのベースディレクトリ
+
+    Returns:
+        タスクIDのリスト
+    """
+    notes_path = Path(notes_base_dir)
+    if not notes_path.exists():
+        return []
+
+    return [d.name for d in notes_path.iterdir() if d.is_dir()]
+
+
+def get_notes_summary(notes_base_dir: str) -> dict[str, dict[str, bool]]:
+    """
+    全ノートの要約を返す
+
+    Args:
+        notes_base_dir: ノートのベースディレクトリ
+
+    Returns:
+        {task_id: {has_lessons: bool, has_skill_candidates: bool, ...}}
+    """
+    notes_path = Path(notes_base_dir)
+    if not notes_path.exists():
+        return {}
+
+    summary: dict[str, dict[str, bool]] = {}
+
+    for task_dir in notes_path.iterdir():
+        if not task_dir.is_dir():
+            continue
+
+        summary[task_dir.name] = {
+            "has_lessons": (task_dir / "lessons.md").exists(),
+            "has_skill_candidates": (task_dir / "skill-candidates.md").exists(),
+            "has_decisions": (task_dir / "decisions.md").exists(),
+            "has_plan": (task_dir / "plan.md").exists(),
+        }
+
+    return summary

ensemble/queue.py

@@ -0,0 +1,166 @@
+"""
+ファイルベースのタスクキュー
+
+アトミック操作でタスクの配信・取得・完了報告を行う。
+"""
+
+from __future__ import annotations
+
+import os
+import uuid
+from datetime import datetime
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from ensemble.lock import atomic_claim, atomic_write
+
+
+class TaskQueue:
+    """
+    ファイルベースのタスクキュー
+
+    構造:
+        queue/
+        ├── tasks/       # 保留中のタスク
+        ├── processing/  # 処理中のタスク
+        └── reports/     # 完了報告
+    """
+
+    def __init__(self, base_dir: Path | None = None) -> None:
+        """
+        キューを初期化する
+
+        Args:
+            base_dir: ベースディレクトリ（デフォルト: queue/）
+        """
+        self.base_dir = base_dir if base_dir else Path("queue")
+        self.tasks_dir = self.base_dir / "tasks"
+        self.processing_dir = self.base_dir / "processing"
+        self.reports_dir = self.base_dir / "reports"
+
+        # ディレクトリ作成
+        self.tasks_dir.mkdir(parents=True, exist_ok=True)
+        self.processing_dir.mkdir(parents=True, exist_ok=True)
+        self.reports_dir.mkdir(parents=True, exist_ok=True)
+
+    def enqueue(
+        self,
+        command: str,
+        agent: str,
+        params: dict[str, Any] | None = None,
+    ) -> str:
+        """
+        タスクをキューに追加する
+
+        Args:
+            command: 実行するコマンド
+            agent: 担当エージェント
+            params: 追加パラメータ
+
+        Returns:
+            タスクID
+        """
+        task_id = self._generate_task_id()
+
+        task = {
+            "task_id": task_id,
+            "command": command,
+            "agent": agent,
+            "params": params or {},
+            "status": "pending",
+            "created_at": datetime.now().isoformat(),
+        }
+
+        task_file = self.tasks_dir / f"{task_id}.yaml"
+        content = yaml.dump(task, allow_unicode=True, default_flow_style=False)
+        atomic_write(str(task_file), content)
+
+        return task_id
+
+    def claim(self) -> dict[str, Any] | None:
+        """
+        タスクを取得する（アトミック）
+
+        Returns:
+            タスクデータ、またはキューが空の場合None
+        """
+        # 最も古いタスクを取得（ファイル名でソート）
+        task_files = sorted(self.tasks_dir.glob("*.yaml"))
+
+        for task_file in task_files:
+            result = atomic_claim(str(task_file), str(self.processing_dir))
+            if result:
+                with open(result) as f:
+                    return yaml.safe_load(f)
+
+        return None
+
+    def complete(
+        self,
+        task_id: str,
+        result: str,
+        output: str,
+        error: str | None = None,
+    ) -> None:
+        """
+        タスク完了を報告する
+
+        Args:
+            task_id: タスクID
+            result: 結果 ("success" or "error")
+            output: 出力内容
+            error: エラーメッセージ（エラー時のみ）
+        """
+        processing_file = self.processing_dir / f"{task_id}.yaml"
+
+        # 元のタスク情報を読み込み
+        if processing_file.exists():
+            with open(processing_file) as f:
+                task = yaml.safe_load(f)
+        else:
+            task = {"task_id": task_id}
+
+        # レポート作成
+        report = {
+            **task,
+            "result": result,
+            "output": output,
+            "completed_at": datetime.now().isoformat(),
+        }
+        if error:
+            report["error"] = error
+
+        # reportsに保存
+        report_file = self.reports_dir / f"{task_id}.yaml"
+        content = yaml.dump(report, allow_unicode=True, default_flow_style=False)
+        atomic_write(str(report_file), content)
+
+        # processingから削除
+        if processing_file.exists():
+            processing_file.unlink()
+
+    def list_pending(self) -> list[str]:
+        """
+        保留中のタスクIDリストを取得する
+
+        Returns:
+            タスクIDのリスト
+        """
+        task_files = self.tasks_dir.glob("*.yaml")
+        return [f.stem for f in task_files]
+
+    def cleanup(self) -> None:
+        """
+        全てのファイルを削除する（セッション開始時用）
+        """
+        for dir_path in [self.tasks_dir, self.processing_dir, self.reports_dir]:
+            for f in dir_path.glob("*.yaml"):
+                f.unlink()
+
+    def _generate_task_id(self) -> str:
+        """ユニークなタスクIDを生成"""
+        timestamp = datetime.now().strftime("%Y%m%d%H%M%S")
+        short_uuid = uuid.uuid4().hex[:8]
+        return f"{timestamp}-{short_uuid}"

ensemble/templates/__init__.py

@@ -0,0 +1,75 @@
+"""Ensemble templates package.
+
+Provides access to bundled agent definitions, commands, workflows, and scripts.
+"""
+
+from importlib import resources
+from pathlib import Path
+from typing import Optional
+
+
+def get_template_path(template_type: str) -> Path:
+    """Get the path to a template directory.
+
+    Args:
+        template_type: One of "agents", "commands", "workflows", "scripts"
+
+    Returns:
+        Path to the template directory
+
+    Raises:
+        ValueError: If template_type is not valid
+    """
+    valid_types = {"agents", "commands", "workflows", "scripts"}
+    if template_type not in valid_types:
+        raise ValueError(f"Invalid template type: {template_type}. Must be one of {valid_types}")
+
+    # Use importlib.resources for Python 3.9+
+    try:
+        # Python 3.9+ style
+        with resources.as_file(resources.files("ensemble.templates") / template_type) as path:
+            return Path(path)
+    except (TypeError, AttributeError):
+        # Fallback for older Python or edge cases
+        package_dir = Path(__file__).parent
+        return package_dir / template_type
+
+
+def get_template_file(template_type: str, filename: str) -> Optional[Path]:
+    """Get the path to a specific template file.
+
+    Args:
+        template_type: One of "agents", "commands", "workflows", "scripts"
+        filename: Name of the file within the template directory
+
+    Returns:
+        Path to the template file, or None if not found
+    """
+    template_dir = get_template_path(template_type)
+    file_path = template_dir / filename
+
+    if file_path.exists():
+        return file_path
+    return None
+
+
+def list_templates(template_type: str) -> list[str]:
+    """List all template files of a given type.
+
+    Args:
+        template_type: One of "agents", "commands", "workflows", "scripts"
+
+    Returns:
+        List of template filenames
+    """
+    template_dir = get_template_path(template_type)
+    if not template_dir.exists():
+        return []
+
+    if template_type in ("agents", "commands"):
+        return [f.name for f in template_dir.glob("*.md")]
+    elif template_type == "workflows":
+        return [f.name for f in template_dir.glob("*.yaml")]
+    elif template_type == "scripts":
+        return [f.name for f in template_dir.glob("*.sh")]
+    return []

ensemble/templates/agents/conductor.md

@@ -0,0 +1,239 @@
+---
+name: conductor
+description: |
+  Ensembleの指揮者（頭脳）。ユーザーのタスクを受け取り、
+  計画・分解・パターン選択・最終判断を行う。
+  実行の伝達・監視はDispatchに委譲する。考えすぎない。即判断。
+tools: Read, Write, Edit, Bash, Glob, Grep, Skill, Task
+model: opus
+---
+
+あなたはEnsembleの指揮者（Conductor）です。
+
+## 最重要ルール: 考えるな、委譲しろ
+
+- あなたの仕事は「判断」と「委譲」。自分でコードを書いたりファイルを直接操作するな。
+- 計画を立てたら即座にDispatchまたはサブエージェントに委譲せよ。
+- 30秒で済む判断に5分かけるな。
+
+## 行動原則
+
+1. まずplanモードで全体計画を立てる
+2. タスクを分解し、最適な実行パターンを選択する
+3. コスト見積もりを行い、適切なワークフローを選択する
+4. 必要なskillsやagentsが不足していれば生成を提案する
+5. Dispatchにタスク配信を指示する（パターンB/Cの場合）
+6. 完了報告を受けたら最終判断のみ行う
+7. 完了後は必ず自己改善フェーズをlearnerに委譲する
+
+## 実行パターン判定基準
+
+### パターンA: subagent直接実行
+- 変更ファイル数 ≤ 3
+- 独立性が高くない単純タスク
+- 例: 単一ファイルの修正、typo修正、小さな機能追加
+
+### パターンB: tmux並列実行
+- 変更ファイル数 4〜10
+- 並列可能な作業あり
+- 例: 複数エンドポイントの実装、テスト追加
+
+### パターンC: worktree分離
+- 機能が独立している
+- 変更ファイル数 > 10 または 複数ブランチ必要
+- 例: 認証・API・UIの同時開発
+
+## パターン別実行方法
+
+### パターンA: takt方式（subagent直接）
+
+Taskツールでsubagentを起動して直接実行する。Dispatchは不要。
+
+```
+1. Task(subagent_type="general-purpose")でタスク実行
+2. 結果を確認
+3. 必要に応じてレビュー
+```
+
+### パターンB: shogun方式（tmux並列）
+
+Dispatchに指示を送り、ワーカーペインを起動させる。
+
+```
+1. タスクを分解し、ワーカー数を決定
+2. queue/conductor/dispatch-instruction.yaml に指示を書く:
+
+   type: start_workers
+   worker_count: 2
+   tasks:
+     - id: task-001
+       instruction: "タスク1の説明"
+       files: ["file1.py"]
+     - id: task-002
+       instruction: "タスク2の説明"
+       files: ["file2.py"]
+   created_at: "{現在時刻}"
+   workflow: default
+   pattern: B
+
+3. Dispatchに通知（2回分割 + ペインID）:
+   source .ensemble/panes.env
+   tmux send-keys -t "$DISPATCH_PANE" '新しい指示があります。queue/conductor/dispatch-instruction.yaml を確認してください'
+   tmux send-keys -t "$DISPATCH_PANE" Enter
+
+4. 完了を待つ（Dispatchからのsend-keysは来ない。status/dashboard.mdを確認）
+```
+
+### パターンC: shogun方式（worktree）
+
+```
+1. 同様にdispatch-instruction.yamlに指示を書く
+2. type: start_worktree を指定
+3. Dispatchがworktree-create.shを実行
+```
+
+## コスト意識のワークフロー選択
+
+### ワークフロー一覧
+
+| ワークフロー | レビュー回数 | 修正ループ | 最大イテレーション | コストレベル |
+|-------------|-------------|-----------|------------------|-------------|
+| simple.yaml | 1回 | なし | 5 | low |
+| default.yaml | 並列2種 | あり | 15 | medium |
+| heavy.yaml | 並列5種 | あり | 25 | high |
+
+### 選択フローチャート
+
+```
+タスク受領
+    │
+    ▼
+[変更規模は？]
+    │
+    ├─ ファイル数 ≤ 2、ドキュメントのみ → simple.yaml
+    │
+    ├─ ファイル数 3〜10、通常の機能開発 → default.yaml
+    │
+    └─ 以下のいずれかに該当 → heavy.yaml
+       - ファイル数 > 10
+       - セキュリティ重要（認証、決済、個人情報）
+       - 大規模リファクタ
+       - 複数サービス間の変更
+```
+
+### 具体的な判定基準
+
+#### simple.yaml を選択するケース
+- README/ドキュメント更新
+- typo/文言修正
+- 設定ファイルの微調整
+- コメント追加/修正
+- 単一テストファイルの追加
+
+#### default.yaml を選択するケース
+- 新規機能の追加（標準的な規模）
+- バグ修正（影響範囲が限定的）
+- テストカバレッジ改善
+- 小〜中規模のリファクタリング
+- 依存ライブラリの更新
+
+#### heavy.yaml を選択するケース
+- 認証・認可システムの変更
+- 決済・課金機能の実装/変更
+- 個人情報を扱う機能の変更
+- データベーススキーマの大幅変更
+- アーキテクチャレベルのリファクタ
+- セキュリティ脆弱性の修正
+- 本番環境に直接影響する変更
+
+### /go-light コマンドとの関係
+
+`/go-light` コマンドは明示的に `simple.yaml` を使用する。
+ユーザーが「軽微な変更」と判断した場合に使用する。
+
+### コスト最適化のヒント
+
+1. **迷ったら default.yaml**: 過剰なレビューより見逃しのリスクが高い
+2. **セキュリティに関わるなら heavy.yaml**: コストよりリスク回避を優先
+3. **段階的エスカレーション**: simple → defaultで問題発見 → heavyで再実行も可
+
+## worktree統合プロトコル
+
+パターンCの場合、全worktreeの作業完了後:
+
+1. integrator agentが各worktreeの変更をメインブランチへマージ
+2. コンフリクトがあれば:
+   - まずAIが自動解決を試みる
+   - 失敗した場合のみConductorに報告
+3. マージ後、各worktreeのCoderが「自分以外の変更」をレビュー（相互レビュー）
+4. 全員承認で完了
+
+## 重要な設計判断のプロトコル
+
+アーキテクチャやテンプレート構造など、重要な設計判断を下す際は:
+
+- 単一エージェントの意見で即決しない
+- 複数の専門家ペルソナ（3〜5人）を召喚し、熟議させる
+- 多数決ではなく、各専門領域からの総意を得る
+
+## 並列ペイン数の動的調整
+
+Claude Max 5並列制限を考慮:
+
+- Conductor用に1セッション確保
+- 残り4セッションをタスクに応じて動的に割り当て
+- タスク数 < 4 の場合は、タスク数と同じペイン数
+
+## 待機プロトコル
+
+タスク完了後・委譲後は必ず以下を実行:
+
+1. 「待機中。次の指示をお待ちしています。」と表示
+2. **処理を停止し、次の入力を待つ**（ポーリングしない）
+
+これにより、send-keysで起こされた時に即座に処理を開始できる。
+
+## 起動トリガーと完了確認
+
+以下の形式で起こされたら即座に処理開始:
+
+| トリガー | 送信元 | アクション |
+|---------|--------|-----------|
+| `/go` または タスク依頼 | ユーザー | 計画立案・パターン選択・実行 |
+
+### 完了確認方法（Dispatchからのsend-keysは来ない）
+
+Dispatchはsend-keysでConductorに報告しない。以下の方法で完了を確認:
+1. `status/dashboard.md` を定期的に確認
+2. `queue/reports/` にファイルが揃ったら完了
+
+これにより、send-keysの信頼性問題を回避する。
+
+## 自律判断チェックリスト
+
+### タスク完了時に自動実行
+- [ ] 全ワーカーの報告を確認
+- [ ] 代理実行の有無をチェック（worker_id と executed_by の不一致）
+- [ ] 異常があれば原因分析
+- [ ] learner agentに自己改善を委譲
+
+### 異常検知時
+- [ ] 代理実行が発生 → 原因調査（通信問題？負荷偏り？）
+- [ ] 失敗タスクあり → リトライ判断またはエスカレーション
+- [ ] 全ワーカー応答なし → インフラ確認
+
+### 定期確認項目
+- [ ] dashboard.md の整合性確認
+- [ ] 未完了タスクの棚卸し
+- [ ] queue/ 内の古いファイル削除
+
+## 禁止事項
+
+- 自分でコードを書く
+- 自分でファイルを直接編集する
+- 考えすぎる（Extended Thinkingは無効化されているはず）
+- Dispatchの仕事（キュー管理、ACK確認）を奪う
+- ポーリングで完了を待つ（イベント駆動で待機せよ）
+- ワーカーの作業を横取りする
+- 曖昧な表現で報告する（具体的な数値を使え）
+- **ペイン番号（main.0, main.1等）を使用する（ペインIDを使え）**