Superpowers-CCG
sitien173/superpowers-ccg
Orquestração multi-modelo com gates: Plan → Execute → Review
Ver no GitHubSkill de orquestração multi-modelo que coordena Claude, Codex e Gemini em um fluxo estruturado de planejamento, execução e revisão. Roteia tarefas entre Claude (coordenador), Codex (back-end) e Gemini (front-end) com gates de qualidade e validação cruzada.
Instalação
npx convez-ai sitien173/superpowers-ccg1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Projetos full-stack que precisam de especialistas back-end e front-end em coordenação
- Ideação e prototipagem com validação cruzada entre múltiplos modelos
- Desenvolvimento com revisão de qualidade automática (spec compliance + edge cases)
Veredito

Skill sofisticado para times de desenvolvimento que precisam orquestrar múltiplos modelos especializados. Impõe estrutura clara (planejar → executar → revisar) e roteamento inteligente, ideal para projetos complexos; não recomendado para tarefas simples e isoladas.
README
A tradução para o português deste README ainda está na fila.
Superpowers-CCG
Multi-model orchestration plugin for Claude Code and Codex. The host coordinator plans, routes, reviews, and handles simple edits. Heavier work is dispatched to Codex (back-side) or Gemini / Antigravity (front-side) through a single MCP tool.
CCG = Claude + Codex + Gemini
Workflow
Three gates: Plan → Execute → Review.
- Plan — for new features / ideation, run Cross-Validation first (ask Codex + Gemini the same narrow question, reconcile divergences). Then frame work as one phase: 2–4 tasks, file set,
Done Whenchecks. Output a# ROUTEblock. - Execute — route by side (no default executor). Worker edits files via its own MCP write tools and returns
## FILES MODIFIED. - Review — (a) Spec: run
Done When+git show <hash>per task commit; (b) Quality scan on changed files (edge cases, error handling, security, naming, duplication, correctness). Output# REVIEWwithPASS/PASS_WITH_DEBT/FAIL.
Severity downgrade: CRITICAL/HIGH force FAIL; MEDIUM downgrades PASS → PASS_WITH_DEBT; LOW is noted only. Quality scan is skipped for docs-only or trivial Claude edits, required for every Codex/Gemini phase.
Canonical spec: skills/coordinating-multi-model-work/SKILL.md.
flowchart TD
A([Request]) --> B{Fuzzy idea or<br/>clear task?}
B -->|"fuzzy idea / requirements"| BR["/brainstorm or /prd<br/>design or PRD doc"]
BR --> WP["/write-plan<br/>PLAN.md + phases"]
B -->|"clear, scoped task"| WP
WP --> P["Gate 1 - Plan<br/>frame phase, emit # ROUTE"]
P --> R{Route by side}
R -->|simple| CO["Coordinator edits directly"]
R -->|back-side| CX["Codex worker via MCP"]
R -->|front-side| GM["Gemini worker via MCP"]
R -->|"full-stack / unclear / high-impact"| CV["Cross-Validation<br/>ask both, reconcile"]
CV --> R
CO --> EX["Gate 2 - Execute<br/>per-task commits + notes + journal"]
CX --> EX
GM --> EX
EX --> RV{"Gate 3 - Review<br/>Spec + Quality scan"}
RV -->|FAIL| P
RV -->|"PASS / PASS_WITH_DEBT"| SQ["Squash commit<br/>update .handover.md"]
SQ --> NX{More phases?}
NX -->|yes| P
NX -->|no| V(["verifying-before-completion"])
Routing
| Phase | Owner | Tool |
|---|---|---|
| Simple — one-line edit, rename, doc tweak, single-file fix | Coordinator | built-in |
| Back-side — backend, API, business logic, database, system, infra, CI/CD, scripts, server-side tests | Codex | mcp__openmcp__run(backend="codex", ...) |
| Front-side — UI, CSS, layout, motion, canvas/SVG, client interactions, multimodal, large-context UI/doc sweeps | Gemini | mcp__openmcp__run(backend="gemini", ...) |
| New feature / ideation (before plan exists) | Cross-Validation → assign side | both backends |
| Full-stack | split into back-side + front-side sub-phases | — |
User overrides ("use Codex", "skip cross-validation", "no external models") always win.
Plan Artifacts
Multi-phase plans live in docs/plans/<YYYY-MM-DD-slug>/. Phase folders are created lazily — only PLAN.md and .handover.md exist at write time.
docs/plans/2026-05-21-user-auth/
PLAN.md # phases, ownership, Done When
.handover.md # resume pointer + cached worker SESSION_IDs
phase-01/ # created when Phase 1 starts
prompt.md # dispatch spec for the worker
notes.md # decision notes, one ## Task <M> block per task
journal.md # Route → External Response → Review → Squash Commit
phase-02/
...
Single-phase / docs-only work uses a flat file (docs/plans/YYYY-MM-DD-<slug>-implementation-plan.md) with no resume artifacts.
.handover.mdis the resume pointer (≤500 tokens). Always coordinator-authored, rewritten on every plan-state change.session_refsfrontmatter caches Codex/GeminiSESSION_IDs and is updated after every MCP call that returns one.prompt.mdholds the full dispatch spec; the MCPPROMPTfield is just a pointer to it. InlinePROMPTonly for one- or two-sentence asks.notes.mdcaptures off-spec decisions, deviations, tradeoffs, assumptions, and follow-ups — appended per task by the worker. Empty sub-sections written as- none.journal.mdis the durable phase record. The coordinator writes the Route skeleton at phase start; the worker appends the full# EXTERNAL RESPONSEblock at phase end; the coordinator finalizes Review and Squash Commit sections after the Review gate.
Worker Contract (Codex / Gemini)
- One commit per task. Message prefix
phase-<N>.task-<M>: <subject>. Hashes returned in## COMMITS. After ReviewPASS, the coordinator squashes them into a singlephase-<N>: <summary>commit (git reset --soft HEAD~<count>). - Per-task
notes.mdblock appended after each task — never batch-written at phase end. # EXTERNAL RESPONSEblock appended tojournal.mdbefore the worker emits its terse completion line.- Same-phase fix: reuse cached
SESSION_ID, sendFIX:+ delta context only.
Resume
A new session reads .handover.md first, then only the journal.md files listed in read_first. Claude Code and Codex use host-specific session-start hook configurations to surface an <RESUME> block when an ACTIVE handover exists.
Install
Claude Code
claude plugin marketplace add https://github.com/sitien173/superpowers-ccg
claude plugin install superpowers-ccg
Codex
Add the Git marketplace, then install the plugin:
codex plugin marketplace add sitien173/superpowers-ccg-codex-marketplace --ref main
codex plugin add superpowers-ccg@superpowers-ccg-marketplace
Qoder
Install the plugin via the Qoder Marketplace (Quest → Marketplace → search "superpowers-ccg"), or add it manually:
- Copy (or symlink) this repo into
~/.qoder/plugins/superpowers-ccg/. - Register hooks by merging the following into
~/.qoder/settings.json:
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "bash \"${QODER_PLUGIN_ROOT}/hooks/run-hook.sh\" superpowers-ccg-session-start.sh --qoder",
"commandWindows": "\"%QODER_PLUGIN_ROOT%\\hooks\\run-hook.cmd\" superpowers-ccg-session-start.sh --qoder",
"statusMessage": "Loading superpowers-ccg context"
}
]
},
{
"hooks": [
{
"type": "command",
"command": "bash \"${QODER_PLUGIN_ROOT}/hooks/run-hook.sh\" superpowers-ccg-user-prompt-submit.sh --qoder",
"commandWindows": "\"%QODER_PLUGIN_ROOT%\\hooks\\run-hook.cmd\" superpowers-ccg-user-prompt-submit.sh --qoder"
}
]
}
]
}
}
Note:
$QODER_PLUGIN_ROOTis the env variable Qoder sets to the plugin's install directory (analogous to$PLUGIN_ROOTin Codex). If Qoder uses a different variable name, update the hook commands above accordingly.
Prerequisites
- Claude Code —
claude --version - Codex CLI —
codex --version - Gemini CLI —
gemini --version - [Antigravity CLI]
agy --version uv/uvx
MCP setup
A single unified server — openmcp — exposes one tool, mcp__openmcp__run, with a backend field ("codex" or "gemini" or "agy").
Environment resolution priority for OpenMCP defaults:
- User environment variables
~/.openmcp/.env
OpenMCP environment variables
| Variable | Purpose | Default |
|---|---|---|
OPENMCP_AGY_MODEL_DEFAULT | Default model when backend="agy" and no model arg is passed | empty |
OPENMCP_CODEX_MODEL_DEFAULT | Default model when backend="codex" and no model arg is passed | empty |
OPENMCP_GEMINI_MODEL_DEFAULT | Default model when backend="gemini" and no model arg is passed | empty |
OPENMCP_CODEX_PROFILE_DEFAULT | Default profile when backend="codex" and no profile arg is passed | mcp-execution |
OPENMCP_GEMINI_ROUTE_TO_AGY | Routes backend="gemini" calls to agy when truthy (1, true, yes, on) | false |
OPENMCP_LOG_FILE | OpenMCP log file path | ~/.openmcp/openmcp.log |
OPENMCP_LOG_LEVEL | OpenMCP log level | INFO |
Reasoning-mode models are hardcoded in openmcp/src/openmcp/server.py (_REASONING_MODELS):
agy → gemini-3.5-flash (suffixed with -<reasoning>), codex → gpt-5.5, gemini → gemini-3.1-pro-preview.
Example ~/.openmcp/.env:
OPENMCP_AGY_MODEL_DEFAULT=gemini-3.5-flash
OPENMCP_CODEX_MODEL_DEFAULT=gpt-5.3-codex
OPENMCP_GEMINI_MODEL_DEFAULT=gemini-2.5-pro
OPENMCP_CODEX_PROFILE_DEFAULT=mcp_execution
OPENMCP_GEMINI_ROUTE_TO_AGY=false
OPENMCP_LOG_FILE=~/.openmcp/openmcp.log
OPENMCP_LOG_LEVEL=INFO
Example plugin env (.mcp.json):
{
"mcpServers": {
"openmcp": {
"env": {
"OPENMCP_AGY_MODEL_DEFAULT": "gemini-3.5-flash",
"OPENMCP_CODEX_MODEL_DEFAULT": "gpt-5.3-codex",
"OPENMCP_GEMINI_MODEL_DEFAULT": "gemini-2.5-pro",
"OPENMCP_CODEX_PROFILE_DEFAULT": "mcp_execution",
"OPENMCP_GEMINI_ROUTE_TO_AGY": "false",
"OPENMCP_LOG_FILE": "~/.openmcp/openmcp.log",
"OPENMCP_LOG_LEVEL": "INFO"
}
}
}
}
If you previously installed separate codexmcp / geminimcp servers, remove them:
claude mcp remove codex
claude mcp remove gemini
claude mcp remove agy
Commands & Skills
Claude Code slash commands (each loads its shared skill before acting):
/brainstorm— explore intent, requirements, and design via dialogue. Cross-Validation runs only when work is full-stack, unclear, or high-impact (not every new feature)./prd— turn rough product or technical requirements into a research-backed PRD (goals, non-goals, requirements, architecture, risks, milestones, acceptance criteria)./write-plan— turn a confirmed design into a phase-based plan./execute-plan— run the active phase under the three gates./setup-openmcp-env— interactively configure everyOPENMCP_*env var and save to~/.openmcp/.env.
Shared skills discovered by Claude Code and Codex (namespace superpowers-ccg:):
coordinating-multi-model-work— canonical 3-gate workflow, routing, review, resume artifacts.brainstorming,writing-plans,executing-plans— phase-stage skills loaded by the slash commands.technical-prd-generator— generate, improve, or review PRDs / technical specs; saves todocs/plans/and can hand off towriting-plans.test-driven-development— failing test first, watch it fail, then minimal code (feature/bugfix phases).systematic-debugging— root-cause investigation before any fix (bugs, test failures).verifying-before-completion— fresh verification evidence before reporting done.
Codex does not install Claude slash-command files as native slash commands. Use the same workflows by invoking the corresponding superpowers-ccg:* skill directly; the command files are thin Claude entry points over those shared skills.
Cross-Host Compatibility
- Claude Code uses
.claude-plugin/plugin.json,commands/*.md,hooks/hooks-claude.json, and the shared.mcp.json. - Codex uses
.codex-plugin/plugin.json,skills/,hooks/hooks-codex.json, and the same shared.mcp.json. - Hook scripts share the handover parsing logic but emit host-specific output contracts.
- OpenMCP is the shared MCP server for both hosts. Delegated Codex workers are always launched with
superpowers-ccg@superpowers-ccg-marketplacedisabled to avoid recursive plugin loading.
Hard Rules
- Fail-closed. Any MCP failure (timeout, unavailable, session-failed, permission-blocked, prompt too long) → output
BLOCKEDand ask the user. No silent retry, executor switch, or Task/Agent fallback. - Absolute paths only when calling
mcp__openmcp__run. The dispatch prompt pointer, thecdargument, and every file path inside the prompt body must be absolute (forward slashes on Windows). Gemini/agy mis-resolves relative paths and may scan the whole device. - One phase, one owner, one review. No draft-then-reimplement handoffs.
- Route by side. No default executor; ambiguous side → ask user.
Use Cases
Every flow runs through the same three gates; what changes is the entry point and how work is routed.
1. New / fresh project (greenfield)
flowchart LR
I["Install plugin + backends"] --> E["/setup-openmcp-env"]
E --> B["/brainstorm or /prd<br/>idea to design / PRD"]
B --> W["/write-plan<br/>docs/plans/.../PLAN.md"]
W --> X["/execute-plan<br/>phase by phase"]
X --> R["Review each phase<br/>PASS then squash"]
R --> V["verifying-before-completion"]
- Install the plugin and the Codex / Gemini backends (see Install).
/setup-openmcp-env— choose models and write~/.openmcp/.env./brainstorm "<product idea>"(or/prd "<requirements>"for a formal spec) — produces a confirmed design / PRD underdocs/plans/./write-plan— turns it intoPLAN.mdwith phases split by side (back-side → Codex, front-side → Gemini)./execute-plan— runs the active phase under the gates; repeat until every phase passes.verifying-before-completion— finalDone Whenevidence across all phases.
Scope already clear? Skip
/brainstormand go straight to/write-plan.
2. New feature (existing codebase)
Example: "Add user auth with email + password; UI on the settings page."
sequenceDiagram
actor U as User
participant C as Coordinator (Claude)
participant X as Codex (back-side)
participant G as Gemini (front-side)
U->>C: describe feature
Note over C,G: Cross-Validation only if full-stack / unclear / high-impact
C->>C: /write-plan -> PLAN.md (Phase 1 back, Phase 2 front)
C->>X: dispatch Phase 1 (prompt.md)
X-->>C: commits + notes + journal + completion line
C->>C: Review Phase 1 (git show, Done When, quality scan) -> PASS -> squash
C->>G: dispatch Phase 2 (prompt.md)
G-->>C: commits + notes + journal + completion line
C->>C: Review Phase 2 -> PASS -> squash
C->>U: verifying-before-completion across both phases
- The coordinator decides the owner by side; a single-side feature skips Cross-Validation and routes straight to Codex or Gemini.
- Each worker edits files with its own tools, commits per task, and writes
notes.md+ the# EXTERNAL RESPONSEjournal block. The coordinator never commits on the worker's behalf.
3. Bug fix / debugging
flowchart TD
B["Bug report / failing test"] --> RC["systematic-debugging<br/>reproduce, find root cause"]
RC --> T["Write failing test that<br/>reproduces the bug — RED"]
T --> F["Minimal fix — GREEN"]
F --> RV{"Review: root cause +<br/>RED to GREEN evidence<br/>in notes.md"}
RV -->|PASS| D["Squash commit"]
RV -->|FAIL| RC
- Routed to the side that owns the buggy code; small, obvious fixes the coordinator handles directly.
- Root cause before fix (
systematic-debugging) and failing test first (test-driven-development) are mandatory — the fix begins from a test that reproduces the bug, and the RED→GREEN evidence lands innotes.md.
4. Full-stack feature (Cross-Validation)
When a phase straddles both sides (shared API contract, schema, auth flow) or is high-impact:
sequenceDiagram
participant C as Coordinator
participant X as Codex
participant G as Gemini
C->>X: same narrow question (reasoning=high)
C->>G: same narrow question (reasoning=high)
X-->>C: back-side answer
G-->>C: front-side answer
C->>C: reconcile divergences, pick the contract
C->>X: Phase 1 - back-side sub-phase
X-->>C: PASS
C->>G: Phase 2 - front-side sub-phase (uses agreed contract)
G-->>C: PASS
- Cross-Validation decides the contract once, then the work splits into routed back / front sub-phases — never a single mixed phase.
- CV dispatches always pass
reasoning="high".
5. Resume after compaction / new session
flowchart LR
S(["New session / compaction"]) --> H["session-start hook<br/>surfaces RESUME block"]
H --> RD["Read .handover.md first"]
RD --> RF["Read only journals<br/>listed in read_first"]
RF --> SR["Restore cached SESSION_IDs<br/>from session_refs"]
SR --> CONT["Continue the active phase"]
- The handover artifacts (
.handover.md+ per-phasejournal.md) are the durable state — a fresh session never re-scans every phase folder. - In Claude Code the hook injects the
<RESUME>block automatically; cached Codex / GeminiSESSION_IDs let in-flight worker sessions continue withFIX:deltas.
Update
claude plugin update superpowers-ccg
codex plugin marketplace upgrade superpowers-ccg-marketplace
codex plugin add superpowers-ccg@superpowers-ccg-marketplace
Support
Issues: https://github.com/sitien173/superpowers-ccg/issues
Acknowledgments
- obra/superpowers — original Superpowers
- BryanHoo/superpowers-ccg — CCG fork
- fengshao1227/ccg-workflow — CCG workflow
- sitien173/superpowers-ccg (openmcp) — unified Codex + Antigravity (agy) MCP server