stitchwand — Multi-Agent Workflow Guide

Is this real?

Yes. Starting after day-5 (MCP + CLI merge), every remaining section of the v0.9 launch plan is designed to run as a parallel multi-agent sprint. Three Claude Code instances, three git worktrees, three branches, merging back in dependency order. This is documented in agents.html and AGENTS-SETUP-REPORT.md.

Agent 1 Core Engine

Works in ../stitchwand-agent-core on branch agent/core-engine. Scope: packages/core/. Parsers, validation, diff, convert, types.

Agent 2 MCP + CLI

Works in ../stitchwand-agent-mcpcli on branch agent/mcp-cli. Scope: packages/mcp-server/ + packages/cli/.

Agent 3 Web App

Works in ../stitchwand-agent-web on branch agent/web-app. Scope: apps/web/. Most day-6–day-9a tasks land here.

Single-task vs combined prompts

The original project plan gives you one prompt per task. That's fine for a small change, but for a section with 5–7 related tasks it's noisy: Claude loses the shape of the section, redoes discovery for every task, and you approve permissions over and over. The combined approach fixes all of that.

Single-task prompt

Use when: you're fixing one bug, landing one tight feature, or intentionally pausing between tasks to QA manually. One prompt, one commit, one review. Max control. Slower throughput.

Combined multi-step prompt

Use when: you want to finish a whole section in one agent session. Claude sees all N tasks at once, enters plan mode, presents a plan, waits for your “approved”, then executes with a self-check after each task.

Rule of thumb: start a section with the combined prompt. If plan mode surfaces a concern, drop into single-task mode for the tricky ones. You can always fall back — you can't easily zoom out.

The plan-first contract

Every combined prompt in this doc starts with the same block. It's the contract that keeps you in control:

contract block

STOP — Plan before you code.

Enter plan mode (Shift+Tab twice in Claude Code, or use the EnterPlanMode
tool). Read every file referenced below, then present a single
implementation plan that covers ALL tasks in this section.

Do NOT use Write, Edit, NotebookEdit, or any file-mutating Bash command
until I reply with the exact word: approved

Your plan must include, for each task:
  1. Files you will create or modify (full paths)
  2. The shape of the changes (new exports, new components, new routes)
  3. What the self-check will run and how you will verify it passes
  4. Any open questions that would change the approach

Claude Code honors this because plan mode and ExitPlanMode are first-class tools. The phrasing also works on agents without plan mode: they just output the plan as text and wait.

What you will find in this guide

Setup & Terminals — one-time worktree setup, which terminal window to name what, how to verify the setup.
Section Prompts — every multi-agent section from the launch plan with both a single-task list and a combined multi-step prompt. Copy buttons on everything.
Merge & QA — dependency-order merge back, QA checklist, cleanup.
FAQ — the stuff you'll ask in hour one.

Deep multi-agent theory (paperclip pattern, AGENTS.md scoping, subagents, Agent Teams) lives in agents.html. This doc is the operating manual.

One-time worktree setup

Run this from the main repo root. It creates three sibling directories, each on its own branch, each with its own node_modules. Do it once; reuse it for every subsequent sprint.

terminal — main repo root

# 1. Create the 3 worktrees
cd /Users/dilshaus/dev/stitchwand
git worktree add ../stitchwand-agent-core   -b agent/core-engine
git worktree add ../stitchwand-agent-mcpcli -b agent/mcp-cli
git worktree add ../stitchwand-agent-web    -b agent/web-app

# 2. Install deps in each (each needs its own node_modules)
cd ../stitchwand-agent-core   && npm install && npx turbo build --filter=@stitchwand/core
cd ../stitchwand-agent-mcpcli && npm install && npx turbo build --filter=@stitchwand/core
cd ../stitchwand-agent-web    && npm install && npx turbo build --filter=@stitchwand/core

# 3. Verify
cd /Users/dilshaus/dev/stitchwand
git worktree list

Disk space: each npm install uses ~175MB. Three worktrees ~525MB. Check df -h first. If tight, delete build artifacts before creating.

Terminal window naming

Open four terminal windows and label them clearly. You do not open a new window per prompt — you open one window per agent and paste prompts into that window's Claude Code session. The fourth window is a coordinator for git, gh, and monitoring.

Window label	Directory	What runs here
🟢 sw-CORE	`../stitchwand-agent-core`	Claude Code session for Agent 1 (Core Engine). Edits `packages/core/`.
🔵 sw-MCPCLI	`../stitchwand-agent-mcpcli`	Claude Code session for Agent 2 (MCP + CLI). Edits `packages/mcp-server/` and `packages/cli/`.
🟣 sw-WEB	`../stitchwand-agent-web`	Claude Code session for Agent 3 (Web App). Edits `apps/web/`. Most day-6–day-9a tasks live here.
🟠 sw-COORD	`/Users/dilshaus/dev/stitchwand`	No Claude session. Plain shell for `git worktree list`, merge-back, `gh`, monitoring, screenshots.

macOS: how to rename the active iTerm or Terminal window

zsh — set the tab title

# iTerm2 / Terminal.app -- set the current tab title
echo -ne "\033]0;🟢 sw-CORE\007"     # run inside core window
echo -ne "\033]0;🔵 sw-MCPCLI\007"   # run inside mcpcli window
echo -ne "\033]0;🟣 sw-WEB\007"      # run inside web window
echo -ne "\033]0;🟠 sw-COORD\007"    # run inside coordinator window

Starting an agent session

Inside each agent window, run claude. Claude Code will automatically pick up that worktree's AGENTS.md and CLAUDE.md. First prompt in every session should tell it to re-read those.

🟢 sw-CORE — launch

cd /Users/dilshaus/dev/stitchwand-agent-core && claude

🔵 sw-MCPCLI — launch

cd /Users/dilshaus/dev/stitchwand-agent-mcpcli && claude

🟣 sw-WEB — launch

cd /Users/dilshaus/dev/stitchwand-agent-web && claude

🟠 sw-COORD — open plain shell (no claude)

cd /Users/dilshaus/dev/stitchwand && git worktree list

First-prompt-of-the-day bootstrap (paste into any agent window)

Agent bootstrap

You are running inside a git worktree. Before anything else:

1. Read AGENTS.md and CLAUDE.md in this worktree. Follow their scope
   rules exactly. Do NOT modify files outside your declared scope.
2. Run: git status && git log --oneline -10
3. Run: npx vitest run
4. Report: which worktree you are in, which branch, any uncommitted
   changes, and whether the baseline tests are green.

Wait for my next prompt before making any changes.

Monitoring from the coordinator window

🟠 sw-COORD — status snapshot

git worktree list
git log --oneline -5 agent/core-engine
git log --oneline -5 agent/mcp-cli
git log --oneline -5 agent/web-app
git diff --stat main..agent/core-engine | tail -1
git diff --stat main..agent/mcp-cli     | tail -1
git diff --stat main..agent/web-app     | tail -1

How to use this tab

Each section below is one day of the launch plan. Every section has two views:

Single-task — the original N prompts, copy one at a time. Use if you want hard checkpoints between tasks.
Multi-step combined — one mega prompt containing the entire section, a plan-first contract, per-task self-checks, and a section-level verification. Use if you want one agent session to finish the whole section autonomously (after approving the plan).

All sections below run in 🟣 sw-WEB.

Day 6 · Wire Convert + DESIGN.md + Analyze Pages

Wire Core pages to real @stitchwand/core functions. Convert, DESIGN.md editor, and Analyze (Validate + Diff + A11y + Lint) all use real data with localStorage persistence.

day-6

🟣 sw-WEB 6 tasks plan-first

6.1 · /convert real API + upload

Wire /convert to real API + file upload

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/convert/page.tsx and packages/core/src/convert.ts.
Replace all setTimeout/mock calls with real fetch('/api/convert') calls.
Add FileReader API for drag-and-drop file upload. Auto-detect input format
(Style Dictionary, Tokens Studio, Tailwind, CSS Custom Props). Save conversion
history to localStorage using a useLocalStorage hook with key 'sw-convert-history'.
Create the /api/convert route handler that calls @stitchwand/core convert().
No mock data should remain.

Self-check

No setTimeout calls remain in apps/web/src/app/(app)/convert/
/api/convert route exists and calls convert() from core
Drag-and-drop works with a real Style Dictionary JSON file
localStorage key sw-convert-history persists across refresh

6.2 · /design-md editor + persistence

Wire /design-md editor with real parsing + persistence

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/design-md/page.tsx and packages/core/src/index.ts.
Wire the DESIGN.md editor to load/save real .md files. Parse DESIGN.md content
to the token model using @stitchwand/core. Add live preview that updates as user
edits. Store recent files list in localStorage with key 'sw-designmd-recent'.
Validate DESIGN.md on save and show errors inline. Add export buttons for all
supported formats (Style Dictionary, Tokens Studio, Tailwind, CSS). All data
must persist across page refreshes.

Self-check

Editor loads a local .md file and parses tokens
Live preview updates on keystroke (debounced is fine)
Invalid DESIGN.md shows inline validation errors
All 4 export formats download correctly
localStorage key sw-designmd-recent survives refresh

6.3 · /analyze Validate tab

Wire /analyze Validate tab to /api/validate

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/analyze/page.tsx and packages/core/src/validate.ts.
Wire the Validate tab to call /api/validate with real file uploads. Create the
route handler that calls @stitchwand/core validate(). Display real grades,
violation lists with severity levels, and overall scores. Add drag-and-drop
file upload for HTML + DESIGN.md files. Save validation results to localStorage
with key 'sw-validate-history' for history view. Replace all mock/demo data
with real validation output.

Self-check

/api/validate route exists and returns real core output
Validate tab shows real grade + severity-sorted violations
localStorage key sw-validate-history persists history
No mock data strings remain in the analyze page

6.4 · /analyze Diff tab

Wire /analyze Diff tab to /api/diff

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/analyze/page.tsx and packages/core/src/diff.ts.
Wire the Diff tab to call /api/diff with two DESIGN.md file uploads. Create
the route handler that calls @stitchwand/core diff(). Display real additions,
removals, and changes with color-coded diff view (green for added, red for
removed, amber for changed). Save diff snapshots to localStorage with key
'sw-diff-history'. Add side-by-side comparison view. Replace all mock data.

Self-check

/api/diff route exists and calls diff() from core
Color-coded diff renders added/removed/changed clearly
Side-by-side comparison layout works at desktop width
localStorage key sw-diff-history persists snapshots

6.5 · /analyze A11y + Lint tabs

Wire /analyze A11y + Lint tabs

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/analyze/page.tsx. Wire the Accessibility tab to
run WCAG contrast ratio checks, touch target sizing, and focus indicator
validation against uploaded DESIGN.md tokens. Wire the Lint tab to check token
naming conventions (camelCase, kebab-case consistency), detect unused tokens,
and flag circular references. Both tabs persist results to localStorage with
keys 'sw-a11y-history' and 'sw-lint-history'. Create /api/a11y and /api/lint
route handlers using @stitchwand/core.

Self-check

/api/a11y and /api/lint routes exist
A11y tab flags a failing contrast pair on a known-bad input
Lint tab detects an unused token on a known-bad input
Both localStorage keys persist across refresh

6.6 · E2E tests

End-to-end test Convert + DESIGN.md + Analyze

Run in web agent worktree (../stitchwand-agent-web).

Write Vitest integration tests for the Convert, DESIGN.md, and Analyze pages.
Test real file uploads with sample token files (Style Dictionary JSON, Tailwind
config). Test DESIGN.md editing, saving, and format export. Test Validate with
real HTML + DESIGN.md producing real grades. Test Diff with two DESIGN.md
versions showing real changes. Verify NO setTimeout calls remain in any of
these pages:
  grep -r 'setTimeout' apps/web/src/app/(app)/convert apps/web/src/app/(app)/design-md apps/web/src/app/(app)/analyze
Run: npx vitest run --reporter=verbose

Self-check

npx vitest run is all-green
The grep for setTimeout returns zero hits
Each new test actually exercises a real @stitchwand/core call

Day 6 · combined multi-step prompt

Run in the Web Agent worktree (../stitchwand-agent-web).
Terminal window: 🟣 sw-WEB

=========================================================================
STOP — Plan before you code.
=========================================================================
Enter plan mode (Shift+Tab twice in Claude Code, or use the EnterPlanMode
tool). Read every file referenced in the tasks below, then present a SINGLE
implementation plan that covers ALL 6 tasks in this section.

Do NOT use Write, Edit, NotebookEdit, or any file-mutating Bash command
until I reply with the exact word: approved

Your plan must include, for each task:
  1. Files you will create or modify (full paths)
  2. The shape of the changes (new exports, new components, new routes)
  3. What the self-check will run and how you will verify it passes
  4. Any open questions that would change the approach

=========================================================================
SECTION: Day 6 — Wire Convert + DESIGN.md + Analyze Pages
Goal: Replace all mock/setTimeout wiring in Convert, DESIGN.md editor,
and the 4 Analyze tabs with real @stitchwand/core calls via API routes,
with localStorage persistence on every page.
Execute these 6 tasks IN ORDER after I approve the plan.
=========================================================================

## Task 6.1 — Wire /convert to real API + file upload
Read apps/web/src/app/(app)/convert/page.tsx and packages/core/src/convert.ts.
Replace all setTimeout/mock calls with real fetch('/api/convert') calls.
Add FileReader API for drag-and-drop file upload. Auto-detect input format
(Style Dictionary, Tokens Studio, Tailwind, CSS Custom Props). Save conversion
history to localStorage using a useLocalStorage hook with key 'sw-convert-history'.
Create the /api/convert route handler that calls @stitchwand/core convert().
No mock data should remain.

Self-check (run before moving to 6.2, report pass/fail for each):
  [ ] grep -r 'setTimeout' apps/web/src/app/(app)/convert  → no hits
  [ ] /api/convert exists and calls core convert()
  [ ] Dragging a real Style Dictionary JSON produces a real result
  [ ] localStorage key 'sw-convert-history' survives refresh

## Task 6.2 — Wire /design-md editor with real parsing + persistence
Read apps/web/src/app/(app)/design-md/page.tsx and packages/core/src/index.ts.
Wire the DESIGN.md editor to load/save real .md files. Parse DESIGN.md content
to the token model using @stitchwand/core. Add live preview that updates as
user edits. Store recent files list in localStorage with key 'sw-designmd-recent'.
Validate DESIGN.md on save and show errors inline. Add export buttons for all
supported formats (Style Dictionary, Tokens Studio, Tailwind, CSS). All data
must persist across page refreshes.

Self-check (run before moving to 6.3):
  [ ] Editor loads a local .md file and parses tokens
  [ ] Live preview updates on edit
  [ ] Invalid DESIGN.md shows inline errors
  [ ] All 4 export formats download correctly
  [ ] localStorage key 'sw-designmd-recent' survives refresh

## Task 6.3 — Wire /analyze Validate tab to /api/validate
Read apps/web/src/app/(app)/analyze/page.tsx and packages/core/src/validate.ts.
Wire the Validate tab to call /api/validate with real file uploads. Create the
route handler that calls @stitchwand/core validate(). Display real grades,
violation lists with severity levels, and overall scores. Add drag-and-drop
file upload for HTML + DESIGN.md files. Save validation results to localStorage
with key 'sw-validate-history' for history view. Replace all mock/demo data
with real validation output.

Self-check (run before moving to 6.4):
  [ ] /api/validate exists and returns real core output
  [ ] Validate tab shows a real grade + severity-sorted violations
  [ ] localStorage key 'sw-validate-history' persists history
  [ ] No mock data strings remain in analyze page (grep confirms)

## Task 6.4 — Wire /analyze Diff tab to /api/diff
Read apps/web/src/app/(app)/analyze/page.tsx and packages/core/src/diff.ts.
Wire the Diff tab to call /api/diff with two DESIGN.md file uploads. Create
the route handler that calls @stitchwand/core diff(). Display real additions,
removals, and changes with color-coded diff view (green for added, red for
removed, amber for changed). Save diff snapshots to localStorage with key
'sw-diff-history'. Add side-by-side comparison view. Replace all mock data.

Self-check (run before moving to 6.5):
  [ ] /api/diff exists and calls core diff()
  [ ] Color-coded diff renders added/removed/changed clearly
  [ ] Side-by-side comparison layout works at desktop width
  [ ] localStorage key 'sw-diff-history' persists snapshots

## Task 6.5 — Wire /analyze A11y + Lint tabs
Read apps/web/src/app/(app)/analyze/page.tsx. Wire the Accessibility tab to
run WCAG contrast ratio checks, touch target sizing, and focus indicator
validation against uploaded DESIGN.md tokens. Wire the Lint tab to check token
naming conventions (camelCase, kebab-case consistency), detect unused tokens,
and flag circular references. Both tabs persist results to localStorage with
keys 'sw-a11y-history' and 'sw-lint-history'. Create /api/a11y and /api/lint
route handlers using @stitchwand/core.

Self-check (run before moving to 6.6):
  [ ] /api/a11y and /api/lint routes exist
  [ ] A11y tab flags a failing contrast pair on a known-bad input
  [ ] Lint tab detects an unused token on a known-bad input
  [ ] Both localStorage keys persist across refresh

## Task 6.6 — End-to-end test Convert + DESIGN.md + Analyze
Write Vitest integration tests for the Convert, DESIGN.md, and Analyze pages.
Test real file uploads with sample token files (Style Dictionary JSON, Tailwind
config). Test DESIGN.md editing, saving, and format export. Test Validate with
real HTML + DESIGN.md producing real grades. Test Diff with two DESIGN.md
versions showing real changes. Verify NO setTimeout calls remain in any of
these pages:
  grep -r 'setTimeout' apps/web/src/app/(app)/convert apps/web/src/app/(app)/design-md apps/web/src/app/(app)/analyze
Run: npx vitest run --reporter=verbose

Task 6.6 self-check (also the section self-check):
  [ ] npx vitest run  → all green
  [ ] The grep above returns zero hits
  [ ] Every new test exercises a real @stitchwand/core call
  [ ] Manual smoke test: refresh each of /convert /design-md /analyze,
      confirm localStorage-persisted data loads

=========================================================================
SECTION SELF-CHECK (run after 6.6)
=========================================================================
  [ ] npx tsc --noEmit                               → no type errors
  [ ] npx vitest run                                 → all green
  [ ] grep -r 'setTimeout' apps/web/src/app/(app)/{convert,design-md,analyze}  → no hits
  [ ] All 6 tasks committed with conventional messages

=========================================================================
RULES (non-negotiable)
=========================================================================
1. Plan first. Do not use Write/Edit/NotebookEdit/file-mutating Bash until I
   reply "approved".
2. After each task, run its self-check and report pass/fail BEFORE starting
   the next task.
3. Only modify files inside apps/web/. If you need a change in packages/core,
   stop and flag it.
4. Commit after each task: feat(convert): wire real API, etc.
5. If a self-check fails, fix it before proceeding. Do not skip.
6. Read AGENTS.md and CLAUDE.md in this worktree before starting. Dev server
   is port 3333.

Day 7 · Wire Prompt Library + Components

Build data models, storage, and real functionality for Prompt Library and Components pages. Both fully functional with localStorage persistence and user-created data.

day-7

🟣 sw-WEB 6 tasks plan-first

7.1 · Prompt Library data model

Prompt Library: data model + storage

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/prompts/page.tsx. Define a PromptTemplate TypeScript
type with fields: id (string), name (string), category (string), content (string),
variables (string[]), createdAt (ISO string), updatedAt (ISO string). Create a
usePromptStorage hook using localStorage with key 'sw-prompts'. Implement CRUD
operations (create, read, update, delete). Seed with 10+ Stitch-specific prompt
templates covering: color palette generation, typography scale, spacing system,
component scaffolding, accessibility audit, token conversion, brand voice,
layout patterns, responsive breakpoints, dark mode tokens. Use strict TypeScript
— no any.

Self-check

PromptTemplate type exported, no any
usePromptStorage hook persists to sw-prompts
10+ seed templates load on first visit

7.2 · Prompt Library UI

Prompt Library: full UI wiring

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/prompts/page.tsx. Wire the UI to the usePromptStorage
hook. Implement: create new prompt with name/category/content fields, edit
existing prompts inline, duplicate prompt, delete with confirmation dialog. Add
variable interpolation — detect {{variableName}} patterns in content and show
input fields for each variable with live preview. Add category filter dropdown
and text search. Copy-to-clipboard button on each prompt output. All actions
must persist to localStorage immediately. No mock data.

Self-check

Create / edit / duplicate / delete all persist to sw-prompts
{{var}} interpolation preview updates live
Category filter + text search both work
Copy button places interpolated content on clipboard

7.3 · Components data model

Components: data model + storage

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/components/page.tsx. Define a ComponentEntry
TypeScript type with fields: id (string), name (string), category (string),
html (string), css (string), designMdRef (string | null),
props (Record<string, string>),
variants (Array<{name: string, overrides: Record<string, string>}>),
createdAt (ISO string). Create a useComponentStorage hook using localStorage
with key 'sw-components'. Implement CRUD operations. Seed with example
components: Button (primary, secondary, ghost variants), Card, Input, Modal,
Badge, Avatar.

Self-check

ComponentEntry type exported with all fields
useComponentStorage persists to sw-components
6+ seeded components load on first visit

7.4 · Components UI

Components: full UI wiring

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/components/page.tsx. Wire the component browser
UI to useComponentStorage. Add live preview iframe that renders component
HTML + CSS. Create component form with HTML/CSS code editors. Variant switcher
— select variant to see different styles applied. Props editor — edit prop
values and see preview update in real time. Code export in 3 formats: raw HTML,
React JSX, Tailwind utility classes. All CRUD operations persist to
localStorage. Add category filter and search.

Self-check

Live preview iframe renders HTML + CSS correctly
Variant switcher actually swaps styles
Props editor updates preview in real time
All 3 export formats produce valid output

7.5 · Components ↔ core tokens

Wire Components to @stitchwand/core token resolution

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/components/page.tsx and packages/core/src/index.ts.
Wire component previews to resolve design tokens from a loaded DESIGN.md file.
When a user loads a DESIGN.md, extract tokens and inject them as CSS custom
properties into component preview iframes. Changing a token value in DESIGN.md
should update all component previews that reference it. Add a 'Validate' button
that checks components against their design system tokens using
@stitchwand/core validate().

Self-check

Loading a DESIGN.md injects CSS custom properties into preview
Editing a token value updates all dependent previews
Validate button surfaces core validate() output in UI

7.6 · E2E tests

End-to-end test Prompt Library + Components

Run in web agent worktree (../stitchwand-agent-web).

Write Vitest integration tests for Prompt Library and Components pages.
Test: create a prompt with {{variables}}, fill variable values, copy
interpolated output. Create a component with variants, switch between
variants, export as React JSX. Test localStorage persistence — save data,
simulate page refresh, verify data loads correctly. Verify seeded templates
and components are present on first load.
Run: npx vitest run --reporter=verbose

Self-check

npx vitest run all green
Persistence tests simulate refresh and verify restore
Seed data assertions pass on a clean localStorage

Day 7 · combined multi-step prompt

Run in the Web Agent worktree (../stitchwand-agent-web).
Terminal window: 🟣 sw-WEB

=========================================================================
STOP — Plan before you code.
=========================================================================
Enter plan mode (Shift+Tab twice in Claude Code, or use the EnterPlanMode
tool). Read every file referenced in the tasks below, then present a SINGLE
implementation plan that covers ALL 6 tasks in this section.

Do NOT use Write, Edit, NotebookEdit, or any file-mutating Bash command
until I reply with the exact word: approved

Your plan must include, for each task:
  1. Files you will create or modify (full paths)
  2. The shape of the changes (types, hooks, components)
  3. What the self-check will run and how you will verify it passes
  4. Any open questions that would change the approach

=========================================================================
SECTION: Day 7 — Wire Prompt Library + Components
Goal: Build real data models, storage hooks, and UI wiring for the Prompt
Library and Components pages. Full CRUD, seeded data, localStorage
persistence, and components that resolve tokens from a loaded DESIGN.md.
Execute these 6 tasks IN ORDER after I approve the plan.
=========================================================================

## Task 7.1 — Prompt Library: data model + storage
Read apps/web/src/app/(app)/prompts/page.tsx. Define a PromptTemplate TypeScript
type with fields: id (string), name (string), category (string), content (string),
variables (string[]), createdAt (ISO string), updatedAt (ISO string). Create a
usePromptStorage hook using localStorage with key 'sw-prompts'. Implement CRUD
operations. Seed with 10+ Stitch-specific prompt templates covering: color
palette generation, typography scale, spacing system, component scaffolding,
accessibility audit, token conversion, brand voice, layout patterns, responsive
breakpoints, dark mode tokens. Use strict TypeScript — no any.

Self-check:
  [ ] PromptTemplate type exported, no `any`
  [ ] usePromptStorage hook persists to 'sw-prompts'
  [ ] 10+ seed templates load on first visit
  [ ] npx tsc --noEmit passes

## Task 7.2 — Prompt Library: full UI wiring
Read apps/web/src/app/(app)/prompts/page.tsx. Wire the UI to usePromptStorage.
Implement: create new prompt with name/category/content fields, edit existing
prompts inline, duplicate prompt, delete with confirmation dialog. Add variable
interpolation — detect {{variableName}} patterns in content and show input
fields for each variable with live preview. Add category filter dropdown and
text search. Copy-to-clipboard button on each prompt output. All actions
persist to localStorage immediately. No mock data.

Self-check:
  [ ] Create / edit / duplicate / delete all persist to 'sw-prompts'
  [ ] {{var}} interpolation preview updates live
  [ ] Category filter + text search both work
  [ ] Copy button places interpolated content on clipboard

## Task 7.3 — Components: data model + storage
Read apps/web/src/app/(app)/components/page.tsx. Define a ComponentEntry type
with fields: id, name, category, html, css, designMdRef, props (Record),
variants (Array of {name, overrides}), createdAt. Create a useComponentStorage
hook using localStorage key 'sw-components'. Implement CRUD. Seed with: Button
(primary/secondary/ghost), Card, Input, Modal, Badge, Avatar.

Self-check:
  [ ] ComponentEntry type exported with all fields
  [ ] useComponentStorage persists to 'sw-components'
  [ ] 6+ seeded components load on first visit

## Task 7.4 — Components: full UI wiring
Read apps/web/src/app/(app)/components/page.tsx. Wire browser UI to
useComponentStorage. Live preview iframe renders HTML + CSS. Create component
form with HTML/CSS editors. Variant switcher UI. Props editor with live preview
updates. Code export in 3 formats: raw HTML, React JSX, Tailwind utility classes.
All CRUD persists. Category filter and search.

Self-check:
  [ ] Live preview iframe renders HTML + CSS correctly
  [ ] Variant switcher swaps styles
  [ ] Props editor updates preview in real time
  [ ] All 3 export formats produce valid output

## Task 7.5 — Wire Components to @stitchwand/core token resolution
Read apps/web/src/app/(app)/components/page.tsx and packages/core/src/index.ts.
When a DESIGN.md is loaded, extract tokens and inject them as CSS custom
properties into component preview iframes. Editing a token value updates all
dependent previews. Add a Validate button using @stitchwand/core validate().

Self-check:
  [ ] Loading a DESIGN.md injects CSS custom properties into preview
  [ ] Editing a token value updates all dependent previews
  [ ] Validate button surfaces core validate() output in UI

## Task 7.6 — End-to-end test Prompt Library + Components
Write Vitest integration tests. Create a prompt with {{variables}}, fill values,
copy interpolated output. Create a component with variants, switch variants,
export as React JSX. Test localStorage persistence — save, refresh, verify.
Verify seeded data present on first load.
Run: npx vitest run --reporter=verbose

Task 7.6 self-check (also section self-check):
  [ ] npx vitest run  → all green
  [ ] Persistence tests simulate refresh and verify restore
  [ ] Seed data assertions pass on a clean localStorage

=========================================================================
SECTION SELF-CHECK (run after 7.6)
=========================================================================
  [ ] npx tsc --noEmit                               → no type errors
  [ ] npx vitest run                                 → all green
  [ ] Manual: open /prompts, create + edit + delete, refresh, data stays
  [ ] Manual: open /components, swap variant, edit prop, refresh, stays
  [ ] All 6 tasks committed with conventional messages

=========================================================================
RULES (non-negotiable)
=========================================================================
1. Plan first. Do not mutate files until I reply "approved".
2. After each task, run its self-check and report pass/fail BEFORE starting
   the next task.
3. Only modify files inside apps/web/. Flag any needed core changes.
4. Commit after each task with conventional messages.
5. Fix any failing self-check before moving on.
6. Read AGENTS.md and CLAUDE.md in this worktree first. Dev server port 3333.

Day 8 · Wire Starter Kits + Design Swarm + Doc Writer

Build data models, storage, and real functionality for the three Advanced features. All fully functional with localStorage persistence and user-created data.

day-8

🟣 sw-WEB 7 tasks plan-first

8.1 · Starter Kits persistence

Starter Kits: data permanence + real generation

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/components/manifest/manifest-page.tsx. Define SavedKit type
with: id, name, brandName, colors (Record<string, string>),
typography ({heading: string, body: string, mono: string}), style (string),
generatedPrompts (string[]), generatedDesignMd (string), createdAt, updatedAt.
Create useKitStorage hook with localStorage key 'sw-kits'. Wire the wizard to
generate real Stitch prompts and DESIGN.md content from user input. Add export
buttons for generated files. Kit history with edit, duplicate, delete. All
data persists across refreshes.

Self-check

SavedKit type exported with all fields
useKitStorage persists to sw-kits
Wizard produces a real prompt + DESIGN.md (no placeholders)
Edit / duplicate / delete all persist

8.2 · Design Swarm data model

Design Swarm: data model + storage

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/swarm/page.tsx. Define SwarmSession type with:
id (string), name (string),
agents (Array<{role: string, specialty: string, color: string}>),
messages (Array<{agentId: string, content: string, timestamp: string}>),
designMdOutput (string), status ('active' | 'completed' | 'paused'),
createdAt (ISO string). Create useSwarmStorage hook with localStorage key
'sw-swarms'. Implement CRUD. Define agent roles: Color Specialist, Typography
Expert, Layout Architect, Accessibility Auditor, Brand Strategist.

Self-check

SwarmSession type exported with all fields
useSwarmStorage persists to sw-swarms
5 agent roles available as defaults

8.3 · Design Swarm UI

Design Swarm: full UI wiring

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/swarm/page.tsx. Wire the UI to useSwarmStorage.
Create swarm session with name and agent selection checkboxes. Show agent
conversation as a chat-like timeline with colored agent avatars and role
labels. Each agent 'contributes' to building a DESIGN.md collaboratively. View
conversation history for completed sessions. Save/load sessions from
localStorage. Export final DESIGN.md output as downloadable file. Duplicate
and restart sessions. Session list sidebar with status badges (active,
completed, paused).

Self-check

New session creates with agent selection
Chat timeline shows colored avatars + role labels
DESIGN.md output exports as .md download
Session list sidebar reflects status badges

8.4 · Doc Writer data model

Doc Writer: data model + storage

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/doc-writer/page.tsx. Define Document TypeScript
type with: id (string), name (string),
docType ('readme' | 'contributing' | 'api' | 'changelog' | 'custom'),
content (string), designMdRef (string | null), createdAt (ISO string),
updatedAt (ISO string). Create useDocStorage hook with localStorage key
'sw-docs'. Implement CRUD operations. Seed with template starters for each
doc type with placeholder content that references DESIGN.md token patterns.

Self-check

Document type exported with all 5 docTypes
useDocStorage persists to sw-docs
Seed template starters load per doc type

8.5 · Doc Writer UI

Doc Writer: full UI wiring

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/doc-writer/page.tsx. Wire the UI to useDocStorage.
Generate documentation content informed by loaded DESIGN.md context (token
names, color values, typography scale). Build a markdown editor with live
preview pane using a split-view layout. Template library with quick-start
options for each doc type. Export as .md file download. Document management:
create, edit, delete, duplicate from sidebar list. Auto-save on edit with
debounce (500ms). All data persists to localStorage.

Self-check

Split-view editor + preview works
Export produces a valid downloadable .md
Auto-save debounced at 500ms
Sidebar CRUD actions all persist

8.6 · Dashboard quick actions

Dashboard: update quick actions for all shipping features

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/page.tsx (dashboard/home page). Update quick
action cards to link to all Core + Advanced features: DESIGN.md, Prompt
Library, Token Studio (Convert), Components, Analyze, Starter Kits, Design
Swarm, Doc Writer. Add a recent activity feed that reads latest items from
localStorage across all tools (sw-convert-history, sw-prompts, sw-components,
sw-kits, sw-swarms, sw-docs). Show item counts and last-modified timestamps
for each tool. Use the same icon set from sidebar.tsx.

Self-check

All 8 quick action cards link to the correct route
Recent activity feed aggregates from all sw-* keys
Icon set matches sidebar.tsx

8.7 · E2E tests

End-to-end test Starter Kits + Design Swarm + Doc Writer

Run in web agent worktree (../stitchwand-agent-web).

Write Vitest integration tests for Starter Kits, Design Swarm, and Doc Writer.
Test cross-feature flow: create a Starter Kit with brand settings, use
generated DESIGN.md in a swarm session, generate documentation from swarm
output. Test each page independently: create/save/load/delete items, export
files. Verify localStorage persistence — save data, refresh, verify it loads.
Run: npx vitest run --reporter=verbose

Self-check

Cross-feature flow test passes
Each page has CRUD + export tests
Persistence tests verify localStorage round-trip
npx vitest run all green

Day 8 · combined multi-step prompt

Run in the Web Agent worktree (../stitchwand-agent-web).
Terminal window: 🟣 sw-WEB

=========================================================================
STOP — Plan before you code.
=========================================================================
Enter plan mode (Shift+Tab twice in Claude Code, or use the EnterPlanMode
tool). Read every file referenced in the tasks below, then present a SINGLE
implementation plan that covers ALL 7 tasks in this section.

Do NOT use Write, Edit, NotebookEdit, or any file-mutating Bash command
until I reply with the exact word: approved

=========================================================================
SECTION: Day 8 — Wire Starter Kits + Design Swarm + Doc Writer
Goal: Build real storage and UI wiring for the three Advanced features plus
a dashboard that reflects them. Everything persists to localStorage.
Execute these 7 tasks IN ORDER after I approve the plan.
=========================================================================

## Task 8.1 — Starter Kits: data permanence + real generation
Read apps/web/src/components/manifest/manifest-page.tsx. Define SavedKit type
with: id, name, brandName, colors (Record), typography (heading/body/mono),
style, generatedPrompts (string[]), generatedDesignMd (string), createdAt,
updatedAt. Create useKitStorage hook with localStorage key 'sw-kits'. Wire the
wizard to generate real Stitch prompts and DESIGN.md content from user input.
Export buttons for generated files. Kit history with edit/duplicate/delete.

Self-check:
  [ ] SavedKit type exported
  [ ] useKitStorage persists to 'sw-kits'
  [ ] Wizard produces a real prompt + DESIGN.md (no placeholders)
  [ ] Edit / duplicate / delete persist

## Task 8.2 — Design Swarm: data model + storage
Read apps/web/src/app/(app)/swarm/page.tsx. Define SwarmSession type with: id,
name, agents (role/specialty/color), messages (agentId/content/timestamp),
designMdOutput, status ('active'|'completed'|'paused'), createdAt. Create
useSwarmStorage hook with localStorage key 'sw-swarms'. CRUD. Agent roles:
Color Specialist, Typography Expert, Layout Architect, Accessibility Auditor,
Brand Strategist.

Self-check:
  [ ] SwarmSession type exported
  [ ] useSwarmStorage persists to 'sw-swarms'
  [ ] 5 default agent roles available

## Task 8.3 — Design Swarm: full UI wiring
Read apps/web/src/app/(app)/swarm/page.tsx. Wire UI to useSwarmStorage. Create
session with name + agent selection checkboxes. Chat-like timeline with
colored avatars and role labels. Agents contribute to building DESIGN.md
collaboratively. History view for completed sessions. Save/load sessions.
Export final DESIGN.md as downloadable file. Duplicate/restart. Session list
sidebar with status badges.

Self-check:
  [ ] New session creates with agent selection
  [ ] Chat timeline shows colored avatars + role labels
  [ ] DESIGN.md output exports as .md download
  [ ] Session list sidebar reflects status badges

## Task 8.4 — Doc Writer: data model + storage
Read apps/web/src/app/(app)/doc-writer/page.tsx. Define Document type with id,
name, docType ('readme'|'contributing'|'api'|'changelog'|'custom'), content,
designMdRef, createdAt, updatedAt. Create useDocStorage hook with localStorage
key 'sw-docs'. CRUD. Seed template starters for each doc type with content
that references DESIGN.md token patterns.

Self-check:
  [ ] Document type exported with all 5 docTypes
  [ ] useDocStorage persists to 'sw-docs'
  [ ] Seed template starters load per doc type

## Task 8.5 — Doc Writer: full UI wiring
Read apps/web/src/app/(app)/doc-writer/page.tsx. Wire UI to useDocStorage.
Generate docs informed by loaded DESIGN.md context (tokens, colors,
typography). Markdown editor with live preview split-view. Template library.
Export as .md download. Sidebar CRUD. Auto-save debounced at 500ms.

Self-check:
  [ ] Split-view editor + preview works
  [ ] Export produces a valid downloadable .md
  [ ] Auto-save debounced at 500ms
  [ ] Sidebar CRUD actions persist

## Task 8.6 — Dashboard: update quick actions for all shipping features
Read apps/web/src/app/(app)/page.tsx. Update quick action cards to link to
every Core + Advanced feature. Add a recent activity feed reading from
sw-convert-history, sw-prompts, sw-components, sw-kits, sw-swarms, sw-docs.
Show item counts and last-modified timestamps. Use icons from sidebar.tsx.

Self-check:
  [ ] All 8 quick action cards link to the correct route
  [ ] Recent activity feed aggregates from all sw-* keys
  [ ] Icon set matches sidebar.tsx

## Task 8.7 — End-to-end test Starter Kits + Design Swarm + Doc Writer
Write Vitest integration tests. Cross-feature flow: create Kit → use
generated DESIGN.md in a swarm → generate docs from swarm output. Each page:
create/save/load/delete items, export files. Verify localStorage round-trip.
Run: npx vitest run --reporter=verbose

Task 8.7 self-check (also section self-check):
  [ ] Cross-feature flow test passes
  [ ] Each page has CRUD + export tests
  [ ] Persistence tests verify round-trip
  [ ] npx vitest run  → all green

=========================================================================
SECTION SELF-CHECK (run after 8.7)
=========================================================================
  [ ] npx tsc --noEmit                               → no type errors
  [ ] npx vitest run                                 → all green
  [ ] Manual: cross-feature flow works end to end in the browser
  [ ] Dashboard recent activity feed shows real counts + timestamps
  [ ] All 7 tasks committed with conventional messages

=========================================================================
RULES (non-negotiable)
=========================================================================
1. Plan first. Do not mutate files until I reply "approved".
2. After each task, run its self-check and report pass/fail BEFORE starting
   the next task.
3. Only modify files inside apps/web/. Flag any needed core changes.
4. Commit after each task with conventional messages.
5. Fix any failing self-check before moving on.
6. Read AGENTS.md and CLAUDE.md in this worktree first. Dev server port 3333.

Day 9a · UI Polish + Voice Removal + Labs Gating

Final UI cleanup. Remove Voice Studio. Gate labs features behind feature flags. Settings page with data management. Full smoke test.

day-9a

🟣 sw-WEB 5 tasks plan-first

9a.1 · Remove Voice Studio

Remove Voice Studio from codebase

Run in web agent worktree (../stitchwand-agent-web).

Find and remove all Voice Studio code. Delete
apps/web/src/app/(app)/voice-studio/ directory. Remove the Voice Studio entry
from apps/web/src/lib/labs-registry.ts. Search for any references to 'voice'
or 'Voice Studio' in sidebar.tsx, command palette, demo data, and settings
pages. Remove all traces completely. Run TypeScript compiler to verify no
broken imports: npx tsc --noEmit

Self-check

apps/web/src/app/(app)/voice-studio/ no longer exists
grep -ri "voice studio" apps/web/src/ returns zero hits
npx tsc --noEmit passes

9a.2 · Labs feature flags

Gate Labs features behind feature flags

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/hooks/use-labs.ts and apps/web/src/lib/labs-registry.ts.
Verify that Labs features only appear in the sidebar when individually enabled
in Settings > Labs. Each lab feature should have a toggle with its name and
description from the registry. Feature state stored in localStorage. Disabled
labs routes should show a 'Feature not enabled — enable in Settings > Labs'
page instead of 404. Test: disable a lab, verify hidden from sidebar, navigate
to its URL directly to see gating message.

Self-check

Disabling a lab hides it from sidebar
Direct navigation to a disabled lab shows the gating page
Re-enabling restores sidebar + route access

9a.3 · Settings data management

Settings: data management + export/import

Run in web agent worktree (../stitchwand-agent-web).

Read apps/web/src/app/(app)/settings/page.tsx. Add a 'Data Management' section
with: Export All Data button (downloads all localStorage keys with 'sw-' prefix
as a single JSON file), Import Data button (file upload that merges or replaces
localStorage data from JSON backup), Clear All Data button with confirmation
dialog, Storage Usage display showing bytes used per feature (prompts,
components, kits, swarms, docs, settings). Test the full export > clear >
import round-trip to verify data integrity.

Self-check

Export downloads a single JSON covering every sw- key
Import restores exact contents after Clear
Storage usage display shows real per-feature bytes
Round-trip (export → clear → import) verified

9a.4 · Full app smoke test

Full app smoke test — all Core + Advanced pages

Run in web agent worktree (../stitchwand-agent-web).

Run a full smoke test of every Core + Advanced feature. Open each page and
verify:
 1) DESIGN.md — load, edit, save, export
 2) Convert — upload file, convert, view result
 3) Analyze — validate, diff, a11y, lint with real files
 4) Prompt Library — create, edit, use variables, copy
 5) Components — create, preview, switch variants, export
 6) Starter Kits — run wizard, save kit, load saved kit
 7) Design Swarm — create session, view agents, export
 8) Doc Writer — create doc, edit, export
Verify NO setTimeout mock calls remain: grep -r 'setTimeout' apps/web/src/
All data persists on page refresh.

Self-check

All 8 features pass their smoke check
grep -r 'setTimeout' apps/web/src/ returns zero hits
Every feature persists across a hard refresh

9a.5 · DESIGN.md Library polish

Solidify DESIGN.md Library filter/sort/drawer

Run in web agent worktree (../stitchwand-agent-web).

Test and polish the DESIGN.md Library filter/sort feature: sort dropdown
(Recent, Oldest, A-Z, Z-A, Most Tokens, Fewest Tokens), filter drawer (category,
status, reset), active file always pinned first. Verify drawer opens without
veil, grid reflows correctly, sort dropdown and drawer stay synced, reset
clears all filters. Test at all breakpoints (mobile, tablet, desktop).

Self-check

Sort dropdown has all 6 options and they actually reorder
Filter drawer syncs with sort state
Active file stays pinned first after any sort/filter
Works at mobile, tablet, and desktop breakpoints

Day 9a · combined multi-step prompt

Run in the Web Agent worktree (../stitchwand-agent-web).
Terminal window: 🟣 sw-WEB

=========================================================================
STOP — Plan before you code.
=========================================================================
Enter plan mode (Shift+Tab twice in Claude Code, or use the EnterPlanMode
tool). Read every file referenced in the tasks below, then present a SINGLE
implementation plan that covers ALL 5 tasks in this section.

Do NOT use Write, Edit, NotebookEdit, or any file-mutating Bash command
until I reply with the exact word: approved

=========================================================================
SECTION: Day 9a — UI Polish + Voice Removal + Labs Gating
Goal: Final cleanup before launch freeze. Remove Voice Studio, gate Labs
features, add Settings data management, smoke test every page, polish the
DESIGN.md Library.
Execute these 5 tasks IN ORDER after I approve the plan.
=========================================================================

## Task 9a.1 — Remove Voice Studio from codebase
Find and remove all Voice Studio code. Delete
apps/web/src/app/(app)/voice-studio/. Remove entry from
apps/web/src/lib/labs-registry.ts. Search for any references to 'voice' or
'Voice Studio' in sidebar.tsx, command palette, demo data, settings. Remove
all traces. Verify: npx tsc --noEmit

Self-check:
  [ ] voice-studio directory gone
  [ ] grep -ri "voice studio" apps/web/src/  → zero hits
  [ ] npx tsc --noEmit passes

## Task 9a.2 — Gate Labs features behind feature flags
Read apps/web/src/hooks/use-labs.ts and apps/web/src/lib/labs-registry.ts.
Verify Labs features only appear in sidebar when enabled in Settings > Labs.
Each lab has a toggle with name + description. State in localStorage. Disabled
routes show 'Feature not enabled — enable in Settings > Labs' instead of 404.
Test: disable a lab, verify hidden from sidebar, navigate directly to see
gating page.

Self-check:
  [ ] Disabling a lab hides it from sidebar
  [ ] Direct nav to a disabled lab shows the gating page
  [ ] Re-enabling restores sidebar + route access

## Task 9a.3 — Settings: data management + export/import
Read apps/web/src/app/(app)/settings/page.tsx. Add a Data Management section:
Export All Data button (downloads all 'sw-' localStorage keys as one JSON),
Import Data button (file upload that restores from backup), Clear All Data
button with confirmation, Storage Usage display showing bytes per feature.
Test export > clear > import round-trip.

Self-check:
  [ ] Export downloads a single JSON covering every sw-* key
  [ ] Import restores exact contents after Clear
  [ ] Storage usage display shows real per-feature bytes
  [ ] Full round-trip verified

## Task 9a.4 — Full app smoke test
Run a full smoke test of every Core + Advanced feature. Open each page and
verify:
 1) DESIGN.md — load, edit, save, export
 2) Convert — upload file, convert, view result
 3) Analyze — validate, diff, a11y, lint with real files
 4) Prompt Library — create, edit, use variables, copy
 5) Components — create, preview, switch variants, export
 6) Starter Kits — run wizard, save kit, load saved kit
 7) Design Swarm — create session, view agents, export
 8) Doc Writer — create doc, edit, export
Verify NO setTimeout mock calls remain: grep -r 'setTimeout' apps/web/src/
All data persists on page refresh.

Self-check:
  [ ] All 8 features pass their smoke check
  [ ] grep -r 'setTimeout' apps/web/src/  → zero hits
  [ ] Every feature persists across a hard refresh

## Task 9a.5 — Solidify DESIGN.md Library filter/sort/drawer
Test and polish the DESIGN.md Library filter/sort feature: sort dropdown
(Recent, Oldest, A-Z, Z-A, Most Tokens, Fewest Tokens), filter drawer
(category, status, reset), active file always pinned first. Verify drawer
opens without veil, grid reflows correctly, sort dropdown and drawer stay
synced, reset clears all filters. Test at mobile, tablet, desktop.

Self-check:
  [ ] Sort dropdown has all 6 options and they reorder correctly
  [ ] Filter drawer syncs with sort state
  [ ] Active file stays pinned first after any sort/filter
  [ ] Works at mobile, tablet, desktop breakpoints

=========================================================================
SECTION SELF-CHECK (run after 9a.5)
=========================================================================
  [ ] npx tsc --noEmit                               → no type errors
  [ ] npx vitest run                                 → all green
  [ ] grep -r 'setTimeout' apps/web/src/             → zero hits
  [ ] grep -ri "voice studio" apps/web/src/          → zero hits
  [ ] Manual smoke test passed on every Core + Advanced feature
  [ ] Export / Clear / Import round-trip verified
  [ ] All 5 tasks committed with conventional messages

=========================================================================
RULES (non-negotiable)
=========================================================================
1. Plan first. Do not mutate files until I reply "approved".
2. After each task, run its self-check and report pass/fail BEFORE starting
   the next task.
3. Only modify files inside apps/web/. Flag any needed core changes.
4. Commit after each task with conventional messages.
5. Fix any failing self-check before moving on.
6. Read AGENTS.md and CLAUDE.md in this worktree first. Dev server port 3333.

Merge order matters

The dependency chain dictates the sequence. Core has no dependencies, so it merges first and can't break anything downstream. MCP + CLI depend on core. Web depends on core (and sometimes MCP types). Always merge in this order:

Step	Branch	Why
1	`agent/core-engine`	No upstream deps. Rebuild core `dist/` after merge.
2	`agent/mcp-cli`	Imports from core `dist/`. Resolve `package-lock.json` if needed.
3	`agent/web-app`	Imports from core and may reference MCP types.
4	—	Full `npx turbo build && npx turbo test` from main.

🟠 sw-COORD — full merge-back sequence

# Step 1: Merge core (no dependencies)
cd /Users/dilshaus/dev/stitchwand
git merge agent/core-engine
npx turbo build --filter=@stitchwand/core
npx turbo test  --filter=@stitchwand/core

# Step 2: Merge MCP + CLI
git merge agent/mcp-cli
npm install   # resolve any package-lock conflict
npx turbo build --filter=@stitchwand/mcp-server --filter=@stitchwand/cli
npx turbo test  --filter=@stitchwand/mcp-server --filter=@stitchwand/cli

# Step 3: Merge web
git merge agent/web-app
npx turbo build
npx turbo test

# Step 4: Full verification
npx turbo build && npx turbo test

# Step 5: Cleanup (only after a successful full build + test)
git worktree remove ../stitchwand-agent-core
git worktree remove ../stitchwand-agent-mcpcli
git worktree remove ../stitchwand-agent-web
git branch -d agent/core-engine agent/mcp-cli agent/web-app

The most common merge conflict is package-lock.json. Accept either side, then run npm install to regenerate it correctly. Do not hand-edit the lockfile.

QA checklist (post-merge, pre-freeze)

QA runs from main after all three merges land. Two parts: automated (tests + build) and manual (click through every P1 fix).

Check	How to verify	Pass criteria
Full test suite	`npx turbo build && npx turbo test`	443+ tests, 0 failures
Type safety	`npx tsc --noEmit` in each package	No errors
No setTimeout mocks	`grep -r 'setTimeout' apps/web/src/app/(app)`	Zero hits
Copy buttons (P1-001)	Open `/design-md`, click Copy on every output panel	Clipboard contains correct content
Preview rendering (P1-002)	Paste real DESIGN.md, check Preview tab	Tables, sections, lists render correctly
Prompt refs (P1-003)	Generate a Starter Kit, read the Stitch Prompt output	Contains "MUST USE attached DESIGN.md"
Extraction accuracy (P1-004)	Convert 3 real design systems, spot-check 10 values	All values match official docs
Preview refresh (P1-005)	Replace DESIGN.md content in editor	Preview updates immediately
localStorage persistence	Refresh each Core + Advanced page	Every persisted key round-trips

Frequently asked questions

Do I really need three terminal windows? Can't one agent do it all?›

A single Claude Code session works on one thing at a time — one directory, one context window. With four packages and 30+ pages, that becomes a bottleneck. Three parallel agents let Core, MCP+CLI, and Web land changes concurrently. If you only have one task to do, sure, run a single agent. For an entire day of launch plan work, three is dramatically faster and keeps each context focused.

Is a "terminal window per prompt" what the launch plan asks for?›

No. That was a reasonable guess from the way the prompts are written (each says "Run in web agent worktree"), but you only need one terminal window per agent. Inside the 🟣 sw-WEB window you paste day-6 task 1, let Claude finish, paste task 2, and so on. Or paste the combined multi-step prompt and let Claude work through all 6 with a single approval.

Why require plan mode and an "approved" handshake?›

Combined prompts do a lot. Plan mode gives you one review point before Claude starts writing files, which is much cheaper to course-correct than stopping mid-implementation. The "approved" keyword makes it unambiguous — Claude won't proceed on a hedge like "that looks fine, but..." You can also use it to say "approved except for task 7.5, skip that one" in the same message.

What happens if the core agent adds a new export that the web agent needs mid-sprint?›

Cherry-pick the specific core commit into the web worktree and rebuild core locally: cd ../stitchwand-agent-web && git cherry-pick <commit> && npx turbo build --filter=@stitchwand/core. Don't merge the whole core branch early — that defeats the isolation.

How do I know which agent is behind?›

From 🟠 sw-COORD run: git diff --stat main..agent/core-engine, git diff --stat main..agent/mcp-cli, git diff --stat main..agent/web-app. Whichever branch has the fewest files changed is the agent you need to check on. The Monitoring Progress section in agents.html has a watch one-liner that updates every five seconds.

The combined prompt is huge. Will Claude actually read all of it?›

Yes. Plan mode is specifically designed for long instructions — Claude will read the whole section, explore the referenced files, and present a plan. If you're worried, ask for the plan to explicitly number each task (1 through N) and list the files it read for each. That gives you a concrete signal that nothing was skimmed.

What if a self-check fails in the middle of a combined run?›

The rules say Claude must stop and fix before moving on. In practice, Claude will either fix it automatically or report the failure and ask. If it silently moves on, the final section self-check will catch it and you can prompt: "Task 6.4 self-check failed on the diff history. Fix it before we move on." The rules block is intentionally restated at the bottom so Claude keeps seeing it in its working context.

Can I use this same pattern for Phase 2 and Phase 3?›

Yes — the worktree branches just change names (agent/p2-core, agent/p3-web, etc.). The plan-first contract and self-check structure transfer directly. Phase 3 adds a fourth agent for infrastructure (GitHub Actions, Stripe webhooks, Sentry); you'd add a 🔴 sw-INFRA terminal window following the same pattern.

Where should I read before running these prompts?›

1) CLAUDE.md (project context, read automatically), 2) the per-worktree AGENTS.md (scope + rules), 3) agents.html (deep theory), 4) AGENTS-SETUP-REPORT.md (current worktree state), 5) launch-plan.html (task context). The bootstrap prompt in Setup & Terminals reminds Claude to do this at the start of every session.