Compare commits
3 Commits
e2e-verifi
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
| 1649a71781 | |||
| a4f80e8c8c | |||
| 2a803a80b9 |
@ -24,11 +24,9 @@ opencode
|
||||
↓
|
||||
/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
|
||||
@ -62,7 +60,7 @@ Ask the user about the following. If the user does not provide detailed preferen
|
||||
|
||||
- **Target platform**: `web`, `flutter`, `winui3`, or `multi`
|
||||
- **Visual style** (e.g. friendly/modern/rounded/calm, dark or light, density)
|
||||
- **Main screens** the app must have
|
||||
- **Main screens** the app must have (treat the answer as additions and constraints — the complete screen list is derived from the PRD in Step 3, never limited to what the user names here)
|
||||
- **Navigation style** (e.g. tab bar, drawer, sidebar, stack)
|
||||
- **Branding preferences** (name, colors, tone)
|
||||
- **Accessibility requirements** (e.g. WCAG level, minimum contrast, large-touch targets)
|
||||
@ -74,7 +72,30 @@ Collect the answers in a single round; do not pause again until generation is co
|
||||
- Follow the **ui-design** skill (loaded automatically) to create `design-brief.md`, `ui-blueprint.json`, and the SVG wireframes.
|
||||
- Follow the **design-tokens** skill (loaded automatically) to create `design-tokens.json`.
|
||||
|
||||
### Step 3: Create the Design Brief
|
||||
### Step 3: Build the Screen Inventory (exhaustive — before designing anything)
|
||||
|
||||
The most common design failure is a missing screen — e.g. a todo app with a list screen but no screen for adding a new item. To prevent it, enumerate **every** screen the requirements imply and write the list to `docs/design/screen-inventory.md` **before** creating any other design file.
|
||||
|
||||
Derive the inventory from the documents read in Step 0. The user's Step 1 answer about main screens is input, never the ceiling.
|
||||
|
||||
1. **Walk every user story and requirement** in `docs/product-requirements.md`, and every flow in `docs/functional-design.md`. For each one, write down every screen the user passes through to complete it end-to-end. If a story cannot be completed with the screens listed so far, the missing screens go on the list.
|
||||
2. **Apply CRUD coverage to every entity** the user manages (e.g. todo item, project, profile). For each entity, explicitly decide each of: list/overview, detail, **create/add**, edit, delete confirmation. Include each as an inventory entry unless the requirements clearly exclude it. If create/edit happens in a modal, dialog, or inline form rather than a full page, it is **still an inventory entry** (record its presentation) — it still needs a blueprint entry and a wireframe.
|
||||
3. **Add the supporting screens** the requirements imply: authentication (sign in / sign up / password reset), settings, onboarding, search/filter results, empty states, error / not-found.
|
||||
|
||||
Write each entry in this format:
|
||||
|
||||
```markdown
|
||||
- [ ] `screen-id` — Title
|
||||
- Purpose: what the user accomplishes here
|
||||
- Source: the PRD user story / functional-design section it comes from
|
||||
- Reached from: the screens/actions that navigate here
|
||||
- Presentation: page | modal | drawer
|
||||
- Key elements: main components, inputs, and actions on the screen
|
||||
```
|
||||
|
||||
End the file with a **traceability table**: one row per user story, listing the screen ids that fulfill it. Every user story must map to at least one screen, and every screen must trace back to at least one requirement. Do not proceed to Step 4 until both directions are fully covered.
|
||||
|
||||
### Step 4: Create the Design Brief
|
||||
|
||||
Create `docs/design/design-brief.md` covering:
|
||||
|
||||
@ -88,7 +109,7 @@ Create `docs/design/design-brief.md` covering:
|
||||
- Examples of preferred UI style
|
||||
- Examples of UI style to avoid
|
||||
|
||||
### Step 4: Create the Design Tokens
|
||||
### Step 5: Create the Design Tokens
|
||||
|
||||
Create `docs/design/design-tokens.json` using a JSON structure inspired by the Design Tokens Community Group format (each token has `$type` and `$value`). Include:
|
||||
|
||||
@ -100,7 +121,7 @@ Create `docs/design/design-tokens.json` using a JSON structure inspired by the D
|
||||
- Animation durations / easings
|
||||
- Breakpoints (if the target includes web)
|
||||
|
||||
### Step 5: Create the UI Blueprint (source of truth)
|
||||
### Step 6: Create the UI Blueprint (source of truth)
|
||||
|
||||
Create `docs/design/ui-blueprint.json`. This is **the** source of truth for UI generation. It must describe:
|
||||
|
||||
@ -113,7 +134,9 @@ Create `docs/design/ui-blueprint.json`. This is **the** source of truth for UI g
|
||||
- Component hierarchy
|
||||
- User actions and navigation behavior
|
||||
|
||||
### Step 6: Create the Platform Mapping
|
||||
**Coverage rule**: the blueprint must contain one screen entry for **every** entry in `docs/design/screen-inventory.md` — including modal/drawer entries. As each screen is added, check it off (`[ ]` → `[x]`) in the inventory. Do not finish this step while any inventory entry is unchecked.
|
||||
|
||||
### Step 7: Create the Platform Mapping
|
||||
|
||||
Create `docs/design/platform-mapping.md` describing how the design spec is converted to each platform:
|
||||
|
||||
@ -131,7 +154,7 @@ WinUI 3:
|
||||
- ui-blueprint.json → XAML pages, UserControls, styles
|
||||
```
|
||||
|
||||
### Step 7: Generate SVG Wireframes (visual references only)
|
||||
### Step 8: Generate SVG Wireframes (visual references only)
|
||||
|
||||
For each screen in `ui-blueprint.json`, generate a corresponding SVG wireframe under `docs/design/screens/`:
|
||||
|
||||
@ -141,10 +164,12 @@ For each screen in `ui-blueprint.json`, generate a corresponding SVG wireframe u
|
||||
|
||||
**Important rule**: SVG files are **not** the source of truth. They are generated as visual references for human review only. The source of truth is `ui-blueprint.json`. If the blueprint and an SVG ever disagree, the blueprint wins and the SVG must be regenerated.
|
||||
|
||||
### Step 8: Consistency Check
|
||||
### Step 9: Consistency Check
|
||||
|
||||
Re-read all generated files and confirm:
|
||||
|
||||
- Every entry in `docs/design/screen-inventory.md` is checked off and has a matching screen (same id) in `ui-blueprint.json`.
|
||||
- Every user story in the PRD can be completed end-to-end using only the screens and actions in the blueprint — in particular, every entity the user can create, edit, or delete has a screen (or modal) for each of those operations.
|
||||
- Every screen in `ui-blueprint.json` has a matching SVG in `screens/`.
|
||||
- Token names referenced in `ui-blueprint.json` exist in `design-tokens.json`.
|
||||
- `platform-mapping.md` covers all target platforms selected in Step 1.
|
||||
@ -154,6 +179,7 @@ Fix any inconsistencies found before finishing.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
- `docs/design/screen-inventory.md` exists and every entry is checked off
|
||||
- `docs/design/design-brief.md` exists
|
||||
- `docs/design/design-tokens.json` exists and is valid JSON
|
||||
- `docs/design/ui-blueprint.json` exists and is valid JSON
|
||||
@ -165,6 +191,7 @@ Completion message:
|
||||
"Design phase is complete!
|
||||
|
||||
Design documents created:
|
||||
✅ docs/design/screen-inventory.md (exhaustive screen list — all entries covered)
|
||||
✅ docs/design/design-brief.md
|
||||
✅ docs/design/design-tokens.json
|
||||
✅ docs/design/ui-blueprint.json (source of truth)
|
||||
@ -174,7 +201,7 @@ Design documents created:
|
||||
Next steps:
|
||||
- Review docs/design/ (especially ui-blueprint.json)
|
||||
- Refine the design with /update-design <change> (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)
|
||||
"
|
||||
|
||||
@ -30,8 +30,6 @@ opencode
|
||||
↓
|
||||
/define-design
|
||||
↓
|
||||
/generate-app web | flutter | winui3
|
||||
↓
|
||||
/plan-milestones
|
||||
↓
|
||||
/execute-milestones phase1-milestones.md ← you are here (one phase file per run)
|
||||
@ -59,6 +57,7 @@ opencode
|
||||
|
||||
1. Follow the **milestone-execution** skill (loaded automatically) for the per-milestone steering structure, task-division rules, and the gate criteria between milestones.
|
||||
2. The **steering** and **development-guidelines** skills apply during implementation, exactly as in `/add-feature`.
|
||||
3. **If the milestone is the App Shell milestone (milestone 01)**, additionally follow the **platform-ui-generation** skill (loaded automatically) 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
|
||||
|
||||
|
||||
@ -1,155 +0,0 @@
|
||||
---
|
||||
description: Generate the initial application for a target platform (web | flutter | winui3) from the design spec
|
||||
agent: build
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
```
|
||||
opencode
|
||||
> /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 <change>`) 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
|
||||
|
||||
Follow the **platform-ui-generation** skill (loaded automatically) 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 (loaded automatically) 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
|
||||
"
|
||||
```
|
||||
@ -24,11 +24,9 @@ opencode
|
||||
↓
|
||||
/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
|
||||
@ -37,7 +35,7 @@ opencode
|
||||
- `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
|
||||
@ -60,6 +58,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
|
||||
@ -84,9 +83,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
|
||||
@ -116,6 +116,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.
|
||||
@ -137,13 +138,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
|
||||
"
|
||||
```
|
||||
|
||||
@ -1,11 +1,11 @@
|
||||
---
|
||||
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)
|
||||
agent: build
|
||||
---
|
||||
|
||||
# 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`)
|
||||
|
||||
@ -39,6 +39,8 @@ Read:
|
||||
|
||||
The blueprint is the source of truth, so it is always updated first. Add/modify screens, components, variants, states, routes, and actions to reflect the requested change. Keep the JSON valid and consistent with the existing schema.
|
||||
|
||||
If the change adds or removes screens, also update `docs/design/screen-inventory.md` (create it if missing — see the ui-design skill) so it stays the complete screen list: new screens get a checked (`[x]`) entry with purpose, source, and how they are reached; removed screens are deleted from it.
|
||||
|
||||
### Step 2: Update `design-tokens.json` (if needed)
|
||||
|
||||
If the change introduces new colors, spacing, typography, radius, shadows, or animations, add the corresponding tokens here. Reuse existing tokens where possible; do not duplicate. Use semantic names. No hard-coded values should be needed downstream.
|
||||
@ -58,6 +60,7 @@ For every screen added or modified in `ui-blueprint.json`, generate or regenerat
|
||||
### Step 6: Consistency Check
|
||||
|
||||
- Every screen in `ui-blueprint.json` has a matching SVG.
|
||||
- `docs/design/screen-inventory.md` (if present) lists exactly the blueprint's screens.
|
||||
- Token names referenced in the blueprint exist in `design-tokens.json`.
|
||||
- The brief and mapping remain consistent with the blueprint.
|
||||
|
||||
|
||||
@ -91,7 +91,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.
|
||||
@ -108,7 +108,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.
|
||||
|
||||
@ -18,13 +18,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
|
||||
|
||||
@ -50,6 +51,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:
|
||||
@ -66,10 +81,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
|
||||
|
||||
@ -83,6 +99,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.
|
||||
|
||||
@ -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]
|
||||
|
||||
|
||||
@ -1,18 +1,18 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# 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
|
||||
@ -84,7 +84,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
|
||||
|
||||
@ -15,11 +15,12 @@ Prefer describing **what a component is and how it behaves** over describing **w
|
||||
|
||||
## Outputs
|
||||
|
||||
This skill produces three kinds of artifacts under `docs/design/`:
|
||||
This skill produces four kinds of artifacts under `docs/design/`:
|
||||
|
||||
1. `design-brief.md` — the UI/UX direction (human-readable, but concrete)
|
||||
2. `ui-blueprint.json` — the source of truth for UI generation (machine-readable)
|
||||
3. `screens/*.svg` — visual wireframes for human review (derived from the blueprint)
|
||||
1. `screen-inventory.md` — an exhaustive checklist of every screen the requirements imply (always created first)
|
||||
2. `design-brief.md` — the UI/UX direction (human-readable, but concrete)
|
||||
3. `ui-blueprint.json` — the source of truth for UI generation (machine-readable)
|
||||
4. `screens/*.svg` — visual wireframes for human review (derived from the blueprint)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@ -31,6 +32,18 @@ Before creating the design, read:
|
||||
|
||||
The design must serve the product requirements and stay consistent with the functional design.
|
||||
|
||||
## Creating `screen-inventory.md` (always first)
|
||||
|
||||
Never design screens from memory of the requirements — a screen that is not on a written list will be forgotten (the classic miss: a list screen exists but the create/add screen does not). Build the inventory before the brief or the blueprint:
|
||||
|
||||
1. **Walk every user story** in the PRD and every flow in the functional design; list every screen the user needs to complete it end-to-end. If a story cannot be completed with the screens listed so far, the missing screens go on the list.
|
||||
2. **Apply CRUD coverage per entity**: for each domain object the user manages, explicitly decide list/overview, detail, **create/add**, edit, and delete confirmation — include each unless the requirements clearly exclude it. Modal/dialog/inline forms count as inventory entries too (record the presentation); they still need blueprint entries and wireframes.
|
||||
3. **Add supporting screens**: authentication, settings, onboarding, search results, empty states, error / not-found — wherever the requirements imply them.
|
||||
|
||||
Each entry is a checkbox item with `screen-id`, title, purpose, source requirement, how it is reached, presentation (page / modal / drawer), and key elements. End the file with a traceability table mapping every user story to the screen ids that fulfill it — both directions must be covered (no story without screens, no screen without a source).
|
||||
|
||||
Check entries off (`[x]`) as their screens are added to `ui-blueprint.json`. The blueprint is not complete while any entry is unchecked.
|
||||
|
||||
## Creating `design-brief.md`
|
||||
|
||||
A concrete, opinionated document. Avoid vague phrases like "modern and clean" without elaboration. Include every section below:
|
||||
@ -149,6 +162,8 @@ Each node has:
|
||||
|
||||
Before finishing:
|
||||
|
||||
- [ ] Every entry in `screen-inventory.md` is checked off and exists in the blueprint (same id).
|
||||
- [ ] Every user story can be completed end-to-end using only blueprint screens and actions — every entity that can be created, edited, or deleted has a screen or modal for each operation.
|
||||
- [ ] Every screen in the blueprint has a matching SVG.
|
||||
- [ ] Every `variant` used in a screen is declared in `components`.
|
||||
- [ ] Every token name used in the blueprint exists in `design-tokens.json`.
|
||||
|
||||
13
AGENTS.md
13
AGENTS.md
@ -79,12 +79,13 @@ Define "what to build" and "how to build it" for the entire application:
|
||||
- **glossary.md** - Ubiquitous language definitions
|
||||
|
||||
#### Design Documents (`docs/design/`)
|
||||
- **screen-inventory.md** - Exhaustive screen checklist derived from the PRD (coverage guarantee for the blueprint)
|
||||
- **design-brief.md** - UI/UX direction
|
||||
- **design-tokens.json** - Styling tokens (source of values)
|
||||
- **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
|
||||
@ -102,7 +103,7 @@ Define "what to do this time" for a specific development task:
|
||||
### opencode Configuration (`.opencode/`)
|
||||
|
||||
- `.opencode/agent/` - Subagent definitions (doc-reviewer, implementation-validator)
|
||||
- `.opencode/command/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, execute-milestones, add-feature, review-docs)
|
||||
- `.opencode/command/` - Slash commands (setup-project, define-design, update-design, plan-milestones, execute-milestones, add-feature, review-docs)
|
||||
- `.opencode/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
|
||||
@ -113,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
|
||||
@ -134,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
|
||||
|
||||
120
README.md
120
README.md
@ -14,7 +14,7 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
|
||||
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
|
||||
@ -27,10 +27,13 @@ PRD, functional design, architecture, repository structure, development guidelin
|
||||
(all under `docs/`). Review them and request edits in normal conversation if needed.
|
||||
|
||||
### Step 3 — Define the UI/UX design: `/define-design`
|
||||
Creates the design specification under `docs/design/`: design brief, design tokens,
|
||||
**`ui-blueprint.json` (the source of truth for UI generation)**, platform mapping, and SVG
|
||||
wireframes (visual references only). You'll be asked once about platform, style, screens,
|
||||
navigation, branding, and accessibility.
|
||||
First builds an **exhaustive screen inventory** (`screen-inventory.md`) from the PRD and
|
||||
functional design — every user story walked end-to-end, plus list/detail/create/edit/delete
|
||||
coverage for every entity — so no screen gets skipped. Then creates the design specification
|
||||
under `docs/design/`: design brief, design tokens, **`ui-blueprint.json` (the source of truth
|
||||
for UI generation, one entry per inventory screen)**, platform mapping, and SVG wireframes
|
||||
(visual references only). You'll be asked once about platform, style, screens, navigation,
|
||||
branding, and accessibility.
|
||||
|
||||
### Step 4 — Review and refine the design **before writing any code**
|
||||
This is the key design-decision gate: iterate on the design while it is still cheap to change.
|
||||
@ -39,18 +42,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:
|
||||
|
||||
@ -72,7 +74,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 <next phase file>`, or feature by feature with `/add-feature <feature>`
|
||||
- UI changes → `/update-design <change>` first, then `/add-feature`
|
||||
- Re-planning → re-run `/plan-milestones` or edit `docs/milestones/` in conversation
|
||||
@ -95,6 +97,7 @@ in sync with the code.
|
||||
- [Configuration Overview](#configuration-overview)
|
||||
- [Usage Workflow](#usage-workflow)
|
||||
- [Design & App Generation](#design--app-generation)
|
||||
- [E2E Testing (Playwright)](#e2e-testing-playwright)
|
||||
- [Commands Reference](#commands-reference)
|
||||
- [Skills Reference](#skills-reference)
|
||||
- [Agents Reference](#agents-reference)
|
||||
@ -204,6 +207,7 @@ opencode
|
||||
│ ├── ideas/
|
||||
│ │ └── initial-requirements.md # Brainstorming notes (pre-PRD)
|
||||
│ ├── design/ # UI/UX design spec (created by /define-design)
|
||||
│ │ ├── screen-inventory.md # exhaustive screen checklist (from the PRD)
|
||||
│ │ ├── design-brief.md
|
||||
│ │ ├── design-tokens.json
|
||||
│ │ ├── ui-blueprint.json # source of truth for UI
|
||||
@ -223,7 +227,6 @@ opencode
|
||||
├── command/ # Slash commands
|
||||
│ ├── setup-project.md
|
||||
│ ├── define-design.md
|
||||
│ ├── generate-app.md
|
||||
│ ├── update-design.md
|
||||
│ ├── plan-milestones.md
|
||||
│ ├── execute-milestones.md
|
||||
@ -323,9 +326,12 @@ first if you have your own idea, or replace it.
|
||||
> /define-design
|
||||
```
|
||||
|
||||
Creates the design specification under `docs/design/` (design brief, design tokens, UI blueprint,
|
||||
platform mapping, and SVG wireframes). You'll be asked about target platform, visual style, main
|
||||
screens, navigation, branding, and accessibility; if you don't specify, sensible defaults are proposed.
|
||||
First builds an exhaustive screen inventory (`screen-inventory.md`) from the PRD and functional
|
||||
design — every user story walked end-to-end, with list/detail/create/edit/delete coverage per
|
||||
entity — then creates the design specification under `docs/design/` (design brief, design tokens,
|
||||
UI blueprint with one entry per inventory screen, platform mapping, and SVG wireframes). You'll be
|
||||
asked about target platform, visual style, main screens, navigation, branding, and accessibility;
|
||||
if you don't specify, sensible defaults are proposed.
|
||||
|
||||
Review and refine the UI/UX **before** generating the app — it is far easier to iterate on the design
|
||||
than on generated code:
|
||||
@ -336,18 +342,7 @@ than on generated code:
|
||||
|
||||
**The design source of truth is `docs/design/ui-blueprint.json`.** SVG files are visual references only.
|
||||
|
||||
### 3. Generate the app
|
||||
|
||||
```
|
||||
> /generate-app web
|
||||
> /generate-app flutter
|
||||
> /generate-app winui3
|
||||
```
|
||||
|
||||
Scaffolds the initial application for the selected target from the design spec — app shell, theme
|
||||
(from tokens), routes, screens, and reusable components. No feature logic is implemented here.
|
||||
|
||||
### 4. Plan milestones
|
||||
### 3. Plan milestones
|
||||
|
||||
```
|
||||
> /plan-milestones
|
||||
@ -357,10 +352,13 @@ Scaffolds the initial application for the selected target from the design spec
|
||||
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`, …) listing its
|
||||
milestones and their features — each feature sized for one `/add-feature` run, with acceptance
|
||||
criteria and a ready-to-run command. Phase 1 delivers the MVP. You'll be asked once about phase
|
||||
count, MVP scope, priorities, and constraints; sensible defaults are proposed from the PRD.
|
||||
criteria and a ready-to-run command. **Milestone 01 is always "App Shell Generation"**: executed
|
||||
like any other milestone, it scaffolds the initial app from the design spec (theme from tokens,
|
||||
one screen per blueprint entry, routes, reusable components — no feature logic) plus the Playwright
|
||||
smoke spec. Phase 1 delivers the MVP. You'll be asked once about target platform, phase count,
|
||||
MVP scope, priorities, and constraints; sensible defaults are proposed from the PRD.
|
||||
|
||||
### 5. Add a feature
|
||||
### 4. Add a feature
|
||||
|
||||
```
|
||||
> /add-feature User authentication
|
||||
@ -376,7 +374,7 @@ This fully autonomous workflow:
|
||||
7. Writes Playwright E2E tests for the acceptance criteria, then runs `npm test`, `npm run lint`, `npm run typecheck`, `npm run test:e2e`
|
||||
8. Records a retrospective, reconciles all six persistent docs with the feature, and checks the feature off in its phase file
|
||||
|
||||
### 6. Execute a phase file (alternative to per-feature runs)
|
||||
### 5. Execute a phase file (alternative to per-feature runs)
|
||||
|
||||
```
|
||||
> /execute-milestones phase1-milestones.md
|
||||
@ -392,7 +390,7 @@ runs the test suite, reconciles the docs, marks the milestone `Completed` — an
|
||||
the next one. When the last milestone finishes, the phase is marked `Completed` in the roadmap.
|
||||
It only stops early on a genuine external blocker, which it records in the roadmap.
|
||||
|
||||
### 7. Review a document
|
||||
### 6. Review a document
|
||||
|
||||
```
|
||||
> /review-docs docs/product-requirements.md
|
||||
@ -401,7 +399,7 @@ It only stops early on a genuine external blocker, which it records in the roadm
|
||||
Launches the `doc-reviewer` subagent to evaluate the document from five perspectives:
|
||||
completeness, clarity, consistency, implementability, and measurability.
|
||||
|
||||
### 8. Day-to-day editing
|
||||
### 7. Day-to-day editing
|
||||
|
||||
You don't always need a command — just ask in normal conversation:
|
||||
|
||||
@ -424,31 +422,67 @@ Recommended workflow:
|
||||
3. Review `docs/design/` and refine the UI/UX until approved:
|
||||
- Re-run `/define-design` to change direction, or
|
||||
- Run `/update-design <change>` for targeted refinements
|
||||
4. Run `/generate-app web`, `/generate-app flutter`, or `/generate-app winui3`
|
||||
5. Run `/plan-milestones` to break the product into phases and milestones (one `phaseN-milestones.md` per phase)
|
||||
6. Use `/execute-milestones phase1-milestones.md` to implement a phase's milestones one by one, or `/add-feature` to go feature by feature
|
||||
7. Use `/update-design` whenever a feature changes the UI
|
||||
4. Run `/plan-milestones` to break the product into phases and milestones (one `phaseN-milestones.md` per phase; milestone 01 = App Shell Generation for the chosen platform)
|
||||
5. Use `/execute-milestones phase1-milestones.md` to implement a phase's milestones one by one (milestone 01 generates the initial app), or `/add-feature` to go feature by feature
|
||||
6. Use `/update-design` whenever a feature changes the UI
|
||||
|
||||
Source of truth:
|
||||
|
||||
- The design source of truth is `docs/design/ui-blueprint.json`.
|
||||
- SVG files (`docs/design/screens/*.svg`) are only visual references.
|
||||
- Generated UI should follow `docs/design/design-tokens.json` — no hard-coded values.
|
||||
- No platform-specific implementation is generated before `/generate-app` is executed.
|
||||
- No platform-specific implementation is generated before the App Shell milestone (milestone 01) is executed.
|
||||
|
||||
See [`docs/design/README.md`](docs/design/README.md) for the full structure.
|
||||
|
||||
---
|
||||
|
||||
## E2E Testing (Playwright)
|
||||
|
||||
Every verification step in this boilerplate includes end-to-end tests. The standard verification
|
||||
sequence — used by `/add-feature` and `/execute-milestones` — is:
|
||||
|
||||
```bash
|
||||
npm test # unit tests
|
||||
npm run lint
|
||||
npm run typecheck
|
||||
npm run test:e2e # Playwright E2E
|
||||
```
|
||||
|
||||
How it works (defined in the `e2e-testing` skill):
|
||||
|
||||
- **Setup is automatic**: on the first verification, if Playwright is missing, the agent installs
|
||||
`@playwright/test`, creates `playwright.config.ts` (dev-server integration, trace/screenshot on
|
||||
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**: 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.
|
||||
- **No green-washing**: a failing E2E test is fixed, never skipped or deleted; milestone gates in
|
||||
`/execute-milestones` do not pass without a green E2E suite.
|
||||
|
||||
```
|
||||
e2e/
|
||||
├── app-shell.spec.ts # smoke: shell renders, all blueprint routes navigate
|
||||
├── [feature-name].spec.ts # one spec per feature (acceptance criteria)
|
||||
└── helpers/ # shared fixtures (only when duplicated 3+ times)
|
||||
```
|
||||
|
||||
Playwright covers the `web` target; for `flutter` the equivalent is `integration_test`, and for
|
||||
`winui3` the platform's UI automation — with the same acceptance-criteria mapping.
|
||||
|
||||
---
|
||||
|
||||
## Commands Reference
|
||||
|
||||
| Command | Description | Example |
|
||||
|---|---|---|
|
||||
| `/setup-project` | Create the six persistent documents automatically | `/setup-project` |
|
||||
| `/define-design` | Create the UI/UX design spec under `docs/design/` | `/define-design` |
|
||||
| `/generate-app` | Scaffold the initial app for a target platform | `/generate-app web` |
|
||||
| `/update-design` | Update the design spec when a feature changes the UI | `/update-design add a profile screen` |
|
||||
| `/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` |
|
||||
@ -465,7 +499,7 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure.
|
||||
| `repository-structure` | Defining the directory layout | `docs/repository-structure.md` |
|
||||
| `development-guidelines` | Creating coding conventions / implementing code | `docs/development-guidelines.md` |
|
||||
| `glossary-creation` | Creating a project glossary | `docs/glossary.md` |
|
||||
| `ui-design` | Creating the design brief, UI blueprint, and SVG wireframes | `docs/design/` files |
|
||||
| `ui-design` | Creating the screen inventory, design brief, UI blueprint, and SVG wireframes | `docs/design/` files |
|
||||
| `design-tokens` | Creating and maintaining design tokens | `docs/design/design-tokens.json` |
|
||||
| `platform-ui-generation` | Converting design files into Web/Flutter/WinUI 3 code | generated app code |
|
||||
| `milestone-planning` | Planning phases/milestones and the feature breakdown per milestone | `docs/milestones/` phase files |
|
||||
|
||||
@ -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 `<screen-i
|
||||
```
|
||||
/setup-project → product/architecture docs
|
||||
/define-design → creates the files above
|
||||
/generate-app web | flutter | winui3 → scaffolds the app from these files
|
||||
/plan-milestones → milestone 01 (App Shell) scaffolds the app from these files
|
||||
/update-design → updates these files when a feature changes the UI
|
||||
/add-feature → reads these files before implementing; updates them first if the UI changes
|
||||
```
|
||||
|
||||
## Status
|
||||
|
||||
This directory is populated by running `/define-design`. Until then, the files above do not exist and `/generate-app` will ask you to run `/define-design` first.
|
||||
This directory is populated by running `/define-design`. Until then, the files above do not exist and milestone planning/execution will warn you to run `/define-design` first.
|
||||
|
||||
@ -39,8 +39,7 @@ One file per phase — the execution unit for `/execute-milestones`. Contains th
|
||||
```
|
||||
/setup-project → product/architecture docs
|
||||
/define-design → UI/UX design spec
|
||||
/generate-app → initial app shell
|
||||
/plan-milestones → creates the files above
|
||||
/plan-milestones → creates the files above (milestone 01 = App Shell Generation)
|
||||
/execute-milestones phase1-milestones.md → implements that phase's milestones one by one (one steering directory per milestone), updating statuses here
|
||||
/add-feature → implements one feature, then checks it off here
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user