Alp River
A river of agents, sized to the task.
Featured in: Alper Ortac's AI Stack
Multi-step agent refinement for Claude Code, scaled by automatic complexity classification. Small changes pass quickly. Bigger ones add steps: clarification, planning, adversarial challenge, implementation, broad review, specialist review, self-heal.
The whole pipeline ships in one folder. Workflow, 32 subagents, 6 slash commands, 8 quality hooks.
Latest updates
The last three versions:
0.3.6
- When the pipeline asks you to decide something, each option now shows a concrete example of what it produces - so you can answer without first asking for one.
- Those prompts now lead with the decision and cut the filler, making the choice easier to grab at a glance.
0.3.5
- The workflow now loads reliably at the start of every session instead of arriving cut off.
- After compacting a long conversation, your task's intent, plan, and decisions come back intact.
0.3.4
- Planning, implementation, and review now lean toward simpler local code with explicit dependencies and strong types.
- Reviews call out the AI-style code that creeps in - defensive branches no one needs, layers without a second use, hidden state.
Full history in CHANGELOG.md.
Install
In Claude Code:
/plugin marketplace add alp82/alp-river
/plugin install alp-river@alperortac
/reload-plugins
To pull updates later:
/plugin marketplace update alperortac
/reload-plugins
The pointer resolves to the plugin's installed path. If your setup restricts file reads, allow the agent to read the plugin's doctrine - on a standard install add Read(~/.claude/plugins/cache/alperortac/alp-river/**) to your .claude/settings.json allowlist.
How to use
Describe what you want - in plain text, or via /alp-river:go if you want a discoverable trigger. Both run the same pipeline; the essentials load automatically and the full doctrine is one read away, nothing to enable.
Step 0 reads your request and picks the framing: bug-shaped requests ("why is X broken", a stack trace, a symptom) take the diagnose path (investigator runs alone in pre-flight); everything else takes the build path (full pre-flight fan-out). On affirmation, the pipeline runs.
Each step is run by a dedicated agent: classifier judges scope, scanners pre-flight the area, clarifier surfaces ambiguity, planner designs the approach, challenger pokes holes, implementer builds, reviewers cross-check, fixer heals findings.
You stay in the loop at a few well-defined moments:
- Intent confirmation (always, every tier - including S follow-ups) - confirm or correct the one-sentence read. A bare affirmation (
yes/correct/proceed) rolls; anything else - your own words, additions, corrections - is treated as a reshape and spawns the interviewer with that reply as the new input. The interviewer loops with you (cap 5 rounds) until intent settles and no new aspects emerge.
- Clarifier questions (M/L/XL when ambiguity remains) - the clarifier researches the codebase first, then asks only what's still open. It loops with you (cap 5 rounds) until clarity is reached, then the planner runs.
- Design picker (when the clarifier flags UI design choice with multiple legitimate shapes) - the design-explorer agent confirms which parameters to expose, builds an interactive page (sandbox or real-page behind a dev gate), and waits for you to copy a labeled key-value spec back into chat. That spec becomes binding for the planner.
- Plan selection (XL) - pick one of the proposed approaches.
- After-plan stop (L/XL whenever a plan was produced) - Continue-build (default) to roll into implementation, or Stop to keep the run as a design pass.
- After-diagnose stop (on bug-framing) - Continue-fix or Continue-plan to roll into the fix path at the right tier, or Stop to keep just the diagnosis. On Continue, you restate the outcome in your own words first - the investigator's report stays on screen but is never silently consumed as intent.
Everything else runs to completion. Reviewer findings feed the fixer automatically.
Override the complexity tier with natural language: treat this as L, skip clarify, go straight to plan.
How the river flows
A complexity classifier reads each task and assigns it a tier - S, M, L, XL, or XXL. The tier decides which steps run. XXL is a pushback - the classifier judges the task too big for one run and proposes a decomposition before any other gate fires.
A SessionStart hook injects a small essentials block plus a pointer to WORKFLOW.md into every Claude session; the agent reads the full doctrine from that file on demand. No per-file imports, no skill matching. After /compact, it fires again to re-anchor that pointer and restore the canonical state (intent, classification, approved plan).
