01
←→ navigate
Skills framework · vibe coding

vibe-*
skills

Spec before code. Context preserved. Always.

The foundation

What is a skill?

Without a skill
Freeform vibes
Agent improvises, forgets between sessions, silently drifts from the plan
→
With a skill
Structured workflow
Step-by-step, verified against spec, every decision logged and auditable
A skill is a named, step-by-step workflow loaded into the agent's context at runtime. It tells Claude exactly what to ask, what to build, which files to touch, and how to verify done — replacing improvisation with a repeatable, auditable process.

Why this exists

AI agents forget, drift,
and improvise.

New session — agent has no idea what was built last time. You describe the project from scratch.
→ CLAUDE.md + CODEBASE.md read every session
Code written before anyone agreed on what "done" looks like. Spec written after the fact, if at all.
→ brainstorm: + new: + feature: enforce spec first
Patterns decided differently in every feature. Three files, three conventions, one codebase.
→ architect: locks patterns, review: catches drift
Scope change absorbed mid-task. No impact check. No doc update. No one knows what changed.
→ change: shows impact before touching any file
Bug fixed by guessing. No regression test. Same bug reappears two features later.
→ bug: writes the failing test before the fix
No quality gate before shipping. Bad patterns from Phase 1 copied into every feature.
→ review: blocks progression until P0s are resolved

The four principles

The 4 Principles

01
Spec before code
No task starts without acceptance criteria. Agent re-reads spec after every task and ticks every criterion before marking done.
02
Context preservation
Agents forget between sessions. ARCHITECTURE.md, CODEBASE.md, SPEC_INDEX.md, TASKS.md, CLAUDE.md read at every session start.
03
Incremental progress
One task at a time. Confirm → build → verify → commit → done. No batching. No running ahead.
04
Drift prevention
DECISIONS.md logs every deviation. change: stops the build. review: checks architecture at every gate.

The full workflow

10 skills. One pipeline.

brainstorm:
Brainstorm
Idea → BRIEF.md
›
architect:
Architect
Patterns locked
›
new:
New App
Full kit generated
›
feature:
Feature
Spec → tasks
›
review:
Review
Phase gate
Any time
design:bug:change:progress
brainstorm: [your idea]
Brainstorm
Fuzzy idea → validated, buildable brief
What it does
  • Runs structured discovery — problem, user, core value, features
  • Two paths: personal (8 steps) or client project (13 steps)
  • Locks navigation structure before a single line of spec
  • Fast path if your idea is already well-formed
  • Outputs BRIEF.md
Real exchange
You
brainstorm: I want to build a habit tracker app
Agent
If this could only do ONE thing perfectly, what would it be? Not a feature — the outcome.
You
I always know at a glance whether I'm keeping my commitments this week.
Agent
Locked. Core value: instant commitment visibility.
architect: confirm
Architect
The agent's constitution — every code decision measured against this
What it locks
  • Folder structure (feature-based vs type-based)
  • State management pattern — which layer owns what
  • TypeScript strict mode, zero any
  • Component library choice
  • Testing philosophy and git commit conventions
  • Outputs ARCHITECTURE.md
Why it matters
Agent
State: I recommend React Context + custom hooks. All localStorage through src/lib/storage.ts — never directly in components. Sound good?
You
Yes.
Agent
✅ Architecture locked. 12 decisions. review: flags any drift as P0.
new: [description]
New App
Full project kit — reads brief + architecture, no repeated questions
What it generates
  • Spec with acceptance criteria and conformance checklist
  • HTML wireframe — interactive, all screens
  • PLAN.md — phases, data model, API contract
  • TASKS.md with phase gates built in from day one
  • CLAUDE.md at project root — agent reads every session
  • CODEBASE.md placeholder — populated after Phase 1
Files created
📁 vibe/
TASKS.mdYou open this
ARCHITECTURE.mdagent
SPEC.md + SPEC_INDEX.mdagent
PLAN.mdagent
CODEBASE.mdagent
DECISIONS.mdagent
CLAUDE.mdproject root
feature: [what to build]
Add Feature
Spec before code — every time, for every feature
What it does
  • Checks for existing incomplete feature with same name first
  • Reads SPEC.md — aligns new feature with existing criteria
  • Graduated UI check: full wireframe / brief note / skip
  • Effort estimates: S / M / L per task, total hours
  • Creates vibe/features/[date-slug]/
TASKS.md after feature:
🔄 Daily Check-ins (0/7)
Estimated: ~14-16 hrs (S:2, M:3, L:2)
[ ] DC-001 · Date utilities
[ ] DC-002 · DateStrip — 7-day nav
[ ] DC-003 · CheckInToggle
[ ] DC-004 · TodayPage
[ ] DC-005 · Tests
design: [component or scope]
Design
Logic first. Design after. Never mixed.
The separation
vibe agent
Logic · data flow
spec compliance · tests
vibe-design
Aesthetics · layout
feel · interactions
  • Reads DESIGN_SYSTEM.md first — detects conflicts with SPEC.md
  • 3+ components: plan approval once, then executes in full
  • If design change needs logic → stops, flags it, won't proceed
  • Updates DESIGN_SYSTEM.md after every pass
Design plan approval (3 components)
Agent
Direction: "Organic and unhurried — checking in should feel like a small daily ritual"

DESIGN-001 · CheckInToggle — sage-500, subtle scale
DESIGN-002 · DateStrip — clay-500 selected, sage dots
DESIGN-003 · TodayPage — warm white, generous spacing

Say "yes" to proceed — I'll style all 3 in order.
bug: [symptom]
Fix Bug
Regression test first. Root cause confirmed. Smallest fix.
Severity triage — first thing
Trivial
Obvious cause
1–2 lines, 1 file
No regression risk
→ 3 tasks, no folder
Significant
Root cause unclear
Multiple files
Regression risk
→ Full BUG_SPEC workflow
Always: regression test before fix
Stale check-ins on date switch (0/4)
[ ] BUG-001 · Write failing test first
[ ] BUG-002 · Fix useCheckIns
[ ] BUG-003 · Verify suite green
[ ] BUG-004 · Update docs
change: [what changed]
Change Spec
Impact shown before any file is touched — always
What it handles
  • New feature additions (now or deferred to backlog)
  • Removing or renaming features anywhere in the build
  • Reverting a previous scope change by D-ID
  • Promoting a backlog item to active feature
  • Updates all docs in correct order — SPEC, TASKS, DECISIONS, BRIEF
Impact assessment — before any file is touched
Agent
Build stage: Mid-feature
Spec: note field added to acceptance criteria
Data: check-ins storage needs nullable note field
Tasks: DC-001-R retrofit storage · DC-003-R add input
Effort: Medium — 2 retrofits

Ready to proceed?
review: phase [N]  ·  review: final
Review
Mandatory gate — no phase progresses without passing it
What it checks
  • Automated first: tests, linter, TypeScript, npm audit
  • Architecture drift vs ARCHITECTURE.md — always P0
  • SOLID principles — file paths + line numbers, no vague feedback
  • Security: hardcoded secrets, auth checks, dependencies
  • Carryover: unresolved P1 in 2+ reviews escalates to P0
  • Final gate: P0 and P1 both zero before deploy
Severity model
P0Blocks gate immediately. e.g. direct DB in component, any type, hardcoded secret
P1Logged to backlog. Must resolve before deploy.
P2Logged. Escalates to P1 if ignored across reviews.
Score: 10.0 − 1.0/P0 − 0.5/P1 − 0.2/P2. Every finding has a file path + line number.
progress
Progress
ASCII dashboard — read-only, always safe to run
Example output
┌─────────────────────────────────────────────────────────────┐ │ Habit Tracker — Build Progress │ │ 48% complete · 17 tasks done of 35 │ ├─────────────────────────────────────────────────────────────┤ │ Phase 1 ████████████████████ 7/7 complete │ │ Phase 2 ████████░░░░░░░░░░░░ 10/21 in progress │ │ Phase 3 ░░░░░░░░░░░░░░░░░░░░ 0/7 pending │ ├─────────────────────────────────────────────────────────────┤ │ Phase 1 → 2: reviewed 2026-03-18 — 0 P0, 1 P1 logged │ │ Phase 2 → 3: pending │ ├─────────────────────────────────────────────────────────────┤ │ ACTIVE Daily Check-ins │ │ [x] DC-001 · Date utilities │ │ [ ] DC-002 · DateStrip ← next │ ├─────────────────────────────────────────────────────────────┤ │ BACKLOG 1 item (dark-mode) · BUGS 0 · SCOPE CHANGES 3│ │ Last: design(check-ins): style CheckInToggle — organic │ └─────────────────────────────────────────────────────────────┘

Two audiences

One file for you.
Everything else for the agent.

Human-facing
vibe/TASKS.md
The only file you ever need to open.
Plain English. Updated after every task.
One word to keep building: next
Agent-facing — you never open these
CLAUDE.mdrules, read every session
vibe/ARCHITECTURE.mdthe constitution
vibe/SPEC.mdacceptance criteria
vibe/SPEC_INDEX.mdcompressed map
vibe/PLAN.mdphases + data model
vibe/CODEBASE.mdlive snapshot
vibe/DECISIONS.mddrift log
vibe/DESIGN_SYSTEM.mdtokens + variants
vibe/features/ · bugs/ · backlog/folders

The framework in three things

1
file to watch
vibe/TASKS.md
1
word to keep building
next
1
gate per phase
review: phase N
brainstorm:architect:new:feature:design:bug:change:review:progress

Spec before code. Context preserved. Always.

vibe-* skills framework

Thank
you.

A structured framework for building with AI coding agents.

brainstorm: architect: new: feature: design: bug: change: review: progress

Spec before code.

Context preserved.

Always.

1 / 15