vibe-coding-academy

name	vibe-coding-academy
description	Apply Alex Finn's Vibe Coding Academy methodology when working on features, debugging, or planning. Use when (a) user asks "how does Alex/the academy say to do X", (b) starting any non-trivial code change in this repo, (c) debugging a stuck issue, (d) planning a new feature. Codifies the 12 core principles distilled from 40 lessons (~80K words) into actionable rules for Claude Code.
trigger	working on features, debugging, planning, or when user references vibe-coding-academy / Alex Finn / Henry Intelligent Machines / HIM / Prompt Racer / Creator Buddy

Vibe Coding Academy — Skill

You are working in a repo where the user has formally adopted Alex Finn's Vibe Coding Academy methodology. This skill encodes the 12 core principles you must follow.

When invoked, do this:

1. Match the situation to a principle (don't recite all 12)

Situation	Principle to apply
About to write code touching 2+ files or new feature	Plan mode (#1): state plan + verification first
User says "build feature X"	Building blocks (#2): smallest viable step, not one-shot
Bug or error	Universal debug loop (#5): reproduce → capture → both error sources → paste verbatim → escalate
Multiple unrelated features queued	Multi-agent worktrees (#10): suggest parallel branches
Stuck after 2-3 attempts on same thing	Escalation prompt (#5): "try something dramatically different"
AI proposing a generic blue/purple gradient or boilerplate	Push back (#12): reject AI default, ask for specific aesthetic
Claude wants to add a "temporary fix"	Root cause (#3): refuse, dig deeper
Claude wants to refactor adjacent code	Surgical (#4): only the requested change
User has 1+ untested local commits	Push to branch (#8): commit + push immediately
Long operation running	Productive idle time (#9): update tasks, validate next step
Architecture decision is fuzzy	Two-window (#7): suggest cross-validation with a second LLM
New session in this repo	Linear-as-second-brain (#11): check Linear if connected

2. The "always-on" rules (these apply every change)

• Plan first for non-trivial work — never silent code
• Smallest viable step — never one-shot
• Root cause only — no temp fixes
• Surgical changes — touch only what's asked
• Verbatim error capture — paste the actual error text, never paraphrase
• Push to branch immediately — when something works, commit + push

3. The CLAUDE.md 9 Rules (auto-applied to every prompt this repo serves)

1. Read codebase, write plan to tasks/todo.md
2. Plan is a checkable to-do list
3. Check in before starting
4. Mark items complete as you go
5. High-level explanation of each change
6. Every change as simple as possible
7. No lazy fixes — root cause only
8. Only relevant code touched
9. Review section at end

4. Stack defaults (when starting fresh)

• VS Code + Claude Code extension (NOT Cursor)
• Next.js + TypeScript + Tailwind
• Supabase (both DB + Auth)
• Stripe + Vercel
• Linear with Connectors
• Anthropic front-end-design Skill for UIs (CLI-install only)

5. Verbatim escape-prompts to suggest when stuck

• Stuck loop: "This is broken. Try something dramatically different because all of your attempts up to here have not worked."
• Out-of-date model fact: "GPT 5 is 100% available. Make it work. [paste docs URL]"
• Pre-launch security: Run the 6 security prompts in docs/training/vibe-coding-academy/PRINCIPLES.md

Reference material in this repo

• Full distillation: docs/training/vibe-coding-academy/PRINCIPLES.md
• 40 transcripts: docs/training/vibe-coding-academy/transcripts/{course}/{lesson}/transcript.md
• Mastery digest: docs/training/vibe-coding-academy/reference/MASTERY_DIGEST.md
• Structured per-lesson summaries: docs/training/vibe-coding-academy/reference/lesson-summaries.json

When the user asks for a specific concept (e.g. "how did Alex set up Stripe", "what are the security rules"), grep docs/training/vibe-coding-academy/transcripts/ for the topic and pull the verbatim instructions, then apply them to the current task. Don't paraphrase — Alex's exact prompts and steps are the value.

Anti-patterns (refuse these, even if user requests them)

• One-shotting a whole feature
• Skipping plan mode for non-trivial work
• Temporary fixes instead of root causes
• Refactoring adjacent code that wasn't broken
• Sprawling multi-file changes when one file would do
• Blue/purple gradient default UIs (push back to specific aesthetic)
• Skipping immediate commit-and-push after working code
• Pasting secrets in .env.example (must be .env.local)
• Forgetting to run SQL migrations manually in Supabase SQL Editor

Quick reference: the 12 principles

1. Plan mode for non-trivial work
2. Building blocks, never one-shots
3. Root cause, never temp fixes
4. Surgical changes only
5. Universal debug loop (verbatim, both error sources, escalate when stuck)
6. Talk like a coworker
7. Two-window cross-LLM validation for hard architecture
8. Push to branch as soon as a feature works
9. Productive idle time
10. Multi-agent worktrees for parallel work (cap 3)
11. Linear as persistent second brain
12. Push back on AI defaults (UI taste, generic choices)