Vibe New App

---
name: vibe-new-app
description: >
  Full spec-driven setup workflow for building a brand new app from scratch with an AI coding agent.
  Triggers on "new:" prefix, "I want to build a new app", "starting a new project",
  "help me spec out a new app", "new project".
  Always use when the user is starting a greenfield project — even without the exact prefix.
  Generates CLAUDE.md at project root and the complete vibe/ folder.
  Reads BRIEF.md and ARCHITECTURE.md if they exist — skips questions already answered.
  Step 5 generates a complete multi-phase feature map in PLAN.md — every feature sequenced,
  dependencies explicit, parallel opportunities identified, future phases sketched.
  TASKS.md Phase 2+ shows ordered features with dependencies visible — not slugs.
  Generates a minimal ARCHITECTURE.md from PLAN.md if architect: was skipped.
  TASKS.md is the single human-facing file. TODO.md does not exist.
  Requires: frontend-design skill for Step 3 wireframe generation.
---

# Vibe New App Skill

Generates the complete project kit from brief and architecture.
Produces CLAUDE.md at project root and the full vibe/ folder the AI coding agent uses.

**Always run in Plan Mode (Shift+Tab). Exit Plan Mode only before task execution.**

---

## The O'Reilly principles this enforces

**Spec before code** — SPEC.md with acceptance criteria exists before any task runs.
**Context preservation** — CLAUDE.md, CODEBASE.md, ARCHITECTURE.md, SPEC_INDEX.md, TASKS.md
read every session so the agent never re-discovers what's been built.
**Incremental verifiable progress** — TASKS.md breaks the build into single verifiable tasks.
**Drift prevention** — DECISIONS.md created ready to log from the first task forward.

---

## Two audiences. Two file types.

**Human-facing — open this:**
- `vibe/TASKS.md` — your single progress view. Plain English. Updated after every task.

**Agent-facing — agent reads these, you never need to open them:**
- `CLAUDE.md` · `vibe/ARCHITECTURE.md` · `vibe/CODEBASE.md`
- `vibe/SPEC.md` · `vibe/SPEC_INDEX.md` · `vibe/PLAN.md` · `vibe/DECISIONS.md`
- `vibe/DESIGN_SYSTEM.md` *(created by design: — agent reads for design context)*
- `vibe/reviews/` · `vibe/features/` · `vibe/bugs/` · `vibe/backlog/`

---

## Folder structure this skill creates

```
your-project/
├── BRIEF.md                   ← brainstorm output (if exists)
├── CLAUDE.md                  ← agent rules — auto-read by Claude Code
└── vibe/
    ├── TASKS.md               ← YOUR progress view — only file you open
    ├── ARCHITECTURE.md        ← agent: patterns, read every session
    ├── CODEBASE.md            ← agent: live codebase snapshot
    ├── SPEC.md                ← agent: full requirements
    ├── SPEC_INDEX.md          ← agent: compressed spec map
    ├── PLAN.md                ← agent: phases and architecture
    ├── DECISIONS.md           ← agent: drift and change log (append-only)
    ├── DESIGN_SYSTEM.md       ← agent: design tokens (created by design:)
    ├── reviews/
    │   └── backlog.md
    ├── features/
    ├── bugs/
    └── backlog/
```

Note: `vibe/DESIGN_SYSTEM.md` is not created here — it is generated the first time
`design:` runs. The agent checks for it at session startup and reads it if it exists.

---

## Step 1 — Capture the idea and check for existing files

**Check for BRIEF.md and ARCHITECTURE.md at project root.**

**Both exist** (ran brainstorm: and architect: — recommended path):
- Read both fully before doing anything else
- Confirm: "Found brief and architecture. [App name] — [core value]. [N] decisions locked. Building from these — no repeated questions."
- Pre-populate Steps 2–5 from BRIEF.md. Use ARCHITECTURE.md for PLAN.md folder structure and CLAUDE.md conventions.
- Skip all answered questions. Surface open questions from the brief.

**Only BRIEF.md exists** (ran brainstorm: but not architect:):
- Read BRIEF.md fully
- Confirm: "Found brief. [App name] — [core value]. [N] decisions locked."
- Pre-populate Steps 2–5. Skip answered questions.
- Note: architect: was skipped — minimal ARCHITECTURE.md will be generated from PLAN.md decisions in Step 9.

**Neither exists** (starting fresh — not recommended but supported):
- Extract: what the app does, who uses it, the core value.
- Ask ONE clarifying question if unclear.
- Confirm: "Got it — building [X] for [who], core value: [Y]. Starting spec."
- Note: both BRIEF.md and ARCHITECTURE.md will be absent — minimal versions generated.

---

## Step 2 — Generate vibe/SPEC.md

Draft SPEC.md covering:
1. **Overview** — What this app does and why (2-3 sentences)
2. **Target users** — Who uses this and what they need
3. **Core features** — Each feature with acceptance criteria
4. **Out of scope** — Explicitly NOT in v1
5. **Tech stack** — Confirmed choices with reasoning
6. **Data model** — Key entities and relationships
7. **API shape** — Core endpoints (if applicable)
8. **Non-functional requirements** — Performance, security, responsiveness
9. **Conformance checklist** — What must be true for v1 to be done

Present draft. Ask: "Does this spec look right? Anything to add, change, or cut?"
Wait for approval. Save as `vibe/SPEC.md`.

**Living document rules:**
- Edit in-place on scope changes (via `change:` only — never informally)
- ~~Strikethrough~~ for removed items — never delete
- Update note at top: `> ⚠️ Last updated: [date] · [reason]`
- SPEC.md and SPEC_INDEX.md always updated as a pair — never one without the other

---

## Step 3 — UI Design

**Requires: frontend-design skill.** If not installed, proceed with prose wireframe description.

Tell the user: "Before planning the build phases, let's lock the UI."

Ask all at once:
1. **Screens** — How many screens/views? List briefly.
2. **Primary screen** — Where do users spend most time?
3. **Layout & nav** — Preferences? (sidebar, bottom nav, top nav — or no preference)
4. **Device** — Desktop only, mobile first, or both?
5. **Interactions** — Anything complex? (drag-drop, real-time, multi-step)
6. **References** — Any apps whose UI you like?
7. **Constraints** — Component library already chosen? Anything must show above fold?

Wait for answers. Generate wireframe using **frontend-design skill** principles:
- Commit to a bold, intentional aesthetic based on the app's purpose
- Complete HTML wireframe artifact covering all screens
- Realistic placeholder content — not Lorem ipsum
- Show navigation between screens

Present wireframe. Iterate until approved. Append UI Specification to vibe/SPEC.md:

```
## UI Specification
### Design direction
[One sentence: aesthetic direction and why]
### Component library
[What's being used, or "none specified"]
### Navigation structure
[Top-level destinations and flow — locked here, expensive to change mid-build]
### Screens
#### [Screen name]
- **Purpose**: [What the user does here]
- **Layout**: [Describe]
- **Key components**: [List]
- **User interactions**: [What the user can do]
- **States**: [Empty, loading, error states]
### Responsive behaviour
[Desktop/mobile approach]
```

Tell the user: "UI spec locked. Moving to planning."

---

## Step 4 — Generate vibe/SPEC_INDEX.md

Read vibe/SPEC.md in full. Generate SPEC_INDEX.md — compressed map under 40 lines:

```
# SPEC_INDEX — [Project Name]
> Compressed map of SPEC.md. Read each session. Fetch only the section you need.
> Last synced: [date]
## Overview — [one sentence] → SPEC.md#overview
## Features — [Feature]: [one sentence] (N criteria) → SPEC.md#feature-name
## UI — [N screens, direction summary] → SPEC.md#ui-specification
## Boundaries — Out of scope: [N items] → SPEC.md#out-of-scope
## Technical — Stack: [key choices] · Data: [N entities] · API: [N endpoints]
## Done condition — Conformance: [N items] → SPEC.md#conformance-checklist
## Backlog — [N items deferred] → vibe/backlog/
```

Save as `vibe/SPEC_INDEX.md`.
Rule: SPEC.md and SPEC_INDEX.md always committed together. Never one without the other.

---

## Step 5 — Generate vibe/PLAN.md

Read `references/PLAN_MD.md` for the full template.
Read vibe/SPEC.md in full. Read ARCHITECTURE.md if it exists.
Read BRIEF.md — specifically: feature list, non-goals, complexity estimate.

The critical section is the **Feature Map** (Section 6).
This is the complete build plan — every feature, every phase, fully sequenced.
It is not a list of slugs. It is not deferred to later.
It is planned now, before Phase 1 begins.

**Step 5A — Draft Sections 1–5 (structure, stack, architecture, data model, API):**

These are standard — fill from SPEC.md and ARCHITECTURE.md.
Identify shared data now: which tables/entities will be read or written by
multiple features. List them explicitly in Section 4 "Shared data" table.
This is the most common source of inter-feature conflicts caught too late.

**Step 5B — Build the Feature Map (Section 6) — the most important step:**

Read vibe/SPEC.md features section. Read BRIEF.md feature list and non-goals.

For every v1 feature, determine:

1. **Build order** — which features have no dependencies (start here),
   which need another feature's data model first, which can run in parallel.

   Ask yourself for each feature:
   - Does this feature READ data created by another feature?
     → It depends on that feature. Build that one first.
   - Does this feature WRITE data that another feature reads?
     → It must come before that feature.
   - Do two features share NO data writes and have the same dependencies?
     → They can run in parallel. Mark both explicitly.

2. **Shared data** — which entities/tables are created by one feature
   and consumed by another. These are the inter-feature dependency points
   that cause mid-build surprises if not planned now.

3. **Future phase sketch** — for Phase 4+ features from BRIEF.md backlog:
   note what Phase 1-3 must NOT hard-code to keep them possible.
   This prevents architectural decisions that feel fine now but block v2.

Build the dependency diagram:
```
Phase 1 complete
    ↓
[Feature with no deps — can start immediately after Phase 1]
    ↓              ↓
[Next feature]  [Parallel feature — no shared writes]
    ↓
[Feature that needs both above]
```

If the dependency order is unclear — ask the user ONE focused question:
> "Does [Feature B] need [Feature A]'s [entity] to exist first, or can they be built independently?"

**Step 5C — Present the feature map for approval:**

> "Here's the complete build plan — all phases mapped out before we start.
>
> [Present the feature map — Phase 1, Phase 2 ordered features with deps,
> Phase 3 tasks, Phase 4+ sketch if applicable]
>
> Build order for Phase 2:
> [ASCII dependency diagram]
>
> Parallel opportunities: [list features that can run simultaneously]
> Shared data points: [list entities that cross feature boundaries]
>
> Does this sequencing look right? Any features that should move earlier or later?"

Wait for approval. Adjust if needed.

**Step 5D — Save as `vibe/PLAN.md`.**

The feature map in PLAN.md is the source of truth for:
- TASKS.md Phase 2+ section (generated from it in Step 7)
- vibe-add-feature (reads it before drafting each feature spec)
- vibe-change-spec (reads it to assess phase impact of scope changes)
- vibe-parallel (reads dependency diagram for wave planning)

---

## Step 6 — Generate CLAUDE.md (project root)

Read vibe/SPEC.md, vibe/PLAN.md, vibe/ARCHITECTURE.md (if exists).
Read `references/CLAUDE_MD.md` for the full template.

Generate CLAUDE.md at **project root** substituting all [placeholders]:
- Project overview from SPEC.md
- Tech stack from PLAN.md
- Commands from chosen stack
- Code style and naming from ARCHITECTURE.md (if exists) or PLAN.md
- Phase gates section — mandatory review gates baked in from day one
- Session completion checklist — the 10-step post-task sequence (full checklist from template)
- CLAUDE.md active feature sections — cleanup rule included

**The per-task "next" sequence must be included verbatim in CLAUDE.md:**

```
## Per-task sequence (runs on every "next")

1. Verify acceptance criteria in FEATURE_TASKS.md are all ticked
2. Run tests: `[test command]` — must pass before commit
3. Run lint: `[lint command] --silent` — must pass before commit
4. Commit code changes:
   git add -A
   git commit -m "feat([scope]): [TASK-ID] — [one line plain English description]"
5. Commit doc updates separately:
   git add vibe/TASKS.md vibe/DECISIONS.md vibe/CODEBASE.md
   git commit -m "docs(TASKS): mark [TASK-ID] done — [plain English]"
6. Update "What just happened" and "What's next" in vibe/TASKS.md
7. Re-read vibe/TASKS.md silently
8. State next task in plain English and confirm before starting

Rules:
- NEVER skip the commit step — uncommitted work is invisible to vibe-graph and vibe-review
- Code commit and doc commit are ALWAYS separate — never mix feat and docs in one commit
- If tests fail — fix before committing, do not commit broken code
- If lint fails — fix before committing, do not commit with lint errors
```

**Investigation discipline (include verbatim):**
```
## Investigation discipline
For requests under 10 words: restate intent in one sentence before reading any files.
Data/state operations (reset, clear, seed, refresh) are not code bugs — do not investigate code.
Confirm the actual request before opening any file.
```

Save as `CLAUDE.md` at project root.

---

## Step 7 — Generate vibe/TASKS.md

Read `references/TASKS_MD.md` for full template and update rules.
Read vibe/SPEC.md, vibe/SPEC_INDEX.md, vibe/PLAN.md — especially Section 6 (Feature Map).

Generate TASKS.md with every phase fully represented:

**Header section:**
```
# TASKS — [Project Name]
> [2-3 plain English sentences: what this app does, who it's for, core value]
> One file to watch. Updated after every task.
```

**Phase 1 — Foundation:**
Each task as a checkbox with one plain English line.
```
## Phase 1 — Foundation
> No user-facing features. Sets up everything Phase 2 depends on.
> Phase 1 exit: run `review: phase 1` when all tasks complete.

[ ] P1-001 · [Task] — [one plain English line]
[ ] P1-002 · [Task] — [one plain English line]
...
[ ] P1-00N · Populate CODEBASE.md — document everything built in Phase 1

## Phase 1 gate
⬜ review: phase 1 — pending
```

**Phase 2 — Core features (fully ordered from PLAN.md feature map):**

This is the critical change. Phase 2 is not slugs — it is the complete
ordered feature list with dependencies visible, derived from PLAN.md Section 6.

```
## Phase 2 — Core features
> Build order is deliberate. Features are sequenced by dependency.
> A feature marked [needs: X] cannot start until X is complete.
> Features marked [parallel with: X] can run simultaneously with X.
> Phase 2 exit: run `review: phase 2` when all features complete.

⬜ [Feature 1 name] — [what the user can do when this is done]
   Build order: 1 · No dependencies · Start here after Phase 1 gate passes
   Shared data: creates [Entity] used by Feature 2 and Feature 3
   Estimate: ~[N] hours
   Spec: run `feature: [name]` to plan this feature in detail

⬜ [Feature 2 name] — [what the user can do]
   Build order: 2 · Needs: Feature 1 complete
   Reason: reads [Entity] created by Feature 1
   Parallel with: Feature 3 (no shared writes)
   Estimate: ~[N] hours
   Spec: run `feature: [name]` to plan this feature in detail

⬜ [Feature 3 name] — [what the user can do]
   Build order: 2 · Needs: Feature 1 complete
   Parallel with: Feature 2 (no shared writes)
   Estimate: ~[N] hours
   Spec: run `feature: [name]` to plan this feature in detail

⬜ [Feature 4 name] — [what the user can do]
   Build order: 3 · Needs: Feature 2 + Feature 3 complete
   Reason: reads [Entity] from Feature 2 and [Entity] from Feature 3
   Estimate: ~[N] hours
   Spec: run `feature: [name]` to plan this feature in detail

## Phase 2 gate
⬜ review: phase 2 — pending
```

**Phase 3 — Polish and hardening:**
```
## Phase 3 — Polish and hardening
> Runs after Phase 2 gate passes. No new features.
> Phase 3 exit: run `review: final` — 0 P0 + 0 P1 before deploy.

⬜ Performance audit — profile and fix slow paths
⬜ Error handling pass — all edge cases, empty states, error boundaries
⬜ Accessibility audit — WCAG AA for all screens
⬜ E2E tests — critical user flows automated
⬜ Security review — auth, input validation, secrets, dependencies
⬜ Documentation — README, API docs, deployment guide

## Final gate
⬜ review: final — pending
```

**Phase 4+ (if in PLAN.md — future phases sketched):**
```
## Phase 4+ — Future (not in current build)
> Planned so Phase 1-3 architecture doesn't foreclose these.
> Run `brainstorm:` when ready to plan the next version.

⬜ [Future feature] — [one sentence] · planned for v2
⬜ [Future feature] — [one sentence] · planned for v2
```

**Footer:**
```
---
## What just happened
[Project name] project kit created. Phase 1 ready to begin.

## What's next
⬜ P1-001 · [First Phase 1 task in plain English]
Start Phase 1: read CLAUDE.md then vibe/TASKS.md. Say "next" for each task.
Run `review: phase 1` when all Phase 1 tasks are complete.
```

**Non-negotiable rules:**
- Build order and dependency reasons visible for every Phase 2+ feature
- `feature: [name]` trigger visible on every planned feature — user knows exactly what to run
- Phase gate instruction visible at end of each phase
- Plain English everywhere — what the user sees/experiences, not technical details
- Human should never need to open PLAN.md to know what to build next or in what order

Save as `vibe/TASKS.md`.

---

## Step 8 — Generate vibe/CODEBASE.md (placeholder)

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

For a new app, CODEBASE.md starts as a placeholder.
The last task in Phase 1 populates it fully from the scaffolded project.

Generate the placeholder version. Save as `vibe/CODEBASE.md`.

---

## Step 9 — Generate remaining vibe/ files and handle ARCHITECTURE.md

### vibe/DECISIONS.md

```
# DECISIONS — [Project Name]
> Append-only. Every drift, scope change, tech choice — logged with full context.

## Decision types
- drift — deviated from PLAN.md or ARCHITECTURE.md
- blocker-resolution — impossible; workaround found
- tech-choice — chose between valid approaches not in plan
- 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

(No entries yet)
```

### vibe/reviews/ folder

Create `vibe/reviews/backlog.md`:
```
# Review Backlog
> P1/P2/P3 issues tracked across all phase reviews.
> P1 must resolve before deploy. Updated after every review.
## Outstanding P1 Issues
(none yet)
## Outstanding P2 Issues
(none yet)
## Resolved Issues
(none yet)
```

### ARCHITECTURE.md handling

**If ARCHITECTURE.md exists at project root:** Move to `vibe/ARCHITECTURE.md`.

**If ARCHITECTURE.md does not exist** (architect: was skipped):
Generate a minimal `vibe/ARCHITECTURE.md` from PLAN.md decisions:
- Extract the folder structure, naming conventions, and tech choices from PLAN.md
- Apply the O'Reilly Principles section verbatim from `references/ARCHITECTURE_MD.md`
- Mark it clearly: `> ⚠️ Auto-generated from PLAN.md — architect: was not run.`
- `> Consider running architect: to make these decisions explicit and add missing sections.`
This ensures review: has an ARCHITECTURE.md to check against from Phase 1.

---

## Step 10 — Spec review gate

Before telling the user the kit is ready, announce and hand off to spec-review:

> "vibe/ folder created. Running spec-review before first task..."

Invoke `vibe-spec-review` with:
- Trigger source: `new-app`
- Scope: SPEC.md + ARCHITECTURE.md + BRIEF.md + AGENT_ARCH.md (all that exist)

After spec-review completes:

## Step 10B — Initialise dependency graph

Invoke `vibe-graph: init`.

This builds the spec graph from SPEC.md and ARCHITECTURE.md —
all planned nodes created before any code is written.
Nodes will transition from `planned` to `built` as features are implemented.

After graph init completes:

## Step 11 — Tell the user

---
> 🎉 **Your project kit is ready.**
>
> **One file to watch:** `vibe/TASKS.md`
>
> **Structure created:**
> ```
> CLAUDE.md
> vibe/TASKS.md        ← open this
> vibe/ARCHITECTURE.md ← [locked from architect: / auto-generated from plan]
> vibe/CODEBASE.md     ← placeholder until Phase 1 done
> vibe/SPEC.md + SPEC_INDEX.md + PLAN.md + DECISIONS.md
> vibe/reviews/backlog.md
> vibe/spec-reviews/   ← spec review history
> vibe/graph/          ← dependency graph (spec graph initialised)
> ```
> **Spec review:** [✅ clean / ⚠️ [N] warnings acknowledged / 🔴 [N] P0s fixed]
> **Graph:** [N] planned nodes · [N] concepts mapped · updates automatically
>
> **Read execution mode:**
> ```bash
> grep "VIBE_MODE" CLAUDE.md 2>/dev/null | cut -d= -f2 | tr -d ' '
> ```
>
> If `autonomous` → read `~/.claude/skills/vibe-mode/references/AUTONOMOUS_EXECUTION_BLOCK.md`
> and follow the autonomous execution protocol for Phase 1 tasks. Begin immediately.
>
> If `manual` or not set → tell the user:
> ```
> Read CLAUDE.md, then vibe/CODEBASE.md, then vibe/ARCHITECTURE.md,
> then vibe/SPEC_INDEX.md, then vibe/TASKS.md.
> Confirm the first task before writing any code.
> ```
> Say **"next"** after each task.
> Run **"review: phase 1"** when Phase 1 completes — mandatory gate.
---