{
  "markdown": "<p align=\"center\">\n  <img src=\"./assets/icon-256.png\" width=\"160\" height=\"160\" alt=\"Ensembra icon\"/>\n</p>\n\n<h1 align=\"center\">Ensembra</h1>\n\n<p align=\"center\">\n  <em>Where agents perform in concert — a multi-agent orchestrator plugin for Claude Code.</em>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/HotRedMat/ensembra/releases\"><img src=\"https://img.shields.io/badge/version-0.13.0-blue\" alt=\"version\"/></a>\n  <a href=\"./LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-green\" alt=\"license\"/></a>\n  <img src=\"https://img.shields.io/badge/plugin%20validate-passing-brightgreen\" alt=\"plugin validate\"/>\n  <img src=\"https://img.shields.io/badge/verification-end--to--end-brightgreen\" alt=\"verification\"/>\n</p>\n\n## Screenshots\n\n<table>\n  <tr>\n    <td align=\"center\">\n      <img src=\"./assets/screenshot-run.png\" width=\"360\" alt=\"/ensembra:run feature output\"/><br/>\n      <sub><code>/ensembra:run feature</code> — 5-phase pipeline with consensus and reuse evaluation</sub>\n    </td>\n    <td align=\"center\">\n      <img src=\"./assets/screenshot-config.png\" width=\"360\" alt=\"/ensembra:config Reuse-First Policy picker\"/><br/>\n      <sub><code>/ensembra:config</code> — interactive picker with cascade-safe custom mode</sub>\n    </td>\n  </tr>\n  <tr>\n    <td align=\"center\" colspan=\"2\">\n      <img src=\"./assets/screenshot-transfer.png\" width=\"500\" alt=\"/ensembra:transfer output\"/><br/>\n      <sub><code>/ensembra:transfer</code> — 10-section handover document with devils-advocate pitfalls</sub>\n    </td>\n  </tr>\n</table>\n\n## What is Ensembra?\n\nEnsembra is a Claude Code plugin that orchestrates **six specialist agents** and **one scribe** through a **5-phase pipeline** to produce structured code reviews, mutual supervision, automatic documentation, and project handover documents. Built for solo developers who want team-level deliberation without the team.\n\n**Key ideas**:\n- **Separation of deliberation and execution**: external LLMs (Ollama / Gemini) debate, Claude Code executes.\n- **Reuse-First cross-cutting policy**: four toggleable devices force every performer to consider existing code before writing new code.\n- **Deep Source Inspection**: 10-item checklist (6 forced + 4 optional) prevents shallow reads.\n- **Consensus-driven flow**: 70/40 thresholds gate Phase 2 execution and halt pipeline on strong disagreement.\n- **Automatic documentation**: every task produces a report; weekly roll-ups and handover documents are built-in.\n\n## 5-Phase Pipeline\n\n```\nPhase 0 Gather     — Deep Scan produces a shared context snapshot\nPhase 1 Deliberate — R1 → (optional R2) → Synthesis with peer signatures\nPhase 2 Execute    — Claude Code edits files per the agreed plan\nPhase 3 Audit      — designated performers verify the diff\nPhase 4 Document   — scribe records Task / Design / Request / Daily / Weekly\n```\n\n## Performers (v0.8.0+ Debate/Audit split)\n\nv0.8.0 splits Performers into three tiers. **Opus is forbidden in debate** and used only by the `final-auditor` in Phase 3 — the unanimous-consensus judge.\n\n**Debate (Phase 1) — external LLMs + sonnet-or-lower, no opus:**\n\n| Role | Responsibility | Default Transport | Default Model |\n|---|---|---|---|\n| 🧭 **planner** | Requirements, acceptance criteria | Claude sub-agent | `sonnet` (v0.8.0: was opus) |\n| 🏛 **architect** | Module boundaries, patterns | MCP (Gemini) → Ollama → Claude | `gemini-2.5-flash` |\n| 🛠 **developer** | Implementation strategy | Claude sub-agent (opt-in external chain) | `sonnet` |\n| 🛡 **security** | Threats, secrets, OWASP | Ollama → Claude | `qwen2.5:14b` |\n| 🧪 **qa** | Edge cases, regression | Ollama → Claude | `qwen2.5:14b` |\n| 😈 **devils-advocate** | Counter-arguments, YAGNI | Claude sub-agent | `haiku` |\n\n**Audit (Phase 3) — specialist auditors → final-auditor:**\n\n| Role | Responsibility | Default Transport | Default Model |\n|---|---|---|---|\n| (specialists) | Preset-specific specialists (see presets table) | varies | varies |\n| ⚖️ **final-auditor** | Unanimous-consensus judge, always last (v0.8.0) | Claude sub-agent | `opus` |\n\n**Document (Phase 4):**\n\n| Role | Responsibility | Default Transport | Default Model |\n|---|---|---|---|\n| ✍️ **scribe** | Phase 4 documentation | Claude sub-agent | `sonnet` |\n\nUnanimous consensus (v0.8.0) = Phase 1 agreement ≥ 70% **AND** `final-auditor.verdict == pass`. Final-auditor rework is capped at 1 cycle (opus cost control). See `CONTRACT.md §8.8` for the generalized Transport Fallback Chain Protocol and `§11.3` for Final Audit details.\n\nAll models auto-fall back to Claude sub-agents when the external transport is unavailable.\n\n## Skills\n\n- `/ensembra:run <preset> <request>` — main pipeline entry point\n- `/ensembra:config` — unified interactive settings picker (all options, all cascade-safe)\n- `/ensembra:transfer [scope]` — project handover document (full project, path, or natural-language scope)\n- `/ensembra:report daily|weekly` — roll-up reports\n\n## Presets\n\n| Preset | Performers | Rounds | Phase 2 | Phase 3 Audit | Phase 4 |\n|---|---|---|---|---|---|\n| `feature` | all 6 | R1→R2→Syn | on | specialists 5 + **final-auditor** | Task+Design+Request |\n| `bugfix` | planner+architect+developer+qa | R1→Syn | on | qa+security + **final-auditor** | Task |\n| `refactor` | architect+developer+devils+qa | R1→R2→Syn | on | architect+devils + **final-auditor** | Task+Design+Request |\n| `security-audit` | security+devils+architect | R1→Syn | off | — (read-only) | Task |\n| `source-analysis` | architect+security+developer | R1→Syn | off | — (read-only) | Task |\n| `transfer` | all 6 + scribe | R1 only | off | off | handover doc |\n\n## Installation\n\n### Option A — Load directly for testing\n\n```bash\ncd /path/to/your/project\nclaude --plugin-dir /path/to/ensembra\n```\n\n### Option B — Install via marketplace\n\n```bash\nclaude plugin marketplace add HotRedMat/ensembra\nclaude plugin install ensembra@ensembra\n```\n\n### Ollama setup (optional, for security/qa)\n\n```bash\nollama pull qwen2.5:14b\n```\n\n### Gemini setup for architect (v0.7.0+, optional)\n\nThe architect Performer uses Gemini via MCP server as the primary transport. The MCP server is **automatically registered** when the plugin is installed (`plugin.json` declares `mcpServers`). To enable:\n\n1. Set API key: `/plugin → ensembra → Configure options → gemini_api_key`\n2. `/reload-plugins`\n\nThat's it — no manual `settings.local.json` editing needed. If Gemini is unavailable (no key set, API error), architect falls back to Ollama (`qwen2.5:14b`), then to a Claude sub-agent — Ensembra works fully without Gemini or Ollama. The API key is stored securely in the OS keychain (`sensitive: true`) and passed only to the MCP server process env — never exposed in skill/agent content or session logs. See [`SECURITY.md`](./SECURITY.md) and `CHANGELOG.md [0.7.0]` for details.\n\n### Prerequisites per platform\n\nThe MCP server (`mcp-servers/gemini-ensembra/server.py`) runs under `python3` and uses only the Python standard library — no `pip install` required. Platform notes:\n\n| OS | Status | Keychain backend | Notes |\n|---|---|---|---|\n| macOS | Primary | `security find-generic-password` | No extra setup. Keychain service name `Claude Code-credentials` |\n| Linux | Secondary | `secret-tool` (libsecret / GNOME Keyring) | Install with `sudo apt install libsecret-tools` or equivalent. Alternative: set env `GEMINI_API_KEY=...` |\n| Windows | Secondary | Win32 Credential Manager (`CredReadW`) | `python3` must resolve on PATH. If only `python` is available, add a `python3` alias via the `py` launcher or a PATH shim. Alternative: set `$env:GEMINI_API_KEY` in your PowerShell profile |\n\nIf `python3` is not on PATH, the MCP server silently fails and the architect Performer falls back to Ollama → Claude — you will see the fallback in the transport badge but not the underlying Python error. Run `python3 --version` once to confirm.\n\n## Reuse-First Policy\n\nFour devices, toggleable via `/ensembra:config → Reuse-First Policy`:\n\n1. **Deep Scan Inventory** — Phase 0 collects all reusable symbols from `commons/`, `shared/`, `lib/`, etc.\n2. **Schema Field** — every R1 output must include `reuse_analysis.decision: reuse | extend | new` with justification\n3. **Auto Disagree** — R2 peers automatically disagree when `new` decisions have weak justification (regex-matched)\n4. **Synthesis Report** — a fixed top-level section reports missed reuse opportunities\n\nQuick Select: **Maximum** (default) / Strong / Balanced / Advisory / Off. Custom mode uses cascade rules so no invalid combination is reachable.\n\n## Out of scope\n\n- **Session handoff notes** (mid-work pause/resume) — use external plugins like `d2-ops-handoff`\n- **ChatGPT integration** — excluded for ToS and stability reasons; use Claude/Gemini/Ollama\n\n## Documentation\n\n- [`CONTRACT.md`](./CONTRACT.md) — pipeline contract, schemas, Reuse-First policy (Korean)\n- [`INTERVIEW.md`](./INTERVIEW.md) — design decision log (Korean)\n- [`SECURITY.md`](./SECURITY.md) — threat model and secret handling (Korean)\n- [`CHANGELOG.md`](./CHANGELOG.md) — version history and verification results\n- [`.claude/ensembra/transfer/2026-04-15-project.md`](./.claude/ensembra/transfer/2026-04-15-project.md) — Ensembra's own handover document (generated by Ensembra itself; v0.11.0+ default path is `.claude/ensembra/` for plugin output isolation)\n\n## Verification status\n\nCumulative through `v0.13.0` — structural and behavioral verification history:\n\n- `claude plugin validate` passes on every release\n- All 9 agents invoked individually in live sessions (6 debate performers + scribe + orchestrator + final-auditor)\n- End-to-end runs on `feature`, `bugfix`, `refactor`, `security-audit`, `source-analysis`, `ops`, `ops-safe` presets (v0.9.0+ added `ops`/`ops-safe` for operations work)\n- `transfer` generated a 528-line handover document for the Ensembra project itself\n- `/ensembra:report daily|weekly` handles both populated and empty-week states\n- **Rework loop** triggered twice on an intentionally-weak email validator, converging on pass with 19 tests\n- **Halt-on-low-consensus** triggered on a deliberately controversial refactor request (0% consensus, pipeline stopped before Phase 2)\n- **Ensembra's `source-analysis` preset caught 4 real drift bugs in Ensembra's own code** — the strongest possible proof that the plugin catches real bugs\n- **All three transports verified end-to-end**: Ollama (`qwen2.5:14b`), Gemini (`gemini-2.5-flash` / `gemini-2.5-pro`), Claude sub-agents\n- **v0.9.0+**: Single MCP server `gemini-ensembra` exposes 9 role-specific tools (architect/planner/developer/security/qa/devils/scribe/final-auditor/triage). One registration, one API key, nine roles.\n- **v0.13.0+**: 429 RESOURCE_EXHAUSTED auto step-downgrade chain (`pro → flash → flash-lite`) in `gemini_client.py` — maintains Gemini-family quality continuity before falling back to external transports (CONTRACT.md §8.9.7).\n\nSee [`CHANGELOG.md`](./CHANGELOG.md) for the full verification log.\n\n## License\n\nMIT © 2026 Seungho Lee\n",
  "bytes": 10985,
  "sha": "8f08015b2b7b0643efedaba754d62a9fd34b9769aadff899640c2c8817cca338",
  "repo_slug": "hotredmat/ensembra",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hotredmat_ensembra_ensembra_2565d0c8/readme"
}