diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index dd77f0fd3..2bfdd6e87 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -6,24 +6,43 @@ 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, next task or 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 actions 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 task | +| 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. +- 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. + - Push only when requested. +- 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. + - 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/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 2c531ffb4..1587062d3 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,44 @@ # 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. - -## Process +Validated phases marked `done`. -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. -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. +Or a `blocked` / `replan needed` report. -## Test +## Process -- 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). -- 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. +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. + - Set the phase `status: done` on success. +4. **Complete.** Commit according to the commit policy. + - Repeat steps 2–4 for the remaining tasks. + +## Rules + +- 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 2943bc426..d615ba9c3 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,26 @@ # 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`. +The coded plan. ## Output -The feature validated green with the plan frontmatter `status: implemented`. +The validated plan marked `implemented`. ## Process -1. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode. -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. + - Start the required runtime if needed. +2. **Mark.** Set the plan `status: implemented`. + - Commit according to the commit policy. -## Test +## Rules -- The validation commands exit zero. -- The plan reads `status: implemented`, committed (`git status --short` shows it clean). +- 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.