ken/opencode-boilerplate
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Remove /generate-app: app shell is now milestone 01 of the plan

Browse Source 
The initial app is no longer generated by a separate command. /plan-milestones
now always makes milestone 01 'App Shell Generation' (target platform asked in
the single question round): theme from design tokens, one screen per blueprint
entry, routes, reusable components — no feature logic — plus Playwright setup
and the e2e/app-shell.spec.ts smoke spec. It is executed like any other
milestone via /execute-milestones (which follows platform-ui-generation for it)
or /add-feature. Milestone 02 becomes the MVP core. All workflow diagrams,
skills, docs READMEs, AGENTS.md, and README updated; docs/design README also
gains the screen-inventory.md entry.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Ken Yasue
2026-07-02 14:10:07 +02:00
parent a4f80e8c8c
commit 1649a71781
13 changed files with 89 additions and 238 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
README.md
View File

@ -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
@ -42,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:
@ -75,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
@ -228,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
@ -344,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
@ -365,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
@ -384,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
@ -400,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
@ -409,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:
@ -432,17 +422,16 @@ 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.
@ -451,7 +440,7 @@ 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`, `/execute-milestones`, and `/generate-app` — is:
sequence — used by `/add-feature` and `/execute-milestones` — is:
```bash
npm test # unit tests
@ -467,7 +456,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.
@ -492,9 +481,8 @@ Playwright covers the `web` target; for `flutter` the equivalent is `integration
|---|---|---|
| `/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` |