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

feat: add design phase and platform app generation phase

Browse Source 
Add a UI/UX design phase (/define-design, /update-design) and a platform
app generation phase (/generate-app web|flutter|winui3) to the workflow,
positioned between /setup-project and /add-feature.

- commands: define-design, generate-app, update-design
- add-feature: check docs/design/ before implementation; update design
  files first when a feature changes the UI
- skills: ui-design, design-tokens, platform-ui-generation
- docs/design/ structure documented (source of truth = ui-blueprint.json;
  SVGs are references only; generated UI follows design-tokens.json)
- README and AGENTS.md updated with the new workflow
This commit is contained in:
Ken Yasue
2026-06-28 18:41:01 +02:00
parent e1ef10be6e
commit f57921abad
10 changed files with 1004 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
README.md
View File

@ -18,6 +18,7 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
- [Directory Structure](#directory-structure)
- [Configuration Overview](#configuration-overview)
- [Usage Workflow](#usage-workflow)
- [Design & App Generation](#design--app-generation)
- [Commands Reference](#commands-reference)
- [Skills Reference](#skills-reference)
- [Agents Reference](#agents-reference)
@ -123,9 +124,15 @@ opencode
│ ├── example.ts
│ └── example.test.ts
│
├── docs/ # Persistent design documents (created by /setup-project)
│ └── ideas/
│ └── initial-requirements.md # Brainstorming notes (pre-PRD)
├── docs/ # Persistent design documents
│ ├── ideas/
│ │ └── initial-requirements.md # Brainstorming notes (pre-PRD)
│ └── design/ # UI/UX design spec (created by /define-design)
│ ├── design-brief.md
│ ├── design-tokens.json
│ ├── ui-blueprint.json # source of truth for UI
│ ├── platform-mapping.md
│ └── screens/*.svg # visual references only
│
├── .steering/ # Per-task steering files (created by /add-feature)
│ └── .gitkeep
@ -136,6 +143,9 @@ opencode
│ └── implementation-validator.md
├── command/ # Slash commands
│ ├── setup-project.md
│ ├── define-design.md
│ ├── generate-app.md
│ ├── update-design.md
│ ├── add-feature.md
│ └── review-docs.md
└── skills/ # Task-specific skills
@ -145,6 +155,9 @@ opencode
├── repository-structure/ (SKILL.md + template.md + guide.md)
├── development-guidelines/(SKILL.md + template.md + guides/)
├── glossary-creation/ (SKILL.md + template.md + guide.md)
├── ui-design/ (SKILL.md)
├── design-tokens/ (SKILL.md)
├── platform-ui-generation/(SKILL.md)
└── steering/ (SKILL.md + templates/)
```
@ -203,13 +216,13 @@ opencode surfaces the right skill when the task matches.
### 1. Initial project setup
Run the setup command to create all six persistent design documents interactively:
Run the setup command to automatically create all six persistent design documents:
```
> /setup-project
```
This creates (one at a time, with your approval):
This creates (automatically, end-to-end):
1. `docs/product-requirements.md` (PRD)
2. `docs/functional-design.md`
3. `docs/architecture.md`
@ -220,7 +233,30 @@ This creates (one at a time, with your approval):
The PRD is based on the brainstorming notes in `docs/ideas/initial-requirements.md`. Edit that file
first if you have your own idea, or replace it.
### 2. Add a feature
### 2. Define the UI/UX design
```
> /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.
**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. Add a feature
```
> /add-feature User authentication
@ -228,13 +264,14 @@ first if you have your own idea, or replace it.
This fully autonomous workflow:
1. Creates `.steering/[YYYYMMDD]-[feature-name]/` with `requirements.md`, `design.md`, `tasklist.md`
2. Generates the steering files (planning mode of the steering skill)
3. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
4. Launches the `implementation-validator` subagent for quality review
5. Runs `npm test`, `npm run lint`, `npm run typecheck`
6. Records a retrospective in `tasklist.md`
2. Reads the design spec (`docs/design/`) and updates it first if the feature changes the UI
3. Generates the steering files (planning mode of the steering skill)
4. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
5. Launches the `implementation-validator` subagent for quality review
6. Runs `npm test`, `npm run lint`, `npm run typecheck`
7. Records a retrospective and reconciles all six persistent docs with the feature
### 3. Review a document
### 5. Review a document
```
> /review-docs docs/product-requirements.md
@ -243,7 +280,7 @@ This fully autonomous workflow:
Launches the `doc-reviewer` subagent to evaluate the document from five perspectives:
completeness, clarity, consistency, implementability, and measurability.
### 4. Day-to-day editing
### 6. Day-to-day editing
You don't always need a command — just ask in normal conversation:
@ -257,11 +294,36 @@ opencode loads the appropriate skill automatically.
---
## Design & App Generation
Recommended workflow:
1. Run `/setup-project`
2. Run `/define-design`
3. Review `docs/design/`
4. Run `/generate-app web`, `/generate-app flutter`, or `/generate-app winui3`
5. Use `/add-feature` to add features
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.
See [`docs/design/README.md`](docs/design/README.md) for the full structure.
---
## Commands Reference
| Command | Description | Example |
|---|---|---|
| `/setup-project` | Create the six persistent documents interactively | `/setup-project` |
| `/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` |
| `/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` |
@ -277,6 +339,9 @@ opencode loads the appropriate skill automatically.
| `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 |
| `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 |
| `steering` | Planning, implementing, and retrospecting on a task | `.steering/[date]-[name]/` files |
Each skill folder contains a `SKILL.md` (instructions) plus `template.md` and/or `guide.md` (reference