Plan deeply, build once. A research-to-execution pipeline skill for Claude Code.
aqua-combo orchestrates Claude Code's native features — Plan Mode, subagents with worktree isolation, adversarial debate, and smart clarification — into a single pipeline. It forces you to research before coding, debate before committing (in FULL mode), and verify before shipping.
It is a structured planning discipline — a forcing function on thinking — not an autonomous engine. Its value is making you research, clarify, debate, and plan before touching code.
/aqua-combo "build a notification system with WebSocket + queue"
| Phase | Name | What happens |
|---|---|---|
| P1 | Research | Deep multi-source research on the problem |
| P2 | Clarify | 3-5 targeted questions you didn't think to ask |
| P3 | Debate | Adversarial stress-test via Gemini or web skepticism |
| P4 | Architect | Design simplest architecture using Plan Mode |
| P5 | Dispatch | Launch subagents in isolated worktrees with crafted prompts |
| P6 | Review | Code review + security audit via specialized subagents |
ultrathink checkpoints (Claude Code's high-effort reasoning keyword) at each decision gate ensure deep analysis. The number of gates depends on the selected mode — FULL mode uses all five numbered gates plus mode selection.
| Mode | Phases | When |
|---|---|---|
| SCOUT | P1 (quick) + plan | Simple task, known pattern, <50 LOC |
| STANDARD | P1 → P2 → P4 → P5 → P6 | New feature, moderate complexity |
| FULL | All P1 through P6 | Architecture, high stakes, production, multi-agent |
Override: /aqua-combo --mode full "redesign the auth system"
aqua-combo orchestrates Claude Code's native features AND installed skills:
Native features:
- Plan Mode (P4) —
Shift+Tabfor read-only architecture planning - Subagents with worktree isolation (P5) — each agent works in its own git branch
ultrathinkkeyword — triggers high-effort reasoning at 5 decision gates- Save-state +
/clear— fresh context between phases for maximum quality - Skill routing — automatically picks the best tool per task
Skill delegation (auto-detected, fallbacks if not installed):
/aqua-searchin P1 — deep research with Czajka formalization + CoVe/octo-definein P2 — multi-AI consensus on requirements/octo-debatein P3 — 3-way AI debate (Claude+Gemini+Codex)/octo--octopus-architecturein P4 — multi-AI architecture design/octo--skill-code-review+/verification-loopin P6 — multi-AI review + automated gates
aqua-combo works standalone — all phases have built-in fallbacks. The recommended skills make each phase stronger but are not required.
aqua-combo's quality gates are LLM-enforced by default. For production use, add deterministic hooks that make gates unbypassable:
- Notification hook — desktop alert when pipeline needs your input (long phases)
- Stop hook — verify all required phases ran before declaring complete
- PreToolUse hook — block file edits until a plan file exists (Iron Law #1)
- SubagentStop hook — auto-notify when dispatched agents finish
See references/context_protocol.md for ready-to-paste hook configurations.
Agent dispatch (P5): Before launching agents, the skill presents a confirmation gate listing all tasks. Agents run in default permission mode unless you explicitly opt in to auto-accept.
Worktree isolation: Each dispatched agent gets its own copy of the repo via git worktree. If an agent's work fails review, git worktree remove discards it cleanly. No mess in your working directory.
Web research safety: P1 research may pull web content. The skill summarizes and paraphrases rather than copy-pasting raw content into agent prompts, reducing prompt injection risk.
git clone https://github.com/prezis/aqua-combo.git
cp -r aqua-combo/SKILL.md aqua-combo/references ~/.claude/skills/aqua-combo/Or manually:
mkdir -p ~/.claude/skills/aqua-combo/references
# Copy SKILL.md and references/ into the above directoryOptional — install the provided subagent definitions for better review:
mkdir -p .claude/agents
cp aqua-combo/references/subagent_definitions.md .claude/agents/README.md
# Then copy individual agent definitions from that file into .claude/agents/aqua-combo/
SKILL.md # Main skill (6 phases + iron laws)
references/
subagent_definitions.md # Ready-to-use .claude/agents/ definitions
prompt_templates.md # Domain-specific templates for agent prompts
context_protocol.md # Context management, resource budgets, failure modes
- Claude Code — the skill runs inside Claude Code's skill system
- Gemini CLI (optional) — used in P3 for adversarial debate. Falls back to web search if unavailable.
Found a way to improve the pipeline? Open an issue or PR. Ideas:
- New subagent definitions for specific domains
- Better prompt templates
- Additional adversarial debate strategies
- Context management improvements
Plan deeply, build once.