vibe-init git:20261030.c951717B

Immutable. This exact content never changes and is served at /api/v1/blob/36320a4a39c30c95.

---
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 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.**
**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, 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"
```

**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 (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 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 — Write the documents the review checks

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 — CLAUDE.md (project root)

Read `references/CLAUDE_RETROFIT.md` for the full template.

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.

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

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`

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 — 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 — 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: 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.
```

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
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 $?
```

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.

### 8A — Record the sign-off

- **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.

### 8B — vibe/DECISIONS.md onboarding entry

Written now, after the review and the sign-off, because it quotes the reviewed stack and
pattern and records who approved.

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).

```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

---

### 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]
```

---

## Stage 9 — Build the dependency graph

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`.

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.

```
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
```

Keep its result for the report. If the build failed or didn't run, the report says so.

---

## Stage 10 — Post-generation report

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 · 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/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]

[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, ARCHITECTURE.md and the PLAN.md feature map ready
  ✅ vibe-fix-bug      — CODEBASE.md and ARCHITECTURE.md ready
  ✅ 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
  [✅ 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
```

---

## 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. 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."

**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.