refactor(aidd-dev): redesign 01-plan into gather/explore/wireframe/plan

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`       | 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` |

plugins/aidd-dev/CATALOG.md

@@ -55,16 +55,17 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai
 
 | Group | File | Description |
 |-------|------|---|
-| `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) | - |
-| `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 acceptance criteria.` |
-| `assets` | [tech-choice-template.md](skills/01-plan/assets/tech-choice-template.md) | `Technology selection and comparison template` |
+| `actions` | [01-gather.md](skills/01-plan/actions/01-gather.md) | - |
+| `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) | `Generate technical implementation plans, define component behaviors, and extract design details from images.` |
+| `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`
 

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) | 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. |

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: <absolute path to the plan or master-plan written to disk>
-child_paths: [<paths to child plans, empty if simple plan>]
+plan_path: <absolute path to the plan file written to disk>
+child_paths: [<absolute paths to the phase files, one per phase>]
 decisions_made:
   - id: <n>
     topic: <what>
@@ -39,7 +39,7 @@ decisions_blocked:
 notes: <observations relevant to next iteration>
 ```
 
-`plan_path` and `child_paths` reflect what `aidd-dev:01-plan` actually wrote  -  the skill picks the path (typically `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>-?<#ticket>-<feature>.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/<yyyy_mm>/<yyyy_mm_dd>_<feature-slug>/`, the plan as `plan.md` and one phase file `phase-<n>.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
 
@@ -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

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.

plugins/aidd-dev/skills/01-plan/README.md

@@ -2,55 +2,44 @@
 
 # 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.
+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 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 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
 
-- 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.
+- 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 3 actions:
+The skill runs four actions in order, the plan being the culmination:
 
-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.
+1. `gather` collects the source the plan rests on and restates it. Always first.
+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.
 
-## Outputs
+A feature folder `aidd_docs/tasks/<yyyy_mm>/<yyyy_mm_dd>_<feature-slug>/`:
 
-- 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.
+- `plan.md` from the plan template: objective, phases, resources, decisions.
+- `phase-<n>.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.
 
 ## Prerequisites
 
-- A validated spec, ticket, or design source as input.
-- Access to the plan template asset bundled with this skill.
+- A request, ticket, or file as the source.
+- The plan and phase templates 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/).
+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.

plugins/aidd-dev/skills/01-plan/SKILL.md

@@ -1,44 +1,31 @@
 ---
 name: 01-plan
-description: Generate technical implementation plans, define component behaviors, and extract design details from images.
-argument-hint: plan | components-behavior | image-extract-details
-model: opus
-context: fork
-agent: planner
+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).
+argument-hint: gather | explore | wireframe | plan
 ---
 
 # Skill: plan
 
-Produces implementation plans from requirements, state machines for component behavior, and structured component inventories from design images.
+Turn a gathered source into an implementation plan and its phase files. 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  | `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              |
-
-## 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.
+## Actions
 
-- 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`.
-- Anything else (requirements, a feature to build) -> `01-plan`.
+| #   | 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 |
 
-Actions may chain (e.g. extract from image, then plan). Read and follow each selected action file.
+Run them in order, `01 → 04`. The plan is the culmination. Skip `03` when there is no UI.
 
-## Actions
+## References
 
-- `@actions/01-plan.md`
-- `@actions/02-components-behavior.md`
-- `@actions/03-image-extract-details.md`
+- `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.
 
-## References
+## Assets
 
-- `@references/plan-status.md` - plan lifecycle `status` values, meaning, and who writes each. All actions inherit it; do not re-specify the table elsewhere.
+- `assets/plan-template.md`: the `plan.md` scaffold.
+- `assets/phase-template.md`: the per-phase scaffold.

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 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.
+
+## 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.