From dd4637233ab8ad3984b03bb763c17af4fb621d74 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Sat, 20 Jun 2026 07:37:44 +0200 Subject: [PATCH 01/42] refactor(framework): split implement into prepare/execute/finalize, delegate SDLC implement MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Splits 02-implement into three focused actions (prepare → execute → finalize) with a branch guard, and commits each plan/phase status transition immediately so the implementer's clean-tree hygiene cannot revert it. 00-sdlc/03-implement now delegates to the implement skill instead of re-spawning the implementer, deleting the duplicated status-write pattern. Interactive gate 3 fires after the whole implement step. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 6 ++- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 4 +- .../skills/00-sdlc/actions/03-implement.md | 26 +++++-------- .../aidd-dev/skills/02-implement/README.md | 38 +++++++----------- plugins/aidd-dev/skills/02-implement/SKILL.md | 27 +++++++------ .../02-implement/actions/01-implement.md | 39 ------------------- .../skills/02-implement/actions/01-prepare.md | 23 +++++++++++ .../skills/02-implement/actions/02-execute.md | 25 ++++++++++++ .../02-implement/actions/03-finalize.md | 21 ++++++++++ 9 files changed, 115 insertions(+), 94 deletions(-) delete mode 100644 plugins/aidd-dev/skills/02-implement/actions/01-implement.md create mode 100644 plugins/aidd-dev/skills/02-implement/actions/01-prepare.md create mode 100644 plugins/aidd-dev/skills/02-implement/actions/02-execute.md create mode 100644 plugins/aidd-dev/skills/02-implement/actions/03-finalize.md diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index f428707a..c11af3f2 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -71,10 +71,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| -| `actions` | [01-implement.md](skills/02-implement/actions/01-implement.md) | - | +| `actions` | [01-prepare.md](skills/02-implement/actions/01-prepare.md) | - | +| `actions` | [02-execute.md](skills/02-implement/actions/02-execute.md) | - | +| `actions` | [03-finalize.md](skills/02-implement/actions/03-finalize.md) | - | | `-` | [README.md](skills/02-implement/README.md) | - | | `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` | -| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness.` | +| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Execute an implementation plan phase by phase, spawning an implementer agent per phase and tracking status until every acceptance criterion is met. Use when a plan exists and its code must be written, or when the SDLC delegates the implement step. Do NOT use to write a plan (use 01-plan), review a diff (use 05-review), or fix a bug with no plan (use 08-debug).` | #### `skills/03-assert` diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 6f650312..95da1bbd 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -48,7 +48,7 @@ Detect the mode from `$ARGUMENTS` once, at skill entry, before dispatching the f | --- | ----------- | ---------------------------------------------------------------------- | ------------------------------ | | 01 | `spec` | Consolidate sources, draft or refine the contract (skippable) | spec | | 02 | `plan` | Produce the mandatory plan file | plan via `planner` | -| 03 | `implement` | Loop milestones until complete | implement via `implementer` | +| 03 | `implement` | Build the plan's code, every phase, until complete | the `implement` skill | | 04 | `review` | Verdict `ship` or `iterate` | review via `reviewer` | | 05 | `ship` | Commit and open a change request via the project's VCS | commit, pull-request | @@ -66,7 +66,7 @@ Activate only in `interactive` mode. In `auto` mode, never pause. 1. **After `01-spec`** - show the spec (or the extracted objective + acceptance criteria when skipped); confirm contract. 2. **After `02-plan`** - show the plan; confirm scope before any code change. -3. **After each phase of `03-implement`** - show the phase output; confirm before continuing. +3. **After `03-implement`** - show the implemented diff; confirm before review. The phase loop runs inside the delegated `implement` skill, so the gate is the whole step, not each phase. 4. **After `04-review`** - show findings and verdict; confirm ship vs iterate. 5. **Before `05-ship` opens the change request** - show title, body, base branch, draft state; confirm before creation. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index 8e04a447..19bcc008 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -1,31 +1,23 @@ # 03 - Implement -Build a milestone, apply a fix list, or finish a remaining scope via the implementer agent. Mandatory. +Build the plan's code by delegating to the `implement` skill, which loops the phases, drives status, and validates. Mandatory. ## Inputs -- one of `milestone` (with acceptance criteria), `fix_list`, `items_remaining` - required -- `spec_slice` - relevant portion of the spec (optional) -- `validation_commands` - shell commands the implementer must run before reporting done (optional) -- `plan_path` (from 02) +- `plan_path` (from 02) - required +- On an `04 = iterate` loop-back, the review findings as a fix list - optional ## Outputs -```yaml -items_implemented: [...] -items_remaining: [...] -completion_score: 0-100 -``` +The plan reaches frontmatter `status: implemented` (or `status: blocked`), every phase `done`, validation green. ## Process -1. **Mark in-progress.** Set `status: in-progress` in the plan frontmatter at `plan_path` (skip if already set). Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -2. **Spawn implementer** (`implementer` agent) with the inputs above. Brief: run `implement` for the milestone or fix list, then `assert` + `test`. -3. **On failure**, run `debug` and re-spawn the implementer with the diagnostic notes until tests pass. -4. **Blocked.** If the implementer surfaces `BLOCKED` in `notes`, write `status: blocked` in the plan frontmatter at `plan_path`, stop (do NOT proceed to 04), and escalate to a human. -5. **Mark implemented.** When the whole plan is implemented (no milestones remain, last pass `items_remaining` empty), set `status: implemented` in the plan frontmatter at `plan_path`. -6. **Return** the implementer's YAML as-is to the SDLC orchestrator. +1. **Delegate.** Invoke the `implement` skill with `plan_path`. It branches, loops each phase through the `implementer`, commits the code and the status transitions, and runs the plan's validation. The orchestrator writes no status itself. +2. **Iterate.** On a loop-back from `04 = iterate`, fold the findings into the plan (set the affected phases back to `pending` or add a fix phase), then delegate again. +3. **Blocked.** The skill stops at `status: blocked` when the implementer hits a human-only condition. Do NOT proceed to `04`; escalate to a human. +4. **Surface.** Report the skill's outcome to the orchestrator so it can move to `04`. ## Test -`completion_score` is an integer between 0 and 100; `items_implemented` and `items_remaining` are present; the validation commands return exit code 0; when fully implemented the plan's frontmatter `status` is `implemented` (or `blocked` if it surfaced a blocker, stopping before 04). +The plan frontmatter `status` is `implemented` (or `blocked`, stopping before `04`); every phase reads `status: done`; the validation commands return exit code 0. diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md index 8708a777..5a0a7817 100644 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ b/plugins/aidd-dev/skills/02-implement/README.md @@ -2,23 +2,18 @@ # 02 - implement -Executes an existing implementation plan phase by phase via the `implementer` -agent, iterating until every acceptance criterion is satisfied. Each phase -loops until the agent reports 100 % completion. +Executes an existing implementation plan phase by phase, spawning an `implementer` agent per phase and iterating until every acceptance criterion is satisfied. Tracks status in the plan and phase frontmatter as it goes. ## When to use -- A plan produced by [01-plan](../01-plan/README.md) is ready and you need - the code written end-to-end against it. -- An iteration of [00-sdlc](../00-sdlc/README.md) is delegating the - `implement` step to this skill. +- A plan produced by [01-plan](../01-plan/README.md) is ready and you need the code written against it. +- An iteration of [00-sdlc](../00-sdlc/README.md) delegates the implement step. ## When NOT to use - No plan exists yet → use [01-plan](../01-plan/README.md) first. - The plan is wrong and needs replanning → amend the plan, not the code. -- The task is a bug fix without a plan surface → use - [08-debug](../08-debug/README.md). +- A bug fix with no plan surface → use [08-debug](../08-debug/README.md). ## How to invoke @@ -26,29 +21,26 @@ loops until the agent reports 100 % completion. Use skill aidd-dev:02-implement ``` -Pass the plan path or content as `$ARGUMENTS`. The skill exposes 1 action: +Pass the plan path or content as `$ARGUMENTS`. The skill runs three actions in order: -1. `implement` - loop each plan phase: spawn the `implementer` agent, wait - for structured output, re-spawn with `items_remaining` until the phase - hits 100 %. Branching is the caller's responsibility; this skill never - creates branches. Plan amendments are made inline and tagged with the - robot marker. +1. **prepare** — fails fast when the plan is missing (never fabricates one); puts `HEAD` on a feature branch when it is on the default branch, otherwise keeps the current branch; sets the plan `status: in-progress`. +2. **execute** — loops the plan's phases: per phase it sets `status: in-progress`, spawns the `implementer` agent, re-spawns with `items_remaining` until 100 %, then sets `status: done`; stops at `status: blocked` when the implementer hits a human-only condition. +3. **finalize** — runs validation, then marks the plan `status: implemented` once every phase is done. + +**Code** commits are the `implementer` agent's job (one per ticked acceptance criterion); the skill commits only its own **tracking** — each status transition, the moment it makes it. That split keeps the same audit trail whether the agent is reached through this skill, the SDLC, or a direct spawn, and stops the implementer's clean-tree hygiene from reverting an uncommitted status edit. ## Outputs -- Code changes on the active branch, one phase at a time. -- `phases_completed` count and `acceptance_satisfied: true` when done. -- Plan amendments inline in the plan file when the loop discovers gaps. +- Code for the feature, one phase at a time, committed by the `implementer` agent on the active feature branch. +- Plan and phase frontmatter status driven `pending → in-progress → done / implemented`, or `blocked` — each transition committed by the skill as it happens. +- Plan amendments inline, tagged 🤖, when the loop finds a gap. ## Prerequisites -- A plan file with phases, M/C/D, and acceptance criteria. +- A plan file with phases and acceptance criteria, from `01-plan`. - The `implementer` agent available in context. - Project rules already loaded for the implementer to respect. ## Technical details -See [`SKILL.md`](SKILL.md) and -[`actions/01-implement.md`](actions/01-implement.md) for the phase loop -contract, the re-spawn rule, and the boundary constraints (no formatting, -no dev mode). +See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the prepare/execute/finalize split: the branch guard, the phase loop, the re-spawn rule, the status lifecycle, and the boundary constraints (no formatting, no dev mode). diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index eeff95ff..9149e207 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -1,24 +1,29 @@ --- name: 02-implement -description: Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness. -context: fork -agent: implementer +description: Execute an implementation plan phase by phase, spawning an implementer agent per phase and tracking status until every acceptance criterion is met. Use when a plan exists and its code must be written, or when the SDLC delegates the implement step. Do NOT use to write a plan (use 01-plan), review a diff (use 05-review), or fix a bug with no plan (use 08-debug). +argument-hint: prepare | execute | finalize --- # Skill: implement -Run an existing technical plan to write code, validating each phase before moving on. +Run an existing plan to write code, one phase at a time, until every acceptance criterion holds. Spawns an implementer agent per phase. -## Agent delegation +## Actions -Spawn the `implementer` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `implementer` agent explicitly with this skill's content as the prompt. +| # | Action | Role | Input | +| --- | ---------- | ----------------------------------------------------- | ------------- | +| 01 | `prepare` | Resolve the plan, branch, mark the plan in-progress | a plan path | +| 02 | `execute` | Loop the phases, code each via the implementer agent | prepared plan | +| 03 | `finalize` | Verify and mark the plan implemented | coded phases | -## Actions +Run them in order, `01 → 03`. + +Status lifecycle: a plan runs `pending → in-progress → implemented` (or `blocked`); a phase runs `pending → in-progress → done`. + +## Transversal rules -```markdown -@actions/01-implement.md -``` +- The `implementer` agent commits the code, one commit per ticked acceptance criterion. This skill commits only its own tracking — each status transition, the moment it makes it — and never commits code. ## References -- `@references/blocked.md` - conditions that make a plan `blocked` (needs a human). All actions inherit it. +- `references/blocked.md`: the conditions that make a plan `blocked` and need a human. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md deleted file mode 100644 index bd2b87de..00000000 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ /dev/null @@ -1,39 +0,0 @@ -# 01 - Implement - -Code the whole feature based on the implementation plan, phase by phase, sequentially, until every acceptance criterion is satisfied. - -## Inputs - -```yaml -plan: -branch: # optional; created when the plan specifies one -``` - -## Outputs - -```yaml -phases_completed: -acceptance_satisfied: true -notes: - - -``` - -## Process - -1. **Resolve the plan (fail-fast).** Resolve the plan from `$ARGUMENTS`. When it is a path, the file must exist and be readable. If neither a readable plan file nor inline plan content is available, stop immediately with the error `plan not found at ` and do nothing else. Never fabricate a substitute plan. -2. **Branch.** Create a new branch if the plan specifies one (`git checkout -b `). Set `status: in-progress` on the plan. Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -3. **Phase loop.** For each phase the plan lists, in order. When the plan is a feature folder, each phase is a `phase-.md` next to `plan.md`; open it for the scope, tasks, and acceptance criteria. - - Set the phase frontmatter `status: in-progress`. - - Spawn the `implementer` agent via the `Task` tool, passing that phase's scope and acceptance criteria. - - Wait for the agent's structured output. If `completion_score < 100`, re-spawn with `items_remaining` until the phase reaches 100 %. - - Set the phase frontmatter `status: done` once it reaches 100 %. -4. **Plan amendments.** If a phase is incorrect, incomplete, or blocked by missing information, amend the plan directly. Mark every change with 🤖 and a brief rationale. -5. **Boundaries.** Never format code. Never run dev mode. Follow project rules already loaded in context. -6. **Verify the feature.** Run validation commands, tests, and any manual checks required to confirm the feature works end to end. -7. **Blocked.** If the implementer surfaces `BLOCKED` in its notes (see the blocked reference), set `status: blocked` and stop the loop. -8. **Mark implemented.** Every phase at 100% + validation passes → set `status: implemented`. - -## Test - -- A missing or unreadable plan path with no inline plan content stops the skill with `plan not found at `, and no substitute plan is fabricated. -- After the loop terminates: every phase has its acceptance criteria checked off and its frontmatter `status` is `done`, validation commands exit zero, and the plan's frontmatter `status` is `implemented` — OR, if a blocking condition held, the loop stopped and it is `blocked`. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md new file mode 100644 index 00000000..c08fef4d --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md @@ -0,0 +1,23 @@ +# 01 - Prepare + +Resolve the plan, put the workspace on a feature branch, and mark the plan in-progress. + +## Input + +A plan, passed via `$ARGUMENTS` as a 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. + +## Process + +1. **Resolve (fail-fast).** Resolve the plan from `$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, run `git checkout -b ` and announce it. On a non-default branch, keep it. +3. **Mark in-progress.** Set the plan frontmatter `status: in-progress` and commit it. + +## Test + +- A missing or unreadable plan with no inline content stops with `plan not found at `, and no plan is fabricated. +- `git rev-parse --abbrev-ref HEAD` is not the default branch. +- The plan reads `status: in-progress`, committed (`git status --short` shows it clean). diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md new file mode 100644 index 00000000..54145e49 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -0,0 +1,25 @@ +# 02 - Execute + +Loop the plan's phases in order, coding each through the implementer agent until every acceptance criterion holds. + +## Input + +The prepared plan on its feature branch, from `01-prepare`. + +## Output + +Every phase coded and its frontmatter marked `status: done`, with the commits on the branch. Or a stop at `status: blocked` when a human is needed. + +## Process + +1. **Open the phase.** Walk the phases in order; in a feature folder each is a `phase-.md` next to `plan.md`. Set its `status: in-progress` and commit it before spawning. +2. **Spawn the implementer.** Spawn the `implementer` agent via `Task` with the phase scope and acceptance criteria. It commits the code; this skill commits only tracking. +3. **Re-spawn until complete.** On `completion_score < 100`, re-spawn with `items_remaining` until 100 percent. Then set `status: done` and commit it. +4. **Stop when blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. +5. **Amend on drift.** When a phase is wrong or incomplete, amend it in place, marked 🤖 with a one-line rationale. + +## Test + +- Each completed phase reads `status: done`, committed (`git status --short` shows no dangling phase edits). +- The branch holds both the code commits and the tracking 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 new file mode 100644 index 00000000..a642d472 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -0,0 +1,21 @@ +# 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`. + +## Output + +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. +2. **Mark implemented.** Every phase done and validation green, set the plan `status: implemented` and commit it. + +## Test + +- The validation commands exit zero. +- The plan reads `status: implemented`, committed (`git status --short` shows it clean). From 299edad370108b475d50a771e82b9d2b29b9ccfd Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Sat, 20 Jun 2026 21:37:41 +0200 Subject: [PATCH 02/42] refactor(framework): gate implement phases on assert and tighten drift to follow-only Phase done-gate moves from the implementer's self-reported completion_score to the assert skill passing (objective). Drift no longer rewrites the plan in place; any mismatch surfaces 'replan needed' to the caller (replanning is the planner's job). Also brings the actions to skill-authoring conformance: one-word step labels, no semicolons in process steps. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/02-implement/README.md | 4 ++-- .../skills/02-implement/actions/01-prepare.md | 4 ++-- .../skills/02-implement/actions/02-execute.md | 14 +++++++------- .../skills/02-implement/actions/03-finalize.md | 2 +- 4 files changed, 12 insertions(+), 12 deletions(-) diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md index 5a0a7817..e2e1b5e0 100644 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ b/plugins/aidd-dev/skills/02-implement/README.md @@ -12,7 +12,7 @@ Executes an existing implementation plan phase by phase, spawning an `implemente ## When NOT to use - No plan exists yet → use [01-plan](../01-plan/README.md) first. -- The plan is wrong and needs replanning → amend the plan, not the code. +- The plan is wrong and needs replanning → replan with [01-plan](../01-plan/README.md); this skill never rewrites the plan. - A bug fix with no plan surface → use [08-debug](../08-debug/README.md). ## How to invoke @@ -33,7 +33,7 @@ Pass the plan path or content as `$ARGUMENTS`. The skill runs three actions in o - Code for the feature, one phase at a time, committed by the `implementer` agent on the active feature branch. - Plan and phase frontmatter status driven `pending → in-progress → done / implemented`, or `blocked` — each transition committed by the skill as it happens. -- Plan amendments inline, tagged 🤖, when the loop finds a gap. +- A `replan needed` report when the plan no longer matches reality; this skill never rewrites the plan. ## Prerequisites 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 c08fef4d..ab9bf86c 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md @@ -12,9 +12,9 @@ The resolved plan on a feature branch with its frontmatter `status: in-progress` ## Process -1. **Resolve (fail-fast).** Resolve the plan from `$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. +1. **Resolve.** Resolve the plan from `$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, run `git checkout -b ` and announce it. On a non-default branch, keep it. -3. **Mark in-progress.** Set the plan frontmatter `status: in-progress` and commit it. +3. **Mark.** Set the plan frontmatter `status: in-progress` and commit it. ## Test 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 54145e49..d1859dc0 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -8,18 +8,18 @@ The prepared plan on its feature branch, from `01-prepare`. ## Output -Every phase coded and its frontmatter marked `status: done`, with the commits on the branch. Or a stop at `status: blocked` when a human is needed. +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 -1. **Open the phase.** Walk the phases in order; in a feature folder each is a `phase-.md` next to `plan.md`. Set its `status: in-progress` and commit it before spawning. -2. **Spawn the implementer.** Spawn the `implementer` agent via `Task` with the phase scope and acceptance criteria. It commits the code; this skill commits only tracking. -3. **Re-spawn until complete.** On `completion_score < 100`, re-spawn with `items_remaining` until 100 percent. Then set `status: done` and commit it. -4. **Stop when blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. -5. **Amend on drift.** When a phase is wrong or incomplete, amend it in place, marked 🤖 with a one-line rationale. +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` and commit it before spawning. +2. **Spawn.** Spawn the `implementer` agent via `Task` with the phase scope and acceptance criteria. It commits the code. This skill commits only tracking. +3. **Assert.** Run the `assert` skill against the phase's acceptance criteria. On failure, re-spawn the implementer with the failing assertions as `items_remaining`. Loop until assert passes — the gate is assert, not the implementer's self-report. Then set `status: done` and commit it. +4. **Blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. +5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch — trivial or substantive — stop and report `replan needed: ` to the caller. Replanning is the planner's job, not this skill's. ## Test -- Each completed phase reads `status: done`, committed (`git status --short` shows no dangling phase edits). +- A phase reaches `status: done` only after the `assert` skill passes against its acceptance criteria, committed (`git status --short` shows no dangling phase edits). - The branch holds both the code commits and the tracking 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 a642d472..2943bc42 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -13,7 +13,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. -2. **Mark implemented.** Every phase done and validation green, set the plan `status: implemented` and commit it. +2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it. ## Test From 3c44ab36e40f093cc063ca269a1b8611416a9c31 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Sat, 20 Jun 2026 23:26:32 +0200 Subject: [PATCH 03/42] refactor(framework): trim implement router and make execute tool-agnostic Router drops how-detail and agent mentions (description trimmed to what+when; status lifecycle moved into a transversal rule; commit rule scoped to the skill's own tracking). Execute steps go tool-agnostic: no `Task`, delegate to the implementer by role, assert the phase instead of naming the assert skill. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 2 +- plugins/aidd-dev/skills/02-implement/SKILL.md | 19 +++++++++---------- .../skills/02-implement/actions/02-execute.md | 8 ++++---- 3 files changed, 14 insertions(+), 15 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index c11af3f2..0e60c682 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -76,7 +76,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-finalize.md](skills/02-implement/actions/03-finalize.md) | - | | `-` | [README.md](skills/02-implement/README.md) | - | | `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` | -| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Execute an implementation plan phase by phase, spawning an implementer agent per phase and tracking status until every acceptance criterion is met. Use when a plan exists and its code must be written, or when the SDLC delegates the implement step. Do NOT use to write a plan (use 01-plan), review a diff (use 05-review), or fix a bug with no plan (use 08-debug).` | +| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing, or when the SDLC delegates the implement step. Do NOT use to write a plan (01-plan), review a diff (05-review), or fix a bug with no plan (08-debug).` | #### `skills/03-assert` diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index 9149e207..a02ec316 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -1,28 +1,27 @@ --- name: 02-implement -description: Execute an implementation plan phase by phase, spawning an implementer agent per phase and tracking status until every acceptance criterion is met. Use when a plan exists and its code must be written, or when the SDLC delegates the implement step. Do NOT use to write a plan (use 01-plan), review a diff (use 05-review), or fix a bug with no plan (use 08-debug). +description: Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing, or when the SDLC delegates the implement step. Do NOT use to write a plan (01-plan), review a diff (05-review), or fix a bug with no plan (08-debug). argument-hint: prepare | execute | finalize --- # Skill: implement -Run an existing plan to write code, one phase at a time, until every acceptance criterion holds. Spawns an implementer agent per phase. +Run an existing plan to write its code, one phase at a time, until every acceptance criterion holds. ## Actions -| # | Action | Role | Input | -| --- | ---------- | ----------------------------------------------------- | ------------- | -| 01 | `prepare` | Resolve the plan, branch, mark the plan in-progress | a plan path | -| 02 | `execute` | Loop the phases, code each via the implementer agent | prepared plan | -| 03 | `finalize` | Verify and mark the plan implemented | coded phases | +| # | 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 them in order, `01 → 03`. -Status lifecycle: a plan runs `pending → in-progress → implemented` (or `blocked`); a phase runs `pending → in-progress → done`. - ## Transversal rules -- The `implementer` agent commits the code, one commit per ticked acceptance criterion. This skill commits only its own tracking — each status transition, the moment it makes it — and never commits code. +- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. +- Commits: commit only the status tracking, the moment each transition is made, and never commit code. ## References 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 d1859dc0..b8fc9ab6 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -12,14 +12,14 @@ Every phase coded, asserted, and its frontmatter marked `status: done`, with the ## 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` and commit it before spawning. -2. **Spawn.** Spawn the `implementer` agent via `Task` with the phase scope and acceptance criteria. It commits the code. This skill commits only tracking. -3. **Assert.** Run the `assert` skill against the phase's acceptance criteria. On failure, re-spawn the implementer with the failing assertions as `items_remaining`. Loop until assert passes — the gate is assert, not the implementer's self-report. Then set `status: done` and commit it. +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` and commit it before delegating. +2. **Delegate.** Hand the phase scope and acceptance criteria to the `implementer` agent. +3. **Assert.** Assert the phase against its acceptance criteria. On failure, hand the failures back to the `implementer` and repeat. The gate is the assertion passing, not the implementer's self-report. Then set `status: done` and commit it. 4. **Blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. 5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch — trivial or substantive — stop and report `replan needed: ` to the caller. Replanning is the planner's job, not this skill's. ## Test -- A phase reaches `status: done` only after the `assert` skill passes against its acceptance criteria, committed (`git status --short` shows no dangling phase edits). +- A phase reaches `status: done` only after assert passes against its acceptance criteria, committed (`git status --short` shows no dangling phase edits). - The branch holds both the code commits and the tracking commits. - A blocker leaves the plan `status: blocked` with no later phase run. From dec5acbfa92363aba8b8b4e8a369fc9c97aa8427 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Mon, 22 Jun 2026 05:33:08 +0200 Subject: [PATCH 04/42] refactor(framework): codify the spawn boundary and align the three agents ARCHITECTURE.md gains the keystone: skills are caller-agnostic recipes, agents are leaf executors, a skill may delegate to an agent and an agent may invoke a declared skill list (never read a skill's files), only the conductor spawns. The planner/implementer/reviewer agents drop hardcoded plugin paths for capability names (R25), replace orchestration-sense 'Planner' with 'conductor' (resolving the implementer's return-to-Planner contradiction), and the implementer carries its BLOCKED criteria inline instead of pointing into the implement skill's files. Precious content preserved. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/ARCHITECTURE.md | 14 +++ plugins/aidd-dev/CATALOG.md | 6 +- plugins/aidd-dev/agents/implementer.md | 109 +++++------------------ plugins/aidd-dev/agents/planner.md | 110 ++++------------------- plugins/aidd-dev/agents/reviewer.md | 117 +++++-------------------- 5 files changed, 78 insertions(+), 278 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bbdeb4bd..2430bc78 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -124,6 +124,20 @@ flowchart LR Each action is a self-contained markdown file with inputs, outputs, depends-on, process steps, and a test checklist. Actions can call other skills via the `Skill` tool, so a skill discovers a capability it needs at runtime (by matching skill descriptions, never by hardcoded plugin name) and delegates to it. +## Skills and agents + +- A **skill** is a caller-agnostic recipe; it runs in the context of whoever invokes it. +- An **agent** is an isolated executor; it runs in its own context and returns only a result. + +Choose by context, not complexity: keep the work visible to the caller → skill; isolate it and take only the result → agent. + +Composition rules: + +- A skill may delegate to an agent. +- An agent may invoke the skills it declares under `# Skills you may invoke`, as capabilities — never by reading a skill's files. +- Only the conductor (the SDLC skill) delegates to agents; a worker agent (`planner`, `implementer`, `reviewer`) never delegates to another agent. +- A worker never declares an orchestration skill (`implement`, `sdlc`), so delegation cannot cycle. + ## Cross-plugin orthogonality Plugins do not reference each other by name. When skill A needs a capability owned by skill B, it discovers a candidate at runtime through description matching. This rule keeps the marketplace forkable, the plugins swappable, and the docs maintainable. diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 0e60c682..66b6a036 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -33,9 +33,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | File | Description | |------|---| -| [implementer.md](agents/implementer.md) | `Milestone executor. Use when a planner has handed off a milestone, a fix list, or items_remaining from a previous incomplete pass. Codes, tests, repairs. Returns what's done, what's remaining, and a completion score. Never replans, never judges.` | -| [planner.md](agents/planner.md) | `Planning agent. Use when a validated spec must be turned into executable milestone plans, or when a top-level SDLC orchestrator needs a replan. Writes plans and decisions only. Never writes code, never judges code, never spawns implementer/reviewer agents.` | -| [reviewer.md](agents/reviewer.md) | `Independent critic in fresh context. Use when an artifact (code, spec, plan, doc) needs verification against a validator (acceptance criteria, checklist file, or any explicit ruleset). Returns reviewed items, findings, completion score and quality score. Never edits the artifact, never decides what to do next.` | +| [implementer.md](agents/implementer.md) | `Codes a handed-off milestone or fix list, tests it, and reports back. Use when an approved scope must become working, validated code. Never plans, never judges its own work.` | +| [planner.md](agents/planner.md) | `Turns an approved spec into an executable plan with milestones, acceptance criteria, and recorded decisions. Use when a spec must become a plan, or a finished pass needs replanning. Never writes code, never judges it.` | +| [reviewer.md](agents/reviewer.md) | `Judges a finished artifact against an explicit validator and reports findings with a score. Use when code, a spec, a plan, or a doc needs independent verification. Never edits the artifact, never decides what happens next.` | ### `skills` diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md index ae744ae0..cb8b8242 100644 --- a/plugins/aidd-dev/agents/implementer.md +++ b/plugins/aidd-dev/agents/implementer.md @@ -1,103 +1,38 @@ --- name: implementer -description: Milestone executor. Use when a planner has handed off a milestone, a fix list, or items_remaining from a previous incomplete pass. Codes, tests, repairs. Returns what's done, what's remaining, and a completion score. Never replans, never judges. +description: Codes a handed-off milestone or fix list, tests it, and reports back. Use when an approved scope must become working, validated code. Never plans, never judges its own work. model: sonnet --- # Role -You build what the top-level SDLC orchestrator or Planner specifies, within the boundaries of the input. You decide how to implement, never what. You report back honestly: what you finished, what you couldn't, and why. - -You implement directly in your context. Do not spawn other agents. Do not search for `Task` or `Agent`; they are not part of this role. - -# Inputs - -When invoked, you receive: - -- A milestone description with explicit acceptance criteria, OR a fix list, OR an `items_remaining` set -- A relevant slice of the spec (for reference) -- Optionally, validation commands (lint, type check, tests, build) - -# Outputs - -When you return, your output is structured: - -```yaml -items_implemented: - - -items_remaining: - - -completion_score: <0-100> # percentage of input scope actually delivered -notes: -``` - -# Definition of Ready - -You may start when: - -- The input scope is identified with explicit acceptance criteria -- Validation commands are available (or you can derive them from project conventions) - -If the scope is ambiguous, return immediately with `completion_score: 0` and an explanation in `notes`. Don't guess. - -# Definition of Done - -Your output is complete when: - -- Every item in the input scope has been attempted (or explicitly skipped with reason) -- Every attempted item has been validated locally (lint, types, tests, build pass) -- The output accurately reports `items_implemented`, `items_remaining`, and `completion_score` +You build what you are handed: a milestone, a fix list, or the unfinished part of an earlier pass. You stay inside that scope. You decide how to build it, never what. You work in your own context and never delegate to another agent. When you finish or get stuck, you return to whoever invoked you with what you did, what is left, and why. # Behavior -- Internalize acceptance criteria before writing code. -- If a fix list or items_remaining was provided, focus only on those. No scope expansion. -- Implement substep by substep. Validate after each substep. Repair before moving on. No accumulation. -- Before package installation or generated build work, make sure `.gitignore` excludes `.env`, `.env.local`, `.env.*.local`, `node_modules/`, `dist/`, `.astro/`, coverage output, and tool caches. -- Never stage or commit generated artifacts (`node_modules/`, `dist/`, `.astro/`, coverage output, caches). -- If generated artifacts were already tracked before your work, remove them from version control in a dedicated hygiene commit before implementation or package installation. Do not mix those deletions with feature commits. If the caller explicitly says hygiene was already handled, verify with `git ls-files node_modules dist .astro coverage`. -- **After every ticked acceptance criterion, commit atomically** via `aidd-vcs:01-commit` with `mode: auto`, `message: "/: "`, `push: false`, or plain `git commit` if the VCS skill is unavailable. One acceptance criterion = one commit. Tasks within a phase guide HOW to implement and do not trigger commits - only the verified-state checkboxes (acceptance criteria) do. This is non-negotiable: the audit trail is the safety net. -- If the milestone involves providers, unit tests must use fixtures while integration tests must exercise the real provider code path. HTTP mocks/cassettes are acceptable only at the network boundary. -- If you cannot complete an item (technical blocker, ambiguity, missing dependency), record it in `items_remaining` and explain in `notes`. Don't fake completion. -- Be honest about `completion_score`. Underreporting is acceptable. Overreporting breaks the loop and produces silent failures. -- When done (fully or partially), return your output. The Planner decides what happens next. +- Internalize the acceptance criteria before writing code. If the scope is ambiguous, say so instead of guessing. +- Build substep by substep. Validate after each one and repair before moving on. Never accumulate. +- Commit after every met acceptance criterion, atomically, via the `commit` skill: one criterion, one commit. The audit trail is non-negotiable. +- Keep generated artifacts out of version control (`node_modules`, `dist`, build output, caches). If they were already tracked, remove them in a separate hygiene commit before any install or feature work. +- For provider work, unit tests run on fixtures and integration tests exercise the real provider path. Mocks belong only at the network boundary. +- Be honest about how much you delivered. Underreporting is fine. Overreporting breaks the loop and hides failures. -# Decisions in scope - -- Implementation choices: libraries, patterns, file layout, naming -- Substep decomposition inside the input scope -- Local refactors strictly within the input scope -- Atomic commit messages (one commit per ticked checkbox is mandatory; you decide the message wording) - -# Decisions out of scope +# Guardrails -- Modifying acceptance criteria - Planner -- Judging your own work - Reviewer -- Replanning, pivoting, expanding scope - surface in `items_remaining` + `notes` +- Stay strictly inside the input scope. No scope expansion. +- No TODOs, no skipped tests, no placeholder mocks, no silent workarounds. Declare anything you bypass. +- Never change the acceptance criteria or the spec. Surface the needed change and let the caller replan. +- Never judge your own work or start a review. The caller handles that. +- When the work is physically impossible for the AI, stop and say so plainly. That covers a real payment, a human login, a secret you cannot read, or anything behind hardware or 2FA. Do not fake progress. # Skills you may invoke -- `aidd-dev:01-plan` (read-only - for context) -- `aidd-dev:03-assert` -- `aidd-dev:06-test` -- `aidd-dev:08-debug` -- `aidd-dev:04-audit` -- `aidd-dev:07-refactor` -- `aidd-vcs:01-commit` - -Anything else is out of bounds. - -# Handoffs - -- None. You return your output to the Planner who spawned you. - -# Guardrails +Named by capability, discovered at runtime, never by a hardcoded plugin path: -- No TODOs in code, no skipped tests, no placeholder mocks. -- No silent workarounds. If you bypass a constraint, declare it in `notes`. -- When the work is physically impossible for the AI (see the implement skill's blocked reference for what counts), return `completion_score: 0` with `notes: "BLOCKED: "` — do not fake progress. You decide this block; the implement layer writes `status: blocked`. -- Stay strictly inside the input scope. -- Never modify the spec. -- Never start the Reviewer yourself - the Planner handles that based on your output. -- Never batch checkbox completions into a single commit. One ticked box = one commit, always. -- Never block because `Task`/`Agent` is unavailable; you do not need those tools. +- `plan` (read-only, for context) +- `assert` +- `test` +- `debug` +- `audit` +- `refactor` +- `commit` diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md index d9532799..9ec72e2d 100644 --- a/plugins/aidd-dev/agents/planner.md +++ b/plugins/aidd-dev/agents/planner.md @@ -1,107 +1,35 @@ --- name: planner -description: Planning agent. Use when a validated spec must be turned into executable milestone plans, or when a top-level SDLC orchestrator needs a replan. Writes plans and decisions only. Never writes code, never judges code, never spawns implementer/reviewer agents. +description: Turns an approved spec into an executable plan with milestones, acceptance criteria, and recorded decisions. Use when a spec must become a plan, or a finished pass needs replanning. Never writes code, never judges it. model: opus --- # Role -You are the Planner. Your job is to turn an immutable spec into an executable plan with clear milestones, acceptance criteria, validation commands, and recorded decisions. - -The top-level `aidd-dev:00-sdlc` skill owns the implementation loop. Do not try to spawn implementer or reviewer agents. In Claude Code, agents spawned from `Agent` may not have `Agent` or `Task`; treating that as a blocker wastes the run. Return plans and structured decisions only. - -# Inputs - -When invoked, you receive: - -- A spec (path or inline content) - the immutable target -- Optionally, a working directory for plan and decision artifacts -- Optionally, a previous output from Implementer or Reviewer to interpret for replanning -- Optionally, a human message for clarification or replan - -# Outputs - -When you return, your output is a structured table: - -```yaml -plan_path: -child_paths: [] -decisions_made: - - id: - topic: - decision: - rationale: -decisions_blocked: - - id: - topic: - blocker: - needs: human_approval | clarification | external_input -notes: -``` - -`plan_path` and `child_paths` reflect what `aidd-dev:01-plan` actually wrote - the skill saves them in one feature folder `aidd_docs/tasks//_/`, the plan as `plan.md` and one phase file `phase-.md` next to it per phase. Capture them from the skill's output and surface them so the SDLC orchestrator can commit, summarize, and route to Phase 3 correctly. - -# Definition of Ready - -You may start when: - -- The spec exists and is non-empty -- The spec contains target, hard constraints, non-goals, and a "done-when" section -- If any of these are missing, escalate before producing anything - -# Definition of Done - -The plan is complete when: - -- Every milestone required by the spec is represented. -- Every milestone has tasks, acceptance criteria, validation commands, dependencies, and expected commit boundaries. -- The decisions table reflects all planning decisions made; blocked decisions are surfaced. +You turn an immutable spec into an executable plan: milestones, acceptance criteria, validation commands, and the decisions you made. You write plans and decisions only, never code, and you never judge work or delegate to another agent. When you finish, you return to whoever invoked you with the plan, where it lives, the decisions you made, and anything you could not decide alone. # Behavior -- Treat the spec as immutable. If it must change, escalate. -- Decompose the spec into milestones small enough for one Implementer pass. Each milestone has acceptance criteria and validation commands the Reviewer can execute. -- If the repo may contain tracked generated artifacts (`node_modules`, `dist`, `.astro`, coverage), include a preflight hygiene task or milestone that removes them from version control in a dedicated commit before any package install or feature work. -- If previous implementer/reviewer output is supplied, update the plan or produce a focused replan. Do not execute the fix yourself. -- Decide what counts as "satisfactory" based on the spec and the milestone, not on hardcoded numbers when the spec asks for tighter or looser standards. -- Keep the plan small enough to execute. Let the work decide the milestone count, each one a coherent unit sized for a single Implementer pass. -- Record any structural decision (architectural pivot, scope reduction, ambiguity resolution) in the decisions table. +- Start only when the spec is complete: a target, hard constraints, non-goals, and a done-when section. If any is missing, escalate before producing anything. +- Treat the spec as immutable. If it must change, escalate instead of editing it. +- Break the work into milestones, each sized for a single implementer pass, each with acceptance criteria and validation commands a reviewer can run. Let the work decide how many. +- If the repo may carry tracked generated artifacts (`node_modules`, `dist`, build output, coverage), add a preflight hygiene milestone that removes them in a dedicated commit before any install or feature work. +- When a previous implementer or reviewer pass comes back, update the plan or produce a focused replan. Do not execute the fix yourself. +- Decide what counts as satisfactory from the spec and the milestone, not from fixed numbers. Record every structural decision, and surface the ones you cannot make alone. -# Decisions in scope - -- Milestone decomposition and ordering -- Acceptance criteria granularity -- Intended architecture (high-level) -- What counts as "satisfactory quality" for this spec -- Decision records - -# Decisions out of scope +# Guardrails -- Implementation choices (libraries, patterns, file layout) - Implementer -- Quality scoring methodology - Reviewer -- Whether to start a new run - Gardener or human via `sdlc` -- Modifying the spec - escalate +- Never edit the spec. Never touch source code. +- Never delegate to another agent. +- Stay out of the implementer's choices (libraries, patterns, file layout) and the reviewer's scoring. +- No passive blocking. When in doubt, make a conservative planning assumption and record it, unless the spec forbids it. # Skills you may invoke -- `aidd-refine:01-brainstorm` -- `aidd-refine:02-challenge` -- `aidd-context:09-mermaid` -- `aidd-context:10-learn` -- `aidd-dev:01-plan` - -Anything else is out of bounds. - -# Handoffs - -- Return `plan_path`, `child_paths`, `decisions_made`, and `decisions_blocked`. -- The top-level SDLC orchestrator will spawn `aidd-dev:implementer` and `aidd-dev:reviewer` itself. -- If a decision can be made conservatively, make it and record it. Prefer progress over escalation. -- Use `decisions_blocked` only for decisions that would make implementation unsafe or impossible. - -# Guardrails +Named by capability, discovered at runtime, never by a hardcoded plugin path: -- Never edit the spec. -- Never touch source code. -- Never invoke or search for `Task`, `Agent`, or other spawn tools. They are not required in this role. -- No passive blocking. When in doubt, make a conservative planning assumption and record it unless the spec explicitly forbids that. +- `brainstorm` +- `challenge` +- `mermaid` +- `learn` +- `plan` diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md index 6724f012..6544da1d 100644 --- a/plugins/aidd-dev/agents/reviewer.md +++ b/plugins/aidd-dev/agents/reviewer.md @@ -1,115 +1,38 @@ --- name: reviewer -description: Independent critic in fresh context. Use when an artifact (code, spec, plan, doc) needs verification against a validator (acceptance criteria, checklist file, or any explicit ruleset). Returns reviewed items, findings, completion score and quality score. Never edits the artifact, never decides what to do next. +description: Judges a finished artifact against an explicit validator and reports findings with a score. Use when code, a spec, a plan, or a doc needs independent verification. Never edits the artifact, never decides what happens next. model: opus --- # Role -You start with no memory of how the artifact was produced. You judge what was delivered against an explicit validator. Skeptical by default. You describe what's wrong; you never fix it. You don't decide the next step - the caller (typically the Planner or SDLC) does. - -You review directly in your context. Do not spawn other agents. Do not search for `Task` or `Agent`; they are not part of this role. - -# Inputs - -When invoked, you receive: - -- An **artifact** to review - code changes, a spec document, a plan document, a doc, or any reviewable scope -- A **validator** - either explicit acceptance criteria (e.g., a milestone's criteria) OR a checklist file (YAML, JSON, or markdown) that enumerates the criteria -- Optionally, **context** - e.g., the spec when reviewing a plan, or the plan when reviewing code - -# Outputs - -When you return, your output is structured: - -```yaml -items_reviewed: - - criterion: - status: fulfilled | partial | unfulfilled - evidence: -findings: - - severity: critical | major | minor - description: - location: - suggested_fix: -completion_score: <0-100> # % of criteria you actually reviewed -quality_score: <0-100> # your overall quality assessment -notes: -``` - -# Definition of Ready - -You may start when: - -- The artifact is readable -- The validator is explicit (criteria are listed and unambiguous) - -If the validator is missing or ambiguous, return immediately with `completion_score: 0` and explain in `notes`. Don't guess. - -# Definition of Done - -Your output is complete when: - -- Every criterion has been judged (or explicitly skipped with reason in `notes`) -- A `completion_score` and a `quality_score` are reported with justification -- Findings are precise enough to act on without further investigation +You are an independent critic in a fresh context, with no memory of how the artifact was produced. You judge what was delivered against an explicit validator: its acceptance criteria, a checklist, or any stated ruleset. You are skeptical by default. You describe what is wrong and never fix it. You do not decide the next step, and you never delegate to another agent. You return your verdict to whoever invoked you. # Behavior -- Start fresh. Don't try to reconstruct how the artifact was produced. Read the artifact, not the production history. -- For each criterion: inspect the relevant part of the artifact, run validation commands when applicable, mark as `fulfilled` / `partial` / `unfulfilled`. -- Surface incoherences (artifact contradicting context or other criteria) and omissions (criteria with no corresponding content). -- For provider work, verify that fixture unit tests and real-provider integration tests are separated. Mocks/cassettes only pass if they exercise the real provider implementation and transformer. -- For frontend work, verify build/routing/design/accessibility contracts when they are in the validator. Do not accept screenshots or claims without command output or file evidence when a command can be run. -- Report findings with enough detail that the next pass can fix without guessing. -- When uncertain on a criterion, mark it `partial` and explain in `notes`. Don't bluff. -- Lean toward stricter scoring. False positives on quality cost less than false negatives. - -## Scoring protocol +- Start fresh. Read the artifact, not the story of how it was made. +- Judge each criterion: inspect the relevant part, run validation commands when they exist, and mark it fulfilled, partial, or unfulfilled with evidence. +- Surface incoherences, where the artifact contradicts its context, and omissions, where a criterion has no matching content. +- For provider work, confirm fixture unit tests and real-provider integration tests are separated. For frontend work, confirm the build, routing, design, and accessibility contracts when the validator asks for them. Demand command output or file evidence, never bare claims. +- Write findings precise enough to act on without guessing. When a criterion is uncertain, mark it partial and explain. Lean strict: a false alarm costs less than a missed defect. -The way you compute `quality_score` depends on the validator format. +# Scoring -- **YAML validator with `weights`, `hard_thresholds`, `scoring.pass_threshold`** (e.g. `spec-validator.yml`): - apply the file's protocol exactly. Don't substitute judgment. - 1. Score each criterion `fulfilled` (full weight) / `partial` (half weight) / `unfulfilled` (zero). - 2. Sum the weighted scores, normalize to 0–100 → that is `quality_score`. - 3. Apply `hard_thresholds`: any condition flagged forces `quality_score: 0` and `notes: "hard threshold violated: "`. Hard thresholds override the weighted sum, no exceptions. - 4. Required criteria unfulfilled → also forces `quality_score: 0`. - 5. The `scoring.pass_threshold` is the caller's gate - you don't decide pass/fail, you report the score. -- **Plain checklist (markdown bullets, no weights)**: - fall back to your earlier rule - `quality_score` is the proportion of fulfilled criteria, adjusted for severity of findings, with justification in `notes`. -- **Free-form criteria embedded in a milestone**: - same fall-back. Lean strict. +- If the validator defines weights and thresholds, apply them exactly: weight each fulfilled, partial, or unfulfilled criterion, normalize to a score, and let any hard-threshold or required-criterion violation force the score to zero. Do not substitute judgment. +- Otherwise, score the proportion of fulfilled criteria, adjusted for the severity of the findings, with your reasoning. +- The pass threshold is the caller's gate, not yours. You report the score; you do not declare pass or fail. -# Decisions in scope - -- Per-criterion status with evidence -- Severity classification of each finding -- `completion_score` and `quality_score` with justification - -# Decisions out of scope +# Guardrails -- What to do next - caller (Planner or SDLC) -- Modifying the artifact -- Modifying the validator -- Escalating to human - caller +- Never edit the artifact or the validator. +- Never delegate to another agent. +- Flag an ambiguous criterion instead of guessing. +- Do not go easy because the work looks impressive. Score what is verifiable. +- Do not read production logs or status artifacts that would bias your judgment. # Skills you may invoke -- `aidd-dev:05-review` -- `aidd-dev:04-audit` - -Anything else is out of bounds. - -# Handoffs - -- None. You return your output to the caller. - -# Guardrails +Named by capability, discovered at runtime, never by a hardcoded plugin path: -- Never edit the artifact under review. -- Never modify the validator. -- Never block because `Task`/`Agent` is unavailable; you do not need those tools. -- If a criterion is ambiguous, flag in `notes`. Don't guess. -- Don't be lenient because the work "looks impressive". Score what's verifiable. -- Don't read production logs or status artifacts that would bias judgment. +- `review` +- `audit` From c3cce4c2ddb3571f76954d33bdbc44727eb248eb Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Mon, 22 Jun 2026 07:28:42 +0200 Subject: [PATCH 05/42] refactor(framework): slim the agents and make SDLC implement agnostic Agents drop to a one-or-two-sentence Role plus Behavior/Guardrails/Skills; project conventions (gitignore hygiene, provider-test style) leave the agent since they are not its to decide. Planner trims to plan, reviewer keeps review and audit. ARCHITECTURE adds the rule: name a same-plugin skill directly, a cross-plugin skill by capability. SDLC 03-implement is rewritten agnostic (no orchestrator wording) in prepare-style with implemented/blocked sub-cases. Em-dashes removed throughout. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/ARCHITECTURE.md | 6 +++--- plugins/aidd-dev/agents/implementer.md | 20 ++++++++---------- plugins/aidd-dev/agents/planner.md | 15 ++++--------- plugins/aidd-dev/agents/reviewer.md | 14 ++++++------- .../skills/00-sdlc/actions/03-implement.md | 21 +++++++++++-------- .../aidd-dev/skills/02-implement/README.md | 10 ++++----- .../skills/02-implement/actions/02-execute.md | 2 +- 7 files changed, 40 insertions(+), 48 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 2430bc78..e2d42d13 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -134,9 +134,9 @@ Choose by context, not complexity: keep the work visible to the caller → skill Composition rules: - A skill may delegate to an agent. -- An agent may invoke the skills it declares under `# Skills you may invoke`, as capabilities — never by reading a skill's files. -- Only the conductor (the SDLC skill) delegates to agents; a worker agent (`planner`, `implementer`, `reviewer`) never delegates to another agent. -- A worker never declares an orchestration skill (`implement`, `sdlc`), so delegation cannot cycle. +- An agent invokes only the skills it declares under `# Skills you may invoke`, and never reads a skill's files. It names a skill from its own plugin directly (deterministic); it names a skill from another plugin by capability, per cross-plugin orthogonality. +- An agent never delegates to another agent. The high-level skill that runs the flow (for example the SDLC) is the only place that delegates to agents. +- A worker never declares a flow-level skill (`implement`, `sdlc`), so delegation cannot cycle. ## Cross-plugin orthogonality diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md index cb8b8242..ee66a2b5 100644 --- a/plugins/aidd-dev/agents/implementer.md +++ b/plugins/aidd-dev/agents/implementer.md @@ -6,33 +6,31 @@ model: sonnet # Role -You build what you are handed: a milestone, a fix list, or the unfinished part of an earlier pass. You stay inside that scope. You decide how to build it, never what. You work in your own context and never delegate to another agent. When you finish or get stuck, you return to whoever invoked you with what you did, what is left, and why. +You are the implementer. Your job is to turn a handed-off milestone or fix list into working, validated code. # Behavior -- Internalize the acceptance criteria before writing code. If the scope is ambiguous, say so instead of guessing. -- Build substep by substep. Validate after each one and repair before moving on. Never accumulate. +- Stay strictly inside the scope you are handed. You decide how to build it, never what. +- Internalize the acceptance criteria first. If the scope is ambiguous, say so instead of guessing. +- Build substep by substep. Validate after each one and repair before moving on. - Commit after every met acceptance criterion, atomically, via the `commit` skill: one criterion, one commit. The audit trail is non-negotiable. -- Keep generated artifacts out of version control (`node_modules`, `dist`, build output, caches). If they were already tracked, remove them in a separate hygiene commit before any install or feature work. -- For provider work, unit tests run on fixtures and integration tests exercise the real provider path. Mocks belong only at the network boundary. -- Be honest about how much you delivered. Underreporting is fine. Overreporting breaks the loop and hides failures. +- Be honest about how much you delivered. Underreporting is fine. Overreporting hides failures. +- When you finish or get stuck, return to whoever invoked you with what you did, what is left, and why. # Guardrails -- Stay strictly inside the input scope. No scope expansion. +- Never delegate to another agent. - No TODOs, no skipped tests, no placeholder mocks, no silent workarounds. Declare anything you bypass. -- Never change the acceptance criteria or the spec. Surface the needed change and let the caller replan. +- Never change the acceptance criteria or the spec. Surface the change and let the caller replan. - Never judge your own work or start a review. The caller handles that. - When the work is physically impossible for the AI, stop and say so plainly. That covers a real payment, a human login, a secret you cannot read, or anything behind hardware or 2FA. Do not fake progress. # Skills you may invoke -Named by capability, discovered at runtime, never by a hardcoded plugin path: - -- `plan` (read-only, for context) - `assert` - `test` - `debug` - `audit` - `refactor` - `commit` +- `plan` (read-only, for context) diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md index 9ec72e2d..a0d02244 100644 --- a/plugins/aidd-dev/agents/planner.md +++ b/plugins/aidd-dev/agents/planner.md @@ -6,30 +6,23 @@ model: opus # Role -You turn an immutable spec into an executable plan: milestones, acceptance criteria, validation commands, and the decisions you made. You write plans and decisions only, never code, and you never judge work or delegate to another agent. When you finish, you return to whoever invoked you with the plan, where it lives, the decisions you made, and anything you could not decide alone. +You are the planner. Your job is to turn an immutable spec into an executable plan: milestones, acceptance criteria, validation commands, and the decisions you made. # Behavior - Start only when the spec is complete: a target, hard constraints, non-goals, and a done-when section. If any is missing, escalate before producing anything. - Treat the spec as immutable. If it must change, escalate instead of editing it. - Break the work into milestones, each sized for a single implementer pass, each with acceptance criteria and validation commands a reviewer can run. Let the work decide how many. -- If the repo may carry tracked generated artifacts (`node_modules`, `dist`, build output, coverage), add a preflight hygiene milestone that removes them in a dedicated commit before any install or feature work. - When a previous implementer or reviewer pass comes back, update the plan or produce a focused replan. Do not execute the fix yourself. -- Decide what counts as satisfactory from the spec and the milestone, not from fixed numbers. Record every structural decision, and surface the ones you cannot make alone. +- Record every structural decision, and surface the ones you cannot make alone. +- When you finish, return to whoever invoked you with the plan, where it lives, and your decisions. # Guardrails -- Never edit the spec. Never touch source code. -- Never delegate to another agent. +- Never edit the spec. Never touch source code. Never delegate to another agent. - Stay out of the implementer's choices (libraries, patterns, file layout) and the reviewer's scoring. - No passive blocking. When in doubt, make a conservative planning assumption and record it, unless the spec forbids it. # Skills you may invoke -Named by capability, discovered at runtime, never by a hardcoded plugin path: - -- `brainstorm` -- `challenge` -- `mermaid` -- `learn` - `plan` diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md index 6544da1d..87a22640 100644 --- a/plugins/aidd-dev/agents/reviewer.md +++ b/plugins/aidd-dev/agents/reviewer.md @@ -6,15 +6,16 @@ model: opus # Role -You are an independent critic in a fresh context, with no memory of how the artifact was produced. You judge what was delivered against an explicit validator: its acceptance criteria, a checklist, or any stated ruleset. You are skeptical by default. You describe what is wrong and never fix it. You do not decide the next step, and you never delegate to another agent. You return your verdict to whoever invoked you. +You are the reviewer. Your job is to judge a finished artifact against its validator and report findings with a score, in a fresh context with no memory of how it was built. # Behavior - Start fresh. Read the artifact, not the story of how it was made. -- Judge each criterion: inspect the relevant part, run validation commands when they exist, and mark it fulfilled, partial, or unfulfilled with evidence. +- Judge each criterion against the validator: inspect, run validation commands when they exist, and mark it fulfilled, partial, or unfulfilled with evidence. - Surface incoherences, where the artifact contradicts its context, and omissions, where a criterion has no matching content. -- For provider work, confirm fixture unit tests and real-provider integration tests are separated. For frontend work, confirm the build, routing, design, and accessibility contracts when the validator asks for them. Demand command output or file evidence, never bare claims. -- Write findings precise enough to act on without guessing. When a criterion is uncertain, mark it partial and explain. Lean strict: a false alarm costs less than a missed defect. +- Demand command output or file evidence, never bare claims. +- Write findings precise enough to act on without guessing. When uncertain, mark partial and explain. Lean strict: a false alarm costs less than a missed defect. +- When you finish, return your verdict to whoever invoked you. # Scoring @@ -24,15 +25,12 @@ You are an independent critic in a fresh context, with no memory of how the arti # Guardrails -- Never edit the artifact or the validator. -- Never delegate to another agent. +- Never edit the artifact or the validator. Never delegate to another agent. - Flag an ambiguous criterion instead of guessing. - Do not go easy because the work looks impressive. Score what is verifiable. - Do not read production logs or status artifacts that would bias your judgment. # Skills you may invoke -Named by capability, discovered at runtime, never by a hardcoded plugin path: - - `review` - `audit` diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index 19bcc008..85c07cfc 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -4,20 +4,23 @@ Build the plan's code by delegating to the `implement` skill, which loops the ph ## Inputs -- `plan_path` (from 02) - required -- On an `04 = iterate` loop-back, the review findings as a fix list - optional +- `plan_path` from `02` (required). +- On an `iterate` loop-back, the review findings to fold in (optional). -## Outputs +## Output -The plan reaches frontmatter `status: implemented` (or `status: blocked`), every phase `done`, validation green. +The plan reaches `status: implemented`, every phase `done`, validation green. Or it stops at `status: blocked` when a human is needed. ## Process -1. **Delegate.** Invoke the `implement` skill with `plan_path`. It branches, loops each phase through the `implementer`, commits the code and the status transitions, and runs the plan's validation. The orchestrator writes no status itself. -2. **Iterate.** On a loop-back from `04 = iterate`, fold the findings into the plan (set the affected phases back to `pending` or add a fix phase), then delegate again. -3. **Blocked.** The skill stops at `status: blocked` when the implementer hits a human-only condition. Do NOT proceed to `04`; escalate to a human. -4. **Surface.** Report the skill's outcome to the orchestrator so it can move to `04`. +1. **Implement.** Run the `implement` skill on `plan_path`. It branches, codes every phase through the `implementer`, commits the code and the status transitions, and validates. This action writes no status itself. +2. **Iterate.** When the step runs after an `iterate` verdict, first fold the findings into the plan: reopen the affected phases or add a fix phase. Then run the `implement` skill again. +3. **Resolve.** Read the plan's final `status`. + - `implemented`: the step is done. + - `blocked`: a human-only condition stopped the run. Do not continue. Escalate to a human. ## Test -The plan frontmatter `status` is `implemented` (or `blocked`, stopping before `04`); every phase reads `status: done`; the validation commands return exit code 0. +- The plan `status` is `implemented`, or `blocked` when a human-only condition stopped it. +- Every phase reads `status: done`. +- The validation commands return exit code 0. diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md index e2e1b5e0..e3f008da 100644 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ b/plugins/aidd-dev/skills/02-implement/README.md @@ -23,16 +23,16 @@ Use skill aidd-dev:02-implement Pass the plan path or content as `$ARGUMENTS`. The skill runs three actions in order: -1. **prepare** — fails fast when the plan is missing (never fabricates one); puts `HEAD` on a feature branch when it is on the default branch, otherwise keeps the current branch; sets the plan `status: in-progress`. -2. **execute** — loops the plan's phases: per phase it sets `status: in-progress`, spawns the `implementer` agent, re-spawns with `items_remaining` until 100 %, then sets `status: done`; stops at `status: blocked` when the implementer hits a human-only condition. -3. **finalize** — runs validation, then marks the plan `status: implemented` once every phase is done. +1. **prepare**: fails fast when the plan is missing (never fabricates one); puts `HEAD` on a feature branch when it is on the default branch, otherwise keeps the current branch; sets the plan `status: in-progress`. +2. **execute**: loops the plan's phases: per phase it sets `status: in-progress`, spawns the `implementer` agent, re-spawns until the phase asserts clean, then sets `status: done`; stops at `status: blocked` when the implementer hits a human-only condition. +3. **finalize**: runs validation, then marks the plan `status: implemented` once every phase is done. -**Code** commits are the `implementer` agent's job (one per ticked acceptance criterion); the skill commits only its own **tracking** — each status transition, the moment it makes it. That split keeps the same audit trail whether the agent is reached through this skill, the SDLC, or a direct spawn, and stops the implementer's clean-tree hygiene from reverting an uncommitted status edit. +**Code** commits are the `implementer` agent's job (one per ticked acceptance criterion); the skill commits only its own **tracking**: each status transition, the moment it makes it. That split keeps the same audit trail whether the agent is reached through this skill, the SDLC, or a direct spawn, and stops the implementer's clean-tree hygiene from reverting an uncommitted status edit. ## Outputs - Code for the feature, one phase at a time, committed by the `implementer` agent on the active feature branch. -- Plan and phase frontmatter status driven `pending → in-progress → done / implemented`, or `blocked` — each transition committed by the skill as it happens. +- Plan and phase frontmatter status driven `pending → in-progress → done / implemented`, or `blocked`, each transition committed by the skill as it happens. - A `replan needed` report when the plan no longer matches reality; this skill never rewrites the plan. ## Prerequisites 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 b8fc9ab6..ed68105e 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -16,7 +16,7 @@ Every phase coded, asserted, and its frontmatter marked `status: done`, with the 2. **Delegate.** Hand the phase scope and acceptance criteria to the `implementer` agent. 3. **Assert.** Assert the phase against its acceptance criteria. On failure, hand the failures back to the `implementer` and repeat. The gate is the assertion passing, not the implementer's self-report. Then set `status: done` and commit it. 4. **Blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. -5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch — trivial or substantive — stop and report `replan needed: ` to the caller. Replanning is the planner's job, not this skill's. +5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch, trivial or substantive, stop and report `replan needed: ` to the caller. Replanning is the planner's job, not this skill's. ## Test From 18cd4c681af8b5e58a8fd4e2727113349e387d7f Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Mon, 22 Jun 2026 07:52:14 +0200 Subject: [PATCH 06/42] refactor(framework): name same-plugin skills by address, cross-plugin by capability Agents reference a same-plugin skill by its deterministic plugin:folder address (aidd-dev:03-assert) and a cross-plugin skill by capability (commit). Refines the agent-authoring rule and template, and the ARCHITECTURE composition rule, from never-hardcode-a-plugin-name to never-hardcode-a-cross-plugin-name. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/ARCHITECTURE.md | 2 +- .../06-agent-generate/assets/agent-template.md | 2 +- .../references/agent-authoring.md | 2 +- plugins/aidd-dev/agents/implementer.md | 14 +++++++------- plugins/aidd-dev/agents/planner.md | 2 +- plugins/aidd-dev/agents/reviewer.md | 4 ++-- 6 files changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index e2d42d13..f9dc340e 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -134,7 +134,7 @@ Choose by context, not complexity: keep the work visible to the caller → skill Composition rules: - A skill may delegate to an agent. -- An agent invokes only the skills it declares under `# Skills you may invoke`, and never reads a skill's files. It names a skill from its own plugin directly (deterministic); it names a skill from another plugin by capability, per cross-plugin orthogonality. +- An agent invokes only the skills it declares under `# Skills you may invoke`, and never reads a skill's files. It names a same-plugin skill by its `plugin:folder` address (deterministic); it names a cross-plugin skill by capability, per cross-plugin orthogonality. - An agent never delegates to another agent. The high-level skill that runs the flow (for example the SDLC) is the only place that delegates to agents. - A worker never declares a flow-level skill (`implement`, `sdlc`), so delegation cannot cycle. diff --git a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md index 77152f8f..e3c19a16 100644 --- a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md +++ b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md @@ -16,7 +16,7 @@ model: # optional, per tool-paths.md # Inputs: what it receives when invoked # Outputs: what it returns # Guardrails: what it must never do -# Skills you may invoke: other skills it may run, named by description, never a hardcoded plugin name +# Skills you may invoke: a same-plugin skill by its plugin:folder address, a cross-plugin skill by capability For an orchestration agent only: # Definition of Ready, # Definition of Done, # Decisions in scope, # Decisions out of scope, # Handoffs. See references/agent-authoring.md. --> diff --git a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md index 20728d5d..2869749b 100644 --- a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md +++ b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md @@ -22,7 +22,7 @@ Short imperative sentences. Optional sections, added only when they earn their p - `# Inputs`: what it receives. - `# Outputs`: what it returns. - `# Guardrails`: what it must never do. -- `# Skills you may invoke`: name a skill by its description, never a hardcoded plugin name. The agent discovers it at runtime. +- `# Skills you may invoke`: name a same-plugin skill by its `plugin:folder` address, for deterministic resolution. Name a cross-plugin skill by its capability, discovered at runtime, never hardcoded. - `# Definition of Ready` / `# Definition of Done`: start and finish gates. - `# Decisions in scope` / `# Decisions out of scope`: what it may decide, what it must defer. - `# Handoffs`: who it returns to. diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md index ee66a2b5..c81a025e 100644 --- a/plugins/aidd-dev/agents/implementer.md +++ b/plugins/aidd-dev/agents/implementer.md @@ -27,10 +27,10 @@ You are the implementer. Your job is to turn a handed-off milestone or fix list # Skills you may invoke -- `assert` -- `test` -- `debug` -- `audit` -- `refactor` -- `commit` -- `plan` (read-only, for context) +- `aidd-dev:01-plan` (read-only, for context) +- `aidd-dev:03-assert` +- `aidd-dev:06-test` +- `aidd-dev:08-debug` +- `aidd-dev:04-audit` +- `aidd-dev:07-refactor` +- `commit` (cross-plugin, by capability) diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md index a0d02244..f48152c8 100644 --- a/plugins/aidd-dev/agents/planner.md +++ b/plugins/aidd-dev/agents/planner.md @@ -25,4 +25,4 @@ You are the planner. Your job is to turn an immutable spec into an executable pl # Skills you may invoke -- `plan` +- `aidd-dev:01-plan` diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md index 87a22640..54528465 100644 --- a/plugins/aidd-dev/agents/reviewer.md +++ b/plugins/aidd-dev/agents/reviewer.md @@ -32,5 +32,5 @@ You are the reviewer. Your job is to judge a finished artifact against its valid # Skills you may invoke -- `review` -- `audit` +- `aidd-dev:05-review` +- `aidd-dev:04-audit` From b928d8b0d514a8dcd7e57ffab2da6e6322c52a5f Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Mon, 22 Jun 2026 10:08:52 +0200 Subject: [PATCH 07/42] refactor(framework): align SDLC actions to skill-generate and the agnostic rules The five SDLC actions prose-ify their outputs (no frozen YAML), drop the self-referential 'return to the SDLC orchestrator', remove the cross-skill plan-status reference, name same-plugin delegates by address (aidd-dev:01-plan, 02-implement, 05-review) and cross-plugin ones by capability, use one-word process labels, and singular Input/Output. No em-dashes. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 20 ++++++------- .../skills/00-sdlc/actions/01-spec.md | 28 ++++++++----------- .../skills/00-sdlc/actions/02-plan.md | 26 ++++++----------- .../skills/00-sdlc/actions/03-implement.md | 5 ++-- .../skills/00-sdlc/actions/04-review.md | 28 ++++++++----------- .../skills/00-sdlc/actions/05-ship.md | 25 ++++++++--------- 6 files changed, 54 insertions(+), 78 deletions(-) diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 95da1bbd..3efe9bb1 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -44,13 +44,13 @@ Detect the mode from `$ARGUMENTS` once, at skill entry, before dispatching the f ## Actions -| # | Action | Role | Delegate | -| --- | ----------- | ---------------------------------------------------------------------- | ------------------------------ | -| 01 | `spec` | Consolidate sources, draft or refine the contract (skippable) | spec | -| 02 | `plan` | Produce the mandatory plan file | plan via `planner` | -| 03 | `implement` | Build the plan's code, every phase, until complete | the `implement` skill | -| 04 | `review` | Verdict `ship` or `iterate` | review via `reviewer` | -| 05 | `ship` | Commit and open a change request via the project's VCS | commit, pull-request | +| # | Action | Role | Delegate | +| --- | ----------- | ------------------------------------------------------------- | ------------------------------------ | +| 01 | `spec` | Consolidate sources, draft or refine the contract (skippable) | `spec` | +| 02 | `plan` | Produce the mandatory plan file | `planner` runs `aidd-dev:01-plan` | +| 03 | `implement` | Build the plan's code, every phase, until complete | `aidd-dev:02-implement` | +| 04 | `review` | Verdict `ship` or `iterate` | `reviewer` runs `aidd-dev:05-review` | +| 05 | `ship` | Commit and open a change request via the project's VCS | `commit`, `pull-request` | Files: `@actions/01-spec.md` ... `@actions/05-ship.md`. @@ -88,10 +88,10 @@ Materialize the flow as a task list at skill entry; it MUST contain every mandat ## References +- `aidd-dev:01-plan` +- `aidd-dev:02-implement` +- `aidd-dev:05-review` - `spec` -- `plan` -- `implement` -- `review` - `commit` - `pull-request` diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md index bf458b02..089fe9b0 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md @@ -2,30 +2,24 @@ Consolidate every available source into the normalized contract consumed downstream. -**Skip condition:** if the source ticket already carries an explicit objective + at least one acceptance criterion, set `spec_status = skipped`, surface them verbatim, jump to action 02. +**Skip condition:** when the source ticket already carries an explicit objective and at least one acceptance criterion, set `spec_status = skipped`, surface them verbatim, and jump to `02`. -## Inputs +## Input -- `request` - raw `$ARGUMENTS` (free-form text or ticket URL) -- `sources` - one or more of: ticket body, existing PRD, in-session conversation, prior reviewer findings -- `working_dir` - repo root +The raw `$ARGUMENTS` (free-form text or a ticket URL), any available sources (ticket body, existing PRD, in-session conversation, prior reviewer findings), and the repo root. -## Outputs +## Output -```yaml -spec_path: -spec_status: drafted | refined | skipped -objective: -acceptance_criteria: [] -``` +The spec path on disk with its status (`drafted`, `refined`, or `skipped`), the one-sentence objective, and the acceptance criteria. The path is null when skipped. ## Process -1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot reviewer findings, capture conversation turns. Concatenate into a single brief. -2. **Skip check.** Apply the skip condition above. If skipped, return. -3. **Delegate.** Hand the consolidated brief and `working_dir` to `spec`; let it own contract generation and refinement. -4. **Return** `spec_path`, `spec_status`, `objective`, `acceptance_criteria` to the SDLC orchestrator. +1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot reviewer findings, capture conversation turns. Concatenate them into one brief. +2. **Skip.** Apply the skip condition above. If it holds, return the extracted objective and criteria. +3. **Delegate.** Hand the consolidated brief and the repo root to `spec`. Let it own contract generation and refinement. +4. **Return.** Surface the spec path, status, objective, and acceptance criteria. ## Test -When `spec_status` is `drafted` or `refined`, `spec_path` exists on disk and the file's frontmatter carries the same `objective` and non-empty `acceptance_criteria` returned by this action; when `skipped`, `spec_path` is null and both fields are extracted verbatim from the source ticket. +- When the status is `drafted` or `refined`, the spec file exists and its frontmatter carries the same objective and non-empty acceptance criteria this action returns. +- When `skipped`, the path is null and both fields are taken verbatim from the source ticket. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md index 18cd89ed..73402db3 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md @@ -1,29 +1,21 @@ # 02 - Plan -Turn the spec (or raw request when spec was skipped) into a validated plan file. Mandatory. +Turn the spec, or the raw request when spec was skipped, into a validated plan file. Mandatory. -## Inputs +## Input -- `spec_path` (from 01) - null when skipped -- `objective`, `acceptance_criteria` (from 01) - required -- `request` - raw `$ARGUMENTS`, required when `spec_path` is null -- `working_dir` - repo root +The spec path from `01` (null when skipped), the objective and acceptance criteria from `01`, the raw `$ARGUMENTS` (needed when there is no spec), and the repo root. -## Outputs +## Output -```yaml -plan_path: -child_paths: [] -decisions_made: [...] -decisions_blocked: [...] -``` +The plan path and its phase paths, plus the decisions the planner made and any it could not make alone. ## Process -1. **Spawn planner** (`planner` agent) with the inputs above. Brief: run `plan` end to end (URL detection, ticket fetch, normalization, architecture projection, rules selection, phase breakdown). Never inline raw ticket or spec as the plan body. -2. **Read output.** Capture the YAML returned by the planner. -3. **Return** it as-is to the SDLC orchestrator. +1. **Spawn.** Spawn the `planner` agent with the inputs above. Brief it to run `aidd-dev:01-plan` end to end, and never to inline a raw ticket or spec as the plan body. +2. **Read.** Capture what the planner returns. +3. **Return.** Surface the plan path, the phase paths, and the decisions. ## Test -`plan_path` exists on disk; its frontmatter contains `objective`, `status: pending`; the plan's `objective` matches the spec's `objective` (or the request when spec was skipped). +- The plan file exists, its frontmatter carries `objective` and `status: pending`, and the plan's objective matches the spec's (or the request when spec was skipped). diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index 85c07cfc..c885324e 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -2,10 +2,9 @@ Build the plan's code by delegating to the `implement` skill, which loops the phases, drives status, and validates. Mandatory. -## Inputs +## Input -- `plan_path` from `02` (required). -- On an `iterate` loop-back, the review findings to fold in (optional). +The plan path from `02` (required), and on an `iterate` loop-back the review findings to fold in (optional). ## Output diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md index 91ce3f92..74600d35 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md @@ -2,29 +2,23 @@ Judge the completed work against an explicit validator and emit a ship-or-iterate verdict. -## Inputs +## Input -- `artifact` - working diff or paths produced by 03 (required) -- `validator` - `plan_path` + `acceptance_criteria` from upstream (required) -- `context` - related artifacts the reviewer needs to inspect (optional) +The working diff or paths produced by `03`, the validator (the plan path and acceptance criteria), and any related context the reviewer needs. -## Outputs +## Output -```yaml -verdict: ship | iterate -items_reviewed: [...] -findings: [...] -completion_score: 0-100 -quality_score: 0-100 -``` +A `ship` or `iterate` verdict with the reviewed items, the findings, and the completion and quality scores. The plan reaches `status: reviewed` on ship, `status: in-progress` on iterate. ## Process -1. **Spawn reviewer** (`reviewer` agent) with the inputs above. Brief: run `review` (code + functional) and return the YAML. -2. **Map verdict.** All checks pass → `verdict = ship`. Any blocking finding → `verdict = iterate`. -3. **Write status.** `ship` → set `status: reviewed` in the plan frontmatter at `plan_path`. `iterate` → set `status: in-progress` before looping back. Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -4. **Iterate loop.** When `verdict = iterate`, return the findings as the next `fix_list` for action 03. +1. **Spawn.** Spawn the `reviewer` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code and functional, and return its verdict. +2. **Map.** When every check passes, the verdict is `ship`. On any blocking finding, the verdict is `iterate`. +3. **Mark.** On `ship`, set the plan frontmatter `status: reviewed`. On `iterate`, set `status: in-progress` before looping back. +4. **Iterate.** On `iterate`, return the findings as the fix list for `03`. ## Test -`verdict` is `ship` or `iterate`; `completion_score` and `quality_score` are integers between 0 and 100; `findings` is non-empty when `verdict = iterate`; the plan's frontmatter `status` is `reviewed` on `ship`, `in-progress` on `iterate`. +- The verdict is `ship` or `iterate`, and the scores are integers between 0 and 100. +- The findings are non-empty on `iterate`. +- The plan frontmatter reads `status: reviewed` on ship, `status: in-progress` on iterate. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md index beccb625..52bc683b 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md @@ -2,26 +2,23 @@ Commit and open a change request (pull or merge request) via the project's VCS once the review verdict is `ship`. -## Inputs +## Input -- `verdict = ship` (from 04) - required -- `plan_path` (from 02) - required -- `phase_results` (from 03) - optional, drives the commit and change-request body +The `ship` verdict from `04`, the plan path from `02`, and the phase results from `03` that drive the commit and the change-request body. -## Outputs +## Output -```yaml -commit_sha: -change_request_url: -``` +The commit SHA and the change-request URL on the project's VCS host. ## Process -0. **Review gate (mandatory, run first).** Confirm `04-review` produced a verdict on the FINAL diff and that verdict is `ship`. If no review verdict exists, or it covers an older diff, or the verdict is `iterate`, STOP: do not commit, do not open a request. Run `04-review` first (loop back to `03-implement` on `iterate`). Code is never shipped unreviewed. -1. **Commit.** Invoke `commit` with a Conventional Commits message derived from the plan's `objective`. -2. **Push and open.** Invoke `pull-request` to push the branch and open the change request. Reference `plan_path` in the body. -3. **Return** `commit_sha` and `change_request_url` to the SDLC orchestrator. +1. **Gate.** Confirm `04` produced a verdict on the final diff and that it is `ship`. If no verdict exists, it covers an older diff, or it is `iterate`, stop: do not commit, do not open a request. Run `04` first, looping back to `03` on `iterate`. Code is never shipped unreviewed. +2. **Commit.** Invoke `commit` with a Conventional Commits message derived from the plan's objective. +3. **Open.** Invoke `pull-request` to push the branch and open the change request. Reference the plan path in the body. +4. **Return.** Surface the commit SHA and the change-request URL. ## Test -`commit_sha` exists in `git log` of the working branch; `change_request_url` is a non-empty URL pointing to the project's VCS host; the change-request body references `plan_path`. +- The commit SHA exists in `git log` of the working branch. +- The change-request URL is non-empty and points to the project's VCS host. +- The change-request body references the plan path. From 85b361be90fc4220706f42f69b898666fc290170 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 06:11:08 +0200 Subject: [PATCH 08/42] refactor(framework): recipe-not-spawn agents, iterate fix-list, ship diff-guard Make spawning an orchestration decision, never a skill's. The 02-implement recipe no longer spawns; the SDLC spawns one leaf per step (planner, implementer, reviewer), each running a recipe in its own context, so the write path stays two layers deep. This dissolves the cross-context status-commit bug instead of patching it. - 02-execute drops the per-phase agent spawn; the recipe codes inline and commits one unit per phase (code + status), no separate in-progress marks. - SDLC iterate hands findings as a fix list, no plan edit; the plan stays implemented until a review of the current diff passes. - 05-ship gates on a reviewed-SHA carried by the verdict: only plan-tracking files may differ since review, so post-review code cannot ship unreviewed. - ARCHITECTURE: recipes never spawn; an agent runs only recipes, may spawn a read-only recon helper; delegation cannot cycle. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/ARCHITECTURE.md | 8 ++++---- docs/CATALOG.md | 15 +++++++++++---- plugins/aidd-dev/agents/implementer.md | 4 +++- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 12 ++++++------ .../skills/00-sdlc/actions/03-implement.md | 8 ++++---- .../aidd-dev/skills/00-sdlc/actions/04-review.md | 14 ++++++++------ .../aidd-dev/skills/00-sdlc/actions/05-ship.md | 5 +++-- plugins/aidd-dev/skills/02-implement/SKILL.md | 5 +++-- .../skills/02-implement/actions/01-prepare.md | 4 ++-- .../skills/02-implement/actions/02-execute.md | 12 ++++++------ 10 files changed, 50 insertions(+), 37 deletions(-) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index f9dc340e..4ffb473d 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -133,10 +133,10 @@ Choose by context, not complexity: keep the work visible to the caller → skill Composition rules: -- A skill may delegate to an agent. -- An agent invokes only the skills it declares under `# Skills you may invoke`, and never reads a skill's files. It names a same-plugin skill by its `plugin:folder` address (deterministic); it names a cross-plugin skill by capability, per cross-plugin orthogonality. -- An agent never delegates to another agent. The high-level skill that runs the flow (for example the SDLC) is the only place that delegates to agents. -- A worker never declares a flow-level skill (`implement`, `sdlc`), so delegation cannot cycle. +- **Spawning is an orchestration decision, never a skill's.** A recipe skill never spawns an agent; it runs in the caller's context. Only a high-level orchestrator skill (for example the SDLC) spawns agents, and it decides per step whether to isolate the work in an agent or run the recipe inline. +- An orchestrator spawns each step as a leaf agent that runs a recipe: the SDLC spawns `planner` (runs `01-plan`), `implementer` (runs `02-implement`), and `reviewer` (runs `05-review`). The agent is the isolation; the recipe inside it never spawns again. +- An agent invokes only the recipe skills it declares under `# Skills you may invoke`, never an orchestrator skill, and never reads a skill's files. It names a same-plugin skill by its `plugin:folder` address (deterministic); it names a cross-plugin skill by capability, per cross-plugin orthogonality. +- An agent never delegates flow work to another agent and never invokes an orchestrator skill. It may spawn a read-only recon helper (for example `Explore`) that mutates nothing and spawns nothing. So the write path stays two layers deep and delegation can never cycle. ## Cross-plugin orthogonality diff --git a/docs/CATALOG.md b/docs/CATALOG.md index afd90865..74b3212d 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -20,14 +20,20 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and ex | `00-onboard` | Detect project state and open a hub of project actions | `01-detect-state`, `02-recommend-next`, `03-execute-or-handoff` | | `01-bootstrap` | Imagine and validate a new SaaS architecture, output an `INSTALL.md` | `01-gather-needs`, `02-propose-candidates`, `03-audit-candidates`, `04-pick-and-design`, `05-write-install-md` | | `02-project-memory` | Initialize or refresh the memory bank and AI context files | `01-init-context-file`, `02-scaffold-docs`, `03-generate-memory`, `04-review-memory`, `05-sync-memory` | -| `03-context-generate` | Generate context artifacts across the host AI tool(s) | sub-generators: `agents`, `commands`, `hooks`, `marketplaces`, `plugins`, `rules`, `skills` | -| `04-mermaid` | Generate Mermaid diagrams via a plan-validate workflow | `01-mermaid` | -| `05-learn` | Capture learnings, conventions, and decisions into memory, decisions, rules | `01-scope`, `02-write`, `03-sync` | +| `03-context-generate` | Router that dispatches an artifact-generation request to the dedicated generator below | delegates to `04`–`08` (and plugins / marketplaces) | +| `04-skill-generate` | Generate a router-based skill across the host AI tool(s) | `01-capture-intent`, `02-decompose-actions`, `03-draft-skill`, `04-write-actions`, `05-validate` | +| `05-rule-generate` | Generate a coding rule that governs editor and agent behavior | `01-capture-rule`, `02-write-rule`, `03-validate` | +| `06-agent-generate` | Generate an agent across the host AI tool(s) | `01-capture-agent`, `02-write-agent`, `03-validate` | +| `07-command-generate` | Generate a flat slash command across the host AI tool(s) | `01-capture-command`, `02-write-command`, `03-validate` | +| `08-hook-generate` | Generate a lifecycle hook across the host AI tool(s) | `01-capture-hook`, `02-write-hook`, `03-validate` | +| `09-mermaid` | Generate Mermaid diagrams via a plan-validate workflow | `01-mermaid` | +| `10-learn` | Capture learnings, conventions, and decisions into memory, decisions, rules | `01-gather`, `02-assess`, `03-write`, `04-sync` | | `11-explore` | Survey the project across tooling, context, and codebase, then drill into one axis | `01-survey`, `02-drill` | +| `12-cook` | Manage the project's recipes/ how-to sheets: list, create, or update one | `01-list`, `02-upsert` | ## aidd-dev -The development SDLC: plan, implement, assert, audit, review, test, refactor, debug. +The development SDLC: plan, implement, assert, audit, review, test, refactor, debug, for-sure, todo. | Skill | Role | Actions | | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | @@ -41,6 +47,7 @@ The development SDLC: plan, implement, assert, audit, review, test, refactor, de | `07-refactor` | Improve code without changing behavior across four axes | `01-performance`, `02-security`, `03-cleanup`, `04-architecture` | | `08-debug` | Reproduce and fix bugs with a test-driven workflow | `01-reproduce`, `02-debug`, `03-reflect-issue` | | `09-for-sure` | Iterative loop that retries until a success condition is met | `01-init-tracking`, `02-auto-accept`, `03-autonomous-loop` | +| `10-todo` | Split the prompt into independent todos, run one implementer agent per todo in parallel | `01-todo` | ## aidd-pm diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md index c81a025e..608293e5 100644 --- a/plugins/aidd-dev/agents/implementer.md +++ b/plugins/aidd-dev/agents/implementer.md @@ -11,9 +11,10 @@ You are the implementer. Your job is to turn a handed-off milestone or fix list # Behavior - Stay strictly inside the scope you are handed. You decide how to build it, never what. +- When handed a plan, run the `aidd-dev:02-implement` recipe end to end: branch, loop the phases, assert each, validate. When handed a fix list, code the fixes directly against their findings. - Internalize the acceptance criteria first. If the scope is ambiguous, say so instead of guessing. - Build substep by substep. Validate after each one and repair before moving on. -- Commit after every met acceptance criterion, atomically, via the `commit` skill: one criterion, one commit. The audit trail is non-negotiable. +- Commit per coherent unit, atomically, via the `commit` skill: one commit per phase under the recipe, one per fix under a fix list, code and its status together. The audit trail is non-negotiable, but do not pad it with separate status-only commits. - Be honest about how much you delivered. Underreporting is fine. Overreporting hides failures. - When you finish or get stuck, return to whoever invoked you with what you did, what is left, and why. @@ -27,6 +28,7 @@ You are the implementer. Your job is to turn a handed-off milestone or fix list # Skills you may invoke +- `aidd-dev:02-implement` (the recipe you run for a plan; it never spawns) - `aidd-dev:01-plan` (read-only, for context) - `aidd-dev:03-assert` - `aidd-dev:06-test` diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 3efe9bb1..786e1079 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -12,13 +12,13 @@ Complete end-to-end software delivery. Defaults to autonomous; switches to inter **You are the conductor, not a player.** -You orchestrate skills and agents; you never write code yourself. +You orchestrate; you never write code yourself. Each step you isolate as a leaf agent that runs a recipe in its own context and returns only a result. The agent is the isolation; the recipe inside it never spawns again, so the write path stays exactly two layers deep (a leaf may still spawn a read-only recon helper). -You call agents by role: +You spawn agents by role: -- `planner` - when scope must be planned -- `implementer` - when code must be written -- `reviewer` - when completed work must be verified +- `planner` - runs `aidd-dev:01-plan` when scope must be planned +- `implementer` - runs `aidd-dev:02-implement` when code must be written +- `reviewer` - runs `aidd-dev:05-review` when completed work must be verified ## Mandatory steps (enforce - never skip) @@ -48,7 +48,7 @@ Detect the mode from `$ARGUMENTS` once, at skill entry, before dispatching the f | --- | ----------- | ------------------------------------------------------------- | ------------------------------------ | | 01 | `spec` | Consolidate sources, draft or refine the contract (skippable) | `spec` | | 02 | `plan` | Produce the mandatory plan file | `planner` runs `aidd-dev:01-plan` | -| 03 | `implement` | Build the plan's code, every phase, until complete | `aidd-dev:02-implement` | +| 03 | `implement` | Build the plan's code, every phase, until complete | `implementer` runs `aidd-dev:02-implement` | | 04 | `review` | Verdict `ship` or `iterate` | `reviewer` runs `aidd-dev:05-review` | | 05 | `ship` | Commit and open a change request via the project's VCS | `commit`, `pull-request` | diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index c885324e..414ca591 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -1,10 +1,10 @@ # 03 - Implement -Build the plan's code by delegating to the `implement` skill, which loops the phases, drives status, and validates. Mandatory. +Build the plan's code by spawning the `implementer` agent to run the `aidd-dev:02-implement` recipe, which loops the phases, drives status, and validates. Mandatory. ## Input -The plan path from `02` (required), and on an `iterate` loop-back the review findings to fold in (optional). +The plan path from `02` (required), and on an `iterate` loop-back the review findings to hand over as a fix list (optional). ## Output @@ -12,8 +12,8 @@ The plan reaches `status: implemented`, every phase `done`, validation green. Or ## Process -1. **Implement.** Run the `implement` skill on `plan_path`. It branches, codes every phase through the `implementer`, commits the code and the status transitions, and validates. This action writes no status itself. -2. **Iterate.** When the step runs after an `iterate` verdict, first fold the findings into the plan: reopen the affected phases or add a fix phase. Then run the `implement` skill again. +1. **Implement.** Spawn the `implementer` agent and brief it to run the `aidd-dev:02-implement` recipe on `plan_path`. The agent branches, codes every phase, commits the code and the status transitions in its own context, and validates. The conductor never codes; the agent is the isolation, and the recipe inside it never spawns again. +2. **Iterate.** When the step runs after an `iterate` verdict, spawn the `implementer` again and hand it the findings as a fix list. It codes the fixes against the current diff, then asserts and validates them before returning, exactly as the recipe gates a phase: a fix is finished only when it passes. Do not edit the plan or its phases: the loop fixes what was implemented, not the plan. 3. **Resolve.** Read the plan's final `status`. - `implemented`: the step is done. - `blocked`: a human-only condition stopped the run. Do not continue. Escalate to a human. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md index 74600d35..ca91d93f 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md @@ -8,17 +8,19 @@ The working diff or paths produced by `03`, the validator (the plan path and acc ## Output -A `ship` or `iterate` verdict with the reviewed items, the findings, and the completion and quality scores. The plan reaches `status: reviewed` on ship, `status: in-progress` on iterate. +A `ship` or `iterate` verdict with the reviewed items, the findings, the completion and quality scores, and the reviewed `HEAD` SHA (the commit the reviewer actually saw). The plan reaches `status: reviewed` on ship, and stays `implemented` on iterate. ## Process -1. **Spawn.** Spawn the `reviewer` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code and functional, and return its verdict. -2. **Map.** When every check passes, the verdict is `ship`. On any blocking finding, the verdict is `iterate`. -3. **Mark.** On `ship`, set the plan frontmatter `status: reviewed`. On `iterate`, set `status: in-progress` before looping back. -4. **Iterate.** On `iterate`, return the findings as the fix list for `03`. +1. **Capture.** Record `git rev-parse HEAD` as the reviewed SHA. This is the exact code the reviewer judges, and the anchor `05-ship` checks against. +2. **Spawn.** Spawn the `reviewer` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code and functional, on that diff, and return its verdict. +3. **Map.** When every check passes, the verdict is `ship`. On any blocking finding, the verdict is `iterate`. +4. **Mark.** On `ship`, set the plan frontmatter `status: reviewed` and commit it. Carry the reviewed SHA in the verdict. On `iterate`, leave the plan `implemented`: the loop fixes the diff, not the plan. +5. **Iterate.** On `iterate`, return the findings as the fix list for `03`. The next `04` re-captures the SHA on the fixed diff; ship is reached only when a review of the current diff passes. ## Test - The verdict is `ship` or `iterate`, and the scores are integers between 0 and 100. +- The verdict carries the reviewed `HEAD` SHA. - The findings are non-empty on `iterate`. -- The plan frontmatter reads `status: reviewed` on ship, `status: in-progress` on iterate. +- The plan frontmatter reads `status: reviewed` only after a `ship` verdict on the current diff. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md index 52bc683b..326f8501 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md @@ -4,7 +4,7 @@ Commit and open a change request (pull or merge request) via the project's VCS o ## Input -The `ship` verdict from `04`, the plan path from `02`, and the phase results from `03` that drive the commit and the change-request body. +The `ship` verdict from `04` including its reviewed `HEAD` SHA, the plan path from `02`, and the phase results from `03` that drive the commit and the change-request body. ## Output @@ -12,13 +12,14 @@ The commit SHA and the change-request URL on the project's VCS host. ## Process -1. **Gate.** Confirm `04` produced a verdict on the final diff and that it is `ship`. If no verdict exists, it covers an older diff, or it is `iterate`, stop: do not commit, do not open a request. Run `04` first, looping back to `03` on `iterate`. Code is never shipped unreviewed. +1. **Gate.** Confirm `04` produced a `ship` verdict and that no code landed after the reviewed SHA it carries. Run `git diff --name-only HEAD`: it must list only plan-tracking files (the `chore(plan): reviewed` commit and the like). Any source-code change means the reviewed verdict is stale and the new code is unreviewed: stop, run `04` on the current diff, looping back to `03` on `iterate`. If no verdict exists or it is `iterate`, stop the same way. Code is never shipped unreviewed. 2. **Commit.** Invoke `commit` with a Conventional Commits message derived from the plan's objective. 3. **Open.** Invoke `pull-request` to push the branch and open the change request. Reference the plan path in the body. 4. **Return.** Surface the commit SHA and the change-request URL. ## Test +- `git diff --name-only HEAD` lists only plan-tracking files: no source change shipped unreviewed. - The commit SHA exists in `git log` of the working branch. - The change-request URL is non-empty and points to the project's VCS host. - The change-request body references the plan path. diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index a02ec316..51f5e359 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -20,8 +20,9 @@ Run them in order, `01 → 03`. ## Transversal rules -- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. -- Commits: commit only the status tracking, the moment each transition is made, and never commit code. +- Context: this is a recipe. It runs in the context of whoever invokes it (a user, or an `implementer` agent the SDLC spawned) and never spawns an agent itself. +- 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 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 ab9bf86c..1879ce66 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md @@ -14,10 +14,10 @@ The resolved plan on a feature branch with its frontmatter `status: in-progress` 1. **Resolve.** Resolve the plan from `$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, run `git checkout -b ` and announce it. On a non-default branch, keep it. -3. **Mark.** Set the plan frontmatter `status: in-progress` and commit 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. ## Test - A missing or unreadable plan with no inline content stops with `plan not found at `, and no plan is fabricated. - `git rev-parse --abbrev-ref HEAD` is not the default branch. -- The plan reads `status: in-progress`, committed (`git status --short` shows it clean). +- The plan frontmatter reads `status: in-progress`. 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 ed68105e..73406f9c 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -1,6 +1,6 @@ # 02 - Execute -Loop the plan's phases in order, coding each through the implementer agent until every acceptance criterion holds. +Loop the plan's phases in order, coding each until every acceptance criterion holds. ## Input @@ -12,14 +12,14 @@ Every phase coded, asserted, and its frontmatter marked `status: done`, with the ## 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` and commit it before delegating. -2. **Delegate.** Hand the phase scope and acceptance criteria to the `implementer` agent. -3. **Assert.** Assert the phase against its acceptance criteria. On failure, hand the failures back to the `implementer` and repeat. The gate is the assertion passing, not the implementer's self-report. Then set `status: done` and commit it. +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. This recipe runs in the caller's context and never spawns an agent. +3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Only once it passes, set `status: done` and commit the phase as one unit, its code and its status together, via the `commit` skill. 4. **Blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. 5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch, trivial or substantive, stop and report `replan needed: ` to the caller. Replanning is the planner's job, not this skill's. ## Test -- A phase reaches `status: done` only after assert passes against its acceptance criteria, committed (`git status --short` shows no dangling phase edits). -- The branch holds both the code commits and the tracking commits. +- 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. From 70632be1da64e96053e74d0b05ba04e7d59bfbda Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 06:30:46 +0200 Subject: [PATCH 09/42] refactor(framework): collapse agents to executor + checker, SDLC owns planning Define agents by durable stance, not as skill aliases. Two workers replace the three thin ones; the orchestrator owns the plan. - executor (was planner + implementer): a dispatched doer that turns a scoped task into working, validated code. It never holds the plan-authoring skill, so it cannot rewrite the contract it implements. - checker (was reviewer): judges against the validator and the real need, with an embedded behavioral checklist (duplication, incoherence, over-engineering, dead code) extended by the project's own checklist. - 00-sdlc (B1): the orchestrator authors the plan itself (runs 01-plan in its own context) and spawns executor for build, checker for review. - 05-review de-spawns (was context: fork + agent: reviewer): it is a recipe the checker runs, so it cannot double-spawn under the checker. - Sweep every reference (plan-status iterate stays implemented, 10-todo, ARCHITECTURE, GLOSSARY, agent-authoring, READMEs). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 2 +- docs/ARCHITECTURE.md | 2 +- docs/GLOSSARY.md | 2 +- .../references/agent-authoring.md | 2 +- plugins/aidd-dev/CATALOG.md | 7 ++- plugins/aidd-dev/README.md | 7 ++- plugins/aidd-dev/agents/checker.md | 44 +++++++++++++++++++ plugins/aidd-dev/agents/executor.md | 33 ++++++++++++++ plugins/aidd-dev/agents/implementer.md | 38 ---------------- plugins/aidd-dev/agents/planner.md | 28 ------------ plugins/aidd-dev/agents/reviewer.md | 36 --------------- plugins/aidd-dev/skills/00-sdlc/README.md | 13 +++--- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 17 ++++--- .../skills/00-sdlc/actions/01-spec.md | 4 +- .../skills/00-sdlc/actions/02-plan.md | 8 ++-- .../skills/00-sdlc/actions/03-implement.md | 6 +-- .../skills/00-sdlc/actions/04-review.md | 8 ++-- .../skills/01-plan/actions/04-plan.md | 2 +- .../skills/01-plan/references/plan-status.md | 4 +- .../aidd-dev/skills/02-implement/README.md | 18 ++++---- plugins/aidd-dev/skills/02-implement/SKILL.md | 2 +- .../skills/02-implement/actions/02-execute.md | 2 +- plugins/aidd-dev/skills/05-review/README.md | 14 +++--- plugins/aidd-dev/skills/05-review/SKILL.md | 6 +-- .../09-for-sure/assets/plan-template.md | 2 +- plugins/aidd-dev/skills/10-todo/README.md | 2 +- plugins/aidd-dev/skills/10-todo/SKILL.md | 2 +- .../skills/10-todo/actions/01-todo.md | 2 +- 28 files changed, 141 insertions(+), 172 deletions(-) create mode 100644 plugins/aidd-dev/agents/checker.md create mode 100644 plugins/aidd-dev/agents/executor.md delete mode 100644 plugins/aidd-dev/agents/implementer.md delete mode 100644 plugins/aidd-dev/agents/planner.md delete mode 100644 plugins/aidd-dev/agents/reviewer.md diff --git a/README.md b/README.md index b5bc4832..180e161f 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ ### Vibe Coding for professional developers — focused on 100% quality on AI-generated code.

- 6 plugins · 38 skills · 3 agents · MIT + 6 plugins · 38 skills · 2 agents · MIT

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 4ffb473d..709cda3c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -134,7 +134,7 @@ Choose by context, not complexity: keep the work visible to the caller → skill Composition rules: - **Spawning is an orchestration decision, never a skill's.** A recipe skill never spawns an agent; it runs in the caller's context. Only a high-level orchestrator skill (for example the SDLC) spawns agents, and it decides per step whether to isolate the work in an agent or run the recipe inline. -- An orchestrator spawns each step as a leaf agent that runs a recipe: the SDLC spawns `planner` (runs `01-plan`), `implementer` (runs `02-implement`), and `reviewer` (runs `05-review`). The agent is the isolation; the recipe inside it never spawns again. +- An orchestrator spawns each step as a leaf agent that runs a recipe, or runs the recipe itself when the step needs no isolation. The SDLC owns planning (runs `01-plan` in its own context) and spawns two workers: `executor` (runs `02-implement`) and `checker` (runs `05-review`). The agent is the isolation; the recipe inside it never spawns again. - An agent invokes only the recipe skills it declares under `# Skills you may invoke`, never an orchestrator skill, and never reads a skill's files. It names a same-plugin skill by its `plugin:folder` address (deterministic); it names a cross-plugin skill by capability, per cross-plugin orthogonality. - An agent never delegates flow work to another agent and never invokes an orchestrator skill. It may spawn a read-only recon helper (for example `Explore`) that mutates nothing and spawns nothing. So the write path stays two layers deep and delegation can never cycle. diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 195804a7..19a57100 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -28,7 +28,7 @@ A single atomic step inside a skill, stored at `plugins//skills//agents/.md`. Agents are scoped (for example `planner`, `implementer`, `reviewer`) and called from skills when a step needs a dedicated role rather than the main thread. Currently agents ship only in `aidd-dev`. +A specialized AI persona under `plugins//agents/.md`. Agents are scoped (for example `executor`, `checker`) and spawned by an orchestrator when a step needs isolation in a dedicated role rather than the main thread. Currently agents ship only in `aidd-dev`. ## Rule diff --git a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md index 2869749b..28fae750 100644 --- a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md +++ b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md @@ -12,7 +12,7 @@ The contract every generated agent must satisfy. An agent is a focused role with ## Naming -- Short and catchy, a single word where possible: `reviewer`, `planner`, `implementer`. +- Short and catchy, a single word where possible: `executor`, `checker`, `auditor`. - Fits the role at a glance. Propose three options for the user to pick. ## Body shape diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 66b6a036..9ba3b01e 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -33,9 +33,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | File | Description | |------|---| -| [implementer.md](agents/implementer.md) | `Codes a handed-off milestone or fix list, tests it, and reports back. Use when an approved scope must become working, validated code. Never plans, never judges its own work.` | -| [planner.md](agents/planner.md) | `Turns an approved spec into an executable plan with milestones, acceptance criteria, and recorded decisions. Use when a spec must become a plan, or a finished pass needs replanning. Never writes code, never judges it.` | -| [reviewer.md](agents/reviewer.md) | `Judges a finished artifact against an explicit validator and reports findings with a score. Use when code, a spec, a plan, or a doc needs independent verification. Never edits the artifact, never decides what happens next.` | +| [checker.md](agents/checker.md) | `Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix.` | +| [executor.md](agents/executor.md) | `Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work.` | ### `skills` @@ -164,5 +163,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-todo.md](skills/10-todo/actions/01-todo.md) | - | | `-` | [README.md](skills/10-todo/README.md) | - | -| `-` | [SKILL.md](skills/10-todo/SKILL.md) | `Split the user prompt into independent todos, run one implementer agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations.` | +| `-` | [SKILL.md](skills/10-todo/SKILL.md) | `Split the user prompt into independent todos, run one executor agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations.` | diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index 976e7ac9..a6c7c16f 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -16,7 +16,7 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert |---|---|---| | [2.0] | [sdlc](skills/00-sdlc/README.md) | Dev SDLC orchestrator (code-shipping pipeline): spec, plan, implement, test, review, commit, PR. | | [2.1] | [plan](skills/01-plan/README.md) | Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. | -| [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness. | +| [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase, recipe-style, iterating until 100% completeness. | | [2.3] | [assert](skills/03-assert/README.md) | Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. | | [2.4] | [audit](skills/04-audit/README.md) | Perform deep codebase analysis to identify technical debt, dead code, and improvement opportunities. | | [2.5] | [review](skills/05-review/README.md) | Review code quality against project rules and validate feature behavior against plan specifications. | @@ -29,6 +29,5 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert | Agent | Description | |---|---| -| planner | Orchestrator. Turns a validated spec into milestones, drives the implementer/reviewer loop, escalates blocked decisions. Never writes code, never judges code. | -| implementer | Milestone executor. Codes, tests, repairs within the milestone scope. Commits atomically per ticked checkbox. Returns completion score. | -| reviewer | Independent critic in fresh context. Verifies an artifact against an explicit validator (acceptance criteria or checklist). Returns findings, completion and quality scores. Never edits the artifact. | +| executor | Dispatched doer in its own context. Turns a scoped task into working, validated code that fits the project, deciding how, never what. Never authors a plan, never judges its own work. | +| checker | Independent critic in fresh context. Judges finished work against its validator and the real need, leaving nothing unchecked. Returns findings, scores, and a verdict. Never edits the work, never implements the fix. | diff --git a/plugins/aidd-dev/agents/checker.md b/plugins/aidd-dev/agents/checker.md new file mode 100644 index 00000000..6ed4cf32 --- /dev/null +++ b/plugins/aidd-dev/agents/checker.md @@ -0,0 +1,44 @@ +--- +name: checker +description: Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix. +model: opus +--- + +# Role + +You are the checker. Your job is to judge finished work against its validator and the real need, in a fresh context with no memory of how it was built, and to leave nothing unchecked. + +# Behavior + +- Build your validator stack first: the acceptance criteria and the need the work is meant to serve. Extend the checklist below with the project's own review checklist when it provides one. +- Judge each criterion: inspect, run validation commands when they exist, and mark it fulfilled, partial, or unfulfilled with evidence. +- Run the checklist on every code or diff, leaving no item unchecked. +- Then check the layer the reviews miss: does the delivered logic serve the actual need, end to end, even when code review and functional review both pass? Name any gap between intent and result. +- Demand command output or file evidence, never bare claims. Lean strict: a false alarm costs less than a missed defect. +- Return your verdict, findings, and score to whoever invoked you. Hold yourself accountable for whatever you pass. + +# Checklist + +This is the behavioral baseline. Apply it to every code or diff, and extend it with the project's own checklist when one exists. + +- [ ] No information duplication. DRY across code and docs; link to the canonical home instead of copying. +- [ ] No incoherence or contradiction. Naming, behavior, and docs-versus-code stay consistent. +- [ ] No over-engineering. The simplest solution that meets the need; no speculative generality, no unused abstraction. +- [ ] No dead code or debug leftovers. No commented-out blocks, stray logs, or silent TODOs. + +# Scoring + +- If the validator defines weights and thresholds, apply them exactly, and let any hard violation force the score to zero. +- Otherwise score the proportion of fulfilled criteria, adjusted for the severity of the findings, with your reasoning. +- The pass threshold is the caller's gate, not yours. You report the score; you do not declare pass or fail. + +# Guardrails + +- Never edit the work or its validator. Never implement the fix. Never delegate to another agent. +- Never pass on vibes: tie every verdict to a stated criterion, a checklist item, or a named need-gap. +- Flag an ambiguous criterion instead of guessing. Do not go easy because the work looks impressive. + +# Skills you may invoke + +- `aidd-dev:05-review` +- `aidd-dev:04-audit` diff --git a/plugins/aidd-dev/agents/executor.md b/plugins/aidd-dev/agents/executor.md new file mode 100644 index 00000000..d9f3ad86 --- /dev/null +++ b/plugins/aidd-dev/agents/executor.md @@ -0,0 +1,33 @@ +--- +name: executor +description: Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work. +model: sonnet +--- + +# Role + +You are the executor. Your job is to turn a dispatched task into working, validated code that fits the project. You decide how, never what. + +# Behavior + +- Honour the project's own conventions where it defines them, and match the code around you. Where it stays silent, follow the prevailing idiom. +- Internalize the acceptance criteria before writing anything. If the scope is ambiguous, surface it instead of guessing. +- Work in a tight loop: build a substep, validate it, repair on red, and only then move on. Validation passing is the gate, never your own say-so. +- Commit per coherent unit, code and its status together, one unit one commit. +- When you finish or stall, return to whoever invoked you with what is done, what is left, and why. + +# Guardrails + +- Never author or edit a plan, spec, or acceptance criterion. That authority is the caller's. On any drift, stop and hand it back to be replanned. +- Stay strictly in the scope you are handed. Declare anything you bypass: no silent TODO, skipped test, or placeholder mock. +- Never judge your own work, and never start a review. The caller handles that. +- Never delegate to another agent. +- When the work is physically impossible for the AI, stop and say so plainly: a real payment, a human login, an unreadable secret, anything behind hardware or 2FA. Do not fake progress. + +# Skills you may invoke + +- `aidd-dev:02-implement` +- `aidd-dev:03-assert` +- `aidd-dev:06-test` +- `aidd-dev:08-debug` +- `commit` (cross-plugin, by capability) diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md deleted file mode 100644 index 608293e5..00000000 --- a/plugins/aidd-dev/agents/implementer.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: implementer -description: Codes a handed-off milestone or fix list, tests it, and reports back. Use when an approved scope must become working, validated code. Never plans, never judges its own work. -model: sonnet ---- - -# Role - -You are the implementer. Your job is to turn a handed-off milestone or fix list into working, validated code. - -# Behavior - -- Stay strictly inside the scope you are handed. You decide how to build it, never what. -- When handed a plan, run the `aidd-dev:02-implement` recipe end to end: branch, loop the phases, assert each, validate. When handed a fix list, code the fixes directly against their findings. -- Internalize the acceptance criteria first. If the scope is ambiguous, say so instead of guessing. -- Build substep by substep. Validate after each one and repair before moving on. -- Commit per coherent unit, atomically, via the `commit` skill: one commit per phase under the recipe, one per fix under a fix list, code and its status together. The audit trail is non-negotiable, but do not pad it with separate status-only commits. -- Be honest about how much you delivered. Underreporting is fine. Overreporting hides failures. -- When you finish or get stuck, return to whoever invoked you with what you did, what is left, and why. - -# Guardrails - -- Never delegate to another agent. -- No TODOs, no skipped tests, no placeholder mocks, no silent workarounds. Declare anything you bypass. -- Never change the acceptance criteria or the spec. Surface the change and let the caller replan. -- Never judge your own work or start a review. The caller handles that. -- When the work is physically impossible for the AI, stop and say so plainly. That covers a real payment, a human login, a secret you cannot read, or anything behind hardware or 2FA. Do not fake progress. - -# Skills you may invoke - -- `aidd-dev:02-implement` (the recipe you run for a plan; it never spawns) -- `aidd-dev:01-plan` (read-only, for context) -- `aidd-dev:03-assert` -- `aidd-dev:06-test` -- `aidd-dev:08-debug` -- `aidd-dev:04-audit` -- `aidd-dev:07-refactor` -- `commit` (cross-plugin, by capability) diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md deleted file mode 100644 index f48152c8..00000000 --- a/plugins/aidd-dev/agents/planner.md +++ /dev/null @@ -1,28 +0,0 @@ ---- -name: planner -description: Turns an approved spec into an executable plan with milestones, acceptance criteria, and recorded decisions. Use when a spec must become a plan, or a finished pass needs replanning. Never writes code, never judges it. -model: opus ---- - -# Role - -You are the planner. Your job is to turn an immutable spec into an executable plan: milestones, acceptance criteria, validation commands, and the decisions you made. - -# Behavior - -- Start only when the spec is complete: a target, hard constraints, non-goals, and a done-when section. If any is missing, escalate before producing anything. -- Treat the spec as immutable. If it must change, escalate instead of editing it. -- Break the work into milestones, each sized for a single implementer pass, each with acceptance criteria and validation commands a reviewer can run. Let the work decide how many. -- When a previous implementer or reviewer pass comes back, update the plan or produce a focused replan. Do not execute the fix yourself. -- Record every structural decision, and surface the ones you cannot make alone. -- When you finish, return to whoever invoked you with the plan, where it lives, and your decisions. - -# Guardrails - -- Never edit the spec. Never touch source code. Never delegate to another agent. -- Stay out of the implementer's choices (libraries, patterns, file layout) and the reviewer's scoring. -- No passive blocking. When in doubt, make a conservative planning assumption and record it, unless the spec forbids it. - -# Skills you may invoke - -- `aidd-dev:01-plan` diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md deleted file mode 100644 index 54528465..00000000 --- a/plugins/aidd-dev/agents/reviewer.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -name: reviewer -description: Judges a finished artifact against an explicit validator and reports findings with a score. Use when code, a spec, a plan, or a doc needs independent verification. Never edits the artifact, never decides what happens next. -model: opus ---- - -# Role - -You are the reviewer. Your job is to judge a finished artifact against its validator and report findings with a score, in a fresh context with no memory of how it was built. - -# Behavior - -- Start fresh. Read the artifact, not the story of how it was made. -- Judge each criterion against the validator: inspect, run validation commands when they exist, and mark it fulfilled, partial, or unfulfilled with evidence. -- Surface incoherences, where the artifact contradicts its context, and omissions, where a criterion has no matching content. -- Demand command output or file evidence, never bare claims. -- Write findings precise enough to act on without guessing. When uncertain, mark partial and explain. Lean strict: a false alarm costs less than a missed defect. -- When you finish, return your verdict to whoever invoked you. - -# Scoring - -- If the validator defines weights and thresholds, apply them exactly: weight each fulfilled, partial, or unfulfilled criterion, normalize to a score, and let any hard-threshold or required-criterion violation force the score to zero. Do not substitute judgment. -- Otherwise, score the proportion of fulfilled criteria, adjusted for the severity of the findings, with your reasoning. -- The pass threshold is the caller's gate, not yours. You report the score; you do not declare pass or fail. - -# Guardrails - -- Never edit the artifact or the validator. Never delegate to another agent. -- Flag an ambiguous criterion instead of guessing. -- Do not go easy because the work looks impressive. Score what is verifiable. -- Do not read production logs or status artifacts that would bias your judgment. - -# Skills you may invoke - -- `aidd-dev:05-review` -- `aidd-dev:04-audit` diff --git a/plugins/aidd-dev/skills/00-sdlc/README.md b/plugins/aidd-dev/skills/00-sdlc/README.md index f181f2f1..b2fea447 100644 --- a/plugins/aidd-dev/skills/00-sdlc/README.md +++ b/plugins/aidd-dev/skills/00-sdlc/README.md @@ -37,9 +37,10 @@ The skill walks 5 actions: 1. `spec` - consolidate sources, draft or refine the contract (skippable if the source ticket already carries objective + acceptance criteria). -2. `plan` - produce the mandatory plan file via the `planner` agent. -3. `implement` - loop milestones via the `implementer` agent until complete. -4. `review` - verdict `ship` or `iterate` via the `reviewer` agent; on +2. `plan` - produce the mandatory plan file by running `aidd-dev:01-plan` in + the orchestrator's own context (it owns the plan). +3. `implement` - loop milestones via the `executor` agent until complete. +4. `review` - verdict `ship` or `iterate` via the `checker` agent; on `iterate`, loop back to step 3 with findings. 5. `ship` - commit and open the pull request. @@ -47,15 +48,15 @@ The skill walks 5 actions: - A spec file (unless skipped). - A plan file in `aidd_docs/tasks/`. -- Atomic commits on the active branch, one per ticked checkbox. +- Atomic commits on the active branch, one per phase. - A pull request with title, body, base branch, and draft state. -- Findings + completion + quality scores from the reviewer. +- Findings + completion + quality scores from the checker. ## Prerequisites - HEAD is on a non-default branch when the run is meant to ship. `05-ship` aborts with `contract_violation: on_default_branch` otherwise. -- The `planner`, `implementer`, and `reviewer` agents are available. +- The `executor` and `checker` agents are available. - A VCS-providing capability is loaded at runtime for the ship step (commit + pull-request creation). diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 786e1079..afdfd780 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -12,13 +12,12 @@ Complete end-to-end software delivery. Defaults to autonomous; switches to inter **You are the conductor, not a player.** -You orchestrate; you never write code yourself. Each step you isolate as a leaf agent that runs a recipe in its own context and returns only a result. The agent is the isolation; the recipe inside it never spawns again, so the write path stays exactly two layers deep (a leaf may still spawn a read-only recon helper). +You orchestrate; you never write code or judge it yourself. You own the plan: you run `aidd-dev:01-plan` in your own context, because the plan is the contract no worker may rewrite. Every other step you isolate as a leaf agent that runs a recipe and returns only a result. The agent is the isolation; the recipe inside it never spawns again, so the write path stays two layers deep (a leaf may still spawn a read-only recon helper). -You spawn agents by role: +You spawn two workers: -- `planner` - runs `aidd-dev:01-plan` when scope must be planned -- `implementer` - runs `aidd-dev:02-implement` when code must be written -- `reviewer` - runs `aidd-dev:05-review` when completed work must be verified +- `executor` - runs `aidd-dev:02-implement` when code must be written. It never holds the plan-authoring skill, so it cannot rewrite the contract. +- `checker` - runs `aidd-dev:05-review` when completed work must be verified. ## Mandatory steps (enforce - never skip) @@ -47,16 +46,16 @@ Detect the mode from `$ARGUMENTS` once, at skill entry, before dispatching the f | # | Action | Role | Delegate | | --- | ----------- | ------------------------------------------------------------- | ------------------------------------ | | 01 | `spec` | Consolidate sources, draft or refine the contract (skippable) | `spec` | -| 02 | `plan` | Produce the mandatory plan file | `planner` runs `aidd-dev:01-plan` | -| 03 | `implement` | Build the plan's code, every phase, until complete | `implementer` runs `aidd-dev:02-implement` | -| 04 | `review` | Verdict `ship` or `iterate` | `reviewer` runs `aidd-dev:05-review` | +| 02 | `plan` | Produce the mandatory plan file | self: runs `aidd-dev:01-plan` | +| 03 | `implement` | Build the plan's code, every phase, until complete | `executor` runs `aidd-dev:02-implement` | +| 04 | `review` | Verdict `ship` or `iterate` | `checker` runs `aidd-dev:05-review` | | 05 | `ship` | Commit and open a change request via the project's VCS | `commit`, `pull-request` | Files: `@actions/01-spec.md` ... `@actions/05-ship.md`. ## Default flow -`01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop back to `03` with the findings as the implementer's fix list. After each action, run its `## Test` before moving to the next. +`01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop back to `03` with the findings as the executor's fix list. After each action, run its `## Test` before moving to the next. `01-spec` self-skips (returns `spec_status = skipped`) when the source ticket already carries an explicit objective + acceptance criteria. It is the ONLY skippable step. `02-plan`, `03-implement`, `04-review`, `05-ship` are mandatory and never skipped (see **Mandatory steps**). diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md index 089fe9b0..6d649c26 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md @@ -6,7 +6,7 @@ Consolidate every available source into the normalized contract consumed downstr ## Input -The raw `$ARGUMENTS` (free-form text or a ticket URL), any available sources (ticket body, existing PRD, in-session conversation, prior reviewer findings), and the repo root. +The raw `$ARGUMENTS` (free-form text or a ticket URL), any available sources (ticket body, existing PRD, in-session conversation, prior checker findings), and the repo root. ## Output @@ -14,7 +14,7 @@ The spec path on disk with its status (`drafted`, `refined`, or `skipped`), the ## Process -1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot reviewer findings, capture conversation turns. Concatenate them into one brief. +1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot checker findings, capture conversation turns. Concatenate them into one brief. 2. **Skip.** Apply the skip condition above. If it holds, return the extracted objective and criteria. 3. **Delegate.** Hand the consolidated brief and the repo root to `spec`. Let it own contract generation and refinement. 4. **Return.** Surface the spec path, status, objective, and acceptance criteria. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md index 73402db3..b67b2b45 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md @@ -8,13 +8,13 @@ The spec path from `01` (null when skipped), the objective and acceptance criter ## Output -The plan path and its phase paths, plus the decisions the planner made and any it could not make alone. +The plan path and its phase paths, plus the decisions you made and any you could not make alone. ## Process -1. **Spawn.** Spawn the `planner` agent with the inputs above. Brief it to run `aidd-dev:01-plan` end to end, and never to inline a raw ticket or spec as the plan body. -2. **Read.** Capture what the planner returns. -3. **Return.** Surface the plan path, the phase paths, and the decisions. +1. **Author.** Run `aidd-dev:01-plan` end to end in your own context. You own the plan: it is the contract the executor may not rewrite, so you write it, never a worker. Never inline a raw ticket or spec as the plan body. +2. **Capture.** Read the plan path, the phase paths, and the decisions the plan records. +3. **Return.** Surface them for the next step. ## Test diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index 414ca591..c4968afa 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -1,6 +1,6 @@ # 03 - Implement -Build the plan's code by spawning the `implementer` agent to run the `aidd-dev:02-implement` recipe, which loops the phases, drives status, and validates. Mandatory. +Build the plan's code by spawning the `executor` agent to run the `aidd-dev:02-implement` recipe, which loops the phases, drives status, and validates. Mandatory. ## Input @@ -12,8 +12,8 @@ The plan reaches `status: implemented`, every phase `done`, validation green. Or ## Process -1. **Implement.** Spawn the `implementer` agent and brief it to run the `aidd-dev:02-implement` recipe on `plan_path`. The agent branches, codes every phase, commits the code and the status transitions in its own context, and validates. The conductor never codes; the agent is the isolation, and the recipe inside it never spawns again. -2. **Iterate.** When the step runs after an `iterate` verdict, spawn the `implementer` again and hand it the findings as a fix list. It codes the fixes against the current diff, then asserts and validates them before returning, exactly as the recipe gates a phase: a fix is finished only when it passes. Do not edit the plan or its phases: the loop fixes what was implemented, not the plan. +1. **Implement.** Spawn the `executor` agent and brief it to run the `aidd-dev:02-implement` recipe on `plan_path`. The agent branches, codes every phase, commits the code and the status transitions in its own context, and validates. The conductor never codes; the agent is the isolation, and the recipe inside it never spawns again. +2. **Iterate.** When the step runs after an `iterate` verdict, spawn the `executor` again and hand it the findings as a fix list. It codes the fixes against the current diff, then asserts and validates them before returning, exactly as the recipe gates a phase: a fix is finished only when it passes. Do not edit the plan or its phases: the loop fixes what was implemented, not the plan. 3. **Resolve.** Read the plan's final `status`. - `implemented`: the step is done. - `blocked`: a human-only condition stopped the run. Do not continue. Escalate to a human. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md index ca91d93f..26c859f7 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md @@ -4,16 +4,16 @@ Judge the completed work against an explicit validator and emit a ship-or-iterat ## Input -The working diff or paths produced by `03`, the validator (the plan path and acceptance criteria), and any related context the reviewer needs. +The working diff or paths produced by `03`, the validator (the plan path and acceptance criteria), and any related context the checker needs. ## Output -A `ship` or `iterate` verdict with the reviewed items, the findings, the completion and quality scores, and the reviewed `HEAD` SHA (the commit the reviewer actually saw). The plan reaches `status: reviewed` on ship, and stays `implemented` on iterate. +A `ship` or `iterate` verdict with the reviewed items, the findings, the completion and quality scores, and the reviewed `HEAD` SHA (the commit the checker actually saw). The plan reaches `status: reviewed` on ship, and stays `implemented` on iterate. ## Process -1. **Capture.** Record `git rev-parse HEAD` as the reviewed SHA. This is the exact code the reviewer judges, and the anchor `05-ship` checks against. -2. **Spawn.** Spawn the `reviewer` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code and functional, on that diff, and return its verdict. +1. **Capture.** Record `git rev-parse HEAD` as the reviewed SHA. This is the exact code the checker judges, and the anchor `05-ship` checks against. +2. **Spawn.** Spawn the `checker` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code and functional, on that diff, and return its verdict. 3. **Map.** When every check passes, the verdict is `ship`. On any blocking finding, the verdict is `iterate`. 4. **Mark.** On `ship`, set the plan frontmatter `status: reviewed` and commit it. Carry the reviewed SHA in the verdict. On `iterate`, leave the plan `implemented`: the loop fixes the diff, not the plan. 5. **Iterate.** On `iterate`, return the findings as the fix list for `03`. The next `04` re-captures the SHA on the fixed diff; ship is reached only when a review of the current diff passes. diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md index 214791ec..160bf208 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md @@ -12,7 +12,7 @@ A feature folder `aidd_docs/tasks//_/` holdin ## Process -1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one implementer pass. Let the work decide how many. +1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many. 2. **Write.** Resolve the feature folder: reuse the one the source already lives in, otherwise create it. Scaffold from the templates and fill the placeholders. Fill only the sections the template defines, add nothing it does not, and omit any section that stays empty (for example resources when nothing was consulted). Slice the projection into each phase, put the resources consulted (docs or in-repo files) in the resources table, and embed any wireframe in its phase's Wireframe section. Display the paths. 3. **Review.** Show the complete plan and its phases with a confidence score (0 to 10, ✓ reasons and ✗ risks). Take feedback, revise the files, and re-show until approved. The score is never written to the plan. diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-status.md b/plugins/aidd-dev/skills/01-plan/references/plan-status.md index 7d537560..7fa23e57 100644 --- a/plugins/aidd-dev/skills/01-plan/references/plan-status.md +++ b/plugins/aidd-dev/skills/01-plan/references/plan-status.md @@ -18,6 +18,6 @@ The plan's `status` frontmatter field tracks its lifecycle for kanban views. The ## Rules - Linear: `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state. -- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed` → status returns to `in-progress`. +- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan. - `implemented` ≠ reviewed. Only the review layer sets `reviewed`. -- The reviewer and implementer agents never write `status`; only plan creation (`01-plan`) and the orchestration layers do. +- The `checker` and `executor` agents never write `status`; only plan creation (`01-plan`) and the orchestration layers do. diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md index e3f008da..e261a0d0 100644 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ b/plugins/aidd-dev/skills/02-implement/README.md @@ -2,7 +2,7 @@ # 02 - implement -Executes an existing implementation plan phase by phase, spawning an `implementer` agent per phase and iterating until every acceptance criterion is satisfied. Tracks status in the plan and phase frontmatter as it goes. +Executes an existing implementation plan phase by phase, as a recipe that runs in the caller's context and never spawns an agent, iterating until every acceptance criterion is satisfied. Tracks status in the plan and phase frontmatter as it goes. ## When to use @@ -24,23 +24,23 @@ Use skill aidd-dev:02-implement Pass the plan path or content as `$ARGUMENTS`. The skill runs three actions in order: 1. **prepare**: fails fast when the plan is missing (never fabricates one); puts `HEAD` on a feature branch when it is on the default branch, otherwise keeps the current branch; sets the plan `status: in-progress`. -2. **execute**: loops the plan's phases: per phase it sets `status: in-progress`, spawns the `implementer` agent, re-spawns until the phase asserts clean, then sets `status: done`; stops at `status: blocked` when the implementer hits a human-only condition. +2. **execute**: loops the plan's phases: per phase it sets `status: in-progress` as a runtime marker, codes the phase, asserts it clean, then commits the phase and sets `status: done`; stops at `status: blocked` on a human-only condition. 3. **finalize**: runs validation, then marks the plan `status: implemented` once every phase is done. -**Code** commits are the `implementer` agent's job (one per ticked acceptance criterion); the skill commits only its own **tracking**: each status transition, the moment it makes it. That split keeps the same audit trail whether the agent is reached through this skill, the SDLC, or a direct spawn, and stops the implementer's clean-tree hygiene from reverting an uncommitted status edit. +**Commits**: the recipe runs in one context, so it commits the code and its status together, one commit per phase, plus a final `implemented` commit. The `in-progress` marks are runtime-only. One context owning both code and status removes the cross-context revert the old skill-spawns-agent split had to guard against. ## Outputs -- Code for the feature, one phase at a time, committed by the `implementer` agent on the active feature branch. -- Plan and phase frontmatter status driven `pending → in-progress → done / implemented`, or `blocked`, each transition committed by the skill as it happens. -- A `replan needed` report when the plan no longer matches reality; this skill never rewrites the plan. +- Code for the feature, one phase at a time, committed on the active feature branch, one commit per phase. +- Plan and phase frontmatter status driven `pending → in-progress → done / implemented`, or `blocked`. +- A `replan needed` report when the plan no longer matches reality; this recipe never rewrites the plan. ## Prerequisites - A plan file with phases and acceptance criteria, from `01-plan`. -- The `implementer` agent available in context. -- Project rules already loaded for the implementer to respect. +- A runner for the recipe: a user, or the `executor` agent the SDLC spawns. +- Project conventions honoured by whoever runs the recipe. ## Technical details -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the prepare/execute/finalize split: the branch guard, the phase loop, the re-spawn rule, the status lifecycle, and the boundary constraints (no formatting, no dev mode). +See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the prepare/execute/finalize split: the branch guard, the phase loop, the assert gate, the status lifecycle, and the boundary constraints (no formatting, no dev mode). diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index 51f5e359..0767c51b 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -20,7 +20,7 @@ Run them in order, `01 → 03`. ## Transversal rules -- Context: this is a recipe. It runs in the context of whoever invokes it (a user, or an `implementer` agent the SDLC spawned) and never spawns an agent itself. +- Context: this is a recipe. It runs in the context of whoever invokes it (a user, or an `executor` agent the SDLC spawned) and never spawns an agent itself. - 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. 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 73406f9c..52fb9a15 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -16,7 +16,7 @@ Every phase coded, asserted, and its frontmatter marked `status: done`, with the 2. **Code.** Build the phase scope against its acceptance criteria. This recipe runs in the caller's context and never spawns an agent. 3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Only once it passes, set `status: done` and commit the phase as one unit, its code and its status together, via the `commit` skill. 4. **Blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. -5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch, trivial or substantive, stop and report `replan needed: ` to the caller. Replanning is the planner's job, not this skill's. +5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch, trivial or substantive, stop and report `replan needed: ` to the caller. Replanning is the orchestrator's job, not this recipe's. ## Test diff --git a/plugins/aidd-dev/skills/05-review/README.md b/plugins/aidd-dev/skills/05-review/README.md index 72003c6f..bf95a38c 100644 --- a/plugins/aidd-dev/skills/05-review/README.md +++ b/plugins/aidd-dev/skills/05-review/README.md @@ -3,9 +3,9 @@ # 05 - review Reviews completed work along two axes: code quality against project rules, -and feature behavior against the plan's acceptance criteria. Runs in a -fresh context via the `reviewer` agent and returns findings plus completion -and quality scores. Never edits the artifact. +and feature behavior against the plan's acceptance criteria. A recipe that +runs in the caller's context (the SDLC isolates it by spawning a `checker`) +and returns findings plus completion and quality scores. Never edits the artifact. ## When to use @@ -48,8 +48,8 @@ The skill exposes 2 actions: - `review-functional` - a verdict (`PASS` / `PARTIAL` / `FAIL`) and a per-criterion scoring matrix; missing or broken behaviors hand off to [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). -- The `reviewer` agent still returns `ship` / `iterate` to the SDLC - orchestrator. +- The `checker` agent running this recipe returns `ship` / `iterate` to the + SDLC orchestrator. ## Prerequisites @@ -60,5 +60,5 @@ The skill exposes 2 actions: ## Technical details See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the two -review contracts. The skill runs the `reviewer` agent in fresh context to -avoid bias from the implementation conversation. +review contracts. The SDLC runs this recipe inside a fresh-context `checker` +agent to avoid bias from the implementation conversation. diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index b5d2fdbc..1b4c68e5 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -3,17 +3,13 @@ name: 05-review description: Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). argument-hint: review-code | review-functional model: opus -context: fork -agent: reviewer --- # Skill: review Read-only review of a diff (a PR or working changes): code quality against project rules, and feature behavior against the plan's acceptance criteria. It surfaces findings and a verdict; it never edits code. The fix hands off to the act-skills (`07-refactor` for code, `02-implement` / `08-debug` for behavior gaps). Diff-scoped - for a whole-codebase read-only diagnosis use `aidd-dev:04-audit` instead. -## Agent delegation - -Spawn the `reviewer` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `reviewer` agent explicitly with this skill's content as the prompt. +This is a recipe: it runs in the context of whoever invokes it and never spawns an agent. The SDLC isolates it by spawning a `checker` to run it; a direct caller runs it inline. ## Available actions diff --git a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md index c8e1aad0..83c22497 100644 --- a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md +++ b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md @@ -52,7 +52,7 @@ status: pending ## Applicable rules - + | Tool | Name | Path | Why it applies | | ------ | ------ | ------------------------------------- | -------------- | diff --git a/plugins/aidd-dev/skills/10-todo/README.md b/plugins/aidd-dev/skills/10-todo/README.md index 727b75be..734bde80 100644 --- a/plugins/aidd-dev/skills/10-todo/README.md +++ b/plugins/aidd-dev/skills/10-todo/README.md @@ -2,7 +2,7 @@ # 10 - todo -Split one prompt into independent todos, run one implementer agent per +Split one prompt into independent todos, run one executor agent per todo in parallel (each refines its todo before coding), and report a minimal table: category, what was launched, output. diff --git a/plugins/aidd-dev/skills/10-todo/SKILL.md b/plugins/aidd-dev/skills/10-todo/SKILL.md index 85a589b7..51137ace 100644 --- a/plugins/aidd-dev/skills/10-todo/SKILL.md +++ b/plugins/aidd-dev/skills/10-todo/SKILL.md @@ -1,6 +1,6 @@ --- name: 10-todo -description: Split the user prompt into independent todos, run one implementer agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations. +description: Split the user prompt into independent todos, run one executor agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations. --- # Todo diff --git a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md index d918c682..504a1140 100644 --- a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md +++ b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md @@ -17,7 +17,7 @@ User's requirement. 1. **Read.** Take `prompt` from `$ARGUMENTS`; if empty, ask the user. 2. **Categorize.** Split the prompt into distinct, independent todos (category + task). Inline, no agent, using template. -3. **Launch.** Spawn one `implementer` agent per todo, all in parallel (one message, multiple Task calls). Each agent prompt mandates, in order: +3. **Launch.** Spawn one `executor` agent per todo, all in parallel (one message, multiple Task calls). Each agent prompt mandates, in order: ```markdown 1. Refine the todo first - discover at runtime a skill whose description covers refining or clarifying a request (never a hardcoded plugin name) and run it on the todo. 2. Implement the refined todo. From ef4dc87b10c31c9c186296788890d0fd30293fe5 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 06:53:02 +0200 Subject: [PATCH 10/42] fix(framework): register executor + checker agents in plugin manifest The agents array still pointed at the deleted planner/implementer/reviewer files, so no aidd-dev agent registered and the SDLC silently fell back to general-purpose subagents. Point it at the new executor and checker. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/.claude-plugin/plugin.json | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/plugins/aidd-dev/.claude-plugin/plugin.json b/plugins/aidd-dev/.claude-plugin/plugin.json index a851b8ae..3518598f 100644 --- a/plugins/aidd-dev/.claude-plugin/plugin.json +++ b/plugins/aidd-dev/.claude-plugin/plugin.json @@ -21,9 +21,8 @@ "./skills/10-todo" ], "agents": [ - "./agents/implementer.md", - "./agents/planner.md", - "./agents/reviewer.md" + "./agents/executor.md", + "./agents/checker.md" ], "keywords": [ "sdlc", From a6375f1c501c6e83489d6b51eb365347c8f9c713 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 09:42:59 +0200 Subject: [PATCH 11/42] refactor(framework): strip SDLC router to the norm, delegate by capability The SKILL.md had grown to seven business-logic sections with heavy duplication and hardcoded cross-plugin skill names. Bring it back to the router contract: description, action table, short transversal rules. - SKILL.md down to ~30 lines: six one-line transversal rules, no Modes / Mandatory / Tracking / Gates / References sections, no empty Assets block. - Cross-plugin steps delegate by capability discovered at runtime, in both the action table and the spec/ship actions, not by hardcoded skill name. - Intra-plugin recipes stay named by address for deterministic resolution. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 2 +- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 103 +++--------------- .../skills/00-sdlc/actions/01-spec.md | 2 +- .../skills/00-sdlc/actions/05-ship.md | 4 +- 4 files changed, 21 insertions(+), 90 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 9ba3b01e..65e31ef4 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -48,7 +48,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [04-review.md](skills/00-sdlc/actions/04-review.md) | - | | `actions` | [05-ship.md](skills/00-sdlc/actions/05-ship.md) | - | | `-` | [README.md](skills/00-sdlc/README.md) | - | -| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated.` | +| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Pure orchestrator for the full AIDD development flow, from a free-form request to shipped code. Use when a request must go end to end: spec, plan, implement, review, ship. Runs auto by default (no human interaction) or interactive (pauses at each step). Delegates every step and holds no logic of its own. Do NOT use to run one step in isolation; call that step's skill directly.` | #### `skills/01-plan` diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index afdfd780..203ad841 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -1,99 +1,30 @@ --- name: 00-sdlc -description: Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated. +description: Pure orchestrator for the full AIDD development flow, from a free-form request to shipped code. Use when a request must go end to end: spec, plan, implement, review, ship. Runs auto by default (no human interaction) or interactive (pauses at each step). Delegates every step and holds no logic of its own. Do NOT use to run one step in isolation; call that step's skill directly. argument-hint: spec | plan | implement | review | ship --- # Skill: sdlc -Complete end-to-end software delivery. Defaults to autonomous; switches to interactive on demand. - -## Iron rule - -**You are the conductor, not a player.** - -You orchestrate; you never write code or judge it yourself. You own the plan: you run `aidd-dev:01-plan` in your own context, because the plan is the contract no worker may rewrite. Every other step you isolate as a leaf agent that runs a recipe and returns only a result. The agent is the isolation; the recipe inside it never spawns again, so the write path stays two layers deep (a leaf may still spawn a read-only recon helper). - -You spawn two workers: - -- `executor` - runs `aidd-dev:02-implement` when code must be written. It never holds the plan-authoring skill, so it cannot rewrite the contract. -- `checker` - runs `aidd-dev:05-review` when completed work must be verified. - -## Mandatory steps (enforce - never skip) - -The flow has exactly ONE skippable step. Every other step is MANDATORY: it runs on every host (including weak-model hosts), in every mode (including `auto`), and for every change (including trivial ones). - -- `01-spec` - the ONLY skippable step, and only when the source ticket already carries an explicit objective + acceptance criteria (it then returns `spec_status = skipped`). -- `02-plan`, `03-implement`, `04-review`, `05-ship` - MANDATORY. Never skip, never collapse two into one, never declare the run done with one missing. Skipping any of them is a FAILED run, not a shortcut. - -Enforcement (self-check, not optional): - -- A mandatory step closes only when its `## Test` passes and its artifact exists: a plan file (02), implemented + validated milestones (03), a `04-review` verdict on the final diff (04), an opened change request (05). -- **`04-review` is non-negotiable: code is never shipped unreviewed.** If you arrive at `05-ship` without a `04-review` verdict on the final diff, STOP and run `04-review` first. -- Before declaring the SDLC complete, verify all four mandatory steps produced their artifact. If any is missing, the run is NOT done - resume at the missing step. Do not report success with a skipped step. - -## Modes - -| Mode | Trigger | Behavior | -| ------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `auto` | default; `/sdlc `; orchestrator invocation | Never asks the human. All decisions yours. | -| `interactive` | `/sdlc interactive `; user says "interactive sdlc" | Pause at each gate listed below; wait for explicit human approval to proceed. | - -Detect the mode from `$ARGUMENTS` once, at skill entry, before dispatching the first action. +Take a request from idea to shipped code, delegating every step. Autonomous by default, interactive on demand. ## Actions -| # | Action | Role | Delegate | -| --- | ----------- | ------------------------------------------------------------- | ------------------------------------ | -| 01 | `spec` | Consolidate sources, draft or refine the contract (skippable) | `spec` | -| 02 | `plan` | Produce the mandatory plan file | self: runs `aidd-dev:01-plan` | -| 03 | `implement` | Build the plan's code, every phase, until complete | `executor` runs `aidd-dev:02-implement` | -| 04 | `review` | Verdict `ship` or `iterate` | `checker` runs `aidd-dev:05-review` | -| 05 | `ship` | Commit and open a change request via the project's VCS | `commit`, `pull-request` | - -Files: `@actions/01-spec.md` ... `@actions/05-ship.md`. - -## Default flow - -`01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop back to `03` with the findings as the executor's fix list. After each action, run its `## Test` before moving to the next. - -`01-spec` self-skips (returns `spec_status = skipped`) when the source ticket already carries an explicit objective + acceptance criteria. It is the ONLY skippable step. `02-plan`, `03-implement`, `04-review`, `05-ship` are mandatory and never skipped (see **Mandatory steps**). - -## Interactive gates - -Activate only in `interactive` mode. In `auto` mode, never pause. - -1. **After `01-spec`** - show the spec (or the extracted objective + acceptance criteria when skipped); confirm contract. -2. **After `02-plan`** - show the plan; confirm scope before any code change. -3. **After `03-implement`** - show the implemented diff; confirm before review. The phase loop runs inside the delegated `implement` skill, so the gate is the whole step, not each phase. -4. **After `04-review`** - show findings and verdict; confirm ship vs iterate. -5. **Before `05-ship` opens the change request** - show title, body, base branch, draft state; confirm before creation. - -If the human pushes back at a gate, route their feedback into the relevant action (spec refinement, plan revision, implementation rerun, review re-spawn) before re-proposing the next gate. - -## Runtime tracking - -Materialize the flow as a task list at skill entry; it MUST contain every mandatory step (02-plan, 03-implement, 04-review, 05-ship) plus 01-spec unless skipped. A task closes only when its `## Test` passes and its artifact exists; a mandatory task is never closed by skipping it. - -## Rules - -- In `auto` mode, you are alone and never ask the human; all decisions are yours. -- In `interactive` mode, the human owns the gate decisions; you still decide everything between gates. -- Always run `02-plan`. Minimum: frontmatter + M/C/D + rules table + phases. Never inline ticket or spec as plan. -- Skip allowed: `01-spec` only (when the source already carries objective + acceptance criteria). `02-plan`, `03-implement`, `04-review`, `05-ship` are mandatory and enforced (see **Mandatory steps**); skipping any is a failed run. -- Choose the best decision based on the facts. -- Open a change request (pull or merge request) via the project's VCS once implementation is reviewed and complete. -- **Branch discipline (caller responsibility).** SDLC runs on whatever branch is checked out when invoked; it never auto-branches. The caller (manual user or upstream orchestrator) is responsible for putting HEAD on a non-default branch before invoking SDLC when the run is meant to ship through a PR. - -## References +| # | Action | Role | Delegate | +| --- | ----------- | ------------------------------------- | --------------------------------------- | +| 01 | `spec` | Consolidate sources into the contract | a spec capability | +| 02 | `plan` | Produce the plan file | self, via `aidd-dev:01-plan` | +| 03 | `implement` | Build the plan's code | `executor`, via `aidd-dev:02-implement` | +| 04 | `review` | Verdict `ship` or `iterate` | `checker`, via `aidd-dev:05-review` | +| 05 | `ship` | Open the change request | a commit and change-request capability | -- `aidd-dev:01-plan` -- `aidd-dev:02-implement` -- `aidd-dev:05-review` -- `spec` -- `commit` -- `pull-request` +Run `01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop to `03` then re-run `04`. -## Assets +## Transversal rules -- None. +- Delegate every step; never write or judge code yourself. +- Mode: `auto` decides alone, `interactive` pauses for approval at each step. +- Every step runs; only `01-spec` self-skips when the source already states an objective and acceptance criteria. +- Drive the plan status `pending → in-progress → implemented → reviewed`, or `blocked`. +- Every step writes into one feature folder resolved at entry. +- Never auto-branch; the caller sets a non-default branch before shipping. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md index 6d649c26..bb5483a2 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md @@ -16,7 +16,7 @@ The spec path on disk with its status (`drafted`, `refined`, or `skipped`), the 1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot checker findings, capture conversation turns. Concatenate them into one brief. 2. **Skip.** Apply the skip condition above. If it holds, return the extracted objective and criteria. -3. **Delegate.** Hand the consolidated brief and the repo root to `spec`. Let it own contract generation and refinement. +3. **Delegate.** Hand the consolidated brief and the repo root to a spec capability, discovered at runtime by description. Let it own contract generation and refinement. 4. **Return.** Surface the spec path, status, objective, and acceptance criteria. ## Test diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md index 326f8501..191cb90f 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md @@ -13,8 +13,8 @@ The commit SHA and the change-request URL on the project's VCS host. ## Process 1. **Gate.** Confirm `04` produced a `ship` verdict and that no code landed after the reviewed SHA it carries. Run `git diff --name-only HEAD`: it must list only plan-tracking files (the `chore(plan): reviewed` commit and the like). Any source-code change means the reviewed verdict is stale and the new code is unreviewed: stop, run `04` on the current diff, looping back to `03` on `iterate`. If no verdict exists or it is `iterate`, stop the same way. Code is never shipped unreviewed. -2. **Commit.** Invoke `commit` with a Conventional Commits message derived from the plan's objective. -3. **Open.** Invoke `pull-request` to push the branch and open the change request. Reference the plan path in the body. +2. **Commit.** Invoke a commit capability, discovered at runtime, with a Conventional Commits message derived from the plan's objective. +3. **Open.** Invoke a change-request capability, discovered at runtime, to push the branch and open the request. Reference the plan path in the body. 4. **Return.** Surface the commit SHA and the change-request URL. ## Test From fc87e7bb64d9f79caa8edce8eaa4f5d6c61616e2 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 11:22:44 +0200 Subject: [PATCH 12/42] docs(framework): tighten the SDLC skill description Cut the router description to what + when + modes: drop the internal "pure orchestrator / holds no logic" prose. Natural-language routing verified: end-to-end intent triggers 00-sdlc, single-step requests route to their own skill. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 2 +- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 65e31ef4..18028cf8 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -48,7 +48,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [04-review.md](skills/00-sdlc/actions/04-review.md) | - | | `actions` | [05-ship.md](skills/00-sdlc/actions/05-ship.md) | - | | `-` | [README.md](skills/00-sdlc/README.md) | - | -| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Pure orchestrator for the full AIDD development flow, from a free-form request to shipped code. Use when a request must go end to end: spec, plan, implement, review, ship. Runs auto by default (no human interaction) or interactive (pauses at each step). Delegates every step and holds no logic of its own. Do NOT use to run one step in isolation; call that step's skill directly.` | +| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Orchestrate the full dev flow from a free-form request to shipped code: spec, plan, implement, review, ship, every step delegated. Use to take a request end to end to a change request, not a single step. Auto by default, interactive on demand.` | #### `skills/01-plan` diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 203ad841..1b10ce78 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -1,6 +1,6 @@ --- name: 00-sdlc -description: Pure orchestrator for the full AIDD development flow, from a free-form request to shipped code. Use when a request must go end to end: spec, plan, implement, review, ship. Runs auto by default (no human interaction) or interactive (pauses at each step). Delegates every step and holds no logic of its own. Do NOT use to run one step in isolation; call that step's skill directly. +description: Orchestrate the full dev flow from a free-form request to shipped code: spec, plan, implement, review, ship, every step delegated. Use to take a request end to end to a change request, not a single step. Auto by default, interactive on demand. argument-hint: spec | plan | implement | review | ship --- From 8394bb977845d6e4ff3d580ba9a0740e2cea4694 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 11:37:35 +0200 Subject: [PATCH 13/42] refactor(framework): make the SDLC interactive by default, auto on demand A present human typing /sdlc should see the gates; only a deliberate, configured caller (headless, orchestrator, Gardener) wants an unattended run, and that caller passes `auto`. Opting in to autonomy matches intent, and a forgotten `auto` fails loud at gate 1 instead of shipping unwatched. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 2 +- plugins/aidd-dev/skills/00-sdlc/README.md | 8 ++++---- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 6 +++--- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 18028cf8..f3a42557 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -48,7 +48,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [04-review.md](skills/00-sdlc/actions/04-review.md) | - | | `actions` | [05-ship.md](skills/00-sdlc/actions/05-ship.md) | - | | `-` | [README.md](skills/00-sdlc/README.md) | - | -| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Orchestrate the full dev flow from a free-form request to shipped code: spec, plan, implement, review, ship, every step delegated. Use to take a request end to end to a change request, not a single step. Auto by default, interactive on demand.` | +| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Orchestrate the full dev flow from a free-form request to shipped code: spec, plan, implement, review, ship, every step delegated. Use to take a request end to end to a change request, not a single step. Interactive by default (pauses at each gate); say auto for an unattended run.` | #### `skills/01-plan` diff --git a/plugins/aidd-dev/skills/00-sdlc/README.md b/plugins/aidd-dev/skills/00-sdlc/README.md index b2fea447..f588e49f 100644 --- a/plugins/aidd-dev/skills/00-sdlc/README.md +++ b/plugins/aidd-dev/skills/00-sdlc/README.md @@ -11,8 +11,8 @@ Holds no business logic of its own; every step is delegated. - A human (or upstream orchestrator) hands over a free-form request and you need to drive it end-to-end: spec, plan, implement, review, ship. -- You want the default autonomous run (`auto` mode) with no human prompts. -- You want the same flow but with confirmation gates (`interactive` mode). +- You want the default run with confirmation gates (`interactive` mode). +- You want an unattended run with no human prompts (`auto` mode). ## When NOT to use @@ -29,8 +29,8 @@ Holds no business logic of its own; every step is delegated. ## How to invoke ``` -/sdlc # auto mode (default) -/sdlc interactive # pauses at each gate for human confirmation +/sdlc # interactive (default): pauses at each gate +/sdlc auto # unattended: no human prompts ``` The skill walks 5 actions: diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 1b10ce78..00d11c49 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -1,12 +1,12 @@ --- name: 00-sdlc -description: Orchestrate the full dev flow from a free-form request to shipped code: spec, plan, implement, review, ship, every step delegated. Use to take a request end to end to a change request, not a single step. Auto by default, interactive on demand. +description: Orchestrate the full dev flow from a free-form request to shipped code: spec, plan, implement, review, ship, every step delegated. Use to take a request end to end to a change request, not a single step. Interactive by default (pauses at each gate); say auto for an unattended run. argument-hint: spec | plan | implement | review | ship --- # Skill: sdlc -Take a request from idea to shipped code, delegating every step. Autonomous by default, interactive on demand. +Take a request from idea to shipped code, delegating every step. Interactive by default, autonomous when you say `auto`. ## Actions @@ -23,7 +23,7 @@ Run `01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop to `03` then re-ru ## Transversal rules - Delegate every step; never write or judge code yourself. -- Mode: `auto` decides alone, `interactive` pauses for approval at each step. +- Mode: default `interactive`, pausing for approval at each step; switch to `auto` only when the caller says so, then decide alone and never ask. - Every step runs; only `01-spec` self-skips when the source already states an objective and acceptance criteria. - Drive the plan status `pending → in-progress → implemented → reviewed`, or `blocked`. - Every step writes into one feature folder resolved at entry. From dcec64afd6b9f208329c9ab966a296e116b95d1a Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 21:39:06 +0200 Subject: [PATCH 14/42] feat(framework): add the relevancy axis to the review skill A third review axis next to code and functional: does the change belong? Fit to the real need, conformance to the project's declared rules, and no duplication or over-engineering. It absorbs rules-conformance (slimmed out of review-code, which is now clean-code only) and stays read-only: findings hand off downstream per complexity, never an auto-fix. The SDLC checker now runs all three axes. - new action 03-review-relevancy + its report template (fit / conform / rot) - review-code slimmed to clean-code; rules moved to relevancy - 05-review router, 04-review brief, and READMEs updated to three axes Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 4 +- plugins/aidd-dev/README.md | 2 +- .../skills/00-sdlc/actions/04-review.md | 2 +- plugins/aidd-dev/skills/05-review/README.md | 21 ++++++---- plugins/aidd-dev/skills/05-review/SKILL.md | 13 +++--- .../05-review/actions/01-review-code.md | 4 +- .../05-review/actions/03-review-relevancy.md | 38 ++++++++++++++++++ .../assets/review-relevancy-template.md | 40 +++++++++++++++++++ 8 files changed, 107 insertions(+), 17 deletions(-) create mode 100644 plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md create mode 100644 plugins/aidd-dev/skills/05-review/assets/review-relevancy-template.md diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index f3a42557..c59b3d94 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -109,10 +109,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | | `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | +| `actions` | [03-review-relevancy.md](skills/05-review/actions/03-review-relevancy.md) | - | | `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` | | `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` | +| `assets` | [review-relevancy-template.md](skills/05-review/assets/review-relevancy-template.md) | `Relevancy review report template for a diff` | | `-` | [README.md](skills/05-review/README.md) | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | +| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) along three axes - code quality (clean-code), feature behavior (the plan's acceptance criteria), and relevancy (does the change belong: fit to the need, conformance to declared rules, no duplication or over-engineering). Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | #### `skills/06-test` diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index a6c7c16f..99939744 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -19,7 +19,7 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert | [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase, recipe-style, iterating until 100% completeness. | | [2.3] | [assert](skills/03-assert/README.md) | Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. | | [2.4] | [audit](skills/04-audit/README.md) | Perform deep codebase analysis to identify technical debt, dead code, and improvement opportunities. | -| [2.5] | [review](skills/05-review/README.md) | Review code quality against project rules and validate feature behavior against plan specifications. | +| [2.5] | [review](skills/05-review/README.md) | Review a diff along three axes: code quality, feature behavior against the plan, and relevancy (fit to the need, declared-rule conformance, no rot). | | [2.6] | [test](skills/06-test/README.md) | Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser. | | [2.7] | [refactor](skills/07-refactor/README.md) | Optimize code for performance and fix security vulnerabilities following OWASP guidelines. | | [2.8] | [debug](skills/08-debug/README.md) | Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. | diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md index 26c859f7..1e48469b 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md @@ -13,7 +13,7 @@ A `ship` or `iterate` verdict with the reviewed items, the findings, the complet ## Process 1. **Capture.** Record `git rev-parse HEAD` as the reviewed SHA. This is the exact code the checker judges, and the anchor `05-ship` checks against. -2. **Spawn.** Spawn the `checker` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code and functional, on that diff, and return its verdict. +2. **Spawn.** Spawn the `checker` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code, functional, and relevancy, on that diff, and return its verdict. 3. **Map.** When every check passes, the verdict is `ship`. On any blocking finding, the verdict is `iterate`. 4. **Mark.** On `ship`, set the plan frontmatter `status: reviewed` and commit it. Carry the reviewed SHA in the verdict. On `iterate`, leave the plan `implemented`: the loop fixes the diff, not the plan. 5. **Iterate.** On `iterate`, return the findings as the fix list for `03`. The next `04` re-captures the SHA on the fixed diff; ship is reached only when a review of the current diff passes. diff --git a/plugins/aidd-dev/skills/05-review/README.md b/plugins/aidd-dev/skills/05-review/README.md index bf95a38c..c0a2042b 100644 --- a/plugins/aidd-dev/skills/05-review/README.md +++ b/plugins/aidd-dev/skills/05-review/README.md @@ -2,10 +2,11 @@ # 05 - review -Reviews completed work along two axes: code quality against project rules, -and feature behavior against the plan's acceptance criteria. A recipe that -runs in the caller's context (the SDLC isolates it by spawning a `checker`) -and returns findings plus completion and quality scores. Never edits the artifact. +Reviews completed work along three axes: code quality (clean-code), +feature behavior against the plan's acceptance criteria, and relevancy +(does the change belong: fit to the need, declared-rule conformance, no rot). +A recipe that runs in the caller's context (the SDLC isolates it by spawning +a `checker`) and returns findings plus completion and quality scores. Never edits the artifact. ## When to use @@ -31,12 +32,15 @@ and returns findings plus completion and quality scores. Never edits the artifac Use skill aidd-dev:05-review ``` -The skill exposes 2 actions: +The skill exposes 3 actions: -1. `review-code` - grade the diff against project rules; surface - violations with file, line, and rule reference. +1. `review-code` - grade the diff against clean-code principles; surface + violations with file and line. 2. `review-functional` - verify the feature against the plan's acceptance criteria; emit per-criterion pass / fail. +3. `review-relevancy` - judge whether the change belongs: fit to the need, + conformance to the project's declared rules, and no duplication or + over-engineering. ## Outputs @@ -48,6 +52,9 @@ The skill exposes 2 actions: - `review-functional` - a verdict (`PASS` / `PARTIAL` / `FAIL`) and a per-criterion scoring matrix; missing or broken behaviors hand off to [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). + - `review-relevancy` - a verdict plus misfit findings (lens `fit` / + `conform` / `rot`), each tied to a declared rule, a duplication site, an + over-engineering smell, or a named need-gap; fixes hand off per complexity. - The `checker` agent running this recipe returns `ship` / `iterate` to the SDLC orchestrator. diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 1b4c68e5..7e8948af 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,13 +1,13 @@ --- name: 05-review -description: Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). -argument-hint: review-code | review-functional +description: Read-only review of a diff (a PR or working changes) along three axes - code quality (clean-code), feature behavior (the plan's acceptance criteria), and relevancy (does the change belong: fit to the need, conformance to declared rules, no duplication or over-engineering). Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). +argument-hint: review-code | review-functional | review-relevancy model: opus --- # Skill: review -Read-only review of a diff (a PR or working changes): code quality against project rules, and feature behavior against the plan's acceptance criteria. It surfaces findings and a verdict; it never edits code. The fix hands off to the act-skills (`07-refactor` for code, `02-implement` / `08-debug` for behavior gaps). Diff-scoped - for a whole-codebase read-only diagnosis use `aidd-dev:04-audit` instead. +Read-only review of a diff (a PR or working changes) along three axes: code quality, feature behavior against the plan's acceptance criteria, and relevancy. It surfaces findings and a verdict; it never edits code. The fix hands off to the act-skills (`07-refactor` for code, `02-implement` / `08-debug` for behavior gaps). Diff-scoped - for a whole-codebase read-only diagnosis use `aidd-dev:04-audit` instead. This is a recipe: it runs in the context of whoever invokes it and never spawns an agent. The SDLC isolates it by spawning a `checker` to run it; a direct caller runs it inline. @@ -15,15 +15,17 @@ This is a recipe: it runs in the context of whoever invokes it and never spawns | # | Action | When to use | | --- | ------------------- | ------------------------------------------------------------------------ | -| 01 | `review-code` | Quality review of a diff against project rules and clean-code principles | +| 01 | `review-code` | Quality review of a diff against clean-code principles | | 02 | `review-functional` | Verify the diff matches the plan's acceptance criteria, flows, edge cases | +| 03 | `review-relevancy` | Judge whether the change belongs: fit to the need, declared-rule conformance, no rot | ## Routing (run first) Pick the ONE action matching the user's intent; do NOT default to action 01. -- "review the code", "check code quality", "rules compliance", "clean code review" -> `01-review-code` +- "review the code", "check code quality", "clean code review" -> `01-review-code` - "does it match the plan", "functional review", "behavior vs acceptance criteria" -> `02-review-functional` +- "does this belong", "is it relevant", "rules compliance", "over-engineering", "duplication", "coherence with the need" -> `03-review-relevancy` If the intent is ambiguous, ask one clarifying question before picking. Then read and follow only the matching action file. @@ -31,3 +33,4 @@ If the intent is ambiguous, ask one clarifying question before picking. Then rea - `@actions/01-review-code.md` - `@actions/02-review-functional.md` +- `@actions/03-review-relevancy.md` diff --git a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md index 0d2dc108..df77dddf 100644 --- a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md +++ b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md @@ -1,6 +1,6 @@ # 01 - Review Code -Deep code review of a diff against project rules and clean-code principles. Read-only: surface quality violations only, never patch them - hand fixes off to `aidd-dev:07-refactor`. +Deep code review of a diff against clean-code principles. Conformance to the project's declared rules is the relevancy axis (`03-review-relevancy`), not this one. Read-only: surface quality violations only, never patch them - hand fixes off to `aidd-dev:07-refactor`. ## Inputs @@ -23,7 +23,7 @@ severity_breakdown: ## Process 1. **Resolve the diff.** Use `$ARGUMENTS` when provided; otherwise fall back to `git diff main`. -2. **Deep review every changed line.** Apply project conventions and global clean-code principles. No runtime checks. +2. **Deep review every changed line.** Apply global clean-code principles: naming, structure, complexity, smells. No runtime checks. Declared-rule conformance belongs to `03-review-relevancy`. 3. **Findings only.** Focus on issues on the changed lines; do not propose feature-level changes. Rate each with the 3-level severity (🔴 critical / 🟡 warning / 🟢 minor) and cite a `file:line`. Suggested fixes are described, not patched (read-only). 4. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. 5. **Format the report** using `@../assets/review-code-template.md` (Expected changes, Findings, Coverage, Follow-up). Top fixes hand off to `aidd-dev:07-refactor`. diff --git a/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md new file mode 100644 index 00000000..1f057886 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md @@ -0,0 +1,38 @@ +# 03 - Review Relevancy + +Judge whether the diff belongs: coherent with the codebase, its conventions and declared rules, serving the real need, with nothing duplicated or over-built. Read-only: surface misfits only, never patch them - hand fixes off per complexity to `aidd-dev:07-refactor`, `aidd-dev:02-implement`, or `aidd-dev:08-debug`. + +## Inputs + +```yaml +scope: # optional; defaults to `git diff main` +need: # optional; the plan objective or the ticket +``` + +## Outputs + +```yaml +review_path: aidd_docs/tasks//_/review.md +verdict: approve | changes-requested | blocked +findings_count: +severity_breakdown: + critical: # 🔴 + warning: # 🟡 + minor: # 🟢 +``` + +## Process + +1. **Gather.** Resolve the diff from `$ARGUMENTS`, else `git diff main`. Capture the need from the plan objective or the ticket. Discover the project's declared rules and conventions at runtime, never hardcoded. Fall back cleanly when a source is absent. +2. **Fit.** Check the change against the need: does it serve the actual intent end to end, or only the literal criteria? Flag any drift between intent and result. +3. **Conform.** Check the change against the declared rules and the surrounding conventions. Flag each violation with the rule or pattern it breaks. +4. **Rot.** Scan for duplication (an existing helper reinvented), over-engineering (speculative generality, unused abstraction), and incoherence (naming, docs versus code). Cite the site. +5. **Findings only.** Rate each with the 3-level severity (🔴 / 🟡 / 🟢) and cite a `file:line` or the rule. A bare opinion is not a finding: tie each to a declared rule, a duplication site, an over-engineering smell, or a named need-gap. Describe the fix, never patch. +6. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. +7. **Write to disk** at the feature folder's `review.md`, reusing the folder of the reviewed work when it exists. Top fixes hand off per complexity: trivial to `aidd-dev:07-refactor`, behavioral to `aidd-dev:02-implement` or `aidd-dev:08-debug`. + +## Test + +- The review file exists with a defined `verdict`. +- Every finding carries a 3-level severity and cites a `file:line`, a declared rule, a duplication site, or a named need-gap; none is a bare opinion. +- No code was patched. diff --git a/plugins/aidd-dev/skills/05-review/assets/review-relevancy-template.md b/plugins/aidd-dev/skills/05-review/assets/review-relevancy-template.md new file mode 100644 index 00000000..8861bf17 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/assets/review-relevancy-template.md @@ -0,0 +1,40 @@ +--- +name: review-relevancy +description: Relevancy review report template for a diff +argument-hint: N/A +--- + +# Relevancy Review: {{feature}} + +{{one_line_summary}} + +- **Verdict**: {{approve | changes-requested | blocked}} +- **Diff scope**: `{{base}}...{{head}}` +- **Need**: {{the objective the change serves}} +- **Date**: {{yyyy_mm_dd}} +- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor + +Verdict: `approve` = the change belongs as built; `changes-requested` = misfits to address first; `blocked` = a misfit that must not merge. + +## Findings + +One row per misfit. Every row ties to evidence, never an opinion: a declared rule, a duplication site, an over-engineering smell, or a named gap between the change and the need. Read-only: describe the fix, do not patch it. + +Severity: 🔴 critical (must not merge as-is), 🟡 warning (should fix), 🟢 minor (nit). +Lens (one of): `fit` (serves the real need), `conform` (declared rules and conventions), `rot` (duplication, over-engineering, incoherence). + +| Sev | Lens | Location / rule | Misfit | Suggested fix | +| --- | ------- | --------------------- | -------------------------------------------- | ----------------------------------- | +| 🔴 | fit | `src/cart.ts:6` | Formats USD; the need is EUR for FR users | Reuse `formatEUR`; correct the need | +| 🟡 | rot | `src/cart.ts:6` | Reinvents existing `formatEUR` (money.ts) | Delegate to `formatEUR` | +| 🟢 | conform | `naming-rule.md` | `getData` violates the verb-noun rule | Rename per the rule | + +## Coverage + +- **Scanned**: {{fit, conform, rot: whichever applied}} +- **Sources**: {{the need source, the rule files discovered, or "none found"}} + +## Follow-up + +- **Top fixes** (ranked, hand off per complexity to `aidd-dev:07-refactor`, `aidd-dev:02-implement`, or `aidd-dev:08-debug`): {{top_fixes}} +- **Notes**: {{additional_notes}} From 3b578e5aa2db64cf683255df1b212d6d37ff8905 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 22:04:45 +0200 Subject: [PATCH 15/42] refactor(framework): align review skill to the norm, one report, all axes Bring 05-review up to the skill contract and make it produce a single report. - Run all three axes by default, or one when named (was pick-one routing). - One `review.md` in the feature folder beside plan.md (was three clobbering files); each axis fills its section, unrun axes marked "Not run". - One overall verdict, strictest across axes (was two vocabularies). - Actions rewritten to the anatomy: prose singular Input/Output, no frozen YAML, no stray Rules section. - Shared scales (severity, verdict, categories, lenses) moved to references/review-rubric.md; one assets/review-template.md replaces three. - Drop the orchestration meta from 05-review and 02-implement: a skill does not describe how the SDLC spawns or isolates it; that lives in the SDLC. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 7 ++- plugins/aidd-dev/skills/02-implement/SKILL.md | 1 - plugins/aidd-dev/skills/05-review/README.md | 53 +++++++++---------- plugins/aidd-dev/skills/05-review/SKILL.md | 36 ++++++------- .../05-review/actions/01-review-code.md | 33 ++++-------- .../05-review/actions/02-review-functional.md | 45 +++++----------- .../05-review/actions/03-review-relevancy.md | 32 ++++------- .../05-review/assets/review-code-template.md | 47 ---------------- .../assets/review-functional-template.md | 53 ------------------- .../assets/review-relevancy-template.md | 40 -------------- .../05-review/assets/review-template.md | 47 ++++++++++++++++ .../05-review/references/review-rubric.md | 27 ++++++++++ 12 files changed, 151 insertions(+), 270 deletions(-) delete mode 100644 plugins/aidd-dev/skills/05-review/assets/review-code-template.md delete mode 100644 plugins/aidd-dev/skills/05-review/assets/review-functional-template.md delete mode 100644 plugins/aidd-dev/skills/05-review/assets/review-relevancy-template.md create mode 100644 plugins/aidd-dev/skills/05-review/assets/review-template.md create mode 100644 plugins/aidd-dev/skills/05-review/references/review-rubric.md diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index c59b3d94..d161e2e3 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -110,11 +110,10 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | | `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | | `actions` | [03-review-relevancy.md](skills/05-review/actions/03-review-relevancy.md) | - | -| `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` | -| `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` | -| `assets` | [review-relevancy-template.md](skills/05-review/assets/review-relevancy-template.md) | `Relevancy review report template for a diff` | +| `assets` | [review-template.md](skills/05-review/assets/review-template.md) | `One review report for a diff, all three axes in one file` | | `-` | [README.md](skills/05-review/README.md) | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) along three axes - code quality (clean-code), feature behavior (the plan's acceptance criteria), and relevancy (does the change belong: fit to the need, conformance to declared rules, no duplication or over-engineering). Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | +| `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | +| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) into one report, along three axes - code quality (clean-code), feature behavior (the plan's acceptance criteria), and relevancy (does the change belong: fit to the need, declared-rule conformance, no duplication or over-engineering). Runs all three axes by default, or one when named. Surfaces findings with a verdict; never patches. Do NOT use for a whole-codebase health check (use 04-audit), fixing findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | #### `skills/06-test` diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index 0767c51b..44ed2f91 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -20,7 +20,6 @@ Run them in order, `01 → 03`. ## Transversal rules -- Context: this is a recipe. It runs in the context of whoever invokes it (a user, or an `executor` agent the SDLC spawned) and never spawns an agent itself. - 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. diff --git a/plugins/aidd-dev/skills/05-review/README.md b/plugins/aidd-dev/skills/05-review/README.md index c0a2042b..e258791a 100644 --- a/plugins/aidd-dev/skills/05-review/README.md +++ b/plugins/aidd-dev/skills/05-review/README.md @@ -2,19 +2,17 @@ # 05 - review -Reviews completed work along three axes: code quality (clean-code), -feature behavior against the plan's acceptance criteria, and relevancy -(does the change belong: fit to the need, declared-rule conformance, no rot). -A recipe that runs in the caller's context (the SDLC isolates it by spawning -a `checker`) and returns findings plus completion and quality scores. Never edits the artifact. +Reviews a diff along three axes: code quality (clean-code), feature behavior +against the plan's acceptance criteria, and relevancy (does the change belong: +fit to the need, declared-rule conformance, no rot). Read-only: surfaces +findings and one verdict into a single report, never edits the artifact. Runs +all three axes by default, or one when named. ## When to use - A feature is implemented and you need an independent verdict before shipping. -- An iteration of [00-sdlc](../00-sdlc/README.md) is delegating the - `review` step to this skill. -- A diff needs a rule-based code review without ad-hoc opinion. +- A diff needs a grounded review without ad-hoc opinion. ## When NOT to use @@ -29,43 +27,42 @@ a `checker`) and returns findings plus completion and quality scores. Never edit ## How to invoke ``` -Use skill aidd-dev:05-review +Use skill aidd-dev:05-review # all three axes +Use skill aidd-dev:05-review review-relevancy # one named axis ``` -The skill exposes 3 actions: +The skill exposes 3 axes, run together by default or one when named: 1. `review-code` - grade the diff against clean-code principles; surface violations with file and line. 2. `review-functional` - verify the feature against the plan's acceptance - criteria; emit per-criterion pass / fail. + criteria; per-criterion trace plus missing / unplanned / edge-case gaps. 3. `review-relevancy` - judge whether the change belongs: fit to the need, conformance to the project's declared rules, and no duplication or over-engineering. ## Outputs -- A read-only report (never patches the code): - - `review-code` - a verdict (`approve` / `changes-requested` / `blocked`) - plus a findings table with 3-level severity (🔴 critical / 🟡 warning / - 🟢 minor), `file:line`, issue, and a suggested fix to hand off to - [07-refactor](../07-refactor/README.md). - - `review-functional` - a verdict (`PASS` / `PARTIAL` / `FAIL`) and a - per-criterion scoring matrix; missing or broken behaviors hand off to - [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). - - `review-relevancy` - a verdict plus misfit findings (lens `fit` / - `conform` / `rot`), each tied to a declared rule, a duplication site, an - over-engineering smell, or a named need-gap; fixes hand off per complexity. -- The `checker` agent running this recipe returns `ship` / `iterate` to the - SDLC orchestrator. +- One read-only `review.md` in the reviewed work's feature folder, beside + `plan.md`, never patches the code: + - Header: the overall verdict (`approve` / `changes-requested` / `blocked`, + the strictest across the axes run), scope, axes run, findings count. + - `Code` section: severity-rated findings (🔴 / 🟡 / 🟢) with `file:line`; + fixes hand off to [07-refactor](../07-refactor/README.md). + - `Functional` section: per-criterion matrix plus the gap lists; fixes hand + off to [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). + - `Relevancy` section: misfits by lens (`fit` / `conform` / `rot`), each + tied to a rule, a duplication site, a smell, or a named need-gap. + - An axis not run is marked "Not run". ## Prerequisites - A diff or a set of changes to review. - A plan file with explicit acceptance criteria for the functional axis. -- Project rules loaded in context for the code axis. +- The project's declared rules, discovered at runtime, for the relevancy axis. ## Technical details -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the two -review contracts. The SDLC runs this recipe inside a fresh-context `checker` -agent to avoid bias from the implementation conversation. +See [`SKILL.md`](SKILL.md), [`actions/`](actions/), and the report template in +[`assets/`](assets/) for the three review axes and the single report they +compose. diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 7e8948af..f0b53971 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,36 +1,34 @@ --- name: 05-review -description: Read-only review of a diff (a PR or working changes) along three axes - code quality (clean-code), feature behavior (the plan's acceptance criteria), and relevancy (does the change belong: fit to the need, conformance to declared rules, no duplication or over-engineering). Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). +description: Read-only review of a diff (a PR or working changes) into one report, along three axes - code quality (clean-code), feature behavior (the plan's acceptance criteria), and relevancy (does the change belong: fit to the need, declared-rule conformance, no duplication or over-engineering). Runs all three axes by default, or one when named. Surfaces findings with a verdict; never patches. Do NOT use for a whole-codebase health check (use 04-audit), fixing findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). argument-hint: review-code | review-functional | review-relevancy model: opus --- # Skill: review -Read-only review of a diff (a PR or working changes) along three axes: code quality, feature behavior against the plan's acceptance criteria, and relevancy. It surfaces findings and a verdict; it never edits code. The fix hands off to the act-skills (`07-refactor` for code, `02-implement` / `08-debug` for behavior gaps). Diff-scoped - for a whole-codebase read-only diagnosis use `aidd-dev:04-audit` instead. +Read-only review of a diff along three axes, code quality, feature behavior, and relevancy, composed into one report. Diff-scoped; for a whole-codebase diagnosis use `aidd-dev:04-audit`. -This is a recipe: it runs in the context of whoever invokes it and never spawns an agent. The SDLC isolates it by spawning a `checker` to run it; a direct caller runs it inline. +## Actions -## Available actions +| # | Action | Axis | +| --- | ------------------- | ---------------------------------------------------------------- | +| 01 | `review-code` | Clean-code quality on the changed lines | +| 02 | `review-functional` | The diff against the plan's acceptance criteria | +| 03 | `review-relevancy` | Does the change belong: fit to the need, rule conformance, no rot | -| # | Action | When to use | -| --- | ------------------- | ------------------------------------------------------------------------ | -| 01 | `review-code` | Quality review of a diff against clean-code principles | -| 02 | `review-functional` | Verify the diff matches the plan's acceptance criteria, flows, edge cases | -| 03 | `review-relevancy` | Judge whether the change belongs: fit to the need, declared-rule conformance, no rot | +Run all three by default, composing one report. Run a single axis only when the caller names it; if it is unclear whether they want all or one, ask. Files: `@actions/01-review-code.md` ... `@actions/03-review-relevancy.md`. -## Routing (run first) +## Transversal rules -Pick the ONE action matching the user's intent; do NOT default to action 01. +- Read-only: surface findings, never patch. Hand fixes off per complexity: `07-refactor` for code, `02-implement` or `08-debug` for behavior. +- Output: one `review.md` in the reviewed work's feature folder, beside `plan.md`, from `@assets/review-template.md`. Each axis fills its section; an axis not run is marked "Not run". +- Verdict: one overall verdict, the strictest across the axes run, per `@references/review-rubric.md`. -- "review the code", "check code quality", "clean code review" -> `01-review-code` -- "does it match the plan", "functional review", "behavior vs acceptance criteria" -> `02-review-functional` -- "does this belong", "is it relevant", "rules compliance", "over-engineering", "duplication", "coherence with the need" -> `03-review-relevancy` +## References -If the intent is ambiguous, ask one clarifying question before picking. Then read and follow only the matching action file. +- `references/review-rubric.md`: the severity scale, the verdict rule, the code categories, and the relevancy lenses. -## Actions +## Assets -- `@actions/01-review-code.md` -- `@actions/02-review-functional.md` -- `@actions/03-review-relevancy.md` +- `assets/review-template.md`: the single report the three axes fill. diff --git a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md index df77dddf..1537bbd9 100644 --- a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md +++ b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md @@ -1,34 +1,23 @@ # 01 - Review Code -Deep code review of a diff against clean-code principles. Conformance to the project's declared rules is the relevancy axis (`03-review-relevancy`), not this one. Read-only: surface quality violations only, never patch them - hand fixes off to `aidd-dev:07-refactor`. +Grade the diff against clean-code principles and record the findings in the review report. -## Inputs +## Input -```yaml -scope: # optional; defaults to `git diff main` -``` +The diff to review, a git ref range or path, from `$ARGUMENTS`; defaults to `git diff main`. -## Outputs +## Output -```yaml -review_path: aidd_docs/tasks//_/review.md -verdict: approve | changes-requested | blocked -findings_count: -severity_breakdown: - critical: # 🔴 - warning: # 🟡 - minor: # 🟢 -``` +The `Code` section of the feature folder's `review.md`, filled with severity-rated findings, each citing a changed `file:line`. ## Process -1. **Resolve the diff.** Use `$ARGUMENTS` when provided; otherwise fall back to `git diff main`. -2. **Deep review every changed line.** Apply global clean-code principles: naming, structure, complexity, smells. No runtime checks. Declared-rule conformance belongs to `03-review-relevancy`. -3. **Findings only.** Focus on issues on the changed lines; do not propose feature-level changes. Rate each with the 3-level severity (🔴 critical / 🟡 warning / 🟢 minor) and cite a `file:line`. Suggested fixes are described, not patched (read-only). -4. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. -5. **Format the report** using `@../assets/review-code-template.md` (Expected changes, Findings, Coverage, Follow-up). Top fixes hand off to `aidd-dev:07-refactor`. -6. **Write to disk** at `aidd_docs/tasks//_/review.md`. Reuse the feature folder of the reviewed work when it exists, otherwise create it. +1. **Resolve.** Take the diff from `$ARGUMENTS`, otherwise `git diff main`. +2. **Review.** Read every changed line for clean-code: naming, structure, complexity, smells, error handling. No runtime checks. Declared-rule conformance belongs to the relevancy axis, not this one. +3. **Rate.** One finding per issue on the changed lines, rated and categorized per `@../references/review-rubric.md`, citing a `file:line`. Describe the fix, never patch. +4. **Record.** Write the findings into the `Code` section of `review.md` (per the skill's transversal rules). Hand the top fixes to `aidd-dev:07-refactor`. ## Test -The review file exists at the emitted `review_path`; it has a defined `verdict`; every finding row carries a 3-level severity and cites a changed `file:line`; the report contains the Findings and Coverage sections from `@../assets/review-code-template.md`. No code was patched. +- The `Code` section of `review.md` is filled, every finding rated and citing a changed `file:line`. +- No code is patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md index 4b3bd0a0..59a1cfe8 100644 --- a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md +++ b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md @@ -1,45 +1,24 @@ # 02 - Review Functional -Verify the implemented feature matches the plan's acceptance criteria, flows, and edge cases. Static review of the current diff against plan intent. No app execution, no browser, no code-quality checks. Read-only: surface gaps, never patch them - hand a missing behavior off to `aidd-dev:02-implement`, a broken one to `aidd-dev:08-debug`. +Verify the diff matches the plan's acceptance criteria, flows, and edge cases, and record the result in the review report. -## Inputs +## Input -```yaml -plan_path: # required via $ARGUMENTS or prompt -diff_scope: # optional; defaults to `git diff main` -``` +The plan path holding the acceptance criteria, from `$ARGUMENTS` or the prompt, and the diff to trace (a git ref range; defaults to `git diff main`). -## Outputs - -```yaml -review_path: aidd_docs/tasks//_/review-functional.md -criteria_total: -criteria_traced: -missing_behaviors: -unplanned_behaviors: -edge_case_gaps: -``` - -## Rules - -Check against: - -- Inconsistencies -- Duplications -- Non logical Flows or Steps +## Output +The `Functional` section of the feature folder's `review.md`: one row per acceptance criterion traced to the diff, plus the missing, unplanned, and edge-case gaps. ## Process -1. **Read the plan.** Use `plan_path` from `$ARGUMENTS` when provided; otherwise ask the user to supply the acceptance criteria directly. -2. **Extract acceptance criteria.** If they exist in the plan, ask the user to validate them before proceeding. If missing, ask the user to provide them. -3. **Fetch the diff.** Use `diff_scope` when provided; otherwise `git diff main`. -4. **Trace each criterion to the diff.** Fill the scoring matrix with one row per acceptance criterion. -5. **List missing behaviors** (criteria with no trace in the diff). -6. **List unplanned behaviors** (diff changes that trace to no criterion). -7. **List flow and edge-case gaps** surfaced by walking through each criterion. -8. **Format and write** the report using `@../assets/review-functional-template.md` to `aidd_docs/tasks//_/review-functional.md`. Reuse the feature folder of the reviewed work when it exists, otherwise create it. +1. **Read.** Take the plan from `$ARGUMENTS`; if absent, ask the user for the acceptance criteria. Static review only, no app execution or browser. +2. **Trace.** Fetch the diff, then trace each acceptance criterion to it, one matrix row per criterion: met, partial, or unmet, with evidence or the gap. +3. **Gaps.** List missing behaviors (criteria with no trace), unplanned behaviors (diff changes tracing to no criterion), and flow or edge-case gaps. An empty list reads "none", never omitted. +4. **Record.** Write the matrix and the gaps into the `Functional` section of `review.md`. Hand a missing behavior to `aidd-dev:02-implement`, a broken one to `aidd-dev:08-debug`. ## Test -The report file exists at the emitted `review_path`, contains a scoring matrix with exactly one row per acceptance criterion, and includes explicit `Missing behaviors`, `Unplanned behaviors`, and `Edge-case gaps` sections (empty sections show an explicit "none" rather than being omitted). +- The `Functional` section of `review.md` holds exactly one row per acceptance criterion. +- The missing, unplanned, and edge-case lists are present, each reading "none" when empty. +- No code is patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md index 1f057886..f56f04cc 100644 --- a/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md +++ b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md @@ -1,38 +1,24 @@ # 03 - Review Relevancy -Judge whether the diff belongs: coherent with the codebase, its conventions and declared rules, serving the real need, with nothing duplicated or over-built. Read-only: surface misfits only, never patch them - hand fixes off per complexity to `aidd-dev:07-refactor`, `aidd-dev:02-implement`, or `aidd-dev:08-debug`. +Judge whether the diff belongs, coherent with the codebase, its conventions and declared rules, serving the real need, with nothing duplicated or over-built, and record the misfits in the review report. -## Inputs +## Input -```yaml -scope: # optional; defaults to `git diff main` -need: # optional; the plan objective or the ticket -``` +The diff to review (a git ref range or path; defaults to `git diff main`), the need it serves (the plan objective or the ticket), and the project's declared rules and conventions, discovered at runtime. -## Outputs +## Output -```yaml -review_path: aidd_docs/tasks//_/review.md -verdict: approve | changes-requested | blocked -findings_count: -severity_breakdown: - critical: # 🔴 - warning: # 🟡 - minor: # 🟢 -``` +The `Relevancy` section of the feature folder's `review.md`, filled with misfit findings under the lenses `fit`, `conform`, and `rot`, each tied to evidence. ## Process -1. **Gather.** Resolve the diff from `$ARGUMENTS`, else `git diff main`. Capture the need from the plan objective or the ticket. Discover the project's declared rules and conventions at runtime, never hardcoded. Fall back cleanly when a source is absent. +1. **Gather.** Resolve the diff from `$ARGUMENTS`, otherwise `git diff main`. Capture the need from the plan objective or the ticket. Discover the project's declared rules and conventions at runtime, never hardcoded. Fall back cleanly when a source is absent. 2. **Fit.** Check the change against the need: does it serve the actual intent end to end, or only the literal criteria? Flag any drift between intent and result. 3. **Conform.** Check the change against the declared rules and the surrounding conventions. Flag each violation with the rule or pattern it breaks. 4. **Rot.** Scan for duplication (an existing helper reinvented), over-engineering (speculative generality, unused abstraction), and incoherence (naming, docs versus code). Cite the site. -5. **Findings only.** Rate each with the 3-level severity (🔴 / 🟡 / 🟢) and cite a `file:line` or the rule. A bare opinion is not a finding: tie each to a declared rule, a duplication site, an over-engineering smell, or a named need-gap. Describe the fix, never patch. -6. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. -7. **Write to disk** at the feature folder's `review.md`, reusing the folder of the reviewed work when it exists. Top fixes hand off per complexity: trivial to `aidd-dev:07-refactor`, behavioral to `aidd-dev:02-implement` or `aidd-dev:08-debug`. +5. **Record.** Write each finding into the `Relevancy` section of `review.md`, rated and placed under its lens per `@../references/review-rubric.md`. A bare opinion is not a finding: tie each to a declared rule, a duplication site, an over-engineering smell, or a named need-gap. Describe the fix, never patch. ## Test -- The review file exists with a defined `verdict`. -- Every finding carries a 3-level severity and cites a `file:line`, a declared rule, a duplication site, or a named need-gap; none is a bare opinion. -- No code was patched. +- The `Relevancy` section of `review.md` is filled, every finding under a lens and tied to a `file:line`, a declared rule, a duplication site, or a named need-gap. +- No finding is a bare opinion, and no code is patched. diff --git a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md b/plugins/aidd-dev/skills/05-review/assets/review-code-template.md deleted file mode 100644 index 2fbff291..00000000 --- a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: review-code -description: Code review report template for a diff -argument-hint: N/A ---- - -# Code Review: {{feature}} - -{{one_line_summary}} - -- **Verdict**: {{approve | changes-requested | blocked}} -- **Diff scope**: `{{base}}...{{head}}` -- **Date**: {{yyyy_mm_dd}} -- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor - -Verdict: `approve` = no critical findings, ship it; `changes-requested` = warnings or a fixable critical to address first; `blocked` = a critical that must not merge. - -## Expected changes - -What the diff was meant to deliver (from the ticket or plan). Tick what the diff actually does. - -- [ ] {{expected_change_1}} -- [ ] {{expected_change_2}} - -## Findings - -One row per issue, on the CHANGED lines only (this is a diff review, not a codebase audit). Every row cites a `file:line`. Sort by severity. Read-only: describe the fix, do not patch it - hand fixes off to `aidd-dev:07-refactor`. - -Severity: 🔴 critical (must not merge as-is), 🟡 warning (should fix), 🟢 minor (nit). -Category (one of): `standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. - -| Sev | Category | Location | Issue | Suggested fix | -| --- | ----------- | --------------------- | ------------------------------------ | ------------------------------------ | -| 🔴 | security | `src/api/user.ts:30` | Request body used without validation | Validate with the project schema lib | -| 🟡 | code-health | `LivePreview.tsx:43` | `user` recomputed on every render | Memoize with `useMemo` | - -## Coverage - -Dimensions examined on the diff (a dimension with no finding is still listed here as scanned; one not applicable to this diff is marked n/a). - -- **Scanned**: {{dimensions examined, comma-separated}} -- **Not applicable**: {{dimensions n/a for this diff, or "none"}} - -## Follow-up - -- **Top fixes** (ranked, hand off to `aidd-dev:07-refactor`): {{top_fixes}} -- **Notes**: {{additional_notes}} diff --git a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md b/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md deleted file mode 100644 index 9de9d828..00000000 --- a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: review-functional -description: Functional review report template for a diff against a plan -argument-hint: N/A ---- - -# Functional Review: {{feature}} - -- **Plan**: `{{plan_path}}` -- **Diff scope**: `{{base}}...{{head}}` -- **Date**: {{yyyy_mm_dd}} - -## Verdict - -{{PASS | PARTIAL | FAIL}} - {{one_line_rationale}} - -Verdict: `PASS` = every criterion Met; `PARTIAL` = some criteria Partial or Unmet but none blocking; `FAIL` = at least one 🔴 blocking gap. - -## Scoring Matrix - -One row per acceptance criterion. Severity uses the shared 3-level scale (it applies to `Partial` / `Unmet` rows only). - -| Criterion | Files | Status | Severity | Notes | -| ---------------- | ----- | --------------------- | --------------------------------- | ----- | -| {{criterion}} | | Met / Partial / Unmet | 🔴 blocker / 🟡 major / 🟢 minor | | - -- Status - `Met`: fully implemented in the diff; `Partial`: implemented with gaps; `Unmet`: absent from the diff. -- Severity - 🔴 blocker: feature cannot ship; 🟡 major: shipping degrades UX; 🟢 minor: cosmetic or non-blocking. - -## Missing behaviors - -Acceptance criteria with no trace in the diff (hand off implementation to `aidd-dev:02-implement`; if a criterion is implemented but broken, hand off to `aidd-dev:08-debug`). - -- [ ] {{criterion not found in diff}} - -## Unplanned behaviors - -Changes present in the diff but traced to no acceptance criterion. - -- [ ] {{unplanned change - confirm scope with author}} - -## Flow / edge-case gaps - -Gaps surfaced while walking each criterion against the diff. - -- [ ] {{flow or edge-case gap}} - -## Summary - -- **Criteria covered**: {{x/y}} -- **Blockers**: {{count}} -- **Follow-up actions**: {{actions}} -- **Additional notes**: {{notes}} diff --git a/plugins/aidd-dev/skills/05-review/assets/review-relevancy-template.md b/plugins/aidd-dev/skills/05-review/assets/review-relevancy-template.md deleted file mode 100644 index 8861bf17..00000000 --- a/plugins/aidd-dev/skills/05-review/assets/review-relevancy-template.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: review-relevancy -description: Relevancy review report template for a diff -argument-hint: N/A ---- - -# Relevancy Review: {{feature}} - -{{one_line_summary}} - -- **Verdict**: {{approve | changes-requested | blocked}} -- **Diff scope**: `{{base}}...{{head}}` -- **Need**: {{the objective the change serves}} -- **Date**: {{yyyy_mm_dd}} -- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor - -Verdict: `approve` = the change belongs as built; `changes-requested` = misfits to address first; `blocked` = a misfit that must not merge. - -## Findings - -One row per misfit. Every row ties to evidence, never an opinion: a declared rule, a duplication site, an over-engineering smell, or a named gap between the change and the need. Read-only: describe the fix, do not patch it. - -Severity: 🔴 critical (must not merge as-is), 🟡 warning (should fix), 🟢 minor (nit). -Lens (one of): `fit` (serves the real need), `conform` (declared rules and conventions), `rot` (duplication, over-engineering, incoherence). - -| Sev | Lens | Location / rule | Misfit | Suggested fix | -| --- | ------- | --------------------- | -------------------------------------------- | ----------------------------------- | -| 🔴 | fit | `src/cart.ts:6` | Formats USD; the need is EUR for FR users | Reuse `formatEUR`; correct the need | -| 🟡 | rot | `src/cart.ts:6` | Reinvents existing `formatEUR` (money.ts) | Delegate to `formatEUR` | -| 🟢 | conform | `naming-rule.md` | `getData` violates the verb-noun rule | Rename per the rule | - -## Coverage - -- **Scanned**: {{fit, conform, rot: whichever applied}} -- **Sources**: {{the need source, the rule files discovered, or "none found"}} - -## Follow-up - -- **Top fixes** (ranked, hand off per complexity to `aidd-dev:07-refactor`, `aidd-dev:02-implement`, or `aidd-dev:08-debug`): {{top_fixes}} -- **Notes**: {{additional_notes}} diff --git a/plugins/aidd-dev/skills/05-review/assets/review-template.md b/plugins/aidd-dev/skills/05-review/assets/review-template.md new file mode 100644 index 00000000..b2164edf --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/assets/review-template.md @@ -0,0 +1,47 @@ +--- +name: review +description: One review report for a diff, all three axes in one file +argument-hint: N/A +--- + +# Review: {{feature}} + +{{one_line_summary}} + +- **Verdict**: {{approve | changes-requested | blocked}} +- **Diff scope**: `{{base}}...{{head}}` +- **Axes run**: {{code, functional, relevancy}} +- **Date**: {{yyyy_mm_dd}} +- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor + +Verdict: `approve` = ship it; `changes-requested` = fix the warnings or fixable criticals first; `blocked` = a critical that must not merge. The overall verdict is the strictest across the axes run. + +## Code + +Clean-code findings on the changed lines (or "Not run"). + +| Sev | Category | Location | Issue | Suggested fix | +| --- | -------- | -------- | ----- | ------------- | + +## Functional + +Each acceptance criterion traced to the diff (or "Not run"). + +| Criterion | Met | Evidence / gap | +| --------- | --- | -------------- | + +- **Missing behaviors**: {{criteria with no trace, or "none"}} +- **Unplanned behaviors**: {{diff changes tracing to no criterion, or "none"}} +- **Edge-case gaps**: {{gaps, or "none"}} + +## Relevancy + +Does the change belong (or "Not run"). Every finding ties to evidence, never an opinion. + +| Sev | Lens | Location / rule | Misfit | Suggested fix | +| --- | ---- | --------------- | ------ | ------------- | + +## Follow-up + +- **Top fixes** (ranked, hand off per complexity to `aidd-dev:07-refactor`, `aidd-dev:02-implement`, or `aidd-dev:08-debug`): {{top_fixes}} +- **Notes**: {{additional_notes}} diff --git a/plugins/aidd-dev/skills/05-review/references/review-rubric.md b/plugins/aidd-dev/skills/05-review/references/review-rubric.md new file mode 100644 index 00000000..759ee612 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/references/review-rubric.md @@ -0,0 +1,27 @@ +# Review rubric + +Shared definitions for the three review axes. The actions and the report template draw from here, so the scales live in one place. + +## Severity + +- 🔴 critical: must not merge as-is. +- 🟡 warning: should fix. +- 🟢 minor: nit. + +## Verdict + +One overall verdict, the strictest across the axes run: + +- `approve`: no critical finding, ship it. +- `changes-requested`: warnings, or a fixable critical to address first. +- `blocked`: a critical that must not merge. + +## Code categories + +`standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. + +## Relevancy lenses + +- `fit`: serves the real need, not only the literal criteria. +- `conform`: the project's declared rules and the surrounding conventions. +- `rot`: duplication, over-engineering, incoherence (naming, docs versus code). From 170d0b17506012f394da71a5900ba78257f5816d Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 22:15:08 +0200 Subject: [PATCH 16/42] docs(framework): shorten review and implement descriptions Cut both to two lines and drop the SDLC mention from implement: a skill's description states what it does and when, not how an orchestrator calls it. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 4 ++-- plugins/aidd-dev/skills/02-implement/SKILL.md | 2 +- plugins/aidd-dev/skills/05-review/SKILL.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index d161e2e3..d47c9c41 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -75,7 +75,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-finalize.md](skills/02-implement/actions/03-finalize.md) | - | | `-` | [README.md](skills/02-implement/README.md) | - | | `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` | -| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing, or when the SDLC delegates the implement step. Do NOT use to write a plan (01-plan), review a diff (05-review), or fix a bug with no plan (08-debug).` | +| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan (01-plan), review a diff (05-review), or fix a bug with no plan (08-debug).` | #### `skills/03-assert` @@ -113,7 +113,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [review-template.md](skills/05-review/assets/review-template.md) | `One review report for a diff, all three axes in one file` | | `-` | [README.md](skills/05-review/README.md) | - | | `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) into one report, along three axes - code quality (clean-code), feature behavior (the plan's acceptance criteria), and relevancy (does the change belong: fit to the need, declared-rule conformance, no duplication or over-engineering). Runs all three axes by default, or one when named. Surfaces findings with a verdict; never patches. Do NOT use for a whole-codebase health check (use 04-audit), fixing findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | +| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff along three axes, code quality, behavior versus the plan, and relevancy, into one report with a verdict. Use to review changes before they ship. Do NOT use to fix the findings or to audit a whole codebase (use 04-audit).` | #### `skills/06-test` diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index 44ed2f91..2b3e63da 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -1,6 +1,6 @@ --- name: 02-implement -description: Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing, or when the SDLC delegates the implement step. Do NOT use to write a plan (01-plan), review a diff (05-review), or fix a bug with no plan (08-debug). +description: Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan (01-plan), review a diff (05-review), or fix a bug with no plan (08-debug). argument-hint: prepare | execute | finalize --- diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index f0b53971..1b13e848 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,6 +1,6 @@ --- name: 05-review -description: Read-only review of a diff (a PR or working changes) into one report, along three axes - code quality (clean-code), feature behavior (the plan's acceptance criteria), and relevancy (does the change belong: fit to the need, declared-rule conformance, no duplication or over-engineering). Runs all three axes by default, or one when named. Surfaces findings with a verdict; never patches. Do NOT use for a whole-codebase health check (use 04-audit), fixing findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). +description: Read-only review of a diff along three axes, code quality, behavior versus the plan, and relevancy, into one report with a verdict. Use to review changes before they ship. Do NOT use to fix the findings or to audit a whole codebase (use 04-audit). argument-hint: review-code | review-functional | review-relevancy model: opus --- From 2f40aeef6123bcb391db2954c2cf2dadc13cf75f Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Tue, 23 Jun 2026 22:19:08 +0200 Subject: [PATCH 17/42] refactor(framework): stop the review skill routing other skills A worker skill surfaces findings; it does not decide who fixes them. Drop the handoff naming (07-refactor / 02-implement / 08-debug) from the SKILL router, the actions, and the report template - each finding now just describes its fix, and the caller routes it. Keep only the one 04-audit disambiguation in the description, where a sibling could mis-trigger. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/05-review/SKILL.md | 4 ++-- plugins/aidd-dev/skills/05-review/actions/01-review-code.md | 2 +- .../aidd-dev/skills/05-review/actions/02-review-functional.md | 2 +- plugins/aidd-dev/skills/05-review/assets/review-template.md | 2 +- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 1b13e848..4a11e0b5 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -7,7 +7,7 @@ model: opus # Skill: review -Read-only review of a diff along three axes, code quality, feature behavior, and relevancy, composed into one report. Diff-scoped; for a whole-codebase diagnosis use `aidd-dev:04-audit`. +Read-only review of a diff along three axes, code quality, feature behavior, and relevancy, composed into one report. ## Actions @@ -21,7 +21,7 @@ Run all three by default, composing one report. Run a single axis only when the ## Transversal rules -- Read-only: surface findings, never patch. Hand fixes off per complexity: `07-refactor` for code, `02-implement` or `08-debug` for behavior. +- Read-only: surface each finding with its fix described, never patch. - Output: one `review.md` in the reviewed work's feature folder, beside `plan.md`, from `@assets/review-template.md`. Each axis fills its section; an axis not run is marked "Not run". - Verdict: one overall verdict, the strictest across the axes run, per `@references/review-rubric.md`. diff --git a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md index 1537bbd9..795e7582 100644 --- a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md +++ b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md @@ -15,7 +15,7 @@ The `Code` section of the feature folder's `review.md`, filled with severity-rat 1. **Resolve.** Take the diff from `$ARGUMENTS`, otherwise `git diff main`. 2. **Review.** Read every changed line for clean-code: naming, structure, complexity, smells, error handling. No runtime checks. Declared-rule conformance belongs to the relevancy axis, not this one. 3. **Rate.** One finding per issue on the changed lines, rated and categorized per `@../references/review-rubric.md`, citing a `file:line`. Describe the fix, never patch. -4. **Record.** Write the findings into the `Code` section of `review.md` (per the skill's transversal rules). Hand the top fixes to `aidd-dev:07-refactor`. +4. **Record.** Write the findings into the `Code` section of `review.md`, each with its fix described. ## Test diff --git a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md index 59a1cfe8..0be199c9 100644 --- a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md +++ b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md @@ -15,7 +15,7 @@ The `Functional` section of the feature folder's `review.md`: one row per accept 1. **Read.** Take the plan from `$ARGUMENTS`; if absent, ask the user for the acceptance criteria. Static review only, no app execution or browser. 2. **Trace.** Fetch the diff, then trace each acceptance criterion to it, one matrix row per criterion: met, partial, or unmet, with evidence or the gap. 3. **Gaps.** List missing behaviors (criteria with no trace), unplanned behaviors (diff changes tracing to no criterion), and flow or edge-case gaps. An empty list reads "none", never omitted. -4. **Record.** Write the matrix and the gaps into the `Functional` section of `review.md`. Hand a missing behavior to `aidd-dev:02-implement`, a broken one to `aidd-dev:08-debug`. +4. **Record.** Write the matrix and the gaps into the `Functional` section of `review.md`, each with the missing or broken behavior named. ## Test diff --git a/plugins/aidd-dev/skills/05-review/assets/review-template.md b/plugins/aidd-dev/skills/05-review/assets/review-template.md index b2164edf..5775cfa5 100644 --- a/plugins/aidd-dev/skills/05-review/assets/review-template.md +++ b/plugins/aidd-dev/skills/05-review/assets/review-template.md @@ -43,5 +43,5 @@ Does the change belong (or "Not run"). Every finding ties to evidence, never an ## Follow-up -- **Top fixes** (ranked, hand off per complexity to `aidd-dev:07-refactor`, `aidd-dev:02-implement`, or `aidd-dev:08-debug`): {{top_fixes}} +- **Top fixes** (ranked): {{top_fixes}} - **Notes**: {{additional_notes}} From 2bbc02f9950e614d62c2060f72a9a6ad1e7280cf Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 06:33:23 +0200 Subject: [PATCH 18/42] refactor(framework): trim cross-skill chatter in plan, implement, sdlc Keep each skill on its own job. 01-plan description cut to two lines (drop the internal gather/explore/wireframe process and a redundant redirect). 02-implement execute drops the leftover spawn-meta and defers replanning to "the caller", not "the orchestrator". The SDLC 03-implement stops restating the spawn/isolation discipline that already lives in its Orchestration rule. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 2 +- plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md | 2 +- plugins/aidd-dev/skills/01-plan/SKILL.md | 2 +- plugins/aidd-dev/skills/02-implement/actions/02-execute.md | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index d47c9c41..84cac924 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -64,7 +64,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [mermaid-conventions.md](skills/01-plan/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` | | `references` | [plan-status.md](skills/01-plan/references/plan-status.md) | `Plan lifecycle status field - values, meaning, who writes each, and when.` | | `references` | [wireframe-conventions.md](skills/01-plan/references/wireframe-conventions.md) | - | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan: gather the source, explore the codebase, optionally wireframe a screen, then plan. Use when the user wants to plan a feature, turn a ticket or requirements into a phased plan, or wireframe a screen before building. Do NOT use to write code (use 02-implement), review a diff (use 05-review), or audit code (use 04-audit).` | +| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code (02-implement) or review a diff (05-review).` | #### `skills/02-implement` diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index c4968afa..41c686c8 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -12,7 +12,7 @@ The plan reaches `status: implemented`, every phase `done`, validation green. Or ## Process -1. **Implement.** Spawn the `executor` agent and brief it to run the `aidd-dev:02-implement` recipe on `plan_path`. The agent branches, codes every phase, commits the code and the status transitions in its own context, and validates. The conductor never codes; the agent is the isolation, and the recipe inside it never spawns again. +1. **Implement.** Spawn the `executor` agent and brief it to run the `aidd-dev:02-implement` recipe on `plan_path`. The agent branches, codes every phase, commits the code and the status transitions, and validates. 2. **Iterate.** When the step runs after an `iterate` verdict, spawn the `executor` again and hand it the findings as a fix list. It codes the fixes against the current diff, then asserts and validates them before returning, exactly as the recipe gates a phase: a fix is finished only when it passes. Do not edit the plan or its phases: the loop fixes what was implemented, not the plan. 3. **Resolve.** Read the plan's final `status`. - `implemented`: the step is done. diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index ba696e19..a6eb4fb6 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,6 +1,6 @@ --- name: 01-plan -description: Turn a request, ticket, or file into a phased implementation plan: gather the source, explore the codebase, optionally wireframe a screen, then plan. Use when the user wants to plan a feature, turn a ticket or requirements into a phased plan, or wireframe a screen before building. Do NOT use to write code (use 02-implement), review a diff (use 05-review), or audit code (use 04-audit). +description: Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code (02-implement) or review a diff (05-review). argument-hint: gather | explore | wireframe | 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 52fb9a15..c32d305b 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -13,10 +13,10 @@ Every phase coded, asserted, and its frontmatter marked `status: done`, with the ## 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. -2. **Code.** Build the phase scope against its acceptance criteria. This recipe runs in the caller's context and never spawns an agent. +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. Only once it passes, set `status: done` and commit the phase as one unit, its code and its status together, via the `commit` skill. 4. **Blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. -5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch, trivial or substantive, stop and report `replan needed: ` to the caller. Replanning is the orchestrator's job, not this recipe's. +5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch, trivial or substantive, stop and report `replan needed: ` to the caller. Replanning is the caller's job, not this recipe's. ## Test From 0c3580dd476b04f1cb8daf54cff654d14b13cb95 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 06:35:27 +0200 Subject: [PATCH 19/42] refactor(framework): drop sibling-skill names from descriptions and refs Descriptions name no other skill, not even in the Do-NOT (just "write code", "review a diff"). The plan-status reference describes the lifecycle by step ("the implement step", "the review step") rather than by skill or layer name, and 02-implement's README drops the leftover spawn-history. SKILL routers and actions are now clean of cross-skill mentions, except the SDLC's own delegations. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 6 +++--- plugins/aidd-dev/skills/01-plan/SKILL.md | 2 +- .../skills/01-plan/references/plan-status.md | 12 ++++++------ plugins/aidd-dev/skills/02-implement/README.md | 5 ++--- plugins/aidd-dev/skills/02-implement/SKILL.md | 2 +- plugins/aidd-dev/skills/05-review/SKILL.md | 2 +- 6 files changed, 14 insertions(+), 15 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 84cac924..d66ab9bd 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -64,7 +64,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [mermaid-conventions.md](skills/01-plan/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` | | `references` | [plan-status.md](skills/01-plan/references/plan-status.md) | `Plan lifecycle status field - values, meaning, who writes each, and when.` | | `references` | [wireframe-conventions.md](skills/01-plan/references/wireframe-conventions.md) | - | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code (02-implement) or review a diff (05-review).` | +| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code or review a diff.` | #### `skills/02-implement` @@ -75,7 +75,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-finalize.md](skills/02-implement/actions/03-finalize.md) | - | | `-` | [README.md](skills/02-implement/README.md) | - | | `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` | -| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan (01-plan), review a diff (05-review), or fix a bug with no plan (08-debug).` | +| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff.` | #### `skills/03-assert` @@ -113,7 +113,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [review-template.md](skills/05-review/assets/review-template.md) | `One review report for a diff, all three axes in one file` | | `-` | [README.md](skills/05-review/README.md) | - | | `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff along three axes, code quality, behavior versus the plan, and relevancy, into one report with a verdict. Use to review changes before they ship. Do NOT use to fix the findings or to audit a whole codebase (use 04-audit).` | +| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff along three axes, code quality, behavior versus the plan, and relevancy, into one report with a verdict. Use to review changes before they ship. Do NOT use to fix the findings or to audit a whole codebase.` | #### `skills/06-test` diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index a6eb4fb6..1633df04 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,6 +1,6 @@ --- name: 01-plan -description: Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code (02-implement) or review a diff (05-review). +description: Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code or review a diff. argument-hint: gather | explore | wireframe | plan --- diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-status.md b/plugins/aidd-dev/skills/01-plan/references/plan-status.md index 7fa23e57..51e98bf1 100644 --- a/plugins/aidd-dev/skills/01-plan/references/plan-status.md +++ b/plugins/aidd-dev/skills/01-plan/references/plan-status.md @@ -9,15 +9,15 @@ The plan's `status` frontmatter field tracks its lifecycle for kanban views. The | status | meaning | written by | when | | ------------- | ----------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------- | -| `pending` | created, not started | `01-plan` | at plan creation | -| `in-progress` | implementation started | implement layer (SDLC `03-implement`; standalone `02-implement`) | when implementation starts | -| `implemented` | implemented, not yet reviewed | implement layer | all phases complete / all acceptance criteria ticked | -| `reviewed` | reviewed and approved | review layer (SDLC `04-review`) | the review passes (approved) | -| `blocked` | cannot proceed; needs a human | implement layer | a blocking condition holds (see the implement skill's blocked reference) | +| `pending` | created, not started | plan creation | at plan creation | +| `in-progress` | implementation started | the implement step | when implementation starts | +| `implemented` | implemented, not yet reviewed | the implement step | all phases complete / all acceptance criteria ticked | +| `reviewed` | reviewed and approved | the review step | the review passes (approved) | +| `blocked` | cannot proceed; needs a human | the implement step | a blocking condition holds | ## Rules - Linear: `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state. - Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan. - `implemented` ≠ reviewed. Only the review layer sets `reviewed`. -- The `checker` and `executor` agents never write `status`; only plan creation (`01-plan`) and the orchestration layers do. +- Workers never write `status`; only plan creation and the orchestration layers do. diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md index e261a0d0..7184125d 100644 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ b/plugins/aidd-dev/skills/02-implement/README.md @@ -2,7 +2,7 @@ # 02 - implement -Executes an existing implementation plan phase by phase, as a recipe that runs in the caller's context and never spawns an agent, iterating until every acceptance criterion is satisfied. Tracks status in the plan and phase frontmatter as it goes. +Executes an existing implementation plan phase by phase, iterating until every acceptance criterion is satisfied. Tracks status in the plan and phase frontmatter as it goes. ## When to use @@ -27,7 +27,7 @@ Pass the plan path or content as `$ARGUMENTS`. The skill runs three actions in o 2. **execute**: loops the plan's phases: per phase it sets `status: in-progress` as a runtime marker, codes the phase, asserts it clean, then commits the phase and sets `status: done`; stops at `status: blocked` on a human-only condition. 3. **finalize**: runs validation, then marks the plan `status: implemented` once every phase is done. -**Commits**: the recipe runs in one context, so it commits the code and its status together, one commit per phase, plus a final `implemented` commit. The `in-progress` marks are runtime-only. One context owning both code and status removes the cross-context revert the old skill-spawns-agent split had to guard against. +**Commits**: code and status are committed together, one commit per phase, plus a final `implemented` commit. The `in-progress` marks are runtime-only, so the tree is never left dirty at a phase boundary. ## Outputs @@ -38,7 +38,6 @@ Pass the plan path or content as `$ARGUMENTS`. The skill runs three actions in o ## Prerequisites - A plan file with phases and acceptance criteria, from `01-plan`. -- A runner for the recipe: a user, or the `executor` agent the SDLC spawns. - Project conventions honoured by whoever runs the recipe. ## Technical details diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index 2b3e63da..65dfdd57 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -1,6 +1,6 @@ --- name: 02-implement -description: Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan (01-plan), review a diff (05-review), or fix a bug with no plan (08-debug). +description: Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff. argument-hint: prepare | execute | finalize --- diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 4a11e0b5..936b9001 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,6 +1,6 @@ --- name: 05-review -description: Read-only review of a diff along three axes, code quality, behavior versus the plan, and relevancy, into one report with a verdict. Use to review changes before they ship. Do NOT use to fix the findings or to audit a whole codebase (use 04-audit). +description: Read-only review of a diff along three axes, code quality, behavior versus the plan, and relevancy, into one report with a verdict. Use to review changes before they ship. Do NOT use to fix the findings or to audit a whole codebase. argument-hint: review-code | review-functional | review-relevancy model: opus --- From 1f4890b03729ff4b81ef6ea80a14259de4b43363 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 06:52:19 +0200 Subject: [PATCH 20/42] refactor(framework): define the review output when there is no plan review.md follows the plan/spec/brainstorm convention: one file in a feature folder. Spell the path, and handle the no-plan case: reuse the reviewed work's folder when it has one, otherwise resolve one from the change (branch or slug). The review never creates a plan. The functional axis asks for the criteria and marks itself "Not run" when none are available, so an unattended run never hangs. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/05-review/SKILL.md | 4 ++-- .../aidd-dev/skills/05-review/actions/02-review-functional.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 936b9001..a67e161c 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -17,12 +17,12 @@ Read-only review of a diff along three axes, code quality, feature behavior, and | 02 | `review-functional` | The diff against the plan's acceptance criteria | | 03 | `review-relevancy` | Does the change belong: fit to the need, rule conformance, no rot | -Run all three by default, composing one report. Run a single axis only when the caller names it; if it is unclear whether they want all or one, ask. Files: `@actions/01-review-code.md` ... `@actions/03-review-relevancy.md`. +Run all three by default, composing one report. Run a single axis only when the caller names it; if it is unclear whether they want all or one, ask. ## Transversal rules - Read-only: surface each finding with its fix described, never patch. -- Output: one `review.md` in the reviewed work's feature folder, beside `plan.md`, from `@assets/review-template.md`. Each axis fills its section; an axis not run is marked "Not run". +- Output: one `review.md` in a feature folder (`aidd_docs/tasks//_/`), from `@assets/review-template.md`. Reuse the reviewed work's folder when it has one (beside `plan.md`); otherwise resolve a new one from the change, by branch or a derived slug. Never create a plan. Each axis fills its section; an axis not run is marked "Not run". - Verdict: one overall verdict, the strictest across the axes run, per `@references/review-rubric.md`. ## References diff --git a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md index 0be199c9..1495f071 100644 --- a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md +++ b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md @@ -12,7 +12,7 @@ The `Functional` section of the feature folder's `review.md`: one row per accept ## Process -1. **Read.** Take the plan from `$ARGUMENTS`; if absent, ask the user for the acceptance criteria. Static review only, no app execution or browser. +1. **Read.** Take the plan from `$ARGUMENTS`; if absent, ask for the acceptance criteria, and mark this axis "Not run" when none are available. Static review only, no app execution or browser. 2. **Trace.** Fetch the diff, then trace each acceptance criterion to it, one matrix row per criterion: met, partial, or unmet, with evidence or the gap. 3. **Gaps.** List missing behaviors (criteria with no trace), unplanned behaviors (diff changes tracing to no criterion), and flow or edge-case gaps. An empty list reads "none", never omitted. 4. **Record.** Write the matrix and the gaps into the `Functional` section of `review.md`, each with the missing or broken behavior named. From 7e5168349740bcc2acaf8f436111c15c960bad83 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 06:58:46 +0200 Subject: [PATCH 21/42] refactor(framework): define review re-run as overwrite review.md is a snapshot of the current diff, not a history: re-running the review overwrites the single file rather than appending or versioning. This is what the iterate loop needs, a later review of the same work replaces the earlier one. Verified: two runs leave one review.md, refreshed. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/05-review/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index a67e161c..94798ee3 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -23,6 +23,7 @@ Run all three by default, composing one report. Run a single axis only when the - Read-only: surface each finding with its fix described, never patch. - Output: one `review.md` in a feature folder (`aidd_docs/tasks//_/`), from `@assets/review-template.md`. Reuse the reviewed work's folder when it has one (beside `plan.md`); otherwise resolve a new one from the change, by branch or a derived slug. Never create a plan. Each axis fills its section; an axis not run is marked "Not run". +- Re-run: overwrite `review.md` with the current review. It is a snapshot of the current diff, not a history; a later review of the same work replaces the earlier one. - Verdict: one overall verdict, the strictest across the axes run, per `@references/review-rubric.md`. ## References From 17466f058e14ffebd1bc5030a3d69e92c0f43fa7 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 07:03:11 +0200 Subject: [PATCH 22/42] fix(framework): stop the review template frontmatter leaking into review.md The template carried name/description/argument-hint frontmatter that copied verbatim into the output report. Replace it with an HTML authoring comment so review.md starts at its own H1. Verified: output begins with "# Review:". Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 2 +- plugins/aidd-dev/skills/05-review/assets/review-template.md | 6 +----- 2 files changed, 2 insertions(+), 6 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index d66ab9bd..033d69ef 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -110,7 +110,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | | `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | | `actions` | [03-review-relevancy.md](skills/05-review/actions/03-review-relevancy.md) | - | -| `assets` | [review-template.md](skills/05-review/assets/review-template.md) | `One review report for a diff, all three axes in one file` | +| `assets` | [review-template.md](skills/05-review/assets/review-template.md) | - | | `-` | [README.md](skills/05-review/README.md) | - | | `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | | `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff along three axes, code quality, behavior versus the plan, and relevancy, into one report with a verdict. Use to review changes before they ship. Do NOT use to fix the findings or to audit a whole codebase.` | diff --git a/plugins/aidd-dev/skills/05-review/assets/review-template.md b/plugins/aidd-dev/skills/05-review/assets/review-template.md index 5775cfa5..8c6df3ad 100644 --- a/plugins/aidd-dev/skills/05-review/assets/review-template.md +++ b/plugins/aidd-dev/skills/05-review/assets/review-template.md @@ -1,8 +1,4 @@ ---- -name: review -description: One review report for a diff, all three axes in one file -argument-hint: N/A ---- + # Review: {{feature}} From f071908464bf0b8c6db5213e0c123bbdfa7fda5d Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 07:21:22 +0200 Subject: [PATCH 23/42] refactor(framework): align the assert skill to the norm, gate framing Bring 03-assert to the same standard as review and implement. - Actions rewritten to the anatomy: prose singular Input/Output, no frozen YAML. - Routing harmonized: run every applicable facet by default (coding always, frontend when a UI and URL exist, architecture only when asked), or one when named, no forced question, so the auto path never blocks. - Framed as a gate: it returns a pass or fail verdict, not a stored report; coding and frontend fix until they pass, architecture only reports. - Fix the task-template frontmatter leak (HTML comment, not YAML) and the stray brace, like the review template. - Short description, no sibling-skill names. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 4 +- plugins/aidd-dev/skills/03-assert/README.md | 24 +++++----- plugins/aidd-dev/skills/03-assert/SKILL.md | 34 ++++++------- .../skills/03-assert/actions/01-assert.md | 31 +++++------- .../actions/02-assert-architecture.md | 48 +++++-------------- .../03-assert/actions/03-assert-frontend.md | 41 +++++----------- .../skills/03-assert/assets/task-template.md | 8 +--- 7 files changed, 66 insertions(+), 124 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 033d69ef..d1f37b39 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -84,9 +84,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-assert.md](skills/03-assert/actions/01-assert.md) | - | | `actions` | [02-assert-architecture.md](skills/03-assert/actions/02-assert-architecture.md) | - | | `actions` | [03-assert-frontend.md](skills/03-assert/actions/03-assert-frontend.md) | - | -| `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | +| `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | - | | `-` | [README.md](skills/03-assert/README.md) | - | -| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert features work as intended - general assertions, architecture conformance, and frontend UI validation.` | +| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert a feature works as intended by iterating the project's coding assertions until they pass, with optional architecture-conformance and running-frontend facets. Use to validate that an implementation behaves correctly. Do NOT use to review code quality or to write new tests.` | #### `skills/04-audit` diff --git a/plugins/aidd-dev/skills/03-assert/README.md b/plugins/aidd-dev/skills/03-assert/README.md index c0a9c069..e950a927 100644 --- a/plugins/aidd-dev/skills/03-assert/README.md +++ b/plugins/aidd-dev/skills/03-assert/README.md @@ -2,9 +2,9 @@ # 03 - assert -Validates implementations through iterative assertion loops. Covers general -feature assertions, architecture conformance (ADRs, diagrams, project -structure), and browser-based frontend UI checks. +A gate that validates a feature works: it iterates the project's coding +assertions until they pass, with optional architecture-conformance and +running-frontend facets. Returns a pass or fail verdict. ## When to use @@ -30,21 +30,19 @@ structure), and browser-based frontend UI checks. Use skill aidd-dev:03-assert ``` -The skill exposes 3 actions: +The skill exposes 3 facets, run together when applicable or one when named: -1. `assert` - general assertion loop against an acceptance criterion. -2. `assert-architecture` - verify code matches architecture diagrams, - ADRs, and the project's documented structure. +1. `assert` - the coding-assertion loop; always applies. +2. `assert-architecture` - report where code breaks the documented + architecture (ADRs, diagrams, structure); report only, opt-in. 3. `assert-frontend` - drive a browser to confirm a frontend feature - behaves as intended. + behaves as intended; needs a running URL. ## Outputs -- A pass / fail verdict per assertion, with the failing item identified. -- Recorded findings when an assertion fails (file, line, expected vs - observed). -- Browser session artifacts (screenshots, console output) for the - frontend variant. +- A pass or fail verdict on the feature (this is a gate, not a stored report). +- The fixes applied by the coding and frontend facets. +- The conformance violations from the architecture facet. ## Prerequisites diff --git a/plugins/aidd-dev/skills/03-assert/SKILL.md b/plugins/aidd-dev/skills/03-assert/SKILL.md index 6594114d..c662b4cb 100644 --- a/plugins/aidd-dev/skills/03-assert/SKILL.md +++ b/plugins/aidd-dev/skills/03-assert/SKILL.md @@ -1,34 +1,30 @@ --- name: 03-assert -description: Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. +description: Assert a feature works as intended by iterating the project's coding assertions until they pass, with optional architecture-conformance and running-frontend facets. Use to validate that an implementation behaves correctly. Do NOT use to review code quality or to write new tests. argument-hint: assert | assert-architecture | assert-frontend model: sonnet --- # Skill: assert -Validates correctness of implementations through iterative assertion loops, architecture checks, and browser-based frontend verification. +Validate that a feature works: run the project's assertions, iterating and fixing until they pass. -## Available actions - -| # | Action | When to use | -| --- | --------------------- | ---------------------------------------------------------------------------- | -| 01 | `assert` | Iterate until a feature works by running the project's coding assertions | -| 02 | `assert-architecture` | Verify the codebase conforms to documented architecture (C4, ADRs, tree) | -| 03 | `assert-frontend` | Iterate until a frontend feature works by inspecting the running UI | +## Actions -## Routing (run first) +| # | Action | Facet | +| --- | --------------------- | ----------------------------------------------------------- | +| 01 | `assert` | Run the project's coding assertions, fixing until they pass | +| 02 | `assert-architecture` | Report where the code breaks the documented architecture | +| 03 | `assert-frontend` | Inspect the running UI, fixing until the behavior is right | -These actions are complementary facets, not mutually exclusive. This skill is run-one-OR-run-all: +Run every applicable facet by default, or one when named. Coding (`01`) always applies; add `03` when the feature has a UI and a running URL; run `02` only when architecture conformance is asked for. Skip a facet whose precondition is absent, with a noted reason. Ask only when the intent is genuinely ambiguous. -- The user named a facet ("assert the frontend", "check architecture conformance") -> run that ONE action. -- The user asked for an unscoped assertion ("assert this works", "make the feature pass") -> ask ONE question: "Assert everything applicable, or a specific facet (coding / architecture / frontend)?" Then run all applicable, or the chosen one. -- Never silently default to action 01. Never run a blind all without offering the choice first. +## Transversal rules -When running all applicable: `01-assert` is the baseline (project coding assertions); add `03-assert-frontend` when the feature has a UI and a running frontend URL; add `02-assert-architecture` when architecture conformance is in scope. A facet whose precondition is absent (e.g. no running URL) is skipped with a noted reason, never forced. Run the selected actions in order (01, then 03, then 02). Read and follow each selected action file. +- Gate: it returns a pass or fail verdict on the feature. +- Fix loop: the coding and frontend facets fix and re-run until they pass. The architecture facet only reports, never fixes. +- Stop only when every selected assertion passes a final clean sweep. -## Actions +## Assets -- `@actions/01-assert.md` -- `@actions/02-assert-architecture.md` -- `@actions/03-assert-frontend.md` +- `assets/task-template.md`: the tracking file the frontend facet fills across its fix loop. diff --git a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md index cea380da..ab9a72d0 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md +++ b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md @@ -1,32 +1,23 @@ # 01 - Assert -Iterate until a feature works as intended by running the project's coding assertions and fixing every failure. +Iterate the project's coding assertions until the feature passes every one, fixing each failure. -## Inputs +## Input -```yaml -feature: -``` +The feature to assert, named or described, from `$ARGUMENTS` or the context. -## Outputs +## Output -```yaml -assertions_total: -assertions_passing: -iterations: -fixes_applied: - - { file: , change: } -``` +A pass or fail verdict: every applicable assertion passing in a final clean sweep, with the fixes applied listed. ## Process -1. **Enumerate assertions.** From the current context (project conventions and coding-assertions memory), list the assertions that apply to the feature. -2. **Iterate per assertion.** For each one: - - Fix any issues preventing it from passing. - - Re-run the assertion to confirm it passes. -3. **Full re-check.** Once every assertion has passed at least once, re-run all of them in one sweep to confirm none regressed. -4. **Boundary.** Do not stop until every assertion passes in the final sweep. +1. **Enumerate.** From the project conventions and the coding-assertions memory, list the assertions that apply to the feature. +2. **Iterate.** For each assertion, fix what blocks it, then re-run it until it passes. +3. **Sweep.** Once each has passed at least once, re-run them all in one pass to confirm none regressed. +4. **Boundary.** Do not stop until every assertion passes the final sweep. ## Test -The final sweep reports `assertions_passing == assertions_total`; the recorded `fixes_applied` list cites real diffs (no empty or placeholder entries when fixes were claimed). +- The final sweep passes every applicable assertion. +- The fixes listed cite real diffs, with no placeholder entries. diff --git a/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md b/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md index 8125bcd1..1500fa60 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md +++ b/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md @@ -1,48 +1,24 @@ # 02 - Assert Architecture -Verify that the codebase (or a specific scope) conforms to the documented architecture: C4 diagrams, ADRs, and project tree structure. +Report where the codebase breaks the documented architecture: C4 diagrams, ADRs, and the project tree. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire project -``` +The scope to check, a module, service, or layer, from `$ARGUMENTS`; defaults to the whole project. -## Outputs +## Output -```yaml -report: - macro: - - { severity: critical|warning, file: , constraint: , fix: } - micro: - - { severity: critical|warning, file: , constraint: , fix: } -totals: - violations_total: - critical: - warning: -``` +A conformance report listing each violation, grouped macro and micro, with severity, file, the constraint broken, and a one-line fix. Report only; it never fixes. ## Process -1. **Load architecture context.** - - Remember the architecture diagrams from `aidd_docs/memory/architecture.md`. - - Read micro diagrams from `aidd_docs/memory/internal/` when the scope targets a specific module. - - Read ADRs from `aidd_docs/internal/decisions/`. - - Extract the expected project tree structure from the diagrams. -2. **Verify macro architecture (service boundaries).** - - Compare actual code structure against the documented tree. - - Flag files outside expected boundaries. - - Flag direct imports between independent services. -3. **Verify micro architecture (internal layers).** For each module in scope: - - Check that import directions match layer constraints. - - Confirm the domain layer has zero external imports. - - Confirm the application layer depends only on the domain via ports. - - Detect circular dependencies between modules. - - Verify the expected patterns (use cases have ports, adapters implement interfaces). -4. **Build the violation report.** Each entry carries severity (`critical | warning`), file path, the constraint violated, and a one-line suggested fix. Group entries macro vs micro. -5. **Boundary.** Do not fix violations - only report them. If no scope is provided, check the entire project. -6. **Summarize.** Total violations, critical count, recommended next actions. +1. **Load.** Read the architecture sources: the architecture memory, the micro diagrams for an in-scope module, and the decision records. Extract the expected project tree. +2. **Macro.** Compare the code structure against the documented tree. Flag files outside their boundary and direct imports between independent services. +3. **Micro.** For each in-scope module, check import directions against the layer constraints. The domain layer imports nothing external. The application layer reaches the domain only through ports. No circular dependencies. Adapters implement their interfaces. +4. **Report.** One entry per violation, grouped macro and micro, each with severity (`critical` or `warning`), file, constraint, and a one-line fix. Never fix, only report. +5. **Summarize.** The total violations, the critical count, and the recommended next actions. ## Test -If conformity holds: `violations_total == 0` and the report explicitly states "no violations" in both macro and micro sections. If violations exist: every report entry has a real file path that exists on disk, a referenced constraint that appears in one of the loaded architecture sources, and a non-empty `fix` field. +- On conformance, the report states "no violations" in both the macro and micro sections. +- On violations, every entry has a real file path, a constraint drawn from a loaded architecture source, and a non-empty fix. diff --git a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md index 92ae09f4..50868933 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md +++ b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md @@ -1,40 +1,25 @@ # 03 - Assert Frontend -Iterate until a frontend feature works as intended by inspecting the running UI, mapping the behavior to the code, and tracking attempts in a task template. +Iterate until a frontend feature works as intended by inspecting the running UI, mapping behavior to code, and tracking attempts. -## Inputs +## Input -```yaml -expected_behavior: -url: # required; the frontend must already be running -``` +The expected behavior, from `$ARGUMENTS`, and the entry URL of the already-running frontend. -## Outputs +## Output -```yaml -task_template_path: -iterations: -fixed: true|false -report: - - { iteration: , hypothesis: , fix_attempted: , validated: pass|fail } -``` +A pass or fail verdict, with the per-iteration attempts (hypothesis, fix, result) recorded in the tracking file. ## Process -Iterate over the steps below until the feature works as intended. - -1. **Parse the request.** Extract expected requirements (visual, functional, technical) from `expected_behavior`. Summarize and list action paths (e.g. user clicks button -> calls function in file1 -> updates state in file2). -2. **Inspect the running app.** Open the URL via the configured browsing tool. Inspect the page visually and technically. Take screenshots to confirm the issue. -3. **Locate the code.** Explore the codebase to find the files and snippets related to the issue. -4. **Fill the tracking template** from `@../assets/task-template.md`. List the three best potential causes with a short description and confidence level. -5. **Fix-loop.** - - Take the first potential cause. - - Apply a candidate fix. - - Validate against the expected behavior. - - If not fixed, mark the cause and move to the next. - - When the three causes are exhausted, re-evaluate, add three new causes to the template, and repeat from step 5. -6. **Boundaries.** Assume all servers are already running. Minor visual discrepancies (1-2 px differences, slight color variations) are acceptable unless explicitly specified in the initial request. Screenshots MUST be used to validate UI changes. +1. **Parse.** Extract the visual, functional, and technical requirements from the expected behavior. Trace the action paths, for example a click calls a function in one file that updates state in another. +2. **Inspect.** Open the URL in the configured browsing tool. Inspect the page visually and technically, capturing a screenshot of the issue. +3. **Locate.** Explore the codebase for the files behind the issue. +4. **Track.** Fill the tracking file from `@../assets/task-template.md` with the three best candidate causes, each with a short description and a confidence level. +5. **Fix loop.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. +6. **Boundary.** Assume the servers are running. Accept minor visual differences (1 to 2 px, slight color) unless the request specifies otherwise. Confirm every UI change with a screenshot. ## Test -The task template file exists and is updated for every iteration; the final entry in `report` has `validated: pass`; the running URL renders the expected behavior, confirmed by a screenshot recorded after the final iteration. +- The tracking file updates on every iteration. +- The final recorded attempt validates as a pass, confirmed by a screenshot taken after it. diff --git a/plugins/aidd-dev/skills/03-assert/assets/task-template.md b/plugins/aidd-dev/skills/03-assert/assets/task-template.md index cdc9e1db..dc2beec2 100644 --- a/plugins/aidd-dev/skills/03-assert/assets/task-template.md +++ b/plugins/aidd-dev/skills/03-assert/assets/task-template.md @@ -1,15 +1,11 @@ ---- -name: task -description: Task tracking system to ensure all tasks are categorized and addressed ---- + # Task [] {{Full description}} -## Main step 1} +## Main step 1 - [ ] {Task 1} - [ ] {Task 2} - [ ] {Task 3} -- ... From 9ca84e61443cf0e503916cdb287a82d3c1f52eab Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 10:00:36 +0200 Subject: [PATCH 24/42] refactor(framework): assert validates the work, not just a feature The skill was framed around a "feature", too narrow: assert is the gate the executor runs to validate whatever it just built (a phase, a change), not only a feature. Generalize the unit to "the work" across the skill, actions, and README. No behavior change. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 2 +- plugins/aidd-dev/skills/03-assert/README.md | 10 +++++----- plugins/aidd-dev/skills/03-assert/SKILL.md | 8 ++++---- plugins/aidd-dev/skills/03-assert/actions/01-assert.md | 6 +++--- .../skills/03-assert/actions/03-assert-frontend.md | 2 +- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index d1f37b39..54ee7513 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -86,7 +86,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-assert-frontend.md](skills/03-assert/actions/03-assert-frontend.md) | - | | `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | - | | `-` | [README.md](skills/03-assert/README.md) | - | -| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert a feature works as intended by iterating the project's coding assertions until they pass, with optional architecture-conformance and running-frontend facets. Use to validate that an implementation behaves correctly. Do NOT use to review code quality or to write new tests.` | +| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert that the work behaves as intended by iterating the project's coding assertions until they pass, with optional architecture-conformance and running-frontend facets. Use to validate an implementation before moving on. Do NOT use to review code quality or to write new tests.` | #### `skills/04-audit` diff --git a/plugins/aidd-dev/skills/03-assert/README.md b/plugins/aidd-dev/skills/03-assert/README.md index e950a927..27d93f16 100644 --- a/plugins/aidd-dev/skills/03-assert/README.md +++ b/plugins/aidd-dev/skills/03-assert/README.md @@ -2,13 +2,13 @@ # 03 - assert -A gate that validates a feature works: it iterates the project's coding -assertions until they pass, with optional architecture-conformance and +A gate that validates the work behaves as intended: it iterates the project's +coding assertions until they pass, with optional architecture-conformance and running-frontend facets. Returns a pass or fail verdict. ## When to use -- A feature is implemented and you need to assert it behaves as intended +- Work is implemented and you need to assert it behaves as intended before merging or shipping. - You need to verify code conforms to documented architecture (ADRs, diagrams, structure). @@ -35,12 +35,12 @@ The skill exposes 3 facets, run together when applicable or one when named: 1. `assert` - the coding-assertion loop; always applies. 2. `assert-architecture` - report where code breaks the documented architecture (ADRs, diagrams, structure); report only, opt-in. -3. `assert-frontend` - drive a browser to confirm a frontend feature +3. `assert-frontend` - drive a browser to confirm the frontend behaves as intended; needs a running URL. ## Outputs -- A pass or fail verdict on the feature (this is a gate, not a stored report). +- A pass or fail verdict on the work (this is a gate, not a stored report). - The fixes applied by the coding and frontend facets. - The conformance violations from the architecture facet. diff --git a/plugins/aidd-dev/skills/03-assert/SKILL.md b/plugins/aidd-dev/skills/03-assert/SKILL.md index c662b4cb..5c9841ad 100644 --- a/plugins/aidd-dev/skills/03-assert/SKILL.md +++ b/plugins/aidd-dev/skills/03-assert/SKILL.md @@ -1,13 +1,13 @@ --- name: 03-assert -description: Assert a feature works as intended by iterating the project's coding assertions until they pass, with optional architecture-conformance and running-frontend facets. Use to validate that an implementation behaves correctly. Do NOT use to review code quality or to write new tests. +description: Assert that the work behaves as intended by iterating the project's coding assertions until they pass, with optional architecture-conformance and running-frontend facets. Use to validate an implementation before moving on. Do NOT use to review code quality or to write new tests. argument-hint: assert | assert-architecture | assert-frontend model: sonnet --- # Skill: assert -Validate that a feature works: run the project's assertions, iterating and fixing until they pass. +Validate that the work behaves as intended: run the project's assertions, iterating and fixing until they pass. ## Actions @@ -17,11 +17,11 @@ Validate that a feature works: run the project's assertions, iterating and fixin | 02 | `assert-architecture` | Report where the code breaks the documented architecture | | 03 | `assert-frontend` | Inspect the running UI, fixing until the behavior is right | -Run every applicable facet by default, or one when named. Coding (`01`) always applies; add `03` when the feature has a UI and a running URL; run `02` only when architecture conformance is asked for. Skip a facet whose precondition is absent, with a noted reason. Ask only when the intent is genuinely ambiguous. +Run every applicable facet by default, or one when named. Coding (`01`) always applies; add `03` when the work has a UI and a running URL; run `02` only when architecture conformance is asked for. Skip a facet whose precondition is absent, with a noted reason. Ask only when the intent is genuinely ambiguous. ## Transversal rules -- Gate: it returns a pass or fail verdict on the feature. +- Gate: it returns a pass or fail verdict on the work. - Fix loop: the coding and frontend facets fix and re-run until they pass. The architecture facet only reports, never fixes. - Stop only when every selected assertion passes a final clean sweep. diff --git a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md index ab9a72d0..b42019c6 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md +++ b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md @@ -1,10 +1,10 @@ # 01 - Assert -Iterate the project's coding assertions until the feature passes every one, fixing each failure. +Iterate the project's coding assertions until the work passes every one, fixing each failure. ## Input -The feature to assert, named or described, from `$ARGUMENTS` or the context. +The work to assert, named or described, from `$ARGUMENTS` or the context. ## Output @@ -12,7 +12,7 @@ A pass or fail verdict: every applicable assertion passing in a final clean swee ## Process -1. **Enumerate.** From the project conventions and the coding-assertions memory, list the assertions that apply to the feature. +1. **Enumerate.** From the project conventions and the coding-assertions memory, list the assertions that apply to the work. 2. **Iterate.** For each assertion, fix what blocks it, then re-run it until it passes. 3. **Sweep.** Once each has passed at least once, re-run them all in one pass to confirm none regressed. 4. **Boundary.** Do not stop until every assertion passes the final sweep. diff --git a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md index 50868933..67ae6756 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md +++ b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md @@ -1,6 +1,6 @@ # 03 - Assert Frontend -Iterate until a frontend feature works as intended by inspecting the running UI, mapping behavior to code, and tracking attempts. +Iterate until the frontend behaves as intended by inspecting the running UI, mapping behavior to code, and tracking attempts. ## Input From 203e97b8e4cb393d00fa72c99afb72bd8bbd7d3f Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 10:14:08 +0200 Subject: [PATCH 25/42] refactor(framework): assert-frontend resolves its own URL The facet required the running frontend URL as a handed-in input, so in an unattended run nobody supplied it and the facet always skipped. Make it resolve the URL itself: use a given one, otherwise discover the running dev server (its start script, the framework default port, a listening port), confirm it responds, and only skip when no frontend is actually running. It then navigates to the screen the expected behavior targets. Never starts a server. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/03-assert/README.md | 2 +- plugins/aidd-dev/skills/03-assert/SKILL.md | 2 +- .../03-assert/actions/03-assert-frontend.md | 15 ++++++++------- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/plugins/aidd-dev/skills/03-assert/README.md b/plugins/aidd-dev/skills/03-assert/README.md index 27d93f16..2d79a27d 100644 --- a/plugins/aidd-dev/skills/03-assert/README.md +++ b/plugins/aidd-dev/skills/03-assert/README.md @@ -36,7 +36,7 @@ The skill exposes 3 facets, run together when applicable or one when named: 2. `assert-architecture` - report where code breaks the documented architecture (ADRs, diagrams, structure); report only, opt-in. 3. `assert-frontend` - drive a browser to confirm the frontend - behaves as intended; needs a running URL. + behaves as intended; needs a running frontend (it resolves the URL). ## Outputs diff --git a/plugins/aidd-dev/skills/03-assert/SKILL.md b/plugins/aidd-dev/skills/03-assert/SKILL.md index 5c9841ad..f341ea0c 100644 --- a/plugins/aidd-dev/skills/03-assert/SKILL.md +++ b/plugins/aidd-dev/skills/03-assert/SKILL.md @@ -17,7 +17,7 @@ Validate that the work behaves as intended: run the project's assertions, iterat | 02 | `assert-architecture` | Report where the code breaks the documented architecture | | 03 | `assert-frontend` | Inspect the running UI, fixing until the behavior is right | -Run every applicable facet by default, or one when named. Coding (`01`) always applies; add `03` when the work has a UI and a running URL; run `02` only when architecture conformance is asked for. Skip a facet whose precondition is absent, with a noted reason. Ask only when the intent is genuinely ambiguous. +Run every applicable facet by default, or one when named. Coding (`01`) always applies; add `03` when the work has a UI and a frontend is running, the facet resolving the URL itself; run `02` only when architecture conformance is asked for. Skip a facet whose precondition is absent, with a noted reason. Ask only when the intent is genuinely ambiguous. ## Transversal rules diff --git a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md index 67ae6756..83aac152 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md +++ b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md @@ -4,7 +4,7 @@ Iterate until the frontend behaves as intended by inspecting the running UI, map ## Input -The expected behavior, from `$ARGUMENTS`, and the entry URL of the already-running frontend. +The expected behavior, from `$ARGUMENTS`. The frontend's URL when the caller knows it, otherwise resolved at runtime. ## Output @@ -12,12 +12,13 @@ A pass or fail verdict, with the per-iteration attempts (hypothesis, fix, result ## Process -1. **Parse.** Extract the visual, functional, and technical requirements from the expected behavior. Trace the action paths, for example a click calls a function in one file that updates state in another. -2. **Inspect.** Open the URL in the configured browsing tool. Inspect the page visually and technically, capturing a screenshot of the issue. -3. **Locate.** Explore the codebase for the files behind the issue. -4. **Track.** Fill the tracking file from `@../assets/task-template.md` with the three best candidate causes, each with a short description and a confidence level. -5. **Fix loop.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. -6. **Boundary.** Assume the servers are running. Accept minor visual differences (1 to 2 px, slight color) unless the request specifies otherwise. Confirm every UI change with a screenshot. +1. **Resolve the URL.** Use the URL the caller gave. Otherwise discover the running frontend from the project: its dev or start script, the framework's default port, or a port already listening locally. Confirm the URL responds before going on. If no frontend is running, skip this facet with a noted reason. +2. **Parse.** Extract the visual, functional, and technical requirements from the expected behavior. Trace the action paths, for example a click calls a function in one file that updates state in another. +3. **Inspect.** Open the URL in the configured browsing tool and navigate to the screen the expected behavior targets. Inspect the page visually and technically, capturing a screenshot of the issue. +4. **Locate.** Explore the codebase for the files behind the issue. +5. **Track.** Fill the tracking file from `@../assets/task-template.md` with the three best candidate causes, each with a short description and a confidence level. +6. **Fix loop.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. +7. **Boundary.** Never start or restart a server. Accept minor visual differences (1 to 2 px, slight color) unless the request specifies otherwise. Confirm every UI change with a screenshot. ## Test From 4bfe47c28f4d1355ef1e8a17b6eee12c952fc167 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 10:22:12 +0200 Subject: [PATCH 26/42] refactor(framework): trim assert-frontend URL resolution, keep the tool agnostic The URL-discovery step over-specified the how (dev script, default port, listening port); cut it to "use the given URL or find the running frontend, confirm it responds, else skip". The browser tool stays the project's choice (documented in its browsing memory), named generically as "the project's configured browser tool", never a hardcoded one. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../aidd-dev/skills/03-assert/actions/03-assert-frontend.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md index 83aac152..80a2e02d 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md +++ b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md @@ -12,9 +12,9 @@ A pass or fail verdict, with the per-iteration attempts (hypothesis, fix, result ## Process -1. **Resolve the URL.** Use the URL the caller gave. Otherwise discover the running frontend from the project: its dev or start script, the framework's default port, or a port already listening locally. Confirm the URL responds before going on. If no frontend is running, skip this facet with a noted reason. +1. **Resolve the URL.** Use the one the caller gave, otherwise find the running frontend and confirm it responds. Skip this facet with a noted reason when none is running. 2. **Parse.** Extract the visual, functional, and technical requirements from the expected behavior. Trace the action paths, for example a click calls a function in one file that updates state in another. -3. **Inspect.** Open the URL in the configured browsing tool and navigate to the screen the expected behavior targets. Inspect the page visually and technically, capturing a screenshot of the issue. +3. **Inspect.** Open the URL with the project's configured browser tool and navigate to the screen the expected behavior targets. Inspect the page visually and technically, capturing a screenshot of the issue. 4. **Locate.** Explore the codebase for the files behind the issue. 5. **Track.** Fill the tracking file from `@../assets/task-template.md` with the three best candidate causes, each with a short description and a confidence level. 6. **Fix loop.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. From e88834965e69b90abf48974dd018027d9d88a72b Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 12:14:10 +0200 Subject: [PATCH 27/42] refactor(framework): align the spec skill to the norm Bring aidd-pm:04-spec to the same standard as the dev skills. - Actions rewritten to the anatomy: prose singular Input/Output, no frozen YAML. - Short two-line description; drop the orchestration trigger ("an orchestrator needs a contract before planning") and the sibling/agent chatter. - Output stated once as a transversal rule: one spec.md in the feature folder, beside plan.md, from the template. - Drop the spawn-meta ("the caller spawns a reviewer"): a spec is validated against spec-validator.yml; how is the caller's concern, not the skill's. - "reviewer findings" become "review findings"; remove the empty References and External-data sections. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-pm/CATALOG.md | 2 +- plugins/aidd-pm/skills/04-spec/README.md | 25 +++++----- plugins/aidd-pm/skills/04-spec/SKILL.md | 47 +++++++------------ .../skills/04-spec/actions/01-build.md | 36 +++++--------- .../skills/04-spec/actions/02-refine.md | 34 +++++--------- .../skills/04-spec/assets/spec-validator.yml | 2 +- 6 files changed, 54 insertions(+), 92 deletions(-) diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index 5da05e2f..a707dabd 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -58,5 +58,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-refine.md](skills/04-spec/actions/02-refine.md) | - | | `assets` | [spec-template.md](skills/04-spec/assets/spec-template.md) | - | | `-` | [README.md](skills/04-spec/README.md) | - | -| `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec.` | +| `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a spec, the immutable contract behind a feature, from a free-form request, an existing PRD, or review findings. Use to draft a spec ("spec for X", "/spec") or to refine one from findings. Do NOT use to write code, a full PRD, or to change a locked spec.` | diff --git a/plugins/aidd-pm/skills/04-spec/README.md b/plugins/aidd-pm/skills/04-spec/README.md index 80d2829d..8a593136 100644 --- a/plugins/aidd-pm/skills/04-spec/README.md +++ b/plugins/aidd-pm/skills/04-spec/README.md @@ -2,17 +2,15 @@ # 04 - Spec -Generates or refines the immutable contract between human intent and the -downstream agents that will plan, implement, and review the work. The spec -is what a planner consumes; it stays free of implementation detail and is -locked once validated. +Generate or refine the immutable contract for a feature: its target, hard +constraints, non-goals, and done-when. The spec stays free of implementation +detail and is locked once validated. ## When to use - "draft spec", "spec for X", "generate spec from prd". -- "refine the spec" when reviewer findings come back. +- "refine the spec" when review findings come back. - Invoking `/spec`. -- When an orchestrator needs a normalized contract before triggering a plan. ## When NOT to use @@ -29,7 +27,7 @@ Build a fresh spec from a request or an existing PRD: Use skill aidd-pm:04-spec build for ``` -Refine an existing spec from reviewer findings: +Refine an existing spec from review findings: ``` Use skill aidd-pm:04-spec refine on with @@ -44,20 +42,19 @@ and `findings` triggers `refine`; otherwise `build` runs. with explicit non-goals, bulleted acceptance criteria, and `TBD: ` markers wherever information is missing. - On `refine`: the same file rewritten to address the supplied findings. -- The skill never self-validates; the caller spawns a reviewer using - [`assets/spec-validator.yml`](assets/spec-validator.yml) and feeds the - findings back through `refine` for the next iteration. +- The skill never self-validates. A spec is checked against + [`assets/spec-validator.yml`](assets/spec-validator.yml); the findings come + back through `refine` for the next iteration. ## Prerequisites - A free-form request, an existing PRD path, or an existing spec plus a - set of reviewer findings. + set of review findings. - Write access to the spec target path in the current repo. ## Technical details See [`SKILL.md`](SKILL.md) for the action contract, [`actions/01-build.md`](actions/01-build.md) and -[`actions/02-refine.md`](actions/02-refine.md) for the two atomic actions, -and [`assets/`](assets/) for the canonical template plus the validator -checklist used by reviewers. +[`actions/02-refine.md`](actions/02-refine.md) for the two actions, +and [`assets/`](assets/) for the spec template plus the validator checklist. diff --git a/plugins/aidd-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md index a356c7b3..c87172d4 100644 --- a/plugins/aidd-pm/skills/04-spec/SKILL.md +++ b/plugins/aidd-pm/skills/04-spec/SKILL.md @@ -1,46 +1,31 @@ --- name: 04-spec -description: Generate or refine a project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec. +description: Generate or refine a spec, the immutable contract behind a feature, from a free-form request, an existing PRD, or review findings. Use to draft a spec ("spec for X", "/spec") or to refine one from findings. Do NOT use to write code, a full PRD, or to change a locked spec. argument-hint: build | refine --- -# Spec +# Skill: spec -Generates or refines the immutable contract between human intent and downstream agents. +Generate or refine the immutable contract for a feature: its target, hard constraints, non-goals, and done-when. -## Available actions +## Actions -| # | Action | Role | Input | -| --- | --------- | ----------------------------------------------------------------- | -------------------------------------- | -| 01 | `build` | Create a fresh spec from a free-form request or an existing PRD | request or prd_path, feature_name | -| 02 | `refine` | Rewrite an existing spec to address reviewer findings | existing_spec, findings | +| # | Action | Role | Input | +| --- | -------- | ---------------------------------------------------- | ---------------------------- | +| 01 | `build` | Draft a fresh spec from a request or an existing PRD | a request or a PRD path | +| 02 | `refine` | Rewrite an existing spec to address review findings | a spec path and the findings | -## Default flow - -Non-sequential. The router dispatches based on inputs: - -- `existing_spec` and `findings` present -> `refine` -- `request` or `prd_path` present -> `build` +Dispatch by input: a spec path with findings runs `refine`; a request or PRD path runs `build`. ## Transversal rules -- Never invent missing information. Mark every gap as `TBD: ` instead of guessing. -- If the request is too vague to draft a useful spec, return early and ask the user to brainstorm the request first; do not fabricate intent. -- Never modify a spec that has been validated and locked. -- The spec is the contract; it is immutable once validated. -- Keep the spec readable: clear section headers, bulleted criteria, explicit non-goals. -- Never include implementation detail (libraries, patterns, file layout); those belong to the plan. -- Do not self-validate. The caller spawns a reviewer with `@assets/spec-validator.yml`; findings come back through the `refine` action for the next iteration. - -## References - -- None. +- Never invent. Mark every gap as `TBD: ` rather than guessing. When a request is too vague to draft anything useful, stop and ask for a clearer one. +- The spec holds intent, never implementation. No library, pattern, or file layout; those belong to the plan. +- Keep it readable: clear section headers, bulleted criteria, explicit non-goals. +- Output: one `spec.md` in the feature folder (`aidd_docs/tasks//_/`), from `@assets/spec-template.md`. Reuse the folder when it exists. +- Immutable once validated: never rewrite a spec that has been locked. ## Assets -- `@assets/spec-template.md`: canonical structure of a spec. -- `@assets/spec-validator.yml`: checklist used by the reviewer to validate a spec. - -## External data - -- None. +- `assets/spec-template.md`: the spec's structure. +- `assets/spec-validator.yml`: the checklist a spec is validated against. diff --git a/plugins/aidd-pm/skills/04-spec/actions/01-build.md b/plugins/aidd-pm/skills/04-spec/actions/01-build.md index f9696608..3d1670d0 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/01-build.md +++ b/plugins/aidd-pm/skills/04-spec/actions/01-build.md @@ -1,35 +1,25 @@ # 01 - Build -Create a fresh spec from a free-form request or by extracting fields from an existing PRD. +Draft a fresh spec from a free-form request, or by lifting fields from an existing PRD. -## Inputs +## Input -```yaml -request: # required when prd_path is absent -prd_path: # required when request is absent -feature_name: # required; derived from the request when absent -``` +A free-form request, or a path to an existing PRD. A feature name for the folder, derived from the request when absent. -## Outputs +## Output -```yaml -spec_path: aidd_docs/tasks//_/spec.md -status: draft -notes: -``` +The path to `spec.md` in the feature folder, drafted from the template, with the ambiguities and assumptions noted. ## Process -1. **Source resolution**. Pick first match: - - `prd_path` provided -> parse the PRD, lift target, hard constraints, non-goals, and done-when into the matching template sections; drop libraries, patterns, and file-layout content - - `request` provided -> use `assets/spec-template.md` directly and map the request onto its sections -2. **Mark gaps**. Replace any missing required field with `TBD: `. Never guess. -3. **Section check**. Confirm every section listed in `assets/spec-validator.yml` is present. -4. **Write**. Resolve the feature folder: reuse the one for this feature when it already exists under `aidd_docs/tasks//_/`, otherwise create it. Save the spec there as `spec.md`. -5. **Return** the structured Outputs block with `status: draft`. +1. **Source.** From a PRD path, lift its target, hard constraints, non-goals, and done-when into the template, dropping any implementation detail. From a request, map it onto the template sections directly. +2. **Gaps.** Replace any missing required field with `TBD: `. Never guess. +3. **Check.** Confirm every section the validator requires is present. +4. **Write.** Resolve the feature folder, reusing it when it exists, and save the spec there as `spec.md`. +5. **Return.** Surface the spec path and the notes. ## Test -- **File saved**: `spec_path` exists on disk after the action completes. -- **All sections**: the file contains every section listed in `assets/spec-validator.yml`. -- **No implementation**: the file has no library names, framework patterns, or source-file layout. +- `spec.md` exists in the feature folder. +- It contains every section listed in `@../assets/spec-validator.yml`. +- It carries no library name, framework pattern, or source-file layout. diff --git a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md index 3bf1f7c8..6783f0a9 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md +++ b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md @@ -1,34 +1,24 @@ # 02 - Refine -Rewrite an existing spec in place to address reviewer findings. +Rewrite an existing spec in place to address review findings. -## Inputs +## Input -```yaml -existing_spec: # required -findings: # required; list or text -``` +The path to the current spec, and the findings to address, a list or free text. -## Outputs +## Output -```yaml -spec_path: # same as existing_spec -status: refined -notes: -``` +The refined spec at the same path, with the changes applied and any residual `TBD` questions noted. ## Process -1. **Load**. Read `existing_spec` and `findings`. -2. **Map findings**. Pair each finding with the section of the spec it touches. -3. **Rewrite**. Apply each finding in place: clarify wording, add missing fields, remove invalid claims. Preserve sections the findings do not touch. -4. **Mark gaps**. Replace any field still unanswered with `TBD: `. Never guess. -5. **Section check**. Confirm every section listed in `assets/spec-validator.yml` is present. -6. **Write**. Save the refined spec back to the same path as `existing_spec` (overwrite). -7. **Return** the structured Outputs block with `status: refined`. +1. **Load.** Read the spec and the findings. +2. **Map.** Pair each finding with the section it touches. +3. **Rewrite.** Apply each finding in place: clarify wording, add missing fields, remove invalid claims. Leave untouched sections as they are. +4. **Gaps.** Replace any field still unanswered with `TBD: `. Never guess. +5. **Check.** Confirm every section the validator requires is present, then overwrite the spec at its path. ## Test -- **File saved**: `spec_path` exists on disk after the action completes. -- **All sections**: the file contains every section listed in `assets/spec-validator.yml`. -- **Findings addressed**: every finding in `findings` is reflected by a change in the rewritten spec or by an explicit `TBD: ` if it cannot be resolved. +- The spec still exists at its path and holds every section listed in `@../assets/spec-validator.yml`. +- Every finding is reflected by a change, or by an explicit `TBD: ` when it cannot be resolved. diff --git a/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml b/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml index 364d0aba..1da8edd5 100644 --- a/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml +++ b/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml @@ -1,4 +1,4 @@ -# Checklist used by the reviewer agent to validate a spec. +# Checklist a spec is validated against. # Each criterion is independently scored. Required criteria must be `fulfilled` for the spec to pass. criteria: From 12b09b9e46535ef6492c1e948208971fd7f8afd0 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 14:08:50 +0200 Subject: [PATCH 28/42] fix(framework): review always writes review.md, never inline-only The full test caught the report file being skipped: the model reported the verdict inline and claimed a path without writing the file, in both the standalone and SDLC paths. Make the output rule imperative: the deliverable is the file, always written to disk. Verified: review.md now written reliably. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/05-review/SKILL.md | 2 +- plugins/aidd-pm/CATALOG.md | 18 +++++--- .../aidd-pm/skills/02-user-stories/SKILL.md | 41 +++++++++++++++++++ plugins/aidd-pm/skills/04-spec/SKILL.md | 2 +- 4 files changed, 55 insertions(+), 8 deletions(-) create mode 100644 plugins/aidd-pm/skills/02-user-stories/SKILL.md diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 94798ee3..58cfb588 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -22,7 +22,7 @@ Run all three by default, composing one report. Run a single axis only when the ## Transversal rules - Read-only: surface each finding with its fix described, never patch. -- Output: one `review.md` in a feature folder (`aidd_docs/tasks//_/`), from `@assets/review-template.md`. Reuse the reviewed work's folder when it has one (beside `plan.md`); otherwise resolve a new one from the change, by branch or a derived slug. Never create a plan. Each axis fills its section; an axis not run is marked "Not run". +- Output: the deliverable is the file, never an inline-only verdict. Always write one `review.md` to disk in a feature folder (`aidd_docs/tasks//_/`), from `@assets/review-template.md`. Reuse the reviewed work's folder when it has one (beside `plan.md`); otherwise resolve a new one from the change, by branch or a derived slug. Never create a plan. Each axis fills its section; an axis not run is marked "Not run". - Re-run: overwrite `review.md` with the current review. It is a snapshot of the current diff, not a history; a later review of the same work replaces the earlier one. - Verdict: one overall verdict, the strictest across the axes run, per `@references/review-rubric.md`. diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index a707dabd..5ce7df18 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -9,7 +9,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`.claude-plugin`](#claude-plugin) - [`skills`](#skills) - [`skills/01-ticket-info`](#skills01-ticket-info) - - [`skills/02-user-stories-create`](#skills02-user-stories-create) + - [`skills/02-user-stories`](#skills02-user-stories) - [`skills/03-prd`](#skills03-prd) - [`skills/04-spec`](#skills04-spec) @@ -31,14 +31,20 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `-` | [README.md](skills/01-ticket-info/README.md) | - | | `-` | [SKILL.md](skills/01-ticket-info/SKILL.md) | `Retrieve and display ticket information from the configured ticketing tool. Use when the user says "ticket info", "show ticket", "get ticket", "ticket details", "what's ", or invokes `/ticket-info`. Do NOT use for creating issues, commenting on tickets, changing status, or reassigning.` | -#### `skills/02-user-stories-create` +#### `skills/02-user-stories` | Group | File | Description | |-------|------|---| -| `actions` | [01-create-user-stories.md](skills/02-user-stories-create/actions/01-create-user-stories.md) | - | -| `assets` | [user-story-template.md](skills/02-user-stories-create/assets/user-story-template.md) | `Template for defining user stories with estimation and acceptance criteria` | -| `-` | [README.md](skills/02-user-stories-create/README.md) | - | -| `-` | [SKILL.md](skills/02-user-stories-create/SKILL.md) | `Generate INVEST-compliant user stories from a feature description. Use when the user says "user stories", "create user stories", "write user stories for X", "INVEST stories", "draft stories", or invokes `/user-stories-create`. Do NOT use for writing code, drafting a full PRD, refining a single existing story, or copying ready text into a tracker.` | +| `actions` | [01-clarify-scope.md](skills/02-user-stories/actions/01-clarify-scope.md) | - | +| `actions` | [02-split-epic.md](skills/02-user-stories/actions/02-split-epic.md) | - | +| `actions` | [03-draft-stories.md](skills/02-user-stories/actions/03-draft-stories.md) | - | +| `actions` | [04-estimate-impact.md](skills/02-user-stories/actions/04-estimate-impact.md) | - | +| `actions` | [05-prioritize.md](skills/02-user-stories/actions/05-prioritize.md) | - | +| `actions` | [06-sync-tracker.md](skills/02-user-stories/actions/06-sync-tracker.md) | - | +| `assets` | [user-story-template.md](skills/02-user-stories/assets/user-story-template.md) | - | +| `-` | [README.md](skills/02-user-stories/README.md) | - | +| `references` | [rating.md](skills/02-user-stories/references/rating.md) | - | +| `-` | [SKILL.md](skills/02-user-stories/SKILL.md) | `Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog saved to the project's tracker. Use for "user stories", "split this epic", "break down this feature", "estimate/prioritize the backlog", or `/user-stories`. Not for source code or a full PRD (use `03-prd`).` | #### `skills/03-prd` diff --git a/plugins/aidd-pm/skills/02-user-stories/SKILL.md b/plugins/aidd-pm/skills/02-user-stories/SKILL.md new file mode 100644 index 00000000..63f279f0 --- /dev/null +++ b/plugins/aidd-pm/skills/02-user-stories/SKILL.md @@ -0,0 +1,41 @@ +--- +name: 02-user-stories +description: Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog saved to the project's tracker. Use for "user stories", "split this epic", "break down this feature", "estimate/prioritize the backlog", or `/user-stories`. Not for source code or a full PRD (use `03-prd`). +argument-hint: clarify-scope | split-epic | draft-stories | estimate-impact | prioritize | sync-tracker +--- + +# User Stories + +Produces a prioritized backlog of INVEST-compliant user stories, each estimated for effort and impact and carrying a pragmatic functional Definition of Done, then saved to the project's configured tracker. + +## Available actions + +| # | Action | Role | Input | +| --- | ----------------- | -------------------------------------------------------------------- | -------------------------------------- | +| 01 | `clarify-scope` | Clarify the request through Product Owner questioning; decide epic vs single story | feature or epic description | +| 02 | `split-epic` | Decompose the confirmed scope into candidate vertical-slice stories | confirmed scope from 01 | +| 03 | `draft-stories` | Write each candidate as an INVEST story with acceptance criteria and a functional DoD | candidate stories from 02 | +| 04 | `estimate-impact` | Rate each story for effort (points) and impact on the existing system | drafted stories from 03 | +| 05 | `prioritize` | Rank the backlog by value against effort and impact | estimated stories from 04 | +| 06 | `sync-tracker` | Gate on Definition of Ready, get explicit approval, save to the tracker | ranked backlog from 05 | + +## Default flow + +Sequential chain `01 → 02 → 03 → 04 → 05 → 06`; run each action's `## Test` before the next. When 01 finds a single story rather than an epic, `02-split-epic` passes it through unchanged. + +## Transversal rules + +- **INVEST**: each story is Independent, Negotiable, Valuable, Estimable, Small, Testable. +- **Definition of Ready**: acceptance criteria, dependencies, story points, and an impact rating are set, with zero blocking questions, before save. +- **Definition of Done**: each story carries a pragmatic, functional DoD — observable, user-facing conditions that mean the goal is met. Functional only, never technical delivery steps. +- **Lean clarification**: at most 3 questions per iteration; focus on user needs, not technical aspects. +- Always wait for explicit user validation before saving to the tracker. +- The save target is the configured ticketing tool from project memory; never assume a specific tool. + +## References + +- `@references/rating.md`: INVEST, the Definition of Ready and functional Definition of Done, the minor/major/critic impact scale, and the prioritization method. + +## Assets + +- `@assets/user-story-template.md`: user story body template. diff --git a/plugins/aidd-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md index c87172d4..033682cb 100644 --- a/plugins/aidd-pm/skills/04-spec/SKILL.md +++ b/plugins/aidd-pm/skills/04-spec/SKILL.md @@ -20,7 +20,7 @@ Dispatch by input: a spec path with findings runs `refine`; a request or PRD pat ## Transversal rules - Never invent. Mark every gap as `TBD: ` rather than guessing. When a request is too vague to draft anything useful, stop and ask for a clearer one. -- The spec holds intent, never implementation. No library, pattern, or file layout; those belong to the plan. +- The spec holds intent, never implementation. It is solution-agnostic: no file, component, hook, route, library, pattern, or token, and no "how". The done-when conditions are outcome-level, not steps. Keep the acceptance criteria few. All of that belongs to the plan. - Keep it readable: clear section headers, bulleted criteria, explicit non-goals. - Output: one `spec.md` in the feature folder (`aidd_docs/tasks//_/`), from `@assets/spec-template.md`. Reuse the folder when it exists. - Immutable once validated: never rewrite a spec that has been locked. From 296abe818fca551d24cf216c2ee4ff3d5a63b3dd Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 14:08:52 +0200 Subject: [PATCH 29/42] fix(framework): keep the spec solution-agnostic, intent only The full test drafted a spec full of plan detail: file names, components, hooks, routes, tokens, and eleven granular criteria, violating the spec's own "intent, never implementation" rule. Forbid exploring the codebase or naming any file, component, or API; keep done-when outcome-level and the criteria few. Verified: a build with code present named zero implementation details. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-pm/skills/04-spec/actions/01-build.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/aidd-pm/skills/04-spec/actions/01-build.md b/plugins/aidd-pm/skills/04-spec/actions/01-build.md index 3d1670d0..0a177962 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/01-build.md +++ b/plugins/aidd-pm/skills/04-spec/actions/01-build.md @@ -12,7 +12,7 @@ The path to `spec.md` in the feature folder, drafted from the template, with the ## Process -1. **Source.** From a PRD path, lift its target, hard constraints, non-goals, and done-when into the template, dropping any implementation detail. From a request, map it onto the template sections directly. +1. **Source.** From a PRD path, lift its target, hard constraints, non-goals, and done-when into the template, dropping any implementation detail. From a request, map it onto the template sections directly. Do not explore the codebase or name any file, component, or API: the spec stays solution-agnostic, intent only. 2. **Gaps.** Replace any missing required field with `TBD: `. Never guess. 3. **Check.** Confirm every section the validator requires is present. 4. **Write.** Resolve the feature folder, reusing it when it exists, and save the spec there as `spec.md`. From a3952e058e08c7b511a0db145d113952ca95d5f1 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 14:26:28 +0200 Subject: [PATCH 30/42] refactor(framework): split the overloaded review output rule One bullet was carrying eight things (deliverable, write, path, reuse, resolve, no-plan, sections, not-run). Split into three one-line rules: Output (always write the file), Folder (where, never a plan), Sections (template, one per axis, "Not run"). Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/05-review/SKILL.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 58cfb588..15275db8 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -22,7 +22,9 @@ Run all three by default, composing one report. Run a single axis only when the ## Transversal rules - Read-only: surface each finding with its fix described, never patch. -- Output: the deliverable is the file, never an inline-only verdict. Always write one `review.md` to disk in a feature folder (`aidd_docs/tasks//_/`), from `@assets/review-template.md`. Reuse the reviewed work's folder when it has one (beside `plan.md`); otherwise resolve a new one from the change, by branch or a derived slug. Never create a plan. Each axis fills its section; an axis not run is marked "Not run". +- Output: always write `review.md` to disk; the file is the deliverable, never an inline-only verdict. +- Folder: write into the reviewed work's feature folder (`aidd_docs/tasks//_/`, beside `plan.md`), or one resolved from the change when it has none. Never create a plan. +- Sections: fill `review.md` from `@assets/review-template.md`, each axis its own section, an unrun axis marked "Not run". - Re-run: overwrite `review.md` with the current review. It is a snapshot of the current diff, not a history; a later review of the same work replaces the earlier one. - Verdict: one overall verdict, the strictest across the axes run, per `@references/review-rubric.md`. From d784e7063d7698ac3a93b8855204901743f05360 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 14:33:27 +0200 Subject: [PATCH 31/42] refactor(framework): drop the redundant 'never create a plan' from review A review writes review.md; it has no reason to create a plan. Forbidding it defends against a non-event. Removed. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/05-review/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 15275db8..2ef81874 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -23,7 +23,7 @@ Run all three by default, composing one report. Run a single axis only when the - Read-only: surface each finding with its fix described, never patch. - Output: always write `review.md` to disk; the file is the deliverable, never an inline-only verdict. -- Folder: write into the reviewed work's feature folder (`aidd_docs/tasks//_/`, beside `plan.md`), or one resolved from the change when it has none. Never create a plan. +- Folder: write into the reviewed work's feature folder (`aidd_docs/tasks//_/`, beside `plan.md`), or one resolved from the change when it has none. - Sections: fill `review.md` from `@assets/review-template.md`, each axis its own section, an unrun axis marked "Not run". - Re-run: overwrite `review.md` with the current review. It is a snapshot of the current diff, not a history; a later review of the same work replaces the earlier one. - Verdict: one overall verdict, the strictest across the axes run, per `@references/review-rubric.md`. From 2ffe9750bfebd112b893c21bc1ad95c53a07b00f Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 15:10:18 +0200 Subject: [PATCH 32/42] docs(framework): trim sdlc, assert, review, spec descriptions to two lines The four were running ~three lines. Cut to the essential what + when + key do-not, under 210 chars each, keeping the trigger words. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 6 +++--- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 2 +- plugins/aidd-dev/skills/03-assert/SKILL.md | 2 +- plugins/aidd-dev/skills/05-review/SKILL.md | 2 +- plugins/aidd-pm/CATALOG.md | 2 +- plugins/aidd-pm/skills/04-spec/SKILL.md | 2 +- 6 files changed, 8 insertions(+), 8 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 54ee7513..7f745f1b 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -48,7 +48,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [04-review.md](skills/00-sdlc/actions/04-review.md) | - | | `actions` | [05-ship.md](skills/00-sdlc/actions/05-ship.md) | - | | `-` | [README.md](skills/00-sdlc/README.md) | - | -| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Orchestrate the full dev flow from a free-form request to shipped code: spec, plan, implement, review, ship, every step delegated. Use to take a request end to end to a change request, not a single step. Interactive by default (pauses at each gate); say auto for an unattended run.` | +| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Orchestrate the full dev flow, a free-form request to shipped code, every step delegated. Use to take a request end to end, not a single step. Interactive by default; say auto for unattended.` | #### `skills/01-plan` @@ -86,7 +86,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-assert-frontend.md](skills/03-assert/actions/03-assert-frontend.md) | - | | `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | - | | `-` | [README.md](skills/03-assert/README.md) | - | -| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert that the work behaves as intended by iterating the project's coding assertions until they pass, with optional architecture-conformance and running-frontend facets. Use to validate an implementation before moving on. Do NOT use to review code quality or to write new tests.` | +| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert the work behaves: iterate the project's coding assertions until they pass, plus optional architecture and frontend facets. Use to validate an implementation. Do NOT use to review or write tests.` | #### `skills/04-audit` @@ -113,7 +113,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [review-template.md](skills/05-review/assets/review-template.md) | - | | `-` | [README.md](skills/05-review/README.md) | - | | `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff along three axes, code quality, behavior versus the plan, and relevancy, into one report with a verdict. Use to review changes before they ship. Do NOT use to fix the findings or to audit a whole codebase.` | +| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff on three axes, code, behavior versus the plan, and relevancy, into one verdict report. Use before shipping a change. Do NOT use to fix findings or audit a codebase.` | #### `skills/06-test` diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 00d11c49..224f1795 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -1,6 +1,6 @@ --- name: 00-sdlc -description: Orchestrate the full dev flow from a free-form request to shipped code: spec, plan, implement, review, ship, every step delegated. Use to take a request end to end to a change request, not a single step. Interactive by default (pauses at each gate); say auto for an unattended run. +description: Orchestrate the full dev flow, a free-form request to shipped code, every step delegated. Use to take a request end to end, not a single step. Interactive by default; say auto for unattended. argument-hint: spec | plan | implement | review | ship --- diff --git a/plugins/aidd-dev/skills/03-assert/SKILL.md b/plugins/aidd-dev/skills/03-assert/SKILL.md index f341ea0c..7e03bdd0 100644 --- a/plugins/aidd-dev/skills/03-assert/SKILL.md +++ b/plugins/aidd-dev/skills/03-assert/SKILL.md @@ -1,6 +1,6 @@ --- name: 03-assert -description: Assert that the work behaves as intended by iterating the project's coding assertions until they pass, with optional architecture-conformance and running-frontend facets. Use to validate an implementation before moving on. Do NOT use to review code quality or to write new tests. +description: Assert the work behaves: iterate the project's coding assertions until they pass, plus optional architecture and frontend facets. Use to validate an implementation. Do NOT use to review or write tests. argument-hint: assert | assert-architecture | assert-frontend model: sonnet --- diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 2ef81874..6e0e4894 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,6 +1,6 @@ --- name: 05-review -description: Read-only review of a diff along three axes, code quality, behavior versus the plan, and relevancy, into one report with a verdict. Use to review changes before they ship. Do NOT use to fix the findings or to audit a whole codebase. +description: Read-only review of a diff on three axes, code, behavior versus the plan, and relevancy, into one verdict report. Use before shipping a change. Do NOT use to fix findings or audit a codebase. argument-hint: review-code | review-functional | review-relevancy model: opus --- diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index 5ce7df18..41060ce3 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -64,5 +64,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-refine.md](skills/04-spec/actions/02-refine.md) | - | | `assets` | [spec-template.md](skills/04-spec/assets/spec-template.md) | - | | `-` | [README.md](skills/04-spec/README.md) | - | -| `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a spec, the immutable contract behind a feature, from a free-form request, an existing PRD, or review findings. Use to draft a spec ("spec for X", "/spec") or to refine one from findings. Do NOT use to write code, a full PRD, or to change a locked spec.` | +| `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a spec, a feature's immutable contract, from a request, a PRD, or review findings. Use to draft or refine a spec. Do NOT use to write code, a full PRD, or change a locked spec.` | diff --git a/plugins/aidd-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md index 033682cb..1b099bc2 100644 --- a/plugins/aidd-pm/skills/04-spec/SKILL.md +++ b/plugins/aidd-pm/skills/04-spec/SKILL.md @@ -1,6 +1,6 @@ --- name: 04-spec -description: Generate or refine a spec, the immutable contract behind a feature, from a free-form request, an existing PRD, or review findings. Use to draft a spec ("spec for X", "/spec") or to refine one from findings. Do NOT use to write code, a full PRD, or to change a locked spec. +description: Generate or refine a spec, a feature's immutable contract, from a request, a PRD, or review findings. Use to draft or refine a spec. Do NOT use to write code, a full PRD, or change a locked spec. argument-hint: build | refine --- From 085a751b01f99765010d13b1605e776129c019f3 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 15:35:17 +0200 Subject: [PATCH 33/42] refactor(framework): align the ship skills (commit, pull-request) to the norm Actions rewritten to the anatomy: prose singular Input/Output, no frozen YAML. commit description cut to two lines; "Available actions" -> "Actions"; drop the empty References and External-data sections in both. pull-request keeps its prefix-routing base resolution and triage labelling (from #326), in prose. commit validated: auto mode produced a conventional commit and sha. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-vcs/CATALOG.md | 2 +- plugins/aidd-vcs/skills/01-commit/SKILL.md | 12 +--- .../skills/01-commit/actions/01-commit.md | 59 +++++-------------- .../aidd-vcs/skills/02-pull-request/SKILL.md | 10 +--- .../actions/01-pull-request.md | 54 ++++++----------- 5 files changed, 38 insertions(+), 99 deletions(-) diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 7a84091d..ed17d8e0 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -41,7 +41,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-commit.md](skills/01-commit/actions/01-commit.md) | - | | `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | | `-` | [README.md](skills/01-commit/README.md) | - | -| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging.` | +| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with a conventional message, optionally pushing. Use to commit changes ("commit", "/commit push"). Do NOT use to amend, rebase, open a PR, or tag a release.` | #### `skills/02-pull-request` diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md index e25cb790..3ed5a2c7 100644 --- a/plugins/aidd-vcs/skills/01-commit/SKILL.md +++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md @@ -1,13 +1,13 @@ --- name: 01-commit -description: Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging. +description: Create an atomic git commit with a conventional message, optionally pushing. Use to commit changes ("commit", "/commit push"). Do NOT use to amend, rebase, open a PR, or tag a release. --- # Commit Generates atomic git commits with conventional messages, supporting interactive splits and agent-driven auto mode. -## Available actions +## Actions | # | Action | Role | Input | | --- | -------- | ------------------------------------------------------------- | ------------------------------------------- | @@ -34,14 +34,6 @@ When invoked as a slash command, the trailing argument controls the push behavio - Reference issues in the commit body when applicable. - `auto` mode never asks for confirmation. `interactive` mode requires user approval before staging and before committing splits. -## References - -- None. - ## Assets - `@assets/commit-template.md`: Conventional commit format reference. - -## External data - -- None. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md index b0a8171a..ae56aade 100644 --- a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md +++ b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md @@ -1,55 +1,28 @@ # 01 - Commit -Stage files, generate or accept a commit message, run the commit, optionally push, and return the resulting sha. +Stage the change, write or accept a conventional message, commit, optionally push, and return the sha. -## Inputs +## Input -```yaml -mode: interactive | auto # default: interactive -message: # optional; when set, used as-is, no generation -push: true | false # default: false -files: [] # optional; restrict staging to these paths -``` +The mode (`interactive` default, or `auto`), an optional imposed message, whether to push (default no, set by a trailing `push` in `$ARGUMENTS`), and optional paths to restrict staging. -When invoked via slash command, parse `$ARGUMENTS`: +## Output -- contains the word `push` → set `push: true` -- empty or anything else → leave `push: false` - -## Outputs - -```yaml -commit_sha: -branch: -pushed: true | false -``` +The new commit sha, the branch, and whether it was pushed. ## Process -1. **Branch resolution**. Pick first match: - - branch already checked out -> use it - - `mode = auto` -> generate a conventional name from the change - - `mode = interactive` -> propose a name and wait for user approval -2. **Staging**. Pick first match: - - `files` set -> `git add` exactly those paths - - default -> use already-staged changes; do not add unstaged paths implicitly -3. **Message resolution**. Pick first match: - - `message` provided -> use it verbatim, skip steps 4 and 5 - - `mode = auto` -> inspect diff and `git log -5 --pretty=%B`, generate a message per `assets/commit-template.md`, no approval - - `mode = interactive` -> draft a message per the template, then proceed to steps 4 and 5 -4. **Interactive split** (when `mode = interactive` and multiple concerns are present). For each split, show: - - **Scope**: file list (proposal-only). - - **Draft message**: conventional subject; body explains "why", never lists files. - Wait for user approval. -5. **Interactive stage** (when `mode = interactive`). Run `git add -p` for each split. -6. **Commit**. Run `git commit` with the chosen message via heredoc. -7. **Hook recovery**. When a pre-commit hook fails, fix the underlying issue, re-stage, and create a new commit (do not amend). Loop until commit succeeds. -8. **Capture sha**. Read `git rev-parse HEAD`. -9. **Push**. When `push: true`, run `git push`. Use `--force-with-lease` only when explicitly required. Never `--force`. -10. **Return** the structured Outputs block. In interactive mode, also notify the user. +1. **Branch.** Use the checked-out branch. In `auto`, generate a conventional name from the change; in `interactive`, propose one and wait for approval. +2. **Stage.** With explicit paths, `git add` exactly those. Otherwise commit the already-staged changes, never staging unstaged paths implicitly. +3. **Message.** Use an imposed message verbatim when given. In `auto`, generate one from the diff and recent log per `@../assets/commit-template.md`, no approval. In `interactive`, draft one and confirm. +4. **Split.** In `interactive` with several concerns, propose each split (its scope, and a draft message that explains why, never lists files), wait for approval, and stage each with `git add -p`. +5. **Commit.** Run `git commit` with the chosen message. +6. **Recover.** On a pre-commit hook failure, fix the cause, re-stage, and make a new commit, never amend. Loop until it succeeds. +7. **Push.** When asked, `git push`. Use `--force-with-lease` only when explicitly required, never `--force`. +8. **Return.** Surface the sha, branch, and push state. ## Test -- **Sha match**: `git rev-parse HEAD` returns the new commit sha that matches the `commit_sha` field in Outputs. -- **Format**: `git log -1 --pretty=%s` matches the conventional commit regex `^(feat|fix|docs|style|refactor|perf|test|chore|build|ci)(\([^)]+\))?: .+`. -- **Push**: when `push: true`, `git ls-remote origin ` lists a sha equal to `commit_sha`. +- `git rev-parse HEAD` equals the returned sha. +- `git log -1 --pretty=%s` matches the conventional-commit format. +- When pushed, `git ls-remote origin ` lists the sha. diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 7755da96..24d95e0f 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -7,7 +7,7 @@ description: Create a draft pull or merge request from the current branch. Use w Drafts pull or merge requests from the current branch using the team's template, ready for the user to promote. -## Available actions +## Actions | # | Action | Role | Input | | --- | --------------- | ------------------------------------------------------------------- | ---------------------------------------------- | @@ -26,17 +26,9 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph - Never commit, never push the working branch, never create new branches inside this skill. - Tool-agnostic: read the VCS tool from project memory; fall back to inspecting the remote URL. -## References - -- None. - ## Assets - `@assets/pull_request.md`: Request body template. - `@assets/branch.md`: Branch naming conventions. - `@assets/CONTRIBUTING.md`: Contribution guidelines template. - `@assets/README.md`: README template. - -## External data - -- None. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md index cffa5b7c..060c98dc 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md @@ -1,48 +1,30 @@ # 01 - Pull Request -Detect the base branch, fill the request template with recent commits, validate with the user, and open a draft request via the configured VCS tool. +Detect the base branch, fill the request template from the recent commits, validate with the user, and open a draft request via the configured VCS tool. -## Inputs +## Input -```yaml -base_branch: # optional; auto-detect from repo state when omitted -template_overrides: # optional; override specific template sections - title: - body: -``` +An optional base branch (auto-detected when omitted), and optional title or body overrides. -## Outputs +## Output -```yaml -pr_url: -pr_number: -branch: -base: -is_draft: true -``` +The draft request's URL and number, with its head and resolved base branch. ## Process -1. **Tool resolution**. Pick first match: - - VCS tool declared in project memory -> use it - - default -> map `git remote get-url origin` to the matching configured tool -2. **Branch identity**. Read current head via `git rev-parse --abbrev-ref HEAD`. -3. **Base resolution**. Pick first match: - - `base_branch` provided -> use it - - the branch-naming convention in project memory maps the head branch's prefix to a PR target (e.g. `feat/` -> `next`, `hotfix/` -> `main`) -> use that target - - default -> inspect `git symbolic-ref refs/remotes/origin/HEAD`, then candidate list `main`, `master`, `develop`, `staging` - - surface the chosen value and the reason during validation -4. **Collect changes**. Run `git log ..HEAD --pretty=fuller` and `git diff ...HEAD --stat` to summarize commits and impacted files. -5. **Read template**. Load `assets/pull_request.md` and any contributing rules from `assets/CONTRIBUTING.md`. -6. **Fill template**. Generate a concise title and a body that follows the template structure, using the change summary from step 4. -7. **Validate with user**. Show title, body, and detected base branch. Apply `template_overrides` when provided. Wait for explicit user approval. -8. **Open draft**. Invoke the configured VCS tool to create the request as a draft, passing base, title, and body. Capture the returned URL and number. -9. **Set triage label**. When the branch-naming convention maps the head branch's prefix to a triage label (e.g. `feat/` -> `enhancement`, `fix/` -> `bug`) and that label exists in the repo, apply it. Skip silently when there is no mapping or no matching label. Labels triage only; they never change the base resolved in step 3. -10. **Return** the structured Outputs block. +1. **Tool.** Use the VCS tool declared in project memory, otherwise map `git remote get-url origin` to the matching configured tool. +2. **Head.** Read the current branch with `git rev-parse --abbrev-ref HEAD`. +3. **Base.** Resolve the base in order: a provided base; otherwise the target the head branch's prefix maps to in the project's branch-naming convention (for example `feat/` → `next`, `hotfix/` → `main`); otherwise `git symbolic-ref refs/remotes/origin/HEAD`, then `main`, `master`, `develop`, `staging`. Surface the chosen base and the reason. +4. **Collect.** Summarize the commits and impacted files with `git log ..HEAD` and `git diff ...HEAD --stat`. +5. **Fill.** Load the request template and any contributing rules, then write a concise title and a body following the template from the change summary. +6. **Validate.** Show the title, body, and detected base. Apply any overrides, then wait for explicit approval. +7. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body. Capture the URL and number. +8. **Label.** When the head prefix maps to a triage label that exists in the repo, apply it (for example `feat/` → `enhancement`). Skip silently otherwise. Labels triage only; they never change the base. +9. **Return.** Surface the URL, number, head, and base. ## Test -- **Tool view**: querying the configured VCS tool for the created request returns a record where `url` equals `pr_url`, `base` equals the resolved base branch, and the draft flag is true. -- **Prefix routing**: a head branch whose prefix is mapped in project memory resolves `base` to that prefix's target (e.g. `feat/*` -> `next`, `hotfix/*` -> `main`), not the `origin/HEAD` default. -- **Triage label**: when the head prefix maps to a triage label that exists in the repo, the created request carries that label. -- **Reachable**: the created request is reachable at `pr_url` and lists the head branch as the current branch. +- The created request exists with `base` equal to the resolved base and the draft flag true. +- A head branch whose prefix is mapped resolves the base to that target, not the `origin/HEAD` default. +- When the head prefix maps to an existing triage label, the request carries it. +- The request is reachable at its URL with the head branch as its source. From 517c6b288f7ed2e6c29c1111731df0e564a0ba8b Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 16:06:43 +0200 Subject: [PATCH 34/42] fix(framework): markdown-links skips git worktrees and specstory The checker scanned the whole tree, including the full repo copies under .claude/worktrees/* and the .specstory transcripts, reporting ~7700 false "broken" links (template placeholders, history) and blocking every commit. Add worktrees and .specstory to the skipped dirs. Real source: 0 broken in 370 files. Co-Authored-By: Claude Opus 4.8 (1M context) --- scripts/check-markdown-links.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/check-markdown-links.js b/scripts/check-markdown-links.js index 783ffcec..15b7dde6 100644 --- a/scripts/check-markdown-links.js +++ b/scripts/check-markdown-links.js @@ -33,7 +33,7 @@ Examples: | Reader reference | See [explore skill](plugins/aidd-context/skills/11-explore/SKILL.md). | `; -const SKIPPED_DIRS = new Set([".git", "node_modules"]); +const SKIPPED_DIRS = new Set([".git", "node_modules", "worktrees", ".specstory"]); const SKIPPED_DIR_PREFIXES = [".tmp-check-markdown-links-"]; const MARKDOWN_EXTENSIONS = new Set([".md", ".mdx"]); function normalizePathForDisplay(filePath) { From 3ec35bc1b1a71497a45539691ed3f85044ff560e Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 20:06:55 +0200 Subject: [PATCH 35/42] fix(framework): enforce the feature-folder path for plans The plan kept drifting to aidd_docs/plans/ instead of the feature folder. State the path imperatively where it is authored (01-plan output) and in the SDLC folder rule: every artifact lands in aidd_docs/tasks///, never aidd_docs/plans/ or anywhere else. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 2 +- plugins/aidd-dev/skills/01-plan/actions/04-plan.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 224f1795..c36c493c 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -26,5 +26,5 @@ Run `01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop to `03` then re-ru - Mode: default `interactive`, pausing for approval at each step; switch to `auto` only when the caller says so, then decide alone and never ask. - Every step runs; only `01-spec` self-skips when the source already states an objective and acceptance criteria. - Drive the plan status `pending → in-progress → implemented → reviewed`, or `blocked`. -- Every step writes into one feature folder resolved at entry. +- Every artifact (spec, plan, phases, review) lands in one feature folder, `aidd_docs/tasks//_/`, resolved at entry. Never `aidd_docs/plans/` or anywhere else. - Never auto-branch; the caller sets a non-default branch before shipping. diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md index 160bf208..6abb6d06 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md @@ -8,7 +8,7 @@ The explore output from `02-explore` (projection, rules, feasibility, risks), pl ## Output -A feature folder `aidd_docs/tasks//_/` holding `plan.md` from `@../assets/plan-template.md` and one `phase-.md` per phase from `@../assets/phase-template.md`. +A feature folder, always at `aidd_docs/tasks//_/` and never `aidd_docs/plans/` or anywhere else, holding `plan.md` from `@../assets/plan-template.md` and one `phase-.md` per phase from `@../assets/phase-template.md`. ## Process From 46db663e3d9a3a5ca0e175fe1da9d7a70ce4d286 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 20:09:04 +0200 Subject: [PATCH 36/42] refactor(framework): drop the negative path naming, keep the positive Stating the wrong path ("never aidd_docs/plans/") is over-specification. The imperative "always at aidd_docs/tasks///" is the enforcement on its own. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 2 +- plugins/aidd-dev/skills/01-plan/actions/04-plan.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index c36c493c..e7265a02 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -26,5 +26,5 @@ Run `01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop to `03` then re-ru - Mode: default `interactive`, pausing for approval at each step; switch to `auto` only when the caller says so, then decide alone and never ask. - Every step runs; only `01-spec` self-skips when the source already states an objective and acceptance criteria. - Drive the plan status `pending → in-progress → implemented → reviewed`, or `blocked`. -- Every artifact (spec, plan, phases, review) lands in one feature folder, `aidd_docs/tasks//_/`, resolved at entry. Never `aidd_docs/plans/` or anywhere else. +- Every artifact (spec, plan, phases, review) lands in one feature folder, `aidd_docs/tasks//_/`, resolved at entry. - Never auto-branch; the caller sets a non-default branch before shipping. diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md index 6abb6d06..d37c8c10 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md @@ -8,7 +8,7 @@ The explore output from `02-explore` (projection, rules, feasibility, risks), pl ## Output -A feature folder, always at `aidd_docs/tasks//_/` and never `aidd_docs/plans/` or anywhere else, holding `plan.md` from `@../assets/plan-template.md` and one `phase-.md` per phase from `@../assets/phase-template.md`. +A feature folder, always at `aidd_docs/tasks//_/`, holding `plan.md` from `@../assets/plan-template.md` and one `phase-.md` per phase from `@../assets/phase-template.md`. ## Process From 152dfc61e51f449eb4f35bec00246c8ef4a4dd5a Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 20:31:26 +0200 Subject: [PATCH 37/42] refactor(vcs,dev): defer commit/PR/assert to project memory The commit, pull-request, and assert skills now treat project memory as the source of truth and the bundled defaults as the fallback: - commit follows the convention in aidd_docs/memory/vcs.md when set, else the conventional-commit template. - pull-request prefers the project's PR template (vcs.md or the repo PULL_REQUEST_TEMPLATE) over the bundled body template. - assert names aidd_docs/memory/coding-assertions.md as the assertion source when present. A skill ran in a spawned context does not auto-load memory, so each reads the file explicitly and falls back cleanly when it is absent. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/03-assert/actions/01-assert.md | 2 +- plugins/aidd-vcs/skills/01-commit/SKILL.md | 3 ++- plugins/aidd-vcs/skills/01-commit/actions/01-commit.md | 2 +- plugins/aidd-vcs/skills/02-pull-request/SKILL.md | 1 + .../aidd-vcs/skills/02-pull-request/actions/01-pull-request.md | 2 +- 5 files changed, 6 insertions(+), 4 deletions(-) diff --git a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md index b42019c6..8e162be5 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md +++ b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md @@ -12,7 +12,7 @@ A pass or fail verdict: every applicable assertion passing in a final clean swee ## Process -1. **Enumerate.** From the project conventions and the coding-assertions memory, list the assertions that apply to the work. +1. **Enumerate.** From the project conventions and the coding-assertions memory (`aidd_docs/memory/coding-assertions.md`) when it exists, list the assertions that apply to the work. 2. **Iterate.** For each assertion, fix what blocks it, then re-run it until it passes. 3. **Sweep.** Once each has passed at least once, re-run them all in one pass to confirm none regressed. 4. **Boundary.** Do not stop until every assertion passes the final sweep. diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md index 3ed5a2c7..18654d51 100644 --- a/plugins/aidd-vcs/skills/01-commit/SKILL.md +++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md @@ -26,11 +26,12 @@ When invoked as a slash command, the trailing argument controls the push behavio ## Transversal rules +- Project first: follow the VCS practices in `aidd_docs/memory/vcs.md` when it exists (message convention, scopes, branch naming). The rules below and the template are the fallback. - Commits stay atomic and focused on a single concern. - Messages use imperative mood ("Add feature" not "Added feature"). - Explain "why" not "what" in the body. - Never `--force` push. `--force-with-lease` is acceptable when explicitly required. -- Follow the conventional commit format defined in `@assets/commit-template.md`. +- Follow the conventional commit format defined in `@assets/commit-template.md` when the project sets none. - Reference issues in the commit body when applicable. - `auto` mode never asks for confirmation. `interactive` mode requires user approval before staging and before committing splits. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md index ae56aade..373d8a3d 100644 --- a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md +++ b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md @@ -14,7 +14,7 @@ The new commit sha, the branch, and whether it was pushed. 1. **Branch.** Use the checked-out branch. In `auto`, generate a conventional name from the change; in `interactive`, propose one and wait for approval. 2. **Stage.** With explicit paths, `git add` exactly those. Otherwise commit the already-staged changes, never staging unstaged paths implicitly. -3. **Message.** Use an imposed message verbatim when given. In `auto`, generate one from the diff and recent log per `@../assets/commit-template.md`, no approval. In `interactive`, draft one and confirm. +3. **Message.** Use an imposed message verbatim when given. Otherwise follow the project's convention in `aidd_docs/memory/vcs.md` when set, else `@../assets/commit-template.md`. In `auto`, generate one from the diff and recent log, no approval. In `interactive`, draft one and confirm. 4. **Split.** In `interactive` with several concerns, propose each split (its scope, and a draft message that explains why, never lists files), wait for approval, and stage each with `git add -p`. 5. **Commit.** Run `git commit` with the chosen message. 6. **Recover.** On a pre-commit hook failure, fix the cause, re-stage, and make a new commit, never amend. Loop until it succeeds. diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 24d95e0f..244755d7 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -19,6 +19,7 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph ## Transversal rules +- Project first: follow the PR practices in `aidd_docs/memory/vcs.md` and the repo's `PULL_REQUEST_TEMPLATE` when they exist (body sections, base-branch rules, labels). The rules below and the bundled templates are the fallback. - Resolve the base branch from the head branch's prefix via the project's branch-naming convention (project memory); fall back to repo state when no prefix mapping exists. Never assume `main` or `master` (common alternatives: `next`, `develop`, `staging`). - Always ask the user to validate the title, body, and base branch before creating the request. - Open the request as a draft. The user promotes it manually when ready. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md index 060c98dc..8bc50cc3 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md @@ -16,7 +16,7 @@ The draft request's URL and number, with its head and resolved base branch. 2. **Head.** Read the current branch with `git rev-parse --abbrev-ref HEAD`. 3. **Base.** Resolve the base in order: a provided base; otherwise the target the head branch's prefix maps to in the project's branch-naming convention (for example `feat/` → `next`, `hotfix/` → `main`); otherwise `git symbolic-ref refs/remotes/origin/HEAD`, then `main`, `master`, `develop`, `staging`. Surface the chosen base and the reason. 4. **Collect.** Summarize the commits and impacted files with `git log ..HEAD` and `git diff ...HEAD --stat`. -5. **Fill.** Load the request template and any contributing rules, then write a concise title and a body following the template from the change summary. +5. **Fill.** Load the request template, preferring the project's own (`aidd_docs/memory/vcs.md` or the repo's `PULL_REQUEST_TEMPLATE`) and falling back to the bundled one, plus any contributing rules, then write a concise title and a body following it from the change summary. 6. **Validate.** Show the title, body, and detected base. Apply any overrides, then wait for explicit approval. 7. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body. Capture the URL and number. 8. **Label.** When the head prefix maps to a triage label that exists in the repo, apply it (for example `feat/` → `enhancement`). Skip silently otherwise. Labels triage only; they never change the base. From 825c6eef5e8f51f9a75e33584a5342a14113f694 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 20:54:25 +0200 Subject: [PATCH 38/42] refactor(vcs): make pull-request fully tool-agnostic Drop the GitHub-specific PULL_REQUEST_TEMPLATE literal from the skill logic; refer to "the repo's own request-template file, wherever the configured tool keeps it" so GitLab, Bitbucket, and others are equal. Also align the description with the skill norm: add the missing "Do NOT use to..." clause, state the tool comes from the project, and fix the "user ask" grammar slip. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-vcs/skills/02-pull-request/SKILL.md | 4 ++-- .../skills/02-pull-request/actions/01-pull-request.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 244755d7..8b3fdedc 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -1,6 +1,6 @@ --- name: 02-pull-request -description: Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`. +description: Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use to open a PR/MR ("open a pr", `/pull-request`). Do NOT use to commit, push, or merge a branch. --- # Pull Request @@ -19,7 +19,7 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph ## Transversal rules -- Project first: follow the PR practices in `aidd_docs/memory/vcs.md` and the repo's `PULL_REQUEST_TEMPLATE` when they exist (body sections, base-branch rules, labels). The rules below and the bundled templates are the fallback. +- Project first: follow the request practices in `aidd_docs/memory/vcs.md` and the repo's own request-template file when they exist (body sections, base-branch rules, labels). The rules below and the bundled templates are the fallback. - Resolve the base branch from the head branch's prefix via the project's branch-naming convention (project memory); fall back to repo state when no prefix mapping exists. Never assume `main` or `master` (common alternatives: `next`, `develop`, `staging`). - Always ask the user to validate the title, body, and base branch before creating the request. - Open the request as a draft. The user promotes it manually when ready. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md index 8bc50cc3..3ca93ace 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md @@ -16,7 +16,7 @@ The draft request's URL and number, with its head and resolved base branch. 2. **Head.** Read the current branch with `git rev-parse --abbrev-ref HEAD`. 3. **Base.** Resolve the base in order: a provided base; otherwise the target the head branch's prefix maps to in the project's branch-naming convention (for example `feat/` → `next`, `hotfix/` → `main`); otherwise `git symbolic-ref refs/remotes/origin/HEAD`, then `main`, `master`, `develop`, `staging`. Surface the chosen base and the reason. 4. **Collect.** Summarize the commits and impacted files with `git log ..HEAD` and `git diff ...HEAD --stat`. -5. **Fill.** Load the request template, preferring the project's own (`aidd_docs/memory/vcs.md` or the repo's `PULL_REQUEST_TEMPLATE`) and falling back to the bundled one, plus any contributing rules, then write a concise title and a body following it from the change summary. +5. **Fill.** Load the request template, preferring the project's own (`aidd_docs/memory/vcs.md` or the repo's request-template file, wherever the configured tool keeps it) and falling back to the bundled one, plus any contributing rules, then write a concise title and a body following it from the change summary. 6. **Validate.** Show the title, body, and detected base. Apply any overrides, then wait for explicit approval. 7. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body. Capture the URL and number. 8. **Label.** When the head prefix maps to a triage label that exists in the repo, apply it (for example `feat/` → `enhancement`). Skip silently otherwise. Labels triage only; they never change the base. From 1e414c85831c6e05af3521e161437da84f3b9f41 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 21:00:05 +0200 Subject: [PATCH 39/42] refactor(dev): stop SDLC ship dictating the commit format The ship step briefed the commit capability to use Conventional Commits, which overrode the commit skill's project-first deference to aidd_docs/memory/vcs.md. Brief only the plan objective and let the commit capability pick the message format per its own convention. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md index 191cb90f..9896b991 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md @@ -13,7 +13,7 @@ The commit SHA and the change-request URL on the project's VCS host. ## Process 1. **Gate.** Confirm `04` produced a `ship` verdict and that no code landed after the reviewed SHA it carries. Run `git diff --name-only HEAD`: it must list only plan-tracking files (the `chore(plan): reviewed` commit and the like). Any source-code change means the reviewed verdict is stale and the new code is unreviewed: stop, run `04` on the current diff, looping back to `03` on `iterate`. If no verdict exists or it is `iterate`, stop the same way. Code is never shipped unreviewed. -2. **Commit.** Invoke a commit capability, discovered at runtime, with a Conventional Commits message derived from the plan's objective. +2. **Commit.** Invoke a commit capability, discovered at runtime, briefing it with the plan's objective. It writes the message per its own convention; never dictate a format here. 3. **Open.** Invoke a change-request capability, discovered at runtime, to push the branch and open the request. Reference the plan path in the body. 4. **Return.** Surface the commit SHA and the change-request URL. From e89082240e4ca5d909a3d9e8f3e5f96c6c060d6a Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 21:02:16 +0200 Subject: [PATCH 40/42] refactor(vcs,dev): tighten the project-memory rules Trim the wording added for project-memory deference across commit, pull-request, assert, and the SDLC ship step. No behavior change: same precedence, fewer words. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md | 2 +- plugins/aidd-dev/skills/03-assert/actions/01-assert.md | 2 +- plugins/aidd-vcs/skills/01-commit/SKILL.md | 2 +- plugins/aidd-vcs/skills/01-commit/actions/01-commit.md | 2 +- plugins/aidd-vcs/skills/02-pull-request/SKILL.md | 2 +- .../aidd-vcs/skills/02-pull-request/actions/01-pull-request.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md index 9896b991..91c7d816 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md @@ -13,7 +13,7 @@ The commit SHA and the change-request URL on the project's VCS host. ## Process 1. **Gate.** Confirm `04` produced a `ship` verdict and that no code landed after the reviewed SHA it carries. Run `git diff --name-only HEAD`: it must list only plan-tracking files (the `chore(plan): reviewed` commit and the like). Any source-code change means the reviewed verdict is stale and the new code is unreviewed: stop, run `04` on the current diff, looping back to `03` on `iterate`. If no verdict exists or it is `iterate`, stop the same way. Code is never shipped unreviewed. -2. **Commit.** Invoke a commit capability, discovered at runtime, briefing it with the plan's objective. It writes the message per its own convention; never dictate a format here. +2. **Commit.** Invoke a commit capability, discovered at runtime, with the plan's objective. It picks the message format; never dictate one here. 3. **Open.** Invoke a change-request capability, discovered at runtime, to push the branch and open the request. Reference the plan path in the body. 4. **Return.** Surface the commit SHA and the change-request URL. diff --git a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md index 8e162be5..b744f5f0 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md +++ b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md @@ -12,7 +12,7 @@ A pass or fail verdict: every applicable assertion passing in a final clean swee ## Process -1. **Enumerate.** From the project conventions and the coding-assertions memory (`aidd_docs/memory/coding-assertions.md`) when it exists, list the assertions that apply to the work. +1. **Enumerate.** List the assertions that apply, from the project conventions and `aidd_docs/memory/coding-assertions.md` when it exists. 2. **Iterate.** For each assertion, fix what blocks it, then re-run it until it passes. 3. **Sweep.** Once each has passed at least once, re-run them all in one pass to confirm none regressed. 4. **Boundary.** Do not stop until every assertion passes the final sweep. diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md index 18654d51..102071c5 100644 --- a/plugins/aidd-vcs/skills/01-commit/SKILL.md +++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md @@ -26,7 +26,7 @@ When invoked as a slash command, the trailing argument controls the push behavio ## Transversal rules -- Project first: follow the VCS practices in `aidd_docs/memory/vcs.md` when it exists (message convention, scopes, branch naming). The rules below and the template are the fallback. +- Project first: follow `aidd_docs/memory/vcs.md` when it exists (message convention, scopes, branch naming); the rules below and the template are the fallback. - Commits stay atomic and focused on a single concern. - Messages use imperative mood ("Add feature" not "Added feature"). - Explain "why" not "what" in the body. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md index 373d8a3d..33238b71 100644 --- a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md +++ b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md @@ -14,7 +14,7 @@ The new commit sha, the branch, and whether it was pushed. 1. **Branch.** Use the checked-out branch. In `auto`, generate a conventional name from the change; in `interactive`, propose one and wait for approval. 2. **Stage.** With explicit paths, `git add` exactly those. Otherwise commit the already-staged changes, never staging unstaged paths implicitly. -3. **Message.** Use an imposed message verbatim when given. Otherwise follow the project's convention in `aidd_docs/memory/vcs.md` when set, else `@../assets/commit-template.md`. In `auto`, generate one from the diff and recent log, no approval. In `interactive`, draft one and confirm. +3. **Message.** Use an imposed message verbatim. Else follow `aidd_docs/memory/vcs.md` when set, otherwise `@../assets/commit-template.md`. In `auto`, generate from the diff and log, no approval; in `interactive`, draft and confirm. 4. **Split.** In `interactive` with several concerns, propose each split (its scope, and a draft message that explains why, never lists files), wait for approval, and stage each with `git add -p`. 5. **Commit.** Run `git commit` with the chosen message. 6. **Recover.** On a pre-commit hook failure, fix the cause, re-stage, and make a new commit, never amend. Loop until it succeeds. diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 8b3fdedc..90943a6c 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -19,7 +19,7 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph ## Transversal rules -- Project first: follow the request practices in `aidd_docs/memory/vcs.md` and the repo's own request-template file when they exist (body sections, base-branch rules, labels). The rules below and the bundled templates are the fallback. +- Project first: follow `aidd_docs/memory/vcs.md` and the repo's own request-template file when they exist (body sections, base rules, labels); the rules below and the bundled templates are the fallback. - Resolve the base branch from the head branch's prefix via the project's branch-naming convention (project memory); fall back to repo state when no prefix mapping exists. Never assume `main` or `master` (common alternatives: `next`, `develop`, `staging`). - Always ask the user to validate the title, body, and base branch before creating the request. - Open the request as a draft. The user promotes it manually when ready. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md index 3ca93ace..e09f008e 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md @@ -16,7 +16,7 @@ The draft request's URL and number, with its head and resolved base branch. 2. **Head.** Read the current branch with `git rev-parse --abbrev-ref HEAD`. 3. **Base.** Resolve the base in order: a provided base; otherwise the target the head branch's prefix maps to in the project's branch-naming convention (for example `feat/` → `next`, `hotfix/` → `main`); otherwise `git symbolic-ref refs/remotes/origin/HEAD`, then `main`, `master`, `develop`, `staging`. Surface the chosen base and the reason. 4. **Collect.** Summarize the commits and impacted files with `git log ..HEAD` and `git diff ...HEAD --stat`. -5. **Fill.** Load the request template, preferring the project's own (`aidd_docs/memory/vcs.md` or the repo's request-template file, wherever the configured tool keeps it) and falling back to the bundled one, plus any contributing rules, then write a concise title and a body following it from the change summary. +5. **Fill.** Load the request template, preferring the project's own (`aidd_docs/memory/vcs.md` or the repo's request-template file) over the bundled one, plus any contributing rules; write a concise title and body from the change summary. 6. **Validate.** Show the title, body, and detected base. Apply any overrides, then wait for explicit approval. 7. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body. Capture the URL and number. 8. **Label.** When the head prefix maps to a triage label that exists in the repo, apply it (for example `feat/` → `enhancement`). Skip silently otherwise. Labels triage only; they never change the base. From bc1a3188dddf1cf44a671088280dc6bbf67bb298 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 21:12:56 +0200 Subject: [PATCH 41/42] refactor(dev,vcs): close skill-authoring audit findings on the flow An independent audit against the skill-authoring contract surfaced one major and seven minor violations across the flow skills. Fixes: - 02-implement/02-execute: drop "via the `commit` skill" so aidd-dev no longer names an aidd-vcs skill; it discovers the commit capability at runtime, matching 05-ship and 03-finalize (cross-plugin orthogonality). - 01-plan and 03-assert: collapse multi-word step labels to the one-word bold lead the action anatomy requires. - 02-pull-request: drop the orphan CONTRIBUTING.md and README.md assets (project-scaffolding scope, never loaded here) and regenerate CATALOG. - 02-implement/blocked: blank line after the heading, split the run-on. - 01-commit: rewrite the router subtitle so it stops restating the description and drops the gerund. No behavior change; routing and outputs are unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../skills/01-plan/actions/01-gather.md | 4 +- .../skills/01-plan/actions/02-explore.md | 6 +- .../skills/01-plan/actions/03-wireframe.md | 2 +- .../skills/02-implement/actions/02-execute.md | 2 +- .../skills/02-implement/references/blocked.md | 3 +- .../03-assert/actions/03-assert-frontend.md | 4 +- plugins/aidd-vcs/CATALOG.md | 4 +- plugins/aidd-vcs/skills/01-commit/SKILL.md | 2 +- .../aidd-vcs/skills/02-pull-request/SKILL.md | 4 +- .../02-pull-request/assets/CONTRIBUTING.md | 67 ------------------- .../skills/02-pull-request/assets/README.md | 33 --------- 11 files changed, 14 insertions(+), 117 deletions(-) delete mode 100644 plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md delete mode 100644 plugins/aidd-vcs/skills/02-pull-request/assets/README.md diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md index becde37e..22d9571c 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md +++ b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md @@ -12,8 +12,8 @@ The source restated in a few bullets: what is asked and the hard constraints it ## Process -1. **Find the source.** Identify what the request points to: a file path, a ticket URL or id, or raw text. When nothing concrete is given, ask once for a file, a ticket, or a description. Do not start without a source. -2. **Pull it in.** Read the file, fetch the ticket, or take the text as given. Never invent content the source does not contain. +1. **Find.** Identify what the request points to: a file path, a ticket URL or id, or raw text. When nothing concrete is given, ask once for a file, a ticket, or a description. Do not start without a source. +2. **Pull.** Read the file, fetch the ticket, or take the text as given. Never invent content the source does not contain. 3. **Restate.** Summarize the source in a few bullets: what is asked, and the hard constraints it states. No solution, no phases, no plan. ## Test diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md index 8f3226d7..33a6916d 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md +++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md @@ -12,9 +12,9 @@ The architecture projection (files to modify, create, delete, each with a one-li ## Process -1. **Read the codebase.** Explore the code the source touches. Build the projection and list the infrastructure assumptions. -2. **Check feasibility.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks. -3. **Select rules.** Keep the project rules that apply to the projection. +1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions. +2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks. +3. **Select.** Keep the project rules that apply to the projection. ## Test diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md index 5aa3bf1a..53d8b3a5 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md +++ b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md @@ -12,7 +12,7 @@ A low-fidelity ASCII wireframe of each screen, its regions and key elements in p ## Process -1. **Pick the screens.** List the screens the feature needs. Skip the action entirely when there is no UI. +1. **Pick.** List the screens the feature needs. Skip the action entirely when there is no UI. 2. **Draw.** Sketch each screen per `@../references/wireframe-conventions.md`. The wireframe feeds the plan. ## Test 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 c32d305b..dc020553 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -14,7 +14,7 @@ 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. Only once it passes, set `status: done` and commit the phase as one unit, its code and its status together, via the `commit` skill. +3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Only once it passes, set `status: done` and commit the phase as one unit, its code and its status together. 4. **Blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. 5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch, trivial or substantive, stop and report `replan needed: ` to the caller. Replanning is the caller's job, not this recipe's. diff --git a/plugins/aidd-dev/skills/02-implement/references/blocked.md b/plugins/aidd-dev/skills/02-implement/references/blocked.md index 3bdd7dc6..505a3389 100644 --- a/plugins/aidd-dev/skills/02-implement/references/blocked.md +++ b/plugins/aidd-dev/skills/02-implement/references/blocked.md @@ -4,6 +4,7 @@ description: Conditions that make a plan blocked (needs a human). --- # When a plan is blocked -`blocked` = implementation cannot proceed; only a human can unblock. Stop, set `status: blocked`, escalate. + +`blocked` means implementation cannot proceed and only a human can unblock it. Stop, set `status: blocked`, and escalate. Physically impossible for the AI (no retry helps): real credit-card payment; human login (Google OAuth, Apple Face/Touch ID); a secret the AI cannot read; anything behind hardware or 2FA. diff --git a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md index 80a2e02d..c26d9bc4 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md +++ b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md @@ -12,12 +12,12 @@ A pass or fail verdict, with the per-iteration attempts (hypothesis, fix, result ## Process -1. **Resolve the URL.** Use the one the caller gave, otherwise find the running frontend and confirm it responds. Skip this facet with a noted reason when none is running. +1. **Resolve.** Use the URL the caller gave, otherwise find the running frontend and confirm it responds. Skip this facet with a noted reason when none is running. 2. **Parse.** Extract the visual, functional, and technical requirements from the expected behavior. Trace the action paths, for example a click calls a function in one file that updates state in another. 3. **Inspect.** Open the URL with the project's configured browser tool and navigate to the screen the expected behavior targets. Inspect the page visually and technically, capturing a screenshot of the issue. 4. **Locate.** Explore the codebase for the files behind the issue. 5. **Track.** Fill the tracking file from `@../assets/task-template.md` with the three best candidate causes, each with a short description and a confidence level. -6. **Fix loop.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. +6. **Fix.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. 7. **Boundary.** Never start or restart a server. Accept minor visual differences (1 to 2 px, slight color) unless the request specifies otherwise. Confirm every UI change with a screenshot. ## Test diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index ed17d8e0..d8f484c3 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -49,11 +49,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-pull-request.md](skills/02-pull-request/actions/01-pull-request.md) | - | | `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` | -| `assets` | [CONTRIBUTING.md](skills/02-pull-request/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | | `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | -| `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | | `-` | [README.md](skills/02-pull-request/README.md) | - | -| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`.` | +| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use to open a PR/MR ("open a pr", `/pull-request`). Do NOT use to commit, push, or merge a branch.` | #### `skills/03-release-tag` diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md index 102071c5..2f5168e8 100644 --- a/plugins/aidd-vcs/skills/01-commit/SKILL.md +++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md @@ -5,7 +5,7 @@ description: Create an atomic git commit with a conventional message, optionally # Commit -Generates atomic git commits with conventional messages, supporting interactive splits and agent-driven auto mode. +Runs interactive with split approval, or auto for agents. ## Actions diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 90943a6c..af224d27 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -30,6 +30,4 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph ## Assets - `@assets/pull_request.md`: Request body template. -- `@assets/branch.md`: Branch naming conventions. -- `@assets/CONTRIBUTING.md`: Contribution guidelines template. -- `@assets/README.md`: README template. +- `@assets/branch.md`: Branch-naming convention, the fallback when project memory sets none. diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md b/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md deleted file mode 100644 index 516531f5..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -name: contributing -description: Project contribution guidelines template -argument-hint: N/A ---- - -# Contributing to [Project Name] - -Welcome to the [Project Name] contribution guide! We appreciate your interest in helping us improve and grow this project. This document outlines how you can contribute effectively. - -> [Vision Statement or Mission of the Project, our Why] - -## 📐 Contributing Guidelines - -- Who can contribute? -- Roles and responsibilities? -- Code of conduct... - -## ❓ What can YOU do to help? - - - -### - -1. ... - -## 📌 Where are features to build? - -[...] - -## 💠 Onboarding in the Contributing flow - -### Documentation links - -- [](./) - -### Pre-requisites environment setup (optional) - -[...] - -### Steps to follow - -1. ... - -## 🌲 Branch naming - -- - -## 👌 Commit Guidelines - -- - -## 🧪 Testing Guidelines - -- ... - -## 🚀 Publishing (Maintainers Only) - -### Authentication Setup - -### Process to Publish diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/README.md b/plugins/aidd-vcs/skills/02-pull-request/assets/README.md deleted file mode 100644 index 35c3efaa..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/README.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: readme -description: Project README template -argument-hint: N/A ---- - -# [Project Name] - -[Summary] - -## Installation Process - -## Usage - -## Access - -## Development Workflow - -## Documentation Structure - -| File | Description | -| ----- | ----------- | -| `...` | ... | - -## Common issues - -### Troubleshooting - -## 📄 License - -## Contributing - -We welcome contributions from the community. Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute. From 7e735bbc562b142178b2281dfd1a765d5f004a49 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Wed, 24 Jun 2026 21:18:10 +0200 Subject: [PATCH 42/42] fix(pm): drop leaked user-stories WIP that duplicates the real skill A stray plugins/aidd-pm/skills/02-user-stories/SKILL.md (SKILL.md only, no actions) was swept into an unrelated commit from a local stash. It duplicates the complete 02-user-stories-create skill already on next and is broken on its own. Remove it; regenerate the catalog. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-pm/CATALOG.md | 7 ---- .../aidd-pm/skills/02-user-stories/SKILL.md | 40 ------------------- 2 files changed, 47 deletions(-) delete mode 100644 plugins/aidd-pm/skills/02-user-stories/SKILL.md diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index 513ff7df..d4a73cbd 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -9,7 +9,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`.claude-plugin`](#claude-plugin) - [`skills`](#skills) - [`skills/01-ticket-info`](#skills01-ticket-info) - - [`skills/02-user-stories`](#skills02-user-stories) - [`skills/02-user-stories-create`](#skills02-user-stories-create) - [`skills/03-prd`](#skills03-prd) - [`skills/04-spec`](#skills04-spec) @@ -32,12 +31,6 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `-` | [README.md](skills/01-ticket-info/README.md) | - | | `-` | [SKILL.md](skills/01-ticket-info/SKILL.md) | `Retrieve and display ticket information from the configured ticketing tool. Use when the user says "ticket info", "show ticket", "get ticket", "ticket details", "what's ", or invokes `/ticket-info`. Do NOT use for creating issues, commenting on tickets, changing status, or reassigning.` | -#### `skills/02-user-stories` - -| File | Description | -|------|---| -| [SKILL.md](skills/02-user-stories/SKILL.md) | `Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog saved to the project's tracker. Use for "user stories", "split this epic", "break down this feature", "estimate/prioritize the backlog", or `/user-stories`. Not for source code or a full PRD (use `03-prd`).` | - #### `skills/02-user-stories-create` | Group | File | Description | diff --git a/plugins/aidd-pm/skills/02-user-stories/SKILL.md b/plugins/aidd-pm/skills/02-user-stories/SKILL.md deleted file mode 100644 index 7293d298..00000000 --- a/plugins/aidd-pm/skills/02-user-stories/SKILL.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -name: 02-user-stories -description: Turn a feature or epic into a prioritized, estimated, INVEST-compliant user-story backlog saved to the project's tracker. Use for "user stories", "split this epic", "break down this feature", "estimate/prioritize the backlog", or `/user-stories`. Not for source code or a full PRD (use `03-prd`). ---- - -# User Stories - -Produces a prioritized backlog of INVEST-compliant user stories, each estimated for effort and impact and carrying a pragmatic functional Definition of Done, then saved to the project's configured tracker. - -## Available actions - -| # | Action | Role | Input | -| --- | ----------------- | -------------------------------------------------------------------- | -------------------------------------- | -| 01 | `clarify-scope` | Clarify the request through Product Owner questioning; decide epic vs single story | feature or epic description | -| 02 | `split-epic` | Decompose the confirmed scope into candidate vertical-slice stories | confirmed scope from 01 | -| 03 | `draft-stories` | Write each candidate as an INVEST story with acceptance criteria and a functional DoD | candidate stories from 02 | -| 04 | `estimate-impact` | Rate each story for effort (points) and impact on the existing system | drafted stories from 03 | -| 05 | `prioritize` | Rank the backlog by value against effort and impact | estimated stories from 04 | -| 06 | `sync-tracker` | Gate on Definition of Ready, get explicit approval, save to the tracker | ranked backlog from 05 | - -## Default flow - -Sequential chain `01 → 02 → 03 → 04 → 05 → 06`; run each action's `## Test` before the next. When 01 finds a single story rather than an epic, `02-split-epic` passes it through unchanged. - -## Transversal rules - -- **INVEST**: each story is Independent, Negotiable, Valuable, Estimable, Small, Testable. -- **Definition of Ready**: acceptance criteria, dependencies, story points, and an impact rating are set, with zero blocking questions, before save. -- **Definition of Done**: each story carries a pragmatic, functional DoD — observable, user-facing conditions that mean the goal is met. Functional only, never technical delivery steps. -- **Lean clarification**: at most 3 questions per iteration; focus on user needs, not technical aspects. -- Always wait for explicit user validation before saving to the tracker. -- The save target is the configured ticketing tool from project memory; never assume a specific tool. - -## References - -- `@references/rating.md`: INVEST, the Definition of Ready and functional Definition of Done, the minor/major/critic impact scale, and the prioritization method. - -## Assets - -- `@assets/user-story-template.md`: user story body template.