vibe-init · diff
git:20261030.a66992c to git:20261030.c951717
410 added, 146 removed. Audit B to B.
---
name: vibe-init
description: >
Onboards an existing or legacy codebase into the vibe-* skills framework.
Reads actual source files, infers architecture and patterns, generates the full vibe/ folder
so vibe-add-feature, vibe-fix-bug, vibe-review, and all vibe-* skills work immediately.
Triggers on "vibe-init", "onboard this project", "init the vibe folder",
"set up vibe for this project", "this is a legacy project", "retrofit this codebase",
"I want to use vibe skills on an existing project", "add vibe to this repo",
"the vibe folder doesn't exist", "can we use vibe skills here".
Always use when the user has an existing codebase with no vibe/ folder and wants
to use any vibe-* skill — even without the exact trigger phrases.
- Single agent session — reads everything, generates everything, no staged checkpoints.
- Produces CLAUDE.md and full vibe/ folder grounded in actual code.
- SPEC.md marked PROVISIONAL — verify before first vibe-review run.
+ Single session: reads the code, writes the documents, then an independent spec review
+ in which a person verifies the PROVISIONAL SPEC.md. Produces CLAUDE.md and the full
+ vibe/ folder, with a PLAN.md feature map of the existing features.
DECISIONS.md starts from today — all prior decisions untracked by design.
---
# Vibe Init Skill
Reverse-engineers the vibe-* framework scaffold from an existing codebase.
Reads actual source files. Infers everything from code. Documents only what is observed.
Produces a complete vibe/ folder that immediately unblocks all vibe-* skills.
> **Autonomous / headless mode.** At startup resolve the settings with
> `python3 ~/.claude/skills/vibe-mode/scripts/vibe_state.py mode` (`mode --run` when the
> caller says this skill was entered from `vibe-mode: run`). If `vibe_mode` is
> `autonomous`, every "wait", "ask", "confirm" and approval step in this skill follows
> vibe-mode's `references/HEADLESS.md` §2 instead: take the recommended option, accept a draft
> only as §2.2 allows (after its independent goldfish review where one runs), log each choice to `vibe/DECISIONS.md`, never ask the
> user, and stop — writing `vibe/.run_state.json` — only when a person is genuinely required.
**Run in agent mode (Claude Code / Cursor). Requires filesystem access.**
- **Single session — reads everything, generates everything, no staged checkpoints.**
+ **No application code. The only files this skill writes are:** `CLAUDE.md` and, under
+ `vibe/`, ARCHITECTURE.md, CODEBASE.md, SPEC.md, IMPLEMENTATION_LOG.md, SPEC_INDEX.md,
+ PLAN.md, TASKS.md, DECISIONS.md, `reviews/backlog.md` and the empty `features/`, `bugs/`,
+ `backlog/` folders (plus what the spec review and vibe-graph write: `vibe/goldfish/spec/`,
+ `vibe/spec-reviews/`, `vibe/.gates.json`, `vibe/graph/`).
+ **The order:** read the code (Stages 1 to 4) → write the four documents a person decides
+ on (Stage 5) → independent spec review, with the person's verification of the SPEC
+ inside it (Stage 6) → generate the files derived from the reviewed text (Stage 7) →
+ approval and the spec gate (Stage 8) → dependency graph (Stage 9) → report (Stage 10).
+
---
## The contract this skill establishes
**Code is the source of truth.** Nothing is invented. If it's in ARCHITECTURE.md,
it was observed in the codebase. If it's in CODEBASE.md, the file exists.
+ The one rule not taken from the code is "Never commit secrets", which every project
+ carries in its Never tier and which is labelled as a vibe rule (5A).
**The past is untracked. The future is fully tracked.**
DECISIONS.md starts with one bootstrap entry dated today (added after any entries already there, never replacing them).
Every decision made through vibe-* skills from this point forward gets logged.
Prior decisions are acknowledged as unknown — not fabricated.
**SPEC.md is provisional.**
It describes observed behaviour, not planned requirements.
- It is marked clearly. vibe-review will flag it until a human verifies it.
+ It is marked clearly, and it stays marked until a person verifies it. That verification
+ happens inside the spec review (Stage 6): the person's corrections are the answer to the
+ review's PROVISIONAL finding, and only then is the banner removed.
This is honest — encoding bugs as requirements is worse than flagging uncertainty.
---
## Pre-flight — confirm project root
Before reading anything:
```bash
pwd
ls -la
```
Confirm you are at the project root (the directory containing the source code).
If not, stop and ask the user to navigate there first.
Check if vibe/ already exists:
```bash
ls -d vibe/ 2>/dev/null && echo "EXISTS" || echo "NOT FOUND"
```
- If vibe/ already exists:
+ **Resuming an unfinished onboarding.** Check this first, before the question below and
+ before anything is archived. An earlier vibe-init run stopped in Stage 6 (usually waiting
+ for a person to verify the SPEC) when `vibe/CODEBASE.md` carries the vibe-init header
+ (`📥 Generated by vibe-init`) and either:
+ - `vibe/goldfish/spec/` exists and `vibe/TASKS.md` does not (a first onboarding that never
+ got past Stage 6), or
+ - `python3 ~/.claude/skills/vibe-mode/scripts/vibe_state.py run-state show` says
+ needs_human with a reason Stage 6 writes: "a person must verify the SPEC derived from
+ code", "goldfish spec: ..." or "spec review could not run: ...". This is the case for a
+ re-run over an existing vibe/, which still has the earlier run's TASKS.md until Stage 7.
+
+ This is not a re-run: don't ask the question below, don't archive, don't regenerate
+ anything. Say so in one line and go straight to Stage 6. vibe-goldfish picks the review up
+ from its ledger, with the person's answers in it.
+
+ If vibe/ already exists (and this is not a resume):
> "A vibe/ folder already exists in this project. Running vibe-init will regenerate its
> files from the current codebase state. vibe/DECISIONS.md is kept and the onboarding entry
- > is appended to it (5E). Nothing in vibe/ is deleted. Continue?"
+ > is appended to it (8B). Nothing in vibe/ is deleted. Regenerate from the code?"
+ In manual mode, when `vibe/CODEBASE.md` carries the vibe-init header and
+ `vibe/goldfish/spec/` exists, offer three answers instead: **(a)** regenerate from the code
+ (a fresh onboarding; the old review is archived), **(b)** resume the unfinished spec review
+ (go straight to Stage 6, nothing archived or regenerated), **(c)** stop. Autonomous mode
+ takes "regenerate": a Stage 6 stop it could resume was already caught above.
Wait for explicit confirmation before proceeding. Confirmation means regenerate file by file
as the steps below say. It never means clearing or deleting vibe/ first, and DECISIONS.md is
- always handled by the append-only rule in 5E.
+ always handled by the append-only rule in 8B.
+ **After confirming a regeneration, before anything is rewritten,** set the old review and sign-off aside.
+ Only an explicit regeneration does this, never a resume.
+ The documents are about to be written again from the code, so findings settled on the old
+ text must not settle the new one, and an old approval must not cover a spec nobody has
+ reviewed:
+ ```bash
+ python3 ~/.claude/skills/vibe-goldfish/scripts/goldfish.py archive spec
+ python3 ~/.claude/skills/vibe-mode/scripts/vibe_state.py gate set spec --status pending
+ ```
+ (`archive` says "nothing to archive" when there was no earlier review. That is fine.)
+
---
## Large codebase protocol
Run this immediately after the pre-flight check — before any file reading.
```bash
find . -type f \
! -path '*/node_modules/*' ! -path '*/.git/*' \
! -path '*/dist/*' ! -path '*/build/*' \
! -path '*/__pycache__/*' ! -path '*/.next/*' \
! -path '*/coverage/*' ! -path '*/vendor/*' \
| wc -l
```
**Classify by file count and set reading budget:**
| Size | Files | Stage 2 anchor reads | Stage 3 sample per folder |
|------|-------|---------------------|--------------------------|
| Small | < 50 | All anchor files | 3 files |
| Medium | 50–200 | All anchor files | 2 files |
| Large | 200–500 | Anchor files — max 25 total | 1 file |
| XL | 500+ | Anchor files — max 15 total | 1 file (critical folders only) |
**For Large (200–500 files):**
- Cap Stage 2 at 25 total file reads across all categories
- Prioritise: package manifest → entry points → schema files → 2 route files → 2 service files
- Stage 3: sample 1 file per folder type, skip folders with < 3 files
- Add to all generated docs: `⚠️ Large codebase — sampled [N]/[total] files`
**For XL (500+ files):**
- Cap Stage 2 at 15 total file reads
- Prioritise: package manifest → entry point → schema file → 1 route file only
- Stage 3: skip — infer patterns from Stage 2 anchor files only
- Add to all generated docs: `⚠️ XL codebase — [N] files. CODEBASE.md covers critical paths only.`
- Tell the user: "This is a large codebase ([N] files). I'll document the critical paths.
Run `document:` on specific modules to fill gaps progressively."
Store the size classification. Apply the budget throughout Stages 2 and 3.
---
## Stage 1 — Topology scan
**Goal:** Understand the full shape of the project without reading file contents.
Fast. Covers everything.
```bash
find . -type f \
! -path '*/node_modules/*' \
! -path '*/.git/*' \
! -path '*/dist/*' \
! -path '*/build/*' \
! -path '*/__pycache__/*' \
! -path '*/.next/*' \
! -path '*/coverage/*' \
! -path '*/vendor/*' \
| sort
```
Also run:
```bash
find . -maxdepth 3 -type d \
! -path '*/node_modules/*' \
! -path '*/.git/*' \
! -path '*/dist/*' \
! -path '*/build/*' \
| sort
```
From the topology, extract:
**Tech stack indicators** (file extensions, config filenames):
- `package.json` → Node.js ecosystem
- `requirements.txt` / `pyproject.toml` / `Pipfile` → Python
- `go.mod` → Go
- `pubspec.yaml` → Flutter/Dart
- `Gemfile` → Ruby
- `pom.xml` / `build.gradle` → Java/Kotlin
- `composer.json` → PHP
**Framework indicators** (folder names, config files):
- `pages/` or `app/` + `next.config.*` → Next.js
- `src/routes/` + `svelte.config.*` → SvelteKit
- `resources/views/` → Laravel
- `app/controllers/` → Rails
- `manage.py` → Django
- `main.py` + `routers/` → FastAPI
**Structural pattern** (from folder names):
- `components/` + `pages/` + `hooks/` → feature-type frontend
- `controllers/` + `services/` + `models/` → MVC backend
- `features/` or `modules/` with sub-folders → feature-based
- flat `src/` → unstructured (note this explicitly)
**Database indicators:**
- `prisma/schema.prisma` → Prisma ORM
- `migrations/` or `alembic/` → SQL migrations present
- `models/` with ORM patterns → ORM-based
- `*.sql` files → raw SQL
Log your topology findings internally. Do not generate any output files yet.
---
## Stage 2 — Anchor file deep read
**Goal:** Read the highest-signal files in full to confirm stack, entry points, and core patterns.
Read every file in this list that exists. Do not skip any that are present.
**Package / dependency manifests (read in full):**
- `package.json`
- `package-lock.json` or `yarn.lock` (dependencies only — skip lockfile hashes)
- `requirements.txt` / `pyproject.toml` / `Pipfile`
- `go.mod`
- `pubspec.yaml`
- `Gemfile`
- `composer.json`
**Configuration files (read in full):**
- `.env.example` or `.env.sample` (NEVER `.env` — never read secrets)
- `docker-compose.yml` / `docker-compose.yaml`
- `Dockerfile`
- `.eslintrc*` / `eslint.config.*`
- `tsconfig.json`
- `vite.config.*` / `next.config.*` / `nuxt.config.*` / `svelte.config.*`
- `tailwind.config.*`
- `jest.config.*` / `vitest.config.*` / `pytest.ini` / `pyproject.toml` (test section)
+ **Boundary evidence (read in full; small files):** the source of the Always / Ask First /
+ Never tiers in 5A. Always read `.gitignore`; the rest count toward the reading budget.
+ - `.gitignore` (what the project already keeps out of git)
+ - `.prettierrc*` / `.editorconfig` / `ruff.toml` / `.flake8` (formatting and lint rules)
+ - CI: `.github/workflows/*.yml` / `.gitlab-ci.yml` / `.circleci/config.yml` (what every change must pass)
+ - Hooks: `.husky/*` / `.pre-commit-config.yaml` / `lefthook.yml` (what runs before a commit or push)
+ - `CONTRIBUTING.md` / `CODEOWNERS` / `.github/CODEOWNERS` / `.github/pull_request_template.md` (who must approve what)
+
**Entry points (read in full):**
- `src/index.*` / `index.*` (root level)
- `src/main.*` / `main.*`
- `src/app.*` / `app.*`
- `src/server.*` / `server.*`
- `src/App.*` (React/Vue root component)
**Route / controller files (read in full — max 5 files):**
- Any file in `routes/`, `controllers/`, `api/`, `pages/api/`, `routers/`
- Prefer the file with the most routes (largest)
**Schema / model files (read in full — max 5 files):**
- `prisma/schema.prisma`
- Any file in `models/`, `schemas/`, `types/`, `db/`
- `src/types/index.*`
**README (read in full if present):**
- `README.md` / `README.rst`
Note: README may be outdated. Cross-check against actual code. Flag discrepancies.
**Security rule — never read:**
- `.env`
- Any file named `secrets.*`, `credentials.*`, `*.key`, `*.pem`, `*.p12`
- Any file in `certs/` or `keys/`
---
## Stage 3 — Pattern sampling
**Goal:** Confirm patterns by reading representative files from each major folder.
For each distinct folder type identified in Stage 1, read 2–3 files in full.
Choose the largest or most centrally-named files — they tend to show the most patterns.
Standard sampling targets:
| Folder type | Files to read | What to extract |
|-------------|--------------|----------------|
| `components/` | 2 representative components | Props patterns, styling approach, composition style |
| `hooks/` or `composables/` | 2 custom hooks | State management patterns, side effect handling |
| `services/` | 2 service files | API call patterns, error handling, data transformation |
| `utils/` or `lib/` | 2 utility files | Helper patterns, shared logic |
| `middleware/` | All (usually small) | Auth patterns, request handling |
| `tests/` or `__tests__/` | 2 test files | Testing patterns, coverage approach |
| `migrations/` | Most recent migration | Schema evolution approach |
**Sampling budget — apply the size classification from large codebase protocol:**
- Small: 3 files per folder type
- Medium: 2 files per folder type
- Large: 1 file per folder type
- XL: skip Stage 3 — patterns inferred from Stage 2 anchor files only
**What to extract from each sampled file:**
- Naming conventions (files, functions, variables, components)
- Import patterns (absolute vs relative, barrel exports)
- Error handling approach
- TypeScript usage (strict, any usage, custom types)
- Code organisation within files
- Comments and documentation style
---
## Stage 4 — Synthesise findings
Before writing any files, internally consolidate everything from Stages 1–3:
**Confirmed stack:**
`[runtime] + [framework] + [database] + [key libraries]`
**Structural pattern:**
`[feature-based / MVC / type-based / flat / mixed]`
**Naming conventions observed:**
- Files: `[camelCase / kebab-case / PascalCase / snake_case]`
- Functions: `[camelCase / snake_case]`
- Components: `[PascalCase]`
- Variables: `[camelCase / snake_case]`
**State management:** `[local state only / Context / Zustand / Redux / Pinia / none observed]`
**Testing:** `[Jest / Vitest / pytest / none observed]` — coverage: `[present / absent]`
**Code quality tooling:** `[ESLint / Prettier / Ruff / Flake8 / none observed]`
**Key integration points observed:**
`[external APIs, auth provider, payment system, storage, etc.]`
+ **Boundary evidence:** for each tier, the rules the code enforces or documents, each
+ with the file that shows it:
+ - Always: what CI, hooks or the lint/format config require of every change.
+ - Ask First: what CONTRIBUTING.md, CODEOWNERS or the PR template says needs someone's approval.
+ - Never: what `.gitignore` keeps out of git, and lint rules set to `error`.
+ A tier with nothing behind it stays empty here. It is not filled with a likely-sounding rule.
+
**Honest gaps — things not observed:**
List anything the code doesn't make clear. These become flagged unknowns in the docs.
---
- ## Stage 5 — Generate vibe/ folder
+ ## Stage 5 — Write the documents the review checks
- Now write all files. Write them in this exact order — each file informs the next.
+ Write these in this order. Each file informs the next. ARCHITECTURE.md, CODEBASE.md,
+ SPEC.md and CLAUDE.md are the four documents the spec review reads (goldfish preset
+ `init`). Nothing derived from them is written yet: SPEC_INDEX.md, PLAN.md, TASKS.md and
+ the onboarding entry in DECISIONS.md come from the reviewed text in Stages 7 and 8, so a
+ review fix never has to chase a copy.
### 5A — vibe/ARCHITECTURE.md
Read `references/ARCHITECTURE_RETROFIT.md` for the full template.
Fill from Stage 4 synthesis. Every section must be grounded in observed evidence.
For each architectural decision, note: `[Observed in: filename or pattern]`
Key sections to populate:
- Architecture overview (ASCII diagram of actual layers)
- Folder structure (exact observed structure with rules inferred from patterns)
- Naming conventions (from Stage 3 sampling — specific, not generic)
- State management (observed approach + rules)
- Error handling (observed patterns)
- Testing philosophy (what exists, what coverage looks like)
- Code quality (observed tooling + inferred rules)
+ - Boundaries: Always / Ask First / Never (from the Stage 4 boundary evidence only)
- Tech stack (confirmed from Stage 2)
+ **Boundaries come from the code, not from a checklist.**
+ - Each rule cites the file that shows it: `[Observed in: .husky/pre-commit]`.
+ - The Never tier always carries `Never commit secrets (.env files, keys, credentials)`,
+ labelled `[vibe rule: every project]`. It is the one rule not observed in the code. If
+ `.gitignore` already keeps `.env` out, cite that too.
+ - A tier with no evidence says so plainly, as its only line:
+ `- None found in the code: confirm with the team.`
+ Never fill a tier with a generic rule so it looks complete. The team adds real rules
+ later, and an empty tier tells the next agent to ask instead of assume.
+
Mark the file header:
```
> 📥 Generated by vibe-init on [date] from codebase analysis.
> Reflects patterns observed in the actual code — not planned decisions.
> Update this file as new patterns are deliberately introduced.
```
### 5B — vibe/CODEBASE.md
Read `references/CODEBASE_RETROFIT.md` for the full template.
This is the most important file for unblocking vibe-add-feature and vibe-fix-bug.
Be thorough. Every key file should be in here.
Sections to populate:
1. **Tech stack** — confirmed from Stage 2
2. **Commands** — dev, build, test, lint (from package.json scripts or Makefile)
3. **Folder map** — every significant folder with one-line purpose
4. **Key files** — every file that other files depend on (entry points, shared utils, config)
5. **Routes / endpoints** — every route observed in Stage 2 + 3
6. **Data model** — every schema/model observed in Stage 2
7. **Key components** — significant UI components with props and purpose
8. **Services / modules** — external integrations, business logic modules
9. **Integration points** — external APIs, auth, payments, storage
10. **Patterns** — the specific patterns confirmed in Stage 3 (with file examples)
Mark each section that was partially sampled:
`> ⚠️ Partially sampled — [N] files read from [folder]. Update as more files are touched.`
### 5C — vibe/SPEC.md
Read `references/SPEC_RETROFIT.md` for the full template.
Add this banner at the very top — it must be visible:
```
> ⚠️ PROVISIONAL SPEC — generated by vibe-init from observed code behaviour.
> This describes what the code DOES, not necessarily what it was INTENDED to do.
> Verify this spec before using vibe-review — incorrect specs will pass broken code.
> Last verified: [unverified — pending human review]
```
+ The banner stays until a person has verified the spec in Stage 6. This skill never
+ removes it on its own judgment, and never in autonomous mode.
+
Sections to populate from code observation:
1. **Overview** — inferred purpose of the application (2-3 sentences from README + entry points)
2. **Observed features** — what the code demonstrably does (routes, UI flows, data operations)
3. **Data model** — entities and relationships as observed in schema files
4. **Tech stack** — confirmed
5. **Integrations** — external services observed
6. **Out of scope** — explicitly unknown (not inferred — mark as "not determined during init")
7. **Conformance checklist** — leave empty, to be filled by the team
Every feature listed must have a note: `[Inferred from: file/route/component name]`
- ### 5D — vibe/SPEC_INDEX.md
-
- Generate compressed map of SPEC.md. Follow same format as vibe-new-app.
- Add provisional banner at top.
-
- ### 5E — vibe/DECISIONS.md
+ ### 5D — CLAUDE.md (project root)
- DECISIONS.md is append-only. Never write it from this template when it already exists
- (an earlier spec-review, or this run's own autonomous logging, may have created it):
- - **Absent:** create it with the template below.
- - **Exists:** keep every existing entry exactly as it is, including entries other skills
- wrote in other formats (for example `## [date] — Spec review`). If the header (the title
- through the `## Format` block) is missing, add it above the existing entries. Add the
- onboarding entry below them, numbered from the highest existing `D-NNN` ID (so it is
- `D-001` only when no entry exists yet).
+ Read `references/CLAUDE_RETROFIT.md` for the full template.
- ```markdown
- # DECISIONS — [Project Name]
- > Append-only. Every drift, scope change, tech choice — logged with full context.
- > Onboarded via vibe-init on [date]. All decisions prior to this date are untracked.
+ Generate CLAUDE.md at **project root**. It is written here, before the review, because
+ the `init` preset reviews it: it carries the commands and boundaries every later session
+ follows.
- ## Decision types
- - drift — deviated from ARCHITECTURE.md
- - blocker-resolution — impossible; workaround found
- - tech-choice — chose between valid approaches
- - scope-change — added/removed via change: command
- - discovery — unexpected finding affecting future tasks
+ Key differences from greenfield CLAUDE.md:
+ - Session startup reads `vibe/CODEBASE.md` first (existing code, not scaffolded)
+ - Phase gates section replaced with: "No phase structure — this is an existing project. Use vibe-review on demand."
+ - Active feature section still present — used by add-feature and fix-bug normally
+ - Note at top: "Onboarded via vibe-init on [date]"
+ - Boundaries: the three tiers copied word for word from vibe/ARCHITECTURE.md (5A),
+ empty tiers and their "None found in the code" line included
- ## Format
- ### D-[ID] — [Short title]
- - **Date**: · **Task**: [TASK-ID] · **Type**: [type]
- - **What was planned**: · **What was done**: · **Why**:
- - **Alternatives considered**: · **Impact on other tasks**:
- - **Approved by**: human | agent-autonomous
+ Commands section must be populated from actual observed scripts:
+ ```bash
+ # From package.json scripts / Makefile / observed patterns
+ dev: [actual dev command]
+ build: [actual build command]
+ test: [actual test command]
+ lint: [actual lint command]
+ ```
- ---
+ If a command wasn't observed, write: `# Not observed during init — confirm with team`
- ### D-001 — Project onboarded via vibe-init
- - **Date**: [today] · **Task**: vibe-init · **Type**: discovery
- - **What was planned**: N/A — legacy project, no prior vibe context
- - **What was done**: Generated vibe/ scaffold from codebase analysis.
- Stack: [confirmed stack]. Pattern: [confirmed pattern].
- Files read: [N] files across [N] directories.
- - **Why**: Retrofitting vibe-* skills framework onto existing codebase.
- - **Alternatives considered**: Manual documentation (rejected — too slow and error-prone)
- - **Impact on other tasks**: All vibe-* skills now operational.
- SPEC.md is provisional — verify before first vibe-review run.
- - **Approved by**: human (triggered vibe-init)
- ```
+ If a CLAUDE.md already exists with `VIBE_MODE`, `APPROVALS` or `PHASES` lines, keep their
+ values in the new file. Regenerating the documents must not change how the run is set.
- ### 5E-bis — vibe/IMPLEMENTATION_LOG.md
+ ### 5E — vibe/IMPLEMENTATION_LOG.md
Create `vibe/IMPLEMENTATION_LOG.md` from the canonical template in
`../vibe-new-app/references/IMPLEMENTATION_LOG_MD.md` (the **FILE TEMPLATE** block, verbatim).
It is the append-only **implementation-decision** log (code-altitude "why this approach,
why this library") — the companion to DECISIONS.md's spec/scope log. On a retrofit it starts
empty (prior implementation decisions are untracked by design, like DECISIONS.md); the build
skills append to it going forward, and `Touches:` lines link entries to vibe-graph nodes.
+ If it already exists, keep it as it is.
- ### 5F — vibe/TASKS.md
+ ### 5F — Create remaining folders
+ ```bash
+ mkdir -p vibe/reviews
+ mkdir -p vibe/features
+ mkdir -p vibe/bugs
+ mkdir -p vibe/backlog
+ ```
+
+ Create `vibe/reviews/backlog.md` (if it doesn't exist):
+ ```markdown
+ # Review backlog
+ > Started on [date] via vibe-init.
+ > Run `review:` to populate this file with the first quality baseline.
+ ## Outstanding P1 issues
+ (none yet — run review: to establish baseline)
+ ## Outstanding P2 issues
+ (none yet)
+ ## Resolved issues
+ (none yet)
+ ```
+
+ ---
+
+ ## Stage 6 — Spec review, with the person's verification inside it
+
+ `vibe-spec-review` documents "Trigger 3 — after vibe-new-app or vibe-init", and a
+ retrofit is exactly where it matters most: the SPEC.md was inferred from code and is
+ marked PROVISIONAL. The review runs before anything is derived from the documents and
+ before the report: the gate runs first, not after you've told the user the job is done.
+
+ > "Documents written from the codebase. Running an independent spec review. The SPEC.md
+ > is PROVISIONAL, so part of this review is you checking it against what the app is
+ > meant to do..."
+
+ Invoke `vibe-spec-review` (say so if this skill was entered from `vibe-mode: run`):
+ - Trigger 3, source `vibe-init`
+ - Goldfish preset `init`, target `spec`
+ - Documents: `vibe/SPEC.md`, `vibe/ARCHITECTURE.md`, `vibe/CODEBASE.md` and `CLAUDE.md`.
+ There is no BRIEF.md in scope: on a retrofit the code is the source, and the codebase
+ reviewer checks the documents against it.
+
+ Answer every finding the way vibe-goldfish's RESOLVE.md says. Never fix findings outside
+ vibe-goldfish.
+
+ ### The PROVISIONAL finding: a person verifies the spec
+
+ The rubric reviewer raises the PROVISIONAL banner as a P1 (CHECKLISTS §3E). The finding is
+ right, and only a person can answer it: the code shows what the app does, not what it was
+ meant to do. Answer it with **escalate**:
+ ```bash
+ python3 ~/.claude/skills/vibe-goldfish/scripts/goldfish.py resolve spec <id> --as escalate \
+ --note "a person must verify the SPEC derived from code"
+ ```
+ Don't contest it, don't mark it fixed yourself, and don't remove the banner.
+
+ **Manual mode.** At vibe-goldfish's Step 6 summary the finding is under "Needs your
+ decision". Ask the person to verify the spec there: list each observed feature with its
+ inferred acceptance criteria, point out anything that looks like a bug written down as a
+ requirement, and ask them to confirm, correct or remove each one. Their corrections are
+ the answer to the finding:
+ 1. `goldfish.py decide spec <id> --as fix --by human`
+ 2. Make exactly the person's corrections in SPEC.md. Where the same fact is in
+ ARCHITECTURE.md, CODEBASE.md or CLAUDE.md, correct it there too in the same fix.
+ 3. Remove the PROVISIONAL banner, set `Last verified: [date] by [person]`, and add a
+ Changelog row ("Verified by [person] in the spec review").
+ 4. `goldfish.py applied spec <id>`
+
+ The next rounds review the verified text, so the review can converge. If the person can't
+ verify now, record `decide spec <id> --as accept-risk --by human` instead: the banner stays,
+ the verdict is ⚠️ SPEC READY WITH ACCEPTED RISKS, and the spec stays provisional for
+ vibe-review.
+
+ **Autonomous mode.** Nobody is there to verify, so the review stops for a person: an agent
+ can't settle an escalated P1 (vibe-goldfish Step 6). This stop is expected for a retrofit.
+ It is not a failure. Never decide the finding yourself (no `decide ... --by agent-autonomous`,
+ not even `--as fix`) and never remove the banner. When
+ spec-review returns, rewrite the run state so the reason is plain:
+ ```bash
+ python3 ~/.claude/skills/vibe-mode/scripts/vibe_state.py run-state set --status needs_human \
+ --reason "a person must verify the SPEC derived from code" \
+ --next "verify vibe/SPEC.md (correct it, remove the PROVISIONAL banner, set Last verified), record the answer with the command in vibe/goldfish/spec/resolution.md, then run vibe-init again: it resumes at Stage 6"
+ ```
+ If other findings are also waiting for a person, name them in `--reason` too. On the
+ resumed run, a finding the person decided as fix whose banner is already gone means
+ their edits are in: run `applied` and continue the review. If the banner is still
+ there, stop again with the same reason.
+
+ If no round raised the PROVISIONAL finding and the banner is still on SPEC.md when the
+ review converges, the person verifies at approval (Stage 8). Their edits change SPEC.md,
+ so the review re-opens by itself and runs again before the gate is recorded. In
+ autonomous mode, stop instead, with the same run state as above: an agent never signs
+ off a spec nobody has verified.
+
+ **⚠️ SPEC NOT REVIEWED** (no subagent tool and the person chose to continue, spec-review
+ Step 1): the person still verifies SPEC.md before Stage 7, the same way, and the banner
+ comes off only then.
+
+ ### Caller guard
+
+ **If spec-review stopped the run** (`python3 ~/.claude/skills/vibe-mode/scripts/vibe_state.py run-state show`
+ says needs_human from spec review), **stop here too**: end the session, don't continue,
+ don't report the step as done. That means: no Stage 7, no spec gate, no onboarding entry,
+ no graph, no report. Running vibe-init again resumes at Stage 6 (Pre-flight). In manual
+ mode, a 🔴 verdict means follow spec-review Step 3 (more rounds, rework, or the person
+ accepts).
+
+ Otherwise continue to Stage 7. If the run state still holds a Stage 6 stop from an
+ earlier run (one of the reasons listed under Pre-flight), replace it now, so a later
+ vibe-init doesn't take a finished onboarding for an unfinished one:
+ `python3 ~/.claude/skills/vibe-mode/scripts/vibe_state.py run-state set --status running --reason "vibe-init: spec review finished"`
+
+ ---
+
+ ## Stage 7 — Generate the derived files from the reviewed text
+
+ Run only after Stage 6 ended without stopping. Read the four documents **as they are now**,
+ with every review fix and the person's corrections, not the Stage 4 notes. If a reviewed
+ document changes again later (Stage 8), regenerate everything in this stage.
+
+ ### 7A — vibe/SPEC_INDEX.md
+
+ Generate a compressed map of the reviewed SPEC.md. Follow the same format as vibe-new-app.
+ If SPEC.md still carries the PROVISIONAL banner (the person accepted it as provisional),
+ put the same banner at the top of SPEC_INDEX.md.
+
+ ### 7B — vibe/PLAN.md (feature map)
+
+ Read `references/PLAN_RETROFIT.md` for the template. PLAN.md here is a feature map, not
+ a greenfield plan: no phases and no scaffolding tasks. Section 6 lists every feature in the
+ reviewed SPEC.md "Observed features" under the same name, marked ✅ built before
+ onboarding, so `feature:` (vibe-add-feature) has a map to check dependencies against and
+ to add new features to.
+
+ If `vibe/PLAN.md` already exists and was not written by vibe-init (no `📥 Generated by
+ vibe-init` header), leave it as it is and say so in the report: it is another skill's
+ plan, and it changes only through `change:`.
+
+ If `vibe/PLAN.md` already carries the vibe-init header (a re-run), rebuild only
+ "### Existing features" from the reviewed SPEC.md. Keep "### Planned features" and every
+ entry in it exactly as it is: `feature:` added those after onboarding, and some may still
+ be in progress. A feature that already has an entry under Planned features is not listed
+ again under Existing features.
+
+ ### 7C — vibe/TASKS.md
+
Generate a minimal but honest TASKS.md:
```markdown
# TASKS — [Project Name]
> Onboarded via vibe-init on [date].
> This project was not built using the vibe-* framework.
> TASKS.md starts here. All future work tracked from this point forward.
## What we're working with
- [2-3 sentences describing the project as inferred — stack, purpose, approximate scale]
+ [2-3 sentences: purpose from the reviewed SPEC.md overview, stack from the reviewed
+ ARCHITECTURE.md, approximate scale from CODEBASE.md]
+ ## Spec gate
+ ⬜ spec: pending · approve the verified spec (SPEC.md, ARCHITECTURE.md, CODEBASE.md, CLAUDE.md) before the first feature
+
## Active work
(nothing yet — add a feature with `feature:` or fix a bug with `bug:`)
## Completed
(prior work not tracked — project onboarded on [date])
+ ✅ [Feature name] · built before onboarding · vibe/SPEC.md § [Feature name]
+ [one line per feature in the reviewed vibe/SPEC.md "Observed features", the same list 7B uses]
## Phase gates
(not applicable — project pre-dates vibe-* framework)
## What's next
Run `review:` on the current codebase to establish a quality baseline.
Then use `feature:` or `bug:` to start tracking work normally.
```
- ### 5G — Create remaining folders
+ The `## Spec gate` line is flipped by `vibe_state.py gate set spec` in Stage 8. Never edit
+ it by hand.
+ If `vibe/TASKS.md` already exists (a re-run), don't write it from the template: it tracks
+ work done since onboarding. Rewrite only "What we're working with" from the reviewed
+ documents, add the `## Spec gate` section (as above) if it is missing, and add a
+ Completed line only for an observed feature that has no line there yet. Keep every other
+ line exactly as it is.
+
+ ---
+
+ ## Stage 8 — Approval and the spec gate
+
+ The spec gate is the person's sign-off on the documents every later skill builds on.
+ Check first that the review still matches the documents:
+
```bash
- mkdir -p vibe/reviews
- mkdir -p vibe/features
- mkdir -p vibe/bugs
- mkdir -p vibe/backlog
+ VS="$HOME/.claude/skills/vibe-mode/scripts/vibe_state.py"
+ GF="$HOME/.claude/skills/vibe-goldfish/scripts/goldfish.py"
+ python3 "$VS" mode # → vibe_mode, approvals (add --run when entered from vibe-mode: run)
+ python3 "$GF" status spec; echo $?
```
- Create `vibe/reviews/backlog.md`:
- ```markdown
- # Review backlog
- > Started on [date] via vibe-init.
- > Run `review:` to populate this file with the first quality baseline.
- ## Outstanding P1 issues
- (none yet — run review: to establish baseline)
- ## Outstanding P2 issues
- (none yet)
- ## Resolved issues
- (none yet)
- ```
+ Exit 2 means someone edited a reviewed document after the review converged. Run Stage 6
+ again (manual: tell the person in one line and offer to run it now), then Stage 7 again.
+ Never record the gate on a review that doesn't match the current text. Exit 3 here only
+ means the person chose "continue anyway" in Stage 6 (manual): that acceptance is already
+ recorded, and their approval below is what signs the gate. If `status` errors with "no
+ goldfish review", the person chose ⚠️ SPEC NOT REVIEWED in Stage 6 (manual only): record
+ their approval below with `--by human` and no `--report`, and write "Spec review: not run
+ (no subagent tool)" in the 8B entry and in the report.
- ### 5H — CLAUDE.md (project root)
+ ### 8A — Record the sign-off
- Read `references/CLAUDE_RETROFIT.md` for the full template.
+ - **Manual mode:** show what the review changed, one line per fix (from
+ `vibe/goldfish/spec/resolution.md`), the person's verification included. Then ask:
+ > "Approve vibe/SPEC.md, vibe/ARCHITECTURE.md, vibe/CODEBASE.md and CLAUDE.md as they
+ > are now?"
+ If they ask for changes, make them, run Stage 6 again (the review re-opens by itself on
+ the edit), regenerate Stage 7, and ask again. On approval:
+ `python3 "$VS" gate set spec --status approved --by human --report vibe/goldfish/spec`
+ - **Autonomous, `APPROVALS=auto`:** `python3 "$VS" gate set spec --status approved --by agent-autonomous --report vibe/goldfish/spec`.
+ The helper refuses unless the goldfish review converged on the current text. If it
+ refuses, don't retry with other flags: STOP with
+ `run-state set --status needs_human --reason "spec gate: [the helper's error]" --next "see vibe/goldfish/spec"`
+ and end the session.
+ - **Autonomous, `APPROVALS=human`:** `python3 "$VS" gate set spec --status pending --report vibe/goldfish/spec`,
+ write the onboarding entry (8B), then STOP:
+ `run-state set --status needs_human --reason spec_approval --next "approve the spec (gate set spec --status approved --by human --report vibe/goldfish/spec), then run vibe-graph: build"`
+ and end the session.
- Generate CLAUDE.md at **project root**.
+ ### 8B — vibe/DECISIONS.md onboarding entry
- Key differences from greenfield CLAUDE.md:
- - Session startup reads `vibe/CODEBASE.md` first (existing code, not scaffolded)
- - Phase gates section replaced with: "No phase structure — this is an existing project. Use vibe-review on demand."
- - Active feature section still present — used by add-feature and fix-bug normally
- - Note at top: "Onboarded via vibe-init on [date]"
+ Written now, after the review and the sign-off, because it quotes the reviewed stack and
+ pattern and records who approved.
- Commands section must be populated from actual observed scripts:
- ```bash
- # From package.json scripts / Makefile / observed patterns
- dev: [actual dev command]
- build: [actual build command]
- test: [actual test command]
- lint: [actual lint command]
- ```
+ DECISIONS.md is append-only. Never write it from this template when it already exists
+ (spec-review, vibe-goldfish or this run's own autonomous logging will usually have created
+ it by now):
+ - **Absent:** create it with the template below.
+ - **Exists:** keep every existing entry exactly as it is, including entries other skills
+ wrote in other formats (for example `## [date] — Spec review`). If the header (the title
+ through the `## Format` block) is missing, add it above the existing entries. Add the
+ onboarding entry below them, numbered from the highest existing `D-NNN` ID (so it is
+ `D-001` only when no entry exists yet).
- If a command wasn't observed, write: `# Not observed during init — confirm with team`
+ ```markdown
+ # DECISIONS — [Project Name]
+ > Append-only. Every drift, scope change, tech choice — logged with full context.
+ > Onboarded via vibe-init on [date]. All decisions prior to this date are untracked.
+ ## Decision types
+ - drift — deviated from ARCHITECTURE.md
+ - blocker-resolution — impossible; workaround found
+ - tech-choice — chose between valid approaches
+ - scope-change — added/removed via change: command
+ - discovery — unexpected finding affecting future tasks
+
+ ## Format
+ ### D-[ID] — [Short title]
+ - **Date**: · **Task**: [TASK-ID] · **Type**: [type]
+ - **What was planned**: · **What was done**: · **Why**:
+ - **Alternatives considered**: · **Impact on other tasks**:
+ - **Approved by**: human | agent-autonomous
+
---
- ## Stage 6 — Spec review gate
+ ### D-001 — Project onboarded via vibe-init
+ - **Date**: [today] · **Task**: vibe-init · **Type**: discovery
+ - **What was planned**: N/A, legacy project with no prior vibe context
+ - **What was done**: Generated vibe/ scaffold from codebase analysis.
+ Stack: [stack from the reviewed ARCHITECTURE.md]. Pattern: [pattern from the reviewed ARCHITECTURE.md].
+ Files read: [N] files across [N] directories.
+ Spec review: [[verdict] in [N] rounds · vibe/goldfish/spec/resolution.md | not run (no subagent tool)]
+ SPEC.md: [verified by [person] on [date] | still PROVISIONAL, accepted as a risk by [person]]
+ - **Why**: Retrofitting vibe-* skills framework onto existing codebase.
+ - **Alternatives considered**: Manual documentation (rejected: too slow and error-prone)
+ - **Impact on other tasks**: Spec gate [approved [date] | pending a person's approval].
+ feature:, bug: and review: build on the reviewed documents from here on.
+ - **Approved by**: [human | agent-autonomous (APPROVALS=auto) | not yet: spec gate pending]
+ ```
- `vibe-spec-review` documents "Trigger 3 — after vibe-new-app or vibe-init", and a
- retrofit is exactly where it matters most: the SPEC.md was inferred from code and is
- marked PROVISIONAL. Invoke it **before** presenting the completion report — the gate
- runs first, not after you've told the user the job is done.
+ ---
- > "vibe/ folder generated from the codebase. Running spec-review — the SPEC.md is
- > PROVISIONAL, so this checks it before you build on it..."
+ ## Stage 9 — Build the dependency graph
- Invoke `vibe-spec-review`:
- - Trigger source: `vibe-init`
- - Scope: SPEC.md + ARCHITECTURE.md + BRIEF.md (all that exist)
+ Only once the spec gate is approved. **First, a sign-off given outside the session:** if
+ `python3 "$VS" gate show` says spec `approved` `by: human` and the onboarding entry still
+ says `not yet: spec gate pending` (autonomous `APPROVALS=human`, the person approved with
+ `gate set spec` after the session stopped), append under it:
+ `- **Approved by**: human · [date from gate show] · report vibe/goldfish/spec`.
+ Then invoke `vibe-graph: build`.
- It will flag the PROVISIONAL SPEC.md as a P1 to verify — expected for a retrofit, not
- a failure. Present the verdict.
+ This converts the reviewed CODEBASE.md into a queryable dependency graph.
+ No extra file reads — the information was just extracted for CODEBASE.md.
+ The graph enables vibe-fix-bug, vibe-test, and vibe-review to query
+ relationships directly instead of loading the full CODEBASE.md.
- **If spec-review stopped the run** (`python3 ~/.claude/skills/vibe-mode/scripts/vibe_state.py run-state show`
- says needs_human from spec review), **stop here too**: end the session, don't continue,
- don't report the step as done. In manual mode, a 🔴 verdict means follow spec-review
- Step 3 (more rounds, rework, or the person accepts). Never fix findings outside vibe-goldfish.
+ ```
+ vibe-graph: build complete
+ Files indexed from CODEBASE.md: [N]
+ Concepts mapped: [N]
+ Graph: vibe/graph/ (3 files generated)
+ Next update: automatic after next vibe-add-feature or vibe-fix-bug
+ ```
- Otherwise continue to the report.
+ Keep its result for the report. If the build failed or didn't run, the report says so.
---
- ## Stage 7 — Post-generation report
+ ## Stage 10 — Post-generation report
- After spec-review has run, output a single consolidated report in the conversation:
+ After the graph step, output a single consolidated report in the conversation. Every
+ line reports what actually happened:
```
✅ vibe-init complete — [Project Name]
GENERATED FILES
- CLAUDE.md ← project root
- vibe/ARCHITECTURE.md ← [N] patterns documented
- vibe/CODEBASE.md ← [N] files mapped, [N] routes, [N] models
- vibe/SPEC.md ← PROVISIONAL — [N] features inferred
- vibe/SPEC_INDEX.md
- vibe/DECISIONS.md ← bootstrap entry added (existing entries kept)
+ CLAUDE.md ← project root · reviewed
+ vibe/ARCHITECTURE.md ← [N] patterns documented · reviewed
+ vibe/CODEBASE.md ← [N] files mapped, [N] routes, [N] models · reviewed
+ vibe/SPEC.md ← [N] features · [verified by [person] | PROVISIONAL, accepted as a risk]
+ vibe/SPEC_INDEX.md ← from the reviewed SPEC.md
+ vibe/PLAN.md ← feature map, [N] existing features marked built [| kept: not written by vibe-init]
+ vibe/TASKS.md ← spec gate: [approved [date]]
+ vibe/DECISIONS.md ← onboarding entry added (existing entries kept)
vibe/IMPLEMENTATION_LOG.md ← empty; implementation decisions logged from here on
- vibe/TASKS.md
vibe/reviews/backlog.md
+ SPEC REVIEW
+ [verdict] · [N] rounds · [n] fixed · [n] contested · [n] escalated
+ Full record: vibe/goldfish/spec/resolution.md
+ [or, on ⚠️ SPEC NOT REVIEWED: Spec review: not run (no subagent tool)]
+
WHAT WAS READ
Stage 1: [N] files in topology scan
Stage 2: [N] anchor files read in full
Stage 3: [N] files sampled across [N] folder types
CONFIRMED
Stack: [e.g. Next.js 14 + TypeScript + Prisma + PostgreSQL]
Pattern: [e.g. Feature-based, MVC-ish]
Routes: [N] endpoints documented
Models: [N] data models documented
Commands: dev / build / test / lint [confirmed / partially confirmed]
+ Boundaries: Always [N] · Ask First [N] · Never [N] ([tiers with none found in the code])
FLAGGED UNKNOWNS
[List anything not determined — honest gaps]
- ⚠️ BEFORE RUNNING vibe-review:
- Scan vibe/SPEC.md and verify the inferred features are correct.
- Incorrect specs will cause review: to pass broken code.
- When verified, remove the PROVISIONAL banner and update "Last verified" date.
+ [Only if SPEC.md is still PROVISIONAL:]
+ ⚠️ SPEC.md IS STILL PROVISIONAL:
+ It was accepted as a risk, not verified. review: may pass code that matches a bug.
+ Verify it with `spec-review:` (preset init) before relying on review:.
WHAT WORKS NOW
- ✅ vibe-add-feature — CODEBASE.md and ARCHITECTURE.md ready
+ ✅ vibe-add-feature — CODEBASE.md, ARCHITECTURE.md and the PLAN.md feature map ready
✅ vibe-fix-bug — CODEBASE.md and ARCHITECTURE.md ready
- ✅ vibe-review — works, but note PROVISIONAL SPEC warning above
+ ✅ vibe-review — works against the [verified | provisional] SPEC.md
✅ vibe-design — CODEBASE.md ready; DESIGN_SYSTEM.md generated on first design: run
✅ vibe-progress — TASKS.md ready (starts from today)
- ✅ vibe-change-spec — SPEC.md ready (verify first)
- ✅ vibe-graph — dependency graph built from CODEBASE.md
+ ✅ vibe-change-spec — SPEC.md ready
+ [✅ vibe-graph — dependency graph built from CODEBASE.md ([N] files indexed)
+ | ⚠️ vibe-graph — not built: [reason]. Run `vibe-graph: build`]
SUGGESTED FIRST STEP
review: ← establishes quality baseline on the existing codebase
```
---
- ## Post-completion — Build dependency graph
-
- After spec-review and the completion report, invoke `vibe-graph: build`.
-
- This converts the CODEBASE.md just written into a queryable dependency graph.
- No extra file reads — the information was just extracted for CODEBASE.md.
- The graph enables vibe-fix-bug, vibe-test, and vibe-review to query
- relationships directly instead of loading the full CODEBASE.md.
-
- ```
- vibe-graph: build complete
- Files indexed from CODEBASE.md: [N]
- Concepts mapped: [N]
- Graph: vibe/graph/ (3 files generated)
- Next update: automatic after next vibe-add-feature or vibe-fix-bug
- ```
-
- ---
-
## Absolute rules
**Never invent.** If a pattern wasn't observed, it doesn't go in the docs.
- Use "not observed during init" over leaving a section blank.
+ Use "not observed during init" over leaving a section blank. The only exception is the
+ labelled `Never commit secrets` vibe rule in the Never tier (5A). An empty boundary tier
+ says "None found in the code: confirm with the team".
**Never read secrets.** `.env`, `*.key`, `*.pem`, `credentials.*` — skip unconditionally.
**Never overstate certainty.** "Pattern observed in 3 of 4 service files" is more honest
than "the project uses service-layer pattern."
- **Never generate PLAN.md.** That's a greenfield document — phases and scaffolding
- don't apply to existing code. Its absence will not break any vibe-* skill.
+ **Review before anything is derived.** SPEC_INDEX.md, PLAN.md, TASKS.md and the onboarding
+ entry come from the reviewed documents (Stage 7 and 8B), never from the Stage 4 notes.
+
+ **Only a person verifies the SPEC.** The PROVISIONAL banner comes off as the answer to the
+ review's finding, with the person's corrections. Never in autonomous mode, never on the
+ skill's own judgment.
+
+ **PLAN.md is a feature map, not a greenfield plan.** No phases and no scaffolding tasks:
+ existing features are listed as built, and new ones are added by `feature:`.
**Flag every gap explicitly.** Unknowns in the docs are features, not failures.
They tell the next agent exactly where to look when something doesn't make sense.
**Large codebase caveat is mandatory.** Any project with 200+ files must carry the
partial sampling warning in ARCHITECTURE.md, CODEBASE.md, and the post-generation report.