diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 31371ab1..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` | 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` | diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 32595145..f428707a 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/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` diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index 349b66e1..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 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. | diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md index fc0506cc..d9532799 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: @@ -39,7 +39,7 @@ decisions_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 @@ -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/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 9962491a..1bf79fb6 100644 --- a/plugins/aidd-dev/skills/01-plan/README.md +++ b/plugins/aidd-dev/skills/01-plan/README.md @@ -2,27 +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. +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 @@ -30,27 +21,25 @@ 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 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//_/`: -- 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-.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. diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index 097dcbf4..ba696e19 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/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. 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..becde37e --- /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 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. 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 15863fcf..00000000 --- a/plugins/aidd-dev/skills/01-plan/actions/01-plan.md +++ /dev/null @@ -1,72 +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. - -## 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: }] -``` - -## 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: - - 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. -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`. - - 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.** - - 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): `objective`, `status: pending`. - - 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` - - 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. - -## Test - -The plan file exists at `plan_path`; its frontmatter contains `objective` and `status: pending`; 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-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-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/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/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/master-plan-template.md b/plugins/aidd-dev/skills/01-plan/assets/master-plan-template.md deleted file mode 100644 index eaee3ebe..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` | pending | [ ] | - - - - -## 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..f50faecb --- /dev/null +++ b/plugins/aidd-dev/skills/01-plan/assets/phase-template.md @@ -0,0 +1,43 @@ +--- +status: pending +--- + +# Instruction: {title} + +Part of [`plan.md`](./plan.md). + +## Architecture projection + + + +```txt +. +``` + +## User Journey + +```mermaid +flowchart TD + A[TODO] +``` + +## Wireframe + +```txt +{the confirmed wireframe, or omit this section when the phase has no UI} +``` + +## 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 a883d334..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,106 +1,32 @@ --- -name: plan -description: Living implementation plan - frozen objective, phases, and acceptance criteria. -argument-hint: N/A objective: "{What must be true when done. One sentence.}" status: pending --- - +## Overview -# Instruction: {title} +| Field | Value | +| ---------- | ----------------------- | +| **Goal** | {one-line summary} | +| **Source** | {file, ticket, or text} | -## Feature +## Phases -- **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} +| # | Phase | File | +| --- | ------------ | ---------------------------- | +| 1 | {phase-name} | [`phase-1.md`](./phase-1.md) | +| 2 | {phase-name} | [`phase-2.md`](./phase-2.md) | -## Architecture projection +## Resources - +| Source | Verified | +| ------------- | --------------------------- | +| {url or path} | {what it settled, one line} | -### Files to modify +## Decisions -- `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] -``` - -## Risk register - - - -| Risk | Impact | Mitigation | -| -------- | ----------------------------- | ------------------------------------- | -| {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 - - - -1. {Step 1...} +| 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/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. 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 b74d35e7..bd2b87de 100644 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md @@ -20,16 +20,20 @@ notes: ## Process -1. **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. -2. **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. +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 %. -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. -6. **Blocked.** If the implementer surfaces `BLOCKED` in its notes (see the blocked reference), set `status: blocked` and stop the loop. -7. **Mark implemented.** Every phase at 100% + validation passes → set `status: implemented`. + - Set the phase frontmatter `status: done` once it reaches 100 %. +4. **Plan amendments.** If a phase is incorrect, incomplete, or blocked by missing information, amend the plan directly. Mark every change with 🤖 and a brief rationale. +5. **Boundaries.** Never format code. Never run dev mode. Follow project rules already loaded in context. +6. **Verify the feature.** Run validation commands, tests, and any manual checks required to confirm the feature works end to end. +7. **Blocked.** If the implementer surfaces `BLOCKED` in its notes (see the blocked reference), set `status: blocked` and stop the loop. +8. **Mark implemented.** Every phase at 100% + validation passes → set `status: implemented`. ## Test -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`. +- A missing or unreadable plan path with no inline plan content stops the skill with `plan not found at `, and no substitute plan is fabricated. +- After the loop terminates: every phase has its acceptance criteria checked off and its frontmatter `status` is `done`, validation commands exit zero, and the plan's frontmatter `status` is `implemented` — OR, if a blocking condition held, the loop stopped and it is `blocked`. diff --git a/plugins/aidd-dev/skills/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-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 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/SKILL.md b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md index 934c426a..94b10962 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md +++ b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md @@ -1,7 +1,7 @@ --- name: 01-brainstorm description: Clarify a vague idea through deep back-and-forth questioning until it is precise enough to act on. Works at any level, functional, technical, or mixed. Use when the user surfaces a half-formed idea, a fuzzy feature, a technical question, or an under-specified request, or asks to brainstorm, clarify, or refine before committing. Keeps probing and following each answer's threads until no real ambiguity remains or the user is satisfied. Not for analytically scanning a written artifact for gaps (use aidd-refine:04-shadow-areas), critiquing finished work (use aidd-refine:02-challenge), or any implementation, planning, or code. -argument-hint: capture-request | ask-probing-questions | integrate-answers | refine-and-validate | confirm-approval +argument-hint: capture | probe | integrate | finalize --- # Brainstorm 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.