Compare commits
5 Commits
e1ef10be6e
...
milestone-
| Author | SHA1 | Date | |
|---|---|---|---|
| 00cb087f77 | |||
| 5e30ac8ef3 | |||
| 89e6a58929 | |||
| 7fdb430c67 | |||
| f57921abad |
@ -27,12 +27,37 @@ agent: build
|
||||
|
||||
1. Read `AGENTS.md` to grasp the overall picture of the project.
|
||||
2. Review the persistent documents in the `docs/` directory to understand the relevant design philosophy and architecture.
|
||||
3. If `docs/milestones/` exists, read `docs/milestones/roadmap.md` and find the milestone document that contains this feature. Use its description, related requirements, affected screens, and acceptance criteria as the basis for planning. If the feature is not in any milestone, note that it is unplanned work and proceed.
|
||||
|
||||
## Step 3: Investigate Existing Patterns
|
||||
|
||||
1. Use the grep tool to search the source code (`src/`) for keywords related to the feature name.
|
||||
2. Analyze the search results to identify existing implementation patterns, naming conventions, and how components are used.
|
||||
|
||||
## Step 3.5: Check the Design Specification (Before Implementation)
|
||||
|
||||
Before implementing any feature, respect the UI/UX design specification.
|
||||
|
||||
1. Check whether the design files exist:
|
||||
- `docs/design/design-brief.md`
|
||||
- `docs/design/design-tokens.json`
|
||||
- `docs/design/ui-blueprint.json`
|
||||
- `docs/design/platform-mapping.md`
|
||||
|
||||
2. **If the design files do not exist**, warn the user and suggest running `/define-design` before continuing. Do not silently proceed without a design spec.
|
||||
|
||||
3. **If the design files exist**, read all four of them before implementation:
|
||||
1. `docs/design/design-brief.md`
|
||||
2. `docs/design/design-tokens.json`
|
||||
3. `docs/design/ui-blueprint.json` (source of truth)
|
||||
4. `docs/design/platform-mapping.md`
|
||||
|
||||
4. **If the feature changes the UI**, update the design files first, following the `/update-design` order:
|
||||
- `ui-blueprint.json` → `design-tokens.json` → `design-brief.md` → `platform-mapping.md` → regenerate affected `screens/*.svg`
|
||||
- The blueprint is the source of truth; SVGs are visual references only.
|
||||
|
||||
5. Then implement the feature according to the selected platform mapping in `platform-mapping.md`, using tokens from `design-tokens.json` (no hard-coded values) and the component tree from `ui-blueprint.json`.
|
||||
|
||||
## Step 4: Planning Phase (Automatic Generation of Steering Files)
|
||||
|
||||
1. Follow the **steering** skill (loaded automatically) in **planning mode** to generate the contents of the three files created in Step 1 (`requirements.md`, `design.md`, `tasklist.md`).
|
||||
@ -123,9 +148,14 @@ If any of the following situations occur while the implementation loop is runnin
|
||||
- ✅ `docs/development-guidelines.md` — add/update any new conventions, patterns, or standards established during the feature
|
||||
- ✅ `docs/glossary.md` — add/update any new domain terms introduced by the feature
|
||||
|
||||
3. **Consistency check**: re-read each updated document and confirm it is consistent with the other documents and with the implemented code. Fix any inconsistencies found.
|
||||
3. **Update the milestone documents (if `docs/milestones/` exists)**:
|
||||
- In the feature's milestone document, use the edit tool to check the feature off (`[ ]` → `[x]`).
|
||||
- If this was the last unchecked feature of the milestone, set the milestone's status to `Completed` (in both the milestone document and `docs/milestones/roadmap.md`), fill in its "Completion Notes", and update the roadmap's current-milestone pointer to the next milestone.
|
||||
- If the feature was not part of any milestone, add it to the current milestone's document as a completed (`[x]`) feature so the plan reflects reality.
|
||||
|
||||
4. **Once this step completes successfully, never stop; immediately proceed to the Completion Criteria.**
|
||||
4. **Consistency check**: re-read each updated document and confirm it is consistent with the other documents and with the implemented code. Fix any inconsistencies found.
|
||||
|
||||
5. **Once this step completes successfully, never stop; immediately proceed to the Completion Criteria.**
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
@ -133,6 +163,6 @@ This workflow completes automatically once all of the following conditions are m
|
||||
- Step 5: All tasks in `tasklist.md` are complete (`[x]` or skipped for a valid reason).
|
||||
- Step 6: The `implementation-validator` subagent's validation passes.
|
||||
- Step 7: The `test`, `lint`, and `typecheck` commands all succeed without errors.
|
||||
- Step 8: Handover notes are recorded in `tasklist.md`, and all six persistent documents in `docs/` have been reconciled with the feature (updates applied, or a skip reason noted for each).
|
||||
- Step 8: Handover notes are recorded in `tasklist.md`, all six persistent documents in `docs/` have been reconciled with the feature (updates applied, or a skip reason noted for each), and the feature is checked off in its milestone document (if `docs/milestones/` exists).
|
||||
|
||||
Until these completion criteria are met, continue to think autonomously, solve problems, and carry on the work.
|
||||
|
||||
181
.opencode/command/define-design.md
Normal file
181
.opencode/command/define-design.md
Normal file
@ -0,0 +1,181 @@
|
||||
---
|
||||
description: Create the UI/UX design specification (design brief, tokens, UI blueprint, platform mapping, SVG wireframes)
|
||||
agent: build
|
||||
---
|
||||
|
||||
# Define Design (UI/UX Design Phase)
|
||||
|
||||
This command creates (or updates) the project's design specification under `docs/design/`. The design is **AI-readable and implementation-ready**: the source of truth is structured text/JSON, not visual images.
|
||||
|
||||
**Design source of truth**: `docs/design/ui-blueprint.json`
|
||||
**Visual references only**: `docs/design/screens/*.svg`
|
||||
|
||||
## How to Run
|
||||
|
||||
```
|
||||
opencode
|
||||
> /define-design
|
||||
```
|
||||
|
||||
## Position in the Workflow
|
||||
|
||||
```
|
||||
/setup-project
|
||||
↓
|
||||
/define-design ← you are here
|
||||
↓
|
||||
/generate-app web | flutter | winui3
|
||||
↓
|
||||
/plan-milestones
|
||||
↓
|
||||
/add-feature
|
||||
```
|
||||
|
||||
## Pre-Run Check
|
||||
|
||||
1. Confirm the persistent documents exist. If any of these are missing, stop and tell the user to run `/setup-project` first:
|
||||
- `docs/product-requirements.md`
|
||||
- `docs/functional-design.md`
|
||||
- `docs/architecture.md`
|
||||
2. Create the design directory if it does not exist:
|
||||
```bash
|
||||
mkdir -p docs/design/screens
|
||||
```
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 0: Read the Inputs
|
||||
|
||||
Read all of the following to understand what is being built:
|
||||
|
||||
- `docs/product-requirements.md`
|
||||
- `docs/functional-design.md`
|
||||
- `docs/architecture.md`
|
||||
- `docs/repository-structure.md`
|
||||
- `docs/development-guidelines.md`
|
||||
- `docs/glossary.md`
|
||||
- `docs/ideas/*` (if present)
|
||||
|
||||
### Step 1: Gather Design Preferences (ask the user once)
|
||||
|
||||
Ask the user about the following. If the user does not provide detailed preferences, **propose a sensible default** derived from the product requirements and confirm it before proceeding.
|
||||
|
||||
- **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
|
||||
- **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)
|
||||
|
||||
Collect the answers in a single round; do not pause again until generation is complete.
|
||||
|
||||
### Step 2: Load the Design Skills
|
||||
|
||||
- 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
|
||||
|
||||
Create `docs/design/design-brief.md` covering:
|
||||
|
||||
- Target users
|
||||
- Design concept
|
||||
- Visual mood
|
||||
- Layout principles
|
||||
- Navigation principles
|
||||
- Accessibility considerations
|
||||
- Platform-specific notes
|
||||
- Examples of preferred UI style
|
||||
- Examples of UI style to avoid
|
||||
|
||||
### Step 4: 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:
|
||||
|
||||
- Colors (semantic names: background, text, accent, border, state, etc.)
|
||||
- Typography (font families, sizes, weights, line heights)
|
||||
- Spacing scale
|
||||
- Border radius
|
||||
- Shadows / elevation
|
||||
- Animation durations / easings
|
||||
- Breakpoints (if the target includes web)
|
||||
|
||||
### Step 5: 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:
|
||||
|
||||
- App name and target platforms
|
||||
- Overall style summary
|
||||
- Routes
|
||||
- Screens (each with id, title, route, layout, and component tree)
|
||||
- Layouts
|
||||
- Components (variants and states)
|
||||
- Component hierarchy
|
||||
- User actions and navigation behavior
|
||||
|
||||
### Step 6: Create the Platform Mapping
|
||||
|
||||
Create `docs/design/platform-mapping.md` describing how the design spec is converted to each platform:
|
||||
|
||||
```text
|
||||
Web:
|
||||
- design-tokens.json → CSS variables or Tailwind theme
|
||||
- ui-blueprint.json → pages, routes, React components, layout components
|
||||
|
||||
Flutter:
|
||||
- design-tokens.json → ThemeData, ColorScheme, constants
|
||||
- ui-blueprint.json → Widget tree, routes, reusable widgets
|
||||
|
||||
WinUI 3:
|
||||
- design-tokens.json → ResourceDictionary
|
||||
- ui-blueprint.json → XAML pages, UserControls, styles
|
||||
```
|
||||
|
||||
### Step 7: Generate SVG Wireframes (visual references only)
|
||||
|
||||
For each screen in `ui-blueprint.json`, generate a corresponding SVG wireframe under `docs/design/screens/`:
|
||||
|
||||
- `docs/design/screens/home.svg`
|
||||
- `docs/design/screens/settings.svg`
|
||||
- `docs/design/screens/[screen-id].svg`
|
||||
|
||||
**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
|
||||
|
||||
Re-read all generated files and confirm:
|
||||
|
||||
- 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.
|
||||
- The design is consistent with `docs/product-requirements.md` and `docs/functional-design.md`.
|
||||
|
||||
Fix any inconsistencies found before finishing.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
- `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
|
||||
- `docs/design/platform-mapping.md` exists
|
||||
- One SVG per screen exists under `docs/design/screens/`
|
||||
|
||||
Completion message:
|
||||
```
|
||||
"Design phase is complete!
|
||||
|
||||
Design documents created:
|
||||
✅ docs/design/design-brief.md
|
||||
✅ docs/design/design-tokens.json
|
||||
✅ docs/design/ui-blueprint.json (source of truth)
|
||||
✅ docs/design/platform-mapping.md
|
||||
✅ docs/design/screens/*.svg (visual references)
|
||||
|
||||
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
|
||||
- Use /update-design when a feature changes the UI
|
||||
- Use /add-feature to add features (it respects the design spec)
|
||||
"
|
||||
```
|
||||
150
.opencode/command/execute-milestones.md
Normal file
150
.opencode/command/execute-milestones.md
Normal file
@ -0,0 +1,150 @@
|
||||
---
|
||||
description: Execute milestones one by one, generating separate steering documents per milestone and implementing all of its features autonomously
|
||||
agent: build
|
||||
---
|
||||
|
||||
# Execute Milestones (Fully Autonomous Milestone Execution Mode)
|
||||
|
||||
This command works through the milestone plan in `docs/milestones/` **one milestone at a time**. For each milestone it generates a **separate set of steering documents** under `.steering/`, divides the milestone's features into concrete tasks, implements them all, validates, tests, and reconciles the documents — then immediately moves on to the next milestone.
|
||||
|
||||
**Important:** This workflow is designed to run fully automatically from start to finish without user intervention. Do not ask the user for confirmation between milestones.
|
||||
|
||||
**Target**: `$ARGUMENTS` — optional: a milestone number (e.g. `2`), a range (e.g. `1-3`), or empty to execute **all remaining milestones in order**.
|
||||
|
||||
## How to Run
|
||||
|
||||
```
|
||||
opencode
|
||||
> /execute-milestones # execute all remaining milestones one by one
|
||||
> /execute-milestones 1 # execute only milestone 1
|
||||
> /execute-milestones 2-3 # execute milestones 2 through 3
|
||||
```
|
||||
|
||||
## Position in the Workflow
|
||||
|
||||
```
|
||||
/setup-project
|
||||
↓
|
||||
/define-design
|
||||
↓
|
||||
/generate-app web | flutter | winui3
|
||||
↓
|
||||
/plan-milestones
|
||||
↓
|
||||
/execute-milestones ← you are here (alternative: /add-feature per feature)
|
||||
```
|
||||
|
||||
## Pre-Run Check
|
||||
|
||||
1. Confirm `docs/milestones/roadmap.md` and at least one `docs/milestones/milestone-*.md` exist. If not, stop and tell the user to run `/plan-milestones` first.
|
||||
2. Check whether the design files (`docs/design/ui-blueprint.json` etc.) exist. If they do not, warn the user and suggest running `/define-design` first. Do not silently proceed without a design spec.
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 0: Build the Execution Queue
|
||||
|
||||
1. Read `docs/milestones/roadmap.md` and every milestone document.
|
||||
2. The execution queue is the milestones selected by `$ARGUMENTS` (all of them when empty), **excluding** milestones whose status is already `Completed`, in ascending milestone number.
|
||||
3. If the queue is empty, report that all selected milestones are already completed and finish.
|
||||
|
||||
### Step 1: Load the Skills
|
||||
|
||||
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`.
|
||||
|
||||
### Step 2: Milestone Loop
|
||||
|
||||
**This step repeats for each milestone in the queue, strictly in order. Never start a milestone before the previous one has passed its gate (Step 2.8).**
|
||||
|
||||
For the current milestone `[NN] [name]`:
|
||||
|
||||
#### 2.1 Create the Milestone Steering Directory
|
||||
|
||||
Create `.steering/[YYYYMMDD]-milestone-[NN]-[kebab-case-name]/` with the three files:
|
||||
|
||||
- `requirements.md`
|
||||
- `design.md`
|
||||
- `tasklist.md`
|
||||
|
||||
Each milestone gets its **own** directory — never reuse or append to another milestone's steering documents.
|
||||
|
||||
#### 2.2 Generate the Steering Documents
|
||||
|
||||
Following the milestone-execution skill:
|
||||
|
||||
- `requirements.md`: the milestone's goal, scope, and every feature with its description, related PRD requirements, affected screens, and acceptance criteria (copied and expanded from the milestone document).
|
||||
- `design.md`: the implementation approach across the milestone's features — shared components, data model changes, and order of implementation — consistent with `docs/architecture.md` and `docs/design/`.
|
||||
- `tasklist.md`: the milestone's features **divided into concrete tasks, grouped by feature** (one `## Feature:` section per feature, each ending with its verification tasks). Every task must be small enough to complete in one implementation-loop iteration.
|
||||
|
||||
#### 2.3 Check the Design Specification
|
||||
|
||||
Apply `/add-feature` Step 3.5 for the milestone as a whole: read all four design files before implementation; if any feature in this milestone changes the UI, update the design files first (blueprint → tokens → brief → mapping → SVGs).
|
||||
|
||||
#### 2.4 Implementation Loop
|
||||
|
||||
Work through `tasklist.md` top to bottom using the same rules as `/add-feature` Step 5:
|
||||
|
||||
- Follow the **steering** skill in **implementation mode**; follow the coding standards in the **development-guidelines** skill.
|
||||
- Mark each task `[ ]` → `[x]` with the edit tool as it completes.
|
||||
- Exception rules A (split oversized tasks) and B (strike obsolete tasks with a reason) apply.
|
||||
- **Forbidden**: skipping tasks, ending the loop with unchecked tasks, or asking the user to decide.
|
||||
|
||||
#### 2.5 Validate the Milestone
|
||||
|
||||
Use the Task tool to launch the `implementation-validator` subagent:
|
||||
- `subagent_type`: "implementation-validator"
|
||||
- `description`: "Milestone implementation validation"
|
||||
- `prompt`: "Please validate the quality of all changes implemented for milestone `[NN] [name]`. The target files are `[list of implemented file paths]`. Focus on coding standards, error handling, testability, consistency with existing patterns, and whether every feature's acceptance criteria in `.steering/[dir]/requirements.md` are met."
|
||||
|
||||
#### 2.6 Run Automated Tests
|
||||
|
||||
```bash
|
||||
npm test
|
||||
npm run lint
|
||||
npm run typecheck
|
||||
```
|
||||
|
||||
If any command fails, analyze, fix, and re-run until all pass.
|
||||
|
||||
#### 2.7 Retrospective and Document Reconciliation
|
||||
|
||||
Apply `/add-feature` Step 8 for the milestone:
|
||||
|
||||
1. Follow the **steering** skill in **retrospective mode**; record handover notes in this milestone's `tasklist.md`.
|
||||
2. Reconcile all six persistent documents in `docs/` with everything implemented in this milestone (updates applied, or a skip reason noted for each).
|
||||
3. In the milestone document: check off every feature (`[ ]` → `[x]`), set the status to `Completed`, and fill in the "Completion Notes".
|
||||
4. In `docs/milestones/roadmap.md`: set this milestone's status to `Completed` and move the current-milestone pointer to the next milestone in the queue (or mark the roadmap complete).
|
||||
|
||||
#### 2.8 Milestone Gate — then Continue
|
||||
|
||||
The milestone is done only when: all tasks are `[x]`, validation passed, tests/lint/typecheck are green, the six documents are reconciled, and the milestone + roadmap statuses are updated.
|
||||
|
||||
**Once the gate passes, never stop; immediately start Step 2 for the next milestone in the queue.** If the gate genuinely cannot be passed (external blocker), record the blocker in the milestone's `tasklist.md` and in `roadmap.md`, then stop and report — this is the only permitted early stop.
|
||||
|
||||
### Step 3: Final Report
|
||||
|
||||
When the queue is empty, report per milestone: steering directory created, features implemented, test results, and document updates.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
- Every milestone in the execution queue has status `Completed` in `docs/milestones/roadmap.md`.
|
||||
- Each executed milestone has its own `.steering/[date]-milestone-[NN]-[name]/` directory with all tasks `[x]`.
|
||||
- Tests, lint, and typecheck pass on the final state.
|
||||
- The six persistent documents reflect everything implemented.
|
||||
|
||||
Completion message:
|
||||
```
|
||||
"Milestone execution is complete!
|
||||
|
||||
Executed:
|
||||
✅ Milestone 01 [name] — .steering/[date]-milestone-01-[name]/ ([n] features, [m] tasks)
|
||||
✅ Milestone NN [name] — .steering/[date]-milestone-NN-[name]/ ([n] features, [m] tasks)
|
||||
|
||||
All statuses updated in docs/milestones/roadmap.md.
|
||||
|
||||
Next steps:
|
||||
- Review the retrospectives in each milestone's tasklist.md
|
||||
- Run the app and verify the milestones end-to-end
|
||||
- Re-run /plan-milestones if the remaining roadmap should change
|
||||
"
|
||||
```
|
||||
151
.opencode/command/generate-app.md
Normal file
151
.opencode/command/generate-app.md
Normal file
@ -0,0 +1,151 @@
|
||||
---
|
||||
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
|
||||
|
||||
- If the target is `web` and the repo has `npm test`, `npm run lint`, `npm run typecheck`, run them and fix any errors caused by the generated code.
|
||||
- For `flutter` / `winui3`, run the platform's available static checks if the toolchain is present; 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
|
||||
|
||||
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
|
||||
"
|
||||
```
|
||||
143
.opencode/command/plan-milestones.md
Normal file
143
.opencode/command/plan-milestones.md
Normal file
@ -0,0 +1,143 @@
|
||||
---
|
||||
description: Plan development milestones and generate milestone documents with the features for each milestone
|
||||
agent: build
|
||||
---
|
||||
|
||||
# Plan Milestones (Milestone Planning Phase)
|
||||
|
||||
This command breaks the product down into an ordered set of **milestones** and generates milestone documents under `docs/milestones/`. Each milestone document lists the features it contains, sized so that each feature can be implemented with one `/add-feature` run.
|
||||
|
||||
**Planning preferences (optional)**: `$ARGUMENTS` (e.g. `/plan-milestones 3 milestones, MVP in 2 weeks, auth first`)
|
||||
|
||||
## How to Run
|
||||
|
||||
```
|
||||
opencode
|
||||
> /plan-milestones
|
||||
> /plan-milestones 3 milestones, MVP first, payments last
|
||||
```
|
||||
|
||||
## Position in the Workflow
|
||||
|
||||
```
|
||||
/setup-project
|
||||
↓
|
||||
/define-design
|
||||
↓
|
||||
/generate-app web | flutter | winui3
|
||||
↓
|
||||
/plan-milestones ← you are here
|
||||
↓
|
||||
/add-feature (once per feature, milestone by milestone)
|
||||
```
|
||||
|
||||
## Pre-Run Check
|
||||
|
||||
1. Confirm the persistent documents exist. If any of these are missing, stop and tell the user to run `/setup-project` first:
|
||||
- `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.
|
||||
3. Create the milestones directory if it does not exist:
|
||||
```bash
|
||||
mkdir -p docs/milestones
|
||||
```
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 0: Read the Inputs
|
||||
|
||||
Read all of the following:
|
||||
|
||||
- `docs/product-requirements.md` (especially user stories and priorities)
|
||||
- `docs/functional-design.md`
|
||||
- `docs/architecture.md`
|
||||
- `docs/design/ui-blueprint.json` and `docs/design/design-brief.md` (if present)
|
||||
- `docs/ideas/*` (if present)
|
||||
- The planning preferences provided in `$ARGUMENTS` (if any)
|
||||
|
||||
### Step 1: Gather Planning Preferences (ask the user once)
|
||||
|
||||
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.
|
||||
|
||||
- **Number of milestones** (default: 2–4 depending on scope)
|
||||
- **MVP definition** — what is the smallest product worth releasing?
|
||||
- **Priorities** — features that must come first or last
|
||||
- **Constraints** — deadlines, dependencies on external systems, team capacity
|
||||
|
||||
Collect the answers in a single round; do not pause again until generation is complete.
|
||||
|
||||
### Step 2: Load the Milestone Planning Skill
|
||||
|
||||
Follow the **milestone-planning** skill (loaded automatically) for the planning rules and the milestone document template.
|
||||
|
||||
### Step 3: Build the Feature Inventory
|
||||
|
||||
Derive the complete list of features from the documents:
|
||||
|
||||
- Every user story / requirement in the PRD (with its priority)
|
||||
- Every functional module in the functional design
|
||||
- Every screen and user action in `ui-blueprint.json` (if present)
|
||||
|
||||
Size each feature so it can be implemented with **one `/add-feature` run**. Split anything larger; merge trivial fragments.
|
||||
|
||||
### Step 4: Group Features into Milestones
|
||||
|
||||
- **Milestone 1 is the MVP**: the smallest set of features that forms a coherent, end-to-end usable product.
|
||||
- Later milestones build on earlier ones, ordered by priority and dependency (a feature never lands before something it depends on).
|
||||
- Every feature belongs to **exactly one** milestone. Explicitly park out-of-scope items in a final "Later / Icebox" section of the roadmap.
|
||||
|
||||
### Step 5: Create the Roadmap Overview
|
||||
|
||||
Create `docs/milestones/roadmap.md` containing:
|
||||
|
||||
- A table of all milestones: number, name, goal, feature count, status (`Not started` / `In progress` / `Completed`)
|
||||
- The ordering rationale (why this sequence)
|
||||
- A pointer to the current milestone
|
||||
- The "Later / Icebox" list of consciously deferred items
|
||||
|
||||
### Step 6: Create One Document per Milestone
|
||||
|
||||
For each milestone, create `docs/milestones/milestone-[NN]-[kebab-case-name].md` (e.g. `milestone-01-mvp.md`) following the milestone-planning skill's template. Each document lists the milestone's features, and each feature includes:
|
||||
|
||||
- A checkbox for status tracking (`- [ ]`)
|
||||
- Description and user value
|
||||
- Related PRD requirements / user stories
|
||||
- Affected screens from `ui-blueprint.json` (if a design spec exists)
|
||||
- Acceptance criteria
|
||||
- The ready-to-run command: `/add-feature [feature name]`
|
||||
|
||||
### Step 7: Consistency Check
|
||||
|
||||
Re-read all generated files and confirm:
|
||||
|
||||
- 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.
|
||||
- Dependencies are ordered correctly across milestones.
|
||||
- Milestone 1 is a coherent, usable MVP on its own.
|
||||
- Each feature name works as a `/add-feature` argument.
|
||||
|
||||
Fix any inconsistencies found before finishing.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
- `docs/milestones/roadmap.md` exists
|
||||
- One `milestone-[NN]-[name].md` per milestone exists
|
||||
- Every feature is assigned to exactly one milestone with acceptance criteria
|
||||
|
||||
Completion message:
|
||||
```
|
||||
"Milestone planning is complete!
|
||||
|
||||
Milestone documents created:
|
||||
✅ docs/milestones/roadmap.md (overview + status)
|
||||
✅ docs/milestones/milestone-01-....md (MVP)
|
||||
✅ docs/milestones/milestone-NN-....md
|
||||
|
||||
Next steps:
|
||||
- Review docs/milestones/ and adjust priorities if needed
|
||||
- Run /execute-milestones to implement all milestones one by one autonomously (a separate steering directory is created per milestone)
|
||||
- Or go feature by feature: run /add-feature [first feature of milestone 1]
|
||||
- Either way, each feature is marked complete in its milestone document as it finishes
|
||||
"
|
||||
```
|
||||
90
.opencode/command/update-design.md
Normal file
90
.opencode/command/update-design.md
Normal file
@ -0,0 +1,90 @@
|
||||
---
|
||||
description: Refine the design before /generate-app, 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.
|
||||
|
||||
**Change description**: `$ARGUMENTS` (e.g. `/update-design add a profile screen with avatar and edit form`)
|
||||
|
||||
## How to Run
|
||||
|
||||
```
|
||||
opencode
|
||||
> /update-design add a profile screen with avatar and edit form
|
||||
```
|
||||
|
||||
## Pre-Run Check
|
||||
|
||||
Confirm the design files exist. If they 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`
|
||||
|
||||
## Procedure
|
||||
|
||||
### Step 0: Read the Inputs
|
||||
|
||||
Read:
|
||||
|
||||
- The existing design files listed above
|
||||
- `docs/product-requirements.md` and `docs/functional-design.md` for context
|
||||
- The change description provided in `$ARGUMENTS`
|
||||
|
||||
### Step 1: Update `ui-blueprint.json` First
|
||||
|
||||
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.
|
||||
|
||||
### 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.
|
||||
|
||||
### Step 3: Update `design-brief.md` (if the direction changes)
|
||||
|
||||
If the change affects the overall design direction (visual mood, layout principles, navigation principles, accessibility), update the brief. If it is a localized screen/component change, leave the brief unchanged.
|
||||
|
||||
### Step 4: Update `platform-mapping.md` (if needed)
|
||||
|
||||
If the change introduces a new platform target or a new kind of mapping (e.g. a new component family that maps differently per platform), update the mapping. Otherwise leave it unchanged.
|
||||
|
||||
### Step 5: Regenerate Affected SVG Wireframes
|
||||
|
||||
For every screen added or modified in `ui-blueprint.json`, generate or regenerate the corresponding SVG under `docs/design/screens/`. Remember: SVGs are visual references only — the blueprint is the source of truth.
|
||||
|
||||
### Step 6: Consistency Check
|
||||
|
||||
- Every screen in `ui-blueprint.json` has a matching SVG.
|
||||
- Token names referenced in the blueprint exist in `design-tokens.json`.
|
||||
- The brief and mapping remain consistent with the blueprint.
|
||||
|
||||
### Step 7: Do Not Implement Code
|
||||
|
||||
Do **not** modify application code in this command. If the user also wants the code updated, they should run `/add-feature` (which reads the updated design files) or ask explicitly.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
- `ui-blueprint.json` has been updated (source of truth).
|
||||
- `design-tokens.json` updated only if new tokens were needed.
|
||||
- `design-brief.md` updated only if the direction changed.
|
||||
- `platform-mapping.md` updated only if mappings changed.
|
||||
- Affected SVG wireframes regenerated.
|
||||
- No application code was changed.
|
||||
|
||||
Completion message:
|
||||
```
|
||||
"Design has been updated.
|
||||
|
||||
Updated:
|
||||
✅ docs/design/ui-blueprint.json (source of truth)
|
||||
✅ docs/design/design-tokens.json (if new tokens were needed)
|
||||
✅ docs/design/design-brief.md (if the direction changed)
|
||||
✅ docs/design/platform-mapping.md (if mappings changed)
|
||||
✅ docs/design/screens/*.svg (regenerated as needed)
|
||||
|
||||
Note: application code was not changed. Run /add-feature to implement the change, respecting the updated design.
|
||||
"
|
||||
```
|
||||
137
.opencode/skills/design-tokens/SKILL.md
Normal file
137
.opencode/skills/design-tokens/SKILL.md
Normal file
@ -0,0 +1,137 @@
|
||||
---
|
||||
name: design-tokens
|
||||
description: Guide for creating and maintaining design-tokens.json, the single source of styling values for Web, Flutter, and WinUI 3. Use when creating or updating design tokens.
|
||||
---
|
||||
|
||||
# Design Tokens Skill
|
||||
|
||||
This skill explains how to create and maintain `docs/design/design-tokens.json` — the single source of truth for all styling values (color, typography, spacing, radius, shadow, motion, breakpoints). Generated platform code must read from these tokens and must never hard-code values.
|
||||
|
||||
## Core Principle
|
||||
|
||||
> One token definition → many platform outputs. Never hard-code a color, size, or spacing in generated code.
|
||||
|
||||
## Format
|
||||
|
||||
Use a JSON structure inspired by the Design Tokens Community Group format. Every token is an object with `$type` and `$value`:
|
||||
|
||||
```json
|
||||
{
|
||||
"color": {
|
||||
"background": {
|
||||
"primary": { "$type": "color", "$value": "#0F172A" }
|
||||
}
|
||||
},
|
||||
"spacing": {
|
||||
"md": { "$type": "dimension", "$value": "16px" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Supported `$type` values: `color`, `dimension`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `number`, `strokeStyle`.
|
||||
|
||||
## Token Groups
|
||||
|
||||
`design-tokens.json` should include these groups (omit a group only if it truly does not apply):
|
||||
|
||||
- **color** — semantic color tokens
|
||||
- **typography** — font families, sizes, weights, line heights
|
||||
- **spacing** — spacing scale (xs, sm, md, lg, xl, …)
|
||||
- **radius** — border radius scale
|
||||
- **shadow** / **elevation** — box-shadow / elevation tokens
|
||||
- **motion** — animation durations and easings
|
||||
- **breakpoint** — responsive breakpoints (include when `web` is a target)
|
||||
|
||||
## Rules
|
||||
|
||||
### Naming tokens
|
||||
|
||||
- Use **semantic names**, not descriptive names. `color.text.primary` (good) vs `color.slate-900` (bad).
|
||||
- Use a consistent scale for numeric families: `sm`, `md`, `lg`, `xl` — or numeric `4`, `8`, `12` — pick one and stick to it.
|
||||
- Group by role then by emphasis: `color.background.primary`, `color.background.muted`, `color.text.primary`, `color.text.secondary`, `color.accent.primary`, `color.state.success`, `color.state.danger`.
|
||||
- Token names are referenced verbatim in `ui-blueprint.json` (e.g. `"padding": "lg"`). They must match exactly.
|
||||
|
||||
### Using semantic color names
|
||||
|
||||
- Define colors by **role** (background, text, accent, border, state, overlay) and **emphasis** (primary, secondary, muted).
|
||||
- Do not expose raw hex scales as the only option. If you need a raw scale, keep it in a separate `color.palette` group and reference it from semantic tokens.
|
||||
- Provide both light and dark values where the app supports them: `color.background.primary` (light) and `color.background.primary-dark`, or a `dark` sub-object — pick one convention and document it in `platform-mapping.md`.
|
||||
|
||||
### Avoiding hard-coded values in generated code
|
||||
|
||||
- Generated Web code uses CSS variables / Tailwind theme keys / theme objects derived from tokens.
|
||||
- Generated Flutter code uses `ThemeData`, `ColorScheme`, and constants derived from tokens.
|
||||
- Generated WinUI 3 code uses `ResourceDictionary` entries derived from tokens.
|
||||
- **Never** inline `#0F172A` or `16px` in generated source. Always reference the token-derived variable/resource.
|
||||
- If a value is needed that has no token, add the token to `design-tokens.json` first, then use it.
|
||||
|
||||
### Mapping tokens to platform-specific code
|
||||
|
||||
`design-tokens.json` is platform-agnostic. The conversion to each platform is documented in `docs/design/platform-mapping.md` and performed by the **platform-ui-generation** skill. This skill only defines and maintains the tokens.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
{
|
||||
"color": {
|
||||
"background": {
|
||||
"primary": { "$type": "color", "$value": "#0F172A" },
|
||||
"muted": { "$type": "color", "$value": "#1E293B" }
|
||||
},
|
||||
"text": {
|
||||
"primary": { "$type": "color", "$value": "#F8FAFC" },
|
||||
"secondary": { "$type": "color", "$value": "#94A3B8" }
|
||||
},
|
||||
"accent": {
|
||||
"primary": { "$type": "color", "$value": "#38BDF8" }
|
||||
},
|
||||
"state": {
|
||||
"success": { "$type": "color", "$value": "#22C55E" },
|
||||
"danger": { "$type": "color", "$value": "#EF4444" }
|
||||
}
|
||||
},
|
||||
"typography": {
|
||||
"fontFamily": {
|
||||
"base": { "$type": "fontFamily", "$value": "Inter, system-ui, sans-serif" }
|
||||
},
|
||||
"size": {
|
||||
"sm": { "$type": "dimension", "$value": "14px" },
|
||||
"md": { "$type": "dimension", "$value": "16px" },
|
||||
"lg": { "$type": "dimension", "$value": "20px" }
|
||||
}
|
||||
},
|
||||
"spacing": {
|
||||
"sm": { "$type": "dimension", "$value": "8px" },
|
||||
"md": { "$type": "dimension", "$value": "16px" },
|
||||
"lg": { "$type": "dimension", "$value": "24px" }
|
||||
},
|
||||
"radius": {
|
||||
"card": { "$type": "dimension", "$value": "16px" },
|
||||
"pill": { "$type": "dimension", "$value": "9999px" }
|
||||
},
|
||||
"shadow": {
|
||||
"card": { "$type": "shadow", "$value": "0 4px 12px rgba(0,0,0,0.15)" }
|
||||
},
|
||||
"motion": {
|
||||
"duration": {
|
||||
"fast": { "$type": "duration", "$value": "120ms" },
|
||||
"base": { "$type": "duration", "$value": "200ms" }
|
||||
}
|
||||
},
|
||||
"breakpoint": {
|
||||
"sm": { "$type": "dimension", "$value": "640px" },
|
||||
"md": { "$type": "dimension", "$value": "768px" },
|
||||
"lg": { "$type": "dimension", "$value": "1024px" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Maintenance Checklist
|
||||
|
||||
When updating tokens:
|
||||
|
||||
- [ ] JSON is valid.
|
||||
- [ ] Token names referenced in `ui-blueprint.json` still exist (no broken references after a rename).
|
||||
- [ ] New tokens follow the naming and semantic-name rules.
|
||||
- [ ] No duplicate tokens (same role under two names).
|
||||
- [ ] `platform-mapping.md` still covers how every token group maps to each target platform.
|
||||
91
.opencode/skills/milestone-execution/SKILL.md
Normal file
91
.opencode/skills/milestone-execution/SKILL.md
Normal file
@ -0,0 +1,91 @@
|
||||
---
|
||||
name: milestone-execution
|
||||
description: Guide for executing milestones one by one - creating a separate steering directory per milestone, dividing the milestone's features into tasks, and enforcing gate criteria between milestones. Use when running /execute-milestones or implementing a whole milestone in one run.
|
||||
---
|
||||
|
||||
# Milestone Execution Skill
|
||||
|
||||
This skill explains how to execute the milestone plan (`docs/milestones/`) one milestone at a time. Where `/add-feature` implements **one feature** with one steering directory, milestone execution implements **one whole milestone** per steering directory — and processes milestones strictly in roadmap order.
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **One milestone = one steering directory**: every milestone gets its own `.steering/[YYYYMMDD]-milestone-[NN]-[name]/` with its own `requirements.md`, `design.md`, and `tasklist.md`. Documents are never shared or reused between milestones.
|
||||
2. **Strict order, one at a time**: milestones execute in ascending number. A milestone starts only after the previous one passed its gate. Never interleave tasks from two milestones.
|
||||
3. **Features divided into tasks**: the milestone's features (from its milestone document) are broken down into concrete tasks in `tasklist.md`, grouped by feature. The milestone document stays the "what"; the steering tasklist is the "how".
|
||||
4. **Same discipline as `/add-feature`**: the steering skill's implementation mode, the development guidelines, the validator subagent, and the test loop all apply per milestone.
|
||||
5. **Status flows upward**: task status lives in the steering `tasklist.md`; feature and milestone status live in `docs/milestones/`. When a milestone's last task completes, check off its features, mark the milestone `Completed`, and advance the roadmap pointer.
|
||||
|
||||
## Steering Directory per Milestone
|
||||
|
||||
Naming: `.steering/[YYYYMMDD]-milestone-[NN]-[kebab-case-name]/` (e.g. `.steering/20260702-milestone-01-mvp/`).
|
||||
|
||||
### `requirements.md`
|
||||
- Milestone goal (from the milestone document)
|
||||
- In/out of scope
|
||||
- One section per feature: description, related PRD requirements, affected screens, acceptance criteria
|
||||
- The milestone's Definition of Done
|
||||
|
||||
### `design.md`
|
||||
- Implementation approach across the whole milestone
|
||||
- Shared components and data-model changes used by multiple features (build these first)
|
||||
- Feature implementation order within the milestone, with a one-line rationale
|
||||
- Consistency notes against `docs/architecture.md` and `docs/design/ui-blueprint.json`
|
||||
|
||||
### `tasklist.md`
|
||||
Tasks are **grouped by feature**, in the implementation order chosen in `design.md`:
|
||||
|
||||
```markdown
|
||||
# Tasklist: Milestone 01 — MVP
|
||||
|
||||
## Shared Foundations
|
||||
- [ ] [Task that multiple features depend on, e.g. data model, shared component]
|
||||
|
||||
## Feature: Register account
|
||||
- [ ] [Task 1: data/model layer]
|
||||
- [ ] [Task 2: logic/service layer]
|
||||
- [ ] [Task 3: UI per affected screen]
|
||||
- [ ] [Task 4: tests for the acceptance criteria]
|
||||
|
||||
## Feature: Log in / log out
|
||||
- [ ] ...
|
||||
|
||||
## Milestone Verification
|
||||
- [ ] All acceptance criteria in requirements.md confirmed
|
||||
- [ ] npm test / lint / typecheck pass
|
||||
|
||||
## Post-Implementation Retrospective
|
||||
_Filled at the end: completion date, plan vs. actual, lessons learned._
|
||||
```
|
||||
|
||||
## How to Divide a Feature into Tasks
|
||||
|
||||
- 3–8 tasks per feature; each completable in **one implementation-loop iteration**.
|
||||
- Slice along the natural layers the feature touches: data/model → logic/service → UI (one task per affected screen) → tests.
|
||||
- Every feature's section ends with a task that verifies its acceptance criteria.
|
||||
- Tasks that unblock several features go into a "Shared Foundations" section at the top — never duplicated per feature.
|
||||
|
||||
## Gate Criteria Between Milestones
|
||||
|
||||
A milestone passes its gate only when **all** of the following hold. Only then may the next milestone start:
|
||||
|
||||
- [ ] Every task in the milestone's `tasklist.md` is `[x]` (or struck with a technical reason).
|
||||
- [ ] The `implementation-validator` subagent's validation passed.
|
||||
- [ ] `npm test`, `npm run lint`, `npm run typecheck` all succeed.
|
||||
- [ ] The six persistent documents in `docs/` are reconciled with the milestone's changes.
|
||||
- [ ] In `docs/milestones/`: every feature is checked off, the milestone status is `Completed` with Completion Notes, and `roadmap.md` points to the next milestone.
|
||||
|
||||
## Failure Handling
|
||||
|
||||
- **A task fails repeatedly**: split it (exception rule A) or re-approach via `design.md`; do not skip it.
|
||||
- **A feature turns out to be unimplementable as specified**: update the milestone document and `requirements.md` with the revised scope and reason, then continue — the plan must reflect reality.
|
||||
- **An external blocker stops the milestone** (missing credential, unavailable service, a decision only the user can make): record the blocker in the milestone's `tasklist.md` and in `roadmap.md` (status stays `In progress`), then stop and report. This is the **only** permitted early stop; never silently skip to the next milestone, because later milestones depend on earlier ones.
|
||||
|
||||
## Consistency Checklist
|
||||
|
||||
Before declaring a milestone (or the whole run) complete:
|
||||
|
||||
- [ ] Each executed milestone has exactly one steering directory, named `[date]-milestone-[NN]-[name]`.
|
||||
- [ ] Every feature of the milestone appears as a section in that `tasklist.md`.
|
||||
- [ ] Feature checkboxes in the milestone document match the completed work.
|
||||
- [ ] `roadmap.md` statuses and current-milestone pointer are correct.
|
||||
- [ ] No task or feature from a later milestone was implemented early.
|
||||
79
.opencode/skills/milestone-planning/SKILL.md
Normal file
79
.opencode/skills/milestone-planning/SKILL.md
Normal file
@ -0,0 +1,79 @@
|
||||
---
|
||||
name: milestone-planning
|
||||
description: Guide for planning development milestones and generating milestone documents with a feature breakdown. Use when planning milestones, a release roadmap, or deciding implementation order under docs/milestones/.
|
||||
---
|
||||
|
||||
# Milestone Planning Skill
|
||||
|
||||
This skill explains how to break a product into ordered milestones and produce milestone documents under `docs/milestones/`. The documents are the bridge between the specification (`docs/`) and implementation (`/add-feature`): every feature in every milestone is sized to be implemented with **one `/add-feature` run**.
|
||||
|
||||
## Core Principles
|
||||
|
||||
1. **MVP first**: Milestone 1 is 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. **Dependency order**: A feature never lands in an earlier milestone than something it depends on.
|
||||
5. **Exactly-once assignment**: Every feature belongs to exactly one milestone. Deliberately deferred items go to the roadmap's "Later / Icebox" — nothing silently disappears.
|
||||
6. **Living documents**: Milestone documents track status. `/add-feature` checks off a feature (`[ ]` → `[x]`) when it completes, and the roadmap status is updated when a milestone finishes.
|
||||
|
||||
## Inputs
|
||||
|
||||
Before planning, read:
|
||||
|
||||
- `docs/product-requirements.md` — user stories, priorities (P0/P1/P2), success metrics
|
||||
- `docs/functional-design.md` — functional modules and data flows
|
||||
- `docs/architecture.md` — technical constraints and dependencies
|
||||
- `docs/design/ui-blueprint.json` (if present) — screens and user actions
|
||||
- `docs/ideas/*` (if present)
|
||||
|
||||
## Outputs
|
||||
|
||||
```
|
||||
docs/milestones/
|
||||
├── roadmap.md # Overview: milestone table, ordering rationale, icebox
|
||||
├── milestone-01-[name].md # MVP
|
||||
├── milestone-02-[name].md
|
||||
└── milestone-NN-[name].md
|
||||
```
|
||||
|
||||
File naming: `milestone-[NN]-[kebab-case-name].md` (e.g. `milestone-01-mvp.md`, `milestone-02-collaboration.md`).
|
||||
|
||||
Use the structure in `template.md` for each milestone document.
|
||||
|
||||
## How to Slice Features
|
||||
|
||||
A well-sized feature:
|
||||
|
||||
- Delivers observable user value (or unblocks one that does)
|
||||
- Touches one primary screen/flow (may touch shared components)
|
||||
- Has 3–7 acceptance criteria
|
||||
- Can be described in one sentence starting with a verb ("Edit user profile", "Filter tasks by tag")
|
||||
- Works verbatim as a command argument: `/add-feature Edit user profile`
|
||||
|
||||
Too big (split it): "User management" → "Register account", "Log in / log out", "Edit user profile", "Reset password".
|
||||
Too small (merge it): "Change button color" → fold into the feature that owns that screen.
|
||||
|
||||
## How to Group Milestones
|
||||
|
||||
1. Tag every feature with its PRD priority and its dependencies.
|
||||
2. Milestone 1 (MVP): 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 release on its own ("after milestone N ships, the user can additionally …").
|
||||
4. Prefer 2–4 milestones with 3–8 features each. More than ~8 features in one milestone usually means it should be split.
|
||||
|
||||
## Status Tracking Rules
|
||||
|
||||
- Feature status lives **only** in the feature checkbox of its milestone document.
|
||||
- Milestone status (`Not started` / `In progress` / `Completed`) lives in both the milestone document header and the roadmap table — keep them in sync.
|
||||
- `/add-feature` Step 8 updates the feature checkbox and, when the last feature of a milestone completes, the milestone and roadmap statuses.
|
||||
- Re-planning (adding/moving/removing features) must update both the milestone document(s) and `roadmap.md` in the same change.
|
||||
|
||||
## Consistency Checklist
|
||||
|
||||
Before finishing:
|
||||
|
||||
- [ ] 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.
|
||||
- [ ] No feature precedes one of its dependencies.
|
||||
- [ ] Milestone 1 is a usable end-to-end product on its own.
|
||||
- [ ] Every feature has acceptance criteria and a ready-to-run `/add-feature` command line.
|
||||
- [ ] `roadmap.md` table matches the milestone documents (names, counts, statuses).
|
||||
88
.opencode/skills/milestone-planning/template.md
Normal file
88
.opencode/skills/milestone-planning/template.md
Normal file
@ -0,0 +1,88 @@
|
||||
# Milestone Document Template
|
||||
|
||||
Use this structure for each `docs/milestones/milestone-[NN]-[name].md`.
|
||||
|
||||
```markdown
|
||||
# Milestone [NN]: [Name]
|
||||
|
||||
**Status**: Not started | In progress | Completed
|
||||
**Goal**: [One sentence: what the user can do after this milestone that they could not before]
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope
|
||||
- [Theme or capability included in this milestone]
|
||||
|
||||
### Out of Scope
|
||||
- [Explicitly excluded item] → [where it lives instead: milestone NN / icebox]
|
||||
|
||||
## Dependencies
|
||||
|
||||
- [What must exist before this milestone can start: previous milestone, external system, decision]
|
||||
|
||||
## Features
|
||||
|
||||
> One `/add-feature` run per feature. Check off each feature when its run completes.
|
||||
|
||||
- [ ] [Feature 1 name]
|
||||
- [ ] [Feature 2 name]
|
||||
- [ ] [Feature 3 name]
|
||||
|
||||
### Feature: [Feature 1 name]
|
||||
|
||||
- **Description**: [What it does and the user value, 1–3 sentences]
|
||||
- **Related requirements**: [PRD user story / requirement IDs or headings]
|
||||
- **Affected screens**: [screen ids from ui-blueprint.json, or "n/a"]
|
||||
- **Acceptance criteria**:
|
||||
- [Criterion 1]
|
||||
- [Criterion 2]
|
||||
- [Criterion 3]
|
||||
- **Command**: `/add-feature [Feature 1 name]`
|
||||
|
||||
### Feature: [Feature 2 name]
|
||||
|
||||
- **Description**: ...
|
||||
- **Related requirements**: ...
|
||||
- **Affected screens**: ...
|
||||
- **Acceptance criteria**:
|
||||
- ...
|
||||
- **Command**: `/add-feature [Feature 2 name]`
|
||||
|
||||
## Definition of Done
|
||||
|
||||
- [ ] All features above are checked off
|
||||
- [ ] `npm test`, `npm run lint`, `npm run typecheck` pass
|
||||
- [ ] Persistent documents in `docs/` are reconciled with all features
|
||||
- [ ] [Milestone-specific criterion, e.g. "demo flow X→Y→Z works end-to-end"]
|
||||
|
||||
## Completion Notes
|
||||
|
||||
_Filled in when the milestone completes: completion date, deviations from plan, lessons learned._
|
||||
```
|
||||
|
||||
# Roadmap Template
|
||||
|
||||
Use this structure for `docs/milestones/roadmap.md`.
|
||||
|
||||
```markdown
|
||||
# Development Roadmap
|
||||
|
||||
**Current milestone**: [NN — name]
|
||||
|
||||
## Milestones
|
||||
|
||||
| # | Name | Goal | Features | Status |
|
||||
|---|------|------|----------|--------|
|
||||
| 01 | [name] | [one-line goal] | [count] | Not started / In progress / Completed |
|
||||
| 02 | [name] | [one-line goal] | [count] | Not started |
|
||||
|
||||
## Ordering Rationale
|
||||
|
||||
[Why this sequence: MVP definition, dependency chains, priority decisions made with the user]
|
||||
|
||||
## Later / Icebox
|
||||
|
||||
Consciously deferred — revisit when re-planning:
|
||||
|
||||
- [Deferred item] — [why deferred]
|
||||
```
|
||||
112
.opencode/skills/platform-ui-generation/SKILL.md
Normal file
112
.opencode/skills/platform-ui-generation/SKILL.md
Normal file
@ -0,0 +1,112 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
## 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`.
|
||||
5. **Respect the platform mapping**: `docs/design/platform-mapping.md` documents how each artifact maps to each platform.
|
||||
|
||||
## Inputs
|
||||
|
||||
- `docs/design/design-brief.md` — direction
|
||||
- `docs/design/design-tokens.json` — values
|
||||
- `docs/design/ui-blueprint.json` — structure (source of truth)
|
||||
- `docs/design/platform-mapping.md` — per-platform conversion rules
|
||||
- `docs/architecture.md` — technology choices (framework, language)
|
||||
|
||||
## General Conversion Rules
|
||||
|
||||
- One screen in the blueprint → one screen/page in the target platform.
|
||||
- One route in the blueprint → one route entry in the navigation config.
|
||||
- A reusable component referenced in multiple screens → a shared component file/widget/control.
|
||||
- Component `variant` → a variant/style modifier on the shared component.
|
||||
- Component `state` → visual states the component must support (default, hover, pressed, disabled, etc.).
|
||||
- `action: navigate:<screen-id>` → navigation to the corresponding route.
|
||||
- Other `action:` values → wire to a handler/placeholder; do not implement feature logic.
|
||||
|
||||
## Web Mapping
|
||||
|
||||
- **design tokens →** CSS variables, a Tailwind config, or a theme object.
|
||||
- `color.*` → CSS custom properties (`--color-background-primary`) or Tailwind theme colors.
|
||||
- `spacing.*`, `radius.*`, `typography.*` → CSS variables / Tailwind theme keys.
|
||||
- `breakpoint.*` → responsive breakpoints.
|
||||
- **ui-blueprint →**
|
||||
- `screens` → pages/routes.
|
||||
- `layout` → layout components (vertical/horizontal stack, grid).
|
||||
- `components` → React (or framework) components, one file per reusable component.
|
||||
- Use **semantic HTML** (`<header>`, `<main>`, `<nav>`, `<button>`, `<label>`) where possible.
|
||||
- Respect responsive layout requirements using the breakpoint tokens.
|
||||
- If no framework is specified in `architecture.md`, choose a simple default suitable for the repository and note the choice.
|
||||
|
||||
## Flutter Mapping
|
||||
|
||||
- **design tokens →**
|
||||
- `color.*` → `ColorScheme` + a color constants file.
|
||||
- `typography.*` → `TextTheme` / text styles.
|
||||
- `spacing.*`, `radius.*` → constants (`spacing_md`, `radiusCard`).
|
||||
- `shadow.*` → `BoxShadow` / elevation.
|
||||
- `motion.duration.*` → `Duration` constants.
|
||||
- Assemble into a `ThemeData`.
|
||||
- **ui-blueprint →**
|
||||
- `screens` → `Screen` widgets + routes (named routes or a router).
|
||||
- `layout.type` → `Column` / `Row` / `Wrap` / `ListView` with `padding` and `SizedBox` gaps from spacing tokens.
|
||||
- `components` → reusable widgets, one file per widget.
|
||||
- Keep clean separation between: `screens/`, `widgets/`, `theme/`, `models/`, `services/`.
|
||||
|
||||
## WinUI 3 Mapping
|
||||
|
||||
- **design tokens →**
|
||||
- `color.*`, `spacing.*`, `radius.*`, `typography.*` → a `ResourceDictionary` (`.xaml`) with `Color`, `Thickness`, `CornerRadius`, `FontFamily`, `Style` resources.
|
||||
- Assemble theme resources and styles keyed by the token names.
|
||||
- **ui-blueprint →**
|
||||
- `screens` → XAML pages (`Page`).
|
||||
- `layout.type` → `StackPanel` / `Grid` with `Padding`/`Margin` from token resources.
|
||||
- `components` → `UserControl`s, one file per reusable component.
|
||||
- Navigation → `Frame` + navigation entries per route.
|
||||
- Use **C# and XAML**.
|
||||
- Keep UI logic separated from business logic (code-behind stays thin; logic goes to services/viewmodels).
|
||||
|
||||
## Shared Component Contract
|
||||
|
||||
Each generated reusable component must:
|
||||
|
||||
- Accept the `variant` as a parameter/prop/style modifier.
|
||||
- Support the `states` declared in the blueprint (default, hover, pressed, disabled).
|
||||
- Reference tokens for all visual values — no hard-coded literals.
|
||||
- Stay presentational: no feature/business logic.
|
||||
|
||||
## Scaffolding Scope (what `/generate-app` creates)
|
||||
|
||||
- App entry point and shell
|
||||
- Theme/styling system from tokens
|
||||
- Router/navigation config from routes
|
||||
- One screen per blueprint screen (layout + components wired, but no feature logic)
|
||||
- One shared component file per reusable component in `components`
|
||||
|
||||
## Out of Scope (handled by `/add-feature`)
|
||||
|
||||
- Feature/business logic
|
||||
- Data fetching and state management for features
|
||||
- Form validation and submission behavior
|
||||
- Anything not described in the current project documents
|
||||
|
||||
## Generation Checklist
|
||||
|
||||
Before finishing a generation:
|
||||
|
||||
- [ ] Every screen in the blueprint has a corresponding generated screen.
|
||||
- [ ] Every route is wired in the navigation config.
|
||||
- [ ] Every reusable component in `components` has a generated file.
|
||||
- [ ] No hard-coded color/size/spacing in generated code — all from tokens.
|
||||
- [ ] Components accept `variant` and support declared `states`.
|
||||
- [ ] No feature logic was implemented beyond the project documents.
|
||||
- [ ] `docs/repository-structure.md` updated if the layout changed.
|
||||
156
.opencode/skills/ui-design/SKILL.md
Normal file
156
.opencode/skills/ui-design/SKILL.md
Normal file
@ -0,0 +1,156 @@
|
||||
---
|
||||
name: ui-design
|
||||
description: Guide for creating the UI/UX design specification (design brief, UI blueprint JSON, and SVG wireframes). Use when defining or updating the design under docs/design/.
|
||||
---
|
||||
|
||||
# UI Design Skill
|
||||
|
||||
This skill explains how to create an **AI-readable, implementation-ready** UI/UX design specification. It prefers structured, machine-consumable descriptions over vague visual descriptions.
|
||||
|
||||
## Core Principle
|
||||
|
||||
> The source of truth is structured text/JSON. Visual images (SVG) are references for humans, not inputs for code generation.
|
||||
|
||||
Prefer describing **what a component is and how it behaves** over describing **what it looks like**. "A primary button with label 'Save' that triggers `action:save`" is better than "a nice blue button in the corner".
|
||||
|
||||
## Outputs
|
||||
|
||||
This skill produces three 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)
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Before creating the design, read:
|
||||
|
||||
- `docs/product-requirements.md`
|
||||
- `docs/functional-design.md`
|
||||
- `docs/architecture.md`
|
||||
|
||||
The design must serve the product requirements and stay consistent with the functional design.
|
||||
|
||||
## Creating `design-brief.md`
|
||||
|
||||
A concrete, opinionated document. Avoid vague phrases like "modern and clean" without elaboration. Include every section below:
|
||||
|
||||
- **Target users** — who the UI is for, and their key contexts/constraints
|
||||
- **Design concept** — the one-paragraph idea the UI embodies
|
||||
- **Visual mood** — concrete descriptors (density, light/dark, rounding, motion amount)
|
||||
- **Layout principles** — grid, alignment, content width, spacing rhythm
|
||||
- **Navigation principles** — primary navigation pattern, depth, back behavior
|
||||
- **Accessibility considerations** — target contrast, touch-target sizes, focus visibility, font scaling
|
||||
- **Platform-specific notes** — how the design adapts to web / Flutter / WinUI 3
|
||||
- **Examples of preferred UI style** — concrete references and why they fit
|
||||
- **Examples of UI style to avoid** — anti-patterns to stay away from
|
||||
|
||||
## Creating `ui-blueprint.json` (source of truth)
|
||||
|
||||
This is the most important file. It must be valid JSON and fully describe the app's UI structure so that a generator can produce Web, Flutter, or WinUI 3 code without guessing.
|
||||
|
||||
### Required top-level fields
|
||||
|
||||
- `app.name`
|
||||
- `app.platformTargets` — e.g. `["web", "flutter", "winui3"]`
|
||||
- `app.style` — short style summary string
|
||||
- `screens` — array of screen objects
|
||||
- `components` — map of reusable component definitions
|
||||
|
||||
### Screen object shape
|
||||
|
||||
Each screen has:
|
||||
|
||||
- `id` — stable identifier (used as the SVG filename)
|
||||
- `title`
|
||||
- `route`
|
||||
- `layout` — type + spacing tokens (e.g. `{ "type": "vertical", "padding": "lg", "gap": "md" }`)
|
||||
- `components` — a tree of component nodes
|
||||
|
||||
### Component node shape
|
||||
|
||||
Each node has:
|
||||
|
||||
- `type` — e.g. `header`, `card`, `text`, `button`, `list`, `input`, `image`, `nav`
|
||||
- `variant` — optional, must exist in the component's `variants`
|
||||
- `role` — optional semantic role (e.g. `title`, `subtitle`, `body`)
|
||||
- `content` / `label` — text content where applicable
|
||||
- `action` — user action, e.g. `navigate:details`, `submit`, `toggle:filters`
|
||||
- `children` — nested component nodes
|
||||
|
||||
### Reusable component definition
|
||||
|
||||
```json
|
||||
"components": {
|
||||
"button": {
|
||||
"variants": ["primary", "secondary", "ghost"],
|
||||
"states": ["default", "hover", "pressed", "disabled"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Example (excerpt)
|
||||
|
||||
```json
|
||||
{
|
||||
"app": {
|
||||
"name": "Example App",
|
||||
"platformTargets": ["web", "flutter", "winui3"],
|
||||
"style": "friendly, modern, rounded, calm"
|
||||
},
|
||||
"screens": [
|
||||
{
|
||||
"id": "home",
|
||||
"title": "Home",
|
||||
"route": "/",
|
||||
"layout": { "type": "vertical", "padding": "lg", "gap": "md" },
|
||||
"components": [
|
||||
{ "type": "header", "title": "Dashboard", "subtitle": "Welcome back" },
|
||||
{
|
||||
"type": "card",
|
||||
"variant": "primary",
|
||||
"children": [
|
||||
{ "type": "text", "role": "title", "content": "Start here" },
|
||||
{ "type": "button", "label": "Open", "action": "navigate:details" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"components": {
|
||||
"button": {
|
||||
"variants": ["primary", "secondary", "ghost"],
|
||||
"states": ["default", "hover", "pressed", "disabled"]
|
||||
},
|
||||
"card": {
|
||||
"variants": ["primary", "secondary", "danger"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Rules
|
||||
|
||||
- Every `variant` referenced in a screen must exist in `components[type].variants`.
|
||||
- Every spacing/radius/color name referenced in layout/components must exist in `design-tokens.json`.
|
||||
- Use `action:` prefixes consistently: `navigate:<screen-id>`, `submit`, `toggle:<id>`, `open:<id>`, etc.
|
||||
- One screen = one route. Do not overload a screen with multiple routes.
|
||||
- Keep the blueprint free of hard-coded pixel values; reference token names instead.
|
||||
|
||||
## Creating SVG wireframes (`screens/*.svg`)
|
||||
|
||||
- Generate **one SVG per screen**, named `<screen-id>.svg`.
|
||||
- The SVG is a **low-fidelity wireframe**, not a pixel-perfect mock. Use boxes, labels, and placeholders.
|
||||
- It must reflect the component tree of its screen in `ui-blueprint.json`.
|
||||
- **If the blueprint and an SVG disagree, the blueprint wins.** Regenerate the SVG.
|
||||
- SVGs exist only so humans can review the design at a glance.
|
||||
|
||||
## Consistency Checklist
|
||||
|
||||
Before finishing:
|
||||
|
||||
- [ ] 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`.
|
||||
- [ ] The brief and the blueprint describe the same app (same screens, same navigation).
|
||||
- [ ] No hard-coded values in the blueprint.
|
||||
38
AGENTS.md
38
AGENTS.md
@ -78,6 +78,19 @@ Define "what to build" and "how to build it" for the entire application:
|
||||
- **development-guidelines.md** - Development guidelines
|
||||
- **glossary.md** - Ubiquitous language definitions
|
||||
|
||||
#### Design Documents (`docs/design/`)
|
||||
- **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`
|
||||
|
||||
#### Milestone Documents (`docs/milestones/`)
|
||||
- **roadmap.md** - Milestone overview: table, ordering rationale, current milestone, icebox
|
||||
- **milestone-[NN]-[name].md** - One per milestone: goal, scope, and the features it contains (each sized for one `/add-feature` run)
|
||||
- Created by `/plan-milestones`; `/add-feature` checks features off as it completes them
|
||||
|
||||
### Work-Unit Documents (`.steering/`)
|
||||
|
||||
Define "what to do this time" for a specific development task:
|
||||
@ -89,16 +102,22 @@ 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, add-feature, review-docs)
|
||||
- `.opencode/skills/` - Task-specific skills (prd-writing, functional-design, architecture-design, repository-structure, development-guidelines, glossary-creation, steering)
|
||||
- `.opencode/command/` - Slash commands (setup-project, define-design, generate-app, 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, steering)
|
||||
|
||||
## Development Process
|
||||
|
||||
### Initial Setup
|
||||
|
||||
1. Use this template
|
||||
2. Create persistent documents with `/setup-project` (interactively creating six)
|
||||
3. Implement features with `/add-feature [feature]`
|
||||
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 the features for each milestone)
|
||||
7. Implement, either way:
|
||||
- `/execute-milestones` — execute all milestones one by one autonomously (one steering directory per milestone), or
|
||||
- `/add-feature [feature]` — one feature at a time, milestone by milestone
|
||||
|
||||
### Day-to-Day Usage
|
||||
|
||||
@ -113,6 +132,17 @@ Define "what to do this time" for a specific development task:
|
||||
# Adding features (use commands for the standard flow)
|
||||
> /add-feature edit user profile
|
||||
|
||||
# Design phase
|
||||
> /define-design
|
||||
> /generate-app web
|
||||
> /update-design add a profile screen
|
||||
|
||||
# Milestone planning and execution
|
||||
> /plan-milestones
|
||||
> /plan-milestones 3 milestones, MVP first
|
||||
> /execute-milestones
|
||||
> /execute-milestones 1
|
||||
|
||||
# Detailed review (when a detailed report is needed)
|
||||
> /review-docs docs/product-requirements.md
|
||||
```
|
||||
|
||||
215
README.md
215
README.md
@ -9,8 +9,81 @@ documents, per-task steering files, AI skills, subagents, and slash commands.
|
||||
|
||||
---
|
||||
|
||||
## Development Workflow (Step by Step)
|
||||
|
||||
How a project goes from idea to working code with this boilerplate:
|
||||
|
||||
```
|
||||
Idea → /setup-project → /define-design → refine design → /generate-app → /plan-milestones → /add-feature (repeat)
|
||||
```
|
||||
|
||||
### Step 1 — Write down your idea
|
||||
Put your brainstorming notes, requirements, and constraints into
|
||||
`docs/ideas/initial-requirements.md` (free-form; replace the sample content with your own).
|
||||
|
||||
### Step 2 — Create the specification: `/setup-project`
|
||||
Automatically creates the six persistent documents that define **what to build**:
|
||||
PRD, functional design, architecture, repository structure, development guidelines, and glossary
|
||||
(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.
|
||||
|
||||
### 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.
|
||||
|
||||
- `/update-design <change>` — targeted refinements (e.g. `add a profile screen`)
|
||||
- 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`
|
||||
Breaks the product into an ordered set of milestones and generates `docs/milestones/`:
|
||||
a `roadmap.md` overview plus one document per milestone listing **the features it contains** —
|
||||
each sized for exactly one `/add-feature` run, with acceptance criteria and a ready-to-run command.
|
||||
Milestone 1 is the MVP; later milestones build on it by priority and dependency.
|
||||
|
||||
### Step 7 — Implement the milestones
|
||||
|
||||
Two ways to work through the plan:
|
||||
|
||||
**Option A — execute whole milestones: `/execute-milestones`**
|
||||
Runs all remaining milestones **one by one, autonomously**. For each milestone it creates a
|
||||
**separate steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the
|
||||
milestone's features into concrete tasks grouped by feature, implements them all, validates,
|
||||
tests, reconciles the docs, and marks the milestone completed — then immediately starts the next
|
||||
milestone. Takes an optional target (`/execute-milestones 1` or `/execute-milestones 2-3`).
|
||||
|
||||
**Option B — one feature at a time: `/add-feature <feature>`**
|
||||
A fully autonomous loop, one feature per run. Each run:
|
||||
|
||||
1. Creates `.steering/[YYYYMMDD]-[feature]/` (requirements, design, tasklist)
|
||||
2. Reads the feature's milestone document and the design spec first — and updates the design first if the feature changes the UI
|
||||
3. Implements every task in `tasklist.md`, checking items off as it goes
|
||||
4. Validates quality with the `implementation-validator` subagent
|
||||
5. Runs `npm test`, `npm run lint`, `npm run typecheck` until green
|
||||
6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its milestone document
|
||||
|
||||
### Step 8 — Repeat and maintain
|
||||
- Remaining milestones → `/execute-milestones`, 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
|
||||
- Document quality checks → `/review-docs <path>`
|
||||
|
||||
**A feature is "done" when**: all tasks in its tasklist are `[x]`, validation passes,
|
||||
test/lint/typecheck succeed, and the persistent documents are back in sync with the code.
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Development Workflow (Step by Step)](#development-workflow-step-by-step)
|
||||
- [What Is Spec-Driven Development?](#what-is-spec-driven-development)
|
||||
- [Conversion Summary (Claude Code → opencode)](#conversion-summary-claude-code--opencode)
|
||||
- [Prerequisites](#prerequisites)
|
||||
@ -18,6 +91,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 +197,18 @@ 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
|
||||
│ └── milestones/ # Milestone plan (created by /plan-milestones)
|
||||
│ ├── roadmap.md # overview + status
|
||||
│ └── milestone-NN-[name].md # features per milestone
|
||||
│
|
||||
├── .steering/ # Per-task steering files (created by /add-feature)
|
||||
│ └── .gitkeep
|
||||
@ -136,6 +219,11 @@ opencode
|
||||
│ └── implementation-validator.md
|
||||
├── command/ # Slash commands
|
||||
│ ├── setup-project.md
|
||||
│ ├── define-design.md
|
||||
│ ├── generate-app.md
|
||||
│ ├── update-design.md
|
||||
│ ├── plan-milestones.md
|
||||
│ ├── execute-milestones.md
|
||||
│ ├── add-feature.md
|
||||
│ └── review-docs.md
|
||||
└── skills/ # Task-specific skills
|
||||
@ -145,6 +233,11 @@ 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)
|
||||
├── milestone-planning/ (SKILL.md + template.md)
|
||||
├── milestone-execution/ (SKILL.md)
|
||||
└── steering/ (SKILL.md + templates/)
|
||||
```
|
||||
|
||||
@ -203,13 +296,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 +313,50 @@ 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.
|
||||
|
||||
Review and refine the UI/UX **before** generating the app — it is far easier to iterate on the design
|
||||
than on generated code:
|
||||
|
||||
- Re-run `/define-design` to change the overall direction.
|
||||
- Run `/update-design <change>` for targeted refinements (e.g. `/update-design make the home screen denser`).
|
||||
- Iterate until the design — especially `docs/design/ui-blueprint.json` — is approved.
|
||||
|
||||
**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
|
||||
|
||||
```
|
||||
> /plan-milestones
|
||||
> /plan-milestones 3 milestones, MVP first
|
||||
```
|
||||
|
||||
Breaks the product into ordered milestones and generates `docs/milestones/`: a `roadmap.md`
|
||||
overview plus one document per milestone listing the features it contains — each sized for one
|
||||
`/add-feature` run, with acceptance criteria and a ready-to-run command. Milestone 1 is the MVP.
|
||||
You'll be asked once about milestone count, MVP scope, priorities, and constraints; sensible
|
||||
defaults are proposed from the PRD.
|
||||
|
||||
### 5. Add a feature
|
||||
|
||||
```
|
||||
> /add-feature User authentication
|
||||
@ -228,13 +364,29 @@ 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 feature's milestone document (`docs/milestones/`) for scope and acceptance criteria
|
||||
3. Reads the design spec (`docs/design/`) and updates it first if the feature changes the UI
|
||||
4. Generates the steering files (planning mode of the steering skill)
|
||||
5. Implements every task in `tasklist.md`, marking each `[ ]` → `[x]` as it goes
|
||||
6. Launches the `implementation-validator` subagent for quality review
|
||||
7. Runs `npm test`, `npm run lint`, `npm run typecheck`
|
||||
8. Records a retrospective, reconciles all six persistent docs with the feature, and checks the feature off in its milestone document
|
||||
|
||||
### 3. Review a document
|
||||
### 6. Execute all milestones one by one (alternative to per-feature runs)
|
||||
|
||||
```
|
||||
> /execute-milestones # all remaining milestones, in order
|
||||
> /execute-milestones 1 # only milestone 1
|
||||
> /execute-milestones 2-3 # milestones 2 through 3
|
||||
```
|
||||
|
||||
Works through the milestone plan autonomously, one milestone at a time. For each milestone it
|
||||
creates a **separate steering directory** (`.steering/[date]-milestone-[NN]-[name]/`), divides the
|
||||
milestone's features into tasks grouped by feature, implements everything, validates, runs the
|
||||
test suite, reconciles the docs, marks the milestone `Completed` — and immediately starts the next
|
||||
one. It only stops early on a genuine external blocker, which it records in the roadmap.
|
||||
|
||||
### 7. Review a document
|
||||
|
||||
```
|
||||
> /review-docs docs/product-requirements.md
|
||||
@ -243,7 +395,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
|
||||
### 8. Day-to-day editing
|
||||
|
||||
You don't always need a command — just ask in normal conversation:
|
||||
|
||||
@ -257,11 +409,41 @@ opencode loads the appropriate skill automatically.
|
||||
|
||||
---
|
||||
|
||||
## Design & App Generation
|
||||
|
||||
Recommended workflow:
|
||||
|
||||
1. Run `/setup-project`
|
||||
2. Run `/define-design`
|
||||
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 milestones with a feature list each
|
||||
6. Use `/execute-milestones` to implement all milestones one by one, or `/add-feature` to go feature by feature
|
||||
7. 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` |
|
||||
| `/plan-milestones` | Plan milestones and generate milestone documents with the features for each | `/plan-milestones 3 milestones, MVP first` |
|
||||
| `/execute-milestones` | Execute milestones one by one, with separate steering documents per milestone | `/execute-milestones` |
|
||||
| `/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 +459,11 @@ 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 |
|
||||
| `milestone-planning` | Planning milestones and the feature breakdown per milestone | `docs/milestones/` files |
|
||||
| `milestone-execution` | Executing milestones one by one with per-milestone steering docs | `.steering/[date]-milestone-NN-[name]/` files |
|
||||
| `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
|
||||
|
||||
62
docs/design/README.md
Normal file
62
docs/design/README.md
Normal file
@ -0,0 +1,62 @@
|
||||
# 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`.
|
||||
|
||||
## Source of truth
|
||||
|
||||
```
|
||||
docs/design/ui-blueprint.json ← THE source of truth for UI generation
|
||||
```
|
||||
|
||||
SVG files are **visual references only**. If an SVG and the blueprint disagree, the blueprint wins and the SVG must be regenerated.
|
||||
|
||||
Generated UI must follow `design-tokens.json` — no hard-coded values.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
docs/design/
|
||||
├── 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
|
||||
├── platform-mapping.md # How the design maps to Web / Flutter / WinUI 3
|
||||
└── screens/ # SVG wireframes (one per blueprint screen)
|
||||
├── home.svg
|
||||
├── settings.svg
|
||||
└── [screen-id].svg
|
||||
```
|
||||
|
||||
## File purposes
|
||||
|
||||
### `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.
|
||||
|
||||
### `design-tokens.json`
|
||||
Design tokens in a Design Tokens Community Group–inspired JSON format (`$type` / `$value`). Covers color, typography, spacing, radius, shadow, motion, and breakpoints. Platform code reads from these tokens and never hard-codes values.
|
||||
|
||||
### `ui-blueprint.json`
|
||||
The source of truth for UI generation. Describes the app name, target platforms, routes, screens (each with a layout and component tree), reusable components (variants and states), and user actions/navigation.
|
||||
|
||||
### `platform-mapping.md`
|
||||
Documents how `design-tokens.json` and `ui-blueprint.json` are converted to each target platform:
|
||||
|
||||
- **Web**: tokens → CSS variables / Tailwind theme; blueprint → pages, routes, components.
|
||||
- **Flutter**: tokens → `ThemeData` / `ColorScheme` / constants; blueprint → widgets, routes.
|
||||
- **WinUI 3**: tokens → `ResourceDictionary`; blueprint → XAML pages, `UserControl`s, navigation.
|
||||
|
||||
### `screens/*.svg`
|
||||
Low-fidelity wireframes, one per screen in `ui-blueprint.json`, named `<screen-id>.svg`. Generated for human review only — never the source of truth.
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
/setup-project → product/architecture docs
|
||||
/define-design → creates the files above
|
||||
/generate-app web | flutter | winui3 → 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.
|
||||
41
docs/milestones/README.md
Normal file
41
docs/milestones/README.md
Normal file
@ -0,0 +1,41 @@
|
||||
# Milestone Documents (`docs/milestones/`)
|
||||
|
||||
This directory holds the project's **milestone plan**: an ordered breakdown of the product into releases, with the features for each milestone. It is created by `/plan-milestones` and kept up to date by `/add-feature`.
|
||||
|
||||
## Structure
|
||||
|
||||
```
|
||||
docs/milestones/
|
||||
├── roadmap.md # Overview: milestone table, ordering rationale, icebox
|
||||
├── milestone-01-[name].md # Milestone 1 (the MVP)
|
||||
├── milestone-02-[name].md
|
||||
└── milestone-NN-[name].md
|
||||
```
|
||||
|
||||
## File purposes
|
||||
|
||||
### `roadmap.md`
|
||||
The overview: a table of all milestones (goal, feature count, status), the ordering rationale, a pointer to the current milestone, and a "Later / Icebox" list of consciously deferred items.
|
||||
|
||||
### `milestone-[NN]-[name].md`
|
||||
One document per milestone. Contains the milestone's goal, scope, dependencies, and its **feature list** — each feature sized for exactly one `/add-feature` run, with description, related PRD requirements, affected screens, acceptance criteria, and the ready-to-run command.
|
||||
|
||||
## Status tracking
|
||||
|
||||
- Each feature has a checkbox in its milestone document; `/add-feature` checks it off (`[ ]` → `[x]`) when the feature completes.
|
||||
- Milestone status (`Not started` / `In progress` / `Completed`) is kept in sync between the milestone document and the roadmap table.
|
||||
|
||||
## Workflow
|
||||
|
||||
```
|
||||
/setup-project → product/architecture docs
|
||||
/define-design → UI/UX design spec
|
||||
/generate-app → initial app shell
|
||||
/plan-milestones → creates the files above
|
||||
/execute-milestones → implements all milestones one by one (one steering directory per milestone), updating statuses here
|
||||
/add-feature → implements one feature, then checks it off here
|
||||
```
|
||||
|
||||
## Status
|
||||
|
||||
This directory is populated by running `/plan-milestones`. Until then, the files above do not exist.
|
||||
Reference in New Issue
Block a user