# 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:

```bash
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:

```bash
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:

```json
{
  "$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:

```bash
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:

```bash
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):

```bash
# 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:

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

Useful maintenance commands:

```bash
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:**
>
> ```bash
> 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](https://github.com/obra/superpowers)
- [omc](https://github.com/Yeachan-Heo/oh-my-claudecode)
- [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills)
- [caveman](https://github.com/JuliusBrussee/caveman)
- [Prompt-Engineering-Guide](https://github.com/dair-ai/Prompt-Engineering-Guide)