Spec Before Code: How I Built a 9-Skill Framework for AI-Driven Development

Every developer who works seriously with an AI coding agent knows the ritual. You open a fresh session, and before any real work happens, you perform the recap: here's the stack, here's the architecture, here's what we decided last week, please don't use that library again. Ten minutes of re-explaining, every single session — and the agent still occasionally "improves" something you explicitly told it to leave alone.

The model wasn't the problem. Claude is an exceptional engineer when it has context. The problem was that the context lived in my head and in scrollback, and both of those evaporate. A chat transcript is not a project memory. The context window is a desk, not a filing cabinet — whatever isn't written down somewhere durable gets re-litigated tomorrow.

So I stopped trying to prompt better and started building a system. The result is the vibe-* framework: nine purpose-built skills for Claude Code that cover the full development lifecycle, all anchored to one rule — nothing gets built before it gets written down. It now runs on live client projects at BetaCraft, and it's the closest thing I've found to giving an AI agent an actual long-term memory and a work ethic.

The core insight is almost embarrassingly simple. Human teams solved the amnesia problem decades ago — not with bigger brains, but with documents. Specs, architecture decision records, task boards. The vibe-* framework just applies that discipline to the AI: every project gets a vibe/ folder, and every skill reads from and writes to it.

• BRIEF.md: What we're building and why — produced by the brainstorm skill, validated before anything else happens. Scope lives here, so scope arguments end here.
• ARCHITECTURE.md: The patterns, the stack, the principles. Read at the start of every agent session; every code decision is measured against it.
• SPEC.md & PLAN.md: Acceptance criteria and the phased build plan. The agent doesn't decide what "done" means — the spec does.
• TASKS.md: The single human-facing progress file. One glance tells you what's shipped, what's active, and what's blocked.
• DECISIONS.md: An append-only log of every scope change and trade-off. The agent consults history instead of re-arguing it.

Each skill is a structured workflow with a natural-language trigger. You don't configure anything — you just talk, and the right process kicks in. Together they cover the lifecycle from "I have an idea" to "this is reviewed and shipped."

The Chain

The skills compose into a pipeline: brainstorm: → architect: → new:, then loops of feature: / bug: / change:, each one closed by review:. Order matters — every downstream skill reads the documents its predecessors wrote, which is exactly why no step ever starts from zero context.

Here's what a real project looks like under the framework. After brainstorm: and architect: have run, new: scaffolds the workspace — and from that point on, every Claude session begins by reading this folder instead of asking me to repeat myself:

my-project/
├── CLAUDE.md            ← agent's standing orders, read every session
└── vibe/
    ├── BRIEF.md         ← what & why (from brainstorm:)
    ├── ARCHITECTURE.md  ← how, structurally (from architect:)
    ├── SPEC.md          ← acceptance criteria
    ├── PLAN.md          ← phased build plan
    ├── TASKS.md         ← human-facing progress view
    ├── DECISIONS.md     ← append-only decision log
    └── features/
        └── 2026-03-12-payments/
            ├── FEATURE_SPEC.md
            ├── FEATURE_PLAN.md
            └── FEATURE_TASKS.md

The discipline shows up at the boundaries. A phase cannot proceed while the review gate reports a P0 issue. A bug fix cannot be written before its regression test exists. A scope change cannot touch code before its impact assessment is logged. None of this slows the agent down — it slows down the mistakes. The agent works at full speed inside the rails; the rails just make sure full speed points in the right direction.

After running this across live BetaCraft client work and my own side projects (both Promptly and ctx/window were built end-to-end on the chain), the differences are concrete:

• Session startup went from minutes to seconds: No recap ritual. The agent reads CLAUDE.md and the vibe/ folder and already knows the project better than a new hire would after a week.
• Drift died: When every decision is written down and re-read each session, the agent stops "creatively" replacing libraries or reinventing patterns. The spec is law because the spec is present.
• Review caught what eyeballs miss: Forcing evidence-based review between phases — file paths and line numbers, not vibes — surfaced the class of bugs that compiles fine and fails in week three.
• Handoffs became trivial: Any developer (or any fresh agent instance) can pick up a project cold, because the project's entire memory is in the repo, not in someone's chat history.

The honest caveat: the framework front-loads effort. Writing a brief and an architecture doc before coding feels slow on day one. It stops feeling slow the first time a scope change lands mid-build and the impact assessment takes five minutes instead of a week of archaeology.

You don't need my exact nine skills — you need the principle they encode. Give your agent durable, versioned documents instead of ephemeral prompts. Make it read them at the start of every session. Put a review gate between phases. Log decisions where they can't be lost. Whether you build that as Claude Code skills, as a folder convention, or as team habit, the payoff is the same: an AI partner that remembers, and a codebase that can prove it.

The full framework — all skills, docs, and an interactive walkthrough — is published at aakashdhar.me/vibe-skill, free to clone and adapt.