vibe

vibe

A personal toolbox for vibe coding — a small, growing collection of things that make coding with an agent easier and more productive. Built mainly for my own private use, but structured to be forkable.

The idea is to stop guiding the agent turn-by-turn and start instructing it: say "I need X", and the tooling already knows the phase, the skills and subagents to use, and how terse to be — so attention goes to what to build, not how to walk the agent through it.

---

What's in the box

Tool	What it gives you	Lives in
Vibe flow	A state-machine-driven coding workflow (strategy / feature / quick) that routes each phase to the right skills, subagents, and output paths. The centerpiece.	.agents/skills/vibe/, .agents/skills/vibe-*
Spec framework	A durable .spec/ planning skill — product/tech/design/plan/lessons docs with templates and validation. Usable on its own, with or without the flow.	.agents/skills/spec/
Agent-file template	AGENTS.md template + merge-agents.sh (managed vibe:instructions block) and opt-in adapter symlinks (CLAUDE.md, WARP.md), so any runtime reads the same neutral core.	CLAUDE.md, AGENTS.md, .agents/skills/vibe-setup/
Claude Code plugin	.claude-plugin/plugin.json + three hooks (inject / guard / gate) + install.sh, so the flow fires every turn and guards its invariants.	.claude/, install.sh

More tools will land over time; this is a personal collection, not a product. The three above are the first cut.

---

The vibe flow

Everything starts at idle. The agent self-locates, then drives one flow. The cursor .agents/skills/vibe/state.json = {flow, phase, feature} points at one entry in .agents/skills/vibe/state-machine.json — the source of truth that holds each state's skill, delegates, caveman level, write surface, and legal next. Transition only via set-state.sh <flow.phase>.

flowchart TD
    I((idle)) -->|fresh repo| SD[setup.detect]
    I -->|set direction| SB[strategy.brainstorm]
    I -->|build a feature| FD[feature.design]
    I -->|small fix| QT[quick.triage]

flowchart LR
    subgraph strategy
        SB[brainstorm] --> SS[spec]
        SS -->|durable lesson| SC[compound]
    end
    subgraph feature
        D[design] --> P[plan]
        P -. human gate .-> IM[impl]
        IM --> V[verify]
        V -. human gate .-> C[compound]
        V -->|targeted fix| IM
        V -->|major drift| P
    end
    subgraph quick
        T[triage] --> F[fix] --> QV[verify]
        T -->|scope balloons| D
    end
    SS --> I((idle))
    SC --> I
    C --> I
    QV --> I

amend is a modifier, not a flow: it makes a targeted scope edit from any state, within that state's write rules, then returns there. The cursor is unchanged.

Phase map

Every phase, the skill shim that drives it, the external skills and feature-dev subagents it delegates to, its caveman density, the spec artifact it reads or writes, and what the stage is for. This mirrors state-machine.json.