From 516b517baae0b76afc6359a5992fa943055f1b40 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Mon, 15 Jun 2026 15:48:38 +0200 Subject: [PATCH 1/8] refactor(aidd-dev): redesign 01-plan around 02-design (replaces components-behavior + image-extract) Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 6 +- plugins/aidd-dev/skills/01-plan/README.md | 26 +++--- plugins/aidd-dev/skills/01-plan/SKILL.md | 21 +++-- .../01-plan/actions/02-components-behavior.md | 35 -------- .../skills/01-plan/actions/02-design.md | 28 +++++++ .../actions/03-image-extract-details.md | 79 ------------------- .../skills/01-plan/evals/scenarios.json | 14 ++++ 7 files changed, 66 insertions(+), 143 deletions(-) delete mode 100644 plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md create mode 100644 plugins/aidd-dev/skills/01-plan/actions/02-design.md delete mode 100644 plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md create mode 100644 plugins/aidd-dev/skills/01-plan/evals/scenarios.json diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 770f3553..82704e04 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -56,14 +56,14 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | Argument Hint | |-------|------|---|---| | `actions` | [01-plan.md](skills/01-plan/actions/01-plan.md) | - | - | -| `actions` | [02-components-behavior.md](skills/01-plan/actions/02-components-behavior.md) | - | - | -| `actions` | [03-image-extract-details.md](skills/01-plan/actions/03-image-extract-details.md) | - | - | +| `actions` | [02-design.md](skills/01-plan/actions/02-design.md) | - | - | | `assets` | [master-plan-template.md](skills/01-plan/assets/master-plan-template.md) | `Parent plan template orchestrating multiple child plans with validation gates` | - | | `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file.` | - | | `assets` | [tech-choice-template.md](skills/01-plan/assets/tech-choice-template.md) | `Technology selection and comparison template` | - | +| `evals` | [scenarios.json](skills/01-plan/evals/scenarios.json) | - | - | | `-` | [README.md](skills/01-plan/README.md) | - | - | | `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).` | - | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, define component behaviors, and extract design details from images.` | - | +| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, and define a frontend page's design - component behaviors as state machines plus the dumb/smart split that delegates the visual to the design tool.` | - | #### `skills/02-implement` diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md index 9962491a..fce3eab4 100644 --- a/plugins/aidd-dev/skills/01-plan/README.md +++ b/plugins/aidd-dev/skills/01-plan/README.md @@ -2,19 +2,18 @@ # 01 - plan -Generates technical implementation plans, defines component behaviors as -state machines, and extracts structured component inventories from design -images. The plan file is the single source of truth that downstream skills -(`02-implement`, `05-review`) consume. +Generates technical implementation plans, and defines a frontend page's +design - component behaviors as state machines plus the dumb/smart split that +delegates the visual to the design tool. The plan file is the single source of +truth that downstream skills (`02-implement`, `05-review`) consume. ## When to use - A validated spec or ticket exists and you need a phased plan with milestones, rules, and acceptance criteria before any code change. -- A frontend component needs its behavior pinned down as a state machine - before implementation. -- A design image (Figma export, mockup, screenshot) needs to be turned into - a hierarchical component inventory. +- A frontend page/feature needs its design pinned down before implementation: + component behavior (state machines), the dumb/smart split, and whether to + render it. ## When NOT to use @@ -30,19 +29,18 @@ images. The plan file is the single source of truth that downstream skills Use skill aidd-dev:01-plan ``` -The skill exposes 3 actions: +The skill exposes 2 actions: 1. `plan` - produce a phased implementation plan from a spec or ticket. -2. `components-behavior` - define a component's behavior as a state machine. -3. `image-extract-details` - analyze a design image and emit a hierarchical - component inventory. +2. `design` - define a frontend page's design: component behavior (state + machines), the dumb/smart split, and the render decision. ## Outputs - A plan file in `aidd_docs/plans/` with frontmatter, M/C/D (must / could / done), rules table, and ordered phases. -- A state-machine description (Mermaid) for the target component. -- A structured component inventory derived from the image source. +- A frontend page design: state machines (Mermaid), the dumb/smart split, and + the render flag. ## Prerequisites diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index a951e4fc..9ffbd894 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: Generate technical implementation plans, define component behaviors, and extract design details from images. +description: Generate technical implementation plans, and define a frontend page's design - component behaviors as state machines plus the dumb/smart split that delegates the visual to the design tool. model: opus context: fork agent: planner @@ -8,7 +8,7 @@ agent: planner # Skill: plan -Produces implementation plans from requirements, state machines for component behavior, and structured component inventories from design images. +Produces implementation plans from requirements, and a frontend page's design: component behavior as state machines, the dumb/smart split, and the render decision. ## Agent delegation @@ -16,24 +16,21 @@ Spawn the `planner` agent to execute this skill. For tools that do not support ` ## Available actions -| # | Action | When to use | -| --- | ------------------------ | --------------------------------------------------------------------------- | -| 01 | `plan` | Turn requirements into a technical implementation plan saved to a task file | -| 02 | `components-behavior` | Define a frontend component's behavior as a state machine (Mermaid) | -| 03 | `image-extract-details` | Analyze a design image into a hierarchical component inventory | +| # | Action | When to use | +| --- | ---------- | ------------------------------------------------------------------------------------ | +| 01 | `plan` | Turn requirements into a technical implementation plan saved to a task file | +| 02 | `design` | Define a frontend page's design: component behavior (state machines) + dumb/smart split + render decision | ## Routing (run first) The planner auto-adapts to the INPUT - do not ask the user to choose. Detect the input type and route; do NOT always fall to action 01. -- A design image or mockup is provided -> `03-image-extract-details` (then feed the inventory into planning). -- The request is about a frontend component's behavior, states, or transitions -> `02-components-behavior`. +- The request is about a frontend page/feature's design - component behavior, states, the dumb/smart split, or whether to render -> `02-design`. - Anything else (requirements, a feature to build) -> `01-plan`. -Actions may chain (e.g. extract from image, then plan). Read and follow each selected action file. +Actions may chain (e.g. design the page, then plan its build). Read and follow each selected action file. ## Actions - `@actions/01-plan.md` -- `@actions/02-components-behavior.md` -- `@actions/03-image-extract-details.md` +- `@actions/02-design.md` diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md b/plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md deleted file mode 100644 index 2f4efbc5..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/02-components-behavior.md +++ /dev/null @@ -1,35 +0,0 @@ -# 02 - Components behavior - -Define the expected behavior of one or more frontend components as state machines, rendered in Mermaid syntax for user validation. - -## Inputs - -```yaml -components: -``` - -## Outputs - -```yaml -state_machines: - - component: - diagram: - states: [] - transitions: [{ from: , to: , event: , condition: }] -``` - -## Process - -Iterate over the steps below until each component is fully defined. - -1. **Parse the request.** Extract the list of components from `$ARGUMENTS`. -2. **Per component**: - - Identify the key states the component can be in. - - Determine the events or actions that trigger transitions between states. - - Define the state machine in Mermaid syntax, applying `@../references/mermaid-conventions.md`. -3. **Sanity-check the model.** Confirm the state machine captures every state and every transition relevant to the component's behavior. -4. **Present the final state machines** to the user for validation. Wait for an explicit OK before exiting. - -## Test - -For each component in `components`: the corresponding `state_machines` entry has a Mermaid block that parses, lists at least two states, and every transition references states that exist in the same diagram. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-design.md b/plugins/aidd-dev/skills/01-plan/actions/02-design.md new file mode 100644 index 00000000..4e75310f --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/02-design.md @@ -0,0 +1,28 @@ +# 02 - Design + +Describe a frontend page's design before code - its components and their behavior, the dumb/smart split, the render decision - then write the **delegation prompt** that tells the implementer how to build it. + +This action describes and delegates. It writes no code, and (running under the `planner`) it does **not** spawn the implementer - the implementation side launches it with the prompt written here. + +## Input + +The page or feature to design (free text). Nothing else. + +## Output + +The page, **described**: what it is, its components and their behavior, the dumb/smart split. Plus a bullet list (or small table) of the elements covered, and the delegation prompt for the implementer. + +## Process + +1. **Describe the page.** Purpose, sections, components. Per component, its behavior (states + transitions) - the SMART layer, owned in-house. +2. **Dumb/smart split.** Mark the **presentational (dumb)** components - props in, UI out, no data/logic/routing/state. Their visual is delegated to the design tool; its `shape` defines the visual behaviors (one line, not re-specified here). +3. **Render decision.** Ask the user once: see the page rendered, or not? +4. **Write the delegation prompt** for the implementer. It must: + - Keep the smart layer (data, state, routing, wiring) in your own code. Author the visual via the design tool with quotes - never `craft` (that builds the feature): `Use skill "impeccable" with "shape - dumb/presentational, props only, tokens from DESIGN.md"`. + - **If render was requested - visual-first.** Craft the page's visual **end-to-end first**, then **verify it in-browser before any wiring**: `Use skill "impeccable" with "live"` to iterate variants until visually good, with `Use skill "impeccable" with "critique "` as the gate. Run under `/goal` (`aidd-dev:09-for-sure`): loop until **zero P0**, then explicit user OK. Only then **attach the verified visual to the code** (wire the smart layer onto it). + - **If not.** Author the dumb visuals inline and wire as you go - no `live`, no loop. +5. **Present** the description + element list + delegation prompt. Wait for an explicit OK before exiting. + +## Test + +The page is described with its components and their behavior; the dumb components are marked; the render decision is recorded; and a delegation prompt exists that builds the smart layer in-house and delegates each dumb visual to the design tool via quoted skill calls. diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md b/plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md deleted file mode 100644 index 8e985445..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/03-image-extract-details.md +++ /dev/null @@ -1,79 +0,0 @@ -# 03 - Image extract details - -Analyze an image to identify and extract the main components, group them by type, merge close variants, and emit a hierarchical inventory ready for planning. - -## Inputs - -```yaml -image: -``` - -## Outputs - -```yaml -main_reusable_components_with_variants: - - name: - variants: - - name: - style: -main_display_components: - - component_name:
- layouts: - - type: - style: - position_and_display: - components: [] -``` - -## Process - -1. **Identify reusable components.** Scan the image for repeatable UI atoms; group them by type. -2. **Extract variants.** For each reusable atom, collect distinct visual variants. Merge variants that are very close (same role, marginal styling differences). -3. **Remove duplicates.** Keep each unique component once. -4. **Hierarchical organization.** Place layout-level display components above the reusable atoms; nest layouts and their sub-components. -5. **Boundaries.** Emoji are not components. Do not detail photography. - -## Test - -`main_reusable_components_with_variants` lists each unique reusable atom exactly once with at least one variant; `main_display_components` covers every top-level section visible in the image; no entry references emoji or stock photography. - -## Output format example - -```yaml -main_reusable_components_with_variants: - - name: "Chip" - variants: - - name: "Generate" - style: "Purple text, rounded pill shape, small sparkle icon" - -main_display_components: - - component_name: Hero Section - layouts: - - type: Vertical Stack - style: "Centered alignment, full-width layout" - position_and_display: "Top of page" - components: - - type: Text Block - content: "For individuals, independent creators and tech companies" - variant: "Heading" - - type: Text Block - content: "Empowering individuals, creators, and tech innovators with cutting-edge AI solutions." - variant: "Subheading" - - - component_name: Feature Grid - layouts: - - type: Two-Column Layout - style: "Even 2-column grid, responsive layout" - position_and_display: "Below hero section" - components: - - component_name: Right Feature Card - position_and_display: "Right column" - layout: "Vertical stack" - sub_components: - - type: Text Block - content: "Don't write by yourself, it's boring. Instead, let AI" - variant: "Paragraph" - - type: Chip - content: "Enhance" - variant: "Enhance" -``` diff --git a/plugins/aidd-dev/skills/01-plan/evals/scenarios.json b/plugins/aidd-dev/skills/01-plan/evals/scenarios.json new file mode 100644 index 00000000..d9f896d5 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/evals/scenarios.json @@ -0,0 +1,14 @@ +[ + { "prompt": "Generate a technical plan for the authentication feature", "expect_action": "plan" }, + { "prompt": "Create an implementation plan from the spec", "expect_action": "plan" }, + { "prompt": "Plan the refactoring of the payment module", "expect_action": "plan" }, + { "prompt": "Design the checkout page", "expect_action": "design" }, + { "prompt": "Define component behavior and the dumb/smart split for the onboarding wizard", "expect_action": "design" }, + { "prompt": "Rédige un plan technique pour l'auth", "expect_action": "plan" }, + { "prompt": "Génère le plan d'implémentation depuis la spec", "expect_action": "plan" }, + { "prompt": "Crée le plan d'implémentation phase par phase", "expect_action": "plan" }, + { "prompt": "Conçois le design de la page checkout", "expect_action": "design" }, + { "prompt": "Write the code for the login page", "expect_action": null }, + { "prompt": "Review my pull request", "expect_action": null }, + { "prompt": "Debug the failing test in auth.test.ts", "expect_action": null } +] From f53257d73461c15b95d96afcacbccb916e1a6c91 Mon Sep 17 00:00:00 2001 From: alexsoyes Date: Thu, 18 Jun 2026 21:33:52 +0200 Subject: [PATCH 2/8] refactor: new plan with phases --- plugins/aidd-dev/CATALOG.md | 8 +- plugins/aidd-dev/skills/01-plan/README.md | 54 --------- plugins/aidd-dev/skills/01-plan/SKILL.md | 17 ++- .../skills/01-plan/actions/01-plan.md | 27 ++--- .../skills/01-plan/actions/02-design.md | 4 + .../01-plan/assets/master-plan-template.md | 45 -------- .../skills/01-plan/assets/phase-template.md | 48 ++++++++ .../skills/01-plan/assets/plan-template.md | 109 +++--------------- .../skills/01-plan/evals/scenarios.json | 14 --- .../skills/01-plan/references/phase-rules.md | 11 ++ .../skills/01-plan/references/plan-rules.md | 8 ++ 11 files changed, 114 insertions(+), 231 deletions(-) delete mode 100644 plugins/aidd-dev/skills/01-plan/README.md delete mode 100644 plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md create mode 100644 plugins/aidd-dev/skills/01-plan/assets/phase-template.md delete mode 100644 plugins/aidd-dev/skills/01-plan/evals/scenarios.json create mode 100644 plugins/aidd-dev/skills/01-plan/references/phase-rules.md create mode 100644 plugins/aidd-dev/skills/01-plan/references/plan-rules.md diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 82704e04..cc7bfee6 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -57,12 +57,12 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---|---| | `actions` | [01-plan.md](skills/01-plan/actions/01-plan.md) | - | - | | `actions` | [02-design.md](skills/01-plan/actions/02-design.md) | - | - | -| `assets` | [master-plan-template.md](skills/01-plan/assets/master-plan-template.md) | `Parent plan template orchestrating multiple child plans with validation gates` | - | -| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file.` | - | +| `assets` | [phase-template.md](skills/01-plan/assets/phase-template.md) | `Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file.` | - | +| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Parent plan template orchestrating multiple child plans with validation gates` | - | | `assets` | [tech-choice-template.md](skills/01-plan/assets/tech-choice-template.md) | `Technology selection and comparison template` | - | -| `evals` | [scenarios.json](skills/01-plan/evals/scenarios.json) | - | - | -| `-` | [README.md](skills/01-plan/README.md) | - | - | | `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` | [phase-rules.md](skills/01-plan/references/phase-rules.md) | - | - | +| `references` | [plan-rules.md](skills/01-plan/references/plan-rules.md) | - | - | | `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, and define a frontend page's design - component behaviors as state machines plus the dumb/smart split that delegates the visual to the design tool.` | - | #### `skills/02-implement` diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md deleted file mode 100644 index fce3eab4..00000000 --- a/plugins/aidd-dev/skills/01-plan/README.md +++ /dev/null @@ -1,54 +0,0 @@ -← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) - -# 01 - plan - -Generates technical implementation plans, and defines a frontend page's -design - component behaviors as state machines plus the dumb/smart split that -delegates the visual to the design tool. The plan file is the single source of -truth that downstream skills (`02-implement`, `05-review`) consume. - -## When to use - -- A validated spec or ticket exists and you need a phased plan with - milestones, rules, and acceptance criteria before any code change. -- A frontend page/feature needs its design pinned down before implementation: - component behavior (state machines), the dumb/smart split, and whether to - render it. - -## When NOT to use - -- You already have a plan and need to write code → use - [02-implement](../02-implement/README.md). -- The task is a single fix with no planning surface → use - [08-debug](../08-debug/README.md) or edit directly. -- You want spec drafting, not planning -> use the project's spec-drafting capability. - -## How to invoke - -``` -Use skill aidd-dev:01-plan -``` - -The skill exposes 2 actions: - -1. `plan` - produce a phased implementation plan from a spec or ticket. -2. `design` - define a frontend page's design: component behavior (state - machines), the dumb/smart split, and the render decision. - -## Outputs - -- A plan file in `aidd_docs/plans/` with frontmatter, M/C/D (must / could / - done), rules table, and ordered phases. -- A frontend page design: state machines (Mermaid), the dumb/smart split, and - the render flag. - -## Prerequisites - -- A validated spec, ticket, or design source as input. -- Access to the plan template asset bundled with this skill. - -## Technical details - -See [`SKILL.md`](SKILL.md) for the action list and -[`assets/plan-template.md`](assets/plan-template.md) for the canonical plan -format. Per-action contracts live in [`actions/`](actions/). diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index 9ffbd894..e6608afb 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,9 +1,10 @@ --- name: 01-plan description: Generate technical implementation plans, and define a frontend page's design - component behaviors as state machines plus the dumb/smart split that delegates the visual to the design tool. -model: opus context: fork agent: planner +model: sonnet +effort: medium --- # Skill: plan @@ -32,5 +33,15 @@ Actions may chain (e.g. design the page, then plan its build). Read and follow e ## Actions -- `@actions/01-plan.md` -- `@actions/02-design.md` +- `actions/01-plan.md` +- `actions/02-design.md` + +## References + +```markdown +@references/phase-template.md +```` + +```markdown +@references/phase-rules.md +``` \ No newline at end of file diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md b/plugins/aidd-dev/skills/01-plan/actions/01-plan.md index f5ff4230..acefc25c 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/01-plan.md @@ -25,21 +25,7 @@ applicable_rules: [{ tool: , name: , path: < ## Process 1. **Parse the input.** Detect ticket URL vs raw text. For URLs, fetch and parse ticket content. For raw text, clean and structure. Normalize text (handle vocal dictation issues). Print the user journey as a simplified ASCII diagram for validation. -2. **Score risk and impact.** Compute the score and pick the plan kind: - - Score < 3 -> simple plan (`@../assets/plan-template.md`) - - Score >= 3 -> master plan (`@../assets/master-plan-template.md` + child plans) - - | Criterion | Points | - | ------------------------------- | ------ | - | Breaking changes to public APIs | +3 | - | Database / schema migrations | +3 | - | 3+ modules affected | +2 | - | 5+ modules affected | +3 | - | Major refactoring | +2 | - | External dependency upgrades | +2 | - - Each part of the plan must be doable without the next ones (independent phases for compatibility). -3. **Validate technical assumptions** by spawning a sub-agent task to: +2. **Validate technical assumptions** by spawning a sub-agent task to: - Explore the codebase to inform plan generation. - List implicit assumptions about the user's infrastructure. - Verify API feasibility before committing to an approach. @@ -47,13 +33,13 @@ applicable_rules: [{ tool: , name: , path: < - Check assumptions against official documentation. - Produce the architecture projection (three lists, each `path - one-line reason`): files to modify, files to create, files to delete. - Inventory project rules from the user's project root; accept a silent empty array when no surface contains rules. -4. **Architecture projection and rules - user validation (gate).** +3. **Architecture projection and rules - user validation (gate).** - From the rules inventory, select rules that apply to the projection using each rule's `description` and `paths` when present. Justify every selected rule in one line. - Display: the three modify / create / delete lists; the table of applicable rules `tool | name | path | why it applies`. - Ask: "Is this projection correct? Anything to add or remove? A missing rule?" - WAIT FOR USER APPROVAL. Iterate until approved. -5. **Task planning.** Define main phases at the macro level; do not mention specific files. Wait for user validation on the phases before moving on. For each phase, list minimal, specific, actionable tasks. -6. **Generate and save the plan.** +4. **Task planning.** Define main phases at the macro level; do not mention specific files. Wait for user validation on the phases before moving on. For each phase, list minimal, specific, actionable tasks. +5. **Generate and save the plan.** - Use the current `!`date`!` for the date stamp. - Determine the feature name from the requirements. - Insert the user journey as Mermaid syntax in the plan (apply `@../references/mermaid-conventions.md`). @@ -64,9 +50,10 @@ applicable_rules: [{ tool: , name: , path: < - Master plan: `aidd_docs/tasks//-?<#ticket_number>--master.md` - Child plans: `aidd_docs/tasks//-?<#ticket_number>--part-N.md` - Display the saved file path. -7. **Quality assurance.** Verify the plan addresses every requirement; flag potential challenges; evaluate confidence (0-10) with ✓ reasons and ✗ risks; require minimum 9/10 before display; add the assessment to the plan. -8. **Display and confirm.** Show the plan, the confidence assessment, and any risks. Challenge the plan with the user. WAIT FOR USER APPROVAL. +6. **Quality assurance.** Verify the plan addresses every requirement; flag potential challenges; evaluate confidence (0-10) with ✓ reasons and ✗ risks; require minimum 9/10 before display; add the assessment to the plan. +7. **Display and confirm.** Show the plan, the confidence assessment, and any risks. Challenge the plan with the user. WAIT FOR USER APPROVAL. ## Test The plan file exists at `plan_path`; its frontmatter contains `objective`, a runnable `success_condition`, `iteration: 0`, and a valid `created_at`; the architecture projection (M / C / D) is non-empty and matches the validated lists; the applicable rules table is consistent with the project's rules inventory; confidence is `>= 9`. + diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-design.md b/plugins/aidd-dev/skills/01-plan/actions/02-design.md index 4e75310f..4388d4b5 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/02-design.md +++ b/plugins/aidd-dev/skills/01-plan/actions/02-design.md @@ -12,6 +12,10 @@ The page or feature to design (free text). Nothing else. The page, **described**: what it is, its components and their behavior, the dumb/smart split. Plus a bullet list (or small table) of the elements covered, and the delegation prompt for the implementer. +## Requirement + +`impeccable` skill installed. + ## Process 1. **Describe the page.** Purpose, sections, components. Per component, its behavior (states + transitions) - the SMART layer, owned in-house. diff --git a/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md deleted file mode 100644 index 3005ee9e..00000000 --- a/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -name: master_plan -description: Parent plan template orchestrating multiple child plans with validation gates -argument-hint: N/A ---- - - - -# Master Plan: {title} - -## Overview - -- **Goal**: {one-line summary} -- **Risk Score**: {X}/10 -- **Branch**: `{branch-prefix}/` - -## Child Plans - -| # | Plan | File | Status | Validated | -| --- | ----------- | --------------- | ------- | --------- | -| 1 | {plan-name} | `./*-part-1.md` | pending | [ ] | -| 2 | {plan-name} | `./*-part-2.md` | blocked | [ ] | - - - - -## Validation Protocol - -1. Complete Plan 1, run its validations -2. [ ] Checkpoint 1: User confirms -3. Unblock Plan 2, repeat -4. [ ] Final: Integration test - -## Estimations - -- **Confidence**: {X}/10 -- **Duration**: {estimate} diff --git a/plugins/aidd-dev/skills/01-plan/assets/phase-template.md b/plugins/aidd-dev/skills/01-plan/assets/phase-template.md new file mode 100644 index 00000000..4c0a28ee --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/assets/phase-template.md @@ -0,0 +1,48 @@ +--- +name: phase +description: Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file. +status: pending +iteration: 0 +created_at: "{YYYY-MM-DDTHH:MM:SSZ}" +--- + +# Instruction: {title} + +| Element |  Value | +| --------------- | --------------- | +| **Plan** | `{plan}/` | +| **Branch name** | `{branch-name}` | + +## Architecture projection + + + +```txt +. +``` + +## User Journey + + + +```mermaid +flowchart TD + A[TODO] +``` + +## Tasks to do + +### `{number})` {name} + +> {straight to point goal} + + + +1. {ultra concise step} + ... + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------------------------ | +| 1... | {focused deterministic verification} | diff --git a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md index 6a66d3f0..70125500 100644 --- a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md +++ b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md @@ -1,69 +1,25 @@ --- name: plan -description: Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file. -argument-hint: N/A -objective: "{What must be true when done. One sentence.}" -success_condition: "{Runnable command that proves done. Example: 'npm test exits 0 AND coverage > 80%'}" -iteration: 0 -created_at: "{YYYY-MM-DDTHH:MM:SSZ}" +description: Parent plan template orchestrating multiple child plans with validation gates +status: pending --- - +## Overview -# Instruction: {title} +| Field | Value | +| -------------- | ------------------ | +| **Goal** | {one-line summary} | +| **Risk Score** | {X}/10 | +| **Brainstorm** | `path/` (`none`) | -## Feature +## Plans -- **Summary**: {Summarize feature based plan, goal oriented} -- **Stack**: `[TECH_STACK_WITH_VERSIONS]` -- **Branch name**: `{suggested-branch-name}` -- **Parent Plan**: `{master-file}` or `none` -- **Sequence**: `{N of M}` or `standalone` -- Confidence: {Confidence} -- Time to implement: {Time to implement} - -## Architecture projection - - - -### Files to modify - -- `path/to/file.ts` - {one-line reason} - -### Files to create - -- `path/to/new-file.ts` - {one-line purpose} - -### Files to delete - -- `path/to/dead.ts` - {one-line reason} - -## Applicable rules - - - -| Tool | Name | Path | Why it applies | -| ------ | ------ | ------------------------------------- | -------------- | -| {tool} | {slug} | `//.` | {short reason} | - -## User Journey - -```mermaid -flowchart TD - A[TODO] -``` +| # | Plan | File | +| --- | ------------ | ----------------------- | +| 1 | {phase-name} | [`./1_{phase}.md`](./#) | +| 2 | {phase-name} | [`./2_{phase}.md`](./#) | ## Risk register @@ -73,37 +29,8 @@ flowchart TD | -------- | ----------------------------- | ------------------------------------- | | {risk 1} | {what breaks if this happens} | {how the plan prevents or handles it} | -## Implementation phases - -### Phase {n}: {name} - -> {straight to point goal} - -#### Tasks - -1. {ultra concise task1, with logical ordering} -2. {...} -3. {...} - -#### Acceptance criteria - -- [ ] {verifiable boolean condition 1} -- [ ] {verifiable boolean condition 2} - -## Amendments - - - -## Log - - - - - - - -## Validation flow demonstration - - +## Decisions -1. {Step 1...} +| Decision | Why | +| -------- | --- | +| | | diff --git a/plugins/aidd-dev/skills/01-plan/evals/scenarios.json b/plugins/aidd-dev/skills/01-plan/evals/scenarios.json deleted file mode 100644 index d9f896d5..00000000 --- a/plugins/aidd-dev/skills/01-plan/evals/scenarios.json +++ /dev/null @@ -1,14 +0,0 @@ -[ - { "prompt": "Generate a technical plan for the authentication feature", "expect_action": "plan" }, - { "prompt": "Create an implementation plan from the spec", "expect_action": "plan" }, - { "prompt": "Plan the refactoring of the payment module", "expect_action": "plan" }, - { "prompt": "Design the checkout page", "expect_action": "design" }, - { "prompt": "Define component behavior and the dumb/smart split for the onboarding wizard", "expect_action": "design" }, - { "prompt": "Rédige un plan technique pour l'auth", "expect_action": "plan" }, - { "prompt": "Génère le plan d'implémentation depuis la spec", "expect_action": "plan" }, - { "prompt": "Crée le plan d'implémentation phase par phase", "expect_action": "plan" }, - { "prompt": "Conçois le design de la page checkout", "expect_action": "design" }, - { "prompt": "Write the code for the login page", "expect_action": null }, - { "prompt": "Review my pull request", "expect_action": null }, - { "prompt": "Debug the failing test in auth.test.ts", "expect_action": null } -] diff --git a/plugins/aidd-dev/skills/01-plan/references/phase-rules.md b/plugins/aidd-dev/skills/01-plan/references/phase-rules.md new file mode 100644 index 00000000..2d79d1ca --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/references/phase-rules.md @@ -0,0 +1,11 @@ +# Phase rules + +- ENGLISH ONLY +- Text is straight to the point, no emojis, no style, use bullet points. +- Replace placeholders (`{variables}`) with actual user inputs. +- Define flow of the feature, from start to end. +- Interpret comments on this file to help you fill it. +- Each phase MUST have acceptance criteria. +- During implementation, the AI may amend this plan. Every AI change MUST be prefixed with 🤖 and include a brief rationale. +- `status`: set `pending` at creation (see the plan-status reference). +- Log is APPEND-ONLY. One entry per step attempt. Never rewrite history. \ No newline at end of file diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-rules.md b/plugins/aidd-dev/skills/01-plan/references/plan-rules.md new file mode 100644 index 00000000..f00f4459 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/references/plan-rules.md @@ -0,0 +1,8 @@ +# Plan rules + +- ENGLISH ONLY +- Text is straight to the point, no emojis, no style, use bullet points. +- Replace placeholders (`{variables}`) with actual user inputs. +- Each child plan uses the standard `plan.md` template format. +- Execution is sequential: next child gated until previous validated. +- Validation is manual via checkbox approval. From 0ae331e2fc4ba59244d4e57cc403275558d47e52 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 19 Jun 2026 06:35:43 +0200 Subject: [PATCH 3/8] refactor(aidd-dev): conform plan skill, ingest brainstorm, add wireframe, fail-fast implement Build on the 01-plan redesign (02-design) and carry it to completion. Plan skill: - Conform to the contract: description states what + when + Do NOT, action anatomy with prose Input/Output (no frozen YAML blocks), Test as plain bullets, consistent style. Keep the dev architecture (planner agent, Routing, Available actions). - Fix the broken References section and add the Assets section, all paths resolve. Recreate the deleted README. - Output directory is aidd_docs/tasks/ everywhere, README aligned to the action (resolves the plans/ vs tasks/ inconsistency). - Drop plan-status.md, the status lives in the template frontmatter now. New behavior: - 01-plan ingests an optional brainstorm artifact: settled decisions become constraints, conflicts surface before generating, the path is recorded. - 03-wireframe: sketch a low-fidelity ASCII screen layout before design. - 02-design's visual delegation to a UI-craft skill is optional and degrades gracefully, the action no longer hard-depends on impeccable. - 02-implement fails fast when the plan path is missing or unreadable instead of fabricating a substitute plan. Refs #292, #275, #265, #276, #288. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/CATALOG.md | 2 +- plugins/aidd-dev/CATALOG.md | 4 +- plugins/aidd-dev/README.md | 2 +- plugins/aidd-dev/skills/01-plan/README.md | 46 ++++++++++++ plugins/aidd-dev/skills/01-plan/SKILL.md | 43 +++++++----- .../skills/01-plan/actions/01-plan.md | 70 +++++++++---------- .../skills/01-plan/actions/02-design.md | 27 +++---- .../skills/01-plan/actions/03-wireframe.md | 22 ++++++ .../skills/01-plan/references/phase-rules.md | 2 +- .../02-implement/actions/01-implement.md | 14 ++-- 10 files changed, 152 insertions(+), 80 deletions(-) create mode 100644 plugins/aidd-dev/skills/01-plan/README.md create mode 100644 plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 6e06a072..456b8e18 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -32,7 +32,7 @@ The development SDLC: plan, implement, assert, audit, review, test, refactor, de | Skill | Role | Actions | | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `00-sdlc` | Pure orchestrator driving the full dev flow end to end | `01-spec`, `02-plan`, `03-implement`, `04-review`, `05-ship` | -| `01-plan` | Technical implementation plans, component behavior, image extraction | `01-plan`, `02-components-behavior`, `03-image-extract-details` | +| `01-plan` | Generate an implementation plan, design a frontend page, or wireframe a screen | `01-plan`, `02-design`, `03-wireframe` | | `02-implement` | Execute a plan phase by phase until 100% complete | `01-implement` | | `03-assert` | Assert features work - general, architecture, frontend UI | `01-assert`, `02-assert-architecture`, `03-assert-frontend` | | `04-audit` | Read-only codebase audit across quality pillars | `01-code-quality`, `02-architecture`, `03-security`, `04-dependencies`, `05-performance`, `06-tests`, `07-ui` | diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index cc7bfee6..0840e777 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -57,13 +57,15 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---|---| | `actions` | [01-plan.md](skills/01-plan/actions/01-plan.md) | - | - | | `actions` | [02-design.md](skills/01-plan/actions/02-design.md) | - | - | +| `actions` | [03-wireframe.md](skills/01-plan/actions/03-wireframe.md) | - | - | | `assets` | [phase-template.md](skills/01-plan/assets/phase-template.md) | `Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file.` | - | | `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Parent plan template orchestrating multiple child plans with validation gates` | - | | `assets` | [tech-choice-template.md](skills/01-plan/assets/tech-choice-template.md) | `Technology selection and comparison template` | - | +| `-` | [README.md](skills/01-plan/README.md) | - | - | | `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` | [phase-rules.md](skills/01-plan/references/phase-rules.md) | - | - | | `references` | [plan-rules.md](skills/01-plan/references/plan-rules.md) | - | - | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate technical implementation plans, and define a frontend page's design - component behaviors as state machines plus the dumb/smart split that delegates the visual to the design tool.` | - | +| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate a technical implementation plan from requirements, design a frontend page before building it (component behavior as state machines, the dumb/smart split, and the render decision), or sketch a low-fidelity wireframe of a screen. Use when the user wants to plan a feature, turn a ticket or requirements into an implementation plan, design a page's structure and behavior, or wireframe a screen layout. Do NOT use for writing the code (use 02-implement), reviewing a diff (use 05-review), or auditing existing code (use 04-audit).` | - | #### `skills/02-implement` diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index 349b66e1..fcc4f1a2 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -15,7 +15,7 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert | Bracket ID | Skill | Description | |---|---|---| | [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) | Generate technical implementation plans, define component behaviors, and extract design details from images. | +| [2.1] | [plan](skills/01-plan/README.md) | Generate an implementation plan from requirements, design a frontend page (behavior, dumb/smart split), or wireframe a screen at low fidelity. | | [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase via the implementer agent, 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. | diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md new file mode 100644 index 00000000..4a190021 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/README.md @@ -0,0 +1,46 @@ +← [aidd-framework](../../../../README.md) / [aidd-dev](../../README.md) + +# 01 - plan + +Generates a technical implementation plan from requirements, or designs a frontend page before building it. The plan file is the single source of truth that downstream skills (`02-implement`, `05-review`) consume. + +## When to use + +- A validated spec or ticket exists and you need a phased plan with milestones, rules, and acceptance criteria before any code change. +- A frontend page needs its design pinned down, component behavior as state machines and the dumb/smart split, before implementation. + +## When NOT to use + +- You already have a plan and need to write code → use [02-implement](../02-implement/README.md). +- The task is a single fix with no planning surface → use [08-debug](../08-debug/README.md) or edit directly. +- You want spec drafting, not planning → use the project's spec-drafting capability. + +## How to invoke + +``` +Use skill aidd-dev:01-plan +``` + +The skill exposes three actions: + +1. `plan` produces a phased implementation plan from requirements, saved to a task file. +2. `design` defines a frontend page's design, component behavior as state machines and the dumb/smart split, with a render decision and a delegation prompt for the implementer. +3. `wireframe` sketches a low-fidelity ASCII layout of a screen before designing it. + +The planner adapts to the input and routes to the right action, it does not ask the user to choose. The actions chain naturally: wireframe a screen, then design it, then plan its build. + +## Outputs + +- A plan file under `aidd_docs/tasks//`, dated and feature-named, with execution frontmatter, the architecture projection (modify, create, delete), an applicable-rules table, and ordered phases. +- A page design with the dumb/smart split and a delegation prompt that builds the smart layer in-house and delegates each dumb visual to the design tool. +- A low-fidelity ASCII wireframe of a screen, its regions labeled, for layout validation before design. + +## Prerequisites + +- Requirements, a ticket, or a page to design as input. +- The plan and phase templates bundled with this skill. +- Optional: a UI-craft skill (`impeccable`) enhances the design action's visual delegation. The design action works without it, authoring dumb visuals inline. + +## Technical details + +See [`SKILL.md`](SKILL.md) for the action list and routing, [`assets/plan-template.md`](assets/plan-template.md) for the plan format, and [`actions/`](actions/) for the per-action contracts. diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index e6608afb..d10f9ad8 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: Generate technical implementation plans, and define a frontend page's design - component behaviors as state machines plus the dumb/smart split that delegates the visual to the design tool. +description: Generate a technical implementation plan from requirements, design a frontend page before building it (component behavior as state machines, the dumb/smart split, and the render decision), or sketch a low-fidelity wireframe of a screen. Use when the user wants to plan a feature, turn a ticket or requirements into an implementation plan, design a page's structure and behavior, or wireframe a screen layout. Do NOT use for writing the code (use 02-implement), reviewing a diff (use 05-review), or auditing existing code (use 04-audit). context: fork agent: planner model: sonnet @@ -9,39 +9,44 @@ effort: medium # Skill: plan -Produces implementation plans from requirements, and a frontend page's design: component behavior as state machines, the dumb/smart split, and the render decision. +Produces an implementation plan from requirements, or a frontend page's design (component behavior as state machines, the dumb/smart split, and the render decision). Never writes code. ## Agent delegation -Spawn the `planner` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `planner` agent explicitly with this skill's content as the prompt. +Spawn the `planner` agent to execute this skill. For tools that do not support `context: fork` frontmatter, invoke the `planner` agent explicitly with this skill's content as the prompt. ## Available actions -| # | Action | When to use | -| --- | ---------- | ------------------------------------------------------------------------------------ | -| 01 | `plan` | Turn requirements into a technical implementation plan saved to a task file | -| 02 | `design` | Define a frontend page's design: component behavior (state machines) + dumb/smart split + render decision | +| # | Action | When to use | +| --- | ----------- | ------------------------------------------------------------------------------------------- | +| 01 | `plan` | Turn requirements into a technical implementation plan saved to a task file | +| 02 | `design` | Define a frontend page's design: component behavior as state machines, the dumb/smart split, the render decision | +| 03 | `wireframe` | Sketch a low-fidelity ASCII layout of a screen before designing it | ## Routing (run first) -The planner auto-adapts to the INPUT - do not ask the user to choose. Detect the input type and route; do NOT always fall to action 01. +The planner adapts to the INPUT, it does not ask the user to choose. Detect the input type and route, never fall to action 01 by default. -- The request is about a frontend page/feature's design - component behavior, states, the dumb/smart split, or whether to render -> `02-design`. -- Anything else (requirements, a feature to build) -> `01-plan`. +- The request is to sketch, lay out, or wireframe a screen at low fidelity, before any design → `03-wireframe`. +- The request is about a frontend page or feature's design, its component behavior, states, the dumb/smart split, or whether to render → `02-design`. +- Anything else, requirements or a feature to build → `01-plan`. -Actions may chain (e.g. design the page, then plan its build). Read and follow each selected action file. +Actions may chain, for example wireframe a screen, then design it, then plan its build. Read and follow each selected action file. ## Actions -- `actions/01-plan.md` -- `actions/02-design.md` +- `@actions/01-plan.md` +- `@actions/02-design.md` +- `@actions/03-wireframe.md` ## References -```markdown -@references/phase-template.md -```` +- `@references/plan-rules.md`: rules every plan file obeys. +- `@references/phase-rules.md`: rules every phase obeys. +- `@references/mermaid-conventions.md`: conventions for the Mermaid diagrams a plan embeds. -```markdown -@references/phase-rules.md -``` \ No newline at end of file +## Assets + +- `@assets/plan-template.md`: the plan file skeleton. +- `@assets/phase-template.md`: the per-phase skeleton. +- `@assets/tech-choice-template.md`: the skeleton for documenting a technical choice. diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md b/plugins/aidd-dev/skills/01-plan/actions/01-plan.md index acefc25c..0f7966e5 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/01-plan.md @@ -2,58 +2,52 @@ Generate a technical implementation plan from requirements, save it to a task file, display it for review, and wait for explicit user confirmation. Never code anything. -## Inputs - -```yaml -requirements: -ticket_number: # optional; inferred when the input is a ticket URL -``` - -## Outputs - -```yaml -plan_path: aidd_docs/tasks//-?<#ticket_number>-(-master|-part-N)?.md -plan_kind: simple | master -confidence: 0-10 -architecture_projection: - modify: [] - create: [] - delete: [] -applicable_rules: [{ tool: , name: , path: , why: }] -``` +## Input + +Requirements as a ticket URL or raw text, passed via `$ARGUMENTS`. The ticket number is optional and inferred when the input is a ticket URL. Optionally, a brainstorm artifact under `aidd_docs/brainstorm/` carrying settled decisions and flagged-open assumptions for the feature. + +## Output + +A plan file saved under `aidd_docs/tasks//`, named `-?<#ticket_number>-` with an optional `-master` or `-part-N` suffix. It carries execution frontmatter (`objective`, a runnable `success_condition`, `iteration: 0`, `created_at`), the validated architecture projection (files to modify, create, and delete, each with a one-line reason), the applicable-rules table, the source brainstorm path, and a confidence score. ## Process 1. **Parse the input.** Detect ticket URL vs raw text. For URLs, fetch and parse ticket content. For raw text, clean and structure. Normalize text (handle vocal dictation issues). Print the user journey as a simplified ASCII diagram for validation. -2. **Validate technical assumptions** by spawning a sub-agent task to: +2. **Ingest the brainstorm, if any.** When a brainstorm artifact is passed, or one exists under `aidd_docs/brainstorm/` for this feature, read it. Treat its **settled** decisions as constraints the plan must honor. Hold its flagged-open assumptions as risks to carry. Record the artifact path for the plan's Brainstorm field. If no artifact exists, continue with `none`. +3. **Validate technical assumptions.** Spawn a sub-agent task to: - Explore the codebase to inform plan generation. - List implicit assumptions about the user's infrastructure. - Verify API feasibility before committing to an approach. - Flag blockers and risks that will arise if not addressed. - Check assumptions against official documentation. - - Produce the architecture projection (three lists, each `path - one-line reason`): files to modify, files to create, files to delete. - - Inventory project rules from the user's project root; accept a silent empty array when no surface contains rules. -3. **Architecture projection and rules - user validation (gate).** + - Produce the architecture projection, three lists (files to modify, to create, to delete), each entry a path and a one-line reason. + - Inventory project rules from the user's project root. Accept a silent empty array when no surface contains rules. +4. **Architecture projection and rules, user validation (gate).** - From the rules inventory, select rules that apply to the projection using each rule's `description` and `paths` when present. Justify every selected rule in one line. - - Display: the three modify / create / delete lists; the table of applicable rules `tool | name | path | why it applies`. + - Display the three modify, create, and delete lists, and the table of applicable rules `tool | name | path | why it applies`. + - Surface any conflict between a settled brainstorm decision and this projection now, before generating, never silently diverge from it. - Ask: "Is this projection correct? Anything to add or remove? A missing rule?" - - WAIT FOR USER APPROVAL. Iterate until approved. -4. **Task planning.** Define main phases at the macro level; do not mention specific files. Wait for user validation on the phases before moving on. For each phase, list minimal, specific, actionable tasks. -5. **Generate and save the plan.** + - Wait for user approval. Iterate until approved. +5. **Task planning.** Define main phases at the macro level, without naming specific files. Wait for user validation on the phases before moving on. For each phase, list minimal, specific, actionable tasks. +6. **Generate and save the plan.** - Use the current `!`date`!` for the date stamp. - Determine the feature name from the requirements. - - Insert the user journey as Mermaid syntax in the plan (apply `@../references/mermaid-conventions.md`). - - Fill the chosen template, including the validated architecture projection and applicable rules. - - Fill execution frontmatter (required - the plan IS the For Sure tracking file): `objective`, `success_condition` (a runnable command; reject vague conditions), `iteration: 0`, `created_at` (ISO 8601 from step 1). - - Save to disk: - - Simple plan: `aidd_docs/tasks//-?<#ticket_number>-.md` - - Master plan: `aidd_docs/tasks//-?<#ticket_number>--master.md` - - Child plans: `aidd_docs/tasks//-?<#ticket_number>--part-N.md` + - Insert the user journey as Mermaid syntax in the plan, applying `@../references/mermaid-conventions.md`. + - Fill the chosen template with the validated architecture projection, applicable rules, and the brainstorm path (or `none`). + - Fill execution frontmatter, required because the plan is the For Sure tracking file: `objective`, `success_condition` (a runnable command, reject vague conditions), `iteration: 0`, `created_at` (ISO 8601 from step 1). + - Save to disk under `aidd_docs/tasks//`: + - Simple plan: `-?<#ticket_number>-.md` + - Master plan: `-?<#ticket_number>--master.md` + - Child plans: `-?<#ticket_number>--part-N.md` - Display the saved file path. -6. **Quality assurance.** Verify the plan addresses every requirement; flag potential challenges; evaluate confidence (0-10) with ✓ reasons and ✗ risks; require minimum 9/10 before display; add the assessment to the plan. -7. **Display and confirm.** Show the plan, the confidence assessment, and any risks. Challenge the plan with the user. WAIT FOR USER APPROVAL. +7. **Quality assurance.** Verify the plan addresses every requirement and honors every settled brainstorm decision. Flag potential challenges. Evaluate confidence from 0 to 10 with ✓ reasons and ✗ risks. Require a minimum of 9 before display. Add the assessment to the plan. +8. **Display and confirm.** Show the plan, the confidence assessment, and any risks. Challenge the plan with the user. Wait for user approval. ## Test -The plan file exists at `plan_path`; its frontmatter contains `objective`, a runnable `success_condition`, `iteration: 0`, and a valid `created_at`; the architecture projection (M / C / D) is non-empty and matches the validated lists; the applicable rules table is consistent with the project's rules inventory; confidence is `>= 9`. - +- The plan file exists under `aidd_docs/tasks//` with the expected name. +- Its frontmatter carries `objective`, a runnable `success_condition`, `iteration: 0`, and a valid `created_at`. +- The architecture projection (modify, create, delete) is non-empty and matches the validated lists. +- The applicable-rules table is consistent with the project's rules inventory. +- When a brainstorm artifact was ingested, its path is recorded and no settled decision is contradicted without being surfaced. +- Confidence is at least 9. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-design.md b/plugins/aidd-dev/skills/01-plan/actions/02-design.md index 4388d4b5..dbcb9d09 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/02-design.md +++ b/plugins/aidd-dev/skills/01-plan/actions/02-design.md @@ -1,8 +1,10 @@ # 02 - Design -Describe a frontend page's design before code - its components and their behavior, the dumb/smart split, the render decision - then write the **delegation prompt** that tells the implementer how to build it. +Describe a frontend page's design before code, its components and their behavior, the dumb/smart split, and the render decision, then write the **delegation prompt** that tells the implementer how to build it. -This action describes and delegates. It writes no code, and (running under the `planner`) it does **not** spawn the implementer - the implementation side launches it with the prompt written here. +This action describes and delegates. It writes no code, and running under the `planner` it does **not** spawn the implementer. The implementation side launches it with the prompt written here. + +The visual delegation is optional and degrades gracefully. When a UI-craft skill (`impeccable`) is installed, the prompt delegates each dumb visual to it. When none is, the prompt authors the dumb visuals inline from the design tokens. The action's core, the page description and the dumb/smart split, never depends on it. ## Input @@ -12,21 +14,20 @@ The page or feature to design (free text). Nothing else. The page, **described**: what it is, its components and their behavior, the dumb/smart split. Plus a bullet list (or small table) of the elements covered, and the delegation prompt for the implementer. -## Requirement - -`impeccable` skill installed. - ## Process -1. **Describe the page.** Purpose, sections, components. Per component, its behavior (states + transitions) - the SMART layer, owned in-house. -2. **Dumb/smart split.** Mark the **presentational (dumb)** components - props in, UI out, no data/logic/routing/state. Their visual is delegated to the design tool; its `shape` defines the visual behaviors (one line, not re-specified here). +1. **Describe the page.** Purpose, sections, components. Per component, its behavior (states and transitions), the SMART layer, owned in-house. +2. **Dumb/smart split.** Mark the **presentational (dumb)** components, props in, UI out, no data, logic, routing, or state. Their visual is delegated to the design tool, and its `shape` defines the visual behaviors (one line, not re-specified here). 3. **Render decision.** Ask the user once: see the page rendered, or not? 4. **Write the delegation prompt** for the implementer. It must: - - Keep the smart layer (data, state, routing, wiring) in your own code. Author the visual via the design tool with quotes - never `craft` (that builds the feature): `Use skill "impeccable" with "shape - dumb/presentational, props only, tokens from DESIGN.md"`. - - **If render was requested - visual-first.** Craft the page's visual **end-to-end first**, then **verify it in-browser before any wiring**: `Use skill "impeccable" with "live"` to iterate variants until visually good, with `Use skill "impeccable" with "critique "` as the gate. Run under `/goal` (`aidd-dev:09-for-sure`): loop until **zero P0**, then explicit user OK. Only then **attach the verified visual to the code** (wire the smart layer onto it). - - **If not.** Author the dumb visuals inline and wire as you go - no `live`, no loop. -5. **Present** the description + element list + delegation prompt. Wait for an explicit OK before exiting. + - Keep the smart layer (data, state, routing, wiring) in your own code. For the dumb visual, when a UI-craft skill is installed, delegate with quotes, never `craft` (that builds the feature): `Use skill "impeccable" with "shape - dumb/presentational, props only, tokens from DESIGN.md"`. When none is installed, author the dumb visual inline from the design tokens. + - **If render was requested, go visual-first.** Craft the page's visual **end-to-end first**, then **verify it in-browser before any wiring**: `Use skill "impeccable" with "live"` to iterate variants until visually good, with `Use skill "impeccable" with "critique "` as the gate. Run under `/goal` (`aidd-dev:09-for-sure`), looping until **zero P0**, then explicit user OK. Only then **attach the verified visual to the code** by wiring the smart layer onto it. + - **If not.** Author the dumb visuals inline and wire as you go, no `live`, no loop. +5. **Present** the description, the element list, and the delegation prompt. Wait for an explicit OK before exiting. ## Test -The page is described with its components and their behavior; the dumb components are marked; the render decision is recorded; and a delegation prompt exists that builds the smart layer in-house and delegates each dumb visual to the design tool via quoted skill calls. +- The page is described with its components and their behavior. +- The dumb components are marked. +- The render decision is recorded. +- A delegation prompt exists that builds the smart layer in-house and delegates each dumb visual to the design tool via quoted skill calls. diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md new file mode 100644 index 00000000..5a8818dc --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md @@ -0,0 +1,22 @@ +# 03 - Wireframe + +Sketch a low-fidelity ASCII wireframe of a screen from a feature description, to validate its structure before designing or building it. + +## Input + +A feature or page description as free text, or user stories. Nothing else. + +## Output + +A low-fidelity ASCII wireframe of each screen, its regions and rough elements in place, with a one-line note per region. Structure only, no behavior, no styling. + +## Process + +1. **Identify the screens.** From the description, list the screen or screens to sketch. Ask the user which one when it is ambiguous. +2. **Block the layout.** Sketch each screen as an ASCII box-drawing wireframe: header, navigation, main regions, and key elements (lists, forms, cards, actions) in their rough position. Keep it low-fi, structure only, no real copy, no colors, no behavior. +3. **Annotate.** Add one line per region on what it holds and why it is there. +4. **Confirm and hand off.** Show the wireframe and ask the user to confirm the layout or adjust it. Wait for the answer. Hand a confirmed layout to `02-design` to pin component behavior and the dumb/smart split. + +## Test + +- The output is an ASCII wireframe of each screen with labeled regions and a one-line note each, carries no behavior or styling, and waits for the user before handing off. diff --git a/plugins/aidd-dev/skills/01-plan/references/phase-rules.md b/plugins/aidd-dev/skills/01-plan/references/phase-rules.md index 2d79d1ca..831a481e 100644 --- a/plugins/aidd-dev/skills/01-plan/references/phase-rules.md +++ b/plugins/aidd-dev/skills/01-plan/references/phase-rules.md @@ -7,5 +7,5 @@ - Interpret comments on this file to help you fill it. - Each phase MUST have acceptance criteria. - During implementation, the AI may amend this plan. Every AI change MUST be prefixed with 🤖 and include a brief rationale. -- `status`: set `pending` at creation (see the plan-status reference). +- `status`: set `pending` at creation, in the frontmatter. - Log is APPEND-ONLY. One entry per step attempt. Never rewrite history. \ No newline at end of file diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md index fb944fa8..c23e693a 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md @@ -20,14 +20,16 @@ notes: ## Process -1. **Branch.** Create a new branch if the plan specifies one (`git checkout -b `). -2. **Phase loop.** For each phase listed in the plan, in order: +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 `). +3. **Phase loop.** For each phase listed in the plan, in order: - Spawn the `implementer` agent via the `Task` tool, passing the phase 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 %. -3. **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. -4. **Boundaries.** Never format code. Never run dev mode. Follow project rules already loaded in context. -5. **Verify the feature.** Run validation commands, tests, and any manual checks required to confirm the feature works end to end. +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. ## Test -After the loop terminates: every phase in the plan has its acceptance criteria checked off, validation commands exit zero, and no plan section is left in a `TBD` or `BLOCKED` state. +- 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, validation commands exit zero, and no plan section is left in a `TBD` or `BLOCKED` state. From fb013b83631b2b34be6336ca21286a43577e071e Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 19 Jun 2026 12:04:37 +0200 Subject: [PATCH 4/8] refactor(aidd-dev): simplify 01-plan to gather/wireframe/plan with feature-folder output Rebuild 01-plan around three actions (gather, wireframe, plan), drop the design action, and emit a per-feature folder holding plan.md plus one phase-.md per phase. Templates carry their own field rules in a header comment; plan/phase rule files folded in and removed. Migrate aidd-pm:04-spec to the same feature-folder convention (spec.md). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/CATALOG.md | 2 +- plugins/aidd-dev/CATALOG.md | 23 +++---- plugins/aidd-dev/README.md | 2 +- plugins/aidd-dev/agents/planner.md | 6 +- plugins/aidd-dev/skills/00-sdlc/README.md | 2 +- plugins/aidd-dev/skills/01-plan/README.md | 28 ++++----- plugins/aidd-dev/skills/01-plan/SKILL.md | 47 +++----------- .../skills/01-plan/actions/01-gather.md | 21 +++++++ .../skills/01-plan/actions/01-plan.md | 53 ---------------- .../skills/01-plan/actions/02-design.md | 33 ---------- .../skills/01-plan/actions/02-wireframe.md | 40 ++++++++++++ .../skills/01-plan/actions/03-plan.md | 26 ++++++++ .../skills/01-plan/actions/03-wireframe.md | 22 ------- .../skills/01-plan/assets/phase-template.md | 34 ++++------- .../skills/01-plan/assets/plan-template.md | 49 +++++++++------ .../01-plan/assets/tech-choice-template.md | 61 ------------------- .../skills/01-plan/references/phase-rules.md | 11 ---- .../skills/01-plan/references/plan-rules.md | 8 --- .../skills/04-spec/actions/01-build.md | 4 +- 19 files changed, 173 insertions(+), 299 deletions(-) create mode 100644 plugins/aidd-dev/skills/01-plan/actions/01-gather.md delete mode 100644 plugins/aidd-dev/skills/01-plan/actions/01-plan.md delete mode 100644 plugins/aidd-dev/skills/01-plan/actions/02-design.md create mode 100644 plugins/aidd-dev/skills/01-plan/actions/02-wireframe.md create mode 100644 plugins/aidd-dev/skills/01-plan/actions/03-plan.md delete mode 100644 plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md delete mode 100644 plugins/aidd-dev/skills/01-plan/assets/tech-choice-template.md delete mode 100644 plugins/aidd-dev/skills/01-plan/references/phase-rules.md delete mode 100644 plugins/aidd-dev/skills/01-plan/references/plan-rules.md diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 456b8e18..6e8b65e9 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -32,7 +32,7 @@ The development SDLC: plan, implement, assert, audit, review, test, refactor, de | Skill | Role | Actions | | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `00-sdlc` | Pure orchestrator driving the full dev flow end to end | `01-spec`, `02-plan`, `03-implement`, `04-review`, `05-ship` | -| `01-plan` | Generate an implementation plan, design a frontend page, or wireframe a screen | `01-plan`, `02-design`, `03-wireframe` | +| `01-plan` | Turn a request, ticket, or file into a phased implementation plan, wireframing a screen first when needed | `01-gather`, `02-wireframe`, `03-plan` | | `02-implement` | Execute a plan phase by phase until 100% complete | `01-implement` | | `03-assert` | Assert features work - general, architecture, frontend UI | `01-assert`, `02-assert-architecture`, `03-assert-frontend` | | `04-audit` | Read-only codebase audit across quality pillars | `01-code-quality`, `02-architecture`, `03-security`, `04-dependencies`, `05-performance`, `06-tests`, `07-ui` | diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 0840e777..767c65ec 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -53,19 +53,16 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai #### `skills/01-plan` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-plan.md](skills/01-plan/actions/01-plan.md) | - | - | -| `actions` | [02-design.md](skills/01-plan/actions/02-design.md) | - | - | -| `actions` | [03-wireframe.md](skills/01-plan/actions/03-wireframe.md) | - | - | -| `assets` | [phase-template.md](skills/01-plan/assets/phase-template.md) | `Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file.` | - | -| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `Parent plan template orchestrating multiple child plans with validation gates` | - | -| `assets` | [tech-choice-template.md](skills/01-plan/assets/tech-choice-template.md) | `Technology selection and comparison template` | - | -| `-` | [README.md](skills/01-plan/README.md) | - | - | -| `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` | [phase-rules.md](skills/01-plan/references/phase-rules.md) | - | - | -| `references` | [plan-rules.md](skills/01-plan/references/plan-rules.md) | - | - | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Generate a technical implementation plan from requirements, design a frontend page before building it (component behavior as state machines, the dumb/smart split, and the render decision), or sketch a low-fidelity wireframe of a screen. Use when the user wants to plan a feature, turn a ticket or requirements into an implementation plan, design a page's structure and behavior, or wireframe a screen layout. Do NOT use for writing the code (use 02-implement), reviewing a diff (use 05-review), or auditing existing code (use 04-audit).` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-gather.md](skills/01-plan/actions/01-gather.md) | - | +| `actions` | [02-wireframe.md](skills/01-plan/actions/02-wireframe.md) | - | +| `actions` | [03-plan.md](skills/01-plan/actions/03-plan.md) | - | +| `assets` | [phase-template.md](skills/01-plan/assets/phase-template.md) | `One phase of a plan - its projection slice, user journey, tasks, and acceptance criteria. The implementer loop tracks it via status and iteration.` | +| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `A feature's implementation plan - rules, phases, risks, decisions. One phase file sits next to it per phase.` | +| `-` | [README.md](skills/01-plan/README.md) | - | +| `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).` | +| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. 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).` | #### `skills/02-implement` diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index fcc4f1a2..976e7ac9 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -15,7 +15,7 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert | Bracket ID | Skill | Description | |---|---|---| | [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) | Generate an implementation plan from requirements, design a frontend page (behavior, dumb/smart split), or wireframe a screen at low fidelity. | +| [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.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. | diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md index 21dc2abf..d1e76cf8 100644 --- a/plugins/aidd-dev/agents/planner.md +++ b/plugins/aidd-dev/agents/planner.md @@ -24,8 +24,8 @@ When invoked, you receive: When you return, your output is a structured table: ```yaml -plan_path: -child_paths: [] +plan_path: +child_paths: [] decisions_made: - id: topic: @@ -40,7 +40,7 @@ plan_status: in_progress | done | blocked notes: ``` -`plan_path` and `child_paths` reflect what `aidd-dev:01-plan` actually wrote - the skill picks the path (typically `aidd_docs/tasks//-?<#ticket>-.md` for simple plans, plus `*-master.md` and `*-part-N.md` for master plans). Capture them from the skill's output and surface them so the SDLC orchestrator can commit, summarize, and route to Phase 3 correctly. +`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 diff --git a/plugins/aidd-dev/skills/00-sdlc/README.md b/plugins/aidd-dev/skills/00-sdlc/README.md index ee150af0..f181f2f1 100644 --- a/plugins/aidd-dev/skills/00-sdlc/README.md +++ b/plugins/aidd-dev/skills/00-sdlc/README.md @@ -46,7 +46,7 @@ The skill walks 5 actions: ## Outputs - A spec file (unless skipped). -- A plan file in `aidd_docs/plans/`. +- A plan file in `aidd_docs/tasks/`. - Atomic commits on the active branch, one per ticked checkbox. - A pull request with title, body, base branch, and draft state. - Findings + completion + quality scores from the reviewer. diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md index 4a190021..4658867d 100644 --- a/plugins/aidd-dev/skills/01-plan/README.md +++ b/plugins/aidd-dev/skills/01-plan/README.md @@ -2,12 +2,12 @@ # 01 - plan -Generates a technical implementation plan from requirements, or designs a frontend page before building it. The plan file is the single source of truth that downstream skills (`02-implement`, `05-review`) consume. +Turns a request, ticket, or file into a phased implementation plan and its phase files. The plan is the single source of truth that downstream skills (`02-implement`, `05-review`) consume. ## When to use -- A validated spec or ticket exists and you need a phased plan with milestones, rules, and acceptance criteria before any code change. -- A frontend page needs its design pinned down, component behavior as state machines and the dumb/smart split, before implementation. +- A spec, ticket, or request exists and you need a phased plan with deterministic acceptance criteria before any code change. +- A screen needs its layout fixed with a low-fidelity wireframe before the plan. ## When NOT to use @@ -21,26 +21,24 @@ Generates a technical implementation plan from requirements, or designs a fronte Use skill aidd-dev:01-plan ``` -The skill exposes three actions: +The skill runs three actions in order, the plan being the culmination: -1. `plan` produces a phased implementation plan from requirements, saved to a task file. -2. `design` defines a frontend page's design, component behavior as state machines and the dumb/smart split, with a render decision and a delegation prompt for the implementer. -3. `wireframe` sketches a low-fidelity ASCII layout of a screen before designing it. +1. `gather` collects the source the plan rests on and restates it. Always first. +2. `wireframe` sketches a low-fidelity ASCII layout of any screen the feature needs. Frontend only, skipped when there is no UI. +3. `plan` turns the gathered source, and any confirmed wireframe, into the plan and its phases. -The planner adapts to the input and routes to the right action, it does not ask the user to choose. The actions chain naturally: wireframe a screen, then design it, then plan its build. +A feature folder `aidd_docs/tasks//_/`: -## Outputs +- `plan.md` from the plan template: rules, phases, risks, decisions, external resources. +- `phase-.md` per phase from the phase template: projection slice, user journey, tasks, acceptance criteria, any wireframe. -- A plan file under `aidd_docs/tasks//`, dated and feature-named, with execution frontmatter, the architecture projection (modify, create, delete), an applicable-rules table, and ordered phases. -- A page design with the dumb/smart split and a delegation prompt that builds the smart layer in-house and delegates each dumb visual to the design tool. -- A low-fidelity ASCII wireframe of a screen, its regions labeled, for layout validation before design. +The plan reuses the folder when the source already lives in one, so a `brainstorm.md` or `spec.md` already there sits alongside, not duplicated. ## Prerequisites -- Requirements, a ticket, or a page to design as input. +- A request, ticket, or file as the source. - The plan and phase templates bundled with this skill. -- Optional: a UI-craft skill (`impeccable`) enhances the design action's visual delegation. The design action works without it, authoring dumb visuals inline. ## Technical details -See [`SKILL.md`](SKILL.md) for the action list and routing, [`assets/plan-template.md`](assets/plan-template.md) for the plan format, and [`actions/`](actions/) for the per-action contracts. +See [`SKILL.md`](SKILL.md) for the action flow, [`assets/plan-template.md`](assets/plan-template.md) for the plan format, and [`actions/`](actions/) for the per-action contracts. diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index d10f9ad8..26d75e65 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,52 +1,25 @@ --- name: 01-plan -description: Generate a technical implementation plan from requirements, design a frontend page before building it (component behavior as state machines, the dumb/smart split, and the render decision), or sketch a low-fidelity wireframe of a screen. Use when the user wants to plan a feature, turn a ticket or requirements into an implementation plan, design a page's structure and behavior, or wireframe a screen layout. Do NOT use for writing the code (use 02-implement), reviewing a diff (use 05-review), or auditing existing code (use 04-audit). -context: fork -agent: planner -model: sonnet -effort: medium +description: Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. 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: plan -Produces an implementation plan from requirements, or a frontend page's design (component behavior as state machines, the dumb/smart split, and the render decision). Never writes code. - -## Agent delegation - -Spawn the `planner` agent to execute this skill. For tools that do not support `context: fork` frontmatter, invoke the `planner` agent explicitly with this skill's content as the prompt. - -## Available actions - -| # | Action | When to use | -| --- | ----------- | ------------------------------------------------------------------------------------------- | -| 01 | `plan` | Turn requirements into a technical implementation plan saved to a task file | -| 02 | `design` | Define a frontend page's design: component behavior as state machines, the dumb/smart split, the render decision | -| 03 | `wireframe` | Sketch a low-fidelity ASCII layout of a screen before designing it | - -## Routing (run first) - -The planner adapts to the INPUT, it does not ask the user to choose. Detect the input type and route, never fall to action 01 by default. - -- The request is to sketch, lay out, or wireframe a screen at low fidelity, before any design → `03-wireframe`. -- The request is about a frontend page or feature's design, its component behavior, states, the dumb/smart split, or whether to render → `02-design`. -- Anything else, requirements or a feature to build → `01-plan`. - -Actions may chain, for example wireframe a screen, then design it, then plan its build. Read and follow each selected action file. +Turn a gathered source into an implementation plan and its phase files. Never writes code. ## Actions -- `@actions/01-plan.md` -- `@actions/02-design.md` -- `@actions/03-wireframe.md` +Run them in order. The plan is the culmination. + +1. `@actions/01-gather.md`: collect and restate the source. Always first. +2. `@actions/02-wireframe.md`: sketch any screen the feature needs. Frontend only, skip when there is no UI. +3. `@actions/03-plan.md`: turn the gathered source, and any confirmed wireframe, into the plan and its phases. ## References -- `@references/plan-rules.md`: rules every plan file obeys. -- `@references/phase-rules.md`: rules every phase obeys. -- `@references/mermaid-conventions.md`: conventions for the Mermaid diagrams a plan embeds. +- `@references/mermaid-conventions.md`: conventions for the Mermaid diagrams a phase embeds. ## Assets -- `@assets/plan-template.md`: the plan file skeleton. -- `@assets/phase-template.md`: the per-phase skeleton. -- `@assets/tech-choice-template.md`: the skeleton for documenting a technical choice. +- `@assets/plan-template.md`: the `plan.md` scaffold. Its header comment carries the field rules. +- `@assets/phase-template.md`: the per-phase scaffold. Its header comment carries the field rules. diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md new file mode 100644 index 00000000..df5e6407 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md @@ -0,0 +1,21 @@ +# 01 - Gather + +Collect the source the plan will rest on, before any planning. Read only. + +## Input + +The user's request, which may be empty. + +## Output + +The source restated in a few bullets: what is asked and the hard constraints it states. The source kind and reference (file path, ticket id, or text) are named. + +## 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 the user once: a file, a ticket, or a description? Wait for the answer. 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. +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 + +- The output names the source kind and reference and restates it in bullets, states no solution, and when nothing concrete was given the user was asked before anything else. diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md b/plugins/aidd-dev/skills/01-plan/actions/01-plan.md deleted file mode 100644 index 0f7966e5..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md +++ /dev/null @@ -1,53 +0,0 @@ -# 01 - Plan - -Generate a technical implementation plan from requirements, save it to a task file, display it for review, and wait for explicit user confirmation. Never code anything. - -## Input - -Requirements as a ticket URL or raw text, passed via `$ARGUMENTS`. The ticket number is optional and inferred when the input is a ticket URL. Optionally, a brainstorm artifact under `aidd_docs/brainstorm/` carrying settled decisions and flagged-open assumptions for the feature. - -## Output - -A plan file saved under `aidd_docs/tasks//`, named `-?<#ticket_number>-` with an optional `-master` or `-part-N` suffix. It carries execution frontmatter (`objective`, a runnable `success_condition`, `iteration: 0`, `created_at`), the validated architecture projection (files to modify, create, and delete, each with a one-line reason), the applicable-rules table, the source brainstorm path, and a confidence score. - -## Process - -1. **Parse the input.** Detect ticket URL vs raw text. For URLs, fetch and parse ticket content. For raw text, clean and structure. Normalize text (handle vocal dictation issues). Print the user journey as a simplified ASCII diagram for validation. -2. **Ingest the brainstorm, if any.** When a brainstorm artifact is passed, or one exists under `aidd_docs/brainstorm/` for this feature, read it. Treat its **settled** decisions as constraints the plan must honor. Hold its flagged-open assumptions as risks to carry. Record the artifact path for the plan's Brainstorm field. If no artifact exists, continue with `none`. -3. **Validate technical assumptions.** Spawn a sub-agent task to: - - Explore the codebase to inform plan generation. - - List implicit assumptions about the user's infrastructure. - - Verify API feasibility before committing to an approach. - - Flag blockers and risks that will arise if not addressed. - - Check assumptions against official documentation. - - Produce the architecture projection, three lists (files to modify, to create, to delete), each entry a path and a one-line reason. - - Inventory project rules from the user's project root. Accept a silent empty array when no surface contains rules. -4. **Architecture projection and rules, user validation (gate).** - - From the rules inventory, select rules that apply to the projection using each rule's `description` and `paths` when present. Justify every selected rule in one line. - - Display the three modify, create, and delete lists, and the table of applicable rules `tool | name | path | why it applies`. - - Surface any conflict between a settled brainstorm decision and this projection now, before generating, never silently diverge from it. - - Ask: "Is this projection correct? Anything to add or remove? A missing rule?" - - Wait for user approval. Iterate until approved. -5. **Task planning.** Define main phases at the macro level, without naming specific files. Wait for user validation on the phases before moving on. For each phase, list minimal, specific, actionable tasks. -6. **Generate and save the plan.** - - Use the current `!`date`!` for the date stamp. - - Determine the feature name from the requirements. - - Insert the user journey as Mermaid syntax in the plan, applying `@../references/mermaid-conventions.md`. - - Fill the chosen template with the validated architecture projection, applicable rules, and the brainstorm path (or `none`). - - Fill execution frontmatter, required because the plan is the For Sure tracking file: `objective`, `success_condition` (a runnable command, reject vague conditions), `iteration: 0`, `created_at` (ISO 8601 from step 1). - - Save to disk under `aidd_docs/tasks//`: - - Simple plan: `-?<#ticket_number>-.md` - - Master plan: `-?<#ticket_number>--master.md` - - Child plans: `-?<#ticket_number>--part-N.md` - - Display the saved file path. -7. **Quality assurance.** Verify the plan addresses every requirement and honors every settled brainstorm decision. Flag potential challenges. Evaluate confidence from 0 to 10 with ✓ reasons and ✗ risks. Require a minimum of 9 before display. Add the assessment to the plan. -8. **Display and confirm.** Show the plan, the confidence assessment, and any risks. Challenge the plan with the user. Wait for user approval. - -## Test - -- The plan file exists under `aidd_docs/tasks//` with the expected name. -- Its frontmatter carries `objective`, a runnable `success_condition`, `iteration: 0`, and a valid `created_at`. -- The architecture projection (modify, create, delete) is non-empty and matches the validated lists. -- The applicable-rules table is consistent with the project's rules inventory. -- When a brainstorm artifact was ingested, its path is recorded and no settled decision is contradicted without being surfaced. -- Confidence is at least 9. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-design.md b/plugins/aidd-dev/skills/01-plan/actions/02-design.md deleted file mode 100644 index dbcb9d09..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/02-design.md +++ /dev/null @@ -1,33 +0,0 @@ -# 02 - Design - -Describe a frontend page's design before code, its components and their behavior, the dumb/smart split, and the render decision, then write the **delegation prompt** that tells the implementer how to build it. - -This action describes and delegates. It writes no code, and running under the `planner` it does **not** spawn the implementer. The implementation side launches it with the prompt written here. - -The visual delegation is optional and degrades gracefully. When a UI-craft skill (`impeccable`) is installed, the prompt delegates each dumb visual to it. When none is, the prompt authors the dumb visuals inline from the design tokens. The action's core, the page description and the dumb/smart split, never depends on it. - -## Input - -The page or feature to design (free text). Nothing else. - -## Output - -The page, **described**: what it is, its components and their behavior, the dumb/smart split. Plus a bullet list (or small table) of the elements covered, and the delegation prompt for the implementer. - -## Process - -1. **Describe the page.** Purpose, sections, components. Per component, its behavior (states and transitions), the SMART layer, owned in-house. -2. **Dumb/smart split.** Mark the **presentational (dumb)** components, props in, UI out, no data, logic, routing, or state. Their visual is delegated to the design tool, and its `shape` defines the visual behaviors (one line, not re-specified here). -3. **Render decision.** Ask the user once: see the page rendered, or not? -4. **Write the delegation prompt** for the implementer. It must: - - Keep the smart layer (data, state, routing, wiring) in your own code. For the dumb visual, when a UI-craft skill is installed, delegate with quotes, never `craft` (that builds the feature): `Use skill "impeccable" with "shape - dumb/presentational, props only, tokens from DESIGN.md"`. When none is installed, author the dumb visual inline from the design tokens. - - **If render was requested, go visual-first.** Craft the page's visual **end-to-end first**, then **verify it in-browser before any wiring**: `Use skill "impeccable" with "live"` to iterate variants until visually good, with `Use skill "impeccable" with "critique "` as the gate. Run under `/goal` (`aidd-dev:09-for-sure`), looping until **zero P0**, then explicit user OK. Only then **attach the verified visual to the code** by wiring the smart layer onto it. - - **If not.** Author the dumb visuals inline and wire as you go, no `live`, no loop. -5. **Present** the description, the element list, and the delegation prompt. Wait for an explicit OK before exiting. - -## Test - -- The page is described with its components and their behavior. -- The dumb components are marked. -- The render decision is recorded. -- A delegation prompt exists that builds the smart layer in-house and delegates each dumb visual to the design tool via quoted skill calls. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/02-wireframe.md new file mode 100644 index 00000000..c0573779 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/02-wireframe.md @@ -0,0 +1,40 @@ +# 02 - Wireframe + +Sketch a low-fidelity ASCII wireframe of a screen, to fix its layout before the plan. Frontend only, skip it when the feature has no UI. + +## Input + +The screen or feature to sketch, from the gathered source. + +## Output + +A low-fidelity ASCII wireframe of each screen, its regions and key elements in place, with a numbered note per region. Structure only, no behavior, no styling, no final copy. + +## Process + +1. **Pick the screens.** List the screen or screens the feature needs. Ask the user which one when it is ambiguous. Skip the action entirely when there is no UI. +2. **Block the layout.** Draw each screen as one box-drawing wireframe with `┌ ─ ┐ │ └ ┘`. Place the regions (header, nav, main, aside, footer) and the key elements (lists, forms, cards, buttons, inputs) where they sit. Number each region. Low fidelity, no colors, no final copy. +3. **Annotate.** Under the sketch, one line per numbered region on what it holds and why. +4. **Confirm.** Show the wireframe and ask the user to confirm the layout or adjust it. Wait for the answer. A confirmed layout feeds the plan. + +## Example + +``` +┌─────────────────────────────────────┐ +│ (1) Header: logo · search · account │ +├──────────┬──────────────────────────┤ +│ (2) Nav │ (3) Results list │ +│ filters │ ┌──────────────────────┐ │ +│ by type │ │ (4) Result card │ │ +│ │ └──────────────────────┘ │ +└──────────┴──────────────────────────┘ +``` + +1. Header: brand, global search, account menu. +2. Nav: filters that narrow the list. +3. Results: the matched items, paginated. +4. Card: one result, title and summary. + +## Test + +- The output is a box-drawing wireframe of each screen with numbered regions and a one-line note each, carries no behavior, styling, or final copy, and waits for the user. diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-plan.md b/plugins/aidd-dev/skills/01-plan/actions/03-plan.md new file mode 100644 index 00000000..e11b2f54 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/03-plan.md @@ -0,0 +1,26 @@ +# 03 - Plan + +Turn the gathered source into a plan and its phases, save them, and confirm with the user. Never code. + +## Input + +The gathered source from `01-gather`, plus any confirmed wireframe from `02-wireframe`. + +## 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`. + +## Process + +1. **Explore, no sub-agent.** Read the codebase here. Produce the architecture projection (files to modify, create, delete, each with a one-line reason), the implicit assumptions, the feasibility checks against official docs (keep each URL and what it settled), and the project rules that apply. +2. **Gate: projection and rules.** Show the projection and the applicable rules. Ask "Correct? Anything to add or remove?" Iterate until approved. +3. **Gate: phases.** Break the work into 3 to 6 phases, each a coherent chunk that ships and verifies on its own, sized for one implementer pass. Show them. Iterate until approved. +4. **Write.** Resolve the feature folder: reuse the one the source already lives in when it sits under `aidd_docs/tasks//_/`, otherwise create one from the current date and a short logical feature slug. Scaffold from the templates and fill every placeholder: `plan.md`, one `phase-.md` per phase (phase 1 is `phase-1.md`), the projection sliced into each phase. Embed any confirmed wireframe in its phase. Display the paths. +5. **Gate: confidence and confirm.** Score the plan 0 to 10 with ✓ reasons and ✗ risks, and report it. Below 9, revise and rescore. At 9 or above, show the plan and its phases, challenge them with the user, and wait for approval. The score gates display, never written to the plan. + +## Test + +- `aidd_docs/tasks//_/plan.md` exists with one `phase-.md` per phase next to it. +- No `{...}` placeholder is left in any written file. +- The phase projection slices together cover the validated modify, create, and delete lists. +- A confidence score of at least 9 was reported and written to no file. diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md deleted file mode 100644 index 5a8818dc..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md +++ /dev/null @@ -1,22 +0,0 @@ -# 03 - Wireframe - -Sketch a low-fidelity ASCII wireframe of a screen from a feature description, to validate its structure before designing or building it. - -## Input - -A feature or page description as free text, or user stories. Nothing else. - -## Output - -A low-fidelity ASCII wireframe of each screen, its regions and rough elements in place, with a one-line note per region. Structure only, no behavior, no styling. - -## Process - -1. **Identify the screens.** From the description, list the screen or screens to sketch. Ask the user which one when it is ambiguous. -2. **Block the layout.** Sketch each screen as an ASCII box-drawing wireframe: header, navigation, main regions, and key elements (lists, forms, cards, actions) in their rough position. Keep it low-fi, structure only, no real copy, no colors, no behavior. -3. **Annotate.** Add one line per region on what it holds and why it is there. -4. **Confirm and hand off.** Show the wireframe and ask the user to confirm the layout or adjust it. Wait for the answer. Hand a confirmed layout to `02-design` to pin component behavior and the dumb/smart split. - -## Test - -- The output is an ASCII wireframe of each screen with labeled regions and a one-line note each, carries no behavior or styling, and waits for the user before handing off. diff --git a/plugins/aidd-dev/skills/01-plan/assets/phase-template.md b/plugins/aidd-dev/skills/01-plan/assets/phase-template.md index 4c0a28ee..ae656be0 100644 --- a/plugins/aidd-dev/skills/01-plan/assets/phase-template.md +++ b/plugins/aidd-dev/skills/01-plan/assets/phase-template.md @@ -1,48 +1,40 @@ --- name: phase -description: Living implementation plan - frozen objective, phases, and append-only execution Log. Used as input artifact AND as the autonomous-loop tracking file. +description: One phase of a plan - its projection slice, user journey, tasks, and acceptance criteria. The implementer loop tracks it via status and iteration. status: pending iteration: 0 created_at: "{YYYY-MM-DDTHH:MM:SSZ}" --- -# Instruction: {title} + -| Element |  Value | -| --------------- | --------------- | -| **Plan** | `{plan}/` | -| **Branch name** | `{branch-name}` | +# Phase: {title} -## Architecture projection +Part of [`plan.md`](./plan.md). - +## Architecture projection ```txt . ``` -## User Journey - - +## User journey ```mermaid flowchart TD A[TODO] ``` -## Tasks to do - -### `{number})` {name} +## Tasks -> {straight to point goal} +### {n}) {name} - +> {goal, straight to the point} 1. {ultra concise step} - ... -## Test acceptance criteria +## Acceptance criteria -| Task | Acceptance criteria | -| ---- | ------------------------------------ | -| 1... | {focused deterministic verification} | +| Task | Criterion | +| ---- | ----------------------------- | +| 1 | {focused deterministic check} | diff --git a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md index 70125500..7ee4a401 100644 --- a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md +++ b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md @@ -1,36 +1,51 @@ --- name: plan -description: Parent plan template orchestrating multiple child plans with validation gates -status: pending +description: A feature's implementation plan - rules, phases, risks, decisions. One phase file sits next to it per phase. +objective: "{one-line objective, matches the source}" +success_condition: "{a command or check that proves the plan is done}" +plan_status: in_progress +iteration: 0 +created_at: "{YYYY-MM-DDTHH:MM:SSZ}" --- + + # Plan: {title} ## Overview -| Field | Value | -| -------------- | ------------------ | -| **Goal** | {one-line summary} | -| **Risk Score** | {X}/10 | -| **Brainstorm** | `path/` (`none`) | +| Field | Value | +| -------------- | ----------------------- | +| **Risk Score** | {X}/10 | +| **Source** | {file, ticket, or text} | -## Plans +## Applicable rules -| # | Plan | File | -| --- | ------------ | ----------------------- | -| 1 | {phase-name} | [`./1_{phase}.md`](./#) | -| 2 | {phase-name} | [`./2_{phase}.md`](./#) | +| Tool | Rule | Path | Why it applies | +| ------ | ------ | -------- | -------------- | +| {tool} | {name} | `{path}` | {one-line why} | -## Risk register +## Phases + +| # | Phase | File | +| --- | ------------ | ---------------------------------- | +| 1 | {phase-name} | [`phase-1.md`](./phase-1.md) | +| 2 | {phase-name} | [`phase-2.md`](./phase-2.md) | - +## Risk register | Risk | Impact | Mitigation | | -------- | ----------------------------- | ------------------------------------- | | {risk 1} | {what breaks if this happens} | {how the plan prevents or handles it} | +## External resources + +| Source | Verified | +| ------ | --------------------------- | +| {url} | {what it settled, one line} | + ## Decisions -| Decision | Why | -| -------- | --- | -| | | +| Decision | Why | +| ---------- | -------------- | +| {decision} | {one-line why} | diff --git a/plugins/aidd-dev/skills/01-plan/assets/tech-choice-template.md b/plugins/aidd-dev/skills/01-plan/assets/tech-choice-template.md deleted file mode 100644 index d9df39b7..00000000 --- a/plugins/aidd-dev/skills/01-plan/assets/tech-choice-template.md +++ /dev/null @@ -1,61 +0,0 @@ ---- -name: tech-choice -description: Technology selection and comparison template -argument-hint: N/A ---- - -# RESEARCH & RECOMMENDATIONS - -[Summary of the user needs and goals] - -## Technology Analysis: [SPECIFIC TECHNOLOGY CATEGORY] - -### Executive Summary - -One paragraph explaining top recommendation and why. - -### Comparison Matrix - -| Solution | Score /10 | Cost | Performance | Integration Effort | Maintenance | Scalability | Key Strength | Key Weakness | -| -------- | --------- | ------- | ----------- | ------------------ | ------------ | ----------- | ------------ | ------------ | -| Option 1 | X.X | €/month | Metric | Easy/Medium/Hard | Low/Med/High | Rating | Feature | Limitation | -| Option 2 | X.X | €/month | Metric | Easy/Medium/Hard | Low/Med/High | Rating | Feature | Limitation | -| Option 3 | X.X | €/month | Metric | Easy/Medium/Hard | Low/Med/High | Rating | Feature | Limitation | - -## Detailed Evaluation - -### 🏆 Recommended: [Technology Name] - -**Why this choice:** - -- Key reason 1 -- Key reason 2 -- Key reason 3 - -**Implementation considerations:** - -- Migration path: Brief strategy -- Time estimate: X weeks/months -- Risk factors: Main risks - -### Alternative Options - -**[Option 2 Name]** - -- Best for: (Specific use case) -- Choose if: (Specific conditions) -- Avoid if: (Specific conditions) - -**[Option 3 Name]** - -- Best for: (Specific use case) -- Choose if: (Specific conditions) -- Avoid if: (Specific conditions) - -## Cost Analysis - -| Solution | Monthly | Annual | Hidden Costs | 2-Year TCO | -| ------------ | ------- | ------ | ------------ | ---------- | -| Current | €X | €X | (List) | €X | -| Recommended | €X | €X | (List) | €X | -| Savings/Cost | €X | €X | - | €X | diff --git a/plugins/aidd-dev/skills/01-plan/references/phase-rules.md b/plugins/aidd-dev/skills/01-plan/references/phase-rules.md deleted file mode 100644 index 831a481e..00000000 --- a/plugins/aidd-dev/skills/01-plan/references/phase-rules.md +++ /dev/null @@ -1,11 +0,0 @@ -# Phase rules - -- ENGLISH ONLY -- Text is straight to the point, no emojis, no style, use bullet points. -- Replace placeholders (`{variables}`) with actual user inputs. -- Define flow of the feature, from start to end. -- Interpret comments on this file to help you fill it. -- Each phase MUST have acceptance criteria. -- During implementation, the AI may amend this plan. Every AI change MUST be prefixed with 🤖 and include a brief rationale. -- `status`: set `pending` at creation, in the frontmatter. -- Log is APPEND-ONLY. One entry per step attempt. Never rewrite history. \ No newline at end of file diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-rules.md b/plugins/aidd-dev/skills/01-plan/references/plan-rules.md deleted file mode 100644 index f00f4459..00000000 --- a/plugins/aidd-dev/skills/01-plan/references/plan-rules.md +++ /dev/null @@ -1,8 +0,0 @@ -# Plan rules - -- ENGLISH ONLY -- Text is straight to the point, no emojis, no style, use bullet points. -- Replace placeholders (`{variables}`) with actual user inputs. -- Each child plan uses the standard `plan.md` template format. -- Execution is sequential: next child gated until previous validated. -- Validation is manual via checkbox approval. 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 43027534..f9696608 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/01-build.md +++ b/plugins/aidd-pm/skills/04-spec/actions/01-build.md @@ -13,7 +13,7 @@ feature_name: # required; derived from the request wh ## Outputs ```yaml -spec_path: aidd_docs/tasks//--spec.md +spec_path: aidd_docs/tasks//_/spec.md status: draft notes: ``` @@ -25,7 +25,7 @@ notes: - `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**. Save the spec to `aidd_docs/tasks//--spec.md`. Create the month directory when missing. +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`. ## Test From c377576d42a926129c5b6684323ba9199ccf331e Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 19 Jun 2026 13:36:34 +0200 Subject: [PATCH 5/8] refactor(aidd-dev): restructure 01-plan into gather/explore/wireframe/plan Split the plan skill into four focused actions: gather the source, explore the codebase (its own deep pass producing the projection, rules, feasibility, and risks), optionally wireframe a screen with that context, then plan (decompose into phases and write the files). Validation collapses to one end review with an improve loop, so the flow runs clean non-interactively. Templates stay minimal: plan.md carries objective + status frontmatter, an overview, phases, resources, and decisions; phase-.md carries the projection slice, user journey, an optional wireframe, tasks, and acceptance criteria. Wireframe drawing conventions move to a reference. The phase count is free, driven by the work, not a fixed range. Conform SKILL.md to the authoring contract (action table, plain reference paths). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/CATALOG.md | 2 +- plugins/aidd-dev/CATALOG.md | 12 +++--- plugins/aidd-dev/agents/planner.md | 2 +- plugins/aidd-dev/skills/01-plan/README.md | 9 ++-- plugins/aidd-dev/skills/01-plan/SKILL.md | 21 +++++---- .../skills/01-plan/actions/01-gather.md | 2 +- .../skills/01-plan/actions/02-explore.md | 23 ++++++++++ .../skills/01-plan/actions/02-wireframe.md | 40 ----------------- .../skills/01-plan/actions/03-plan.md | 26 ----------- .../skills/01-plan/actions/03-wireframe.md | 20 +++++++++ .../skills/01-plan/actions/04-plan.md | 24 +++++++++++ .../skills/01-plan/assets/phase-template.md | 33 +++++++------- .../skills/01-plan/assets/plan-template.md | 43 ++++++------------- .../references/wireframe-conventions.md | 28 ++++++++++++ 14 files changed, 153 insertions(+), 132 deletions(-) create mode 100644 plugins/aidd-dev/skills/01-plan/actions/02-explore.md delete mode 100644 plugins/aidd-dev/skills/01-plan/actions/02-wireframe.md delete mode 100644 plugins/aidd-dev/skills/01-plan/actions/03-plan.md create mode 100644 plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md create mode 100644 plugins/aidd-dev/skills/01-plan/actions/04-plan.md create mode 100644 plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 7d2046bd..afd90865 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -32,7 +32,7 @@ The development SDLC: plan, implement, assert, audit, review, test, refactor, de | Skill | Role | Actions | | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | `00-sdlc` | Pure orchestrator driving the full dev flow end to end | `01-spec`, `02-plan`, `03-implement`, `04-review`, `05-ship` | -| `01-plan` | Turn a request, ticket, or file into a phased implementation plan, wireframing a screen first when needed | `01-gather`, `02-wireframe`, `03-plan` | +| `01-plan` | Turn a request, ticket, or file into a phased implementation plan: gather, explore, wireframe, plan | `01-gather`, `02-explore`, `03-wireframe`, `04-plan` | | `02-implement` | Execute a plan phase by phase until 100% complete | `01-implement` | | `03-assert` | Assert features work - general, architecture, frontend UI | `01-assert`, `02-assert-architecture`, `03-assert-frontend` | | `04-audit` | Read-only codebase audit across quality pillars | `01-code-quality`, `02-architecture`, `03-security`, `04-dependencies`, `05-performance`, `06-tests`, `07-ui` | diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 9d23a032..3db84589 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -56,14 +56,16 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-gather.md](skills/01-plan/actions/01-gather.md) | - | -| `actions` | [02-wireframe.md](skills/01-plan/actions/02-wireframe.md) | - | -| `actions` | [03-plan.md](skills/01-plan/actions/03-plan.md) | - | -| `assets` | [phase-template.md](skills/01-plan/assets/phase-template.md) | `One phase of a plan - its projection slice, user journey, tasks, and acceptance criteria. The implementer loop tracks it via status and iteration.` | -| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | `A feature's implementation plan - rules, phases, risks, decisions. One phase file sits next to it per phase.` | +| `actions` | [02-explore.md](skills/01-plan/actions/02-explore.md) | - | +| `actions` | [03-wireframe.md](skills/01-plan/actions/03-wireframe.md) | - | +| `actions` | [04-plan.md](skills/01-plan/actions/04-plan.md) | - | +| `assets` | [phase-template.md](skills/01-plan/assets/phase-template.md) | - | +| `assets` | [plan-template.md](skills/01-plan/assets/plan-template.md) | - | | `-` | [README.md](skills/01-plan/README.md) | - | | `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.` | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. 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).` | +| `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).` | #### `skills/02-implement` diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md index 360cb276..d9532799 100644 --- a/plugins/aidd-dev/agents/planner.md +++ b/plugins/aidd-dev/agents/planner.md @@ -64,7 +64,7 @@ The plan is complete when: - 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. Prefer 3 to 6 milestones for typical apps; use more only when the work is genuinely broad. +- 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. # Decisions in scope diff --git a/plugins/aidd-dev/skills/01-plan/README.md b/plugins/aidd-dev/skills/01-plan/README.md index 4658867d..1bf79fb6 100644 --- a/plugins/aidd-dev/skills/01-plan/README.md +++ b/plugins/aidd-dev/skills/01-plan/README.md @@ -21,15 +21,16 @@ Turns a request, ticket, or file into a phased implementation plan and its phase Use skill aidd-dev:01-plan ``` -The skill runs three actions in order, the plan being the culmination: +The skill runs four actions in order, the plan being the culmination: 1. `gather` collects the source the plan rests on and restates it. Always first. -2. `wireframe` sketches a low-fidelity ASCII layout of any screen the feature needs. Frontend only, skipped when there is no UI. -3. `plan` turns the gathered source, and any confirmed wireframe, into the plan and its phases. +2. `explore` reads the codebase for the architecture projection, the applicable rules, and feasibility. Gated with the user. +3. `wireframe` sketches a low-fidelity ASCII layout of any screen the feature needs, using the explored context. Frontend only, skipped when there is no UI. +4. `plan` breaks the work into phases and writes the plan and its phase files. A feature folder `aidd_docs/tasks//_/`: -- `plan.md` from the plan template: rules, phases, risks, decisions, external resources. +- `plan.md` from the plan template: objective, phases, resources, decisions. - `phase-.md` per phase from the phase template: projection slice, user journey, tasks, acceptance criteria, any wireframe. The plan reuses the folder when the source already lives in one, so a `brainstorm.md` or `spec.md` already there sits alongside, not duplicated. diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index 26d75e65..6f0c8e27 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, gathering the source first and optionally wireframing a screen before planning. 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: 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: plan @@ -9,17 +9,22 @@ Turn a gathered source into an implementation plan and its phase files. Never wr ## Actions -Run them in order. The plan is the culmination. +| # | Action | Role | Input | +| --- | ----------- | ---------------------------------------------------- | -------------------------- | +| 01 | `gather` | Collect and restate the source | user request | +| 02 | `explore` | Read the codebase for projection, rules, feasibility | gathered source | +| 03 | `wireframe` | Sketch a screen at low fidelity, frontend only | source + explore context | +| 04 | `plan` | Break into phases, write the plan and phase files | explore output + wireframe | -1. `@actions/01-gather.md`: collect and restate the source. Always first. -2. `@actions/02-wireframe.md`: sketch any screen the feature needs. Frontend only, skip when there is no UI. -3. `@actions/03-plan.md`: turn the gathered source, and any confirmed wireframe, into the plan and its phases. +Run them in order, `01 → 04`. The plan is the culmination. Skip `03` when there is no UI. ## References -- `@references/mermaid-conventions.md`: conventions for the Mermaid diagrams a phase embeds. +- `references/mermaid-conventions.md`: conventions for the Mermaid diagrams a phase embeds. +- `references/wireframe-conventions.md`: how to draw the ASCII wireframe a screen needs. +- `references/plan-status.md`: the plan lifecycle `status` values and who writes each. ## Assets -- `@assets/plan-template.md`: the `plan.md` scaffold. Its header comment carries the field rules. -- `@assets/phase-template.md`: the per-phase scaffold. Its header comment carries the field rules. +- `assets/plan-template.md`: the `plan.md` scaffold. +- `assets/phase-template.md`: the per-phase scaffold. 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 df5e6407..becde37e 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md +++ b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md @@ -12,7 +12,7 @@ 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 the user once: a file, a ticket, or a description? Wait for the answer. Do not start without a source. +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. 3. **Restate.** Summarize the source in a few bullets: what is asked, and the hard constraints it states. No solution, no phases, no plan. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md new file mode 100644 index 00000000..8f3226d7 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md @@ -0,0 +1,23 @@ +# 02 - Explore + +Read the codebase to ground the plan: what it touches, which rules apply, what is feasible. Read only. + +## Input + +The gathered source from `01-gather`. + +## Output + +The architecture projection (files to modify, create, delete, each with a one-line reason), the project rules that apply (each justified in one line, or none), the feasibility checks (each source consulted, a doc URL or an in-repo file, and what it settled), and the risks. + +## 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. + +## Test + +- The projection lists files to modify, create, and delete, each with a one-line reason. +- Every feasibility check records its source and what it settled. +- The applicable rules are identified and justified, or none apply. diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/02-wireframe.md deleted file mode 100644 index c0573779..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/02-wireframe.md +++ /dev/null @@ -1,40 +0,0 @@ -# 02 - Wireframe - -Sketch a low-fidelity ASCII wireframe of a screen, to fix its layout before the plan. Frontend only, skip it when the feature has no UI. - -## Input - -The screen or feature to sketch, from the gathered source. - -## Output - -A low-fidelity ASCII wireframe of each screen, its regions and key elements in place, with a numbered note per region. Structure only, no behavior, no styling, no final copy. - -## Process - -1. **Pick the screens.** List the screen or screens the feature needs. Ask the user which one when it is ambiguous. Skip the action entirely when there is no UI. -2. **Block the layout.** Draw each screen as one box-drawing wireframe with `┌ ─ ┐ │ └ ┘`. Place the regions (header, nav, main, aside, footer) and the key elements (lists, forms, cards, buttons, inputs) where they sit. Number each region. Low fidelity, no colors, no final copy. -3. **Annotate.** Under the sketch, one line per numbered region on what it holds and why. -4. **Confirm.** Show the wireframe and ask the user to confirm the layout or adjust it. Wait for the answer. A confirmed layout feeds the plan. - -## Example - -``` -┌─────────────────────────────────────┐ -│ (1) Header: logo · search · account │ -├──────────┬──────────────────────────┤ -│ (2) Nav │ (3) Results list │ -│ filters │ ┌──────────────────────┐ │ -│ by type │ │ (4) Result card │ │ -│ │ └──────────────────────┘ │ -└──────────┴──────────────────────────┘ -``` - -1. Header: brand, global search, account menu. -2. Nav: filters that narrow the list. -3. Results: the matched items, paginated. -4. Card: one result, title and summary. - -## Test - -- The output is a box-drawing wireframe of each screen with numbered regions and a one-line note each, carries no behavior, styling, or final copy, and waits for the user. diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-plan.md b/plugins/aidd-dev/skills/01-plan/actions/03-plan.md deleted file mode 100644 index e11b2f54..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/03-plan.md +++ /dev/null @@ -1,26 +0,0 @@ -# 03 - Plan - -Turn the gathered source into a plan and its phases, save them, and confirm with the user. Never code. - -## Input - -The gathered source from `01-gather`, plus any confirmed wireframe from `02-wireframe`. - -## 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`. - -## Process - -1. **Explore, no sub-agent.** Read the codebase here. Produce the architecture projection (files to modify, create, delete, each with a one-line reason), the implicit assumptions, the feasibility checks against official docs (keep each URL and what it settled), and the project rules that apply. -2. **Gate: projection and rules.** Show the projection and the applicable rules. Ask "Correct? Anything to add or remove?" Iterate until approved. -3. **Gate: phases.** Break the work into 3 to 6 phases, each a coherent chunk that ships and verifies on its own, sized for one implementer pass. Show them. Iterate until approved. -4. **Write.** Resolve the feature folder: reuse the one the source already lives in when it sits under `aidd_docs/tasks//_/`, otherwise create one from the current date and a short logical feature slug. Scaffold from the templates and fill every placeholder: `plan.md`, one `phase-.md` per phase (phase 1 is `phase-1.md`), the projection sliced into each phase. Embed any confirmed wireframe in its phase. Display the paths. -5. **Gate: confidence and confirm.** Score the plan 0 to 10 with ✓ reasons and ✗ risks, and report it. Below 9, revise and rescore. At 9 or above, show the plan and its phases, challenge them with the user, and wait for approval. The score gates display, never written to the plan. - -## Test - -- `aidd_docs/tasks//_/plan.md` exists with one `phase-.md` per phase next to it. -- No `{...}` placeholder is left in any written file. -- The phase projection slices together cover the validated modify, create, and delete lists. -- A confidence score of at least 9 was reported and written to no file. diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md new file mode 100644 index 00000000..5aa3bf1a --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md @@ -0,0 +1,20 @@ +# 03 - Wireframe + +Sketch a low-fidelity ASCII wireframe of a screen, to fix its layout before the plan. Frontend only, skip it when the feature has no UI. + +## Input + +The screens to sketch, from the gathered source and the `02-explore` context (the existing screens and components). + +## Output + +A low-fidelity ASCII wireframe of each screen, its regions and key elements in place, with a numbered note per region. Structure only, no behavior, no styling, no final copy. + +## Process + +1. **Pick the screens.** 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 + +- The output is a box-drawing wireframe of each screen with numbered regions and a one-line note each, carrying no behavior, styling, or final copy. diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md new file mode 100644 index 00000000..214791ec --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md @@ -0,0 +1,24 @@ +# 04 - Plan + +Turn the explored source into a plan and its phases, save them, then review the whole until approved. Never code. + +## Input + +The explore output from `02-explore` (projection, rules, feasibility, risks), plus any confirmed wireframe from `03-wireframe`. + +## 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`. + +## 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. +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. + +## Test + +- `aidd_docs/tasks//_/plan.md` exists with one `phase-.md` per phase next to it. +- No `{...}` placeholder is left in any written file. +- The phase projection slices together cover the modify, create, and delete lists. +- A confidence score was reported and written to no file. diff --git a/plugins/aidd-dev/skills/01-plan/assets/phase-template.md b/plugins/aidd-dev/skills/01-plan/assets/phase-template.md index ae656be0..f50faecb 100644 --- a/plugins/aidd-dev/skills/01-plan/assets/phase-template.md +++ b/plugins/aidd-dev/skills/01-plan/assets/phase-template.md @@ -1,40 +1,43 @@ --- -name: phase -description: One phase of a plan - its projection slice, user journey, tasks, and acceptance criteria. The implementer loop tracks it via status and iteration. status: pending -iteration: 0 -created_at: "{YYYY-MM-DDTHH:MM:SSZ}" --- - - -# Phase: {title} +# Instruction: {title} Part of [`plan.md`](./plan.md). ## Architecture projection + + ```txt . ``` -## User journey +## User Journey ```mermaid flowchart TD A[TODO] ``` -## Tasks +## Wireframe + +```txt +{the confirmed wireframe, or omit this section when the phase has no UI} +``` + +## Tasks to do -### {n}) {name} +### `{number})` {name} -> {goal, straight to the point} +> {straight to point goal} 1. {ultra concise step} + ... -## Acceptance criteria +## Test acceptance criteria -| Task | Criterion | -| ---- | ----------------------------- | -| 1 | {focused deterministic check} | +| Task | Acceptance criteria | +| ---- | ------------------------------------ | +| 1... | {focused deterministic verification} | diff --git a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md index 7ee4a401..b1080cb1 100644 --- a/plugins/aidd-dev/skills/01-plan/assets/plan-template.md +++ b/plugins/aidd-dev/skills/01-plan/assets/plan-template.md @@ -1,48 +1,29 @@ --- -name: plan -description: A feature's implementation plan - rules, phases, risks, decisions. One phase file sits next to it per phase. -objective: "{one-line objective, matches the source}" -success_condition: "{a command or check that proves the plan is done}" -plan_status: in_progress -iteration: 0 -created_at: "{YYYY-MM-DDTHH:MM:SSZ}" +objective: "{What must be true when done. One sentence.}" +status: pending --- - - # Plan: {title} ## Overview -| Field | Value | -| -------------- | ----------------------- | -| **Risk Score** | {X}/10 | -| **Source** | {file, ticket, or text} | - -## Applicable rules - -| Tool | Rule | Path | Why it applies | -| ------ | ------ | -------- | -------------- | -| {tool} | {name} | `{path}` | {one-line why} | +| Field | Value | +| ---------- | ----------------------- | +| **Goal** | {one-line summary} | +| **Source** | {file, ticket, or text} | ## Phases -| # | Phase | File | -| --- | ------------ | ---------------------------------- | +| # | Phase | File | +| --- | ------------ | ---------------------------- | | 1 | {phase-name} | [`phase-1.md`](./phase-1.md) | | 2 | {phase-name} | [`phase-2.md`](./phase-2.md) | -## Risk register - -| Risk | Impact | Mitigation | -| -------- | ----------------------------- | ------------------------------------- | -| {risk 1} | {what breaks if this happens} | {how the plan prevents or handles it} | - -## External resources +## Resources -| Source | Verified | -| ------ | --------------------------- | -| {url} | {what it settled, one line} | +| Source | Verified | +| ------------- | --------------------------- | +| {url or path} | {what it settled, one line} | ## Decisions diff --git a/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md new file mode 100644 index 00000000..1dfb2394 --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/references/wireframe-conventions.md @@ -0,0 +1,28 @@ +# Wireframe conventions + +A wireframe is a low-fidelity ASCII sketch of a screen. Structure only: no behavior, no styling, no final copy. + +## Drawing + +- One box per screen, drawn with `┌ ─ ┐ │ └ ┘`. +- Place the regions (header, nav, main, aside, footer) and the key elements (lists, forms, cards, buttons, inputs) where they sit. +- Number each region. +- Under the sketch, one line per number on what it holds and why. + +## Example + +``` +┌─────────────────────────────────────┐ +│ (1) Header: logo · search · account │ +├──────────┬──────────────────────────┤ +│ (2) Nav │ (3) Results list │ +│ filters │ ┌──────────────────────┐ │ +│ by type │ │ (4) Result card │ │ +│ │ └──────────────────────┘ │ +└──────────┴──────────────────────────┘ +``` + +1. Header: brand, global search, account menu. +2. Nav: filters that narrow the list. +3. Results: the matched items, paginated. +4. Card: one result, title and summary. From d87e763eba6f7d639c93774aed3f841a9815760c Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 19 Jun 2026 13:40:13 +0200 Subject: [PATCH 6/8] fix(aidd-dev): make 02-implement traverse the plan's phase files explicitly The redesigned plan splits phases into phase-.md files linked from plan.md. Spell out that the phase loop opens each phase file for its scope, tasks, and acceptance criteria, so the implementer reads the feature-folder layout correctly. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/02-implement/actions/01-implement.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md index 77f1974c..80b55bad 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md @@ -22,8 +22,8 @@ notes: 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 listed in the plan, in order: - - Spawn the `implementer` agent via the `Task` tool, passing the phase scope and acceptance criteria. +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. + - 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 %. 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. From 002bd9ce59d06760605fe8f4e8a647a1b51d74a6 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 19 Jun 2026 13:45:29 +0200 Subject: [PATCH 7/8] fix(aidd-dev): track per-phase status in the phase frontmatter The implement loop now sets each phase's frontmatter status: in-progress when the phase starts, done when it reaches 100 percent. The plan's own status (in-progress to implemented) is unchanged. Phase status is no longer dead metadata. Co-Authored-By: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/skills/02-implement/actions/01-implement.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md index 80b55bad..bd2b87de 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md @@ -23,8 +23,10 @@ notes: 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. @@ -34,4 +36,4 @@ notes: ## 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, 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`. +- 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`. From a7de255f8b4a17a94a97c56a72b81493edd6343d Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE Date: Fri, 19 Jun 2026 15:48:19 +0200 Subject: [PATCH 8/8] refactor: land brainstorm and review in the feature folder Brainstorm persists to /brainstorm.md and review writes /review.md and review-functional.md, both resolve-or-reuse the feature folder under aidd_docs/tasks//_/. Joins spec.md and plan.md so the whole lifecycle of one feature lives together. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../skills/05-review/actions/01-review-code.md | 4 ++-- .../skills/05-review/actions/02-review-functional.md | 4 ++-- plugins/aidd-refine/skills/01-brainstorm/README.md | 2 +- .../skills/01-brainstorm/actions/04-finalize.md | 10 +++++----- 4 files changed, 10 insertions(+), 10 deletions(-) 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 63978f69..0d2dc108 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 @@ -11,7 +11,7 @@ scope: # optional; defaults to `git diff main` ## Outputs ```yaml -review_path: aidd_docs/tasks//-.review.md +review_path: aidd_docs/tasks//_/review.md verdict: approve | changes-requested | blocked findings_count: severity_breakdown: @@ -27,7 +27,7 @@ severity_breakdown: 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`. Create the month directory when missing. +6. **Write to disk** at `aidd_docs/tasks//_/review.md`. Reuse the feature folder of the reviewed work when it exists, otherwise create it. ## 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 8e3c9b9d..4b3bd0a0 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 @@ diff_scope: # optional; defaults to `git diff mai ## Outputs ```yaml -review_path: aidd_docs/tasks//-.review_functional.md +review_path: aidd_docs/tasks//_/review-functional.md criteria_total: criteria_traced: missing_behaviors: @@ -38,7 +38,7 @@ Check against: 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`. Create the month directory when missing. +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. ## Test diff --git a/plugins/aidd-refine/skills/01-brainstorm/README.md b/plugins/aidd-refine/skills/01-brainstorm/README.md index 74d23687..4ab29000 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/README.md +++ b/plugins/aidd-refine/skills/01-brainstorm/README.md @@ -18,7 +18,7 @@ Turns a vague idea into a precise one through a deep, natural conversation, at w ## The loop -`capture` restates the idea and reads its altitude. Then `probe → integrate` repeats: each round asks pointed questions on the live thread, follows the forks the answers open, challenges assumptions, and folds the answers back in. It keeps going until no real ambiguity remains or the user is satisfied. There is no fixed round count, the idea is done when it is clear, not on a timer. `finalize` consolidates the refined idea, flags every open assumption and risk, and offers to persist it to a dated file under `aidd_docs/brainstorm/`, a ticket, or the session only. +`capture` restates the idea and reads its altitude. Then `probe → integrate` repeats: each round asks pointed questions on the live thread, follows the forks the answers open, challenges assumptions, and folds the answers back in. It keeps going until no real ambiguity remains or the user is satisfied. There is no fixed round count, the idea is done when it is clear, not on a timer. `finalize` consolidates the refined idea, flags every open assumption and risk, and offers to persist it as `brainstorm.md` in the feature folder under `aidd_docs/tasks/`, a ticket, or the session only. ## What makes it dig diff --git a/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md b/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md index 401e7a2d..bf4ece30 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md +++ b/plugins/aidd-refine/skills/01-brainstorm/actions/04-finalize.md @@ -8,7 +8,7 @@ The clarified idea and the conversation so far. ## Output -The approved refined idea with its flagged open assumptions and risks, a pointer to the fitting next step, and, when the user picks the file, a markdown file at `aidd_docs/brainstorm/-.md`. +The approved refined idea with its flagged open assumptions and risks, a pointer to the fitting next step, and, when the user picks the file, a markdown file at `aidd_docs/tasks//_/brainstorm.md`. ## Process @@ -17,16 +17,16 @@ The approved refined idea with its flagged open assumptions and risks, a pointer 3. **Get approval.** Show the refined idea and the open list, and ask the user to confirm or correct. Wait for the answer. 4. **Point to the next move.** Say in plain words what the refined idea is now ready for, planning it, specifying it, or building it, so the user's next request reaches the right tool on its own. Describe the move, never name a plugin or skill, and never run it. 5. **Offer to persist.** Once approved, present all three destinations and act on the pick. Name all three, persist nothing without the user's choice. - - **File.** Write the document to exactly `aidd_docs/brainstorm/-.md`, where `` is today's date and `` is the idea in kebab-case. The directory and format are fixed, never another path or name. Create `aidd_docs/brainstorm/` if missing. + - **File.** Write the document to the feature folder as `aidd_docs/tasks//_/brainstorm.md`, where `` is today's date and `` is the idea in kebab-case. Reuse the feature folder when one already exists for this idea, otherwise create it. The format is fixed, never another name. | Idea, saved on | File written | | --- | --- | - | aidd-craft plugin, 2026-03-09 | `aidd_docs/brainstorm/2026_03_09-aidd-craft-plugin.md` | - | dark mode toggle, 2026-11-20 | `aidd_docs/brainstorm/2026_11_20-dark-mode-toggle.md` | + | aidd-craft plugin, 2026-03-09 | `aidd_docs/tasks/2026_03/2026_03_09_aidd-craft-plugin/brainstorm.md` | + | dark mode toggle, 2026-11-20 | `aidd_docs/tasks/2026_11/2026_11_20_dark-mode-toggle/brainstorm.md` | - **Ticket.** Open or append a ticket drawn from the memory and VCS context. - **Session.** Keep it in the conversation only, write nothing. ## Test - The output is a consolidated intent-level idea plus an explicit list of open assumptions and risks, approved by the user, and it names all three persist destinations and the fitting next move without a `plugin:skill` identifier. -- When the user picks the file, a file exists afterward at `aidd_docs/brainstorm/-.md` and nowhere else. +- When the user picks the file, a file exists afterward at `aidd_docs/tasks//_/brainstorm.md` and nowhere else.