alp-river

Latest updates

The last three updates:

1.2.15

• A finished run now ends with a timing summary: total time, time per phase, and time per milestone when the work was built in milestones.

1.2.14

• Removed the opt-in screenshot-based visual check because they were unreliable.

1.2.13

• A big change with several genuinely different ways to build it can now explore those approaches in parallel and settle on the strongest one, or blend the best parts, before any code is written.

Full history in CHANGELOG.md.

Getting Started

1. Set your main Claude Code session model (the orchestrator that runs the routing loop) to a top-tier model like Opus at high effort - the orchestrator drives every routing decision, so a weaker main model degrades the whole pipeline.
2. Install the plugin (see Install below).
3. Describe what you want in plain English (or use /alp-river:go), then respond only at the decision points.

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 it works

No commands required. Describe what you want in plain text - or use /alp-river:go for a discoverable trigger. Both run the same workflow.

Triage reads your request and picks one of four conversation types. A deterministic router then runs only the stages that type needs, and pulls in more only when the work reveals it needs them - discover no email infra and a research stage joins; a plan that signs tokens pulls in a security lens. Size (XS-XXL) is just how many stages the route ended up with.

flowchart TD
    t{triage reads<br/>your request}
    t -->|talk| A[discuss<br/>no code, just answers]
    t -->|sketch| B[sketch-build<br/>throwaway in .prototypes/]
    t -->|code| C[plan → test → implement<br/>→ review → heal]
    t -->|system| D[plan → safety-gate<br/>→ execute → verify]

Path	You're...	What it leaves behind
talk	thinking out loud, asking, weighing options	nothing - answers, worked examples, tradeoffs. Reads freely; only expensive moves (a web search, a diagram) ask first.
sketch	trying an idea fast	a throwaway artifact in .prototypes/ - code, a diagram, or a UI mockup. Relaxed ceremony; correctness and security still apply.
code	changing the codebase	a reviewed, tested change in your repo. The full route: clarify, plan, challenge, red tests, implement, review fan-out, self-heal. A large change proceeds as verified milestones - each built, reviewed, and confirmed before the next.
system	changing the machine (configs, troubleshooting, CLI tooling)	a verified change, with a safety check before anything destructive or irreversible.

Where you stay in the loop

You're pulled in only at decisions that could change the outcome:

• Intent - a clear ask gets a one-line read and proceeds; you correct it in your next message. A genuinely ambiguous ask sends the interviewer to loop with you until intent settles.
• Clarifier questions - researches the codebase first, then asks only what's still open.
• Design picker - for UI with multiple legitimate shapes, builds an interactive page; you paste back the chosen spec.
• Cost / plan / safety gates - fire only when the route turns expensive, a plan is ready, or a destructive step is queued. Never as fixed ceremony.

Everything else runs to convergence: done when no signal triggers an unrun stage and every review lens is clean. Reviewer findings feed the fixer automatically.

Examples

"Rename a variable across the module"

Trivial code change - plan, write, check, done.