Ken Yasue
1b67d1f15e
- New skill e2e-testing: on-demand Playwright setup (config, test:e2e script), acceptance-criteria-driven specs (one per feature + app-shell smoke), blueprint-driven semantic locators, and the shared verification checklist - /add-feature Step 7 and /execute-milestones Step 2.6 now write/update E2E specs and run npm run test:e2e alongside test/lint/typecheck; milestone gates and completion criteria include E2E - /generate-app Step 5 sets up Playwright and creates the app-shell smoke spec for the web target (integration_test / UI automation noted for flutter/winui3) - steering tasklist template, milestone-planning Definition of Done, milestone-execution task slicing/gates, development-guidelines pointers, and implementation-validator checks updated - CLAUDE.md, README, and settings.json updated Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
165 lines
8.8 KiB
Markdown
165 lines
8.8 KiB
Markdown
---
|
|
description: Execute one phase file (phaseN-milestones.md) - implement its milestones one by one with separate steering documents per milestone
|
|
---
|
|
|
|
# Execute Milestones (Fully Autonomous Phase Execution Mode)
|
|
|
|
This command executes **one phase file** from `docs/milestones/` — implementing its milestones **one at a time, in order**. 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 in the phase file.
|
|
|
|
**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.
|
|
|
|
**Phase file (required)**: `$ARGUMENTS` — the phase file to execute. Accepted forms:
|
|
- `phase1-milestones.md`
|
|
- `docs/milestones/phase1-milestones.md`
|
|
- `phase1` or `1` (resolved to `docs/milestones/phase1-milestones.md`)
|
|
|
|
## How to Run
|
|
|
|
```bash
|
|
claude
|
|
> /execute-milestones phase1-milestones.md
|
|
> /execute-milestones docs/milestones/phase2-milestones.md
|
|
> /execute-milestones 1
|
|
```
|
|
|
|
## Position in the Workflow
|
|
|
|
```
|
|
/setup-project
|
|
↓
|
|
/define-design
|
|
↓
|
|
/generate-app web | flutter | winui3
|
|
↓
|
|
/plan-milestones
|
|
↓
|
|
/execute-milestones phase1-milestones.md ← you are here (one phase file per run)
|
|
↓
|
|
/execute-milestones phase2-milestones.md (next run)
|
|
```
|
|
|
|
## Pre-Run Check
|
|
|
|
1. **The phase file argument is required.** If `$ARGUMENTS` is empty, or it does not resolve to an existing `docs/milestones/phase[N]-milestones.md` file, **stop**, list the phase files that exist under `docs/milestones/` with their statuses, and ask the user to specify one. Never pick a phase file yourself.
|
|
2. If no phase files exist at all, stop and tell the user to run `/plan-milestones` first.
|
|
3. Read `docs/milestones/roadmap.md`. If an **earlier phase** is not yet `Completed`, warn the user (later phases build on earlier ones) and continue only if the user accepts.
|
|
4. 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 the specified phase file and `docs/milestones/roadmap.md`.
|
|
2. The execution queue is every milestone in the phase file whose status is not already `Completed`, in ascending milestone number.
|
|
3. If the queue is empty, report that the phase is already completed and finish.
|
|
4. Set the phase's status to `In progress` (in the phase file header and in `roadmap.md`).
|
|
|
|
### Step 1: Load the Skills
|
|
|
|
1. Load the **milestone-execution skill** (`Skill('milestone-execution')`) for the per-milestone steering structure, task-division rules, and the gate criteria between milestones.
|
|
2. The **steering skill** and **development-guidelines skill** 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 phase file).
|
|
- `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:
|
|
|
|
- Use `Skill('steering')` in **implementation mode**; follow the coding standards in `Skill('development-guidelines')`.
|
|
- 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 (including Playwright E2E)
|
|
|
|
1. Write or update the milestone's end-to-end tests following the **e2e-testing skill** (`Skill('e2e-testing')`): one `e2e/[feature-name].spec.ts` per feature in the milestone, covering its acceptance criteria. Set up Playwright first (as described in the skill) if it is missing.
|
|
2. Run:
|
|
|
|
```bash
|
|
Bash('npm test')
|
|
Bash('npm run lint')
|
|
Bash('npm run typecheck')
|
|
Bash('npm run test:e2e')
|
|
```
|
|
|
|
If any command fails, analyze, fix, and re-run until all pass. Never skip or delete a failing test to make verification pass.
|
|
|
|
#### 2.7 Retrospective and Document Reconciliation
|
|
|
|
Apply `/add-feature` Step 8 for the milestone:
|
|
|
|
1. Run `Skill('steering')` 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 **phase file**: check off every feature of this milestone (`[ ]` → `[x]`), set the milestone's status to `Completed`, and fill in its "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.
|
|
|
|
#### 2.8 Milestone Gate — then Continue
|
|
|
|
The milestone is done only when: all tasks are `[x]`, validation passed, tests/lint/typecheck/E2E (Playwright) are green, the six documents are reconciled, and the milestone status is updated in the phase file and the roadmap.
|
|
|
|
**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`, the phase file, and `roadmap.md`, then stop and report — this is the only permitted early stop.
|
|
|
|
### Step 3: Close the Phase and Report
|
|
|
|
1. When the queue is empty, set the phase's status to `Completed` in the phase file header and in `roadmap.md`, and move the roadmap's current-phase pointer to the next phase file (or mark the roadmap complete if this was the last phase).
|
|
2. Report per milestone: steering directory created, features implemented, test results, and document updates.
|
|
|
|
## Completion Criteria
|
|
|
|
- Every milestone in the specified phase file has status `Completed`.
|
|
- The phase's status is `Completed` in both the phase file and `docs/milestones/roadmap.md`.
|
|
- Each executed milestone has its own `.steering/[date]-milestone-[NN]-[name]/` directory with all tasks `[x]`.
|
|
- Tests, lint, typecheck, and Playwright E2E tests pass on the final state, with E2E coverage for every implemented feature's acceptance criteria.
|
|
- The six persistent documents reflect everything implemented.
|
|
|
|
Completion message:
|
|
```
|
|
"Phase execution is complete: [phase file]
|
|
|
|
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 [phase file] and docs/milestones/roadmap.md.
|
|
|
|
Next steps:
|
|
- Review the retrospectives in each milestone's tasklist.md
|
|
- Run the app and verify the phase end-to-end
|
|
- Continue with the next phase: /execute-milestones [next phase file]
|
|
- Re-run /plan-milestones if the remaining roadmap should change
|
|
"
|
|
```
|