{"id":51215845,"url":"https://github.com/withkynam/vibecode-pro-max-kit","last_synced_at":"2026-06-28T07:00:58.341Z","repository":{"id":360655481,"uuid":"1250957639","full_name":"withkynam/vibecode-pro-max-kit","owner":"withkynam","description":"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, \u0026 workflow on autopilot loops with 0 need for human gate. Kills context rot, ships features, not spaghetti. Claude Code \u0026 Codex. Any stack","archived":false,"fork":false,"pushed_at":"2026-06-20T03:06:08.000Z","size":14854,"stargazers_count":949,"open_issues_count":19,"forks_count":205,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-06-20T05:08:49.262Z","etag":null,"topics":["agentic","ai-agents","ai-coding-assistant","ai-development","ai-workflow","anthropic","claude","claude-code","cli-tools","code-quality","codex","coding-agents","cursor","developer-tools","llm","openai","prompt-engineering","typescript","vibe-coding","vibecoding"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/withkynam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-27T05:46:25.000Z","updated_at":"2026-06-20T03:06:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/withkynam/vibecode-pro-max-kit","commit_stats":null,"previous_names":["withkynam/vibecode-pro-max-kit"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/withkynam/vibecode-pro-max-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withkynam%2Fvibecode-pro-max-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withkynam%2Fvibecode-pro-max-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withkynam%2Fvibecode-pro-max-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withkynam%2Fvibecode-pro-max-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/withkynam","download_url":"https://codeload.github.com/withkynam/vibecode-pro-max-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withkynam%2Fvibecode-pro-max-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34880189,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic","ai-agents","ai-coding-assistant","ai-development","ai-workflow","anthropic","claude","claude-code","cli-tools","code-quality","codex","coding-agents","cursor","developer-tools","llm","openai","prompt-engineering","typescript","vibe-coding","vibecoding"],"created_at":"2026-06-28T04:01:00.196Z","updated_at":"2026-06-28T07:00:58.324Z","avatar_url":"https://github.com/withkynam.png","language":"JavaScript","funding_links":[],"categories":["⭐ 精选第三方技能","🛠️ Tools \u0026 Utilities"],"sub_categories":["💻 开发效率"],"readme":"\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eEnglish\u003c/strong\u003e |\n  \u003ca href=\"docs/i18n/README.zh-CN.md\"\u003e简体中文\u003c/a\u003e |\n  \u003ca href=\"docs/i18n/README.ja-JP.md\"\u003e日本語\u003c/a\u003e |\n  \u003ca href=\"docs/i18n/README.ko-KR.md\"\u003e한국어\u003c/a\u003e |\n  \u003ca href=\"docs/i18n/README.vi-VN.md\"\u003eTiếng Việt\u003c/a\u003e |\n  \u003ca href=\"docs/i18n/README.pt-BR.md\"\u003ePortuguês\u003c/a\u003e |\n  \u003ca href=\"docs/i18n/README.es.md\"\u003eEspañol\u003c/a\u003e |\n  \u003ca href=\"docs/i18n/README.de.md\"\u003eDeutsch\u003c/a\u003e |\n  \u003ca href=\"docs/i18n/README.fr.md\"\u003eFrançais\u003c/a\u003e |\n  \u003ca href=\"docs/i18n/README.hi.md\"\u003eहिंदी\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n\u003ca href=\"https://flowser.ai\"\u003e\n  \u003cimg src=\"assets/flowser-logo.svg\" alt=\"Flowser\" width=\"120\"\u003e\n\u003c/a\u003e\n\n*Built by world-class engineers, for vibecoders at*\u003cbr\u003e\n*[flowser.ai](https://flowser.ai) — AI Agents with computers for GTM*\n\n\u003cbr\u003e\n\n# vibecode-pro-max-kit\n\n\u003cbr\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://media.tenor.com/q_5em_iLaxoAAAAC/tanjiro-i-water-style.gif\" alt=\"Flow like water\" width=\"480\"\u003e\n  \u003cbr\u003e\u003cbr\u003e\n  \u003cem\u003e\"Total Concentration — Spec Breathing, Tenth Form: the Vibe Flow never breaks.\"\u003c/em\u003e\u003cbr\u003e\n  \u003cstrong\u003e— Tanjiro Kamado\u003c/strong\u003e\n\u003c/p\u003e\n\n*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.*\n\n\u003ctable align=\"center\"\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\u003cstrong\u003e📦 One-command install\u003c/strong\u003e\u003cbr\u003eOne \u003ccode\u003ecurl\u003c/code\u003e line drops it into any project. It detects new vs. returning users and never overwrites your files.\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\u003cstrong\u003e🌐 Works everywhere\u003c/strong\u003e\u003cbr\u003eAny tech stack, any language, and any AI coding agent — Claude Code, Codex, Cursor, Windsurf, Copilot, and more.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🧭 RIPER-5 plan-first workflow\u003c/strong\u003e\u003cbr\u003e7 gated phases (Research → Spec → Innovate → Plan → Validate → Execute → Update-Process) stop the agent from jumping straight to code.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🚀 Autopilot mode (quick / fast / full)\u003c/strong\u003e\u003cbr\u003eStart a hands-free run at any phase with a single phrase. Three lanes match the ceremony to the risk.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🎯 \u003ccode\u003e/goal\u003c/code\u003e — the run-until-done token\u003c/strong\u003e\u003cbr\u003eOne copy-pasteable block keeps the agent running phase after phase without stopping — and resumes the run in a fresh session.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🔁 PVL + EVL self-healing loops\u003c/strong\u003e\u003cbr\u003ePlan-check-fix and test-check-fix loops find gaps, fix them, and re-check on their own — up to 10 cycles each.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🔍 vc-autoresearch\u003c/strong\u003e\u003cbr\u003eA reusable find-gaps → fix → repeat loop you can point at plans, tests, specs, docs, or evals.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🧪 Feasibility probes\u003c/strong\u003e\u003cbr\u003eTest-before-you-build verdicts (VIABLE / NOT-VIABLE) before the agent commits to any design approach.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🎛️ Smart strategy picker\u003c/strong\u003e\u003cbr\u003eBefore each phase it weighs one agent vs. many vs. a coordinated team — with cost estimates — and picks the cheapest that fits.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🧮 Smart model use\u003c/strong\u003e\u003cbr\u003eThe expensive model only writes code; the cheaper model does everything else. Lower cost, same quality.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🤔 Intent clarification\u003c/strong\u003e\u003cbr\u003eWhen a request is vague, the agent asks a few sharp questions up front instead of guessing and building the wrong thing.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🛡️ 36 validators\u003c/strong\u003e\u003cbr\u003eMechanical correctness checks — not opinions — guard the kit's own structure and catch drift before it ships.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🏗️ Phase programs\u003c/strong\u003e\u003cbr\u003eLarge projects are split into independent phases with quality gates between them, so big work doesn't fall apart.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🔀 Programs that reshape themselves\u003c/strong\u003e\u003cbr\u003eAs it learns, the agent inserts new phases, reorders work, and skips blocked steps — the plan adapts on the fly.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🧠 Never loses its place\u003c/strong\u003e\u003cbr\u003eProgress notes are written to disk every phase, so a run survives a memory reset and picks up exactly where it left off.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e📚 Self-improving project memory\u003c/strong\u003e\u003cbr\u003eIt learns your codebase on setup and keeps its own shared notes current after every feature ships, so docs never go stale.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e⚡ Quick Fix + Fast Mode\u003c/strong\u003e\u003cbr\u003eLight lanes for small changes skip the heavy ceremony, so a one-line fix stays a one-line fix.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🧱 Layered, auto-discovered skills\u003c/strong\u003e\u003cbr\u003eSkills are organized in clear layers and discovered automatically — the agent always finds the right tool for the step.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🤖 15 agents · 33 skills · 10 hooks\u003c/strong\u003e\u003cbr\u003eA full team of specialized agents, reusable skills, and safety hooks, all wired together out of the box.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🔄 Full kit lifecycle\u003c/strong\u003e\u003cbr\u003eInstall, setup, update, and publish are all one command each — keeping every project on the latest kit safely.\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e📝 SPEC — your plain-language sign-off\u003c/strong\u003e\u003cbr\u003eBefore any design, you state what to build in simple user stories — the cheapest place to catch a misunderstanding.\u003c/td\u003e\n\u003ctd valign=\"top\"\u003e\u003cstrong\u003e🎯 Always checks your intent\u003c/strong\u003e\u003cbr\u003eEvery later phase measures back against your SPEC: is what we're building actually what you asked for?\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/withkynam/vibecode-pro-max-kit/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/withkynam/vibecode-pro-max-kit\" alt=\"Stars\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/withkynam/vibecode-pro-max-kit/network/members\"\u003e\u003cimg src=\"https://img.shields.io/github/forks/withkynam/vibecode-pro-max-kit\" alt=\"Forks\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/withkynam/vibecode-pro-max-kit\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/withkynam/vibecode-pro-max-kit/graphs/contributors\"\u003e\u003cimg src=\"https://img.shields.io/github/contributors/withkynam/vibecode-pro-max-kit\" alt=\"Contributors\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/withkynam/vibecode-pro-max-kit/actions/workflows/validate.yml\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/withkynam/vibecode-pro-max-kit/validate.yml\" alt=\"CI\"\u003e\u003c/a\u003e\n  \u003ca href=\"CHANGELOG.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/version-3.2.5-2EA043\" alt=\"Version\"\u003e\u003c/a\u003e\n  \u003cimg src=\"https://img.shields.io/badge/agents-15-orange\" alt=\"Agents\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/skills-33-purple\" alt=\"Skills\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/hooks-10-blue\" alt=\"Hooks\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/tools-7_%E2%9C%93-38BDF8\" alt=\"7 Tools\"\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cstrong\u003eThe simplest, most flexible, team-friendly coding kit for\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\n  \u003ca href=\"https://github.com/anthropics/claude-code\"\u003e\u003cimg src=\"https://img.shields.io/badge/Claude_Code-191919?style=for-the-badge\u0026logo=anthropic\u0026logoColor=white\" alt=\"Claude Code\"\u003e\u003c/a\u003e\u0026nbsp;\n  \u003ca href=\"https://github.com/openai/codex\"\u003e\u003cimg src=\"https://img.shields.io/badge/Codex_CLI-412991?style=for-the-badge\u0026logo=openai\u0026logoColor=white\" alt=\"Codex CLI\"\u003e\u003c/a\u003e\u0026nbsp;\n  \u003ca href=\"https://cursor.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/Cursor-000?style=for-the-badge\u0026logo=cursor\u0026logoColor=white\" alt=\"Cursor\"\u003e\u003c/a\u003e\u0026nbsp;\n  \u003ca href=\"https://windsurf.com\"\u003e\u003cimg src=\"https://img.shields.io/badge/Windsurf-09B6A2?style=for-the-badge\u0026logo=codeium\u0026logoColor=white\" alt=\"Windsurf\"\u003e\u003c/a\u003e\u003cbr\u003e\n  \u003ca href=\"https://github.com/google-gemini/gemini-cli\"\u003e\u003cimg src=\"https://img.shields.io/badge/Antigravity-8E75B2?style=for-the-badge\u0026logo=googlegemini\u0026logoColor=white\" alt=\"Antigravity\"\u003e\u003c/a\u003e\u0026nbsp;\n  \u003ca href=\"https://github.com/opencode-ai/opencode\"\u003e\u003cimg src=\"https://img.shields.io/badge/OpenCode-333?style=for-the-badge\" alt=\"OpenCode\"\u003e\u003c/a\u003e\u0026nbsp;\n  \u003ca href=\"https://github.com/features/copilot\"\u003e\u003cimg src=\"https://img.shields.io/badge/GitHub_Copilot-000?style=for-the-badge\u0026logo=githubcopilot\u0026logoColor=white\" alt=\"GitHub Copilot\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003cem\u003eWorks across any tech stack, any language, any project\u003c/em\u003e\u003cbr\u003e\u003cbr\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://skillicons.dev/icons?i=ts%2Cjs%2Creact%2Cnextjs%2Cvue%2Cnuxt%2Csvelte%2Cangular%2Cnodejs%2Cexpress%2Cbun%2Cpython%2Cdjango%2Cflask%2Cfastapi\u0026theme=dark\u0026perline=15\" /\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://skillicons.dev/icons?i=ts%2Cjs%2Creact%2Cnextjs%2Cvue%2Cnuxt%2Csvelte%2Cangular%2Cnodejs%2Cexpress%2Cbun%2Cpython%2Cdjango%2Cflask%2Cfastapi\u0026theme=light\u0026perline=15\" /\u003e\n    \u003cimg alt=\"Tech Stack Row 1\" src=\"https://skillicons.dev/icons?i=ts,js,react,nextjs,vue,nuxt,svelte,angular,nodejs,express,bun,python,django,flask,fastapi\u0026perline=15\" /\u003e\n  \u003c/picture\u003e\n  \u003cbr\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://skillicons.dev/icons?i=ruby%2Crails%2Cgo%2Crust%2Cjava%2Cspring%2Ckotlin%2Cswift%2Cphp%2Claravel%2Ccs%2Cdotnet%2Celixir%2Cgraphql%2Cprisma\u0026theme=dark\u0026perline=15\" /\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://skillicons.dev/icons?i=ruby%2Crails%2Cgo%2Crust%2Cjava%2Cspring%2Ckotlin%2Cswift%2Cphp%2Claravel%2Ccs%2Cdotnet%2Celixir%2Cgraphql%2Cprisma\u0026theme=light\u0026perline=15\" /\u003e\n    \u003cimg alt=\"Tech Stack Row 2\" src=\"https://skillicons.dev/icons?i=ruby,rails,go,rust,java,spring,kotlin,swift,php,laravel,cs,dotnet,elixir,graphql,prisma\u0026perline=15\" /\u003e\n  \u003c/picture\u003e\n  \u003cbr\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://skillicons.dev/icons?i=supabase%2Cfirebase%2Cpostgres%2Cmongodb%2Credis%2Cdocker%2Ckubernetes%2Caws%2Cgcp%2Cazure%2Cvercel%2Ccloudflare%2Ctailwind%2Celectron\u0026theme=dark\u0026perline=15\" /\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://skillicons.dev/icons?i=supabase%2Cfirebase%2Cpostgres%2Cmongodb%2Credis%2Cdocker%2Ckubernetes%2Caws%2Cgcp%2Cazure%2Cvercel%2Ccloudflare%2Ctailwind%2Celectron\u0026theme=light\u0026perline=15\" /\u003e\n    \u003cimg alt=\"Tech Stack Row 3\" src=\"https://skillicons.dev/icons?i=supabase,firebase,postgres,mongodb,redis,docker,kubernetes,aws,gcp,azure,vercel,cloudflare,tailwind,electron\u0026perline=15\" /\u003e\n  \u003c/picture\u003e\n  \u003cbr\u003e\n  \u003cp\u003e\u003cem\u003eNot just for show. When you run \u003ccode\u003evc-setup\u003c/code\u003e, agents scan your codebase,\u003cbr\u003e\n  detect your stack, and build project-specific knowledge groups that every skill reads before it works.\u003cbr\u003e\n  Other harnesses lock agents to one language — \u003ccode\u003erust-review-agent\u003c/code\u003e, \u003ccode\u003epython-linter\u003c/code\u003e — useless elsewhere.\u003cbr\u003e\n  This one adapts to any combination above and builds up knowledge as you ship.\u003c/em\u003e\u003c/p\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\n## ⚡ Get Started — One Command, 30 Seconds\n\n\u003e **Prerequisites:** Node.js ≥ 22, git, bash (macOS / Linux / WSL / **Git Bash**; on Alpine: `apk add bash`).\n\u003e\n\u003e **Windows:** the installer is a bash script — run it inside **Git Bash** (ships with [Git for Windows](https://git-scm.com/download/win)) 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](https://learn.microsoft.com/en-us/windows/apps/get-started/enable-your-device-for-development).\n\n**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.*\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash\n```\n\nWhen it finishes, it prints one of two messages — **read the bottom of the output and do exactly what it says:**\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch3\u003e🆕 Fresh project\u003c/h3\u003e\nInstaller detects no harness and prints:\n\u003cbr\u003e\u003cbr\u003e\n\u003ccode\u003eNext: Run: claude → Say: \"Run vc-setup\"\u003c/code\u003e\n\u003cbr\u003e\u003cbr\u003e\n\u003cstrong\u003e→ Open your agent and say \u003ccode\u003eRun vc-setup\u003c/code\u003e\u003c/strong\u003e\n\u003cbr\u003e\u003cbr\u003e\n\u003csub\u003evc-setup detects your tech stack, creates the \u003ccode\u003eprocess/\u003c/code\u003e folder, scans your codebase, and fills in your \u003cem\u003ereal\u003c/em\u003e architecture, conventions, and test commands — a conversation, not a checklist.\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch3\u003e🔄 Existing harness (upgrade)\u003c/h3\u003e\nInstaller detects a prior install and prints:\n\u003cbr\u003e\u003cbr\u003e\n\u003ccode\u003eNext (upgrade detected): Run: claude → Say: \"Run vc-update\"\u003c/code\u003e\n\u003cbr\u003e\u003cbr\u003e\n\u003cstrong\u003e→ Open your agent and say \u003ccode\u003eRun vc-update\u003c/code\u003e\u003c/strong\u003e\n\u003cbr\u003e\u003cbr\u003e\n\u003csub\u003evc-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 \u003cstrong\u003ezero data loss\u003c/strong\u003e. Your \u003ccode\u003eprocess/\u003c/code\u003e is never touched.\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e 💡 **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.\n\n\u003cbr\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📦 What install puts on disk (non-destructive)\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n```\nyour-project/\n├── .claude/\n│   ├── agents/              # 🤖 15 agent definitions (.md)\n│   ├── skills/              # ⚡ 33 skills (each a dir with SKILL.md)\n│   └── hooks/               # 🪝 10 lifecycle hooks (.cjs / .mjs)\n├── .codex/agents/           # 🔄 Mirrored agents for Codex\n├── .agents/skills →         # 🔗 Symlink to .claude/skills (Codex discovery)\n├── CLAUDE.md                # 📋 Orchestrator + routing rules\n├── AGENTS.md                # 📖 Agent + skill registry (cross-tool)\n└── process/\n    └── development-protocols/  # 📜 22 shared workflow docs (seeded by install)\n                                #    context/, plans, features → built by vc-setup\n```\n\n- **Non-destructive.** Your existing `.claude/skills/`, `.claude/agents/`, `process/`, and `settings.json` are never wiped. Only kit-owned files are written or updated.\n- **Existing config?** Backed up to `.vibecode-backup/`; your `settings.json` is restored afterward.\n- **Existing `CLAUDE.md`?** Backed up as `CLAUDE.md.pre-vibecode`.\n- **Existing `process/`?** Never touched by install — `vc-setup` / `vc-update` migrate it interactively, showing you the diff first.\n\n\u003e **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.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🤖 Prefer to drive setup from your agent? (full prompt)\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cbr\u003e\n\n\u003e Open Claude Code or Codex **with your project folder as the working directory**, then paste:\n\n```\nFirst, install the vibecode-pro-max-kit agent harness by running this command:\n\ncurl -fsSL https://raw.githubusercontent.com/withkynam/vibecode-pro-max-kit/main/install.sh | bash\n\nAfter install completes, run vc-setup and follow the full interactive flow:\n\n1. DETECT — Read package.json (or go.mod, Cargo.toml, pyproject.toml, etc.), detect my\n   stack: framework, package manager, monorepo structure, test framework, database, auth.\n   Also check for any existing .claude/, process/, or context files.\n2. SHOW ME WHAT YOU FOUND — Summarize detection and wait for me to confirm. If this is an\n   existing project, tell me what looks good vs what could be improved.\n3. ASK ME ABOUT THE PROJECT — Have a real conversation. Ask follow-ups, probe anything\n   vague, keep going until you genuinely understand it. Summarize back and confirm.\n4. SCAFFOLD — Create the process/ directory. If process/ already exists, show me the plan\n   and wait for approval. Never silently move or delete my files.\n5. STUDY — Deep-scan and populate process/context/all-context.md with REAL content: repo\n   structure, stack + versions, patterns, import aliases, env vars, routes, schema, tests.\n   No placeholder text.\n6. VALIDATE — Run all validation checks to confirm everything is wired correctly.\n\nRules: read and preserve good existing context; show me a summary before each major change\nand wait for my OK; never create empty placeholder files; ask before reorganizing.\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003eTable of Contents\u003c/summary\u003e\n\n- [At a Glance](#-at-a-glance) · [The Problem](#-the-problem) · [The Fix](#-the-fix)\n- [Vibe Coding Revolution](#the-vibe-coding-revolution) · [Who Is This For](#who-is-this-for) · [How This Compares](#how-this-compares) · [What Makes This Different](#-what-makes-this-different)\n- [How It Works: The Coordinator](#-how-it-works--the-coordinator) · [The RIPER-5 Lifecycle](#-the-riper-5-lifecycle) · [Intent Clarification](#-intent-clarification)\n- [The Two Quality Loops (PVL + EVL)](#-the-two-quality-loops--pvl--evl) · [Strategy Compare + Model Policy](#-strategy-compare--model-policy) · [Autopilot Mode](#-autopilot-mode--hands-free-riper-5) · [Feasibility Probes + Validators](#-feasibility-probes--the-validator-safety-net)\n- [Built-in Safety Systems](#-built-in-safety-systems) · [Pre-Implementation Intelligence](#-pre-implementation-intelligence) · [Quality Pipeline](#-quality-pipeline--built-into-execution)\n- [Plan Lifecycle](#-the-plan-lifecycle) · [Phase Programs](#-phase-programs--large-projects-that-dont-fall-apart) · [Context Groups](#-context-groups) · [Feature Folders](#-feature-folders) · [Skill Layers](#-skill-layers) · [Self-Improving Memory](#-self-improving-project-memory)\n- [What's Inside](#-whats-inside) · [Quick Fix + Fast Mode](#-quick-fix--fast-mode) · [Kit Lifecycle](#-kit-lifecycle-install--setup--update--publish) · [Contributing](#contributing)\n\n\u003c/details\u003e\n\n---\n\n## 🎁 At a Glance\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e🤖\u003c/h1\u003e\u003ch3\u003e15\u003c/h3\u003e\u003cstrong\u003eAgents\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eOne per phase + 6 specialist agents\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e⚡\u003c/h1\u003e\u003ch3\u003e33\u003c/h3\u003e\u003cstrong\u003eSkills\u003c/strong\u003e\u003cbr\u003e\u003csub\u003e20 workflow + 13 helper, matched by keyword\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e🪝\u003c/h1\u003e\u003ch3\u003e10\u003c/h3\u003e\u003cstrong\u003eHooks\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eSafety rails + automatic context loading\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e📜\u003c/h1\u003e\u003ch3\u003e22\u003c/h3\u003e\u003cstrong\u003eProtocols\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eShared rules every agent follows\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e🛡️\u003c/h1\u003e\u003ch3\u003e36\u003c/h3\u003e\u003cstrong\u003eValidators\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eAutomated checks that catch errors before they ship\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e🔧\u003c/h1\u003e\u003ch3\u003e7\u003c/h3\u003e\u003cstrong\u003eTools\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eClaude Code · Codex · Cursor · Windsurf · Antigravity · OpenCode · Copilot\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e🌍\u003c/h1\u003e\u003ch3\u003e10\u003c/h3\u003e\u003cstrong\u003eLanguages\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eEN · 中文 · 日本語 · 한국어 · VI · PT · DE · FR · ES · हिन्दी\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e⚡\u003c/h1\u003e\u003ch3\u003e30s\u003c/h3\u003e\u003cstrong\u003eInstall\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eOne command, then your agent guides the rest\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e🛩️\u003c/h1\u003e\u003cstrong\u003eAutopilot\u003c/strong\u003e\u003cbr\u003e\u003csub\u003e3 lanes (quick / fast / full) — start at any phase, runs start to finish without stopping\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e📌\u003c/h1\u003e\u003cstrong\u003e/goal blocks\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eShort copy-pasteable texts that resume hands-free runs across sessions after a reset\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e🔁\u003c/h1\u003e\u003cstrong\u003evc-autoresearch\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eFind-gaps → fix → repeat loop (shared tool for plans, tests, and evals)\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"25%\" valign=\"top\"\u003e\u003ch1\u003e🔬\u003c/h1\u003e\u003cstrong\u003eFeasibility probes\u003c/strong\u003e\u003cbr\u003e\u003csub\u003eTest-before-you-build verdicts (VIABLE / NOT-VIABLE) before locking in a design\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🔥 The Problem\n\nYou 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.\n\n**But that's just the surface.** The deeper problems hit harder:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🧠\u003c/h1\u003e\n\u003cstrong\u003eContext dies every session\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nYour agent forgets everything it learned. Same mistakes, same questions, every time. No memory, no compounding knowledge.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e📄\u003c/h1\u003e\n\u003cstrong\u003eDocs go stale instantly\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nYou wrote great context docs last week. They're already outdated. Nothing auto-updates them as the codebase evolves.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e💥\u003c/h1\u003e\n\u003cstrong\u003eBig tasks collapse mid-way\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nThe context window fills, state is lost, the agent starts hallucinating. You restart from scratch on hour 3.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🤝\u003c/h1\u003e\n\u003cstrong\u003eNo specs, no review, no collaboration\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nYour 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.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🎭\u003c/h1\u003e\n\u003cstrong\u003eArchitecture decisions are hallucinated\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nThe agent invents patterns instead of researching how other codebases solved the same problem.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🚀\u003c/h1\u003e\n\u003cstrong\u003eNothing verifies \"done\"\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nThe agent says \"all tests pass\" — but it never independently re-ran them. You find out in production.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n**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.**\n\n---\n\n## 🛠️ The Fix\n\nThis 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.**\n\n\u003cbr\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"50%\" valign=\"top\"\u003e\u003ch1\u003e📋\u003c/h1\u003e\u003cstrong\u003ePlan-first approach\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\u003csub\u003ePMs and devs review the same written plan before any code is written\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"50%\" valign=\"top\"\u003e\u003ch1\u003e🔄\u003c/h1\u003e\u003cstrong\u003eSelf-improving knowledge\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\u003csub\u003eUpdates itself every time a feature ships — docs never go stale\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"50%\" valign=\"top\"\u003e\u003ch1\u003e⚡\u003c/h1\u003e\u003cstrong\u003eHands-free execution\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\u003csub\u003eSurvives session resets — runs for hours, not minutes\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"50%\" valign=\"top\"\u003e\u003ch1\u003e🧬\u003c/h1\u003e\u003cstrong\u003eArchitecture research\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\u003csub\u003eStudies real codebases before making design decisions\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"50%\" valign=\"top\"\u003e\u003ch1\u003e✅\u003c/h1\u003e\u003cstrong\u003eTwo quality checks\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\u003csub\u003ePlans are checked before coding; tests are re-run independently after\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"50%\" valign=\"top\"\u003e\u003ch1\u003e🧭\u003c/h1\u003e\u003cstrong\u003eSmart knowledge routing\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\u003csub\u003eLoads only what is relevant — not your whole knowledge base every time\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cbr\u003e\n\n### The full RIPER-5 flow — 7 phases, every step gated\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    R[\"RESEARCH\\nread-only facts\"]\n    S[\"SPEC\\nrequirements doc\"]\n    I[\"INNOVATE\\n2-3 approaches\"]\n    P[\"PLAN\\ndetailed checklist\"]\n    V[\"VALIDATE\\nplan → contract\\n(PVL loop)\"]\n    E[\"EXECUTE\\nimplement\\n(EVL loop)\"]\n    U[\"UPDATE PROCESS\\ncapture + archive\"]\n\n    R --\u003e|\"go\"| S\n    S --\u003e|\"go\"| I\n    I --\u003e|\"go\"| P\n    P --\u003e|\"ENTER VALIDATE\"| V\n    V --\u003e|\"Gate: PASS\"| E\n    E --\u003e|\"gates green\"| U\n\n    style R fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style S fill:#0277BD,stroke:#01579B,color:#FFFFFF\n    style I fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style P fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style V fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style E fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style U fill:#00695C,stroke:#004D40,color:#FFFFFF\n```\n\n**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.\n\n---\n\n## The Vibe Coding Revolution\n\n\u003cdiv align=\"center\"\u003e\n\u003ch3\u003e\u003cem\u003e\"The hottest new programming language is English.\"\u003c/em\u003e\u003c/h3\u003e\n\u003cstrong\u003e— Andrej Karpathy\u003c/strong\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n**Vibe coding changed who can build software. Plan-first development changes what they can ship.**\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\u003ch3\u003e63%\u003c/h3\u003e\u003csub\u003eof vibe coding users are \u003cstrong\u003eNOT\u003c/strong\u003e developers\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\u003ch3\u003e16.2M\u003c/h3\u003e\u003csub\u003ecitizen developers worldwide\u003cbr\u003e(38% YoY growth)\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\u003ch3\u003e$4.7B\u003c/h3\u003e\u003csub\u003evibe coding market\u003cbr\u003egrowing 38% annually\u003c/sub\u003e\u003c/td\u003e\n\u003ctd align=\"center\" width=\"50%\"\u003e\u003ch3\u003e25%\u003c/h3\u003e\u003csub\u003eof YC W25 startups had 95%+ AI-generated codebases\u003c/sub\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\nMost 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.\n\n---\n\n## Who Is This For?\n\n\u003cdiv align=\"center\"\u003e\n\u003ch3\u003e\u003cem\u003e\"The point isn't who typed it. It's what shipped.\"\u003c/em\u003e\u003c/h3\u003e\n\u003cstrong\u003e— Garry Tan, YC\u003c/strong\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🧑‍💼\u003c/h1\u003e\n\u003cstrong\u003eCEO / Founder\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\n\u003cem\u003e\"Build me a SaaS with auth, billing, and a landing page\"\u003c/em\u003e\u003cbr\u003e\u003cbr\u003e\nThe 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.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e📊\u003c/h1\u003e\n\u003cstrong\u003eProduct Manager\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\n\u003cem\u003e\"Create a dashboard showing MRR, churn, and growth metrics\"\u003c/em\u003e\u003cbr\u003e\u003cbr\u003e\nIt generates a PRD-style SPEC, gets your approval before writing code, implements to spec, and archives the plan as searchable project history.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🎨\u003c/h1\u003e\n\u003cstrong\u003eDesigner\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\n\u003cem\u003e\"Match this Figma screenshot pixel-perfect\"\u003c/em\u003e\u003cbr\u003e\u003cbr\u003e\nThe design-aware agent analyzes your mockup, implements component-by-component with your design tokens, and spawns visual comparison checks.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e⚙️\u003c/h1\u003e\n\u003cstrong\u003eEngineer\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\n\u003cem\u003e\"Refactor the auth module to support RBAC with zero downtime\"\u003c/em\u003e\u003cbr\u003e\u003cbr\u003e\nIt 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.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## How This Compares\n\n| Feature | vibecode-pro-max-kit | Superpowers | GSD | gstack |\n|---------|---------------------|-------------|-----|--------|\n| Plan-first lifecycle | Full RIPER-5 (research → spec → innovate → plan → validate → execute → update) | Mandatory workflows | Context-rot fix | Partial |\n| Step-locked safety | Agent tools are restricted per phase (read-only research, no writing in innovate) | Skill-based constraints | Phase separation | None |\n| Quality check loops | **Two** — PVL (check the plan) + EVL (independently re-run tests) | Per-skill | None automatic | None |\n| Multi-tool support | 7 tools via `AGENTS.md` + `SKILL.md` open standards | Claude Code plugin | 14 runtimes | 1 tool |\n| Auto-improving knowledge | Topic-grouped knowledge, updated after every feature | Plugin memory | Disk-persisted state | Manual |\n| Team collaboration | Shared plans, specs, and review files | Solo | Solo | Solo |\n| Skills system | 33 auto-discovered, keyword-matched at every prompt | 86 composable skills | Meta-prompting | 23 role tools |\n| Large multi-phase projects | Umbrella plans + per-phase inner loop with regression checks | Single task | Single task | Single task |\n| Hands-free mode | Autopilot (3 lanes) + standing `/goal` consent | Manual | Manual | Manual |\n| Installation | 30s `curl` + auto-routed setup | Plugin marketplace | npx one-liner | git clone |\n\n\u003e **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.\n\n---\n\n## ⚡ What Makes This Different\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🔒\u003c/h1\u003e\n\u003cstrong\u003eStep-Locked Tool Restrictions\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nYour agent literally \u003cstrong\u003ecannot\u003c/strong\u003e write code during research. RESEARCH is read-only, INNOVATE has no Write, PLAN/VALIDATE write only to \u003ccode\u003eprocess/\u003c/code\u003e. \u003cstrong\u003eReal capability limits\u003c/strong\u003e, not just suggestions.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🎯\u003c/h1\u003e\n\u003cstrong\u003eThe Lead Agent Never Touches Code\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nThe coordinator routes, monitors, and drives loops — it \u003cstrong\u003enever edits source files or runs tests itself\u003c/strong\u003e. Every edit and every test run happens inside a dedicated sub-agent. No hidden work.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🔍\u003c/h1\u003e\n\u003cstrong\u003eAutomatic Skill Discovery\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nBefore handling any request, it scans \u003cstrong\u003e33 skills\u003c/strong\u003e and matches keywords. Say \"add webhook support\" and \u003ccode\u003evc-security\u003c/code\u003e + \u003ccode\u003evc-scenario\u003c/code\u003e are pulled in automatically.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e💾\u003c/h1\u003e\n\u003cstrong\u003eSurvives Session Resets\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nPlans, reports, knowledge docs, and learnings all live on disk. The startup hook restores approval gates after a session reset. \u003cstrong\u003eNothing is lost.\u003c/strong\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🛡️\u003c/h1\u003e\n\u003cstrong\u003eSelf-Policing Step Guard\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nWhen the agent is about to skip a required step, it stops itself: \u003cem\u003e\"PHASE JUMPING PREVENTED.\"\u003c/em\u003e A \u003cstrong\u003ebuilt-in guard against shortcuts\u003c/strong\u003e.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🔄\u003c/h1\u003e\n\u003cstrong\u003eWorks Across 7 AI Coding Tools\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nTwo open standards — \u003ccode\u003eAGENTS.md\u003c/code\u003e and \u003ccode\u003eSKILL.md\u003c/code\u003e — mean \u003cstrong\u003ezero adapters, zero plugins.\u003c/strong\u003e Start in Claude Code, switch to Cursor, continue in Codex.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🧭 How It Works — The Coordinator\n\nYour main session is a **coordinator** (called the orchestrator), not a worker. It does four things and nothing else:\n\n```\nYour request\n  → Step 0: Skill Discovery (scan 33 skills, match keywords, attach candidates)\n  → Detect intent (feature / bug / question / refactor / UI) + score ambiguity\n  → Route to the right agent in a fresh context window\n  → Monitor: step compliance, status codes, loop driving\n```\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🧑‍✈️\u003c/h1\u003e\n\u003cstrong\u003eIt delegates, never implements\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nResearch → \u003ccode\u003evc-research-agent\u003c/code\u003e. Plan → \u003ccode\u003evc-plan-agent\u003c/code\u003e. Code → \u003ccode\u003evc-execute-agent\u003c/code\u003e. The coordinator hands off the right context and waits — it never does the actual work itself.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🚫\u003c/h1\u003e\n\u003cstrong\u003eNo hidden execution — ever\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nThe moment a plan with an agreed checklist exists, \"ENTER EXECUTE MODE\" \u003cstrong\u003ealways\u003c/strong\u003e launches \u003ccode\u003evc-execute-agent\u003c/code\u003e. Even a one-line fix goes through it. Tests run only inside a dedicated \u003ccode\u003evc-tester\u003c/code\u003e. This holds regardless of change size.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e📨\u003c/h1\u003e\n\u003cstrong\u003eClear status codes, not vague signals\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nEvery sub-agent ends with one of: \u003ccode\u003eDONE\u003c/code\u003e · \u003ccode\u003eDONE_WITH_CONCERNS\u003c/code\u003e · \u003ccode\u003eBLOCKED\u003c/code\u003e · \u003ccode\u003eNEEDS_CONTEXT\u003c/code\u003e. The coordinator never ignores a blocker and never retries the same blocked approach three times.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🔁\u003c/h1\u003e\n\u003cstrong\u003eIt drives the fix loops\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nSub-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.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    REQ[\"User request\"]\n    SD[\"Step 0: Skill Discovery\\nscan 33 skills, match keywords\"]\n    INT{\"Detect intent\\n+ score ambiguity\"}\n    RES[\"vc-research-agent\\n(feature / question)\"]\n    PLN[\"vc-plan-agent\\n(after INNOVATE)\"]\n    VAL[\"vc-validate-agent\\n(PVL loop)\"]\n    EXE[\"vc-execute-agent\\n(EXECUTE)\"]\n    TST[\"vc-tester\\n(EVL loop)\"]\n    UPD[\"vc-update-process-agent\\n(closeout)\"]\n    MON[\"Monitor\\nstatus codes · loop driving\\nno inline execution ever\"]\n\n    REQ --\u003e SD --\u003e INT\n    INT --\u003e|\"feature / research\"| RES\n    INT --\u003e|\"plan phase\"| PLN\n    INT --\u003e|\"validate phase\"| VAL\n    INT --\u003e|\"execute phase\"| EXE\n    EXE -.-\u003e|\"EVL\"| TST\n    INT --\u003e|\"update phase\"| UPD\n    RES --\u003e MON\n    PLN --\u003e MON\n    VAL --\u003e MON\n    TST --\u003e MON\n    UPD --\u003e MON\n\n    style REQ fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style SD fill:#0277BD,stroke:#01579B,color:#FFFFFF\n    style INT fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style RES fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style PLN fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style VAL fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style EXE fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style TST fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style UPD fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style MON fill:#37474F,stroke:#263238,color:#FFFFFF\n```\n\n\u003e **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.\n\n---\n\n## 📊 The RIPER-5 Lifecycle\n\n| Phase | What happens | Agent | You say |\n|-------|-------------|-------|---------|\n| 🔍 **RESEARCH** | Read-only fact gathering — codebase + web. Never modifies files. | `vc-research-agent` | *(auto on feature requests)* |\n| 📝 **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` |\n| 💡 **INNOVATE** | Explore 2-3 approaches with trade-offs. Decision summary (chosen + rejected + why). | `vc-innovate-agent` | `go` |\n| 📋 **PLAN** | Write the detailed spec: touchpoints, public contracts, which files it can touch, verification evidence, resume handoff. | `vc-plan-agent` | `go` |\n| ✅ **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` |\n| ⚡ **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` |\n| 🧠 **UPDATE PROCESS** | Capture learnings, update context, archive plan, write closeout packet. | `vc-update-process-agent` | *(recommended after non-trivial work)* |\n\n\u003e 📝 **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.)\n\u003e\n\u003e **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.\n\n```mermaid\nflowchart TD\n    U[\"You: what I really want\u003cbr\u003e(plain words)\"] --\u003e S[\"📝 SPEC\u003cbr\u003eexpected behavior + acceptance\u003cbr\u003ecriteria — you approve\"]\n    S --\u003e I[\"💡 INNOVATE\"]\n    S --\u003e P[\"📋 PLAN\"]\n    S --\u003e V[\"✅ VALIDATE\"]\n    S --\u003e E[\"⚡ EXECUTE\"]\n    I -.-\u003e|\"check back\"| Q{\"Is this what\u003cbr\u003eyou asked for?\"}\n    P -.-\u003e|\"check back\"| Q\n    V -.-\u003e|\"check back\"| Q\n    E -.-\u003e|\"check back\"| Q\n    Q --\u003e|yes| GO[\"keep building\"]\n    Q --\u003e|no| S\n```\n\n\u003cbr\u003e\n\n### 💻 Example sessions\n\n```\n# 🆕 Feature request\nYou: \"add webhook support to the API\"\n→ Skill discovery surfaces: vc-scenario, vc-security\n→ research-agent gathers context (read-only, can't touch code)\n→ \"go\" → spec-agent writes requirements doc → you approve\n→ \"go\" → innovate-agent compares approaches → decision summary\n→ \"go\" → plan-agent writes the plan, listing which files it will touch\n→ \"ENTER VALIDATE MODE\" → validate-agent gates the plan (PVL loop) → Gate: PASS\n→ \"ENTER EXECUTE MODE\" → execute-agent implements → tester re-runs gates (EVL) → reviewer → git-manager\n→ Closeout packet: what changed, what's verified, recommended next step\n```\n\n```\n# 🐛 Bug fix\nYou: \"login redirect is broken\"\n→ Routes to vc-debugger → gathers evidence FIRST → 2-3 competing hypotheses\n→ Systematically eliminates each → root cause with proof chain\n→ execute-agent implements the fix → EVL re-test → quality pipeline\n```\n\n```\n# ⏩ Fast mode\nYou: \"ENTER FAST MODE - add rate limiting middleware\"\n→ Compressed RESEARCH + SPEC + INNOVATE + PLAN + VALIDATE in one pass\n→ Mandatory safety pause after VALIDATE → you review → \"ENTER EXECUTE MODE\"\n```\n\n```\n# 🤖 Autopilot (hands-free)\nYou: \"autopilot full: build a notifications system\"\n→ ONE consolidated clarification round → provisional /goal block (standing consent)\n→ Drives the full RIPER-5 sequence autonomously, pausing only on hard stops\n```\n\n```\n# 🏗️ Large program\nYou: \"build a full testing platform\"\n→ Umbrella plan + phase plans in a feature folder\n→ Each phase inner loop: research → innovate → plan → PVL → execute → EVL → update\n→ Progress survives context compaction — durable reports on disk\n```\n\n---\n\n## 🎯 Intent Clarification\n\nBefore 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.*\n\n| Tier | When | Behavior |\n|---|---|---|\n| **Tier 0** — silent auto-route | Score 0–1, or you said \"go\" / \"just do it\", or resuming a plan | Routes immediately, no questions |\n| **Tier 1** — inline summary | Score 2 | States its understanding + chosen route in one line, then proceeds |\n| **Tier 2** — questions | Score 3+ | Asks focused multiple-choice questions before routing |\n\n\u003e 🧠 **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.\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    REQ[\"User request\"]\n    SCORE{\"ambiguity score\\n0–4 binary signals\"}\n    AUTO[\"Auto-skip conditions\\n(go / continue / mid-phase\\n/ trivial / explicit mode\\n/ resuming plan / pure info)\"]\n    T0[\"Tier 0\\nsilent auto-route\\n(score 0–1 OR auto-skip)\"]\n    T1[\"Tier 1\\ninline summary\\n(score 2)\"]\n    T2[\"Tier 2\\nask focused questions\\n(score 3+)\"]\n    ROUTE[\"Route to matching agent\\n(research / plan / execute / …)\"]\n    STILL{\"still unclear\\nafter Tier 2?\"}\n    FINAL[\"One final plain question\\n(max 2 clarification rounds)\"]\n    NARROW[\"Default: vc-research-agent\\nnarrowest reasonable scope\"]\n\n    REQ --\u003e AUTO\n    AUTO --\u003e|\"auto-skip matches\"| T0\n    AUTO --\u003e|\"no auto-skip\"| SCORE\n    SCORE --\u003e|\"0–1\"| T0\n    SCORE --\u003e|\"2\"| T1\n    SCORE --\u003e|\"3+\"| T2\n    T0 --\u003e ROUTE\n    T1 --\u003e ROUTE\n    T2 --\u003e STILL\n    STILL --\u003e|\"resolved\"| ROUTE\n    STILL --\u003e|\"still unclear\"| FINAL --\u003e NARROW\n\n    style REQ fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style AUTO fill:#0277BD,stroke:#01579B,color:#FFFFFF\n    style SCORE fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style T0 fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style T1 fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style T2 fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style ROUTE fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style STILL fill:#F57F17,stroke:#F9A825,color:#000000\n    style FINAL fill:#AD1457,stroke:#880E4F,color:#FFFFFF\n    style NARROW fill:#00695C,stroke:#004D40,color:#FFFFFF\n```\n\n---\n\n## ✅ The Two Quality Loops — PVL + EVL\n\nMost harnesses check *once*, if at all. This one wraps EXECUTE in **two independent loops** — one before code is written, one after.\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '15px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    PLAN[\"📋 PLAN written\"]\n    PVL{\"✅ PVL\\nValidate the plan\\nV1–V7 gates\"}\n    PASS[\"Gate: PASS\"]\n    SUPP[\"📝 plan-agent supplements\\n(addresses gaps)\"]\n    EXEC[\"⚡ EXECUTE\\nimplement the plan\"]\n    EVL{\"🧪 EVL\\ntester re-runs the\\nvalidate-contract gates\"}\n    FIX[\"⚡ execute-agent\\nsupplement (fix gate)\"]\n    DONE[\"🧠 UPDATE PROCESS\"]\n\n    PLAN --\u003e PVL\n    PVL --\u003e|\"CONDITIONAL / BLOCKED\"| SUPP\n    SUPP --\u003e|\"re-run from V1\"| PVL\n    PVL --\u003e|\"PASS\"| PASS\n    PASS --\u003e|\"ENTER EXECUTE\"| EXEC\n    EXEC --\u003e EVL\n    EVL --\u003e|\"gate fails\"| FIX\n    FIX --\u003e|\"re-run\"| EVL\n    EVL --\u003e|\"all gates green\"| DONE\n\n    style PLAN fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style PVL fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style PASS fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style SUPP fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style EXEC fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style EVL fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style FIX fill:#AD1457,stroke:#880E4F,color:#FFFFFF\n    style DONE fill:#00695C,stroke:#004D40,color:#FFFFFF\n```\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch3\u003e📋 PVL — Plan-Validate-Fix\u003c/h3\u003e\nBefore EXECUTE, \u003ccode\u003evc-validate-agent\u003c/code\u003e runs the plan through \u003cstrong\u003eV1–V7 checkpoints\u003c/strong\u003e — splitting the work across several agents to cover infra, test coverage, breaking changes, security, and per-section feasibility. A first-pass \u003cstrong\u003eCONDITIONAL\u003c/strong\u003e or \u003cstrong\u003eBLOCKED\u003c/strong\u003e is never the end — it routes back to \u003ccode\u003evc-plan-agent\u003c/code\u003e to update the plan, then re-checks from V1.\n\u003cbr\u003e\u003cbr\u003e\n\u003csub\u003eTracked by \u003ccode\u003evc-autoresearch\u003c/code\u003e (domain: plan) — a find-gaps-and-fix loop. 10-cycle cap. Plateau detection. Only \u003cstrong\u003eGate: PASS\u003c/strong\u003e (or a CONDITIONAL you explicitly accept) unlocks EXECUTE.\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch3\u003e🧪 EVL — Execute-Validate-Fix\u003c/h3\u003e\nAfter EXECUTE reports done — \u003cstrong\u003eeven when it claims all checkpoints are green\u003c/strong\u003e — the lead agent \u003cstrong\u003ealways\u003c/strong\u003e spawns \u003ccode\u003evc-tester\u003c/code\u003e to independently re-run the exact agreed-checklist test commands. A failing checkpoint routes to a scoped \u003ccode\u003evc-execute-agent\u003c/code\u003e fix, then re-tests.\n\u003cbr\u003e\u003cbr\u003e\n\u003csub\u003eTracked by \u003ccode\u003evc-autoresearch\u003c/code\u003e (domain: tests). 10-cycle cap. The execute-agent's own internal \"iterate until green\" loop \u003cstrong\u003enever\u003c/strong\u003e substitutes for this independent confirmation.\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n\u003e 💎 **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).\n\n### 🔁 vc-autoresearch — Shared Loop Engine\n\nBoth 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.\n\nThe 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).\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    START[\"Start loop\\n(orchestrator init results.tsv\\nheader + baseline row)\"]\n    FIND[\"Find gaps\\n(validate-agent / tester\\nreturns gap list)\"]\n    RPT[\"Write iteration report\\n{slug}-iteration-{NNN}_REPORT_{dd-mm-yy}.md\"]\n    TSV[\"Append results.tsv row\\n(cycle N, gap count)\"]\n    FIX[\"Fix gaps\\n(plan-agent supplement\\nOR execute-agent supplement)\"]\n    CHK[\"Guard checks\\nplateau? cap hit? regression?\"]\n    RECHECK[\"Re-check\\n(re-run validate / tester)\"]\n    SUCC[\"SUCCESS\\nall-clear 2 consecutive rounds\"]\n    HALT[\"HALT\\nplateau / 10-cycle cap / regression\"]\n\n    START --\u003e FIND --\u003e RPT --\u003e TSV --\u003e FIX --\u003e CHK\n    CHK --\u003e|\"safe to continue\"| RECHECK\n    RECHECK --\u003e FIND\n    CHK --\u003e|\"plateau / cap / regression\"| HALT\n    FIND --\u003e|\"no gaps found (×2)\"| SUCC\n\n    style START fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style FIND fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style RPT fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style TSV fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style FIX fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style CHK fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style RECHECK fill:#0277BD,stroke:#01579B,color:#FFFFFF\n    style SUCC fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style HALT fill:#B71C1C,stroke:#7F0000,color:#FFFFFF\n```\n\n| Mode | Does | Stops when |\n|---|---|---|\n| `vc-autoresearch` (core) | find gaps → fix → repeat | no gaps found OR metric goal hit |\n| `vc-autoresearch:probe` | 8 personas interrogate the corpus until saturation | no new constraints for 3 rounds |\n| `vc-autoresearch:reason` | adversarial debate with blind judges | judges converge or iteration cap |\n| `vc-autoresearch:evals` | analyze TSV results — trends, plateaus, recommendations | analysis only |\n\n**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).\n\n---\n\n## 👥 Strategy Compare + Model Policy\n\nAt **every phase transition**, the lead agent invokes `vc-agent-strategy-compare` to recommend *how* to run the next phase — with cost estimates.\n\n| Strategy | When | Coordination |\n|---|---|---|\n| **Sequential** | Work depends on prior output | One agent at a time |\n| **Parallel subagents** | Independent dimensions, fire-and-forget | None — lead agent collects + combines results |\n| **Workflow** | Predictable splitting of work across a list | Scripted steps |\n| **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 |\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    SS[\"vc-agent-strategy-compare\\n(every phase transition)\"]\n    SC{\"signal score\\n0–7\"}\n    SEQ[\"Sequential\\none agent at a time\\n(output feeds next)\"]\n    PAR[\"Parallel subagents\\nfire-and-forget\\n(independent dimensions)\"]\n    WF[\"Workflow\\nscripted steps\\nacross a list\"]\n    TEAM[\"Agent team\\nTeamCreate + TaskCreate\\n+ SendMessage\\n(must coordinate mid-run)\"]\n    MC{\"which phase?\"}\n    OPUS[\"🔴 opus\\n(EXECUTE only)\"]\n    SONNET[\"🔵 sonnet\\n(every other phase)\"]\n\n    SS --\u003e SC\n    SC --\u003e|\"low / dependent\"| SEQ\n    SC --\u003e|\"mid / independent\"| PAR\n    SC --\u003e|\"predictable split\"| WF\n    SC --\u003e|\"high / must coordinate\\nor 3+ phase plans\"| TEAM\n    SS --\u003e MC\n    MC --\u003e|\"EXECUTE / fast-mode\\nquick-fix (real code)\"| OPUS\n    MC --\u003e|\"Research / Spec\\nInnovate / Plan\\nValidate / Update\\nall reviewers\"| SONNET\n\n    style SS fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style SC fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style SEQ fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style PAR fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style WF fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style TEAM fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style MC fill:#0277BD,stroke:#01579B,color:#FFFFFF\n    style OPUS fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style SONNET fill:#37474F,stroke:#263238,color:#FFFFFF\n```\n\n\u003e ⚠️ **\"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.\n\n### 🧮 Model selection policy\n\n| Phase | Model | Why |\n|---|---|---|\n| **EXECUTE** (+ fast-mode, quick-fix doing real code) | 🔴 **opus** | Real source edits, builds, migrations |\n| Research · Spec · Innovate · Plan · Validate · Update · all reviewers/researchers | 🔵 **sonnet** | Planning and analysis — cheaper, plenty capable |\n\n\u003e 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.\n\n---\n\n## 🤖 Autopilot Mode — Hands-Free RIPER-5\n\nSay **`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.\n\n**Trigger anywhere:** autopilot can start at the beginning of a session *or* at any point mid-session. On trigger, the lead agent reads the saved files on disk to figure out which RIPER-5 phase you are already in, then picks up from there and drives the rest on its own.\n\n| On-disk state | Entry phase |\n|---|---|\n| No SPEC file | Start at RESEARCH |\n| SPEC file present | Skip to post-SPEC (INNOVATE) |\n| Plan file present | Skip to post-PLAN (VALIDATE) |\n| Validate-contract with PASS/CONDITIONAL | Skip to EXECUTE |\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    TRG[\"autopilot trigger phrase\\n(anywhere in session)\"]\n    DISK[\"Read saved files on disk\\ndetect current phase\"]\n    CLR[\"ONE consolidated\\nclarification round\"]\n    GOAL[\"Emit provisional /goal block\\n(≤4000 chars, copy-pasteable\\nstanding EXECUTE consent)\"]\n    ACT[\"AUTOPILOT_ACTIVATED\\nautonomous run begins\"]\n    PHASES[\"Drive remaining phases\\nRESEARCH → … → UPDATE PROCESS\\n(no user pauses)\"]\n    HS1[\"🛑 Irreversible / outward action\\nnot pre-approved\"]\n    HS2[\"⛔ Cascade BLOCKED\\n(several phases stuck)\"]\n    HS3[\"💸 Live-provider billed probe\\n(double opt-in required)\"]\n    DONE[\"Run complete\\nautopilot deactivates\"]\n\n    TRG --\u003e DISK --\u003e CLR --\u003e GOAL --\u003e ACT --\u003e PHASES\n    PHASES --\u003e|\"hard stop 1\"| HS1\n    PHASES --\u003e|\"hard stop 2\"| HS2\n    PHASES --\u003e|\"hard stop 3\"| HS3\n    PHASES --\u003e|\"all phases done\"| DONE\n\n    style TRG fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style DISK fill:#0277BD,stroke:#01579B,color:#FFFFFF\n    style CLR fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style GOAL fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style ACT fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style PHASES fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style HS1 fill:#B71C1C,stroke:#7F0000,color:#FFFFFF\n    style HS2 fill:#B71C1C,stroke:#7F0000,color:#FFFFFF\n    style HS3 fill:#B71C1C,stroke:#7F0000,color:#FFFFFF\n    style DONE fill:#00695C,stroke:#004D40,color:#FFFFFF\n```\n\n```\nYou: \"autopilot full: add team invitations with email + role management\"\n→ Reads saved files → detects current phase → enters there\n→ ONE consolidated clarification round (scope, hard stops, autonomy boundaries, first-phase strategy)\n→ Provisional /goal block emitted (≤4000 chars, copy-pasteable, standing EXECUTE consent)\n→ AUTOPILOT_ACTIVATED → drives remaining phases on its own\n→ Stops ONLY for hard stops\n```\n\n### Three lanes — match ceremony to risk\n\n| Lane | Trigger | Flow |\n|---|---|---|\n| 🟢 **quick** | `autopilot quick: [task]` | Scout → edit → scoped check. No plan, no contract, no EVL. |\n| 🟡 **fast** | `autopilot fast: [task]` | Compressed R→S→I→P→V → EXECUTE + EVL. |\n| 🔴 **full** | `autopilot [task]` / `autopilot full:` | Complete RIPER-5 (default). |\n\n### 🌙 Hands-Free: One Phrase, Built While You Sleep\n\nSay `autopilot full: [task]` — or paste a `/goal` block — and the following all happen with **zero human input**:\n\n- **Plan-check-and-fix loop** — finds gaps in the plan, fixes them, and re-checks. Up to 10 rounds on its own.\n- **Build-test-and-fix loop** — writes code, runs tests, fixes failures, re-runs. Up to 10 rounds on its own. It never trusts its own \"all green\" — a separate checker (vc-tester) independently re-runs every test to confirm.\n- **Phase-to-phase advancement** — moves from research to plan to code to done without waiting for you.\n- **Picks up after a memory reset** — plans, reports, and progress all live as files on disk. After compaction (when the AI's short-term memory clears), the next session reads those files and continues exactly where it left off.\n- **Stuck feature? Set it aside, keep going** — if one phase can't be resolved, the agent writes a backlog note and moves on to the next feature. You can run many features in parallel without one blocker stopping everything.\n- **Teams of agents for parallel features** — multiple agents can build separate features at the same time, each locked to its own files so they never collide. A stuck feature is parked, not a blocker for the rest.\n\n### Hard stops always surface (even on autopilot)\n\nThese are the **only three times it stops and asks you**:\n\n- 🛑 Anything it cannot undo, or that reaches the outside world and was not pre-approved (going live, sending real messages, charging money)\n- ⛔ Several phases in a row get stuck with no progress — a real dead-end worth your eyes\n- 💸 A test that would spend real money on a paid outside service — it asks before running\n\n---\n\n### 🎯 /goal — the autonomous run token\n\n**Required, not decoration:** after every VALIDATE phase completes, the lead agent *must* emit a copy-pasteable `/goal` block before EXECUTE starts. This is a required handoff file — not optional commentary.\n\n**Format constraints:**\n\n| Block type | Required fields | Hard limit |\n|---|---|---|\n| Post-VALIDATE block | SESSION GOAL · Charter+umbrella plan · Autonomy · Hard stop conditions · Next phase · Validate contract · Execute start | ≤ 4000 chars |\n| Provisional (autopilot) block | SESSION GOAL · ENTRY PHASE · REMAINING PHASES · CLARIFICATIONS LOCKED · EXECUTE CONSENT · DECISION POLICY · HARD STOPS · TEST GATES · START (+ optional LANE) | ≤ 4000 chars |\n\nThe `/goal` command rejects blocks longer than 4000 characters. Keep it short — use the required fields as the structure, not a prose essay.\n\n**Standalone /goal mode:** paste a `/goal` block into a new session and the run picks up from the phase named in `START`. Clarifications and decision rules are already set — no new clarification round. Under a standing `/goal`, the agent decides on its own at every reversible step, sends BLOCKED items to a backlog, and writes its own reports — but **worker agent delegation stays mandatory.** Autopilot removes *approval pauses* only, never the no-inline-execution rule.\n\nValidated by `validate-autopilot-goal-block.mjs`.\n\n---\n\n## 🔬 Feasibility Probes + The Validator Safety Net\n\n### 🔬 Feasibility probes — test the assumption before building on it\n\nWhen SPEC, INNOVATE, or VALIDATE hits a key assumption it cannot confirm by reading alone, it emits `VC-FEASIBILITY-PROBE-NEEDED` and stops. The lead agent spawns `vc-debugger` to run a real test and write a **VERDICT**:\n\n| Verdict | Meaning |\n|---|---|\n| ✅ **VIABLE** | Assumption holds — design may rely on it |\n| ❌ **NOT-VIABLE** | Assumption is false — that approach is forbidden |\n| ❓ **INCONCLUSIVE** | Couldn't prove it — carried forward as a known-gap |\n\nEach verdict comes with a 3-part design note: **what the result allows · what it rules out · what is still uncertain** — fed word-for-word back into the paused phase. Probes are **cost-classed** (`cheap-local` / `needs-container` / `needs-live-provider` → double opt-in / `needs-browser` / `needs-cf`) so a billed or shared-resource probe never runs silently.\n\n### 🛡️ 36 validators — mechanical correctness, not opinion\n\nThe kit ships **36 validator scripts** that turn \"did the agent follow the rules?\" into a clear pass/fail result. They run after any phase that touches harness files, and as required checkpoints in UPDATE PROCESS:\n\n| Validator family | Checks |\n|---|---|\n| `vc-audit-vc` | Agent parity (Claude/Codex), skill registry, kit portability, agent frontmatter |\n| `vc-audit-context` | Context routing, discovery frontmatter, skill keywords |\n| `vc-audit-plans` | Plan inventory, umbrella state, phase completeness, phase reports, backlog notes |\n| 14 VC-system behavior validators | Each owns a pass/fail fixture pair — strategy-compare output, closeout, intent-clarify, feasibility verdict, autoresearch log, and more |\n\n---\n\n## 🛡️ Built-in Safety Systems\n\nThese are not guidelines — they are **hard rules** built into every agent.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e📝\u003c/h1\u003e\n\u003cstrong\u003eProgress Notes, Not Mid-Run Pauses\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nDuring coding the agent writes progress notes to the phase report file as it works. No mid-run pause, no \"continue or return?\" prompt. If it hits a problem that needs a plan change, it stops and returns to PLAN. Otherwise it keeps going.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🚫\u003c/h1\u003e\n\u003cstrong\u003eNever Quietly Deviate\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nIf coding hits a problem that needs a plan change, the agent \u003cstrong\u003estops immediately\u003c/strong\u003e, explains, and returns to PLAN. No silent improvising.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🔐\u003c/h1\u003e\n\u003cstrong\u003ePrivacy Guardrails Hook\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nThe agent is \u003cstrong\u003eblocked from reading\u003c/strong\u003e \u003ccode\u003e.env\u003c/code\u003e, credentials, SSH keys, and \u003ccode\u003e.pem\u003c/code\u003e files without explicit approval.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e⚠️\u003c/h1\u003e\n\u003cstrong\u003eHigh-Risk Evidence Packs\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nFor auth, billing, schema migrations, or public-API changes, the system requires a formal \u003cstrong\u003e5-file evidence pack\u003c/strong\u003e before calling work \"done\" — always manual, never auto-bypassed.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e📨\u003c/h1\u003e\n\u003cstrong\u003eStatus-Code Discipline\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nWorker agents must close with \u003ccode\u003eDONE\u003c/code\u003e / \u003ccode\u003eDONE_WITH_CONCERNS\u003c/code\u003e / \u003ccode\u003eBLOCKED\u003c/code\u003e / \u003ccode\u003eNEEDS_CONTEXT\u003c/code\u003e. Blockers are never ignored; correctness concerns become action items.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e📊\u003c/h1\u003e\n\u003cstrong\u003eCloseout + Drift Scoring\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nAfter coding, a closeout packet scores urgency: \u003cstrong\u003eLOW\u003c/strong\u003e (light touch) → \u003cstrong\u003eMEDIUM\u003c/strong\u003e (significant) → \u003cstrong\u003eHIGH\u003c/strong\u003e (harness/protocol files touched), and recommends the next safe step.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🔍 Pre-Implementation Intelligence\n\nBefore a single line of code is written, three specialist skills can catch issues:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🎭\u003c/h1\u003e\n\u003cstrong\u003e5-Persona Debate — \u003ccode\u003evc-predict\u003c/code\u003e\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nArchitect, Security, Performance, UX, and Devil's Advocate debate your plan. Produces a \u003cstrong\u003eGO / CAUTION / STOP\u003c/strong\u003e verdict before you write a line.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🎲\u003c/h1\u003e\n\u003cstrong\u003e12-Dimension Edge Cases — \u003ccode\u003evc-scenario\u003c/code\u003e\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nDecomposes a feature across 12 dimensions (user types, input extremes, timing, scale, state, env, errors, auth, data, integrations, compliance, business logic). Output doubles as test specs.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🔐\u003c/h1\u003e\n\u003cstrong\u003eSTRIDE + OWASP Audit — \u003ccode\u003evc-security\u003c/code\u003e\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nDual-methodology security audit with dependency auditing, secret detection, and an \u003cstrong\u003eauto-fix mode\u003c/strong\u003e that sorts by severity and fixes Critical first with regression guards.\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🔬\u003c/h1\u003e\n\u003cstrong\u003eEvidence-First Debugging — \u003ccode\u003evc-debugger\u003c/code\u003e\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nGathers evidence → forms 2-3 competing hypotheses → tests each → documents the elimination path. \u003cstrong\u003eNever guesses — proves.\u003c/strong\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## ✅ Quality Pipeline — Built Into Execution\n\n**Tests first, then code.** The agreed checklist (written before any code is touched) defines the exact tests that must pass. The execute-agent writes code until those tests go green. Then a separate checker — `vc-tester` — re-runs every test on its own to confirm. The execute-agent's own \"all green\" is never taken at face value. At the very end, the reviewer checks that the whole project still works together, not just the new piece.\n\nThe execute-agent does not just write code and call it done. It moves through a **quality pipeline** automatically:\n\n\u003cbr\u003e\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '16px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    E[\"⚡ Execute-Agent\\nImplements the plan\"]\n    SR[\"🔎 Self-Review\\nLine-by-line check\\nagainst plan\"]\n    T[\"🧪 Tester (EVL)\\nDiff-aware — re-runs\\nthe contract gates\"]\n    CR[\"🔍 Code Reviewer\\nEdge case scout\\n+ adversarial review\"]\n    CS[\"✨ Code Simplifier\\nClarity refactoring\"]\n    GM[\"📦 Git Manager\\nLogical commit splitting\\nfrom touched_files\"]\n\n    E --\u003e SR --\u003e T --\u003e CR --\u003e CS --\u003e GM\n\n    style E fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style SR fill:#AD1457,stroke:#880E4F,color:#FFFFFF\n    style T fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style CR fill:#283593,stroke:#1A237E,color:#FFFFFF\n    style CS fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style GM fill:#37474F,stroke:#263238,color:#FFFFFF\n```\n\n| Step | What it does |\n|---|---|\n| 🔎 **Self-review** | Checks every checklist item against the plan, records any deviation |\n| 🧪 **Tester (EVL)** | Re-runs the agreed-checklist tests independently; maps changed files → test files, escalates to the full suite when \u003e70% mapped |\n| 🔍 **Code reviewer** | Sends an edge-case scout *before* review; checks N+1 queries, auth paths, data leaks |\n| ✨ **Simplifier** | Tidies the code for clarity after review — no behavior changes |\n| 📦 **Git manager** | Receives `touched_files`, splits into logical conventional commits, refuses unknown files |\n\n---\n\n## 📋 The Plan Lifecycle\n\nEvery non-trivial feature follows a **plan lifecycle** — a written spec that is created, reviewed, built against, and then archived as permanent project history.\n\n\u003cbr\u003e\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '16px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    A[\"🆕 Feature Request\"]\n    B[\"📝 Plan Created\\nin active/{slug}_{date}/\"]\n    C{\"👀 User Reviews\\nthe Plan\"}\n    D[\"✅ VALIDATE\\n(PVL gates)\"]\n    E[\"⚡ Execute + EVL\"]\n    F[\"📦 Plan Archived\\nto completed/\"]\n    G[\"🧠 Learnings →\\nall-context.md\"]\n    H[\"🔄 Next Feature\\nStarts Smarter\"]\n\n    A --\u003e B --\u003e C\n    C --\u003e|\"✏️ Needs Changes\"| B\n    C --\u003e|\"✅ Approved\"| D --\u003e E --\u003e F --\u003e G --\u003e H\n    H -.-\u003e|\"context compounds\"| A\n\n    style A fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style B fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style C fill:#F57F17,stroke:#F9A825,color:#000000\n    style D fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style E fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style F fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style G fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style H fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n```\n\n\u003e 💡 Six months from now, when someone asks *\"why did we build auth this way?\"*, the answer is in `completed/`. Not lost in a Slack thread.\n\n**Where plans live — task-folder convention:**\n\n```\nprocess/\n├── general-plans/\n│   ├── active/\n│   │   └── webhooks_28-05-26/          # 📋 Task folder: plan + colocated reports/refs\n│   │       └── webhooks_PLAN_28-05-26.md\n│   ├── completed/                       # ✅ Archived (searchable history)\n│   └── backlog/                         # 📌 Deferred work\n└── features/\n    └── billing/                         # 🏷️ Feature-scoped (5+ artifacts)\n        ├── active/{slug}_{date}/\n        ├── completed/\n        └── backlog/\n```\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    PC[\"vc-plan-agent creates task folder\\nprocess/general-plans/active/{slug}_{date}/\\nOR features/{feature}/active/{slug}_{date}/\"]\n    PLAN[\"{slug}_PLAN_{dd-mm-yy}.md\\n— plan file\\n— Validate Contract appended here\"]\n    REF[\"{slug}_REF_{dd-mm-yy}.md\\n— optional references\"]\n    RPT[\"{slug}-iteration-{NNN}_REPORT_{dd-mm-yy}.md\\n— per PVL/EVL cycle report\"]\n    TSV[\"results.tsv\\n— rolling loop log\\n(header + baseline + cycle rows)\"]\n    PP[\"PHASE PROGRAM extras\"]\n    UMB[\"umbrella_PLAN_{dd-mm-yy}.md\\n— Program Goal Charter\\n— /goal block\"]\n    PHN[\"phase-N_PLAN_{dd-mm-yy}.md\\n— one file per phase\"]\n    REG[\"phase-blast-radius-registry.md\\n— per-phase file ownership\"]\n\n    PC --\u003e PLAN\n    PC --\u003e REF\n    PC --\u003e RPT\n    PC --\u003e TSV\n    PC --\u003e PP\n    PP --\u003e UMB\n    PP --\u003e PHN\n    PP --\u003e REG\n\n    style PC fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style PLAN fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style REF fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style RPT fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style TSV fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style PP fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style UMB fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style PHN fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style REG fill:#37474F,stroke:#263238,color:#FFFFFF\n```\n\n\u003e Every plan carries: 📍 **touchpoints** (files created/modified) · 📜 **public contracts** · 💥 **which files it can touch** (what could break, what to test) · ✅ **verification evidence** · 🔄 **resume handoff**. `vc-plan-discovery` finds the right plan to resume; the `post-write-plan-check` hook checks plan structure on every plan write.\n\n---\n\n## 🏗️ Phase Programs — Large Projects That Don't Fall Apart\n\nNormal features use one plan. **Large multi-phase projects** use a phase program — an umbrella plan plus per-phase plans, each running a full **7-step inner loop** with its own checkpoints and a saved report.\n\n\u003cbr\u003e\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    UP[\"🎯 Umbrella Plan\\nProgram Goal Charter\\n(north star · done · scope tiers)\"]\n    P1[\"📋 Phase 1\"]\n    P2[\"📋 Phase 2 ...\"]\n\n    subgraph LOOP[\"🔁 Per-phase inner loop (skips SPEC)\"]\n        direction TB\n        R[\"🔍 Research\"]\n        I[\"💡 Innovate\"]\n        PL[\"📋 Plan-supplement\"]\n        PVL[\"✅ PVL\"]\n        EX[\"⚡ Execute\"]\n        EVL[\"🧪 EVL\"]\n        UPD[\"🧠 Update\"]\n        R --\u003e I --\u003e PL --\u003e PVL --\u003e EX --\u003e EVL --\u003e UPD\n    end\n\n    UP --\u003e P1 --\u003e LOOP\n    LOOP -.-\u003e|\"learnings feed\\nnext phase\"| P2\n\n    style UP fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style P1 fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style P2 fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style R fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style I fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style PL fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style PVL fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style EX fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style EVL fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style UPD fill:#00695C,stroke:#004D40,color:#FFFFFF\n```\n\n| | Feature | Why it matters |\n|---|---|---|\n| 🔄 | **Re-research at every phase** | Checks for code drift, reads latest reports, refreshes assumptions |\n| ✅ | **Checkpoints per phase** | A phase is not done until evidence proves it. Honest status: `PLANNED → CODE DONE → TESTING → VERIFIED` or `BLOCKED` |\n| 📄 | **Saved reports** | Every phase writes results to disk — progress survives a memory reset |\n| 🧠 | **Learnings feed forward** | Phase 1 discoveries update Phase 2's plan before coding starts |\n| 🏗️ | **Foundation vs expansion** | Explicitly separates \"prove the architecture\" from \"implement everything\" |\n| 🚧 | **Honest blocker handling** | Stuck phases stay `BLOCKED` with evidence. No faking a green status |\n\n\u003cbr\u003e\n\n### 🔀 The program reshapes itself as it learns\n\nThe plan you write at the start is a rough map, not a fixed contract. As the program runs, it adjusts — so you do not have to predict every step in advance.\n\n**It can add a new phase in the middle of a run.**\nWhile working, the agent may discover a missing step — something that must happen before the next phase can proceed. When that happens, it inserts a new phase right there, renumbers the rest, and carries on. No human needed. (Internal signal: `MID_PROGRAM_PLAN_CREATED` — the new plan is written to disk and added to the registry automatically.)\n\n**It can reorder phases.**\nResearch sometimes shows the planned order is wrong — for example, Phase 3 depends on something only Phase 4 produces. The agent rearranges the remaining phases and records why. (Internal signal: `PHASE_RESTRUCTURE_NOTICE` — saved in the phase report as an audit trail, not a blocker.)\n\n**It updates each phase's own plan right before coding it.**\nBefore any phase starts coding, a quick research pass reviews what the program has learned so far. It then updates that phase's checklist with new findings. This is called a **plan-supplement** step. Plans are never frozen — they absorb fresh facts from earlier phases.\n\n**It skips work that cannot start yet.**\nIf a phase depends on something not yet ready — a service not yet built, a decision not yet made — the agent marks that phase as dependency-blocked, sets it aside, and moves on to the next one. The whole program does not stall because one phase is waiting.\n\n**It knows when to stop and ask.**\nA single stuck phase just gets parked in a backlog and the program continues. But if several phases in a row hit a wall with no progress, the agent treats that as a real dead-end — a **cascade stop** — and pauses to show you what happened. One stuck phase is normal. Several in a row signals something structural is wrong.\n\n**It keeps a live scoreboard.**\nEvery program has a one-page status section in the umbrella plan showing which phase is current, whether it is done, and where the report lives. Anyone — or the agent itself after a memory reset — can read it and know exactly where things stand. It also keeps a simple file registry so two phases working at the same time never edit the same files.\n\n**One big final check.**\nAt the end of the whole program, the agent runs an end-to-end test that the entire project still works together — not just each piece on its own. Individual phase checkpoints prove each part works; this final check proves the parts work as a whole.\n\n---\n\n### 🧠 It Never Loses Its Place (Survives a Memory Reset)\n\nLong jobs finish correctly — even when the AI's memory resets mid-way. The plan, the progress, and the proof all live in files on disk, not only in the agent's head.\n\nAI agents have a limited working memory. On a long job that memory fills up and gets squeezed down — details can blur. When a new session starts (or memory is cleared), the agent does not guess where it left off. It reads the files.\n\nHere is exactly how that works:\n\n**1. It writes a short report after every phase.**\nWhen a phase finishes, a report file is written to disk. Progress lives in your project folder, not just in the agent's head. A memory squeeze cannot erase a file.\n\n**2. It keeps a checklist of which steps are done.**\nEach phase plan holds a **Phase Loop Progress** list — tick-boxes for every step (research, plan-check, build, test, capture learnings). After a reset, the agent reads those boxes and knows the exact next step. No need to catch it up.\n\n**3. A brief \"envelope\" at the start of every phase.**\nEvery worker agent (a focused helper that does one phase of work) opens by emitting a **Context Envelope** — a 10-field note: which feature, which phase, which branch, which plan file, which tests to run. It takes seconds to read. The agent is ready before it does anything.\n\n**4. It trusts the files over its own memory.**\nOn resume, the agent checks what is actually in the code and git history versus what the plan says. The real state wins. A plan that went stale cannot mislead the agent into repeating work or skipping steps.\n\n**5. A running scoreboard and per-round reports.**\nEvery fix loop (the plan-check loop and the build-test loop) keeps a `results.tsv` scoreboard file — one row per round, tracking how many issues remain. When a session ends mid-loop, the next session reads the count, picks up at the right round, and continues. No rounds are lost.\n\n**6. It re-injects a reminder on resume.**\nWhen memory is squeezed, the system automatically reloads the latest status note into the new session. If any approval was pending — say, a checkpoint that needed a \"yes\" before moving on — the reminder flags it. Nothing is silently skipped.\n\n\u003e 💡 In short: you can start an autopilot run, close your laptop, and come back hours later. The agent will be exactly where it should be — or will pick up from the last saved checkpoint, with evidence on disk to prove it.\n\n---\n\n## 🧠 Context Groups\n\nProject knowledge is organized into **context groups** — stable knowledge areas, each with an `all-{group}.md` router file that tells agents what to read and when. Agents follow the router, loading only what is relevant — not the whole knowledge base every time.\n\n\u003cbr\u003e\n\n```\nprocess/context/\n├── all-context.md              # 🧭 Root router — architecture, stack, patterns, conventions\n├── tests/all-tests.md          # 🧪 Test runners, commands, debugging procedures\n├── container/all-container.md   # 🐳 Docker, deployment, infra procedures\n├── uxui/all-uxui.md            # 🎨 Components, design tokens, patterns\n├── infra/all-infra.md          # 🖥️ Server infrastructure, deployment\n└── {your-domain}/all-{domain}.md  # 📚 Any domain with 3+ durable docs (auto-promoted)\n```\n\n| | How it works |\n|---|---|\n| 🧭 **Router pattern** | Agents read only what is relevant to their task |\n| 📏 **Auto-promotion** | Topics with 3+ docs (or a single file that gets too large) get their own group |\n| 🔄 **Always current** | Updated by `vc-update-process-agent` after every non-trivial feature |\n| 🧪 **Auditable** | `vc-audit-context` checks routing, discovery frontmatter, and consistency |\n| 📨 **Context Envelope** | Every inner-loop agent emits a 10-field note at start (feature → phase → session-goal → branch → worktree → context-group → blast-radius-packages → active-plan → test-runner → validate-contract) so a fresh worker agent knows exactly where it stands |\n\n\u003e The kit ships only the protocol seed — your context groups are **built for your project** by `vc-setup`, scanning your real code. They are a pattern, not a fixed list.\n\n---\n\n## 📁 Feature Folders\n\nWhen a topic builds up 5 or more files, it gets its own **feature folder** — a complete lifecycle container.\n\n```\nprocess/features/{feature}/\n├── active/{slug}_{date}/   # 📋 Plans being worked on (reports/refs colocated)\n├── completed/              # ✅ Archived plans (searchable decision history)\n└── backlog/                # 📌 Deferred work (agents check before duplicating)\n```\n\n| | What happens |\n|---|---|\n| 🆕 | New work starts in `active/` → reports accumulate → plan archives to `completed/` |\n| 📌 | Deferred work goes to `backlog/` — agents check it before creating duplicate plans |\n| 📦 | Feature promotion happens automatically when general artifacts hit 5+ |\n| 🔍 | Every feature has complete, self-contained history — plans, decisions, reports, research |\n\n---\n\n## 🧱 Skill Layers\n\nThe 33 skills fall into three layers. Every `SKILL.md` declares its `layer` + `trigger_keywords` in frontmatter, and a generated catalog keeps discovery fast.\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\u003ch1\u003e🎭\u003c/h1\u003e\n\u003cstrong\u003eActor agents\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nOwn a phase or role. Live in \u003ccode\u003e.claude/agents/\u003c/code\u003e — these are the 15 agents, not skills.\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\u003ch1\u003e📜\u003c/h1\u003e\n\u003cstrong\u003eContract skills (20)\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nEach one produces a specific file or agreed output — \u003ccode\u003evc-generate-plan\u003c/code\u003e, \u003ccode\u003evc-validate-findings\u003c/code\u003e, \u003ccode\u003evc-autopilot\u003c/code\u003e, the audits. Results can be checked.\n\u003c/td\u003e\n\u003ctd width=\"33%\" valign=\"top\"\u003e\n\u003ch1\u003e🛠️\u003c/h1\u003e\n\u003cstrong\u003eHelper skills (13)\u003c/strong\u003e\u003cbr\u003e\u003cbr\u003e\nImprove \u003cem\u003ehow\u003c/em\u003e agents work, produce no file of their own — \u003ccode\u003evc-scout\u003c/code\u003e, \u003ccode\u003evc-sequential-thinking\u003c/code\u003e, \u003ccode\u003evc-problem-solving\u003c/code\u003e, \u003ccode\u003evc-docs-seeker\u003c/code\u003e.\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🧠 Self-Improving Project Memory\n\nEvery completed feature feeds learnings back into the context system — **the knowledge builds up, it does not reset.**\n\nMost AI-assisted codebases have the opposite property: every new session starts cold. The agent re-reads the same files, re-discovers the same patterns, and re-makes the same decisions — because the last session's insight lived only in a chat window. The kit's answer is not a prompt trick. It is a **durable context-file system** (`process/context/`) that every agent reads at session start, every validator protects, and every completed feature enriches.\n\nSix months and many memory resets later, the agent still knows *why* your auth works the way it does — because that knowledge is on disk, routed, and auditable, not trapped in a dead session.\n\n\u003cbr\u003e\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    FEAT[\"Feature ships\\n(EXECUTE + EVL complete)\"]\n    UP[\"UPDATE PROCESS phase\\nvc-update-process-agent\"]\n    CTX[\"process/context/ updated\\nsmallest relevant file\\n+ all-context.md router\"]\n    AGENT[\"Next agent spawned\\nreads context router\\n→ routes to correct group file\"]\n    BETTER[\"Better next feature\\nno re-discovery, no stale patterns\"]\n    FEAT --\u003e UP --\u003e CTX --\u003e AGENT --\u003e BETTER\n    BETTER -.-\u003e|\"compounds each feature\"| FEAT\n\n    style FEAT fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style UP fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style CTX fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style AGENT fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style BETTER fill:#E65100,stroke:#BF360C,color:#FFFFFF\n```\n\n### The core mechanism: `process/context/` as portable, shared memory\n\n`process/context/` holds structured knowledge organized into topic groups — architecture decisions, coding conventions, deployment steps, test patterns, infrastructure facts. Unlike a chat history, this knowledge:\n\n- **travels into every worker agent** — `vc-context-discovery` routes each spawned agent to the right `all-{group}.md` router for its task, then to the smallest relevant deep file. A research agent, a plan agent, and a coding agent all start with the same shared understanding\n- **survives a memory reset** — it is on disk, not in a context window; a squeezed session loses none of it\n- **is readable by both Claude and Codex** — `.agents/skills` is a shortcut link to `.claude/skills/`, so the same context system serves both agents without duplication\n\nThe root router (`all-context.md`) points to group routers (`all-{group}.md`), which route to the smallest relevant deep file. Agents follow the router — they never hard-code file paths. This means renames and group splits require only router edits, not a codebase-wide search.\n\n```\nprocess/context/\n├── all-context.md                  ← root router (architecture, stack, patterns)\n├── tests/all-tests.md              ← test runners, debugging, commands\n├── container/all-container.md      ← Docker, deployment, infra procedures\n├── uxui/all-uxui.md                ← components, design tokens, visual conventions\n└── {domain}/all-{domain}.md        ← any domain with 3+ durable docs (auto-promoted)\n```\n\n\u003cbr\u003e\n\n### What makes it self-improving (not just \"living docs\")\n\nThe phrase \"living docs\" usually means \"docs we intend to keep up to date but mostly forget.\" This system enforces the intention mechanically.\n\n**The UPDATE PROCESS phase requires a per-file context review before it can close.** `vc-update-process-agent` cannot finish a phase until every potentially-affected context file has been reviewed with a concrete reason per file. \"No updates needed\" is allowed — but it must name each reviewed file and explain why. Vague reasons are rejected. The checkpoint is binary: record the review, or the phase does not close.\n\nThe full feedback loop per completed feature:\n\n| Step | Owner | What happens |\n|------|-------|-------------|\n| 1. Git diff analysis | `vc-scout` | Maps changed files → affected context areas |\n| 2. Per-file review | `vc-update-process-agent` | Names each context file, states the update or an explicit \"no change + reason\" |\n| 3. Updates applied | parallel worker agents | Each area's context file is updated with new patterns, decisions, learnings |\n| 4. Routing verified | `validate-context-discovery.mjs` | Confirms every doc is indexed and routers are consistent |\n| 5. Discovery confirmed | `validate-all-context.mjs` | Confirms `all-context.md` and group routers match the current files on disk |\n\nYour 100th feature benefits from everything learned in the first 99 — not as an aspiration, but as a mechanical guarantee.\n\n\u003cbr\u003e\n\n### Forward Preview: learnings feed forward, not just backward\n\nEvery phase report carries a `## Forward Preview` section written for the *next* phase's agent. It gives the exact commands to keep green, dependency changes, and file-scope changes found mid-phase. The agent picking up Phase 3 does not have to re-read Phase 2's output and guess what matters. It is handed a focused brief.\n\nThis is different from context docs: context docs carry *lasting* knowledge (decisions that stay true across features); Forward Preview carries *temporary* handoff state (what the next work session needs to know right now).\n\n\u003cbr\u003e\n\n### Validator suite prevents rot\n\nLasting knowledge goes stale when nobody checks it. The kit ships validators that run as part of every phase closeout:\n\n| Validator | What it catches |\n|-----------|----------------|\n| `validate-context-discovery.mjs` | Docs not indexed by any router; broken links; missing frontmatter |\n| `validate-all-context.mjs` | `all-context.md` out of sync with actual files on disk |\n| `validate-skill-keywords.mjs` | Skills missing `trigger_keywords` or `layer` fields (breaks routing Step 0) |\n| `validate-protocol-discovery.mjs` | Protocol files in `process/development-protocols/` missing discovery frontmatter |\n\nThese run like automated checks — a stale or orphaned doc fails. The system polices its own health.\n\n\u003cbr\u003e\n\n### Context groups self-organize\n\nGroups are created automatically when a topic reaches 3+ docs or a single file goes past ~800 lines. Agents follow routers and never hard-code paths — so adding a new group (e.g. `process/context/billing/all-billing.md`) requires only a router update, not changes to every agent that mentions billing. The router is the stable reference; the files behind it can reorganize freely.\n\n\u003e The kit seeds context groups from your real codebase (via `vc-setup`). The groups are not a fixed list — they are a pattern. Your auth area, your infra area, your payments area each become first-class routable knowledge as the project grows.\n\n---\n\n## 🤖 What's Inside\n\n\u003cbr\u003e\n\n### 15 Agents\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand the agent roster\u003c/summary\u003e\n\n\u003cbr\u003e\n\n**Core workflow agents** — one per RIPER-5 phase (R → SPEC → I → P → V → E → UP):\n\n| Agent | Model | Role |\n|-------|:---:|------|\n| 🔍 `vc-research-agent` | sonnet | Codebase + web research, read-only. Contradiction tracking built in |\n| 📝 `vc-spec-agent` | sonnet | Product-discovery requirements doc before INNOVATE. Produces `*_SPEC_*.md` |\n| 💡 `vc-innovate-agent` | sonnet | Compare 2-3 approaches. Decision summary (chosen + rejected) before PLAN |\n| 📋 `vc-plan-agent` | sonnet | Write the plan with anti-shortcut guards. \"I already know how\" is not a plan |\n| ✅ `vc-validate-agent` | sonnet | Turn plan → agreed checklist (V1–V7). Checkpoint: PASS/CONDITIONAL/BLOCKED |\n| ⚡ `vc-execute-agent` | **opus** | Implement per plan. Progress notes to phase report, deviation protocol, self-review |\n| ⏩ `vc-fast-mode-agent` | **opus** | Compressed R→S→I→P→V with a required safety pause before EXECUTE |\n| 🔧 `vc-quick-fix-agent` | **opus** | QUICK FIX lane: one small low-risk edit + scoped check, no plan/validate |\n| 🧠 `vc-update-process-agent` | sonnet | 7-phase closeout: archive, update context, stale-artifact scan, learnings |\n\n\u003cbr\u003e\n\n**Specialist agents** — called during EXECUTE or standalone:\n\n| Agent | Role |\n|-------|------|\n| 🐛 `vc-debugger` | Gathers evidence before forming a hypothesis. Competing hypotheses, elimination chains, feasibility probes |\n| 🧪 `vc-tester` | Change-aware. Re-runs agreed-checklist tests (EVL). Auto-escalates on config changes |\n| 🔎 `vc-code-reviewer` | Sends an edge-case scout BEFORE review. N+1 detection, auth-path checking |\n| ✨ `vc-code-simplifier` | Tidies code for clarity without changing behavior |\n| 🎨 `vc-ui-ux-designer` | Design-aware frontend. Can spawn a research worker mid-build |\n| 📦 `vc-git-manager` | Splits into logical commits from `touched_files`. Refuses unknown files |\n\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n### 33 Skills (auto-discovered)\n\n\u003cdetails\u003e\n\u003csummary\u003eClick to expand the skill list (20 contract + 13 helper)\u003c/summary\u003e\n\n\u003cbr\u003e\n\n**📜 Contract skills (20)** — own an artifact: `vc-generate-plan` · `vc-generate-context` · `vc-generate-spec` · `vc-generate-closeout` · `vc-generate-phase-program` · `vc-audit-context` · `vc-audit-plans` · `vc-audit-vc` · `vc-update` · `vc-publish` · `vc-feasibility-test` · `vc-risk-evidence-pack` · `vc-test-coverage-plan` · `vc-validate-findings` · `vc-autoresearch` · `vc-intent-clarify` · `vc-autopilot` · `vc-agent-strategy-compare` · `vc-plan-discovery` · `vc-context-discovery`\n\n**🛠️ Helper skills (13)** — improve how agents work: `vc-review-situation` · `vc-sequential-thinking` · `vc-problem-solving` · `vc-scout` · `vc-debug` · `vc-docs-seeker` · `vc-frontend-design` · `vc-agent-browser` · `vc-web-testing` · `vc-setup` · `vc-predict` · `vc-scenario` · `vc-security`\n\n\u003c/details\u003e\n\n\u003e **⚠️ Naming rule:** Do NOT use the `vc-` prefix for your own skills or agents — that namespace is reserved for kit-shipped files, and the stale-removal guard treats any `vc-*` path under `.claude/skills/` and `.claude/agents/` as kit-owned. Use `my-`, `team-`, or `proj-` instead.\n\n\u003cbr\u003e\n\n### 🪝 10 Hooks\n\n| Hook | What it does |\n|------|-------------|\n| 🔐 `privacy-block.cjs` | Blocks reading `.env`, credentials, SSH keys. Requires explicit approval |\n| 🚫 `scout-block.cjs` | Prevents wandering into `node_modules/`, `dist/`. Gitignore-syntax `.ckignore` |\n| 🧠 `session-init.cjs` | Detects stack, injects env, recovers approval gates after compaction |\n| 💉 `subagent-init.cjs` | Injects a compact context block into every subagent |\n| ✨ `post-edit-simplify-reminder.cjs` | After 5+ edits, nudges to run the simplifier (non-blocking, throttled) |\n| 📛 `descriptive-name.cjs` | Language-aware file-naming conventions on every Write |\n| 📊 `session-state.cjs` | Session metrics + token awareness |\n| 📋 `post-write-plan-check.mjs` | Validates plan-artifact structure on every Write to a `*_PLAN_*.md` |\n| 🧹 `post-commit-lint.mjs` | Checks conventional-commits prefix on every `git commit` |\n| 🔍 `stop-validator-sweep.cjs` | Runs core harness validators when the session stops |\n\n\u003cbr\u003e\n\n**Where everything lives:**\n\n```text\nyour-project/\n├── .claude/{agents,skills,hooks}/   # 🤖 15 agents · ⚡ 33 skills · 🪝 10 hooks\n├── .codex/agents/                   # 🔄 Mirrored for Codex\n├── .agents/skills -\u003e .claude/skills # 🔗 Symlink for Codex discovery\n├── CLAUDE.md · AGENTS.md            # 📋 Orchestrator config + cross-tool registry\n└── process/\n    ├── context/                     # 🧠 Auto-routed knowledge domains\n    ├── general-plans/               # 📋 Cross-cutting plans + task folders\n    ├── features/                    # 🏷️ Feature-scoped lifecycle folders\n    └── development-protocols/       # 📜 22 shared workflow docs\n```\n\n---\n\n## ⚡ Quick Fix + Fast Mode\n\nTwo lighter options for when the full RIPER-5 process is more than the job needs:\n\n\u003ctable\u003e\n\u003ctr\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e🔧\u003c/h1\u003e\n\u003cstrong\u003eQuick Fix\u003c/strong\u003e — \u003ccode\u003e\"quick fix: …\"\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\nBigger than a trivial one-liner, smaller than \"needs a plan.\" The lead agent scouts read-only → one-line confirm → spawns \u003ccode\u003evc-quick-fix-agent\u003c/code\u003e for the edit + a scoped check on touched files only. \u003cstrong\u003eNo plan, no agreed checklist, no EVL.\u003c/strong\u003e\n\u003cbr\u003e\u003cbr\u003e\n\u003csub\u003eCancelled immediately if the change touches schema, auth, API, billing, or migration surfaces — then it routes to full RESEARCH.\u003c/sub\u003e\n\u003c/td\u003e\n\u003ctd width=\"50%\" valign=\"top\"\u003e\n\u003ch1\u003e⏩\u003c/h1\u003e\n\u003cstrong\u003eFast Mode\u003c/strong\u003e — \u003ccode\u003e\"ENTER FAST MODE - …\"\u003c/code\u003e\u003cbr\u003e\u003cbr\u003e\nSqueezes RESEARCH + SPEC + INNOVATE + PLAN + VALIDATE into one pass — but still \u003cstrong\u003ewrites a plan, writes an agreed checklist, and pauses before EXECUTE.\u003c/strong\u003e\n\u003cbr\u003e\u003cbr\u003e\n\u003csub\u003eIn plain Fast Mode, there is a post-VALIDATE pause — you review, then say \"ENTER EXECUTE MODE.\" Use \u003ccode\u003eautopilot fast: [task]\u003c/code\u003e to remove that pause and run all the way through without stopping.\u003c/sub\u003e\n\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/table\u003e\n\n---\n\n## 🔄 Kit Lifecycle: Install · Setup · Update · Publish\n\n| Command | What it does | When |\n|---|---|---|\n| `curl … install.sh \\| bash` | Syncs kit files without overwriting yours; auto-detects fresh vs upgrade and routes you | First install + every upgrade |\n| **Run vc-setup** | Detects stack, scaffolds `process/`, deep-scans codebase, populates real context | After a fresh install |\n| **Run vc-update** | Computes a precise diff, shows what will change, waits for your OK; migrates old-format plans/folders with zero data loss | On every upgrade |\n| **Run vc-publish** *(maintainers)* | Publishes harness changes back out to the kit repo | Contributing to the kit itself |\n\n```mermaid\n%%{init: {'theme': 'base', 'themeVariables': {'fontSize': '14px', 'lineColor': '#8888AA'}} }%%\nflowchart TD\n    TRG[\"EXECUTE complete\\nENTER UPDATE PROCESS MODE\"]\n    AGT[\"spawn vc-update-process-agent\"]\n    A[\"(a) Archive plan\\nactive/ → completed/\"]\n    B[\"(b) Update process/context/\\nsmallest relevant file\\n+ all-context.md router\"]\n    C[\"(c) Tier-1 audits\\n(change-type gated)\"]\n    AVC[\"vc-audit-vc\\nharness/agent edits\"]\n    ACX[\"vc-audit-context\\ncontext-doc edits\"]\n    APL[\"vc-audit-plans\\nplan/program edits\"]\n    D[\"(d) Capture learnings\\nto memory\"]\n    E[\"(e) Write closeout packet\\nvc-generate-closeout\"]\n    F[\"(f) Conventional commit\\nvc-git-manager\"]\n\n    TRG --\u003e AGT --\u003e A --\u003e B --\u003e C\n    C --\u003e AVC\n    C --\u003e ACX\n    C --\u003e APL\n    AVC --\u003e D\n    ACX --\u003e D\n    APL --\u003e D\n    D --\u003e E --\u003e F\n\n    style TRG fill:#1565C0,stroke:#0D47A1,color:#FFFFFF\n    style AGT fill:#0277BD,stroke:#01579B,color:#FFFFFF\n    style A fill:#6A1B9A,stroke:#4A148C,color:#FFFFFF\n    style B fill:#00695C,stroke:#004D40,color:#FFFFFF\n    style C fill:#E65100,stroke:#BF360C,color:#FFFFFF\n    style AVC fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style ACX fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style APL fill:#2E7D32,stroke:#1B5E20,color:#FFFFFF\n    style D fill:#558B2F,stroke:#33691E,color:#FFFFFF\n    style E fill:#C62828,stroke:#B71C1C,color:#FFFFFF\n    style F fill:#37474F,stroke:#263238,color:#FFFFFF\n```\n\n\u003e 💡 `vc-update` shows a preview diff and waits for your OK. Your `process/` directory and project-specific content are **never** silently changed. Re-running install is safe to run twice.\n\n---\n\n## 💡 More Reasons It Just Works\n\nMany small, smart defaults add up to less babysitting and lower cost.\n\n- **Each role only gets the tools it needs.** During planning, the agent literally cannot edit code — those tools are turned off. This stops the agent from jumping ahead and changing things before the plan is approved. The system simply does not allow it.\n\n- **It uses the premium AI model only where it matters.** Code-writing uses the top model. Planning, research, review, and checking all use a cheaper, faster model. The result: roughly 60–70% lower cost compared to running the top model for everything — with no quality loss on the work that counts.\n\n- **It tests risky guesses before building on them.** When the agent is not sure something will work — a specific API behavior, a library feature, an infrastructure assumption — it runs a tiny real experiment first. The result is clear: works, does not work, or unclear. That verdict and a plain-English note get fed straight into the plan. The agent does not spend hours building on a wrong assumption.\n\n- **Tidy, meaningful save points.** Changes are committed in clean, logical chunks with clear messages — automatically. The history is easy to read and easy to undo one piece at a time.\n\n- **Helpful automatic reminders.** Small built-in helpers nudge for things like running the right checks on changed files, keeping code simple, and writing a proper commit message. Quality stays high without you having to police it.\n\n- **You can run the self-improving loop on its own.** The same \"find problems, fix them, repeat\" engine that drives plan-checking and test-fixing also works as a standalone tool on any messy area — a spec, the docs, the tests, an error list. You do not need a full feature build to use it.\n\n- **Built-in proof the workflow rules actually work.** The kit ships with its own test suite: a set of checks with known-good and known-bad examples that prove the workflow rules behave correctly. The system checks itself. You do not have to trust that the guardrails are on — you can run the checks and see.\n\n---\n\n## Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n\u003cbr\u003e\n\n**Quick links:**\n\n- 🐛 [Report a bug](https://github.com/withkynam/vibecode-pro-max-kit/issues/new?template=1.bug_report.yml)\n- 💡 [Request a feature](https://github.com/withkynam/vibecode-pro-max-kit/issues/new?template=2.feature_request.yml)\n- ⚡ [Submit a skill](https://github.com/withkynam/vibecode-pro-max-kit/issues/new?template=3.skill_submission.yml)\n- 🌐 [Add a translation](https://github.com/withkynam/vibecode-pro-max-kit/issues/new?template=5.translation.yml)\n\n\u003cbr\u003e\n\n\u003ca href=\"https://github.com/withkynam/vibecode-pro-max-kit/graphs/contributors\"\u003e\n  \u003cimg src=\"https://contrib.rocks/image?repo=withkynam/vibecode-pro-max-kit\" alt=\"Contributors\" /\u003e\n\u003c/a\u003e\n\n\u003cbr\u003e\n\n### 🙏 Credits\n\nvibecode-pro-max-kit focuses on the spec-driven development framework and self-improving context organization, without bloating you with 80+ skills. Fewer tools, more structure.\n\n---\n\n## ⭐ Star History\n\n\u003ca href=\"https://star-history.com/#withkynam/vibecode-pro-max-kit\u0026Date\"\u003e\n \u003cpicture\u003e\n   \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=withkynam/vibecode-pro-max-kit\u0026type=Date\u0026theme=dark\" /\u003e\n   \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=withkynam/vibecode-pro-max-kit\u0026type=Date\" /\u003e\n   \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=withkynam/vibecode-pro-max-kit\u0026type=Date\" /\u003e\n \u003c/picture\u003e\n\u003c/a\u003e\n\n---\n\n## 📄 License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwithkynam%2Fvibecode-pro-max-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwithkynam%2Fvibecode-pro-max-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwithkynam%2Fvibecode-pro-max-kit/lists"}