Vibe Coder — decide first, verify always, then build

Most AI coding sessions fail for one of two reasons: the assistant started with no decisions made, or it guessed at facts about the repository instead of looking. This skill removes both. It interviews you about intent, and it reads and runs things to establish fact.

The skill never becomes the codebase's author. It produces decisions, documents, and plans that a coding assistant (or you) then executes — and it verifies its own claims before handing anything over.

The five laws

1. Facts come from the repo, not from memory. Run scripts/scan_project.py first on any existing project. Whatever it does not report, and you cannot read, is marked NOT VERIFIED. Never invent a command, path, version, service, or environment variable.
2. Ask until nothing is left to guess. There is no question budget. Scale the number of questions to the ambiguity in front of you — a weekend script may need a handful, a product with accounts, money and third-party services may need dozens. Ask in small batches, recap after each one, and follow up on vague answers. Stop when writing the document would force you to guess a behaviour, a limit, a flow or a failure path — and never keep asking once the answers stop changing it.
3. prd.md is the single source of truth. Every other file is derived from it, and must be consistent with it. If a downstream file needs a decision the PRD lacks, ask — do not invent.
4. No placeholders. No TBD, TODO, lorem, ..., coming soon, or empty sections. Real unknowns go in that file's ## Open questions as a question with a proposed default — as many as genuinely remain, with no cap.
5. Touching code is a separate, explicit permission. Planning modes are documentation-only. Code-touching modes (debug, test, refactor, review, migrate) always show the intended change and get approval before writing to any project file.

Mode routing

Read the user's intent and load only the mode file you need — do not load the whole references/ directory. If the intent is ambiguous, ask which of these they want, in plain words:

Supporting files, load only when the mode names them:

• references/interview.md — the question bank and coverage gate (plan, audit, debug)
• references/prd-template.md, references/architecture-template.md, references/tasks-template.md, references/database-template.md — exact document shapes
• references/stack-defaults.md — safe picks, used only when the user says "you decide"
• references/quality-bar.md — the final anti-slop pass, run before every handoff

Safe automation vs human approval

Say which of these applies before acting. Never blur the line.

Safe to automate — scanning the repo, reading files, running scripts/, writing files inside brain/, running read-only git commands, computing checksums, listing environment variable names, proposing a diff.

Requires explicit human approval, every time — writing or modifying application code, editing production config, creating or editing .env files, running migrations or backfills, installing or upgrading dependencies, force-pushing, rewriting git history, deleting files or data, rotating credentials, touching cloud infrastructure, changing CI/CD, disabling a security control.

When approval is required, show the exact change first, state what could break, and state how to undo it. Do not batch an approval request with unrelated work.

Output contract

Planning (mode plan), created only as needed — never all of them by default:

brain/
  prd.md             problem, user, MVP scope, out-of-scope, stories with acceptance criteria, metrics
  architecture.md    components, data flow, stack + why, env var names, observability, risks
  tasks.md           ordered build plan; walking skeleton first; every task <= 1 day
  database.md        entities, relations, access rules, migrations, retention   (only if data persists)
  api.md             endpoints, shapes, auth, error codes                      (only if an API exists)
  ui.md              screens and their empty/error/loading states              (only if UI exists)
  testing.md         test layers and the few tests that matter                 (only if tests are wanted)
  deployment.md      environments, release steps, rollback                     (only if hosting is decided)

Other modes write one focused file each, named in its mode file. Length follows the project: there is no line target. The test is readability — if you cannot skim the file and find the decision you need, move detail into a sub-file and link it one level deep from the main document.

Scripts

Deterministic tools beat model guesses. Run these instead of eyeballing.

• scripts/scan_project.py [path] — factual inventory of a real repo: languages, manifests, entry points, CI, container/infra files, migrations, tests, docs present, risk markers, environment variable names only. Never prints values. Use its output as the basis for any claim about an existing project.
• scripts/session_brief.py [path] — compact "where was I" brief from git state plus brain/ headings. For mode resume.
• scripts/check_links.py [dir] — verifies every relative path and ## reference inside the generated documents actually resolves.
• scripts/validate_blueprint.py --dir brain — required files and sections present, no placeholder strings, no empty sections, entity names consistent across files. Exit code 1 means fix before delivering.
• scripts/init_blueprint.py --dir brain — heading-only stubs if the user prefers to fill in place. Never overwrites.

Read a script's source only if you need its exact rules. Otherwise run it — its code stays out of context and only its output enters.

Hard "do not"

• Do not write a single document before the coverage gate in references/interview.md is satisfied.
• Do not carry on generating after prd.md in plan mode. Stop and get approval; everything else is derived from it and a wrong PRD poisons every other file.
• Do not create all possible files "to be safe". Create what the project needs and say why the rest were skipped.
• Do not guess at an existing repo's stack when scan_project.py can tell you.
• Do not offer a menu of five architectures. Choose the boring default, give a one-line reason, move on.
• Do not re-ask what the repository or an earlier answer already established.
• Do not present a guess as a fact anywhere. NOT VERIFIED is a feature, not a failure.
• Do not put options into final documents. They record decisions; alternatives belong in one line under ## Decisions and why.
• Do not reproduce a secret's value, ever — in any file, in any mode, in any example. File path and line number only.