04 — Quickstart

When to read this: Right after installing the kit. This is a 30-minute walkthrough that takes you from agent-workflow to your first kicked-off spec. You'll skim or skip later chapters that go deep on each step.

The shortest path through the kit's full setup. Uses a fictional project — a small writing tracker — but the steps are the same for any project. By the end you'll have:

• A bootstrapped repo with all the kit's files in it.
• A filled-out PRD, ROADMAP, DESIGN.md, and CLAUDE.md.
• A backlog with triaged specs.
• One spec actively in progress.

This walkthrough skips ARCHITECTURE.md because the example project doesn't have a database. Add it as a step between PRD and DESIGN if you need it — see Chapter 06.

The example project#

A web app that helps a solo writer track daily word counts and weekly streaks. One user (themselves), no auth, no database (local storage is fine for V1), one page. Call it WordPace.

A thin project. Exactly the kind where the kit's structure feels like overkill at first and pays off most over the next month.

Step 0 — Create the project#

mkdir wordpace && cd wordpace
git init

Scaffold whatever framework you like in this directory: Next.js, Vite + React, Astro, raw HTML. The kit doesn't care. For this walkthrough, commit an empty repo and move on.

Step 1 — Run the bootstrap#

agent-workflow

Output ends with a "Bootstrap complete" banner and a hint to read GETTING-STARTED.md. The kit has dropped these files into your project:

CLAUDE.md           AGENTS.md           GETTING-STARTED.md
prompts/            .claude/             .cursor/
docs/backlog.md     docs/agent-workflow-skills.md
scripts/check-tokens.sh                   tests/a11y.spec.ts

Skim GETTING-STARTED.md once. The rest of this chapter walks the same flow.

Commit:

git add . && git commit -m "kit: bootstrap"

Step 2 — Write the PRD with prd-grill#

Open Claude Code (or Cursor) in the project folder. In the chat, type:

prd-grill

This invokes the prd-grill skill. It reads the project state, then asks questions one at a time. It recommends an answer with each one. You react instead of starting from a blank prompt.

An abbreviated version of what the conversation looks like (you do this for real — this is the shape):

Skill: Who is V1 for? Not "everyone" or "writers" generically — name a single archetype, ideally based on a real person. What do they do, what's the moment in their day they'd reach for this product?

You: Me. Solo founder, write a daily blog post and weekly newsletter. Currently track word counts in a spreadsheet, hate it.

Skill: I'd guess the user is a solo founder/writer who writes daily for an audience — not a novelist. The trigger moment is probably "I'm done writing for the day, want to log it without leaving my flow." Does that fit?

You: Yes, with one addition: the streak matters more than the count. I want to see "you've written 7 days in a row" when I open the app.

The skill walks six phases: primary user, problem, V1 capabilities, non-goals (the longest section by design), success metrics, constraints. Spend the most time on non-goals. That's where AI agents drift later if you didn't write things down.

When the skill is done, it writes docs/PRD.md. Open it. Read it once. If a section reads vague, run prd-grill again on that section.

Chapter 05 goes deep on what makes a good PRD section.

Commit:

git add docs/PRD.md && git commit -m "docs: write PRD"

Step 3 — Write DESIGN.md with design-md-builder#

Same shape, different skill. In the chat:

design-md-builder

The skill asks for 3 sites whose visual design you'd steal and 2 sites you actively dislike, and why. Then it walks through brand identity, type system, color, motion.

A real abbreviated session:

Skill: Reference sites?

You: Pitchfork, Stripe Press, Linear's old marketing site.

Skill: Strong editorial mix — Pitchfork's serif headlines, Stripe Press's confident type contrast, Linear's restraint. Aesthetic direction proposal: "editorial restraint" — display serif at heavy weight (Fraunces 800), body in a clean grotesque (Cabinet Grotesk 400), one accent color, no decorative motion. Confirm or push back?

You: Yes, but let's use Newsreader instead of Fraunces — I want a touch more warmth.

When the skill is done, it writes DESIGN.md at the repo root. Open it. The structure looks like:

# DESIGN.md
## Brand identity
## Type system
## Color
## Space and shape
## Motion
## Voice
## Forbidden defaults
  ### Universal
  ### Project-specific rejections

Chapter 07 goes deep on DESIGN.md.

Commit:

git add DESIGN.md && git commit -m "design: lock in brand"

Step 4 — Draft the ROADMAP#

The kit ships a prompt at prompts/prompt-roadmap.md that you hand to Claude Code. In the chat:

Read docs/PRD.md and follow prompts/prompt-roadmap.md to draft docs/ROADMAP.md.

The agent reads the PRD, follows the prompt's structure (2–4 phases, each shippable on its own, ordered by dependency), and writes a draft.

For WordPace, the output might look like:

## P0: Setup
**Acceptance criteria:**
- [ ] Vite + React project initialized with kit + DESIGN.md tokens wired in
- [ ] Tokens visible at /tokens dev route for sanity check
- [ ] check-tokens.sh passes on a stub component
 
**Depends on:** none
 
## P1: Daily logger
**Acceptance criteria:**
- [ ] User can enter today's word count and submit
- [ ] App stores entries in localStorage with a date key
- [ ] Today's entry shows on the page after submission
 
**Depends on:** P0
 
## P2: Streak
**Acceptance criteria:**
- [ ] App computes consecutive-day streak from localStorage
- [ ] Streak shown prominently above today's entry
 
**Depends on:** P1
 
## Out of scope for V1
- ❌ Multi-user / cloud sync. *Local-only for V1.*
- ❌ Word goals or targets. *Streak is the only motivation surface.*
- ❌ Mobile native. *Mobile-responsive web is enough.*

Read it. If the order is wrong or a phase isn't shippable on its own, edit it.

Commit:

git add docs/ROADMAP.md && git commit -m "docs: draft ROADMAP"

Step 5 — Fill in CLAUDE.md placeholders#

Open CLAUDE.md. The kit ships it with {{PLACEHOLDERS}}:

• {{PROJECT_NAME}} → WordPace
• {{ONE_PARAGRAPH_PRODUCT}} → distill from the PRD's user + problem + V1 sections
• {{TREE_OR_STUB}} → run tree -L 2 -I node_modules and paste the result
• {{CONVENTIONS_DO_AND_DONT}} → 3–6 short bullets ("Use OKLCH for color via DESIGN.md tokens", "Don't introduce a backend without revising the PRD")
• {{SUCCESS_METRICS}} → pull from PRD §5
• {{ANTI_PATTERNS}} → pull from PRD §6 (the things you said the product is not)

Each placeholder is 1–3 lines. Don't paste your whole PRD. CLAUDE.md is the cheat sheet. PRD.md is the source.

Commit:

git add CLAUDE.md && git commit -m "docs: fill CLAUDE.md"

Step 6 — Seed the backlog#

The kit ships another prompt at prompts/prompt-seed-backlog.md. In the chat:

Read docs/PRD.md and docs/ROADMAP.md and follow prompts/prompt-seed-backlog.md to populate the Inbox in docs/backlog.md.

The agent reads both docs and appends pre-classified items to the Inbox. For WordPace it might produce:

## Inbox
 
### Phase 0 — Setup
- TASK-02: Initialize Vite + React + Tailwind v4
- TASK-03: Wire DESIGN.md tokens into globals.css @theme inline block
- TASK-04: Add check-tokens.sh to npm run lint
 
### Phase 1 — Daily logger
- US-01: User can enter today's word count
- US-02: App stores entry in localStorage with a date key
- US-03: Today's entry shows on the page after submission
 
### Phase 2 — Streak
- US-04: App computes streak from localStorage entries
- US-05: Streak shown prominently above today's entry

(Plus the existing TASK-01: Define ROADMAP and phase files item from the kit's stub. You can mark that one [x] since you just did it.)

Commit:

git add docs/backlog.md && git commit -m "docs: seed backlog"

Step 7 — Triage the backlog#

Move items from the Inbox into phase files, tagging each with kind: ui | backend | infra. In the chat:

/backlog-triage

The skill walks through each Inbox item, asks (or recommends) a kind, then moves it into docs/backlog/phase-N-*.md. The kind tag is what the kickoff command reads later to dispatch correctly:

• kind: ui → kicked off via /craft-ui (visual review gate)
• kind: backend → kicked off via /kickoff-spec (tests-pass gate)
• kind: infra → kicked off via /kickoff-spec (tests-pass + smoke check)

For WordPace, most items are ui: the input form, the display, the streak surface. The TASK items are infra: build setup, token wiring, lint configuration.

After triage, your backlog folder looks like:

docs/
├── backlog.md                 ← Inbox now mostly empty
└── backlog/
    ├── phase-0-setup.md       ← TASK-02, TASK-03, TASK-04
    ├── phase-1-logger.md      ← US-01, US-02, US-03
    └── phase-2-streak.md      ← US-04, US-05

Each spec file has the item details, the kind tag, and an acceptance criteria checklist.

Commit:

git add docs/ && git commit -m "docs: triage backlog into phases"

Step 8 — Pick and kick off the first spec#

In the chat:

/pick-next-task

The skill reads the phased backlog, identifies what's unblocked (P0 ready, dependencies met), and recommends the next item. For WordPace, that's TASK-02: Initialize Vite + React + Tailwind v4.

Kick it off:

/kickoff-spec TASK-02

The skill validates the spec, flips its row to [~] (in progress), and dispatches to the right executor. TASK-02 is kind: infra, so it goes through the kickoff-spec skill's tests-pass gate. If it were kind: ui, it would go to /craft-ui and the visual review gate.

The agent now does the work: runs npm create vite, installs Tailwind v4, and so on. When done, it runs the verification gate (here: a smoke check that npm run dev starts without error).

If the gate passes, the agent reports back. Ship it via /ship-spec TASK-02. That runs a code review, asks for human merge confirmation, and flips the spec to [x].

Chapter 09 walks through the daily loop in detail, including all the mid-loop escape hatches (/architecture-review, design-reviewer, etc.).

Where you are now#

You have:

• A real PRD that says what WordPace is and explicitly what it isn't.
• A real DESIGN.md that pins down the brand instead of letting the agent guess.
• A 3-phase ROADMAP, ordered by dependency.
• A triaged backlog with kind tags driving the right execution lane.
• One spec shipped (P0 setup) and a clear path to the next.

Maybe 30 minutes of questions, plus 5 minutes per skill. The payoff is the next 30 days of work where the agent doesn't have to keep asking what the project is.

What to read next#

• If you want to go deeper on the PRD interrogation: Chapter 05.
• If you skipped ARCHITECTURE.md and your project has a database: Chapter 06.
• If DESIGN.md still feels vague after one pass: Chapter 07.
• For the daily build loop: Chapter 09.
• For a longer end-to-end example: Worked example: Pomodoro Tracker.