diff --git a/.opencode/command/execute-milestones.md b/.opencode/command/execute-milestones.md new file mode 100644 index 0000000..fdefe9f --- /dev/null +++ b/.opencode/command/execute-milestones.md @@ -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 +" +``` diff --git a/.opencode/command/plan-milestones.md b/.opencode/command/plan-milestones.md index 0dd2fe0..6706381 100644 --- a/.opencode/command/plan-milestones.md +++ b/.opencode/command/plan-milestones.md @@ -136,7 +136,8 @@ Milestone documents created: Next steps: - Review docs/milestones/ and adjust priorities if needed -- Start milestone 1: run /add-feature [first feature of milestone 1] -- /add-feature marks each feature complete in its milestone document as it finishes +- 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 " ``` diff --git a/.opencode/skills/milestone-execution/SKILL.md b/.opencode/skills/milestone-execution/SKILL.md new file mode 100644 index 0000000..bce761c --- /dev/null +++ b/.opencode/skills/milestone-execution/SKILL.md @@ -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. diff --git a/AGENTS.md b/AGENTS.md index db460fb..73151e8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -102,8 +102,8 @@ Define "what to do this time" for a specific development task: ### opencode Configuration (`.opencode/`) - `.opencode/agent/` - Subagent definitions (doc-reviewer, implementation-validator) -- `.opencode/command/` - Slash commands (setup-project, define-design, generate-app, update-design, plan-milestones, 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, 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 @@ -115,7 +115,9 @@ Define "what to do this time" for a specific development task: 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 features with `/add-feature [feature]`, milestone by 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 @@ -135,9 +137,11 @@ Define "what to do this time" for a specific development task: > /generate-app web > /update-design add a profile screen -# Milestone planning +# 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 diff --git a/README.md b/README.md index c760dd2..260f60f 100644 --- a/README.md +++ b/README.md @@ -49,8 +49,19 @@ a `roadmap.md` overview plus one document per milestone listing **the features i 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 features: `/add-feature ` -A fully autonomous loop, one feature at a time, milestone by milestone. Each run: +### 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 `** +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 @@ -60,7 +71,7 @@ A fully autonomous loop, one feature at a time, milestone by milestone. Each run 6. Records a retrospective, reconciles all six `docs/` documents, and checks the feature off in its milestone document ### Step 8 — Repeat and maintain -- More features → `/add-feature `, working through the milestones in order +- Remaining milestones → `/execute-milestones`, or feature by feature with `/add-feature ` - UI changes → `/update-design ` first, then `/add-feature` - Re-planning → re-run `/plan-milestones` or edit `docs/milestones/` in conversation - Document quality checks → `/review-docs ` @@ -212,6 +223,7 @@ opencode │ ├── generate-app.md │ ├── update-design.md │ ├── plan-milestones.md + │ ├── execute-milestones.md │ ├── add-feature.md │ └── review-docs.md └── skills/ # Task-specific skills @@ -225,6 +237,7 @@ opencode ├── design-tokens/ (SKILL.md) ├── platform-ui-generation/(SKILL.md) ├── milestone-planning/ (SKILL.md + template.md) + ├── milestone-execution/ (SKILL.md) └── steering/ (SKILL.md + templates/) ``` @@ -359,7 +372,21 @@ This fully autonomous workflow: 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 -### 6. 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 @@ -368,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. -### 7. Day-to-day editing +### 8. Day-to-day editing You don't always need a command — just ask in normal conversation: @@ -393,7 +420,7 @@ Recommended workflow: - Run `/update-design ` 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 `/add-feature` to add features, milestone by milestone +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: @@ -416,6 +443,7 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure. | `/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` | @@ -435,6 +463,7 @@ See [`docs/design/README.md`](docs/design/README.md) for the full structure. | `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 diff --git a/docs/milestones/README.md b/docs/milestones/README.md index 64de26f..d913579 100644 --- a/docs/milestones/README.md +++ b/docs/milestones/README.md @@ -32,6 +32,7 @@ One document per milestone. Contains the milestone's goal, scope, dependencies, /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 ```