Stage: planning

Purpose: Understand the current app and codebase, discuss redesign scope and direction with the user, and produce an approved re-design plan. Output artifact: write to the absolute path provided in your prompt Valid results this stage writes: pending (plan drafted, awaiting user approval), approved (user has explicitly confirmed)

This is an interruptible stage — you may pause naturally for user Q&A at any point.

Step 1 — Read state and write initial artifact

Read epoch from state.md. Immediately write the output artifact at the path shown in your I/O context with result: pending so the stop hook knows the stage is in progress:

---
epoch: <epoch>
result: pending
---
# Re-design Plan: <Topic>
(in progress)

Step 2 — Explore the app via browser

Use browser tools (Playwright or Chrome DevTools MCP) to navigate the running app:

• Visit every distinct page / route
• Screenshot or snapshot each page
• Note the current visual style: color palette, typography, layout patterns, spacing, component library in use
• Note interaction patterns: navigation, modals, forms, CTAs
• Identify pages or sections that feel visually weakest or most inconsistent

Step 3 — Read the codebase

• Identify the frontend tech stack (framework, component library, styling system)
• Understand how styles are applied (CSS modules, Tailwind, styled-components, etc.)
• Note any existing design tokens or theme files
• Understand the project's file structure for UI components

Step 4 — Discuss with the user

Ask the user targeted questions to scope the redesign. One question at a time, pause for answers. Cover:

1. Which pages / sections are in scope for this redesign?
2. What is the desired mood or identity? (e.g. "minimal and professional", "warm and approachable", "bold and modern")
3. Are there reference sites or brands to draw inspiration from?
4. Any hard constraints? (must keep existing component library, brand colors, accessibility requirements, etc.)
5. What is the biggest pain point in the current design?

Stop asking once you have enough to write a concrete plan.

Step 5 — Write the re-design plan

Update the output artifact with the full plan:

---
epoch: <epoch>
result: pending
---
# Re-design Plan: <Topic>

## Current State Assessment
<Summary of pages reviewed, current visual style, main weaknesses>

## Redesign Scope
<List of pages / components in scope>

## Design Direction
<Mood, identity, reference inspirations, key visual decisions>

## Design System Changes
<Color palette, typography scale, spacing system, component updates>

## Page-by-Page Changes
### <Page 1>
- <specific change>
### <Page 2>
- <specific change>

## Constraints & Out of Scope
<Hard constraints the executor must respect; what is NOT being changed>

## Acceptance Criteria
- [ ] Design feels like a coherent whole (consistent colors, type, spacing)
- [ ] No unmodified stock component defaults or obvious AI-generated patterns
- [ ] Typography hierarchy and spacing are consistent across all in-scope pages
- [ ] Color contrast ratios meet WCAG AA minimum
- [ ] Primary actions and navigation remain clear and usable
- [ ] All in-scope pages match the agreed design direction

Step 6 — Get user approval

"Re-design plan saved. Please review and confirm to start execution, or request changes."

If the user requests changes, update the plan body — keep result: pending.

Step 7 — Finalize

Once the user explicitly approves, overwrite the output artifact changing result: pending → result: approved.

Do NOT call update-status.sh — the main loop handles state transitions.