From eb3c659da826682d4395812308c77f1a6c4b9f0d Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 1 Oct 2026 12:14:24 +0800 Subject: [PATCH 1/2] 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/2] 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.