What is vibecode-pro-max-kit?

Your AI forgets. This remembers. Spec-driven coding harness for vibecoders, product owners, CEOs and real builders — self-improving context memory, 15 agents, 33 skills working with /goal, agent-team, & workflow on autopilot loops with 0 need for human gate. Kills context rot, ships features, not spaghetti. Claude Code & Codex. Any stack. It is open-source on GitHub.

Is vibecode-pro-max-kit free to use?

vibecode-pro-max-kit is open-source under the MIT license, so it is free to use.

What category does vibecode-pro-max-kit belong to?

vibecode-pro-max-kit is listed under devtools in the Claudeers registry of Claude-compatible tools.

Built by world-class engineers, for vibecoders at
flowser.ai — AI Agents with computers for GTM

vibecode-pro-max-kit

Flow like water

"Total Concentration — Spec Breathing, Tenth Form: the Vibe Flow never breaks."
— Tanjiro Kamado

Drop this into any project. Your AI agent gets a complete plan-first dev process — 7 gated phases, self-healing check loops, and autopilot that runs start to finish without losing its place.

📦 One-command install One `curl` line drops it into any project. It detects new vs. returning users and never overwrites your files.	🌐 Works everywhere Any tech stack, any language, and any AI coding agent — Claude Code, Codex, Cursor, Windsurf, Copilot, and more.
🧭 RIPER-5 plan-first workflow 7 gated phases (Research → Spec → Innovate → Plan → Validate → Execute → Update-Process) stop the agent from jumping straight to code.	🚀 Autopilot mode (quick / fast / full) Start a hands-free run at any phase with a single phrase. Three lanes match the ceremony to the risk.
🎯 `/goal` — the run-until-done token One copy-pasteable block keeps the agent running phase after phase without stopping — and resumes the run in a fresh session.	🔁 PVL + EVL self-healing loops Plan-check-fix and test-check-fix loops find gaps, fix them, and re-check on their own — up to 10 cycles each.
🔍 vc-autoresearch A reusable find-gaps → fix → repeat loop you can point at plans, tests, specs, docs, or evals.	🧪 Feasibility probes Test-before-you-build verdicts (VIABLE / NOT-VIABLE) before the agent commits to any design approach.
🎛️ Smart strategy picker Before each phase it weighs one agent vs. many vs. a coordinated team — with cost estimates — and picks the cheapest that fits.	🧮 Smart model use The expensive model only writes code; the cheaper model does everything else. Lower cost, same quality.
🤔 Intent clarification When a request is vague, the agent asks a few sharp questions up front instead of guessing and building the wrong thing.	🛡️ 36 validators Mechanical correctness checks — not opinions — guard the kit's own structure and catch drift before it ships.
🏗️ Phase programs Large projects are split into independent phases with quality gates between them, so big work doesn't fall apart.	🔀 Programs that reshape themselves As it learns, the agent inserts new phases, reorders work, and skips blocked steps — the plan adapts on the fly.
🧠 Never loses its place Progress notes are written to disk every phase, so a run survives a memory reset and picks up exactly where it left off.	📚 Self-improving project memory It learns your codebase on setup and keeps its own shared notes current after every feature ships, so docs never go stale.
⚡ Quick Fix + Fast Mode Light lanes for small changes skip the heavy ceremony, so a one-line fix stays a one-line fix.	🧱 Layered, auto-discovered skills Skills are organized in clear layers and discovered automatically — the agent always finds the right tool for the step.
🤖 15 agents · 33 skills · 10 hooks A full team of specialized agents, reusable skills, and safety hooks, all wired together out of the box.	🔄 Full kit lifecycle Install, setup, update, and publish are all one command each — keeping every project on the latest kit safely.
📝 SPEC — your plain-language sign-off Before any design, you state what to build in simple user stories — the cheapest place to catch a misunderstanding.	🎯 Always checks your intent Every later phase measures back against your SPEC: is what we're building actually what you asked for?

The simplest, most flexible, team-friendly coding kit for

Works across any tech stack, any language, any project

Tech Stack Row 1
Tech Stack Row 2
Tech Stack Row 3

Not just for show. When you run vc-setup, agents scan your codebase,
detect your stack, and build project-specific knowledge groups that every skill reads before it works.
Other harnesses lock agents to one language — rust-review-agent, python-linter — useless elsewhere.
This one adapts to any combination above and builds up knowledge as you ship.

⚡ Get Started — One Command, 30 Seconds

Prerequisites: Node.js ≥ 22, git, bash (macOS / Linux / WSL / Git Bash; on Alpine: apk add bash).

Windows: the installer is a bash script — run it inside Git Bash (ships with Git for Windows) or WSL, not PowerShell or cmd.exe. Both work out of the box: the installer detects Windows shells and, when symlinks aren't permitted, automatically falls back to copying (install still completes). For true symlinks (so Codex auto-reflects vc-update changes), enable Developer Mode.

There is only one command, and it works for everyone. Run it inside your project folder. It detects whether you are a new or returning user, installs safely without overwriting your files, and then tells you the exact next thing to say.

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

When it finishes, it prints one of two messages — read the bottom of the output and do exactly what it says:

🆕 Fresh project

Installer detects no harness and prints:

Next: Run: claude → Say: "Run vc-setup"

→ Open your agent and say Run vc-setup

_{vc-setup detects your tech stack, creates the process/ folder, scans your codebase, and fills in your real architecture, conventions, and test commands — a conversation, not a checklist.}

🔄 Existing harness (upgrade)

Installer detects a prior install and prints:

Next (upgrade detected): Run: claude → Say: "Run vc-update"

→ Open your agent and say Run vc-update

_{vc-update pulls the latest version and, if it finds old-format plans or folders, gives you a ready-to-paste prompt to finish the move with zero data loss. Your process/ is never touched.}

💡 You never have to guess the command. install.sh routes you: fresh → vc-setup, upgrade → vc-update. Re-running install is always safe — it never breaks things. Codex users: run /vc-setup (or /vc-update) instead of saying it in chat.

📦 What install puts on disk (non-destructive)

your-project/
├── .claude/
│   ├── agents/              # 🤖 15 agent definitions (.md)
│   ├── skills/              # ⚡ 33 skills (each a dir with SKILL.md)
│   └── hooks/               # 🪝 10 lifecycle hooks (.cjs / .mjs)
├── .codex/agents/           # 🔄 Mirrored agents for Codex
├── .agents/skills →         # 🔗 Symlink to .claude/skills (Codex discovery)
├── CLAUDE.md                # 📋 Orchestrator + routing rules
├── AGENTS.md                # 📖 Agent + skill registry (cross-tool)
└── process/
    └── development-protocols/  # 📜 22 shared workflow docs (seeded by install)
                                #    context/, plans, features → built by vc-setup

Non-destructive. Your existing .claude/skills/, .claude/agents/, process/, and settings.json are never wiped. Only kit-owned files are written or updated.
Existing config? Backed up to .vibecode-backup/; your settings.json is restored afterward.
Existing CLAUDE.md? Backed up as CLAUDE.md.pre-vibecode.
Existing process/? Never touched by install — vc-setup / vc-update migrate it interactively, showing you the diff first.

One-time first-install caveat: if you have custom skills/agents whose names start with vc- (the reserved kit namespace) and have never run install before, the stale-removal step may flag them. After install, run ls .claude/skills/ .claude/agents/ to confirm. Use a non-vc- prefix (my-, team-, proj-) for your own additions to avoid this entirely.

🤖 Prefer to drive setup from your agent? (full prompt)

Open Claude Code or Codex with your project folder as the working directory, then paste:

First, install the vibecode-pro-max-kit agent harness by running this command:

curl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash

After install completes, run vc-setup and follow the full interactive flow:

1. DETECT — Read package.json (or go.mod, Cargo.toml, pyproject.toml, etc.), detect my
   stack: framework, package manager, monorepo structure, test framework, database, auth.
   Also check for any existing .claude/, process/, or context files.
2. SHOW ME WHAT YOU FOUND — Summarize detection and wait for me to confirm. If this is an
   existing project, tell me what looks good vs what could be improved.
3. ASK ME ABOUT THE PROJECT — Have a real conversation. Ask follow-ups, probe anything
   vague, keep going until you genuinely understand it. Summarize back and confirm.
4. SCAFFOLD — Create the process/ directory. If process/ already exists, show me the plan
   and wait for approval. Never silently move or delete my files.
5. STUDY — Deep-scan and populate process/context/all-context.md with REAL content: repo
   structure, stack + versions, patterns, import aliases, env vars, routes, schema, tests.
   No placeholder text.
6. VALIDATE — Run all validation checks to confirm everything is wired correctly.

Rules: read and preserve good existing context; show me a summary before each major change
and wait for my OK; never create empty placeholder files; ask before reorganizing.

Table of Contents

At a Glance · The Problem · The Fix
Vibe Coding Revolution · Who Is This For · How This Compares · What Makes This Different
How It Works: The Coordinator · The RIPER-5 Lifecycle · Intent Clarification
The Two Quality Loops (PVL + EVL) · Strategy Compare + Model Policy · Autopilot Mode · Feasibility Probes + Validators
Built-in Safety Systems · Pre-Implementation Intelligence · Quality Pipeline
Plan Lifecycle · Phase Programs · Context Groups · Feature Folders · Skill Layers · Self-Improving Memory
What's Inside · Quick Fix + Fast Mode · Kit Lifecycle · Contributing

🎁 At a Glance

🤖

15

Agents
_{One per phase + 6 specialist agents}

⚡

33

Skills
_{20 workflow + 13 helper, matched by keyword}

🪝

10

Hooks
_{Safety rails + automatic context loading}

📜

22

Protocols
_{Shared rules every agent follows}

🛡️

36

Validators
_{Automated checks that catch errors before they ship}

🔧

7

Tools
_{Claude Code · Codex · Cursor · Windsurf · Antigravity · OpenCode · Copilot}

🌍

10

Languages
_{EN · 中文 · 日本語 · 한국어 · VI · PT · DE · FR · ES · हिन्दी}

⚡

30s

Install
_{One command, then your agent guides the rest}

🛩️

Autopilot
_{3 lanes (quick / fast / full) — start at any phase, runs start to finish without stopping}

📌

/goal blocks
_{Short copy-pasteable texts that resume hands-free runs across sessions after a reset}

🔁

vc-autoresearch
_{Find-gaps → fix → repeat loop (shared tool for plans, tests, and evals)}

🔬

Feasibility probes
_{Test-before-you-build verdicts (VIABLE / NOT-VIABLE) before locking in a design}

🔥 The Problem

You ask Claude to "add webhook support." It immediately starts writing code. No questions about your architecture. No check on existing patterns. No plan. You get 400 lines that don't fit your codebase, and you spend an hour fixing it.

But that's just the surface. The deeper problems hit harder:

🧠 Context dies every session Your agent forgets everything it learned. Same mistakes, same questions, every time. No memory, no compounding knowledge.	📄 Docs go stale instantly You wrote great context docs last week. They're already outdated. Nothing auto-updates them as the codebase evolves.
💥 Big tasks collapse mid-way The context window fills, state is lost, the agent starts hallucinating. You restart from scratch on hour 3.	🤝 No specs, no review, no collaboration Your PM can't review what the agent is about to build. There is no written plan to share, discuss, or approve before code is written.
🎭 Architecture decisions are hallucinated The agent invents patterns instead of researching how other codebases solved the same problem.	🚀 Nothing verifies "done" The agent says "all tests pass" — but it never independently re-ran them. You find out in production.

Your agent has intelligence but no process, no memory, and no way to collaborate with your team. Whether you're a developer, a PM, or a CEO who just started vibe coding — this hits everyone the same way, and the fix is the same: give your agent a real development process.

🛠️ The Fix

This kit installs a complete development system into your project — not just a CLAUDE.md, but 15 specialized agents, 33 skills, 10 hooks, and 22 protocols — with a step-locked workflow that makes your agent understand before it builds, and prove before it ships.

📋 Plan-first approach _{PMs and devs review the same written plan before any code is written}	🔄 Self-improving knowledge _{Updates itself every time a feature ships — docs never go stale}
⚡ Hands-free execution _{Survives session resets — runs for hours, not minutes}	🧬 Architecture research _{Studies real codebases before making design decisions}
✅ Two quality checks _{Plans are checked before coding; tests are re-run independently after}	🧭 Smart knowledge routing _{Loads only what is relevant — not your whole knowledge base every time}

The full RIPER-5 flow — 7 phases, every step gated

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%
flowchart TD
    R["RESEARCH\nread-only facts"]
    S["SPEC\nrequirements doc"]
    I["INNOVATE\n2-3 approaches"]
    P["PLAN\ndetailed checklist"]
    V["VALIDATE\nplan → contract\n(PVL loop)"]
    E["EXECUTE\nimplement\n(EVL loop)"]
    U["UPDATE PROCESS\ncapture + archive"]

    R -->|"go"| S
    S -->|"go"| I
    I -->|"go"| P
    P -->|"ENTER VALIDATE"| V
    V -->|"Gate: PASS"| E
    E -->|"gates green"| U

    style R fill:#1565C0,stroke:#0D47A1,color:#FFFFFF
    style S fill:#0277BD,stroke:#01579B,color:#FFFFFF
    style I fill:#E65100,stroke:#BF360C,color:#FFFFFF
    style P fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
    style V fill:#558B2F,stroke:#33691E,color:#FFFFFF
    style E fill:#C62828,stroke:#B71C1C,color:#FFFFFF
    style U fill:#00695C,stroke:#004D40,color:#FFFFFF

In interactive mode, each phase waits for your "go" before it moves on — you stay in the loop at every step. In autopilot or /goal mode, you give approval once up front, then the system drives itself all the way to done. It stops only for three specific hard stops listed below. VALIDATE and the post-EXECUTE re-test are not optional — they are hard gates that block bad work from shipping — and they run automatically in both modes.

The Vibe Coding Revolution

"The hottest new programming language is English."

— Andrej Karpathy

Vibe coding changed who can build software. Plan-first development changes what they can ship.

63% _{of vibe coding users are NOT developers}	16.2M _{citizen developers worldwide (38% YoY growth)}
$4.7B _{vibe coding market growing 38% annually}	25% _{of YC W25 startups had 95%+ AI-generated codebases}

Most tools help you start a project. This kit helps you finish it — with plans your team can review, knowledge that never goes stale, and safety checks that catch mistakes before they ship.

Who Is This For?

"The point isn't who typed it. It's what shipped."

— Garry Tan, YC

🧑‍💼 CEO / Founder "Build me a SaaS with auth, billing, and a landing page" The agent researches your stack, writes an architecture plan you can review, implements with tests, and captures every decision for your technical co-founder to audit later.	📊 Product Manager "Create a dashboard showing MRR, churn, and growth metrics" It generates a PRD-style SPEC, gets your approval before writing code, implements to spec, and archives the plan as searchable project history.
🎨 Designer "Match this Figma screenshot pixel-perfect" The design-aware agent analyzes your mockup, implements component-by-component with your design tokens, and spawns visual comparison checks.	⚙️ Engineer "Refactor the auth module to support RBAC with zero downtime" It researches your current auth code and how other codebases solved RBAC, writes a migration plan that maps which files could be affected, then builds it safely with rollback notes.

How This Compares

Feature	vibecode-pro-max-kit	Superpowers	GSD	gstack
Plan-first lifecycle	Full RIPER-5 (research → spec → innovate → plan → validate → execute → update)	Mandatory workflows	Context-rot fix	Partial
Step-locked safety	Agent tools are restricted per phase (read-only research, no writing in innovate)	Skill-based constraints	Phase separation	None
Quality check loops	Two — PVL (check the plan) + EVL (independently re-run tests)	Per-skill	None automatic	None
Multi-tool support	7 tools via `AGENTS.md` + `SKILL.md` open standards	Claude Code plugin	14 runtimes	1 tool
Auto-improving knowledge	Topic-grouped knowledge, updated after every feature	Plugin memory	Disk-persisted state	Manual
Team collaboration	Shared plans, specs, and review files	Solo	Solo	Solo
Skills system	33 auto-discovered, keyword-matched at every prompt	86 composable skills	Meta-prompting	23 role tools
Large multi-phase projects	Umbrella plans + per-phase inner loop with regression checks	Single task	Single task	Single task
Hands-free mode	Autopilot (3 lanes) + standing `/goal` consent	Manual	Manual	Manual
Installation	30s `curl` + auto-routed setup	Plugin marketplace	npx one-liner	git clone

On runtime breadth: GSD supports 14 runtimes. We support 7 deeply — with full agent harnesses, skill discovery, and lifecycle hooks on every platform. Breadth vs. depth: your choice.

⚡ What Makes This Different

🔒 Step-Locked Tool Restrictions Your agent literally cannot write code during research. RESEARCH is read-only, INNOVATE has no Write, PLAN/VALIDATE write only to `process/`. Real capability limits, not just suggestions.	🎯 The Lead Agent Never Touches Code The coordinator routes, monitors, and drives loops — it never edits source files or runs tests itself. Every edit and every test run happens inside a dedicated sub-agent. No hidden work.
🔍 Automatic Skill Discovery Before handling any request, it scans 33 skills and matches keywords. Say "add webhook support" and `vc-security` + `vc-scenario` are pulled in automatically.	💾 Survives Session Resets Plans, reports, knowledge docs, and learnings all live on disk. The startup hook restores approval gates after a session reset. Nothing is lost.
🛡️ Self-Policing Step Guard When the agent is about to skip a required step, it stops itself: "PHASE JUMPING PREVENTED." A built-in guard against shortcuts.	🔄 Works Across 7 AI Coding Tools Two open standards — `AGENTS.md` and `SKILL.md` — mean zero adapters, zero plugins. Start in Claude Code, switch to Cursor, continue in Codex.

🧭 How It Works — The Coordinator

Your main session is a coordinator (called the orchestrator), not a worker. It does four things and nothing else:

Your request
  → Step 0: Skill Discovery (scan 33 skills, match keywords, attach candidates)
  → Detect intent (feature / bug / question / refactor / UI) + score ambiguity
  → Route to the right agent in a fresh context window
  → Monitor: step compliance, status codes, loop driving

🧑‍✈️ It delegates, never implements Research → `vc-research-agent`. Plan → `vc-plan-agent`. Code → `vc-execute-agent`. The coordinator hands off the right context and waits — it never does the actual work itself.	🚫 No hidden execution — ever The moment a plan with an agreed checklist exists, "ENTER EXECUTE MODE" always launches `vc-execute-agent`. Even a one-line fix goes through it. Tests run only inside a dedicated `vc-tester`. This holds regardless of change size.
📨 Clear status codes, not vague signals Every sub-agent ends with one of: `DONE` · `DONE_WITH_CONCERNS` · `BLOCKED` · `NEEDS_CONTEXT`. The coordinator never ignores a blocker and never retries the same blocked approach three times.	🔁 It drives the fix loops Sub-agents run once, report a result, and stop. Only the coordinator re-launches them. It drives both the PVL (plan-check-fix) and EVL (test-check-fix) loops and owns all tracking.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%
flowchart TD
    REQ["User request"]
    SD["Step 0: Skill Discovery\nscan 33 skills, match keywords"]
    INT{"Detect intent\n+ score ambiguity"}
    RES["vc-research-agent\n(feature / question)"]
    PLN["vc-plan-agent\n(after INNOVATE)"]
    VAL["vc-validate-agent\n(PVL loop)"]
    EXE["vc-execute-agent\n(EXECUTE)"]
    TST["vc-tester\n(EVL loop)"]
    UPD["vc-update-process-agent\n(closeout)"]
    MON["Monitor\nstatus codes · loop driving\nno inline execution ever"]

    REQ --> SD --> INT
    INT -->|"feature / research"| RES
    INT -->|"plan phase"| PLN
    INT -->|"validate phase"| VAL
    INT -->|"execute phase"| EXE
    EXE -.->|"EVL"| TST
    INT -->|"update phase"| UPD
    RES --> MON
    PLN --> MON
    VAL --> MON
    TST --> MON
    UPD --> MON

    style REQ fill:#1565C0,stroke:#0D47A1,color:#FFFFFF
    style SD fill:#0277BD,stroke:#01579B,color:#FFFFFF
    style INT fill:#E65100,stroke:#BF360C,color:#FFFFFF
    style RES fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
    style PLN fill:#558B2F,stroke:#33691E,color:#FFFFFF
    style VAL fill:#558B2F,stroke:#33691E,color:#FFFFFF
    style EXE fill:#C62828,stroke:#B71C1C,color:#FFFFFF
    style TST fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF
    style UPD fill:#00695C,stroke:#004D40,color:#FFFFFF
    style MON fill:#37474F,stroke:#263238,color:#FFFFFF

Why this matters: an agent that can both decide and secretly edit will find ways to skip the plan. By separating the coordinator from the workers (sub-agents), the process becomes structurally honest — the only way to write code is to go through the required steps.

📊 The RIPER-5 Lifecycle

Phase	What happens	Agent	You say
🔍 RESEARCH	Read-only fact gathering — codebase + web. Never modifies files.	`vc-research-agent`	(auto on feature requests)
📝 SPEC	Product-discovery requirements doc — user stories, acceptance criteria, out-of-scope — for your review before any design.	`vc-spec-agent`	`go` / `ENTER SPEC MODE`
💡 INNOVATE	Explore 2-3 approaches with trade-offs. Decision summary (chosen + rejected + why).	`vc-innovate-agent`	`go`
📋 PLAN	Write the detailed spec: touchpoints, public contracts, which files it can touch, verification evidence, resume handoff.	`vc-plan-agent`	`go`
✅ VALIDATE	Turn the plan into an agreed checklist (V1–V7 checkpoints). Verdict: PASS / CONDITIONAL / BLOCKED. Runs the PVL loop.	`vc-validate-agent`	`ENTER VALIDATE MODE`
⚡ EXECUTE	Implement exactly the plan. Progress notes to the phase report, deviation protocol, self-review. Then the EVL loop re-runs the checkpoints.	`vc-execute-agent`	`ENTER EXECUTE MODE`
🧠 UPDATE PROCESS	Capture learnings, update context, archive plan, write closeout packet.	`vc-update-process-agent`	(recommended after non-trivial work)

📝 Why SPEC is its own phase: most harnesses jump from "understand" to "design." Inserting a product-discovery SPEC step means you (or your PM) sign off on what is being built — in plain user stories and acceptance criteria — before the agent debates how. It is the cheapest possible place to catch a misunderstanding. (Inside a phase program's inner loop, SPEC is skipped — the umbrella SPEC governs all phases.)

The SPEC is the measuring stick. It states the expected behavior in simple terms you can scan in a minute. Every phase after it — Innovate, Plan, Validate, Execute — checks back against it and asks the same question: is what we are building actually what you asked for? When the work starts to drift, the SPEC is what catches it.

flowchart TD
    U["You: what I really want<br>(plain words)"] --> S["📝 SPEC<br>expected behavior + acceptance<br>criteria — you approve"]
    S --> I["💡 INNOVATE"]
    S --> P["📋 PLAN"]
    S --> V["✅ VALIDATE"]
    S --> E["⚡ EXECUTE"]
    I -.->|"check back"| Q{"Is this what<br>you asked for?"}
    P -.->|"check back"| Q
    V -.->|"check back"| Q
    E -.->|"check back"| Q
    Q -->|yes| GO["keep building"]
    Q -->|no| S

💻 Example sessions

# 🆕 Feature request
You: "add webhook support to the API"
→ Skill discovery surfaces: vc-scenario, vc-security
→ research-agent gathers context (read-only, can't touch code)
→ "go" → spec-agent writes requirements doc → you approve
→ "go" → innovate-agent compares approaches → decision summary
→ "go" → plan-agent writes the plan, listing which files it will touch
→ "ENTER VALIDATE MODE" → validate-agent gates the plan (PVL loop) → Gate: PASS
→ "ENTER EXECUTE MODE" → execute-agent implements → tester re-runs gates (EVL) → reviewer → git-manager
→ Closeout packet: what changed, what's verified, recommended next step

# 🐛 Bug fix
You: "login redirect is broken"
→ Routes to vc-debugger → gathers evidence FIRST → 2-3 competing hypotheses
→ Systematically eliminates each → root cause with proof chain
→ execute-agent implements the fix → EVL re-test → quality pipeline

# ⏩ Fast mode
You: "ENTER FAST MODE - add rate limiting middleware"
→ Compressed RESEARCH + SPEC + INNOVATE + PLAN + VALIDATE in one pass
→ Mandatory safety pause after VALIDATE → you review → "ENTER EXECUTE MODE"

# 🤖 Autopilot (hands-free)
You: "autopilot full: build a notifications system"
→ ONE consolidated clarification round → provisional /goal block (standing consent)
→ Drives the full RIPER-5 sequence autonomously, pausing only on hard stops

# 🏗️ Large program
You: "build a full testing platform"
→ Umbrella plan + phase plans in a feature folder
→ Each phase inner loop: research → innovate → plan → PVL → execute → EVL → update
→ Progress survives context compaction — durable reports on disk

🎯 Intent Clarification

Before routing, the lead agent scores your request's ambiguity on 4 binary signals (0–4) and picks a tier. It asks questions only when they would actually change what it does.

Tier	When	Behavior
Tier 0 — silent auto-route	Score 0–1, or you said "go" / "just do it", or resuming a plan	Routes immediately, no questions
Tier 1 — inline summary	Score 2	States its understanding + chosen route in one line, then proceeds
Tier 2 — questions	Score 3+	Asks focused multiple-choice questions before routing

🧠 Two rounds max. If still unclear after Tier 2, it asks one final plain question, then defaults to research with the narrowest reasonable scope. It never loops clarification forever. After RESEARCH, it re-checks intent — if research shows the request was different from what was assumed, it re-presents; if confirmed, it proceeds without re-asking.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%
flowchart TD
    REQ["User request"]
    SCORE{"ambiguity score\n0–4 binary signals"}
    AUTO["Auto-skip conditions\n(go / continue / mid-phase\n/ trivial / explicit mode\n/ resuming plan / pure info)"]
    T0["Tier 0\nsilent auto-route\n(score 0–1 OR auto-skip)"]
    T1["Tier 1\ninline summary\n(score 2)"]
    T2["Tier 2\nask focused questions\n(score 3+)"]
    ROUTE["Route to matching agent\n(research / plan / execute / …)"]
    STILL{"still unclear\nafter Tier 2?"}
    FINAL["One final plain question\n(max 2 clarification rounds)"]
    NARROW["Default: vc-research-agent\nnarrowest reasonable scope"]

    REQ --> AUTO
    AUTO -->|"auto-skip matches"| T0
    AUTO -->|"no auto-skip"| SCORE
    SCORE -->|"0–1"| T0
    SCORE -->|"2"| T1
    SCORE -->|"3+"| T2
    T0 --> ROUTE
    T1 --> ROUTE
    T2 --> STILL
    STILL -->|"resolved"| ROUTE
    STILL -->|"still unclear"| FINAL --> NARROW

    style REQ fill:#1565C0,stroke:#0D47A1,color:#FFFFFF
    style AUTO fill:#0277BD,stroke:#01579B,color:#FFFFFF
    style SCORE fill:#E65100,stroke:#BF360C,color:#FFFFFF
    style T0 fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
    style T1 fill:#558B2F,stroke:#33691E,color:#FFFFFF
    style T2 fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF
    style ROUTE fill:#C62828,stroke:#B71C1C,color:#FFFFFF
    style STILL fill:#F57F17,stroke:#F9A825,color:#000000
    style FINAL fill:#AD1457,stroke:#880E4F,color:#FFFFFF
    style NARROW fill:#00695C,stroke:#004D40,color:#FFFFFF

✅ The Two Quality Loops — PVL + EVL

Most harnesses check once, if at all. This one wraps EXECUTE in two independent loops — one before code is written, one after.

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '15px', 'lineColor': '#8888AA'}} }%%
flowchart TD
    PLAN["📋 PLAN written"]
    PVL{"✅ PVL\nValidate the plan\nV1–V7 gates"}
    PASS["Gate: PASS"]
    SUPP["📝 plan-agent supplements\n(addresses gaps)"]
    EXEC["⚡ EXECUTE\nimplement the plan"]
    EVL{"🧪 EVL\ntester re-runs the\nvalidate-contract gates"}
    FIX["⚡ execute-agent\nsupplement (fix gate)"]
    DONE["🧠 UPDATE PROCESS"]

    PLAN --> PVL
    PVL -->|"CONDITIONAL / BLOCKED"| SUPP
    SUPP -->|"re-run from V1"| PVL
    PVL -->|"PASS"| PASS
    PASS -->|"ENTER EXECUTE"| EXEC
    EXEC --> EVL
    EVL -->|"gate fails"| FIX
    FIX -->|"re-run"| EVL
    EVL -->|"all gates green"| DONE

    style PLAN fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
    style PVL fill:#558B2F,stroke:#33691E,color:#FFFFFF
    style PASS fill:#00695C,stroke:#004D40,color:#FFFFFF
    style SUPP fill:#E65100,stroke:#BF360C,color:#FFFFFF
    style EXEC fill:#C62828,stroke:#B71C1C,color:#FFFFFF
    style EVL fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF
    style FIX fill:#AD1457,stroke:#880E4F,color:#FFFFFF
    style DONE fill:#00695C,stroke:#004D40,color:#FFFFFF

📋 PVL — Plan-Validate-Fix

Before EXECUTE, vc-validate-agent runs the plan through V1–V7 checkpoints — splitting the work across several agents to cover infra, test coverage, breaking changes, security, and per-section feasibility. A first-pass CONDITIONAL or BLOCKED is never the end — it routes back to vc-plan-agent to update the plan, then re-checks from V1.

_{Tracked by vc-autoresearch (domain: plan) — a find-gaps-and-fix loop. 10-cycle cap. Plateau detection. Only Gate: PASS (or a CONDITIONAL you explicitly accept) unlocks EXECUTE.}

🧪 EVL — Execute-Validate-Fix

After EXECUTE reports done — even when it claims all checkpoints are green — the lead agent always spawns vc-tester to independently re-run the exact agreed-checklist test commands. A failing checkpoint routes to a scoped vc-execute-agent fix, then re-tests.

_{Tracked by vc-autoresearch (domain: tests). 10-cycle cap. The execute-agent's own internal "iterate until green" loop never substitutes for this independent confirmation.}

💎 The verdict ladder: PASS → proceed · CONDITIONAL → fixable gaps; the loop fires (or you accept them on record) · BLOCKED → a deeper problem; returns to PLAN (under autopilot: the gap goes to a backlog and the run continues).

🔁 vc-autoresearch — Shared Loop Engine

Both PVL and EVL use the same tracking layer: vc-autoresearch — a find-gaps → fix → repeat loop. The lead agent drives the loop — it owns the round counter, per-round reports, TSV log, and plateau/cap/regression checks. Worker agents are fire-and-forget: they return a result and stop. No agent re-spawns itself or spawns another phase agent.

The same engine can run on its own: "harden this spec", "fix all lint", "improve test coverage", "improve these docs" — any repeated find-gaps-and-fix task across 6 domains (spec · tests · ux · docs · plan · errors).

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%
flowchart TD
    START["Start loop\n(orchestrator init results.tsv\nheader + baseline row)"]
    FIND["Find gaps\n(validate-agent / tester\nreturns gap list)"]
    RPT["Write iteration report\n{slug}-iteration-{NNN}_REPORT_{dd-mm-yy}.md"]
    TSV["Append results.tsv row\n(cycle N, gap count)"]
    FIX["Fix gaps\n(plan-agent supplement\nOR execute-agent supplement)"]
    CHK["Guard checks\nplateau? cap hit? regression?"]
    RECHECK["Re-check\n(re-run validate / tester)"]
    SUCC["SUCCESS\nall-clear 2 consecutive rounds"]
    HALT["HALT\nplateau / 10-cycle cap / regression"]

    START --> FIND --> RPT --> TSV --> FIX --> CHK
    CHK -->|"safe to continue"| RECHECK
    RECHECK --> FIND
    CHK -->|"plateau / cap / regression"| HALT
    FIND -->|"no gaps found (×2)"| SUCC

    style START fill:#1565C0,stroke:#0D47A1,color:#FFFFFF
    style FIND fill:#E65100,stroke:#BF360C,color:#FFFFFF
    style RPT fill:#558B2F,stroke:#33691E,color:#FFFFFF
    style TSV fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
    style FIX fill:#C62828,stroke:#B71C1C,color:#FFFFFF
    style CHK fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF
    style RECHECK fill:#0277BD,stroke:#01579B,color:#FFFFFF
    style SUCC fill:#00695C,stroke:#004D40,color:#FFFFFF
    style HALT fill:#B71C1C,stroke:#7F0000,color:#FFFFFF

Mode	Does	Stops when
`vc-autoresearch` (core)	find gaps → fix → repeat	no gaps found OR metric goal hit
`vc-autoresearch:probe`	8 personas interrogate the corpus until saturation	no new constraints for 3 rounds
`vc-autoresearch:reason`	adversarial debate with blind judges	judges converge or iteration cap
`vc-autoresearch:evals`	analyze TSV results — trends, plateaus, recommendations	analysis only

Stop conditions: SUCCESS (all-clear two rounds in a row) · HALT_PLATEAU (no progress for 3 rounds) · HALT_CAP (10-round hard limit) · HALT_REGRESSION (a check that was passing now fails).

👥 Strategy Compare + Model Policy

At every phase transition, the lead agent invokes vc-agent-strategy-compare to recommend how to run the next phase — with cost estimates.

Strategy	When	Coordination
Sequential	Work depends on prior output	One agent at a time
Parallel subagents	Independent dimensions, fire-and-forget	None — lead agent collects + combines results
Workflow	Predictable splitting of work across a list	Scripted steps
Agent team	Agents must talk to each other mid-run (e.g. each touches separate files across 3+ phase plans)	TeamCreate + shared task list + SendMessage

%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%
flowchart TD
    SS["vc-agent-strategy-compare\n(every phase transition)"]
    SC{"signal score\n0–7"}
    SEQ["Sequential\none agent at a time\n(output feeds next)"]
    PAR["Parallel subagents\nfire-and-forget\n(independent dimensions)"]
    WF["Workflow\nscripted steps\nacross a list"]
    TEAM["Agent team\nTeamCreate + TaskCreate\n+ SendMessage\n(must coordinate mid-run)"]
    MC{"which phase?"}
    OPUS["🔴 opus\n(EXECUTE only)"]
    SONNET["🔵 sonnet\n(every other phase)"]

    SS --> SC
    SC -->|"low / dependent"| SEQ
    SC -->|"mid / independent"| PAR
    SC -->|"predictable split"| WF
    SC -->|"high / must coordinate\nor 3+ phase plans"| TEAM
    SS --> MC
    MC -->|"EXECUTE / fast-mode\nquick-fix (real code)"| OPUS
    MC -->|"Research / Spec\nInnovate / Plan\nValidate / Update\nall reviewers"| SONNET

    style SS fill:#1565C0,stroke:#0D47A1,color:#FFFFFF
    style SC fill:#E65100,stroke:#BF360C,color:#FFFFFF
    style SEQ fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF
    style PAR fill:#558B2F,stroke:#33691E,color:#FFFFFF
    style WF fill:#00695C,stroke:#004D40,color:#FFFFFF
    style TEAM fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF
    style MC fill:#0277BD,stroke:#01579B,color:#FFFFFF
    style OPUS fill:#C62828,stroke:#B71C1C,color:#FFFFFF
    style SONNET fill:#37474F,stroke:#263238,color:#FFFFFF

⚠️ "Agent team" means the real machinery — named teammates, a shared task list, and inter-agent messaging — not bare parallel agents called a "team." It is required (not optional) for creating 3+ phase plans and for multi-file edits where agents must each stay in their own files. Only a true team can communicate while running.

🧮 Model selection policy

Phase	Model	Why
EXECUTE (+ fast-mode, quick-fix doing real code)	🔴 opus	Real source edits, builds, migrations
Research · Spec · Innovate · Plan · Validate · Update · all reviewers/researchers	🔵 sonnet	Planning and analysis — cheaper, plenty capable

When work is split across several agents, only the coding agent uses opus. Every reviewer, researcher, validator, and planner uses sonnet. The lead agent names the model each time it spawns a worker.

🤖 Autopilot Mode — Hands-Free RIPER-5

Say autopilot [task] (or run autopilot, autonomous mode, ENTER AUTOPILOT MODE) and the agent runs the entire remaining RIPER-5 sequence with one clarification round up front — then no more pauses until it is done.

…view the full README on GitHub.

Platforms	cli, api, desktop, web
Operating systems	—
AI compatibility	claude
License	MIT
Pricing	open-source
Language	JavaScript