From eb3c659da826682d4395812308c77f1a6c4b9f0d Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 1 Oct 2026 12:14:24 +0800 Subject: [PATCH 1/4] docs(aidd-dev): require real workflow validation during implementation --- plugins/aidd-dev/skills/02-implement/actions/02-execute.md | 4 ++-- plugins/aidd-dev/skills/02-implement/actions/03-finalize.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md index 2c531ffb4..9fd620b0b 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -14,13 +14,13 @@ Every phase coded, asserted, and its frontmatter marked `status: done`, with the 1. **Open.** Walk the phases in order. In a feature folder each is a `phase-.md` next to `plan.md`. Set its `status: in-progress` as a runtime marker; no commit yet. 2. **Code.** Build the phase scope against its acceptance criteria. -3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Once it passes, set `status: done` and commit the phase as one unit, its code and its status together. +3. **Assert.** Validate the phase's acceptance criteria through the real affected workflow using the appropriate interface (browser, CLI, API…). Check actual against expected behavior at every step; fix mismatches and restart from the beginning. Require a full successful run with observable evidence before setting `status: done`; if validation is blocked, report it without claiming success. Commit the phase as one unit, its code and its status together. 4. **Guard.** Stop the loop on either condition: - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked`, commit, stop. - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: `. Never rewrite the plan; replanning is the caller's job. ## Test -- A phase reaches `status: done` only after assert passes against its acceptance criteria, in one commit with its code (`git status --short` shows no dangling phase edits). +- A phase reaches `status: done` only after a full workflow run passes its acceptance criteria with observable evidence at every step, in one commit with its code (`git status --short` shows no dangling phase edits). - The branch holds one commit per phase; there are no separate `in-progress` status commits. - A blocker leaves the plan `status: blocked` with no later phase run. diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md index 2943bc426..1afff777b 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -12,7 +12,7 @@ The feature validated green with the plan frontmatter `status: implemented`. ## Process -1. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode. +1. **Verify.** Run the plan's validation commands and tests; start the required runtime if needed. Never format code. 2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it. ## Test From aca8d3a3d591f9da59009f3570a86bdd871a62c1 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 5 Oct 2026 09:24:36 +0700 Subject: [PATCH 2/4] docs(aidd-dev): simplify implementation rules and success gates --- plugins/aidd-dev/skills/02-implement/SKILL.md | 34 +++++++++++-------- .../skills/02-implement/actions/01-prepare.md | 18 ++++------ .../skills/02-implement/actions/02-execute.md | 23 ++++++------- .../02-implement/actions/03-finalize.md | 16 ++++----- 4 files changed, 44 insertions(+), 47 deletions(-) diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index dd77f0fd3..acbbe6b11 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -6,24 +6,30 @@ argument-hint: plan # Skill: implement -Run an existing plan to write its code, one phase at a time, until every acceptance criterion holds. +```mermaid +flowchart LR + prepare --> execute --> finalize --> implemented + prepare -->|missing plan| stop + execute -->|fix or next phase| execute + execute --> blocked + execute --> replan + finalize -->|validation fails| finalize + finalize --> blocked + finalize --> replan +``` ## Actions -| # | Action | Role | Input | -| --- | ---------- | ----------------------------------------------- | ------------- | -| 01 | `prepare` | Resolve the plan, branch, mark it in-progress | a plan path | -| 02 | `execute` | Loop the phases, code and assert each | prepared plan | -| 03 | `finalize` | Verify and mark the plan implemented | coded phases | +Run in order; read each action file in `actions/` before executing it. -Run them in order, `01 → 03`. -Before running an action, read its file in `actions/`, not only the table or assets. +| Action | Does | +| -------- | ------------------------------------- | +| prepare | resolve the plan and branch | +| execute | implement and validate each phase | +| finalize | validate and mark the plan implemented | ## Transversal rules -- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. The `in-progress` values are runtime markers; only `done` and `implemented` need to land in a commit. -- Commits: one commit per phase, its code together with the phase reaching `done`, plus a final commit for the plan reaching `implemented`. Never leave the tree dirty at a phase boundary. Do not scatter separate `in-progress` status commits: one context now owns both code and status, so there is nothing to guard against. - -## References - -- `references/blocked.md`: the conditions that make a plan `blocked` and need a human. +- Status: plan `pending → in-progress → implemented` (or `blocked`); phases `pending → in-progress → done`. `in-progress` is a runtime marker. +- Commits: one per phase, code and `done` together; one final commit for `implemented`. Keep phase boundaries clean; never commit `in-progress` alone. +- Formatting: never format code manually; use project formatters or hooks. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md index 7e99042de..3e44ec202 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md @@ -1,23 +1,19 @@ # 01 - Prepare -Resolve the plan, put the workspace on a feature branch, and mark the plan in-progress. - ## Input -A plan, passed as arguments as a path or inline content. +A plan path or inline content. ## Output -The resolved plan on a feature branch with its frontmatter `status: in-progress`, ready for the phase loop. Or a fail-fast stop when no plan resolves. +The resolved plan on a feature branch with `status: in-progress`, or a missing-plan report. ## Process -1. **Resolve.** Resolve the plan from the arguments. A path must exist and be readable. With neither a readable file nor inline content, stop with `plan not found at `. Never fabricate a plan. -2. **Branch.** On the default branch, create a feature branch and announce it. On a non-default branch, keep it. -3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. No separate commit: it rides into the first phase commit, or into the `implemented` commit if there is no phase to code. +1. **Resolve.** Read the supplied plan. +2. **Branch.** Create and announce a feature branch on the default branch; otherwise keep the current branch. +3. **Mark.** Set the plan frontmatter `status: in-progress`. -## Test +## Rules -- A missing or unreadable plan with no inline content stops with `plan not found at `, and no plan is fabricated. -- The current branch is not the default branch. -- The plan frontmatter reads `status: in-progress`. +- Without a readable plan or inline content, stop with `plan not found at `; never fabricate a plan. diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md index 9fd620b0b..8dfcdb424 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -1,26 +1,23 @@ # 02 - Execute -Loop the plan's phases in order, coding each until every acceptance criterion holds. - ## Input -The prepared plan on its feature branch, from `01-prepare`. +The prepared plan. ## Output -Every phase coded, asserted, and its frontmatter marked `status: done`, with the commits on the branch. Or a stop at `status: blocked` when a human is needed, or a `replan needed` report on any drift from the plan. +Committed phases marked `done`, or a `blocked` / `replan needed` report. ## Process -1. **Open.** Walk the phases in order. In a feature folder each is a `phase-.md` next to `plan.md`. Set its `status: in-progress` as a runtime marker; no commit yet. +1. **Open.** Walk phases in order, setting each `status: in-progress` (`phase-.md` beside `plan.md` in a feature folder). 2. **Code.** Build the phase scope against its acceptance criteria. -3. **Assert.** Validate the phase's acceptance criteria through the real affected workflow using the appropriate interface (browser, CLI, API…). Check actual against expected behavior at every step; fix mismatches and restart from the beginning. Require a full successful run with observable evidence before setting `status: done`; if validation is blocked, report it without claiming success. Commit the phase as one unit, its code and its status together. -4. **Guard.** Stop the loop on either condition: - - **Blocked** (see [blocked.md](../references/blocked.md)): set the plan `status: blocked`, commit, stop. - - **Drift**: any mismatch with the plan, trivial or substantive, stop and report `replan needed: `. Never rewrite the plan; replanning is the caller's job. +3. **Assert.** Apply the validation rules below. +4. **Complete.** Set the phase `status: done` and commit it. -## Test +## Rules -- A phase reaches `status: done` only after a full workflow run passes its acceptance criteria with observable evidence at every step, in one commit with its code (`git status --short` shows no dangling phase edits). -- The branch holds one commit per phase; there are no separate `in-progress` status commits. -- A blocker leaves the plan `status: blocked` with no later phase run. +- Workflow: validate every acceptance criterion through the real affected workflow using the appropriate interface (browser, CLI, API…). Check actual against expected behavior at every step; fix mismatches, then restart from the beginning. +- Success: `done` requires a full successful run with observable evidence for every step. Report blocked validation; never count it as success. +- Blocked: follow [blocked.md](../references/blocked.md) and commit the blocked plan. +- Drift: if satisfying the acceptance criteria requires changing scope or requirements, stop with `replan needed: `. Never rewrite the plan. diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md index 1afff777b..ec7a8d14f 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -1,21 +1,19 @@ # 03 - Finalize -Run the validation and mark the plan implemented once every phase is done. - ## Input -A plan whose phases are all `status: done`, from `02-execute`. +A plan whose phases are all `done`. ## Output -The feature validated green with the plan frontmatter `status: implemented`. +The validated plan committed as `implemented`. ## Process -1. **Verify.** Run the plan's validation commands and tests; start the required runtime if needed. Never format code. -2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it. +1. **Verify.** Run the plan's validation commands and tests, starting the required runtime if needed. +2. **Mark.** Set the plan `status: implemented` and commit it. -## Test +## Rules -- The validation commands exit zero. -- The plan reads `status: implemented`, committed (`git status --short` shows it clean). +- Success: `implemented` requires every phase `done` and all validation commands and tests passing. +- Failure: fix validation failures and rerun the affected workflow plus validation commands and tests before `implemented`; follow Execute's validation, blocker and drift rules. From 3143f2c3d9bd047bf8b50b54b3dfcc64bae0c6e2 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 9 Oct 2026 11:24:37 +0700 Subject: [PATCH 3/4] docs(aidd-dev): commit validated implementation tasks atomically --- plugins/aidd-dev/skills/02-implement/SKILL.md | 26 ++++++++++--- .../skills/02-implement/actions/02-execute.md | 39 ++++++++++++++----- .../02-implement/actions/03-finalize.md | 18 ++++++--- 3 files changed, 63 insertions(+), 20 deletions(-) diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index acbbe6b11..9ae0ffce8 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -10,7 +10,7 @@ argument-hint: plan flowchart LR prepare --> execute --> finalize --> implemented prepare -->|missing plan| stop - execute -->|fix or next phase| execute + execute -->|fix, next task or phase| execute execute --> blocked execute --> replan finalize -->|validation fails| finalize @@ -20,16 +20,30 @@ flowchart LR ## Actions -Run in order; read each action file in `actions/` before executing it. +Run actions in order. +Read each action file in `actions/` before executing it. | Action | Does | | -------- | ------------------------------------- | | prepare | resolve the plan and branch | -| execute | implement and validate each phase | +| execute | implement and validate each task | | finalize | validate and mark the plan implemented | ## Transversal rules -- Status: plan `pending → in-progress → implemented` (or `blocked`); phases `pending → in-progress → done`. `in-progress` is a runtime marker. -- Commits: one per phase, code and `done` together; one final commit for `implemented`. Keep phase boundaries clean; never commit `in-progress` alone. -- Formatting: never format code manually; use project formatters or hooks. +- Track the plan through `pending → in-progress → implemented` (or `blocked`). + - Track phases through `pending → in-progress → done`. + - Treat `in-progress` as a runtime marker. + - Never commit `in-progress` alone. +- Follow user and project commit instructions. + - Otherwise, commit locally at the boundaries below. + - Push only when requested. +- Make one commit per validated task. + - Include all its code, tests and docs together. + - Group tasks only when they cannot be validated separately. + - Never split a task by step or file. + - Exclude unrelated changes. +- Include `done` in the phase's last task commit. +- Make a final commit for `implemented`. +- Use project formatters or hooks. + - Never format code manually. diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md index 8dfcdb424..1b00b0351 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -6,18 +6,39 @@ The prepared plan. ## Output -Committed phases marked `done`, or a `blocked` / `replan needed` report. +Validated phases marked `done`. +Commits follow the commit policy. + +Or a `blocked` / `replan needed` report. ## Process -1. **Open.** Walk phases in order, setting each `status: in-progress` (`phase-.md` beside `plan.md` in a feature folder). -2. **Code.** Build the phase scope against its acceptance criteria. -3. **Assert.** Apply the validation rules below. -4. **Complete.** Set the phase `status: done` and commit it. +1. **Open.** Walk phases in order. + - Set the current phase `status: in-progress`. + - In a feature folder, read `phase-.md` beside `plan.md`. +2. **Code.** Build the next task or inseparable group against its acceptance criteria. + - Follow the plan's task order. +3. **Assert.** Apply the validation rules below to every acceptance criterion of the selected task or group. + - After the last task, validate the full phase workflow. +4. **Complete.** Commit according to the commit policy. + - Set the phase `status: done` before its last task commit, only after full phase validation. + - Repeat steps 2–4 for the remaining tasks. ## Rules -- Workflow: validate every acceptance criterion through the real affected workflow using the appropriate interface (browser, CLI, API…). Check actual against expected behavior at every step; fix mismatches, then restart from the beginning. -- Success: `done` requires a full successful run with observable evidence for every step. Report blocked validation; never count it as success. -- Blocked: follow [blocked.md](../references/blocked.md) and commit the blocked plan. -- Drift: if satisfying the acceptance criteria requires changing scope or requirements, stop with `replan needed: `. Never rewrite the plan. +- Validate every acceptance criterion through the real affected workflow. + - Use the appropriate interface (browser, CLI, API…). + - Check actual against expected behavior at every step. + - Fix any mismatch. + - Restart from the beginning after a repair. +- Gate task commits and `done` on successful validation. + - Require a full successful run. + - Require observable evidence for every step. + - Report blocked validation. + - Never count blocked validation as success. +- Follow [blocked.md](../references/blocked.md) when implementation is blocked. + - Record the blocked plan according to the commit policy. + - Leave unfinished code uncommitted. +- Stop if satisfying the acceptance criteria requires changing scope or requirements. + - Report `replan needed: `. + - Never rewrite the plan. diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md index ec7a8d14f..1c88bb65b 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -6,14 +6,22 @@ A plan whose phases are all `done`. ## Output -The validated plan committed as `implemented`. +The validated plan marked `implemented`. +Commits follow the commit policy. ## Process -1. **Verify.** Run the plan's validation commands and tests, starting the required runtime if needed. -2. **Mark.** Set the plan `status: implemented` and commit it. +1. **Verify.** Run the plan's validation commands and tests. + - Start the required runtime if needed. +2. **Mark.** Set the plan `status: implemented`. + - Commit according to the commit policy. ## Rules -- Success: `implemented` requires every phase `done` and all validation commands and tests passing. -- Failure: fix validation failures and rerun the affected workflow plus validation commands and tests before `implemented`; follow Execute's validation, blocker and drift rules. +- Gate `implemented` on successful validation. + - Require every phase `done`. + - Require all validation commands and tests to pass. +- Repair validation failures before `implemented`. + - Rerun the affected workflow after a repair. + - Rerun the validation commands and tests. + - Follow Execute's validation, blocker and drift rules. From 92508df0a2f18b9b6cdc92ae3e914144fba5fe74 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Fri, 9 Oct 2026 11:35:26 +0700 Subject: [PATCH 4/4] docs(aidd-dev): deduplicate implementation commit rules --- plugins/aidd-dev/skills/02-implement/SKILL.md | 3 +-- plugins/aidd-dev/skills/02-implement/actions/02-execute.md | 6 +++--- plugins/aidd-dev/skills/02-implement/actions/03-finalize.md | 3 +-- 3 files changed, 5 insertions(+), 7 deletions(-) diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index 9ae0ffce8..2bfdd6e87 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -36,9 +36,8 @@ Read each action file in `actions/` before executing it. - Treat `in-progress` as a runtime marker. - Never commit `in-progress` alone. - Follow user and project commit instructions. - - Otherwise, commit locally at the boundaries below. - Push only when requested. -- Make one commit per validated task. +- By default, make one local commit per validated task. - Include all its code, tests and docs together. - Group tasks only when they cannot be validated separately. - Never split a task by step or file. diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md index 1b00b0351..1587062d3 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -7,7 +7,6 @@ The prepared plan. ## Output Validated phases marked `done`. -Commits follow the commit policy. Or a `blocked` / `replan needed` report. @@ -19,9 +18,10 @@ Or a `blocked` / `replan needed` report. 2. **Code.** Build the next task or inseparable group against its acceptance criteria. - Follow the plan's task order. 3. **Assert.** Apply the validation rules below to every acceptance criterion of the selected task or group. - - After the last task, validate the full phase workflow. + - After the last task: + - Validate the full phase workflow. + - Set the phase `status: done` on success. 4. **Complete.** Commit according to the commit policy. - - Set the phase `status: done` before its last task commit, only after full phase validation. - Repeat steps 2–4 for the remaining tasks. ## Rules diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md index 1c88bb65b..d615ba9c3 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -2,12 +2,11 @@ ## Input -A plan whose phases are all `done`. +The coded plan. ## Output The validated plan marked `implemented`. -Commits follow the commit policy. ## Process