diff --git a/.claude/commands/define-design.md b/.claude/commands/define-design.md index f031885..f828f05 100644 --- a/.claude/commands/define-design.md +++ b/.claude/commands/define-design.md @@ -23,11 +23,9 @@ claude ↓ /define-design ← you are here ↓ -/generate-app web | flutter | winui3 +/plan-milestones (milestone 01 = app shell, generated from this design) ↓ -/plan-milestones - ↓ -/add-feature +/execute-milestones phase1-milestones.md (or /add-feature per feature) ``` ## Pre-Run Check @@ -202,7 +200,7 @@ Design documents created: Next steps: - Review docs/design/ (especially ui-blueprint.json) - Refine the design with /update-design (or re-run /define-design) until approved — do this BEFORE generating code -- Run /generate-app web | flutter | winui3 to generate the initial app +- Run /plan-milestones — milestone 01 (App Shell Generation) scaffolds the app from this design - Use /update-design when a feature changes the UI - Use /add-feature to add features (it respects the design spec) " diff --git a/.claude/commands/execute-milestones.md b/.claude/commands/execute-milestones.md index a59dd57..d5d1e60 100644 --- a/.claude/commands/execute-milestones.md +++ b/.claude/commands/execute-milestones.md @@ -29,8 +29,6 @@ claude ↓ /define-design ↓ -/generate-app web | flutter | winui3 - ↓ /plan-milestones ↓ /execute-milestones phase1-milestones.md ← you are here (one phase file per run) @@ -58,6 +56,7 @@ claude 1. Load the **milestone-execution skill** (`Skill('milestone-execution')`) for the per-milestone steering structure, task-division rules, and the gate criteria between milestones. 2. The **steering skill** and **development-guidelines skill** apply during implementation, exactly as in `/add-feature`. +3. **If the milestone is the App Shell milestone (milestone 01)**, additionally load the **platform-ui-generation skill** (`Skill('platform-ui-generation')`) for the design→code mapping rules of the target platform recorded in the milestone. Its E2E verification is the `e2e/app-shell.spec.ts` smoke spec (shell renders, every blueprint route navigates). ### Step 2: Milestone Loop diff --git a/.claude/commands/generate-app.md b/.claude/commands/generate-app.md deleted file mode 100644 index 43e74fc..0000000 --- a/.claude/commands/generate-app.md +++ /dev/null @@ -1,154 +0,0 @@ ---- -description: Generate the initial application for a target platform (web | flutter | winui3) from the design spec ---- - -# Generate App (Platform App Generation Phase) - -This command generates the **initial application** for the selected target platform, using the design files in `docs/design/` as the source of truth. It creates the app shell, theme, routes, screens, and reusable components — **not** feature logic. Features are added later with `/add-feature`. - -**Target platform**: `$ARGUMENTS` — must be one of `web`, `flutter`, `winui3`. - -## How to Run - -```bash -claude -> /generate-app web -> /generate-app flutter -> /generate-app winui3 -``` - -## Position in the Workflow - -``` -/setup-project - ↓ -/define-design - ↓ -/generate-app web | flutter | winui3 ← you are here - ↓ -/plan-milestones - ↓ -/add-feature -``` - -## Pre-Run Check - -1. Validate the target: - - If `$ARGUMENTS` is not one of `web`, `flutter`, `winui3`, stop and ask the user to provide a valid target. -2. Confirm the design files exist. If any of these are missing, stop and tell the user to run `/define-design` first: - - `docs/design/design-brief.md` - - `docs/design/design-tokens.json` - - `docs/design/ui-blueprint.json` - - `docs/design/platform-mapping.md` -3. **Important**: Do **not** generate any platform-specific implementation before this command is executed. This command is the only place initial app scaffolding is created. -4. This command generates from the design **as-is**. Refine the design first (re-run `/define-design` or use `/update-design `) if anything needs to change — it is far easier to refine before code is generated than after. - -## Procedure - -### Step 0: Read the Inputs - -Read all of the following: - -- `docs/product-requirements.md` -- `docs/functional-design.md` -- `docs/architecture.md` -- `docs/repository-structure.md` -- `docs/development-guidelines.md` -- `docs/design/design-brief.md` -- `docs/design/design-tokens.json` -- `docs/design/ui-blueprint.json` -- `docs/design/platform-mapping.md` - -### Step 1: Load the Platform Generation Skill - -Load the **platform-ui-generation skill** (`Skill('platform-ui-generation')`) for the mapping rules from design files to the selected platform's code. - -### Step 2: Generate the App Shell - -Generate the initial application for the selected target. In all cases: - -- Respect the design tokens and the UI blueprint exactly. -- Create reusable UI components (do not inline everything into screens). -- Create the initial screen structure (one screen per entry in `ui-blueprint.json`). -- Create the initial route/navigation structure. -- Use semantic, accessible markup/semantics where the platform supports it. -- **Do not implement features that are not described in the current project documents.** Only the app shell, theme, routes, screens, and shared components. - -### Step 3: Platform-Specific Requirements - -Apply the requirements for the selected target: - -#### `/generate-app web` -- Generate a Web app using the technology defined in `docs/architecture.md`. -- If no framework is specified, ask the user or choose a simple default suitable for the repository. -- Convert `design-tokens.json` into CSS variables, a Tailwind config, or an equivalent styling system. -- Convert `ui-blueprint.json` into pages, layouts, and components. -- Use semantic HTML where possible. -- Respect responsive layout requirements (use breakpoints from the tokens). - -#### `/generate-app flutter` -- Generate a Flutter app. -- Convert `design-tokens.json` into: - - `ThemeData` - - `ColorScheme` - - spacing constants - - radius constants - - text styles -- Convert `ui-blueprint.json` into: - - routes - - screens - - reusable widgets -- Keep clean separation between: `screens`, `widgets`, `theme`, `models`, `services`. - -#### `/generate-app winui3` -- Generate a WinUI 3 application structure. -- Convert `design-tokens.json` into: - - `ResourceDictionary` - - theme resources - - styles -- Convert `ui-blueprint.json` into: - - XAML pages - - `UserControl`s - - navigation structure -- Use C# and XAML. -- Keep UI logic separated from business logic where possible. - -### Step 4: Update Repository Structure Document - -If new directories/files were created, update `docs/repository-structure.md` so it reflects the generated layout. - -### Step 5: Verify (including Playwright E2E) - -- If the target is `web`: - - Run `npm test`, `npm run lint`, `npm run typecheck` (where present) and fix any errors caused by the generated code. - - Set up Playwright following the **e2e-testing skill** (`Skill('e2e-testing')`) if it is not set up yet, and create the app-shell smoke spec `e2e/app-shell.spec.ts` (shell renders, every blueprint route navigates, primary navigation works). - - Run `npm run test:e2e` and fix any failures caused by the generated code. -- For `flutter` / `winui3`, run the platform's available static checks and UI/integration tests if the toolchain is present (`integration_test` for Flutter, the platform's UI automation for WinUI 3); otherwise note what should be checked manually. - -## Completion Criteria - -- The initial app shell exists for the selected target. -- Design tokens are converted into the platform's styling system. -- The UI blueprint is converted into screens, routes, and reusable components. -- No feature logic beyond what the project documents describe has been implemented. -- `docs/repository-structure.md` has been updated if the layout changed. - -Completion message: -``` -"App generation is complete for target: [target] - -Generated: -✅ App shell + entry point -✅ Theme / styling system (from design-tokens.json) -✅ Routes / navigation (from ui-blueprint.json) -✅ Screens (one per blueprint screen) -✅ Reusable components -✅ Playwright E2E smoke spec (e2e/app-shell.spec.ts, web target) - -Next steps: -- Run the app and verify the shell renders -- Run /plan-milestones to break the product into milestones with a feature list each -- Use /add-feature to implement features (they will respect the design spec) -- Use /update-design when a feature changes the UI -" -``` diff --git a/.claude/commands/plan-milestones.md b/.claude/commands/plan-milestones.md index 3c91647..53df0ed 100644 --- a/.claude/commands/plan-milestones.md +++ b/.claude/commands/plan-milestones.md @@ -23,11 +23,9 @@ claude ↓ /define-design ↓ -/generate-app web | flutter | winui3 - ↓ /plan-milestones ← you are here ↓ -/execute-milestones phase1-milestones.md (one phase file at a time) +/execute-milestones phase1-milestones.md (one phase file at a time; milestone 01 generates the app shell) ``` ## Pre-Run Check @@ -36,7 +34,7 @@ claude - `docs/product-requirements.md` - `docs/functional-design.md` - `docs/architecture.md` -2. Check whether the design files (`docs/design/ui-blueprint.json` etc.) exist. If they do not, warn the user that milestones will be planned without a design spec and suggest running `/define-design` first. Continue only if the user accepts. +2. Check whether the design files (`docs/design/ui-blueprint.json` etc.) exist. If they do not, warn the user that milestones will be planned without a design spec — and that milestone 01 (App Shell Generation) is scaffolded from that spec — and suggest running `/define-design` first. Continue only if the user accepts. 3. Create the milestones directory if it does not exist: ```bash mkdir -p docs/milestones @@ -59,6 +57,7 @@ Read all of the following: If `$ARGUMENTS` does not already answer these, ask the user about the following. If the user does not provide detailed preferences, **propose a sensible default** derived from the PRD priorities and confirm it before proceeding. +- **Target platform** — `web`, `flutter`, or `winui3` (propose the default from `docs/architecture.md` and `docs/design/platform-mapping.md`); milestone 01 generates the app shell for this platform - **Number of phases** (default: 2–3) and **milestones per phase** (default: 1–3) - **MVP definition** — what is the smallest product worth releasing? (phase 1 must deliver it) - **Priorities** — features that must come first or last @@ -83,9 +82,10 @@ Size each feature so it can be implemented with **one `/add-feature` run**. Spli ### Step 4: Group Features into Milestones, and Milestones into Phases - Number milestones globally and consecutively across all phases (`01`, `02`, …). -- **Milestone 1 is the MVP core**: the smallest set of features that forms a coherent, end-to-end usable product. +- **Milestone 01 is always "App Shell Generation"** (there is no separate generate-app command — the shell is built as the first milestone). Following the **platform-ui-generation skill**, it scaffolds the app for the target platform from `docs/design/`: theme from `design-tokens.json`, routes/screens (one per blueprint screen) and reusable components from `ui-blueprint.json`, **no feature logic**, plus Playwright setup with the `e2e/app-shell.spec.ts` smoke spec. Its features are pre-defined in the milestone-planning skill. +- **Milestone 02 is the MVP core**: the smallest set of features that forms a coherent, end-to-end usable product on top of the shell. - Later milestones build on earlier ones, ordered by priority and dependency (a feature never lands before something it depends on). -- **Phase 1 delivers the MVP**: it contains milestone 1 (plus any milestone needed to make the MVP releasable). Later phases group the remaining milestones by theme and priority — each phase should be a meaningful release on its own. +- **Phase 1 delivers the MVP**: it contains milestones 01 (app shell) and 02 (plus any milestone needed to make the MVP releasable). Later phases group the remaining milestones by theme and priority — each phase should be a meaningful release on its own. - Every feature belongs to **exactly one** milestone, and every milestone to **exactly one** phase. Explicitly park out-of-scope items in a final "Later / Icebox" section of the roadmap. ### Step 5: Create the Roadmap Overview @@ -115,6 +115,7 @@ For each phase, create `docs/milestones/phase[N]-milestones.md` (e.g. `phase1-mi Re-read all generated files and confirm: +- Milestone 01 is the App Shell milestone (target platform recorded, features per the milestone-planning skill). - Every P0/P1 requirement in the PRD is covered by a milestone (or explicitly parked in the icebox). - Every feature appears in exactly one milestone, and every milestone in exactly one phase file. - Milestone numbering is global and consecutive across the phase files. @@ -136,13 +137,13 @@ Completion message: Milestone documents created: ✅ docs/milestones/roadmap.md (overview + status) -✅ docs/milestones/phase1-milestones.md (MVP phase: milestones 01–NN) +✅ docs/milestones/phase1-milestones.md (MVP phase: milestone 01 = app shell, milestones 02–NN) ✅ docs/milestones/phase2-milestones.md (milestones NN–NN) Next steps: - Review docs/milestones/ and adjust priorities if needed - Run /execute-milestones phase1-milestones.md to implement phase 1 (a separate steering directory is created per milestone) -- Or go feature by feature: run /add-feature [first feature of milestone 1] +- Or go feature by feature: run /add-feature [first feature of milestone 01 — the app shell] - Either way, each feature is marked complete in its phase file as it finishes " ``` diff --git a/.claude/commands/update-design.md b/.claude/commands/update-design.md index c9b2d43..e7d3052 100644 --- a/.claude/commands/update-design.md +++ b/.claude/commands/update-design.md @@ -1,10 +1,10 @@ --- -description: Refine the design before /generate-app, or update it when a feature changes the UI (blueprint first, then tokens, brief, and SVGs) +description: Refine the design before the app shell is generated (milestone 01), or update it when a feature changes the UI (blueprint first, then tokens, brief, and SVGs) --- # Update Design -This command updates the design specification. It is used in two situations: (1) to refine the UI/UX **before** running `/generate-app` (e.g. adjusting screens, tokens, or layout after reviewing the initial design), and (2) to update the design when a feature changes the UI. It updates the structured design files **only** — it does **not** implement application code unless explicitly requested. +This command updates the design specification. It is used in two situations: (1) to refine the UI/UX **before** the app shell is generated by milestone 01 (e.g. adjusting screens, tokens, or layout after reviewing the initial design), and (2) to update the design when a feature changes the UI. It updates the structured design files **only** — it does **not** implement application code unless explicitly requested. **Change description**: `$ARGUMENTS` (e.g. `/update-design add a profile screen with avatar and edit form`) diff --git a/.claude/skills/e2e-testing/SKILL.md b/.claude/skills/e2e-testing/SKILL.md index 31ea271..f425dee 100644 --- a/.claude/skills/e2e-testing/SKILL.md +++ b/.claude/skills/e2e-testing/SKILL.md @@ -92,7 +92,7 @@ test.describe('Edit user profile', () => { ## Writing the App-Shell Smoke Spec -Created by `/generate-app` (web target). `e2e/app-shell.spec.ts` must verify: +Created by the App Shell milestone (milestone 01, web target). `e2e/app-shell.spec.ts` must verify: - The app starts and the entry screen renders. - Every route in `ui-blueprint.json` is reachable and renders its screen title. @@ -109,7 +109,7 @@ npm run test:e2e ## Verification Checklist -Used by `/add-feature` Step 7, `/execute-milestones` Step 2.6, and `/generate-app` Step 5: +Used by `/add-feature` Step 7 and `/execute-milestones` Step 2.6 (including the App Shell milestone): - [ ] Playwright is set up (`test:e2e` script exists) — set it up via this skill if missing. - [ ] Every implemented feature has `e2e/[feature].spec.ts` covering its acceptance criteria. diff --git a/.claude/skills/milestone-planning/SKILL.md b/.claude/skills/milestone-planning/SKILL.md index 592bb7b..88deafd 100644 --- a/.claude/skills/milestone-planning/SKILL.md +++ b/.claude/skills/milestone-planning/SKILL.md @@ -19,13 +19,14 @@ Roadmap (roadmap.md) ## Core Principles -1. **MVP first**: Phase 1 delivers the MVP; milestone 1 is its core — the smallest coherent, end-to-end usable product. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use. -2. **Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone". -3. **One feature = one `/add-feature` run**: If a feature needs more than one steering directory to implement, split it. If it is a one-line change, merge it into a neighbor. -4. **One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release. -5. **Dependency order**: A feature never lands in an earlier milestone than something it depends on, and a milestone never lands in an earlier phase than its dependencies. -6. **Exactly-once assignment**: Every feature belongs to exactly one milestone; every milestone to exactly one phase file. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears. -7. **Living documents**: Phase files track status. `/add-feature` and `/execute-milestones` check off features (`[ ]` → `[x]`) as they complete, and milestone/phase statuses are updated in both the phase file and `roadmap.md`. +1. **App shell first**: Milestone 01 is always **App Shell Generation** — there is no separate generate-app command; the initial app is built as the first milestone (see "Milestone 01" below). +2. **MVP first**: Phase 1 delivers the MVP; milestone 02 is its core — the smallest coherent, end-to-end usable product on top of the shell. Not a layer (e.g. "all the models"), but a vertical slice a user could actually use. +3. **Vertical slices**: Each feature cuts through UI → logic → data. Avoid horizontal milestones like "backend milestone" / "frontend milestone". +4. **One feature = one `/add-feature` run**: If a feature needs more than one steering directory to implement, split it. If it is a one-line change, merge it into a neighbor. +5. **One phase file = one `/execute-milestones` run**: A phase groups 1–3 milestones that together form a meaningful release. +6. **Dependency order**: A feature never lands in an earlier milestone than something it depends on, and a milestone never lands in an earlier phase than its dependencies. +7. **Exactly-once assignment**: Every feature belongs to exactly one milestone; every milestone to exactly one phase file. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears. +8. **Living documents**: Phase files track status. `/add-feature` and `/execute-milestones` check off features (`[ ]` → `[x]`) as they complete, and milestone/phase statuses are updated in both the phase file and `roadmap.md`. ## Inputs @@ -51,6 +52,20 @@ File naming: `phase[N]-milestones.md` with `N` starting at 1 (e.g. `phase1-miles Use the structure in `template.md` for each phase file and for the roadmap. +## Milestone 01: App Shell Generation (always the first milestone) + +The initial app is not created by a separate command — it is **milestone 01**, the first milestone of phase 1, executed like any other milestone (via `/execute-milestones phase1-milestones.md` or feature by feature with `/add-feature`). Implementation follows the **platform-ui-generation skill** for the design→code mapping. + +Record the **target platform** (`web` | `flutter` | `winui3`) in the milestone's Scope. Its features are: + +- [ ] Generate the app shell and theme from the design tokens — entry point, layout shell, and the platform's styling system converted from `design-tokens.json` +- [ ] Generate routes, screens, and reusable components from the UI blueprint — one screen per `ui-blueprint.json` entry, navigation wired, shared components extracted, **no feature logic** +- [ ] Set up Playwright and the app-shell smoke spec — `playwright.config.ts`, `test:e2e` script, and `e2e/app-shell.spec.ts` verifying the shell renders and every blueprint route navigates (see the e2e-testing skill; platform equivalents for flutter/winui3) + +Definition of done (in addition to the standard one): the app runs, every blueprint screen is reachable, tokens are the only styling source (no hard-coded values), and no feature logic exists beyond what the documents describe. + +**Dependency**: milestone 01 requires the design spec (`docs/design/`). Every later milestone depends on milestone 01. + ## How to Slice Features A well-sized feature: @@ -67,10 +82,11 @@ Too small (merge it): "Change button color" → fold into the feature that owns ## How to Group Milestones and Phases 1. Tag every feature with its PRD priority and its dependencies. -2. Milestone 1 (MVP core): the minimal dependency-closed set of P0 features that forms a usable product walk-through (a user can start, do the core job, and finish). -3. Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful step on its own ("after milestone N, the user can additionally …"). Prefer 3–8 features per milestone. -4. **Phase 1** contains milestone 1 plus any milestone required to make the MVP releasable. **Following phases** group the remaining milestones into meaningful releases — prefer 2–3 phases with 1–3 milestones each. -5. A phase should be independently valuable: after `/execute-milestones phase[N]-milestones.md` finishes, the product is in a releasable state. +2. Milestone 01 (App Shell): always first — see "Milestone 01" above. +3. Milestone 02 (MVP core): the minimal dependency-closed set of P0 features that forms a usable product walk-through (a user can start, do the core job, and finish). +4. Following milestones: group remaining features by theme and priority, keeping each milestone a meaningful step on its own ("after milestone N, the user can additionally …"). Prefer 3–8 features per milestone. +5. **Phase 1** contains milestones 01 and 02 plus any milestone required to make the MVP releasable. **Following phases** group the remaining milestones into meaningful releases — prefer 2–3 phases with 1–3 milestones each. +6. A phase should be independently valuable: after `/execute-milestones phase[N]-milestones.md` finishes, the product is in a releasable state. ## Status Tracking Rules @@ -84,6 +100,7 @@ Too small (merge it): "Change button color" → fold into the feature that owns Before finishing: +- [ ] Milestone 01 is the App Shell milestone, with its target platform recorded and the three shell features listed. - [ ] Every P0/P1 PRD requirement maps to a feature in some milestone (or is explicitly in the icebox). - [ ] Every feature appears in exactly one milestone; every milestone in exactly one phase file. - [ ] Milestone numbering is global and consecutive across phase files. diff --git a/.claude/skills/milestone-planning/template.md b/.claude/skills/milestone-planning/template.md index cb37ced..d2f8543 100644 --- a/.claude/skills/milestone-planning/template.md +++ b/.claude/skills/milestone-planning/template.md @@ -2,6 +2,8 @@ Use this structure for each `docs/milestones/phase[N]-milestones.md`. A phase file contains one or more milestones; milestone numbers are global across all phase files. +**Milestone 01 is always "App Shell Generation"** (first milestone of phase 1): its In Scope records the target platform (`web` | `flutter` | `winui3`), its features are the three shell features defined in SKILL.md (theme from tokens, screens/routes from the blueprint, Playwright + app-shell smoke spec), and its Definition of Done additionally requires that every blueprint screen is reachable and no feature logic was implemented. + ```markdown # Phase [N]: [Name] diff --git a/.claude/skills/platform-ui-generation/SKILL.md b/.claude/skills/platform-ui-generation/SKILL.md index 3aab12e..c505406 100644 --- a/.claude/skills/platform-ui-generation/SKILL.md +++ b/.claude/skills/platform-ui-generation/SKILL.md @@ -1,19 +1,19 @@ --- name: platform-ui-generation -description: Guide for converting the design files (design-tokens.json + ui-blueprint.json) into application code for Web, Flutter, or WinUI 3. Use when running /generate-app or implementing UI against the design spec. +description: Guide for converting the design files (design-tokens.json + ui-blueprint.json) into application code for Web, Flutter, or WinUI 3. Use when executing the App Shell milestone (milestone 01) or implementing UI against the design spec. allowed-tools: Read, Write, Edit, Bash --- # Platform UI Generation Skill -This skill explains how to convert the design files under `docs/design/` into application code. It is used by `/generate-app` and by `/add-feature` when implementing UI. +This skill explains how to convert the design files under `docs/design/` into application code. It is used by the **App Shell milestone** (milestone 01 — planned by `/plan-milestones`, executed by `/execute-milestones` or `/add-feature`) and by `/add-feature` when implementing UI. ## Core Principles 1. **Source of truth**: `docs/design/ui-blueprint.json` defines structure; `docs/design/design-tokens.json` defines values. 2. **No hard-coded values**: every color, size, spacing, radius, and duration in generated code must come from a token. 3. **Reusable components first**: extract reusable components; do not inline the entire tree into screens. -4. **No feature logic during scaffolding**: `/generate-app` creates the shell, theme, routes, screens, and shared components only. Features come from `/add-feature`. +4. **No feature logic during scaffolding**: the App Shell milestone creates the shell, theme, routes, screens, and shared components only. Features come from the later milestones. 5. **Respect the platform mapping**: `docs/design/platform-mapping.md` documents how each artifact maps to each platform. ## Inputs @@ -85,7 +85,7 @@ Each generated reusable component must: - Reference tokens for all visual values — no hard-coded literals. - Stay presentational: no feature/business logic. -## Scaffolding Scope (what `/generate-app` creates) +## Scaffolding Scope (what the App Shell milestone creates) - App entry point and shell - Theme/styling system from tokens diff --git a/CLAUDE.md b/CLAUDE.md index db8ad66..3857533 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -85,7 +85,7 @@ Define "what to build" and "how to build it" for the entire application: - **ui-blueprint.json** - UI structure (source of truth for UI generation) - **platform-mapping.md** - How the design maps to Web / Flutter / WinUI 3 - **screens/\*.svg** - Visual wireframes (references only) -- Created by `/define-design`, updated by `/update-design`, consumed by `/generate-app` and `/add-feature` +- Created by `/define-design`, updated by `/update-design`, consumed by the App Shell milestone (milestone 01) and `/add-feature` #### Milestone Documents (`docs/milestones/`) - **roadmap.md** - Overview: phase/milestone table, ordering rationale, current phase and milestone, icebox @@ -103,7 +103,7 @@ Define "what to do this time" for a specific development task: ### Claude Code Configuration (`.claude/`) - `.claude/agents/` - Subagent definitions (doc-reviewer, implementation-validator) -- `.claude/commands/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, execute-milestones, add-feature, review-docs) +- `.claude/commands/` - Slash commands (setup-project, define-design, update-design, plan-milestones, execute-milestones, add-feature, review-docs) - `.claude/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, ui-design, design-tokens, platform-ui-generation, milestone-planning, milestone-execution, e2e-testing, steering) ## Development Process @@ -114,10 +114,9 @@ Define "what to do this time" for a specific development task: 2. Create persistent documents with `/setup-project` (automatically creating six) 3. Define the UI/UX design with `/define-design` (creates `docs/design/`) 4. Review and refine the UI/UX with `/update-design` (or re-run `/define-design`) until approved — before generating code -5. Generate the initial app with `/generate-app web | flutter | winui3` -6. Plan milestones with `/plan-milestones` (creates `docs/milestones/` with one `phase[N]-milestones.md` per phase) -7. Implement, either way: - - `/execute-milestones phase1-milestones.md` — execute one phase file: its milestones one by one autonomously (one steering directory per milestone); repeat with the next phase file, or +5. Plan milestones with `/plan-milestones` (creates `docs/milestones/` with one `phase[N]-milestones.md` per phase; milestone 01 is always App Shell Generation from the design spec) +6. Implement, either way: + - `/execute-milestones phase1-milestones.md` — execute one phase file: its milestones one by one autonomously (one steering directory per milestone; milestone 01 generates the initial app); repeat with the next phase file, or - `/add-feature [feature]` — one feature at a time, milestone by milestone ### Day-to-Day Usage @@ -135,7 +134,6 @@ Define "what to do this time" for a specific development task: # Design phase > /define-design -> /generate-app web > /update-design add a profile screen # Milestone planning and execution diff --git a/README.md b/README.md index 6c85eda..2d883c9 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,7 @@ https://github.com/GenerativeAgents/claude-code-book How a project goes from idea to working code with this boilerplate: ``` -Idea → /setup-project → /define-design → refine design → /generate-app → /plan-milestones → /execute-milestones (phase by phase) +Idea → /setup-project → /define-design → refine design → /plan-milestones → /execute-milestones (phase by phase; milestone 01 generates the app) ``` ### Step 1 — Write down your idea @@ -41,18 +41,17 @@ This is the key design-decision gate: iterate on the design while it is still ch - Re-run `/define-design` — change the overall direction - Repeat until you approve the design (especially `ui-blueprint.json`) -### Step 5 — Generate the initial app: `/generate-app web | flutter | winui3` -Scaffolds the app shell from the approved design: theme (from tokens), routes, screens, and -reusable components. No feature logic yet. - -### Step 6 — Plan milestones: `/plan-milestones` +### Step 5 — Plan milestones: `/plan-milestones` Breaks the product into **phases** and milestones, and generates `docs/milestones/`: a `roadmap.md` overview plus **one file per phase** (`phase1-milestones.md`, `phase2-milestones.md`, …). Each phase file lists its milestones and **the features they contain** — each feature sized for exactly one `/add-feature` run, with acceptance criteria and a -ready-to-run command. Phase 1 delivers the MVP; later phases build on it by priority and dependency. +ready-to-run command. **Milestone 01 is always "App Shell Generation"**: it scaffolds the initial +app from the approved design (theme from tokens, one screen per blueprint entry, routes, reusable +components — no feature logic) plus the Playwright smoke spec; there is no separate generate-app +step. Phase 1 delivers the MVP; later phases build on it by priority and dependency. -### Step 7 — Implement the milestones +### Step 6 — Implement the milestones Two ways to work through the plan: @@ -74,7 +73,7 @@ A fully autonomous loop, one feature per run. Each run: 5. Writes Playwright E2E tests for the feature's acceptance criteria, then runs `npm test`, `npm run lint`, `npm run typecheck`, and `npm run test:e2e` until green 6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its phase file -### Step 8 — Repeat and maintain +### Step 7 — Repeat and maintain - Remaining phases → `/execute-milestones `, or feature by feature with `/add-feature ` - UI changes → `/update-design ` first, then `/add-feature` - Re-planning → re-run `/plan-milestones` or edit `docs/milestones/` in conversation @@ -87,7 +86,7 @@ in sync with the code. ## E2E Testing (Playwright) Every verification step in this boilerplate includes end-to-end tests. The standard verification -sequence — used by `/add-feature`, `/execute-milestones`, and `/generate-app` — is: +sequence — used by `/add-feature` and `/execute-milestones` — is: ```bash npm test # unit tests @@ -103,7 +102,7 @@ How it works (defined in the `e2e-testing` skill): failure), and adds the `test:e2e` script. - **Tests are derived from acceptance criteria**: each feature gets `e2e/[feature].spec.ts` with one test per acceptance criterion, written before verification runs. -- **The app shell has a smoke spec**: `/generate-app` creates `e2e/app-shell.spec.ts`, which +- **The app shell has a smoke spec**: the App Shell milestone (milestone 01) creates `e2e/app-shell.spec.ts`, which checks that the shell renders and every route in `ui-blueprint.json` navigates. - **Blueprint-driven locators**: tests navigate by the blueprint's routes and use semantic locators (`getByRole`, `getByLabel`) — no CSS/XPath tied to implementation details, no fixed waits. @@ -150,8 +149,7 @@ claude > /setup-project > /define-design > /update-design [refinement] # repeat until the design is approved -> /generate-app web # or flutter | winui3 -> /plan-milestones +> /plan-milestones # milestone 01 = app shell generation > /execute-milestones phase1-milestones.md # one phase at a time, or: > /add-feature [feature name] # one feature at a time ``` @@ -165,8 +163,7 @@ See [Development Workflow (Step by Step)](#development-workflow-step-by-step) ab | `/setup-project` | Create the six persistent documents automatically | `/setup-project` | | `/define-design` | Create the UI/UX design spec under `docs/design/` | `/define-design` | | `/update-design` | Refine the design before generation, or update it when a feature changes the UI | `/update-design add a profile screen` | -| `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` | -| `/plan-milestones` | Plan phases and milestones; generates one `phase[N]-milestones.md` per phase | `/plan-milestones 2 phases, MVP first` | +| `/plan-milestones` | Plan phases and milestones; generates one `phase[N]-milestones.md` per phase (milestone 01 = App Shell Generation) | `/plan-milestones 2 phases, MVP first` | | `/execute-milestones` | Execute one phase file: its milestones one by one, with separate steering documents per milestone (file argument required) | `/execute-milestones phase1-milestones.md` | | `/add-feature` | Implement a feature end-to-end (autonomous) | `/add-feature User profile editing` | | `/review-docs` | Detailed document review via subagent | `/review-docs docs/architecture.md` | diff --git a/docs/design/README.md b/docs/design/README.md index 91c0b19..3adac9a 100644 --- a/docs/design/README.md +++ b/docs/design/README.md @@ -1,6 +1,6 @@ # Design Specification (`docs/design/`) -This directory holds the project's **UI/UX design specification**. It is created and maintained by the `/define-design` and `/update-design` commands and consumed by `/generate-app` and `/add-feature`. +This directory holds the project's **UI/UX design specification**. It is created and maintained by the `/define-design` and `/update-design` commands and consumed by the App Shell milestone (milestone 01) and `/add-feature`. ## Source of truth @@ -16,6 +16,7 @@ Generated UI must follow `design-tokens.json` — no hard-coded values. ``` docs/design/ +├── screen-inventory.md # Exhaustive screen checklist derived from the PRD (built first) ├── design-brief.md # UI/UX direction (human-readable, concrete) ├── design-tokens.json # Styling values (color, type, spacing, radius, …) ├── ui-blueprint.json # Source of truth: screens, components, routes, actions @@ -28,6 +29,9 @@ docs/design/ ## File purposes +### `screen-inventory.md` +The exhaustive checklist of every screen the requirements imply — built first, before any other design file. Derived from every PRD user story walked end-to-end, CRUD coverage per entity (list/detail/create/edit/delete, modals included), and supporting screens, ending with a story→screen traceability table. Every entry must exist in `ui-blueprint.json`. + ### `design-brief.md` Overall UI/UX direction: target users, design concept, visual mood, layout/navigation principles, accessibility, platform-specific notes, preferred styles, and styles to avoid. @@ -52,11 +56,11 @@ Low-fidelity wireframes, one per screen in `ui-blueprint.json`, named `