vibekit

vibekit

Vibekit is a discipline-first vibe-coding plugin for Claude Code, OpenAI Codex, OpenCode, Gemini CLI, and Pi. One command, /vibe <intent>, drives a 7-stage pipeline (brainstorm → plan → isolate → exec → verify → review → integrate) that produces a verified, user-approved feature. For autonomy, /ralph-loop re-runs /vibe across iterations until verify-gate is satisfied, bounded by budgets, and never bypassing sign-off.

Token-efficient per feature: subagent briefs are RTCO-compressed and reports are schema-stripped, while every guardrail, evidence quotes, plans, constraints, degradation warnings, stays verbatim.

Guardrails are non-negotiable. If the plan is wrong or the tests don't pass, the pipeline halts loudly, it does not silently commit the wrong thing.

---

What you get

• /vibe <intent>, the full 7-stage pipeline in one command.
• /ralph-loop <intent>, autonomous bounded re-run of /vibe with a blocker classifier and thrashing critic. Same gates, never bypasses sign-off.
• Fifteen invocable skills that also work standalone, plus an auto-loaded priming layer (using-vibekit) that carries the trigger map.
• Auto-trigger discipline. A SessionStart hook (Claude Code) and equivalent adapters (Codex native discovery, Gemini @-import, opencode plugin, Pi before_agent_start extension) load using-vibekit into every session so pipeline skills cannot be silently skipped.
• Evidence-based verification. Every "done" claim is backed by the exact test output, verbatim.
• Halt-and-report discipline. Real live eval caught two plan defects cleanly, neither reached a commit.
• Token-efficient by design. Compression is applied to agent framing, every guardrail stays verbatim.
• Karpathy-aligned discipline. Four-axis authoring contract: PEG (substance), Karpathy (behavior), Caveman (style), Quad-Adapter (cross-runtime portability).
• Parallel-group dispatch when a plan marks tasks as independent, with honest sequential fallback on runtimes that lack parallel subagents.
• Cross-session knowledge. memory-dual captures durable project knowledge, atomic facts, compound documents, and a working notepad, under one file-backed convention.

---

Install

Choose your runtime below and use its native plugin or package installer bellow:

Claude Code

From a marketplace that hosts this plugin:

/plugin marketplace add rizukirr/vibekit
/plugin install vibekit@vibekit

From a local clone:

git clone <this repo>
cd vibekit
# then add the repo path as a plugin source in Claude Code settings

After installation, restart Claude Code. The /vibe command and all skills become available.

OpenCode

Install @rizukirr/vibekit using npm:

npm install -g @rizukirr/vibekit 

Then add the scoped npm package name to an OpenCode configuration file:

• Global, for all projects: ~/.config/opencode/opencode.json
• Project-specific: <project-root>/opencode.json

OpenCode also accepts the .jsonc extension. It will install and load the configured package through its own package cache:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@rizukirr/vibekit"]
}

Tell the agent:

Fetch and follow instructions from https://raw.githubusercontent.com/rizukirr/vibekit/refs/heads/main/.opencode/INSTALL.md

That keeps installation instructions centralized in one file and avoids README drift.

OpenAI Codex

Register and install the plugin through its Codex marketplace:

codex plugin marketplace add rizukirr/vibekit
codex plugin add vibekit --marketplace vibekit

Restart Codex after installation. Detailed Codex docs, including verification steps, are in .codex/INSTALL.md.

Gemini CLI

Use Gemini's extension installer with the GitHub URL:

Tell Gemini CLI:

Fetch and follow instructions from https://raw.githubusercontent.com/rizukirr/vibekit/refs/heads/main/INSTALL.gemini.md

Detailed Gemini docs: INSTALL.gemini.md.

Pi

Use Pi's package installer with either the npm release or Git repository:

Tell Pi:

Fetch and follow instructions from https://raw.githubusercontent.com/rizukirr/vibekit/refs/heads/main/.pi-plugin/INSTALL.md

Manual installation is also documented in .pi-plugin/INSTALL.md.

Quick install (global settings):

# Pinned npm release:
pi install npm:@rizukirr/vibekit@0.5.2

# Or track the git repository:
pi install git:github.com/rizukirr/vibekit

Install into project settings (.pi/settings.json) instead of global settings:

pi install git:github.com/rizukirr/vibekit -l

Useful maintenance commands:

pi list
pi update
pi remove git:github.com/rizukirr/vibekit

Heads-up, possible conflict if vibekit is already installed. Pi reads skills from ~/.agents/skills/ as well as Pi package sources. If you previously installed vibekit for another runtime (commonly Codex, which symlinks ~/.agents/skills/vibekit/), Pi can already see every vibekit skill from that path, and installing again can produce benign "skill collision" warnings on startup. Check first:

ls ~/.agents/skills/vibekit/ 2>/dev/null

If that lists 16 skill directories, vibekit is already reachable on Pi via /skill:<name>. Skip pi install to avoid collision warnings, or follow the "Avoiding collisions" guidance in .pi-plugin/INSTALL.md.

---

Quick start

/vibe add a toKebabCase utility with tests

What happens:

1. Brainstorm. The pipeline asks a few clarifying questions (edge cases, scope, testing approach), proposes 2–3 approaches with trade-offs, and writes a short design doc you sign off on.
2. Plan. It produces a TDD-shaped implementation plan, every step is bite-sized, every command is exact, every commit is named.
3. Isolate. A git worktree gets created so your main branch is untouched.
4. Execute. Each task runs in a fresh subagent with a tight brief. On any "Expected" mismatch, the agent halts and reports, no improvised fixes.
5. Verify. Every spec requirement is checked against the actual evidence. Three independent verdict passes per requirement.
6. Review. A self-critique surfaces blocks / warns / nits. You see the full diff.
7. Integrate. You pick: merge locally, open a PR, keep the branch, or abandon. Nothing ships without your explicit choice.

You only talk to the pipeline during brainstorm and at each gate. The rest is autonomous.

---

The skills

All 15 invocable skills live in skills/ and can be used standalone. A 16th skill, using-vibekit, is the priming layer, it is auto-loaded on session start by every supported runtime and is not invoked manually.

Pipeline:

Skill	Role
vibe	Orchestrator for the 7-stage pipeline.
brainstorm-lean	Disciplined Socratic design gate with a HARD-GATE before implementation, pushback turn challenges framing before approaches are proposed.
plan-write	TDD-shaped, bite-sized implementation plan with exact commands, mandatory → verify: clause per task, optional parallel-group markers.
brief-compiler	Turns verbose intents into tight RTCO subagent briefs with surgical-change constraints baked in.
exec-dispatch	One fresh subagent per task, two-stage review, parallel-group fan-out where the runtime supports it.
report-filter	Validates subagent returns against the declared schema, rejects drift.
verify-gate	Evidence-based completion check, three independent verdict dispatches per requirement, plus a fail-closed surgical-diff pass.
review-pack	Reflexion-style self-critique with simplicity + surgical-diff passes, then user sign-off on the diff.
security-review	Optional threat-model gate, peer to review-pack. Tiered security pass over the diff, universal code-security always, AI-artifact checks when the diff builds a skill/agent/prompt/MCP server. Blocks finish-branch on CRITICAL/HIGH with a written-waiver escape.
finish-branch	Integration endpoint, merge / PR / keep / abandon, no auto-actions.
isolate	Dedicated worktree or branch per run, rollback is cheap.

Cross-cutting:

Skill	Role
memory-dual	Durable project knowledge under .vibekit/memory/, atomic facts and compound documents in one storage convention, plus a working notepad. Keyword + tag + type search, [[key]] cross-links, audit pass.
vibekit-doctor	Diagnostic health check, skill files, runtime registrations, .vibekit/ health, docs/ subdirs, authoring contracts. Read-only by default, --fix for safe repairs.
debug-recovery	Pipeline failure branch + standalone debugger. Stop-the-line root-cause triage with one fresh read-only confirmation dispatch, produces a proven diagnosis and routes the fix to exec-dispatch/plan-write. Never edits code.
ralph-loop	Autonomous-driver peer to vibe, bounded persistence loop with blocker classifier and thrashing critic. Same gates, same sign-off, no shortcuts. Cross-runtime with degraded checkpoint mode where native loops are absent.

---

The guardrails

Non-negotiable. None of them can be bypassed by a flag.

• No implementation without an approved spec.
• No dispatch without a plan.
• No commit without the task's exact test command running and passing.
• No "done" claim without evidence quoted verbatim.
• No merge / PR / push without explicit user sign-off.
• On any "Expected" mismatch: halt and report, never improvise a fix.

This is what keeps vibe-coding from turning into vibe-disasters.

---

Token budget

Measured in live eval on a small feature (toKebabCase utility, 2-task plan, 1 verification pass):

• Total subagent tokens: ~118k across 4 dispatches.
• Wall clock: minutes per dispatch, dominated by test-runner I/O.
• Compression concentrated in agent briefs + reports, guardrails stay full prose.

Large features scale linearly with task count. Verification cost scales with requirement count × 3 (self-consistency). For large specs the verify-gate skill offers a critical-only mode.

---

Philosophy

• Form compresses, guardrails don't. Agent framing is fragmented, evidence and constraints are verbatim.
• Halt is a feature. The pipeline would rather stop and surface a defect than improvise.
• One thing per run. No mega-runs. One feature, one spec, one plan, one integration choice.
• Files over summaries. Stages hand off via committed files, never prose summaries.
• Cross-runtime portability is a contract, not a hope. Every runtime-coupled skill declares its required capabilities and ships a documented fallback for runtimes that lack them, with a verbatim degradation warning, never a silent skip.

---

Evals

Three evals are on record under docs/evals/:

• 2026-04-21-static-eval-run-01.md, initial static walkthrough, found 3 blocking defects, 7 warns, 4 nits.
• 2026-04-21-static-eval-run-02.md, post-fix re-walk, all blockers resolved, no regressions.
• 2026-04-21-live-eval-run-03.md, live dispatch on a throwaway repo, the halt-and-report discipline was proven twice under real subagents.

Re-running the evals after substantive skill changes is recommended. A packaged harness will come in a later release.

---

License

MIT.

Acknowledgements

Thanks to all plugins that inspired this one, especially:

• superpowers
• omc
• andrej-karpathy-skills
• caveman
• Prompt-Engineering-Guide