From 109688495dccd28952455a2c97ca28e274fde528 Mon Sep 17 00:00:00 2001 From: Alex <8973343+alexsoyes@users.noreply.github.com> Date: Fri, 19 Jun 2026 13:18:50 +0200 Subject: [PATCH 01/14] feat(skills): sync argument hints (#296) --- lefthook.yml | 11 +- .../aidd-context/skills/00-onboard/SKILL.md | 1 + .../aidd-context/skills/01-bootstrap/SKILL.md | 1 + .../skills/02-project-memory/SKILL.md | 1 + .../skills/04-skill-generate/SKILL.md | 1 + .../actions/03-draft-skill.md | 4 +- .../actions/04-write-actions.md | 6 +- .../assets/skill-template.md | 1 + .../references/skill-authoring.md | 1 + .../skills/05-rule-generate/SKILL.md | 1 + .../skills/06-agent-generate/SKILL.md | 1 + .../skills/07-command-generate/SKILL.md | 1 + .../skills/08-hook-generate/SKILL.md | 1 + plugins/aidd-context/skills/10-learn/SKILL.md | 1 + .../aidd-context/skills/11-explore/SKILL.md | 1 + plugins/aidd-context/skills/12-cook/SKILL.md | 1 + plugins/aidd-dev/CATALOG.md | 80 ++++++------ plugins/aidd-dev/skills/00-sdlc/SKILL.md | 1 + plugins/aidd-dev/skills/01-plan/SKILL.md | 1 + plugins/aidd-dev/skills/03-assert/SKILL.md | 1 + plugins/aidd-dev/skills/04-audit/SKILL.md | 1 + plugins/aidd-dev/skills/05-review/SKILL.md | 1 + plugins/aidd-dev/skills/06-test/SKILL.md | 1 + plugins/aidd-dev/skills/07-refactor/SKILL.md | 1 + plugins/aidd-dev/skills/08-debug/SKILL.md | 1 + plugins/aidd-dev/skills/09-for-sure/SKILL.md | 1 + .../skills/00-async-dev/SKILL.md | 1 + plugins/aidd-pm/CATALOG.md | 26 ++-- plugins/aidd-pm/skills/04-spec/SKILL.md | 1 + .../aidd-refine/skills/01-brainstorm/SKILL.md | 1 + .../aidd-refine/skills/03-condense/SKILL.md | 1 + .../skills/04-shadow-areas/SKILL.md | 1 + .../aidd-refine/skills/05-fact-check/SKILL.md | 1 + plugins/aidd-vcs/CATALOG.md | 56 ++++----- scripts/summarize-markdown.js | 11 +- scripts/sync-skill-argument-hints.mjs | 119 ++++++++++++++++++ 36 files changed, 253 insertions(+), 88 deletions(-) create mode 100755 scripts/sync-skill-argument-hints.mjs diff --git a/lefthook.yml b/lefthook.yml index 7821aa66..f51e108f 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -33,6 +33,15 @@ pre-commit: exit 1 fi done + sync-skill-argument-hints: + glob: "plugins/*/skills/**" + run: | + if ! command -v node >/dev/null 2>&1; then + echo "ℹ️ node not available; skipping sync-skill-argument-hints" + exit 0 + fi + node scripts/sync-skill-argument-hints.mjs >/dev/null + git add plugins/*/skills/*/SKILL.md 2>/dev/null || true summarize-plugin-catalogs: run: | [ -d plugins ] || exit 0 @@ -44,7 +53,7 @@ pre-commit: name=$(basename "$plugin") node scripts/summarize-markdown.js "$plugin" "${plugin}CATALOG.md" \ --depth=4 \ - --fields=description,argument-hint \ + --fields=description \ --title="$name catalog" \ --tagline="Auto-generated index of skills, agents, references and assets shipped by the \`$name\` plugin." \ >/dev/null diff --git a/plugins/aidd-context/skills/00-onboard/SKILL.md b/plugins/aidd-context/skills/00-onboard/SKILL.md index c873ebca..38f9202c 100644 --- a/plugins/aidd-context/skills/00-onboard/SKILL.md +++ b/plugins/aidd-context/skills/00-onboard/SKILL.md @@ -1,6 +1,7 @@ --- name: 00-onboard description: Guide the user through the AIDD framework on the current project. Explain the flow in plain language and suggest the next logical step, adapted to what is already set up and which AIDD plugins are installed. Use when the user asks where to start, what to do next, how AIDD works, or to be onboarded. Not for listing every installed surface (the explore skill does that) or running a skill the user already knows they need (invoke it directly). +argument-hint: read-project | orient | act --- # Onboard diff --git a/plugins/aidd-context/skills/01-bootstrap/SKILL.md b/plugins/aidd-context/skills/01-bootstrap/SKILL.md index d5f8efa2..a2ce5d0c 100644 --- a/plugins/aidd-context/skills/01-bootstrap/SKILL.md +++ b/plugins/aidd-context/skills/01-bootstrap/SKILL.md @@ -1,6 +1,7 @@ --- name: 01-bootstrap description: Imagine and validate the technical architecture of a new SaaS through interactive Q&A, candidate-stack comparison, multi-agent audit, and an INSTALL.md output. Use when starting a new SaaS project, choosing a stack, designing the architecture pattern (monolith vs microservices vs serverless), or producing a project's INSTALL.md. Do NOT use for editing an existing project's stack, database schema design, or scaffolding actual files (this skill produces docs only, no code). +argument-hint: gather-needs | propose-candidates | audit-candidates | pick-and-design | write-install-md --- # Bootstrap diff --git a/plugins/aidd-context/skills/02-project-memory/SKILL.md b/plugins/aidd-context/skills/02-project-memory/SKILL.md index 28af6162..de12e39c 100644 --- a/plugins/aidd-context/skills/02-project-memory/SKILL.md +++ b/plugins/aidd-context/skills/02-project-memory/SKILL.md @@ -1,6 +1,7 @@ --- name: 02-project-memory description: Initialize or refresh the project memory bank. Not for updating one memory file after it exists (use the learn skill) or editing a single rule (edit it directly). +argument-hint: init-context-file | scaffold-docs | generate-memory | review-memory | sync-memory --- # Project Memory diff --git a/plugins/aidd-context/skills/04-skill-generate/SKILL.md b/plugins/aidd-context/skills/04-skill-generate/SKILL.md index 34aa875d..fbe94307 100644 --- a/plugins/aidd-context/skills/04-skill-generate/SKILL.md +++ b/plugins/aidd-context/skills/04-skill-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 04-skill-generate description: Generate a router-based skill across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a skill, or turn a workflow into one. Not for other artifacts like rules, agents, commands, hooks. +argument-hint: capture-intent | decompose-actions | draft-skill | write-actions | validate --- # Skill Generate diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md b/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md index 5b29b1ac..db3d136a 100644 --- a/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md +++ b/plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md @@ -14,7 +14,7 @@ One SKILL.md per confirmed tool, and the list of files written. 1. **Build.** Copy `@../assets/skill-template.md` into one canonical SKILL.md. Strip the scaffold (comments + `<...>`). - Modify: edit in place. Keep non-router sections, change only the touched rows. -2. **Frontmatter.** Fill per R5 and the naming (`@../references/skill-authoring.md`). `name` equals the folder. Manual mode adds the manual-only flag. +2. **Frontmatter.** Fill per R5 and the naming (`@../references/skill-authoring.md`). `name` equals the folder. For plugin source, or host tools that support it, `argument-hint` lists action names only when the skill has two or more actions, joined with ` | `, and must match the action plan. Manual mode adds the manual-only flag. - Host: per-tool frontmatter (`@../references/tool-paths.md`). - Plugin source: keep canonical `name` + `description`. Reconciled at install. 3. **Body.** Write the action table. State the flow in one line. @@ -31,4 +31,4 @@ One SKILL.md per confirmed tool, and the list of files written. - Each SKILL.md exists and starts with `---` frontmatter. - Each is 500 lines or fewer and sits under the target base. -- The action-table slugs match the plan. +- The action-table slugs match the plan. `argument-hint` is omitted for one-action skills; when emitted, its action names match the plan. diff --git a/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md b/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md index 26862bfa..4dfdd597 100644 --- a/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md +++ b/plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md @@ -14,11 +14,13 @@ One file per action, per confirmed tool, at `//actions/-< 1. **Resolve.** Host mode: for each confirmed tool, resolve the skills root from `@../references/tool-paths.md`. Plugin source: use `plugins//skills//`. 2. **Fill.** For each action, fill `@../assets/action-template.md`: strip the scaffold (comments + `<...>`), copy the test from 02 verbatim into `## Test`. +3. **Sync hint.** When the parent SKILL.md accepts `argument-hint` and has two or more actions, update it from the final action file names only, joined with ` | `. Omit it for one-action skills. In this repository, run `node scripts/sync-skill-argument-hints.mjs`; otherwise edit the field directly. - Modify: write only the changed actions, leave the rest untouched. -3. **Compose.** Include any template or reference via `@`. Never "read X then apply". -4. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). +4. **Compose.** Include any template or reference via `@`. Never "read X then apply". +5. **Validate.** Run the write-target validation (`@../references/tool-paths.md`). ## Test - Each action file exists and carries `## Output`, `## Process`, `## Test`. +- One-action skills omit `argument-hint`. When present, the parent SKILL.md `argument-hint` lists the same action names as the action files. - Each sits under the target base. diff --git a/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md b/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md index 3af4e1bd..4d161330 100644 --- a/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md +++ b/plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md @@ -1,6 +1,7 @@ --- name: description: . Use when . , use " only when a sibling skill could mis-trigger.> (<= 1024 chars, third person, no XML tags; all "when" lives here, not in the body.) +argument-hint: # omit when the skill has only one action --- # diff --git a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md index c9582fbd..746aabc5 100644 --- a/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md +++ b/plugins/aidd-context/skills/04-skill-generate/references/skill-authoring.md @@ -41,6 +41,7 @@ The router: YAML frontmatter + markdown body. - `name` (kebab-case, <= 64 chars) MUST equal the skill's folder name. No colon, slash, dot, plugin prefix, or namespace. Reserved words forbidden: `anthropic`, `claude`. Regex `^[a-z0-9]+(-[a-z0-9]+)*$`. - `description`: per R5. +- `argument-hint` when supported or in plugin source and the skill has two or more actions: action names only, joined with ` | `, matching the files in `actions/`. Omit it for one-action skills. - A manual-only flag makes the skill user-only. The exact frontmatter key is per tool. - Body: pure router. The action table maps each `#` and slug to a role and input. State the flow (a sequential chain or a trigger-to-action map). Self-skips stated explicitly. diff --git a/plugins/aidd-context/skills/05-rule-generate/SKILL.md b/plugins/aidd-context/skills/05-rule-generate/SKILL.md index 696b9f74..67e51723 100644 --- a/plugins/aidd-context/skills/05-rule-generate/SKILL.md +++ b/plugins/aidd-context/skills/05-rule-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 05-rule-generate description: Generate a coding rule that governs editor and agent behavior, across the host AI tools a project uses. Use when the user wants to write, add, or refactor a rule, a convention, or a coding standard, or to scan a codebase and propose rules. Not for other artifacts like skills, agents, commands, hooks. +argument-hint: capture-rule | write-rule | validate --- # Rule Generate diff --git a/plugins/aidd-context/skills/06-agent-generate/SKILL.md b/plugins/aidd-context/skills/06-agent-generate/SKILL.md index bbebf4ee..ed658a19 100644 --- a/plugins/aidd-context/skills/06-agent-generate/SKILL.md +++ b/plugins/aidd-context/skills/06-agent-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 06-agent-generate description: Generate an agent across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor an agent, subagent or specialized role. Not for other artifacts like skills, rules, commands, hooks. +argument-hint: capture-agent | write-agent | validate --- # Agent Generate diff --git a/plugins/aidd-context/skills/07-command-generate/SKILL.md b/plugins/aidd-context/skills/07-command-generate/SKILL.md index f0d40d02..6f349a3d 100644 --- a/plugins/aidd-context/skills/07-command-generate/SKILL.md +++ b/plugins/aidd-context/skills/07-command-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 07-command-generate description: Generate a flat slash command across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a one-shot slash command. Not for multi-step skills or other artifacts like rules, agents, hooks. +argument-hint: capture-command | write-command | validate --- # Command Generate diff --git a/plugins/aidd-context/skills/08-hook-generate/SKILL.md b/plugins/aidd-context/skills/08-hook-generate/SKILL.md index 07769648..ac77e824 100644 --- a/plugins/aidd-context/skills/08-hook-generate/SKILL.md +++ b/plugins/aidd-context/skills/08-hook-generate/SKILL.md @@ -1,6 +1,7 @@ --- name: 08-hook-generate description: Generate a hook (a handler that runs automatically at a lifecycle event) across the host AI tools a project uses. Use when the user wants to create, scaffold, or refactor a hook, or automate an action at a lifecycle point. Not for other artifacts like skills, rules, agents, commands. +argument-hint: capture-hook | write-hook | validate --- # Hook Generate diff --git a/plugins/aidd-context/skills/10-learn/SKILL.md b/plugins/aidd-context/skills/10-learn/SKILL.md index 2abbab67..8ee8014b 100644 --- a/plugins/aidd-context/skills/10-learn/SKILL.md +++ b/plugins/aidd-context/skills/10-learn/SKILL.md @@ -1,6 +1,7 @@ --- name: 10-learn description: Capture durable project learnings from the conversation or the project's git history and route them to memory, a decision record, a rule, or a new skill. Use when the user asks to capture, record, or remember a decision, a convention, or a lesson, or to distill what recent work taught. Scores each candidate and confirms before writing. Not for personal or AI preferences, routine edits, or anything already captured. +argument-hint: gather | assess | write | sync --- # Learn diff --git a/plugins/aidd-context/skills/11-explore/SKILL.md b/plugins/aidd-context/skills/11-explore/SKILL.md index d7558dd2..34b9338b 100644 --- a/plugins/aidd-context/skills/11-explore/SKILL.md +++ b/plugins/aidd-context/skills/11-explore/SKILL.md @@ -1,6 +1,7 @@ --- name: 11-explore description: Explore the current project across its tooling, context, and codebase. Use to survey what is installed and set up, see what is available, or find which installed skill, agent, or rule fits a goal. Not for the next step to take (onboard does that) or running an item (this skill only points). +argument-hint: survey | drill --- # Explore diff --git a/plugins/aidd-context/skills/12-cook/SKILL.md b/plugins/aidd-context/skills/12-cook/SKILL.md index e0b61a88..2cd52dbc 100644 --- a/plugins/aidd-context/skills/12-cook/SKILL.md +++ b/plugins/aidd-context/skills/12-cook/SKILL.md @@ -1,6 +1,7 @@ --- name: 12-cook description: Manage the project's recipes/ how-to sheets: list them as a table, or create and update one from the canonical template. Use for "list recipes", "new recipe", "update a recipe", "cook a recipe". +argument-hint: list | upsert --- # Cook diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index ec41b86e..32595145 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -53,18 +53,18 @@ 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-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` | - | -| `-` | [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.` | - | +| 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` | +| `-` | [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.` | #### `skills/02-implement` @@ -88,29 +88,29 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai #### `skills/04-audit` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-code-quality.md](skills/04-audit/actions/01-code-quality.md) | - | - | -| `actions` | [02-architecture.md](skills/04-audit/actions/02-architecture.md) | - | - | -| `actions` | [03-security.md](skills/04-audit/actions/03-security.md) | - | - | -| `actions` | [04-dependencies.md](skills/04-audit/actions/04-dependencies.md) | - | - | -| `actions` | [05-performance.md](skills/04-audit/actions/05-performance.md) | - | - | -| `actions` | [06-tests.md](skills/04-audit/actions/06-tests.md) | - | - | -| `actions` | [07-ui.md](skills/04-audit/actions/07-ui.md) | - | - | -| `assets` | [audit-template.md](skills/04-audit/assets/audit-template.md) | `Codebase audit report template` | - | -| `-` | [README.md](skills/04-audit/README.md) | - | - | -| `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Read-only codebase audit across quality pillars (code-quality, architecture, security, dependencies, performance, tests, ui). Diagnoses and reports findings; never edits code. Use when the user wants to assess, audit, or health-check a codebase or one dimension of it, then hands off to the act-skills (refactor, test, impeccable) to fix. Do NOT use for fixing the findings (hand off to refactor/test/impeccable), per-PR code review (use 05-review), or validating that a feature works (use 03-assert).` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-code-quality.md](skills/04-audit/actions/01-code-quality.md) | - | +| `actions` | [02-architecture.md](skills/04-audit/actions/02-architecture.md) | - | +| `actions` | [03-security.md](skills/04-audit/actions/03-security.md) | - | +| `actions` | [04-dependencies.md](skills/04-audit/actions/04-dependencies.md) | - | +| `actions` | [05-performance.md](skills/04-audit/actions/05-performance.md) | - | +| `actions` | [06-tests.md](skills/04-audit/actions/06-tests.md) | - | +| `actions` | [07-ui.md](skills/04-audit/actions/07-ui.md) | - | +| `assets` | [audit-template.md](skills/04-audit/assets/audit-template.md) | `Codebase audit report template` | +| `-` | [README.md](skills/04-audit/README.md) | - | +| `-` | [SKILL.md](skills/04-audit/SKILL.md) | `Read-only codebase audit across quality pillars (code-quality, architecture, security, dependencies, performance, tests, ui). Diagnoses and reports findings; never edits code. Use when the user wants to assess, audit, or health-check a codebase or one dimension of it, then hands off to the act-skills (refactor, test, impeccable) to fix. Do NOT use for fixing the findings (hand off to refactor/test/impeccable), per-PR code review (use 05-review), or validating that a feature works (use 03-assert).` | #### `skills/05-review` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | - | -| `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | - | -| `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` | - | -| `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` | - | -| `-` | [README.md](skills/05-review/README.md) | - | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | +| `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | +| `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` | +| `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` | +| `-` | [README.md](skills/05-review/README.md) | - | +| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | #### `skills/06-test` @@ -146,14 +146,14 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai #### `skills/09-for-sure` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-init-tracking.md](skills/09-for-sure/actions/01-init-tracking.md) | - | - | -| `actions` | [02-auto-accept.md](skills/09-for-sure/actions/02-auto-accept.md) | - | - | -| `actions` | [03-autonomous-loop.md](skills/09-for-sure/actions/03-autonomous-loop.md) | - | - | -| `assets` | [plan-template.md](skills/09-for-sure/assets/plan-template.md) | `For Sure autonomous-loop tracking file. Extends the 01-plan format with `success_condition` and `iteration` (For-Sure-only), which the loop runs and increments.` | - | -| `-` | [README.md](skills/09-for-sure/README.md) | - | - | -| `-` | [SKILL.md](skills/09-for-sure/SKILL.md) | `Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-init-tracking.md](skills/09-for-sure/actions/01-init-tracking.md) | - | +| `actions` | [02-auto-accept.md](skills/09-for-sure/actions/02-auto-accept.md) | - | +| `actions` | [03-autonomous-loop.md](skills/09-for-sure/actions/03-autonomous-loop.md) | - | +| `assets` | [plan-template.md](skills/09-for-sure/assets/plan-template.md) | `For Sure autonomous-loop tracking file. Extends the 01-plan format with `success_condition` and `iteration` (For-Sure-only), which the loop runs and increments.` | +| `-` | [README.md](skills/09-for-sure/README.md) | - | +| `-` | [SKILL.md](skills/09-for-sure/SKILL.md) | `Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria.` | #### `skills/10-todo` diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index c6c4162a..6f650312 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -1,6 +1,7 @@ --- name: 00-sdlc description: Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated. +argument-hint: spec | plan | implement | review | ship --- # Skill: sdlc diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index 9fd3e2d9..097dcbf4 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,6 +1,7 @@ --- 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 diff --git a/plugins/aidd-dev/skills/03-assert/SKILL.md b/plugins/aidd-dev/skills/03-assert/SKILL.md index 32646380..6594114d 100644 --- a/plugins/aidd-dev/skills/03-assert/SKILL.md +++ b/plugins/aidd-dev/skills/03-assert/SKILL.md @@ -1,6 +1,7 @@ --- name: 03-assert description: Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. +argument-hint: assert | assert-architecture | assert-frontend model: sonnet --- diff --git a/plugins/aidd-dev/skills/04-audit/SKILL.md b/plugins/aidd-dev/skills/04-audit/SKILL.md index d4f98968..714f7d2d 100644 --- a/plugins/aidd-dev/skills/04-audit/SKILL.md +++ b/plugins/aidd-dev/skills/04-audit/SKILL.md @@ -1,6 +1,7 @@ --- name: 04-audit description: Read-only codebase audit across quality pillars (code-quality, architecture, security, dependencies, performance, tests, ui). Diagnoses and reports findings; never edits code. Use when the user wants to assess, audit, or health-check a codebase or one dimension of it, then hands off to the act-skills (refactor, test, impeccable) to fix. Do NOT use for fixing the findings (hand off to refactor/test/impeccable), per-PR code review (use 05-review), or validating that a feature works (use 03-assert). +argument-hint: code-quality | architecture | security | dependencies | performance | tests | ui model: opus --- diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index 5de8c5f9..b5d2fdbc 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,6 +1,7 @@ --- name: 05-review description: Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). +argument-hint: review-code | review-functional model: opus context: fork agent: reviewer diff --git a/plugins/aidd-dev/skills/06-test/SKILL.md b/plugins/aidd-dev/skills/06-test/SKILL.md index aa1e8bd8..9f67186d 100644 --- a/plugins/aidd-dev/skills/06-test/SKILL.md +++ b/plugins/aidd-dev/skills/06-test/SKILL.md @@ -1,6 +1,7 @@ --- name: 06-test description: Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser. +argument-hint: test | test-journey model: sonnet --- diff --git a/plugins/aidd-dev/skills/07-refactor/SKILL.md b/plugins/aidd-dev/skills/07-refactor/SKILL.md index a0a88431..52e66b60 100644 --- a/plugins/aidd-dev/skills/07-refactor/SKILL.md +++ b/plugins/aidd-dev/skills/07-refactor/SKILL.md @@ -1,6 +1,7 @@ --- name: 07-refactor description: Improve code without breaking behavior across four axes - cleanup (clean-code + tech debt), performance, security, architecture. Scans and fixes, or fixes the findings of an audit report pushed in by the caller. Use when the user wants to refactor, clean up, optimize, harden, or restructure code. Do NOT use for read-only diagnosis (use 04-audit), adding tests (use 06-test), or UI redesign (use the impeccable skill). +argument-hint: performance | security | cleanup | architecture --- # Skill: refactor diff --git a/plugins/aidd-dev/skills/08-debug/SKILL.md b/plugins/aidd-dev/skills/08-debug/SKILL.md index f809908c..1c5a1f1d 100644 --- a/plugins/aidd-dev/skills/08-debug/SKILL.md +++ b/plugins/aidd-dev/skills/08-debug/SKILL.md @@ -1,6 +1,7 @@ --- name: 08-debug description: Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. +argument-hint: reproduce | debug | reflect-issue model: opus --- diff --git a/plugins/aidd-dev/skills/09-for-sure/SKILL.md b/plugins/aidd-dev/skills/09-for-sure/SKILL.md index f4f5fcac..989821e3 100644 --- a/plugins/aidd-dev/skills/09-for-sure/SKILL.md +++ b/plugins/aidd-dev/skills/09-for-sure/SKILL.md @@ -1,6 +1,7 @@ --- name: 09-for-sure description: Iterative agent loop that tracks attempts and retries until a success condition is met. Use when the user says "for sure", "make sure", "keep trying until", "loop until done", "don't stop until", or needs guaranteed completion of a task with explicit success criteria. +argument-hint: init-tracking | auto-accept | autonomous-loop --- # For Sure diff --git a/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md b/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md index c4bf21d5..d045bc2a 100644 --- a/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md +++ b/plugins/aidd-orchestrator/skills/00-async-dev/SKILL.md @@ -1,6 +1,7 @@ --- name: 00-async-dev description: Single entry point for the async-dev pipeline (setup, run, review). Hybrid router decides which sub-flow to execute from $ARGUMENTS keyword (`setup` / `run` / `review`), trigger source (label `to-implement` / `to-review`, comment `@claude /implement` / `/review`), repo state (workflow + config presence, PR linked to issue), or natural-language intent. Use when the user says "set up async dev", "run async dev on issue #N", "address review on PR #N", "/async-dev", "claude on issues", or when triggered by a webhook with the matching labels or comments. Do NOT use for plain status checks on the async pipeline or for SDLC orchestration unrelated to issue/PR automation. +argument-hint: collect-comments | detect-stop | fix-iteration | finalize | poll-ready | resolve-deps | acquire-lock | check-sdlc | delegate-sdlc | write-audit | detect-context | ask-config | generate-workflow | generate-local-script | write-config | bootstrap-labels | install-user-scope-plugins | configure-remote-secrets | bootstrap-scheduling | commit-and-push | smoke-test --- # Async-dev diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index e2860668..5da05e2f 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -33,22 +33,22 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai #### `skills/02-user-stories-create` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-create-user-stories.md](skills/02-user-stories-create/actions/01-create-user-stories.md) | - | - | -| `assets` | [user-story-template.md](skills/02-user-stories-create/assets/user-story-template.md) | `Template for defining user stories with estimation and acceptance criteria` | - | -| `-` | [README.md](skills/02-user-stories-create/README.md) | - | - | -| `-` | [SKILL.md](skills/02-user-stories-create/SKILL.md) | `Generate INVEST-compliant user stories from a feature description. Use when the user says "user stories", "create user stories", "write user stories for X", "INVEST stories", "draft stories", or invokes `/user-stories-create`. Do NOT use for writing code, drafting a full PRD, refining a single existing story, or copying ready text into a tracker.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-create-user-stories.md](skills/02-user-stories-create/actions/01-create-user-stories.md) | - | +| `assets` | [user-story-template.md](skills/02-user-stories-create/assets/user-story-template.md) | `Template for defining user stories with estimation and acceptance criteria` | +| `-` | [README.md](skills/02-user-stories-create/README.md) | - | +| `-` | [SKILL.md](skills/02-user-stories-create/SKILL.md) | `Generate INVEST-compliant user stories from a feature description. Use when the user says "user stories", "create user stories", "write user stories for X", "INVEST stories", "draft stories", or invokes `/user-stories-create`. Do NOT use for writing code, drafting a full PRD, refining a single existing story, or copying ready text into a tracker.` | #### `skills/03-prd` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-prd.md](skills/03-prd/actions/01-prd.md) | - | - | -| `assets` | [prd-template.md](skills/03-prd/assets/prd-template.md) | `Product Requirements Document template (15 sections)` | - | -| `assets` | [task-template.md](skills/03-prd/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | - | -| `-` | [README.md](skills/03-prd/README.md) | - | - | -| `-` | [SKILL.md](skills/03-prd/SKILL.md) | `Generate a structured Product Requirements Document from a feature description or user stories, validated with the user before save. Use when the user says "prd", "draft prd", "write prd", "product requirements for X", "generate a prd", or invokes `/prd`. Do NOT use for writing user stories, drafting a technical implementation plan, or writing source code.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-prd.md](skills/03-prd/actions/01-prd.md) | - | +| `assets` | [prd-template.md](skills/03-prd/assets/prd-template.md) | `Product Requirements Document template (15 sections)` | +| `assets` | [task-template.md](skills/03-prd/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | +| `-` | [README.md](skills/03-prd/README.md) | - | +| `-` | [SKILL.md](skills/03-prd/SKILL.md) | `Generate a structured Product Requirements Document from a feature description or user stories, validated with the user before save. Use when the user says "prd", "draft prd", "write prd", "product requirements for X", "generate a prd", or invokes `/prd`. Do NOT use for writing user stories, drafting a technical implementation plan, or writing source code.` | #### `skills/04-spec` diff --git a/plugins/aidd-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md index b72ce125..a356c7b3 100644 --- a/plugins/aidd-pm/skills/04-spec/SKILL.md +++ b/plugins/aidd-pm/skills/04-spec/SKILL.md @@ -1,6 +1,7 @@ --- name: 04-spec description: Generate or refine a project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec. +argument-hint: build | refine --- # Spec diff --git a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md index d7d77ef6..934c426a 100644 --- a/plugins/aidd-refine/skills/01-brainstorm/SKILL.md +++ b/plugins/aidd-refine/skills/01-brainstorm/SKILL.md @@ -1,6 +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 --- # Brainstorm diff --git a/plugins/aidd-refine/skills/03-condense/SKILL.md b/plugins/aidd-refine/skills/03-condense/SKILL.md index 67533545..70173e0e 100644 --- a/plugins/aidd-refine/skills/03-condense/SKILL.md +++ b/plugins/aidd-refine/skills/03-condense/SKILL.md @@ -1,6 +1,7 @@ --- name: 03-condense description: Toggle terse output mode with intensity levels (lite, full, ultra) so prose drops articles, filler, and pleasantries while code, quoted errors, and security warnings stay verbatim. Also reports real token usage and estimated savings under condense mode for the current session. Use when the user says "condense", "condense output", "be more concise", "shorter answers", "tighten output", "/condense", "/condense full", "/condense ultra", "stop condense", "normal mode", "/condense-stats", "how much have we saved", or "token savings". Do NOT use for editing existing prose, summarizing a long document, or compressing source code (only output style is affected, not content). +argument-hint: condense | stats --- # Condense diff --git a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md index 3df59f34..a6c7fdf4 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md @@ -1,6 +1,7 @@ --- name: 04-shadow-areas description: Analytical scan of a markdown artifact (idea, user-stories, PRD, spec) to surface blind spots - unstated assumption, missing actor, missing failure mode, ambiguous term, missing acceptance criterion, missing edge case, and missing dependency - emitting a structured shadow report grouped by category and sorted by severity. Use when the user says "find blind spots in this spec", "what's missing in this PRD", "shadow report", "shadow analysis", "scan for gaps", "find what's missing", "spot blind spots", "review for gaps", or asks for an analytical gap scan of a written artifact. Do NOT use for interactive clarification through iterative Q&A (use aidd-refine:01-brainstorm for that), implementing features, writing tests, or reviewing code style. +argument-hint: detect | render-report | diff --- # Shadow Areas diff --git a/plugins/aidd-refine/skills/05-fact-check/SKILL.md b/plugins/aidd-refine/skills/05-fact-check/SKILL.md index af670ba6..b09fae28 100644 --- a/plugins/aidd-refine/skills/05-fact-check/SKILL.md +++ b/plugins/aidd-refine/skills/05-fact-check/SKILL.md @@ -1,6 +1,7 @@ --- name: 05-fact-check description: Verify factual claims in a piece of text against authoritative sources and rewrite it with footnote citations, hedging any claim that cannot be confirmed. Runs a cheapest-first verification cascade (project memory and docs, then codebase inspection, then web lookup) and reports both sources when they disagree. Use when the user says "fact-check this", "verify that claim", "are you sure about that", "is that actually true", "cite your sources", "where did you get that fact", "did you make that up", "double-check the version you gave me", "vérifie cette information", or "es-tu sûr de ça". Do NOT use to auto-guard the AI's own output (this skill only fires on an explicit request), to judge code logic correctness, or to clarify vague requirements through iterative Q&A - use `aidd-refine:01-brainstorm` for that. +argument-hint: identify-claims | verify | report --- # Fact-check diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 4cc8de8d..9f9bf6c2 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -25,41 +25,41 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai #### `skills/01-commit` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-commit.md](skills/01-commit/actions/01-commit.md) | - | - | -| `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | - | -| `-` | [README.md](skills/01-commit/README.md) | - | - | -| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-commit.md](skills/01-commit/actions/01-commit.md) | - | +| `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | +| `-` | [README.md](skills/01-commit/README.md) | - | +| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging.` | #### `skills/02-pull-request` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-pull-request.md](skills/02-pull-request/actions/01-pull-request.md) | - | - | -| `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` | - | -| `assets` | [CONTRIBUTING.md](skills/02-pull-request/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | - | -| `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | - | -| `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | - | -| `-` | [README.md](skills/02-pull-request/README.md) | - | - | -| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-pull-request.md](skills/02-pull-request/actions/01-pull-request.md) | - | +| `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` | +| `assets` | [CONTRIBUTING.md](skills/02-pull-request/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | +| `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | +| `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | +| `-` | [README.md](skills/02-pull-request/README.md) | - | +| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits.` | #### `skills/03-release-tag` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-release-tag.md](skills/03-release-tag/actions/01-release-tag.md) | - | - | -| `assets` | [release-template.md](skills/03-release-tag/assets/release-template.md) | `VCS release notes template` | - | -| `-` | [README.md](skills/03-release-tag/README.md) | - | - | -| `-` | [SKILL.md](skills/03-release-tag/SKILL.md) | `Cut a semver release with annotated tag and release notes. Use when the user says "release", "tag", "tag this release", "bump version", "release v1.2.0", "cut a release", or invokes `/release-tag`. Do NOT use for plain commits without a tag, opening pull requests, pushing a branch only, or amending existing tags.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-release-tag.md](skills/03-release-tag/actions/01-release-tag.md) | - | +| `assets` | [release-template.md](skills/03-release-tag/assets/release-template.md) | `VCS release notes template` | +| `-` | [README.md](skills/03-release-tag/README.md) | - | +| `-` | [SKILL.md](skills/03-release-tag/SKILL.md) | `Cut a semver release with annotated tag and release notes. Use when the user says "release", "tag", "tag this release", "bump version", "release v1.2.0", "cut a release", or invokes `/release-tag`. Do NOT use for plain commits without a tag, opening pull requests, pushing a branch only, or amending existing tags.` | #### `skills/04-issue-create` -| Group | File | Description | Argument Hint | -|-------|------|---|---| -| `actions` | [01-issue-create.md](skills/04-issue-create/actions/01-issue-create.md) | - | - | -| `assets` | [CONTRIBUTING.md](skills/04-issue-create/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | - | -| `assets` | [issue-template.md](skills/04-issue-create/assets/issue-template.md) | `VCS issue/ticket template` | - | -| `-` | [README.md](skills/04-issue-create/README.md) | - | - | -| `-` | [SKILL.md](skills/04-issue-create/SKILL.md) | `Create an issue in the configured ticketing tool. Use when the user says "new issue", "create an issue", "file a bug", "file an issue", "report bug", "open an issue", or invokes `/issue-create`. Do NOT use for committing changes, opening pull requests, tagging releases, or commenting on existing issues.` | - | +| Group | File | Description | +|-------|------|---| +| `actions` | [01-issue-create.md](skills/04-issue-create/actions/01-issue-create.md) | - | +| `assets` | [CONTRIBUTING.md](skills/04-issue-create/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | +| `assets` | [issue-template.md](skills/04-issue-create/assets/issue-template.md) | `VCS issue/ticket template` | +| `-` | [README.md](skills/04-issue-create/README.md) | - | +| `-` | [SKILL.md](skills/04-issue-create/SKILL.md) | `Create an issue in the configured ticketing tool. Use when the user says "new issue", "create an issue", "file a bug", "file an issue", "report bug", "open an issue", or invokes `/issue-create`. Do NOT use for committing changes, opening pull requests, tagging releases, or commenting on existing issues.` | diff --git a/scripts/summarize-markdown.js b/scripts/summarize-markdown.js index e3aa25c9..a589e12b 100755 --- a/scripts/summarize-markdown.js +++ b/scripts/summarize-markdown.js @@ -69,6 +69,8 @@ for (const arg of process.argv) { const fs = require("node:fs"); const path = require("node:path"); +const NON_TABLE_FRONTMATTER_KEYS = new Set(["argument-hint"]); + function parseFrontmatter(content) { const lines = content.split("\n"); @@ -242,6 +244,11 @@ function truncateText(text, maxLength = 50) { return `${text.substring(0, maxLength - 3)}...`; } +function formatFrontmatterValue(value) { + if (!value || value === "N/A") return "-"; + return `\`${value}\``; +} + /** * Group files by their first path component (subfolder) * @param {Array} files - Array of file objects @@ -326,7 +333,7 @@ function generateTable(files, outputFile) { } parsedFiles.push({ file, frontmatter }); for (const key of Object.keys(frontmatter)) { - if (key !== "name") allKeys.add(key); + if (key !== "name" && !NON_TABLE_FRONTMATTER_KEYS.has(key)) allKeys.add(key); } } catch (error) { console.warn( @@ -354,7 +361,7 @@ function generateTable(files, outputFile) { const fileLink = `[${template}](${relativePath})`; const values = extraColumns.map((key) => { const val = frontmatter[key]; - return val && val !== "N/A" ? `\`${val}\`` : "-"; + return formatFrontmatterValue(val); }); rows.push({ group, fileLink, values }); } diff --git a/scripts/sync-skill-argument-hints.mjs b/scripts/sync-skill-argument-hints.mjs new file mode 100755 index 00000000..d4b31bf6 --- /dev/null +++ b/scripts/sync-skill-argument-hints.mjs @@ -0,0 +1,119 @@ +#!/usr/bin/env node +// Keeps SKILL.md frontmatter argument-hint values in sync with action file names. +// Omits the field when a skill has zero or one action. +// Usage: +// node scripts/sync-skill-argument-hints.mjs # rewrite stale files +// node scripts/sync-skill-argument-hints.mjs --check # exit 1 if stale + +import { readdir, readFile, writeFile } from "node:fs/promises"; +import path from "node:path"; + +const ROOT = process.cwd(); +const PLUGINS_DIR = path.join(ROOT, "plugins"); +const CHECK = process.argv.includes("--check"); + +function actionName(file) { + return path.basename(file, path.extname(file)).replace(/^\d+-/, ""); +} + +async function existsDir(dir) { + try { + const entries = await readdir(dir, { withFileTypes: true }); + return entries; + } catch (error) { + if (error.code === "ENOENT") return null; + throw error; + } +} + +async function collectMarkdownFiles(dir) { + const entries = await existsDir(dir); + if (!entries) return []; + + const files = []; + for (const entry of entries) { + const full = path.join(dir, entry.name); + if (entry.isDirectory()) { + files.push(...(await collectMarkdownFiles(full))); + } else if (entry.isFile() && entry.name.endsWith(".md")) { + files.push(full); + } + } + return files.sort((a, b) => a.localeCompare(b)); +} + +async function skillDirs() { + const plugins = await existsDir(PLUGINS_DIR); + if (!plugins) return []; + + const dirs = []; + for (const plugin of plugins) { + if (!plugin.isDirectory()) continue; + const skillsDir = path.join(PLUGINS_DIR, plugin.name, "skills"); + const skills = await existsDir(skillsDir); + if (!skills) continue; + for (const skill of skills) { + if (skill.isDirectory()) dirs.push(path.join(skillsDir, skill.name)); + } + } + return dirs.sort((a, b) => a.localeCompare(b)); +} + +function splitFrontmatter(content) { + if (!content.startsWith("---\n")) return null; + const end = content.indexOf("\n---", 4); + if (end === -1) return null; + return { + frontmatter: content.slice(4, end), + body: content.slice(end), + }; +} + +function syncArgumentHint(content, hint) { + const parts = splitFrontmatter(content); + if (!parts) return content; + + const lines = parts.frontmatter.split("\n"); + const index = lines.findIndex((value) => value.startsWith("argument-hint:")); + if (!hint) { + if (index !== -1) lines.splice(index, 1); + return `---\n${lines.join("\n")}${parts.body}`; + } + + const line = `argument-hint: ${hint}`; + if (index === -1) { + const descriptionIndex = lines.findIndex((value) => value.startsWith("description:")); + const insertAt = descriptionIndex === -1 ? lines.length : descriptionIndex + 1; + lines.splice(insertAt, 0, line); + } else { + lines[index] = line; + } + + return `---\n${lines.join("\n")}${parts.body}`; +} + +const stale = []; +for (const dir of await skillDirs()) { + const skillPath = path.join(dir, "SKILL.md"); + const actionFiles = await collectMarkdownFiles(path.join(dir, "actions")); + const names = [...new Set(actionFiles.map(actionName))]; + const hint = names.length > 1 ? names.join(" | ") : null; + const before = await readFile(skillPath, "utf8"); + const after = syncArgumentHint(before, hint); + if (after !== before) { + const relative = path.relative(ROOT, skillPath); + stale.push(relative); + if (!CHECK) await writeFile(skillPath, after); + } +} + +if (stale.length > 0) { + if (CHECK) { + console.error(`Stale argument-hint frontmatter:\n${stale.join("\n")}`); + console.error("Run: node scripts/sync-skill-argument-hints.mjs"); + process.exit(1); + } + console.log(`Synced argument-hint frontmatter in ${stale.length} SKILL.md file(s).`); +} else { + console.log("All skill argument-hint frontmatter values are current."); +} From d4e5c29fc60cbbde91ba8f89bb41a5f3ce02ec19 Mon Sep 17 00:00:00 2001 From: Alex <8973343+alexsoyes@users.noreply.github.com> Date: Fri, 19 Jun 2026 16:50:07 +0200 Subject: [PATCH 02/14] refactor(aidd-dev): redesign 01-plan into gather/explore/wireframe/plan (#271) Four-action plan skill (gather/explore/wireframe/plan), unified feature-folder artifact layout (brainstorm/spec/plan/phases/review), implement reads the new layout with per-plan and per-phase status tracking. Closes #292 Closes #265 Closes #276 --- docs/CATALOG.md | 2 +- plugins/aidd-dev/CATALOG.md | 15 +-- plugins/aidd-dev/README.md | 2 +- plugins/aidd-dev/agents/planner.md | 8 +- plugins/aidd-dev/skills/00-sdlc/README.md | 2 +- plugins/aidd-dev/skills/01-plan/README.md | 49 +++----- plugins/aidd-dev/skills/01-plan/SKILL.md | 49 +++----- .../skills/01-plan/actions/01-gather.md | 21 ++++ .../skills/01-plan/actions/01-plan.md | 72 ----------- .../01-plan/actions/02-components-behavior.md | 35 ------ .../skills/01-plan/actions/02-explore.md | 23 ++++ .../actions/03-image-extract-details.md | 79 ------------ .../skills/01-plan/actions/03-wireframe.md | 20 ++++ .../skills/01-plan/actions/04-plan.md | 24 ++++ .../01-plan/assets/master-plan-template.md | 45 ------- .../skills/01-plan/assets/phase-template.md | 43 +++++++ .../skills/01-plan/assets/plan-template.md | 112 +++--------------- .../01-plan/assets/tech-choice-template.md | 61 ---------- .../references/wireframe-conventions.md | 28 +++++ .../02-implement/actions/01-implement.md | 22 ++-- .../05-review/actions/01-review-code.md | 4 +- .../05-review/actions/02-review-functional.md | 4 +- .../skills/04-spec/actions/01-build.md | 4 +- .../skills/01-brainstorm/README.md | 2 +- .../aidd-refine/skills/01-brainstorm/SKILL.md | 2 +- .../01-brainstorm/actions/04-finalize.md | 10 +- 26 files changed, 256 insertions(+), 482 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-components-behavior.md create mode 100644 plugins/aidd-dev/skills/01-plan/actions/02-explore.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/actions/03-wireframe.md create mode 100644 plugins/aidd-dev/skills/01-plan/actions/04-plan.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/assets/tech-choice-template.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 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. From dc14a73072903a8a14b9b44957ba9dfa57e31ad7 Mon Sep 17 00:00:00 2001 From: Alex <8973343+alexsoyes@users.noreply.github.com> Date: Sat, 20 Jun 2026 12:55:45 +0200 Subject: [PATCH 03/14] docs(framework): add dominance checks to review and rules (#313) * docs(framework): add dominance checks to review and rules Dominance issues were easy for agents to miss when a weaker rule, criterion, or documentation statement was already covered, overridden, or invalidated by a stronger element. This adds the check at the global context, rule-generation, reviewer, and review-template levels. * docs(framework): reduce dominance check duplication Keep the concise dominance rule in global and rule-authoring surfaces while leaving the detailed case breakdown to the reviewer. Validation now states the shared check without reimplementing reviewer classification. * docs(framework): separate global and rule dominance checks Keep the general dominance reminder and reviewer taxonomy separate from rule-generation specifics. Rule authoring and validation now only check for duplicate, weaker, or contradictory rule bullets. * docs(framework): prefer intention-revealing names Naming guidance belongs in the global project context because it applies across artifacts. This keeps the rule concise and avoids duplicating it in domain-specific rule generation flows. * docs(aidd-context): validate rules against shared contracts Rule validation should apply the rule-authoring and tool-path contracts instead of restating individual rule checks. The test now has a single outcome sentence rather than multiple bullet assertions. * docs(aidd-dev): align dominance wording with review role The reviewer should report parallel elements rather than describe adding behavior. This keeps the dominance check phrased for read-only review while preserving the same taxonomy. --- CLAUDE.md | 2 ++ .../skills/02-project-memory/assets/AGENTS.md | 2 ++ .../skills/05-rule-generate/actions/03-validate.md | 7 ++++--- .../skills/05-rule-generate/references/rule-authoring.md | 1 + plugins/aidd-dev/agents/reviewer.md | 8 ++++++++ 5 files changed, 17 insertions(+), 3 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index bf7514c5..386af27b 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,6 +18,8 @@ All instructions and information above are willing to be up to date, but always - Do not commit or push yourself unless I ask you to. - For every plugin change, think hard about where responsibility belongs; follow the placement and orchestration rules in `docs/ARCHITECTURE.md`. - Never duplicate across docs - link to the canonical home. +- Before adding any instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, do not add a parallel element: delete it, merge it into the stronger element, or rewrite the set with explicit scope, priority, and exception. +- When naming anything, prefer intention-revealing names over technical ones: describe the goal or responsibility, not the mechanism, tool, or file format. ### Answering Guidelines diff --git a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md index da9aad46..20b5e034 100644 --- a/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md +++ b/plugins/aidd-context/skills/02-project-memory/assets/AGENTS.md @@ -21,6 +21,8 @@ - Do not commit or push unless the user asks. - Do not assume your knowledge is current. Be sure of an answer before giving it. +- Before adding any instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, do not add a parallel element: delete it, merge it into the stronger element, or rewrite the set with explicit scope, priority, and exception. +- When naming anything, prefer intention-revealing names over technical ones: describe the goal or responsibility, not the mechanism, tool, or file format. ## Memory Management diff --git a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md index 26427308..7e4f3495 100644 --- a/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md +++ b/plugins/aidd-context/skills/05-rule-generate/actions/03-validate.md @@ -13,9 +13,10 @@ A short pass or fail line per rule file. ## Process 1. **Exists.** Confirm each file is on disk at its expected path. -2. **Frontmatter.** Confirm each carries its tool's scope frontmatter matching the rule's reach, per `@../references/tool-paths.md`. An all-files rule may carry no scope field. -3. **Concise.** Confirm the body is terse and on one topic. Flag a crowded file to split. +2. **Contract.** Validate the file against `@../references/rule-authoring.md`. +3. **Target.** Validate target path and frontmatter against `@../references/tool-paths.md`. +4. **Report.** Emit one pass/fail line per file. ## Test -- Every written rule file exists. Its scope frontmatter matches its reach, or is absent for an all-files rule. +Every written rule file has one pass/fail result against both referenced contracts. diff --git a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md index 9867cadf..5d40573b 100644 --- a/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md +++ b/plugins/aidd-context/skills/05-rule-generate/references/rule-authoring.md @@ -8,6 +8,7 @@ The contract every generated rule must satisfy. A rule governs editor and agent - **R2.** Bullets only, no prose. One ultra-short rule per bullet (3-7 words). Less is more. - **R3.** Scope every rule to the files it applies to, or mark it as applying to all. - **R4.** English only, regardless of conversation language. +- **R5.** Do not add a rule bullet that repeats, weakens, or contradicts another active bullet in the same rule. ## File naming diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md index 6724f012..6abcc8ea 100644 --- a/plugins/aidd-dev/agents/reviewer.md +++ b/plugins/aidd-dev/agents/reviewer.md @@ -59,6 +59,14 @@ Your output is complete when: - Start fresh. Don't try to reconstruct how the artifact was produced. Read the artifact, not the production history. - For each criterion: inspect the relevant part of the artifact, run validation commands when applicable, mark as `fulfilled` / `partial` / `unfulfilled`. - Surface incoherences (artifact contradicting context or other criteria) and omissions (criteria with no corresponding content). +- When reviewing any added instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, report the parallel element and suggest deleting it, merging it into the stronger element, or rewriting the set with explicit scope, priority, and exception. + +| Case | What to detect | Example | Action | +| --- | --- | --- | --- | +| Subsumption | A stronger element already implies a weaker one. | "All fixtures must be TypeScript" plus "Do not add legacy fixture formats." | Delete the weaker element, or convert it into an example under the stronger one. | +| Override | A specific element changes a general one. | "All docs are English" plus "Onboarding examples may stay French." | Rewrite with explicit scope, priority, and exception. | +| Invalidation | One element makes another obsolete, impossible, or false. | A doc explains an active command that another doc says was removed. | Remove the invalid element, or mark it historical with a current replacement. | + - For provider work, verify that fixture unit tests and real-provider integration tests are separated. Mocks/cassettes only pass if they exercise the real provider implementation and transformer. - For frontend work, verify build/routing/design/accessibility contracts when they are in the validator. Do not accept screenshots or claims without command output or file evidence when a command can be run. - Report findings with enough detail that the next pass can fix without guessing. From 9fdfa452dfe1239223c53568667c42a075451282 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Mon, 22 Jun 2026 06:27:50 +0200 Subject: [PATCH 04/14] ci(framework): trigger Validate on next branch (#317) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Required check "lefthook (framework-local checks)" (next.json ruleset) is published only by validate.yml, whose pull_request/push filter was [main]. PRs targeting next never fired it, so the required status stayed "Expected — Waiting for status" forever, deadlocking merges (e.g. #307). Add next to both push and pull_request branch filters. Co-authored-by: Claude Opus 4.8 (1M context) --- .github/workflows/validate.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index b3ae480a..65c27879 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -6,9 +6,9 @@ name: Validate on: push: - branches: [main] + branches: [main, next] pull_request: - branches: [main] + branches: [main, next] permissions: contents: read From 4918fa483306527513295d290455f8ad03df0ee9 Mon Sep 17 00:00:00 2001 From: Alex <8973343+alexsoyes@users.noreply.github.com> Date: Mon, 22 Jun 2026 07:20:44 +0200 Subject: [PATCH 05/14] feat(framework): add markdown link checker (#307) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat(framework): add markdown link checker * fix(scripts): exempt template scaffold placeholder links 01-plan's plan-template.md / phase-template.md link to ./plan.md and ./phase-N.md — files the skill emits next to the generated output at runtime (see actions/04-plan.md), never committed to the repo. The checker flagged them as broken. Extend the existing asset-template branch: a dot-relative target in a *-template.md that resolves nowhere is an intentional placeholder for a generated sibling, so treat it as ignored rather than broken. The assets/templates fallback (used by 02-project-memory) is unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) --------- Co-authored-by: Baptiste LAFOURCADE Co-authored-by: Claude Opus 4.8 (1M context) --- CONTRIBUTING.md | 10 + lefthook.yml | 8 + .../__tests__/check-markdown-links.test.js | 200 ++++++++ scripts/check-markdown-links.js | 466 ++++++++++++++++++ 4 files changed, 684 insertions(+) create mode 100644 scripts/__tests__/check-markdown-links.test.js create mode 100644 scripts/check-markdown-links.js diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1fb74f33..8d9de6e9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -43,6 +43,16 @@ make setup `make` lists every target; `make doctor` / `make check` verify the environment and run the pre-commit checks. +### Markdown links + +Lefthook runs the Markdown link checker during pre-commit. `make setup` installs the hooks; if dependencies are already installed and you only need the hook wiring, run: + +```bash +pnpm exec lefthook install --force +``` + +Run `node scripts/check-markdown-links.js` to scan the repository. Detailed usage, supported forms, exclusions, and fix guidance live in `node scripts/check-markdown-links.js --help`. + ### Test your changes locally Exercise the skills you touched before opening a PR. Neither tool hot-reloads the checkout (both serve a copied cache), so after editing: diff --git a/lefthook.yml b/lefthook.yml index f51e108f..90364fe5 100644 --- a/lefthook.yml +++ b/lefthook.yml @@ -42,6 +42,14 @@ pre-commit: fi node scripts/sync-skill-argument-hints.mjs >/dev/null git add plugins/*/skills/*/SKILL.md 2>/dev/null || true + markdown-links: + glob: "**/*.md" + run: | + if ! command -v node >/dev/null 2>&1; then + echo "ℹ️ node not available; skipping markdown-links" + exit 0 + fi + node scripts/check-markdown-links.js summarize-plugin-catalogs: run: | [ -d plugins ] || exit 0 diff --git a/scripts/__tests__/check-markdown-links.test.js b/scripts/__tests__/check-markdown-links.test.js new file mode 100644 index 00000000..4ccaeb28 --- /dev/null +++ b/scripts/__tests__/check-markdown-links.test.js @@ -0,0 +1,200 @@ +const assert = require("node:assert/strict"); +const { spawnSync } = require("node:child_process"); +const fs = require("node:fs"); +const path = require("node:path"); +const test = require("node:test"); + +const { + formatIssue, + reportProblems, +} = require("../check-markdown-links.js"); + +const root = path.resolve(__dirname, "../.."); +const script = path.join(root, "scripts/check-markdown-links.js"); + +test("formatIssue includes correction details", () => { + assert.equal( + formatIssue({ + raw: "./courses/intro.md", + reason: "cross-repo-relative-link", + suggestion: "https://github.com/ai-driven-dev/framework/blob/main/courses/intro.md", + }), + "./courses/intro.md (cross-repo relative link; suggestion: https://github.com/ai-driven-dev/framework/blob/main/courses/intro.md)", + ); +}); + +test("reportProblems writes a markdown source issue table", () => { + const lines = []; + const originalConsoleError = console.error; + console.error = (line = "") => lines.push(line); + + try { + reportProblems( + [ + { + file: path.join(root, "CLAUDE.md"), + line: 34, + raw: "@aidd_docs/memory/architecture.md", + reason: "local-path-not-found", + }, + ], + 339, + ); + } finally { + console.error = originalConsoleError; + } + + assert.deepEqual(lines, [ + "| source | issue |", + "| - | - |", + "| CLAUDE.md:34 | @aidd_docs/memory/architecture.md (local path not found) |", + "", + "❌ Links: 1 broken in 339 files", + ]); +}); + +test("reportProblems writes a success summary when there are no problems", () => { + const lines = []; + + const status = reportProblems([], 42, () => { + throw new Error("unexpected error logger call"); + }, (line) => lines.push(line)); + + assert.equal(status, 0); + assert.deepEqual(lines, ["✅ Links: 0 broken in 42 files"]); +}); + +test("--help documents supported links, exclusions, fixes, and examples", () => { + const result = spawnSync(process.execPath, [script, "--help"], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stdout, /node scripts\/check-markdown-links\.js \[--ignore path\]/u); + assert.match(result.stdout, /Markdown links and images/u); + assert.match(result.stdout, /@path/u); + assert.match(result.stdout, /src: path/u); + assert.match(result.stdout, /Anchor-only links/u); + assert.match(result.stdout, /mailto:/u); + assert.match(result.stdout, /tel:/u); + assert.match(result.stdout, /HTML angle-bracket/u); + assert.match(result.stdout, /\.git and node_modules/u); + assert.match(result.stdout, /Runtime variables, glob patterns, and bare words/u); + assert.match(result.stdout, /\| Need \| Use \|/u); + assert.match(result.stdout, /\| Include\/import a file in agent context \| @path\/to\/file\.md \|/u); + assert.match(result.stdout, /\| Reference a file for the reader \| \[label\]\(path\/to\/file\.md\) \|/u); + assert.match(result.stdout, /\| Case \| Example \|/u); + assert.match(result.stdout, /@plugins\/aidd-context\/skills\/11-explore\/SKILL\.md/u); + assert.match(result.stdout, /\[explore skill\]\(plugins\/aidd-context\/skills\/11-explore\/SKILL\.md\)/u); +}); + +test("CLI checks one markdown file covering supported, ignored, and broken forms", () => { + const tempDir = fs.mkdtempSync(path.join(root, "scripts/__tests__/.tmp-check-markdown-links-")); + const fixture = path.join(tempDir, "all-cases.md"); + const readmePath = path.relative(tempDir, path.join(root, "README.md")); + const logoPath = path.relative(tempDir, path.join(root, "docs/assets/logo.png")); + const claudePath = path.relative(tempDir, path.join(root, "CLAUDE.md")); + const contributingPath = path.relative(tempDir, path.join(root, "CONTRIBUTING.md")); + const outsidePath = path.relative(tempDir, path.resolve(root, "..", "outside.md")); + const outsideSuggestion = "https://github.com/ai-driven-dev/framework/blob/main/outside.md"; + + fs.writeFileSync( + fixture, + [ + "# Link checker fixture", + "", + "## Supported existing forms", + `See [README](${readmePath}).`, + `![Logo](${logoPath})`, + `@${claudePath}`, + `src: ${contributingPath}`, + "", + "## Ignored forms", + "[Anchor only](#local-heading)", + "[Mail](mailto:security@example.com)", + "[Phone](tel:+33123456789)", + "", + `Logo`, + "src: $ARGUMENTS", + "src: plugins/*/README.md", + "src: README", + "[External URL](https://example.com/not-checked.md)", + "", + "## Broken forms", + "[Missing markdown](./missing.md)", + "@./missing-agent.md", + "src: ./missing-source.md", + `[Cross repo](${outsidePath})`, + "", + ].join("\n"), + "utf8", + ); + + try { + const result = spawnSync(process.execPath, [script, fixture], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 1); + assert.equal(result.stdout, ""); + assert.match(result.stderr, /\| source \| issue \|/u); + assert.match(result.stderr, /\| - \| - \|/u); + assert.match(result.stderr, /missing\.md \(local path not found\)/u); + assert.match(result.stderr, /@\.\/missing-agent\.md \(local path not found\)/u); + assert.match(result.stderr, /\.\/missing-source\.md \(local path not found\)/u); + assert.ok( + result.stderr.includes(`${outsidePath} (cross-repo relative link; suggestion: ${outsideSuggestion})`), + result.stderr, + ); + assert.match(result.stderr, /❌ Links: 4 broken in 1 files/u); + + assert.doesNotMatch(result.stderr, /local-heading/u); + assert.doesNotMatch(result.stderr, /mailto:security@example\.com/u); + assert.doesNotMatch(result.stderr, /tel:\+33123456789/u); + assert.doesNotMatch(result.stderr, /(?:^|\s)https?:\/\/example\.com\/not-checked(?:\s|$)/u); + assert.doesNotMatch(result.stderr, /\$ARGUMENTS/u); + assert.doesNotMatch(result.stderr, /plugins\/\*\/README\.md/u); + } finally { + fs.rmSync(tempDir, { recursive: true, force: true }); + } +}); + +test("CLI without paths scans the repository and prints a summary", () => { + const result = spawnSync(process.execPath, [script], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stdout, /✅ Links: 0 broken in \d+ files/u); +}); + +test("CLI fails when an explicit input path does not exist", () => { + const result = spawnSync(process.execPath, [script, "DOES_NOT_EXIST.md"], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 1); + assert.match(result.stderr, /❌ Path not found: DOES_NOT_EXIST\.md/u); +}); + +test("repository scan ignores interrupted test temp directories", () => { + const tempDir = fs.mkdtempSync(path.join(root, "scripts/__tests__/.tmp-check-markdown-links-")); + + try { + fs.writeFileSync(path.join(tempDir, "leftover.md"), "[Missing](./missing.md)\n", "utf8"); + + const result = spawnSync(process.execPath, [script], { + cwd: root, + encoding: "utf8", + }); + + assert.equal(result.status, 0); + assert.match(result.stdout, /✅ Links: 0 broken in \d+ files/u); + } finally { + fs.rmSync(tempDir, { recursive: true, force: true }); + } +}); diff --git a/scripts/check-markdown-links.js b/scripts/check-markdown-links.js new file mode 100644 index 00000000..783ffcec --- /dev/null +++ b/scripts/check-markdown-links.js @@ -0,0 +1,466 @@ +#!/usr/bin/env node + +const fs = require("node:fs"); +const path = require("node:path"); + +const ROOT = path.resolve(__dirname, ".."); + +const HELP_TEXT = `Usage: + node scripts/check-markdown-links.js [--ignore path] + +Supported link forms: + - Markdown links and images: [label](path), ![alt](path) + - Agent context includes/imports: @path/to/file.md + - Source declarations: src: path/to/file.md + +Ignored / excluded forms: + - Anchor-only links such as #usage + - mailto: and tel: links + - HTML angle-bracket links and HTML attributes + - .git and node_modules directories + - Runtime variables, glob patterns, and bare words + +How to fix broken links: + | Need | Use | + | - | - | + | Include/import a file in agent context | @path/to/file.md | + | Reference a file for the reader | [label](path/to/file.md) | + +Examples: + | Case | Example | + | - | - | + | Agent include/import | @plugins/aidd-context/skills/11-explore/SKILL.md | + | Reader reference | See [explore skill](plugins/aidd-context/skills/11-explore/SKILL.md). | +`; + +const SKIPPED_DIRS = new Set([".git", "node_modules"]); +const SKIPPED_DIR_PREFIXES = [".tmp-check-markdown-links-"]; +const MARKDOWN_EXTENSIONS = new Set([".md", ".mdx"]); +function normalizePathForDisplay(filePath) { + const relative = path.relative(ROOT, filePath).replaceAll(path.sep, "/"); + return relative || "."; +} + +function normalizeForMatch(filePath) { + return path.resolve(ROOT, filePath); +} + +function pathStartsWith(candidate, parent) { + const relative = path.relative(parent, candidate); + return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); +} + +function parseArgs(argv) { + const paths = []; + const ignores = []; + + for (let index = 0; index < argv.length; index += 1) { + const arg = argv[index]; + + if (arg === "--help" || arg === "-h") { + return { help: true, paths, ignores }; + } + + if (arg === "--ignore") { + const ignoredPath = argv[index + 1]; + if (!ignoredPath || ignoredPath.startsWith("--")) { + throw new Error("--ignore requires a path"); + } + ignores.push(ignoredPath); + index += 1; + continue; + } + + paths.push(arg); + } + + return { help: false, paths: paths.length > 0 ? paths : ["."], ignores }; +} + +function isIgnored(filePath, ignoredPaths) { + const absolute = path.resolve(filePath); + return ignoredPaths.some((ignoredPath) => pathStartsWith(absolute, ignoredPath)); +} + +function collectMarkdownFiles(inputPaths, ignoredPaths = []) { + const files = []; + const normalizedIgnores = ignoredPaths.map((ignoredPath) => normalizeForMatch(ignoredPath)); + const missingInputs = inputPaths.filter((inputPath) => !fs.existsSync(path.resolve(ROOT, inputPath))); + + if (missingInputs.length > 0) { + throw new Error(`Path not found: ${missingInputs.join(", ")}`); + } + + function visit(currentPath) { + const absolute = path.resolve(ROOT, currentPath); + if (!fs.existsSync(absolute)) { + return; + } + + if (isIgnored(absolute, normalizedIgnores)) { + return; + } + + const stat = fs.statSync(absolute); + if (stat.isDirectory()) { + const basename = path.basename(absolute); + if (SKIPPED_DIRS.has(basename) || SKIPPED_DIR_PREFIXES.some((prefix) => basename.startsWith(prefix))) { + return; + } + + for (const entry of fs.readdirSync(absolute, { withFileTypes: true })) { + visit(path.join(absolute, entry.name)); + } + return; + } + + if (stat.isFile() && MARKDOWN_EXTENSIONS.has(path.extname(absolute).toLowerCase())) { + files.push(absolute); + } + } + + for (const inputPath of inputPaths) { + visit(inputPath); + } + + return files.sort((a, b) => normalizePathForDisplay(a).localeCompare(normalizePathForDisplay(b))); +} + +function gatherMarkdownFiles(inputs, cwd = ROOT) { + return collectMarkdownFiles(inputs.length > 0 ? inputs : ["."], []).map((file) => path.resolve(cwd, path.relative(ROOT, file))); +} + +function filterIgnoredFiles(files, ignore = [], root = ROOT) { + if (ignore.length === 0) { + return files; + } + + const ignoredPaths = ignore.map((ignoredPath) => path.resolve(root, ignoredPath)); + return files.filter((file) => !isIgnored(file, ignoredPaths)); +} + +function lineNumberAt(content, index) { + return content.slice(0, index).split("\n").length; +} + +function stripTrailingPunctuation(target) { + return target.replace(/[.,;:]+$/u, ""); +} + +function splitMarkdownTarget(rawTarget) { + const trimmed = rawTarget.trim(); + if (trimmed.startsWith("<") && trimmed.endsWith(">")) { + return trimmed; + } + return trimmed.split(/\s+/u)[0]; +} + +function extractLinks(content) { + const links = []; + const markdownLinkPattern = /!?\[[^\]\n]*\]\(([^)\n]+)\)/gu; + const atPathPattern = /(^|[\n\r][ \t>*-]*)@([^\s`)\]},;]+)/gu; + const srcPathPattern = /\bsrc:\s*([^\s`)\]},;]+)/gu; + + for (const match of content.matchAll(markdownLinkPattern)) { + links.push({ + raw: splitMarkdownTarget(match[1]), + index: match.index, + kind: "markdown", + }); + } + + for (const match of content.matchAll(atPathPattern)) { + links.push({ + raw: `@${stripTrailingPunctuation(match[2])}`, + index: match.index + match[1].length, + kind: "agent-import", + }); + } + + for (const match of content.matchAll(srcPathPattern)) { + links.push({ + raw: stripTrailingPunctuation(match[1]), + index: match.index, + kind: "src", + }); + } + + return links; +} + +function isIgnoredTarget(target) { + if (!target) { + return true; + } + + if (target.startsWith("<") && target.endsWith(">")) { + return true; + } + + if (/[<>]/u.test(target)) { + return true; + } + + if (target.startsWith("#")) { + return true; + } + + if (/^(mailto|tel):/iu.test(target)) { + return true; + } + + if (/[*?[\]]/u.test(target)) { + return true; + } + + if (/^\$[\w_]+/u.test(target)) { + return true; + } + + if (/\{\{[^}]+\}\}/u.test(target)) { + return true; + } + + if (!target.includes("/") && !target.includes(".") && !target.startsWith("..")) { + return true; + } + + return false; +} + +function stripAnchor(target) { + const hashIndex = target.indexOf("#"); + return hashIndex === -1 ? target : target.slice(0, hashIndex); +} + +function safeDecodeUri(target) { + try { + return decodeURI(target); + } catch { + return target; + } +} + +function isRemoteUrl(target) { + return /^https?:\/\//iu.test(target); +} + +function resolveLocalPath(target, sourceFile) { + const withoutAnchor = stripAnchor(target); + if (!withoutAnchor) { + return { ignored: true }; + } + + const decoded = safeDecodeUri(withoutAnchor); + if (path.isAbsolute(decoded)) { + return { absolute: path.resolve(ROOT, decoded.slice(1)) }; + } + + const absolute = path.resolve(path.dirname(sourceFile), decoded); + const sourceRelative = normalizePathForDisplay(sourceFile); + const assetTemplateMatch = sourceRelative.match(/^(plugins\/[^/]+\/skills\/[^/]+\/assets)\/.+$/u); + if (assetTemplateMatch) { + const generatedTemplateAbsolute = path.resolve(ROOT, assetTemplateMatch[1], "templates", decoded); + if (!fs.existsSync(absolute) && fs.existsSync(generatedTemplateAbsolute)) { + return { absolute: generatedTemplateAbsolute }; + } + // A *-template.md scaffold links to files emitted next to the generated + // output at runtime (e.g. ./plan.md, ./phase-1.md), which never exist in + // the repo. A dot-relative target that resolves nowhere is an intentional + // placeholder for that generated sibling, not a broken link. + if (!fs.existsSync(absolute) && /-template\.md$/u.test(sourceRelative) && /^\.\.?\//u.test(decoded)) { + return { ignored: true }; + } + } + + if (normalizePathForDisplay(sourceFile).startsWith(".github/")) { + const repoRootAbsolute = path.resolve(ROOT, decoded); + if (!fs.existsSync(absolute) && fs.existsSync(repoRootAbsolute)) { + return { absolute: repoRootAbsolute }; + } + } + + return { absolute }; +} + +function problemForTarget(target, sourceFile) { + const validationTarget = target.startsWith("@") ? target.slice(1) : target; + + if (isIgnoredTarget(validationTarget)) { + return null; + } + + if (isRemoteUrl(validationTarget)) { + return null; + } + + const resolved = resolveLocalPath(validationTarget, sourceFile); + if (resolved.ignored) { + return null; + } + + if (!pathStartsWith(resolved.absolute, ROOT)) { + const repoRelative = path.relative(ROOT, resolved.absolute).replaceAll(path.sep, "/"); + return { + raw: target, + reason: "cross-repo-relative-link", + suggestion: `https://github.com/ai-driven-dev/framework/blob/main/${repoRelative.replace(/^(\.\.\/)+/u, "")}`, + }; + } + + if (!fs.existsSync(resolved.absolute)) { + return { raw: target, reason: "local-path-not-found" }; + } + + return null; +} + +function checkFile(filePath) { + const content = fs.readFileSync(filePath, "utf8"); + const links = extractLinks(content); + const problems = []; + + for (const link of links) { + const problem = problemForTarget(link.raw, filePath); + if (!problem) { + continue; + } + + problems.push({ + ...problem, + file: filePath, + line: lineNumberAt(content, link.index), + kind: link.kind, + }); + } + + return problems; +} + +function checkMarkdownLinks(pathsToCheck, ignoredPaths = []) { + const files = collectMarkdownFiles(pathsToCheck, ignoredPaths); + const problems = files.flatMap((file) => checkFile(file)); + return { files, problems }; +} + +function findBrokenLinks(files) { + return files.flatMap((file) => checkFile(file)); +} + +function issueLink(problem) { + return problem.raw ?? problem.link; +} + +function issueReason(problem) { + if (problem.reason) { + return problem.reason; + } + + switch (problem.type) { + case "cross-repo": + return "cross-repo-relative-link"; + case "broken-remote": + return "remote-url-not-found"; + case "broken-template": + return "template-path-not-found"; + default: + return problem.type; + } +} + +function formatIssue(problem) { + const link = issueLink(problem); + + switch (issueReason(problem)) { + case "cross-repo-relative-link": + return `${link} (cross-repo relative link; suggestion: ${problem.suggestion})`; + case "remote-url-not-found": + return `${link} (remote URL not found locally)`; + case "template-path-not-found": + return `${link} (template path not found in framework source)`; + case "local-path-not-found": + return `${link} (local path not found)`; + default: + return `${link} (file not found)`; + } +} + +function escapeMarkdownTableCell(value) { + return String(value).replaceAll("\\", "\\\\").replaceAll("|", "\\|").replaceAll("\n", " "); +} + +function reportProblems(problems, checkedFileCount, logger = console.error, successLogger = console.log) { + if (problems.length === 0) { + successLogger(`✅ Links: 0 broken in ${checkedFileCount} files`); + return 0; + } + + logger("| source | issue |"); + logger("| - | - |"); + + for (const problem of problems) { + const source = `${normalizePathForDisplay(problem.file)}:${problem.line}`; + logger(`| ${escapeMarkdownTableCell(source)} | ${escapeMarkdownTableCell(formatIssue(problem))} |`); + } + + logger(""); + logger(`❌ Links: ${problems.length} broken in ${checkedFileCount} files`); + return 1; +} + +function runCli(argv = process.argv.slice(2)) { + let parsed; + try { + parsed = parseArgs(argv); + } catch (error) { + console.error(error.message); + console.error("Run with --help for usage."); + return 1; + } + + if (parsed.help) { + console.log(HELP_TEXT); + return 0; + } + + try { + const { files, problems } = checkMarkdownLinks(parsed.paths, parsed.ignores); + reportProblems(problems, files.length); + return problems.length === 0 ? 0 : 1; + } catch (error) { + console.error(`❌ ${error.message}`); + return 1; + } +} + +function run(inputs, { ignore = [] } = {}) { + try { + const { files, problems } = checkMarkdownLinks(inputs && inputs.length > 0 ? inputs : ["."], ignore); + reportProblems(problems, files.length); + return problems.length === 0 ? 0 : 1; + } catch (error) { + console.error(`❌ ${error.message}`); + return 1; + } +} + +if (require.main === module) { + process.exitCode = runCli(); +} + +module.exports = { + HELP_TEXT, + checkFile, + checkMarkdownLinks, + collectMarkdownFiles, + extractLinks, + filterIgnoredFiles, + formatIssue, + gatherMarkdownFiles, + findBrokenLinks, + parseArgs, + problemForTarget, + reportProblems, + run, + runCli, +}; From 5dfb9ba631b2fce6a9f07cdf99a3cfb699b3721b Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Mon, 22 Jun 2026 22:08:16 +0200 Subject: [PATCH 06/14] feat(aidd-ui): scaffold alpha plugin (0.1.0-alpha.0) (#319) * feat(aidd-ui): scaffold alpha plugin (0.1.0-alpha.0) Add aidd-ui as a new plugin with a single smoke-test skill (01-hello). Registered in marketplace.json (recommended: false) and release config; alpha status is conveyed by the 0.1.0-alpha.0 version in plugin.json. Lives on a dedicated branch off next, so it is not public until it graduates to main. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(aidd-ui): mark alpha / not-ready across surfaces Add prominent alpha warnings to the plugin README, the homepage plugins table, and the marketplace and plugin descriptions so the not-ready status is unmistakable. Co-Authored-By: Claude Opus 4.8 (1M context) --------- Co-authored-by: Claude Opus 4.8 (1M context) --- .claude-plugin/marketplace.json | 7 +++++ .release-please-manifest.json | 3 +- README.md | 15 ++++++++-- plugins/aidd-ui/.claude-plugin/plugin.json | 12 ++++++++ plugins/aidd-ui/CATALOG.md | 30 +++++++++++++++++++ plugins/aidd-ui/README.md | 28 +++++++++++++++++ plugins/aidd-ui/skills/01-hello/README.md | 29 ++++++++++++++++++ plugins/aidd-ui/skills/01-hello/SKILL.md | 14 +++++++++ .../skills/01-hello/actions/01-greet.md | 15 ++++++++++ release-please-config.json | 10 +++++++ 10 files changed, 160 insertions(+), 3 deletions(-) create mode 100644 plugins/aidd-ui/.claude-plugin/plugin.json create mode 100644 plugins/aidd-ui/CATALOG.md create mode 100644 plugins/aidd-ui/README.md create mode 100644 plugins/aidd-ui/skills/01-hello/README.md create mode 100644 plugins/aidd-ui/skills/01-hello/SKILL.md create mode 100644 plugins/aidd-ui/skills/01-hello/actions/01-greet.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b1e7b1d3..1a6128fb 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -48,6 +48,13 @@ "description": "Meta-cognition: refine input through brainstorming, refine output through challenge and condensed communication mode.", "strict": true, "recommended": true + }, + { + "name": "aidd-ui", + "source": "./plugins/aidd-ui", + "description": "ALPHA, not ready for use. UI and UX concern: design, review, and improve frontend interfaces.", + "strict": true, + "recommended": false } ] } diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 7eef9bd7..fa56eff3 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -5,5 +5,6 @@ "plugins/aidd-vcs": "2.0.0", "plugins/aidd-pm": "2.0.0", "plugins/aidd-orchestrator": "2.0.0", - "plugins/aidd-refine": "2.0.0" + "plugins/aidd-refine": "2.0.0", + "plugins/aidd-ui": "0.1.0-alpha.0" } diff --git a/README.md b/README.md index 7ee5ad88..5f1d5e71 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@

🇫🇷 The first French open-source framework for AI-driven development.

- 6 plugins · 38 skills · 3 agents · MIT + 7 plugins · 39 skills · 3 agents · MIT

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -152,7 +152,7 @@ flowchart TD ## 🧩 Plugins -Six plugins covering the whole SDLC — **install all of them**; they're designed to work together. +Seven plugins covering the whole SDLC — **install all of them**; they're designed to work together. (`aidd-ui` is 🚧 **alpha — not ready for use**, off the curated install path.) @@ -211,6 +211,17 @@ Meta-cognition: brainstorm, challenge, condense, shadow-areas, fact-check. Label an issue, get a PR; re-label, get the review applied. + + + +
+ +### 🎨 [aidd-ui](plugins/aidd-ui/README.md) 🚧 + +`1 skill` · **alpha — not ready** + +UI and UX: design, review, and improve frontend interfaces. ⚠️ Alpha (`0.1.0-alpha.0`), smoke-test only — do not rely on it yet. +
diff --git a/plugins/aidd-ui/.claude-plugin/plugin.json b/plugins/aidd-ui/.claude-plugin/plugin.json new file mode 100644 index 00000000..894d576b --- /dev/null +++ b/plugins/aidd-ui/.claude-plugin/plugin.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", + "name": "aidd-ui", + "version": "0.1.0-alpha.0", + "description": "ALPHA, not ready for use. UI and UX concern for the AI-Driven Development framework. Use when the user wants to design, review, or improve a frontend interface. Do NOT use for backend-only or non-UI tasks.", + "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" }, + "skills": ["./skills/01-hello"], + "keywords": ["ui", "ux", "design", "frontend"], + "repository": "https://github.com/ai-driven-dev/framework", + "homepage": "https://ai-driven.dev", + "license": "MIT" +} diff --git a/plugins/aidd-ui/CATALOG.md b/plugins/aidd-ui/CATALOG.md new file mode 100644 index 00000000..5b18635c --- /dev/null +++ b/plugins/aidd-ui/CATALOG.md @@ -0,0 +1,30 @@ +# aidd-ui catalog + +Auto-generated index of skills, agents, references and assets shipped by the `aidd-ui` plugin. + +> This file is automatically updated by the `scripts/summarize-markdown.js` script. + +## Table of Contents + +- [`.claude-plugin`](#claude-plugin) +- [`skills`](#skills) + - [`skills/01-hello`](#skills01-hello) + +--- + +### `.claude-plugin` + +| File | +|------| +| [plugin.json](.claude-plugin/plugin.json) | + +### `skills` + +#### `skills/01-hello` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-greet.md](skills/01-hello/actions/01-greet.md) | - | +| `-` | [README.md](skills/01-hello/README.md) | - | +| `-` | [SKILL.md](skills/01-hello/SKILL.md) | `Smoke-test skill that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Do NOT use for real UI or UX design work.` | + diff --git a/plugins/aidd-ui/README.md b/plugins/aidd-ui/README.md new file mode 100644 index 00000000..f54d34cd --- /dev/null +++ b/plugins/aidd-ui/README.md @@ -0,0 +1,28 @@ +← [aidd-framework](../../README.md) + +# aidd-ui 🚧 alpha + +UI and UX concern for the AI-Driven Development framework. + +> ⚠️ **ALPHA — NOT READY FOR USE.** `0.1.0-alpha.0`. This plugin ships a single smoke-test skill and no real UI/UX capability yet. Do not install it expecting to use it; it exists only to validate the scaffold. APIs, skills, and naming may change or be removed without notice. + +> Status: alpha (experimental). + +This plugin is in alpha (`0.1.0-alpha.0`). It lives on a dedicated branch off `next` and is registered with `recommended: false`, so it stays off the curated install path until it stabilises and graduates to `main`. While it is not in the published marketplace yet, test it from a local checkout of this branch: + +``` +claude --plugin-dir plugins/aidd-ui # zero-marketplace, session-scoped +# or, persistent: +/plugin marketplace add . # register this checkout as a local marketplace +/plugin install aidd-ui@aidd-framework +``` + +Then run `aidd-ui:01-hello` to confirm it loads. + +One starter skill today; real UI and UX skills land as the concern stabilises. + +## Skills + +| Bracket ID | Skill | Description | +| ---------- | ----- | ----------- | +| [7.1] | [hello](skills/01-hello/README.md) | Smoke-test skill that confirms the plugin loads. | diff --git a/plugins/aidd-ui/skills/01-hello/README.md b/plugins/aidd-ui/skills/01-hello/README.md new file mode 100644 index 00000000..11b4803c --- /dev/null +++ b/plugins/aidd-ui/skills/01-hello/README.md @@ -0,0 +1,29 @@ +← [aidd-ui](../../README.md) + +# hello + +Smoke-test skill for the alpha `aidd-ui` plugin. It greets the caller and confirms the plugin loaded. + +## When to use + +- To verify the alpha `aidd-ui` plugin is installed and reachable after a local install or reload. + +## When NOT to use + +- For real UI or UX design, review, or improvement work. Those skills do not exist yet. + +## How to invoke + +`aidd-ui:01-hello` + +## Outputs + +- A short greeting printed in the chat. + +## Prerequisites + +- The plugin loaded locally (`claude --plugin-dir plugins/aidd-ui`, or installed from the marketplace). + +## Technical details + +See [SKILL.md](SKILL.md). diff --git a/plugins/aidd-ui/skills/01-hello/SKILL.md b/plugins/aidd-ui/skills/01-hello/SKILL.md new file mode 100644 index 00000000..ce72346a --- /dev/null +++ b/plugins/aidd-ui/skills/01-hello/SKILL.md @@ -0,0 +1,14 @@ +--- +name: 01-hello +description: Smoke-test skill that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Do NOT use for real UI or UX design work. +--- + +## Available actions + +| ID | Name | Purpose | +| --- | ----- | --------------------------------------------- | +| 01 | greet | Greet the user and confirm the skill works. | + +## Default flow + +Run action `01-greet` and return its message. diff --git a/plugins/aidd-ui/skills/01-hello/actions/01-greet.md b/plugins/aidd-ui/skills/01-hello/actions/01-greet.md new file mode 100644 index 00000000..176cfcda --- /dev/null +++ b/plugins/aidd-ui/skills/01-hello/actions/01-greet.md @@ -0,0 +1,15 @@ +# 01 - greet + +Greets the caller. + +## Inputs + +- none + +## Outputs + +- a short greeting printed in the chat + +## Process + +1. Print "Hello from aidd-ui (alpha)." diff --git a/release-please-config.json b/release-please-config.json index 256c699f..85d6d3ac 100644 --- a/release-please-config.json +++ b/release-please-config.json @@ -82,6 +82,16 @@ "jsonpath": "$.version" } ] + }, + "plugins/aidd-ui": { + "package-name": "aidd-ui", + "extra-files": [ + { + "type": "json", + "path": ".claude-plugin/plugin.json", + "jsonpath": "$.version" + } + ] } } } From d08bd55db0f3bcd083599d0f4df3571d923e8403 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Tue, 23 Jun 2026 06:24:15 +0200 Subject: [PATCH 07/14] chore(deps): target next instead of main for dependabot (#324) Dependabot had no target-branch, so its PRs defaulted to main. main only takes the weekly promotion PR and the auto-merged Release PR (RELEASE.md), so dep updates landing there cut off-cycle releases (js-yaml bump shipped v5.0.3 mid-week). Point both ecosystems at next so updates batch into the weekly release like all other work. Co-authored-by: Claude Opus 4.8 (1M context) --- .github/dependabot.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 60d26dec..f9d10b99 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -2,6 +2,10 @@ version: 2 updates: - package-ecosystem: "github-actions" directory: "/" + # Target `next`, not `main`. `main` only takes the weekly promotion PR and + # the Release PR (see RELEASE.md); dep updates batch on `next` and ship in + # the weekly release instead of cutting off-cycle releases. + target-branch: "next" schedule: interval: "weekly" day: "monday" @@ -15,6 +19,7 @@ updates: - package-ecosystem: "npm" directory: "/" + target-branch: "next" schedule: interval: "weekly" day: "monday" From 87c650ca88cf5ef4df3fbf3a417aba712a2f1240 Mon Sep 17 00:00:00 2001 From: Alex <8973343+alexsoyes@users.noreply.github.com> Date: Tue, 23 Jun 2026 11:29:03 +0200 Subject: [PATCH 08/14] feat(aidd-vcs): add repo-init skill (init + publish a repository) (#269) New skill aidd-vcs:00-repo-init: init a project's repository (git init, default branch, CONTRIBUTING.md, bootstrap commit) and, on request, create the remote and push. Provider- and mechanism-agnostic: host + reach (CLI, MCP, or API) resolved from VCS memory or environment, main as default-branch fallback. No hardcoded provider or fixed mechanism. Conforms to the skill-authoring contract (R1-R13 + action anatomy). Co-authored-by: Baptiste LAFOURCADE Co-authored-by: Claude Opus 4.8 (1M context) --- README.md | 4 +-- plugins/aidd-vcs/.claude-plugin/plugin.json | 4 ++- plugins/aidd-vcs/CATALOG.md | 13 ++++++- .../aidd-vcs/skills/00-repo-init/README.md | 34 ++++++++++++++++++ plugins/aidd-vcs/skills/00-repo-init/SKILL.md | 35 +++++++++++++++++++ .../skills/00-repo-init/actions/01-init.md | 34 ++++++++++++++++++ .../skills/00-repo-init/actions/02-publish.md | 24 +++++++++++++ .../00-repo-init/assets/CONTRIBUTING.md | 18 ++++++++++ .../aidd-vcs/skills/02-pull-request/SKILL.md | 2 +- 9 files changed, 163 insertions(+), 5 deletions(-) create mode 100644 plugins/aidd-vcs/skills/00-repo-init/README.md create mode 100644 plugins/aidd-vcs/skills/00-repo-init/SKILL.md create mode 100644 plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md create mode 100644 plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md create mode 100644 plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md diff --git a/README.md b/README.md index 5f1d5e71..b11a07f0 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@

🇫🇷 The first French open-source framework for AI-driven development.

- 7 plugins · 39 skills · 3 agents · MIT + 7 plugins · 40 skills · 3 agents · MIT

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -178,7 +178,7 @@ SDLC loop: sdlc, plan, implement, assert, audit, review, test, refactor, debug, ### 🌿 [aidd-vcs](plugins/aidd-vcs/README.md) -`4 skills` · stable +`5 skills` · stable Commits, pull / merge requests, release tags, issue creation. diff --git a/plugins/aidd-vcs/.claude-plugin/plugin.json b/plugins/aidd-vcs/.claude-plugin/plugin.json index fc109aa6..36f72f53 100644 --- a/plugins/aidd-vcs/.claude-plugin/plugin.json +++ b/plugins/aidd-vcs/.claude-plugin/plugin.json @@ -2,12 +2,13 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "aidd-vcs", "version": "2.0.0", - "description": "External artifacts: commit, pull-request, release-tag, issue-create", + "description": "External artifacts: repo-init, commit, pull-request, release-tag, issue-create", "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" }, "skills": [ + "./skills/00-repo-init", "./skills/01-commit", "./skills/02-pull-request", "./skills/03-release-tag", @@ -15,6 +16,7 @@ ], "keywords": [ "git", + "repo-init", "commit", "pull-request", "release", diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 9f9bf6c2..7a84091d 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -8,6 +8,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai - [`.claude-plugin`](#claude-plugin) - [`skills`](#skills) + - [`skills/00-repo-init`](#skills00-repo-init) - [`skills/01-commit`](#skills01-commit) - [`skills/02-pull-request`](#skills02-pull-request) - [`skills/03-release-tag`](#skills03-release-tag) @@ -23,6 +24,16 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai ### `skills` +#### `skills/00-repo-init` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-init.md](skills/00-repo-init/actions/01-init.md) | - | +| `actions` | [02-publish.md](skills/00-repo-init/actions/02-publish.md) | - | +| `assets` | [CONTRIBUTING.md](skills/00-repo-init/assets/CONTRIBUTING.md) | - | +| `-` | [README.md](skills/00-repo-init/README.md) | - | +| `-` | [SKILL.md](skills/00-repo-init/SKILL.md) | `Initialize a project's repository - resolve the default branch and VCS provider, run git init with a bootstrap commit, write CONTRIBUTING.md, and on request create the remote repository and push. Use when the user says "init a repo", "git init", "initialize version control", "set up a new repo", "start a project", "create the remote and push", or "publish this repo". Do NOT use for committing changes (use 01-commit), opening pull requests (use 02-pull-request), tagging releases (use 03-release-tag), or cloning an existing remote.` | + #### `skills/01-commit` | Group | File | Description | @@ -42,7 +53,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | | `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | | `-` | [README.md](skills/02-pull-request/README.md) | - | -| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits.` | +| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`.` | #### `skills/03-release-tag` diff --git a/plugins/aidd-vcs/skills/00-repo-init/README.md b/plugins/aidd-vcs/skills/00-repo-init/README.md new file mode 100644 index 00000000..6c7ecd3b --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/README.md @@ -0,0 +1,34 @@ +← [aidd-vcs](../../README.md) + +# 00-repo-init + +Initializes a project's repository locally and, on request, on the remote host: `git init`, sets the default branch, resolves the provider, and can create the remote repository and push, returning its URL. + +> Status: experimental. + +## When to use + +- Starting version control on a new project (e.g. right after scaffolding it). +- Creating the remote repository and pushing the initial state. + +## When NOT to use + +- Cloning an existing remote, opening pull requests, or tagging releases. +- Re-initializing a directory that is already a repository (the local step no-ops there). + +## How to invoke + +`aidd-vcs:00-repo-init`, or say "initialize a git repository here" / "create the remote and publish". + +## Outputs + +- `init`: an initialized `.git`, the default branch set, the resolved provider, and `origin` added when a remote URL is given. +- `publish`: the created remote repository and a push, returning its URL. + +## Prerequisites + +- `git` on the PATH. For `publish`, the resolved host's tooling (CLI, MCP, or API) available and authenticated. + +## Technical details + +Two actions: `init` (local) and `publish` (remote, outward-facing, confirms first). See [SKILL.md](SKILL.md). diff --git a/plugins/aidd-vcs/skills/00-repo-init/SKILL.md b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md new file mode 100644 index 00000000..a205e6dc --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/SKILL.md @@ -0,0 +1,35 @@ +--- +name: 00-repo-init +description: Initialize a project's repository - resolve the default branch and VCS provider, run git init with a bootstrap commit, write CONTRIBUTING.md, and on request create the remote repository and push. Use when the user says "init a repo", "git init", "initialize version control", "set up a new repo", "start a project", "create the remote and push", or "publish this repo". Do NOT use for committing changes (use 01-commit), opening pull requests (use 02-pull-request), tagging releases (use 03-release-tag), or cloning an existing remote. +argument-hint: init | publish +--- + +# Repo Init + +Initializes a project's repository locally and, on request, on the remote host, then returns the remote URL. + +## Available actions + +| # | Action | Role | Input | +| --- | --------- | ------------------------------------------------------------------------------------------------- | ------------------------------- | +| 01 | `init` | Resolve VCS config, `git init`, set the default branch, write `CONTRIBUTING.md`, bootstrap commit | cwd, default_branch, remote_url | +| 02 | `publish` | Create the remote repo on the resolved host and push, return its URL | cwd, non_interactive | + +## Default flow + +Chain `01 → 02`, testing each before the next. The router runs `init` alone for a local-only request, and runs `publish` after an `init` when asked to create the remote. + +## Transversal rules + +- The local step is idempotent. If the target is already a git work tree, `init` does nothing and reports. +- `init` makes one bootstrap commit (`--allow-empty`) so `HEAD` exists and is pushable. The project's real first commit stays the commit skill's job. +- `publish` is outward-facing. It confirms before creating the remote unless `non_interactive` is set. +- The provider is open. Resolve the host and how to reach it (CLI, MCP, or API) from the VCS memory when present, else from the VCS tooling available in the environment. Never restrict to a fixed list or a fixed mechanism. `main` is the default-branch fallback. + +## Assets + +- `assets/CONTRIBUTING.md`: the project-root `CONTRIBUTING.md` template. + +## External data + +- `aidd_docs/memory/vcs.md`: the project's VCS config (default branch, provider), read by both actions when present and pointed to, never copied. diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md new file mode 100644 index 00000000..5ffc0b7c --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/01-init.md @@ -0,0 +1,34 @@ +# 01 - Init + +Initialize a fresh local git repository on the resolved default branch. + +## Input + +- `cwd` (optional): directory to initialize. Defaults to the current directory. +- `default_branch` (optional): overrides the resolved branch. +- `remote_url` (optional): added as `origin` when given. + +## Output + +A report of the repo root, the resolved default branch and provider, and whether `origin` was added. Reports `created: false` and stops when the target is already a git work tree. + +## Process + +1. **Guard.** If `cwd` is already a git work tree, skip and report `created: false`. +2. **Resolve.** Read the default branch and provider from the project's VCS memory. If absent, infer the provider from the environment (an installed VCS CLI, a configured MCP, or an existing remote URL). Fall back to `main` when nothing resolves. An explicit `default_branch` wins. +3. **Init.** Run `git init -b `. +4. **Contribute.** Write `CONTRIBUTING.md` at the repo root from the template, filling `{{PROJECT_NAME}}`. Leave no raw `{{...}}`. + + ```markdown + @../assets/CONTRIBUTING.md + ``` + +5. **Bootstrap.** Commit once so `HEAD` exists and is pushable: `git -C commit --allow-empty -m "chore: initialize repository"`. +6. **Remote.** If `remote_url` is given, run `git -C remote add origin `. + +## Test + +- `git -C rev-parse --is-inside-work-tree` prints `true`. +- `git -C symbolic-ref --short HEAD` equals the resolved default branch. +- `CONTRIBUTING.md` exists at the repo root and contains no `{{`. +- `git -C rev-parse HEAD` resolves to a commit. diff --git a/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md new file mode 100644 index 00000000..fe6a4499 --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/actions/02-publish.md @@ -0,0 +1,24 @@ +# 02 - Publish + +Create the project's remote repository on the resolved host and push to it. Outward-facing; runs after `01-init`. + +## Input + +- `cwd` (optional): the initialized local repository. Defaults to the current directory. +- `non_interactive` (optional, default `false`): skip the confirmation prompt for scaffolder or auto runs. + +## Output + +A report of the created remote URL, the resolved provider, and the pushed default branch. + +## Process + +1. **Resolve.** Read the host and how to reach it (CLI, MCP, or API) from the project's VCS memory. If absent, detect it from the VCS tooling available in the environment. Use no fixed provider list or fixed mechanism. +2. **Confirm.** Unless `non_interactive`, confirm before creating the remote. The remote may be public, so create it private by default. +3. **Create.** Create the remote repository and push through the resolved host tooling. `01-init` already left a pushable `HEAD`. If no host tooling is available, stop and report. +4. **Return.** Report the remote URL to the user. + +## Test + +- The action prints a non-empty remote URL. +- `git -C remote get-url origin` resolves to that URL. diff --git a/plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md b/plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md new file mode 100644 index 00000000..e13f1bbe --- /dev/null +++ b/plugins/aidd-vcs/skills/00-repo-init/assets/CONTRIBUTING.md @@ -0,0 +1,18 @@ +# Contributing to {{PROJECT_NAME}} + +## Setup + +See `INSTALL.md`. + +## Workflow + +1. Branch off the default branch. +2. Implement against the wired route stubs - keep architecture boundaries (see `INSTALL.md`). +3. Add or extend tests alongside the code (see `INSTALL.md` for how to run them). +4. Run the suite before opening a request. + +## Conventions + +- Commits: conventional commits (`(): description`). +- The CI pipeline runs the test suite on every push; keep it green. +- Do not put business logic in route stubs until you replace them with real handlers. diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 638e29cb..4a01ea01 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -1,6 +1,6 @@ --- name: 02-pull-request -description: Create a draft pull or merge request from the current branch. Use when the user says "open a pr", "open a pull request", "create a pr", "create a merge request", "open mr", "draft a pr for this branch", or invokes `/pull-request`. Do NOT use for committing changes, pushing a branch directly, tagging releases, merging an existing request, or amending commits. +description: Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`. --- # Pull Request From c13d41fe1c200db262c23910bbe73600aa52a235 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Tue, 23 Jun 2026 21:30:09 +0200 Subject: [PATCH 09/14] docs(framework): unify change taxonomy into one source of truth (#325) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ci(deps): bump actions/checkout from 6.0.3 to 7.0.0 (#321) Bumps [actions/checkout](https://github.com/actions/checkout) from 6.0.3 to 7.0.0. - [Release notes](https://github.com/actions/checkout/releases) - [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/checkout/compare/df4cb1c069e1874edd31b4311f1884172cec0e10...9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0) --- updated-dependencies: - dependency-name: actions/checkout dependency-version: 7.0.0 dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * docs(framework): unify change taxonomy into one source of truth The same change taxonomy (kind -> where it ships) was re-spelled across branch prefix, commit type, label, and the board "Work Type" field, and the four drifted. A maintainer got lost finding routing info. Make aidd_docs/memory/vcs.md the single canonical home: one dense table (kind, prefix, commit type, triage label, next/main) plus a strict routing rule. CONTRIBUTING and RELEASE now link it instead of restating it; the inline label table is gone. Trim labels 11 -> 8 (drop help wanted, npm, github-actions) and stop dependabot re-adding the dropped ecosystem labels. Add a Project 8 board playbook + label-delete note to MAINTAINERS, and fix its stale "Work Type" reference. Routing is derived from the branch prefix, never a label or board field. Spec + plan recorded under aidd_docs/. Co-Authored-By: Claude Opus 4.8 (1M context) * fix(aidd-vcs): derive PR base from branch prefix, auto-apply triage label The pull-request action resolved the base from origin/HEAD against a candidate list (main/master/develop/staging) that omitted `next`, so a `feat/*` PR targeted `main`. Resolve the base from the head branch's prefix via the project-memory routing table first, falling back to the old detection. After opening, apply the prefix's triage label when it exists. Stays generic: reads project memory, never hardcodes `next`. Also fix the stale `aidd_docs/` -> `docs/` prefix in the branch template. Co-Authored-By: Claude Opus 4.8 (1M context) * docs(framework): make the routing table an actionable guide Reframe the canonical Types table as "I want to… → I do…": add an Issue template column and a one-line board Status flow, so a contributor finds their row and reads off branch, label, and PR target in one glance. Still the single source of truth — no new table, no duplication. Co-Authored-By: Claude Opus 4.8 (1M context) --------- Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Claude Opus 4.8 (1M context) --- .github/dependabot.yml | 2 - .github/labels.yml | 18 ++--- .github/workflows/back-merge.yml | 2 +- .github/workflows/ci.yml | 8 +-- .github/workflows/codeql.yml | 2 +- .github/workflows/validate.yml | 2 +- CONTRIBUTING.md | 11 +-- RELEASE.md | 4 +- aidd_docs/memory/vcs.md | 36 +++++++--- .../2026_06_23-unify-taxonomy/phase-1.md | 55 +++++++++++++++ .../2026_06_23-unify-taxonomy/phase-2.md | 43 ++++++++++++ .../2026_06_23-unify-taxonomy/phase-3.md | 56 ++++++++++++++++ .../2026_06_23-unify-taxonomy/phase-4.md | 64 ++++++++++++++++++ .../2026_06_23-unify-taxonomy/phase-5.md | 67 +++++++++++++++++++ .../plans/2026_06_23-unify-taxonomy/plan.md | 60 +++++++++++++++++ .../2026_06/2026_06_23-unify-taxonomy.md | 49 ++++++++++++++ docs/MAINTAINERS.md | 65 +++++++++++++++++- .../actions/01-pull-request.md | 9 ++- .../skills/02-pull-request/assets/branch.md | 2 +- 19 files changed, 510 insertions(+), 45 deletions(-) create mode 100644 aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md create mode 100644 aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md create mode 100644 aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md create mode 100644 aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md create mode 100644 aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md create mode 100644 aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md create mode 100644 aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md diff --git a/.github/dependabot.yml b/.github/dependabot.yml index f9d10b99..8ed28f73 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -15,7 +15,6 @@ updates: include: "scope" labels: - "dependencies" - - "github-actions" - package-ecosystem: "npm" directory: "/" @@ -29,4 +28,3 @@ updates: include: "scope" labels: - "dependencies" - - "npm" diff --git a/.github/labels.yml b/.github/labels.yml index 48bc27cd..25ecc914 100644 --- a/.github/labels.yml +++ b/.github/labels.yml @@ -1,5 +1,9 @@ # Canonical issue and PR label list for ai-driven-dev/framework. # +# Labels are TRIAGE ONLY: they categorize an issue or PR. They never decide +# where a PR targets — routing is by branch prefix (see aidd_docs/memory/vcs.md). +# Keep one triage label per change. +# # This file is the source of truth. When the GitHub label set drifts from # this file, sync manually with: # @@ -24,31 +28,19 @@ color: 0075ca - name: security - description: Security-sensitive issue or fix + description: Security-sensitive issue or fix (cross-cutting, add to any kind) color: B60205 - name: good first issue description: Good for newcomers color: 7057ff -- name: help wanted - description: Extra attention is needed - color: 008672 - # --- Dependencies -------------------------------------------------------- - name: dependencies description: Dependency update (dependabot) color: 0366d6 -- name: github-actions - description: GitHub Actions workflow change - color: "000000" - -- name: npm - description: npm dependency update - color: cb3837 - # --- Release tooling ----------------------------------------------------- - name: "autorelease: pending" diff --git a/.github/workflows/back-merge.yml b/.github/workflows/back-merge.yml index 2a234956..9bdf4af0 100644 --- a/.github/workflows/back-merge.yml +++ b/.github/workflows/back-merge.yml @@ -25,7 +25,7 @@ jobs: app-id: ${{ secrets.AIDD_BOT_APP_ID }} private-key: ${{ secrets.AIDD_BOT_PRIVATE_KEY }} - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: ref: next fetch-depth: 0 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3334d65f..356729c1 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -22,7 +22,7 @@ jobs: contents: read pull-requests: read steps: - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 with: fetch-depth: 0 - uses: wagoid/commitlint-github-action@b948419dd99f3fd78a6548d48f94e3df7f6bf3ed # v6.2.1 @@ -94,7 +94,7 @@ jobs: if: needs.release-please.outputs.release_created == 'true' runs-on: ubuntu-latest steps: - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Build clean marketplace bundle # A self-contained marketplace a user can extract and register with @@ -141,7 +141,7 @@ jobs: - { tool: codex, mode: flat, flag: "--flat" } - { tool: opencode, mode: flat, flag: "--flat" } steps: - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 with: @@ -193,7 +193,7 @@ jobs: echo "released=false" >> $GITHUB_OUTPUT fi - - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 if: steps.check.outputs.released == 'true' - name: Get plugin version diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index b2bd1ab6..68b81d32 100644 --- a/.github/workflows/codeql.yml +++ b/.github/workflows/codeql.yml @@ -28,7 +28,7 @@ jobs: language: [javascript-typescript] steps: - name: Checkout - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Initialize CodeQL uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2 diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index 65c27879..291ab085 100644 --- a/.github/workflows/validate.yml +++ b/.github/workflows/validate.yml @@ -22,7 +22,7 @@ jobs: CI: "true" steps: - name: Checkout - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3 + uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0 - name: Setup Node uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8d9de6e9..b926b083 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -78,16 +78,9 @@ One scope per commit (split cross-plugin changes). The types, the scopes, and th ## 3. Open a pull request -- Branch off `next` and target `next` (the integration branch); `hotfix/*` branches off `main` for urgent production fixes. See [`RELEASE.md`](./RELEASE.md). +- Branch off `next` and target `next` (the integration branch); only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target — the full prefix → label → target table is in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#types). - **Fill the PR template** (applied automatically): explain *what* changed and *how* you resolved it technically - that narrative is the point of the PR. The conventional title and pre-commit hooks are already enforced by CI, so don't spend the description re-asserting them. -- **Label the PR** so reviewers and the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8) triage at a glance: - - | Label | When to use | - | ----- | ----------- | - | `bug` | A fix for broken behaviour. | - | `enhancement` | A new skill, agent, rule, or feature. | - | `documentation` | A docs-only change (README, CONTRIBUTING, skill docs). | - | `security` | A security-sensitive change or fix. | +- **Label the PR** so reviewers and the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8) triage at a glance. The triage label follows your branch kind and the PR skill applies it automatically; the label per kind is in that same [routing table](aidd_docs/memory/vcs.md#types) (`security` is cross-cutting — add it to any kind). - The PR title follows the same conventional format (the **Commitlint** CI job enforces it); PRs are squash-merged using that title. - A **Habilité** review gates every merge ([`CODEOWNERS`](./.github/CODEOWNERS)); Certifié contributors cannot self-merge. - Decision rules (lazy consensus, explicit consensus for cross-plugin/contract changes, the quality veto) live in [`GOVERNANCE.md`](./GOVERNANCE.md#code-decisions-merging). diff --git a/RELEASE.md b/RELEASE.md index 6b56092c..8eb93edc 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -21,7 +21,9 @@ For who may merge and release, see [`GOVERNANCE.md`](GOVERNANCE.md). ## Where your change goes Almost everything flows through `next` and ships in the weekly release. Only an -urgent production fix takes the fast lane straight to `main`. +urgent production fix takes the fast lane straight to `main`. The branch prefix +decides the target; the canonical prefix → target table lives in +[`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#types). ```mermaid flowchart LR diff --git a/aidd_docs/memory/vcs.md b/aidd_docs/memory/vcs.md index 4fc34de5..2f3c7e46 100644 --- a/aidd_docs/memory/vcs.md +++ b/aidd_docs/memory/vcs.md @@ -16,15 +16,33 @@ type/ticket-short-description ### Types -| Prefix | Usage | Branch from | PR target | -| --- | --- | --- | --- | -| `feat/` | New feature | `next` | `next` | -| `fix/` | Bug fix | `next` | `next` | -| `docs/` | Documentation only | `next` | `next` | -| `refactor/` | Code change (no feat/fix) | `next` | `next` | -| `chore/` | Build, config, deps | `next` | `next` | -| `test/` | Add/update tests | `next` | `next` | -| `hotfix/` | Urgent production fix | `main` | `main` | +The single source of truth: find your row, read left to right — it tells you the +branch to create, the label that applies, and where the PR goes. The branch +**prefix** alone decides the target (not a label, not a board field); the +`aidd-vcs:02-pull-request` skill reads this table to set the base automatically. + +| I want to… | Issue template | Branch | Commit | Label (auto) | PR targets | +| ---------- | -------------- | ------ | ------ | ------------ | ---------- | +| ship a feature | ✨ Feature | `feat/…` | `feat:` | `enhancement` | `next` | +| fix a bug | 🐛 Bug | `fix/…` | `fix:` | `bug` | `next` | +| change docs only | ✨ Feature | `docs/…` | `docs:` | `documentation` | `next` | +| refactor (no behaviour change) | — | `refactor/…` | `refactor:` | — | `next` | +| build / config / deps | — | `chore/…` | `chore:` | `dependencies` | `next` | +| add or update tests | — | `test/…` | `test:` | — | `next` | +| 🚨 urgent production fix | 🐛 Bug | `hotfix/…` | `fix:` | `bug` | **`main`** | + +#### Routing rule (strict) + +- Everything batches on `next` and ships in the weekly release. +- **Only `hotfix/*` targets `main`** — an urgent production fix, out of cycle. + +Once the PR is open, the board advances on its own: +`Todo → In review` (PR opened) `→ Ready` (review approved) `→ Done` (merged). + +Labels are **triage only**: they categorize, they never route. `security` is +cross-cutting — add it to any kind when the change is security-sensitive. The +"Commit" column shows the conventional type; the authoritative type list is the +[Commit Convention](#commit-convention) below (mirrors `commitlint.config.cjs`). ### Examples diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md new file mode 100644 index 00000000..5ef7e5b2 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md @@ -0,0 +1,55 @@ +--- +status: done +--- + +# Instruction: Canonical routing table + +Part of [`plan.md`](./plan.md). Dependency root — author before all other phases. + +## Architecture projection + +```txt +aidd_docs/memory/ +└── vcs.md 🔁 Branch-Naming "Types" table gains 2 columns (triage label, + routing ✓/-) + a strict routing callout + a triage-only note. +``` + +## Tasks to do + +### `1)` Replace the branch "Types" table with the dense canonical table + +> One grid that maps kind → prefix → commit type → triage label → destination. + +1. Under `## Branch Naming Convention` → `### Types`, replace the current 4-column table with: + + | Kind | Branch prefix | Commit type | Triage label | `next` | `main` | + | ---- | ------------- | ----------- | ------------ | :----: | :----: | + | Feature | `feat/` | `feat` | `enhancement` | ✓ | – | + | Fix | `fix/` | `fix` | `bug` | ✓ | – | + | Docs | `docs/` | `docs` | `documentation` | ✓ | – | + | Refactor | `refactor/` | `refactor` | – | ✓ | – | + | Chore | `chore/` | `chore` | `dependencies` | ✓ | – | + | Test | `test/` | `test` | – | ✓ | – | + | Hotfix | `hotfix/` | `fix` | `bug` | – | ✓ | + +2. Keep the existing `### Format` and `### Examples` blocks unchanged. + +### `2)` Add the strict routing callout + triage-only note + +> Make the rule unmissable and kill the label/route confusion. + +1. Immediately under the table, add a short callout, in substance: + - The branch **prefix alone** decides the PR target — not a label, not a board field. + - Everything batches on `next`; **only `hotfix/*` targets `main`** (urgent production fix, out of cycle). + - The `aidd-vcs:02-pull-request` skill reads this table to set the base branch automatically. +2. Add the triage-only note: labels categorize, they never route; `security` is cross-cutting — add it to any kind when the change is security-sensitive. +3. Confirm the commit-type and changelog definitions are untouched (the `## Commit Convention` section stays as-is; the table's "commit type" column is illustrative, not a redefinition). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | The dense 6-column table renders in `vcs.md`; exactly one row routes to `main` (`hotfix`); all others to `next`. | +| 1 | The table is the only place in the repo with the kind·prefix·label·✓/- grid (`grep -rl` for a unique cell string returns only `vcs.md`). | +| 2 | A "routing rule (strict)" callout states prefix-decides-target and the single `hotfix→main` exception; a triage-only note is present. | +| 2 | `## Commit Convention` section is byte-identical to before (no commit-type or scope changes). | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md new file mode 100644 index 00000000..3a4b9359 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md @@ -0,0 +1,43 @@ +--- +status: done +--- + +# Instruction: Label set + dependabot (atomic) + +Part of [`plan.md`](./plan.md). **Atomic unit** — both files change together; never drop a label from one without the other (else dependabot recreates it ungoverned). + +## Architecture projection + +```txt +.github/ +├── labels.yml 🔁 11 → 8 labels + triage-only header note. +└── dependabot.yml 🔁 `labels:` keys lose `npm` and `github-actions`. +``` + +## Tasks to do + +### `1)` Trim `labels.yml` to 8 + header note + +> Keep triage types + required automation labels; cut the noise. + +1. Keep: `bug`, `enhancement`, `documentation`, `security`, `good first issue`, `dependencies`, `autorelease: pending`, `autorelease: tagged`. +2. Remove: `help wanted`, `npm`, `github-actions`. +3. Add a header comment: labels are **triage only**; routing is by branch prefix (see `aidd_docs/memory/vcs.md`); keep one triage label per change. +4. Leave colors/descriptions of kept labels intact (refine `security` description to note it is cross-cutting). + +### `2)` Drop ecosystem labels from `dependabot.yml` + +> The `dependencies` umbrella is enough at this scale. + +1. In the `github-actions` ecosystem block, set `labels: ["dependencies"]` (remove `github-actions`). +2. In the `npm` ecosystem block, set `labels: ["dependencies"]` (remove `npm`). +3. Touch nothing else (schedule, prefixes, limits stay). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | `grep '^- name:' .github/labels.yml` lists exactly the 8 kept labels; `help wanted`, `npm`, `github-actions` absent. | +| 1 | Header comment states triage-only + routing-by-prefix + link to vcs.md. | +| 2 | Both ecosystem blocks in `dependabot.yml` have `labels: ["dependencies"]` only. | +| 1+2 | `grep -rn -e 'help wanted' -e '"npm"' -e 'github-actions' .github/labels.yml .github/dependabot.yml` returns no orphan reference to a dropped label. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md new file mode 100644 index 00000000..6e16a94d --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md @@ -0,0 +1,56 @@ +--- +status: done +--- + +# Instruction: Docs point to canonical (no duplication) + +Part of [`plan.md`](./plan.md). Depends on phase 1 (the anchor target must exist). + +## Architecture projection + +```txt +. +├── CONTRIBUTING.md 🔁 Inline label table (L75-80) → link to vcs.md table; +│ routing prose (L71) → short pointer + link. +└── RELEASE.md 🔁 "Where your change goes" links the vcs.md table; + flow mermaid kept; any restated routing prose trimmed. +``` + +## User Journey + +```mermaid +flowchart TD + A[Contributor lost] --> B[CONTRIBUTING hub] + B -->|naming + routing| C[vcs.md table] + B -->|release flow| D[RELEASE.md] + B -->|who merges| E[GOVERNANCE.md] +``` + +## Tasks to do + +### `1)` De-duplicate `CONTRIBUTING.md` + +> It is already a hub; remove the one restated taxonomy. + +1. Replace the inline label table (the `| Label | When to use |` block) with a one-line pointer to the canonical table: triage labels + routing live in `aidd_docs/memory/vcs.md` (link to the `#types` anchor). Keep the PR-labelling instruction itself. +2. Trim the routing prose ("Branch off `next`… `hotfix/*` off `main`…") to a short gist + link to the vcs.md table; do not restate the full table. +3. Verify the three hub links resolve and are one hop each: naming/routing → vcs.md, release → RELEASE.md, merge → GOVERNANCE.md. +4. Confirm the issue-template path still holds: opening a 🐛 / ✨ issue applies `bug` / `enhancement` automatically (no edit — verification only). + +### `2)` Point `RELEASE.md` at the canonical table + +> Anyone landing here finds the table by link, not a copy. + +1. In `## Where your change goes`, add a sentence linking the canonical prefix→target table at `aidd_docs/memory/vcs.md#types`. +2. Keep the existing flow mermaid and the commit-type→changelog table (release domain, matches release-please-config — leave as-is). +3. Ensure no prefix→target *table* is restated here (the mermaid is a flow diagram, allowed). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | `CONTRIBUTING.md` no longer contains the `| Label | When to use |` table; a link to `vcs.md` triage/routing replaces it. | +| 1 | CONTRIBUTING contains exactly one link each to vcs.md, RELEASE.md, GOVERNANCE.md reachable in one hop. | +| 1 | Creating an issue via each template yields it pre-labelled (`labels:` keys confirmed present in both templates). | +| 2 | `RELEASE.md` "Where your change goes" links `vcs.md#types`; no prefix→target table restated. | +| 1+2 | A text search for a unique cell of the canonical grid returns hits only in `vcs.md`, not in CONTRIBUTING/RELEASE/GOVERNANCE. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md new file mode 100644 index 00000000..c1fa8f54 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md @@ -0,0 +1,64 @@ +--- +status: done +--- + +# Instruction: PR automation routes by prefix + +Part of [`plan.md`](./plan.md). Depends on phase 1 (the skill reads the canonical table from memory). Keep the plugin **generic** — it reads project memory, never hardcodes `next`. + +## Architecture projection + +```txt +plugins/aidd-vcs/skills/02-pull-request/ +├── actions/01-pull-request.md 🔁 Base resolution derives target from branch +│ prefix via project memory; +auto-label step. +└── assets/branch.md 🔁 Stale `aidd_docs/` → `docs/` prefix. +``` + +## User Journey + +```mermaid +flowchart TD + A[Head branch e.g. feat/x] --> B{prefix in project-memory table?} + B -->|yes| C[base = that row's PR target] + B -->|no| D[fallback: origin/HEAD, then main/master/develop/staging] + C --> E[open draft PR] + D --> E + E --> F[apply matching triage label if defined + exists] +``` + +## Tasks to do + +### `1)` Base resolution by branch prefix + +> Fixes feat/→main: `next` was absent from the candidate list. + +1. In `## Process` step 3 (Base resolution), insert a match BEFORE the `origin/HEAD` fallback: if the project's branch-naming convention (project memory) maps the head branch's prefix to a PR target, use that target. +2. Keep the existing `origin/HEAD` → `main/master/develop/staging` as the fallback when no prefix mapping exists. +3. Keep it generic: phrase as "the branch-naming convention in project memory", never hardcode `next`. +4. Surface the chosen base and the reason ("prefix `feat/` → `next` per project convention") during the step-7 validation. + +### `2)` Auto-apply the triage label + +> A PR is born typed, matching the issue model. + +1. Add a numbered step after "Open draft": when the convention maps the head prefix to a triage label and that label exists in the repo, apply it; skip silently otherwise. +2. State explicitly: labels triage only; this step never changes the base resolved earlier. +3. Update the `## Test` checklist to cover prefix-derived base + label application; extend Outputs if a label field is warranted. + +### `3)` Fix the stale generic template + +> `branch.md` is a generic distributable template; correct the bug only. + +1. In `assets/branch.md` Types table, change the `aidd_docs/` prefix row to `docs/`. +2. No other change — it stays a generic naming template (no `next`/`main`, no repo-specific routing). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | Step 3 lists a prefix→target derivation via project memory BEFORE the origin/HEAD fallback; no literal `next` hardcoded. | +| 1 | Tracing the doc logic: a `feat/*` head resolves base `next`; `hotfix/*` resolves `main` (per the vcs.md table). | +| 2 | A numbered step applies the prefix-mapped triage label post-open, gated on label existence, marked triage-only. | +| 2 | `## Test` checklist asserts the prefix-derived base and the applied label. | +| 3 | `assets/branch.md` shows `docs/`; no `aidd_docs/` remains; no `next`/`main` added. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md new file mode 100644 index 00000000..2ffa2ac9 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md @@ -0,0 +1,67 @@ +--- +status: done +--- + +# Instruction: Board playbook (Project 8) + +Part of [`plan.md`](./plan.md). The board is GitHub Project config, not repo files — deliver a **playbook** the maintainer applies. Independent of phases 1-4 (can run in parallel). + +## Architecture projection + +```txt +docs/ +└── MAINTAINERS.md 🔁 New "## Project board (Project 8)" section: the + field/status/view playbook (gh commands + UI steps). +``` + +> Confirm `MAINTAINERS.md` is the right host at implement; if it does not fit, create `docs/BOARD.md` and link it from MAINTAINERS + CONTRIBUTING. + +## User Journey + +```mermaid +flowchart TD + A[Maintainer opens playbook] --> B[Drop Work type + Phases] + B --> C[Keep Priority] + C --> D[Set Status options] + D --> E[Wire built-in workflows] + E --> F[Add Timeline view] +``` + +## Tasks to do + +### `1)` Write the field-cleanup steps + +> Each board property answers one question; kill the duplicates. + +1. **Drop "Work type"** (duplicates the Type label) and **"Phases"** (duplicates Status/Milestone). Provide the `gh` inspection + deletion commands, e.g.: + - `gh project field-list 8 --owner ai-driven-dev` to read field IDs. + - `gh project field-delete ` for each dropped field. +2. **Keep Priority** — state explicitly it stays (P0·P1·P2), no action. + +### `2)` Status options + automation + +> Status carries the flow and advances itself. + +1. Set Status single-select options: `Todo · In progress · In review · Ready · Done`. Note this is a single-select field edit (UI; `gh project field-create` only creates new fields — document the UI path to edit the existing Status options, with the `gh` create path as the from-scratch alternative). +2. Document the built-in workflow wiring (Project → Workflows, UI): + - item added → **Todo** + - PR linked / ready for review → **In review** + - code review approved → **Ready** + - PR merged / issue closed → **Done** +3. Flag which transitions are GitHub built-ins vs. manual moves (In progress is typically manual). + +### `3)` Timeline view + verification checklist + +> The "phases" replacement Alex asked for. + +1. Add a **Timeline** view (UI: New view → Timeline; date field = target/milestone). Document the steps. +2. End the section with a tick-box checklist mirroring the spec board done-when: Work type removed · Phases removed · Priority kept · Status options set · automation enabled · Timeline view present. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | Playbook gives concrete `gh project field-list`/`field-delete` commands for Work type + Phases, and states Priority is kept. | +| 2 | Playbook lists the 5 Status options and the 4 built-in transitions, marking built-in vs manual. | +| 3 | Playbook documents adding a Timeline view and ends with a board-done-when checklist. | +| all | Section is self-contained: a maintainer can apply it end-to-end without re-deriving anything from the Loom. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md new file mode 100644 index 00000000..2e8f91ca --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md @@ -0,0 +1,60 @@ +--- +objective: "The change taxonomy + routing rule live in one canonical table (vcs.md); every other surface links to it or derives from it; the board playbook is delivered." +status: implemented +--- + +# Plan: Unify the change taxonomy into one source of truth + a projected board + +## Overview + +| Field | Value | +| ---------- | --------------------------------------------------------------------- | +| **Goal** | One canonical routing table; all surfaces link/derive; board playbook. | +| **Source** | [`2026_06_23-unify-taxonomy.md`](../../specs/2026_06/2026_06_23-unify-taxonomy.md) (spec, VALID 100/100) | + +## Phases + +| # | Phase | File | +| --- | ------------------------------ | ---------------------------- | +| 1 | Canonical routing table | [`phase-1.md`](./phase-1.md) | +| 2 | Label set + dependabot (atomic)| [`phase-2.md`](./phase-2.md) | +| 3 | Docs point to canonical | [`phase-3.md`](./phase-3.md) | +| 4 | PR automation routes by prefix | [`phase-4.md`](./phase-4.md) | +| 5 | Board playbook (Project 8) | [`phase-5.md`](./phase-5.md) | + +## Resources + +| Source | Verified | +| ------------- | --------------------------- | +| `aidd_docs/memory/vcs.md` | Holds branch table (prefix · from · target) — no label column, no ✓/-. Becomes the dense canonical. | +| `RELEASE.md` | "Where your change goes" has a flow mermaid + commit→changelog table (matches release-please-config). | +| `CONTRIBUTING.md` | Already a hub: links vcs.md (commits L67), RELEASE (routing L71), GOVERNANCE (merge). Inline label table L75-80 is the one duplication. | +| `.github/labels.yml` | 11 labels. | +| `.github/dependabot.yml` | Applies `dependencies`+`npm` and `dependencies`+`github-actions` — must drop in lockstep with labels.yml. | +| `.github/ISSUE_TEMPLATE/bug_report.yml` / `feature_request.yml` | Already carry `labels: ["bug"]` / `["enhancement"]` — done-when "issue born typed" PRE-SATISFIED; verify-only. | +| `plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md` | Base resolution candidate list `main/master/develop/staging` — `next` absent (the feat/→main bug). | +| `docs/MAINTAINERS.md` | Existing maintainer-ops home — proposed host for the board playbook section. | + +## Decisions + +| Decision | Why | +| ---------- | -------------- | +| Canonical table lives in `vcs.md` (AI-auto-loaded memory) | PR skill + AI both read memory; flipping to a human doc would couple automation to a non-loaded file. | +| RELEASE keeps its flow mermaid | A flow diagram ≠ the mapping table; the prefix→target *table* stays single-homed in vcs.md, RELEASE links it. | +| Board playbook appended to `docs/MAINTAINERS.md` | Maintainer-ops already lives there; avoids a new orphan doc (no-sprawl ethos). Confirm fit at implement. | +| Issue templates: no edit | They already apply the Type label; editing would be churn. | +| Plugin `branch.md` / PR action stay generic | Distributable layer (ARCHITECTURE.md); they read project memory, never hardcode `next`. | + +## Spec done-when → phase coverage + +| Spec done-when | Phase | +| -------------- | ----- | +| Mapping exists once; others link | 1 (author) + 3 (link) | +| Strict: single production-routed row | 1 | +| Front-door routes 3 destinations, one hop | 3 | +| Label set reduced, triage-only, no routing-by-label | 2 | +| Dropped labels not recreated by automation | 2 | +| Issue born typed | pre-satisfied (verify in 3) | +| PR base + label by prefix | 4 | +| Board fields orthogonal (Work type, Phases gone; Priority kept) | 5 | +| Status lifecycle + automation + Timeline view | 5 | diff --git a/aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md b/aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md new file mode 100644 index 00000000..d540653c --- /dev/null +++ b/aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md @@ -0,0 +1,49 @@ +# Unify the change taxonomy into one source of truth + a projected board + +## Target + +Define the change-classification taxonomy and its routing rule **once**, in a single canonical place that every other contributor-facing surface and the project board links to or derives from — never restates. + +## Hard constraints + +- One canonical home for the taxonomy/routing definition; every other document links to it rather than restating it (repo rule: never duplicate across docs). +- Routing (which branch a change targets) is **derived from the branch prefix**, never stored as a label or a board field. +- The canonical definition must be consumable by both the AI tooling (the always-loaded project memory) and humans, without a second copy existing. +- The distributable plugin templates stay generic — they are products shipped to other projects, not mirrors of this repo's own instance. +- Commit-type and changelog-section definitions are left unchanged (already aligned to Conventional Commits and the release tool). +- Board changes are delivered as a maintainer playbook (the board is external config), not as repo file edits; repo deliverables must not assume the board can be edited as repo files. +- Each board field and each label answers a distinct question; no field may duplicate another field or a label. + +## Non-goals + +- Renaming the `enhancement` label to `feature` — `enhancement` stays; the spec only documents that it is the label form of a `feat`/feature change. +- Any label-sync workflow or board automation beyond GitHub's built-in project workflows. +- Changing the allowed commit types or the changelog sections. +- Restructuring the generic plugin pull-request / branch templates beyond correcting a stale, incorrect prefix value. +- Building the board for the maintainer — the spec supplies the playbook; applying it is the maintainer's act. + +## Done-when + +- The change-kind → routing (next vs main) mapping exists in exactly one document; searching the repo finds that mapping rendered once, and every other doc that needs it contains a link to that single home. *(verify: text search shows one occurrence of the mapping table; the release doc and the contributor doc each link to it.)* +- The routing rule is strict and unambiguous: exactly one branch prefix routes to the production branch (the urgent-fix prefix); all other prefixes route to the integration branch. *(verify: the canonical table shows a single production-routed row.)* +- A single contributor front-door document routes a reader to naming+routing, the release flow, and the merge/governance rules, each reachable in one hop. *(verify: the front-door doc contains a link to each of the three; and a text search for the canonical routing table/sentence returns hits only in its canonical home, not in the front-door, release, or governance docs.)* +- The issue/PR label set is reduced to triage-type labels plus the automation labels the tooling requires; no label encodes routing, and a header states labels are triage-only. *(verify: the label list equals the agreed reduced set; a search finds no label used to decide routing.)* +- Labels removed from the canonical list are not recreated by any automation. *(verify: the dependency-update config no longer references the removed labels.)* +- An issue opened from a project issue template is created already carrying its Type label, with no manual step. *(verify: creating an issue via each template yields an issue pre-labelled with its type.)* +- A pull request opened by the project's PR automation targets the branch determined solely by the head branch's prefix, and carries the matching Type label. *(verify: a feature-prefixed branch produces a PR targeting the integration branch; the urgent-fix prefix targets production; the type label is present.)* +- The board exposes only orthogonal fields — the field that duplicated the Type label is gone, and the redundant phase field is gone — while Priority remains. *(verify: board playbook checklist confirms both fields removed and Priority kept.)* +- The board Status field carries the agreed lifecycle states and advances through them via built-in automation, and a Timeline view exists. *(verify: board playbook checklist confirms the Status options, the enabled built-in transitions, and the Timeline view.)* + +## Stakeholders + +- Decider: Baptiste (resolves any taxonomy/placement tradeoff). +- Owner: Baptiste & Alex (maintainers, long-term owners of the convention and the board). +- Consumer: public contributors (read the docs/board, open issues/PRs) and the AI tooling (reads the canonical memory, opens PRs, applies labels). + +## Context + +- Source: Alex's Loom review — the same taxonomy is currently re-spelled across branch prefix, commit type, label, and the board "Work type" field, and the four drift; a maintainer got lost finding routing info. The ask: fewer, clearer, non-duplicated, strict rules. +- Guiding principle agreed in brainstorm: one taxonomy, defined once, projected everywhere (docs, label, board field, timeline), advanced by automation, never re-typed by a human. +- Orthogonal property model agreed: Type → label; Priority → board field; Status → board field (auto-advanced); When → milestone/timeline; Effort/onboarding → the good-first-issue label; Routing → derived from branch prefix. +- Existing anchors that constrain the canonical definition: the commit linter (Conventional Commits) and the release tool's changelog sections are already correct and authoritative for their domains; the taxonomy mirrors them, it does not redefine them. +- The board is GitHub Project 8 (public roadmap + maintainer triage), configured outside the repo. diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index 92d37f8a..06b0dc8a 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -15,10 +15,73 @@ How to operate this repository day to day. For **who** may do what and the decis ## Daily -- **Triage issues.** New issues auto-add to board #8. Set `Status` / `Area` / `Priority` / `Work Type`; link under an epic (native sub-issues) if relevant. +- **Triage issues.** New issues auto-add to board #8. Set `Status` / `Area` / `Priority`; link under an epic (native sub-issues) if relevant. **Type** is the issue/PR label, not a board field (see [Project board layout](#project-board-project-8)). - **Roadmap.** Priority is set by the community vote (mechanism in `GOVERNANCE.md`). Accepted items live on board #8 - keep `ROADMAP.md` as a pointer, do not maintain a second list. - **Review PRs.** Every PR needs a Habilité (CODEOWNERS) approval; checks `lefthook`, `Commitlint` must pass; squash-merge. +## Project board (Project 8) + +The board is a **view** of the same taxonomy the docs define — it never invents its own. Each property answers one question: **Type** = the label, **Priority** = how urgent, **Status** = where in the flow, **When** = the Timeline. Routing (`next` vs `main`) is *not* a board property — it derives from the branch prefix ([routing table](../aidd_docs/memory/vcs.md#types)). + +Apply this layout once (org-admin or board-write needed). Read field IDs first: + +```bash +gh project field-list 8 --owner ai-driven-dev # note the IDs you need below +``` + +### Fields + +- **Drop `Work type`** — duplicates the Type label. **Drop `Phases`** — duplicates Status/Milestone (and no milestone exists, so it is noise): + ```bash + gh project field-delete --id + gh project field-delete --id + ``` +- **Keep `Priority`** (P0 · P1 · P2) and `Area`. No action. +- **`Status`** — single-select options, in order: `Todo` · `In progress` · `In review` · `Ready` · `Done`. `Status` is a built-in field; edit its options in the UI (Board → `Status` field header → Edit values). The CLI only *creates* fields, so use it only if you are rebuilding from scratch: + ```bash + # from-scratch alternative only — NOT for editing the existing Status field + gh project field-create 8 --owner ai-driven-dev --name Status \ + --data-type SINGLE_SELECT \ + --single-select-options "Todo,In progress,In review,Ready,Done" + ``` + +### Status automation (UI: Project → ⋯ → Workflows) + +GitHub built-in workflows drive most transitions; `In progress` is the one manual move. + +| Trigger (built-in) | Set `Status` to | +| ------------------ | --------------- | +| Item added to project | `Todo` | +| Pull request linked / ready for review | `In review` | +| Code review approved | `Ready` | +| Pull request merged · item closed | `Done` | +| *(manual — picked up by a maintainer)* | `In progress` | + +### Timeline view + +Replaces the old "Phases". UI: **New view → Timeline**, date field = the Milestone / target date. Use it as the roadmap horizon (`this week` / `next` / `later`). + +### Apply checklist + +- [ ] `Work type` field deleted +- [ ] `Phases` field deleted +- [ ] `Priority` kept +- [ ] `Status` options = Todo · In progress · In review · Ready · Done +- [ ] Built-in Status workflows enabled (added→Todo, ready→In review, approved→Ready, merged/closed→Done) +- [ ] Timeline view present + +## Labels + +[`.github/labels.yml`](../.github/labels.yml) is the canonical set (triage only — routing is by branch prefix). The documented sync loop **creates/updates** from the file; it does **not** delete. So when you remove a label from the file, also delete it on GitHub: + +```bash +gh label delete "help wanted" --yes +gh label delete npm --yes +gh label delete "github-actions" --yes +``` + +Dependabot labels its PRs `dependencies` only (ecosystem sub-labels were dropped); confirm `.github/dependabot.yml` does not re-add a deleted label before deleting it. + ## Releases release-please opens/updates a `chore: release main` PR on each push to `main`. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md index 995eb329..cffa5b7c 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md @@ -29,15 +29,20 @@ is_draft: true 2. **Branch identity**. Read current head via `git rev-parse --abbrev-ref HEAD`. 3. **Base resolution**. Pick first match: - `base_branch` provided -> use it - - default -> inspect `git symbolic-ref refs/remotes/origin/HEAD`, then candidate list `main`, `master`, `develop`, `staging`; surface the chosen value during validation + - the branch-naming convention in project memory maps the head branch's prefix to a PR target (e.g. `feat/` -> `next`, `hotfix/` -> `main`) -> use that target + - default -> inspect `git symbolic-ref refs/remotes/origin/HEAD`, then candidate list `main`, `master`, `develop`, `staging` + - surface the chosen value and the reason during validation 4. **Collect changes**. Run `git log ..HEAD --pretty=fuller` and `git diff ...HEAD --stat` to summarize commits and impacted files. 5. **Read template**. Load `assets/pull_request.md` and any contributing rules from `assets/CONTRIBUTING.md`. 6. **Fill template**. Generate a concise title and a body that follows the template structure, using the change summary from step 4. 7. **Validate with user**. Show title, body, and detected base branch. Apply `template_overrides` when provided. Wait for explicit user approval. 8. **Open draft**. Invoke the configured VCS tool to create the request as a draft, passing base, title, and body. Capture the returned URL and number. -9. **Return** the structured Outputs block. +9. **Set triage label**. When the branch-naming convention maps the head branch's prefix to a triage label (e.g. `feat/` -> `enhancement`, `fix/` -> `bug`) and that label exists in the repo, apply it. Skip silently when there is no mapping or no matching label. Labels triage only; they never change the base resolved in step 3. +10. **Return** the structured Outputs block. ## Test - **Tool view**: querying the configured VCS tool for the created request returns a record where `url` equals `pr_url`, `base` equals the resolved base branch, and the draft flag is true. +- **Prefix routing**: a head branch whose prefix is mapped in project memory resolves `base` to that prefix's target (e.g. `feat/*` -> `next`, `hotfix/*` -> `main`), not the `origin/HEAD` default. +- **Triage label**: when the head prefix maps to a triage label that exists in the repo, the created request carries that label. - **Reachable**: the created request is reachable at `pr_url` and lists the head branch as the current branch. diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md b/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md index 2ef27410..70b0c16a 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md +++ b/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md @@ -18,7 +18,7 @@ type/ticket-short-description | ------------ | ------------------------- | | `feat/` | New feature | | `fix/` | Bug fix | -| `aidd_docs/` | Documentation only | +| `docs/` | Documentation only | | `refactor/` | Code change (no feat/fix) | | `chore/` | Build, config, deps | | `test/` | Add/update tests | From e973a0e4264974e13983d748ff414c648b894de4 Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Tue, 23 Jun 2026 21:35:29 +0200 Subject: [PATCH 10/14] fix(aidd-vcs): sync pull-request skill contract with prefix routing (#326) The skill's transversal rules still described base detection from repo state only, omitting the prefix-based routing and auto-labelling the action now performs. Bring the SKILL.md contract in line: base resolves from the branch prefix via project memory (fallback to repo state), and the matching triage label is applied after opening. Co-authored-by: Claude Opus 4.8 (1M context) --- plugins/aidd-vcs/skills/02-pull-request/SKILL.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 4a01ea01..7755da96 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -19,9 +19,10 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph ## Transversal rules -- Detect the base branch from repo state. Do NOT assume `main` or `master` (common alternatives: `develop`, `staging`). +- Resolve the base branch from the head branch's prefix via the project's branch-naming convention (project memory); fall back to repo state when no prefix mapping exists. Never assume `main` or `master` (common alternatives: `next`, `develop`, `staging`). - Always ask the user to validate the title, body, and base branch before creating the request. - Open the request as a draft. The user promotes it manually when ready. +- After opening, apply the triage label the branch prefix maps to, when that label exists; labels triage only, they never change the resolved base. - Never commit, never push the working branch, never create new branches inside this skill. - Tool-agnostic: read the VCS tool from project memory; fall back to inspecting the remote URL. From dcc1eb647d60691a964db967d1554d812048138a Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Wed, 24 Jun 2026 13:46:52 +0200 Subject: [PATCH 11/14] refactor(aidd-refine): align skills with skill contract (#327) * refactor(aidd-refine): align 02-05 skills with skill contract Bring challenge, condense, shadow-areas and fact-check skills to the 04-skill-generate contract and concise, plain language. - SKILL.md routers: `## Actions` header, plain-path references/assets, drop empty None. sections - actions: singular Input/Output, no pipeline-variable notation, bold process labels, no frozen data blocks - move challenge report skeleton to a new assets/report-template.md - extract fact-check output-discipline into a cited reference - shorten the four skill descriptions to two lines Co-Authored-By: Claude Opus 4.8 (1M context) * refactor(aidd-refine): tighten tests and trim duplication Follow-up from a headless skill-by-skill audit against the 04-skill-generate contract. - shadow-areas: collapse redundant Test bullets (6/8/6 -> 5/7/4), one-line Outputs, fix 01-detect handoff (route via 03-diff before 02-render-report when a prior report exists) - challenge: fix Test deal-breaker/confidence rule to match the rubric, drop transversal rules that restated the action - condense: drop persistence-duplicate process step, tighten tests, lean the router (no inline examples) - fact-check: shorten 03-report Output, dedupe caching guidance Co-Authored-By: Claude Opus 4.8 (1M context) * style(aidd-refine): drop punctuation dashes for concise prose Replace em-dash-style " - " punctuation with commas, colons, or parentheses across skill bodies, actions, and references. Keep title headers and the literal "(unverified - no source found)" output marker. Also fix severity-rubric "Definition rule" -> "Decision rule" label. Co-Authored-By: Claude Opus 4.8 (1M context) * fix(aidd-refine): harden condense and fact-check fidelity Found by the behavioral eval harness running the skills for real. - fact-check: add a `refuted` verdict (a source contradicts the claim, distinct from "no source found"); emit the unverified marker verbatim; forbid leaking the verification method (commands, "by inspection"); remove "cascade exhausted ..." from the report template, which leaked a forbidden word the discipline bans - condense: 01-condense must emit the exact `Condense: ON ().` line, since 02-stats and the hook parse it from the transcript * test(aidd-refine): add behavioral skill-eval harness Runs each refine skill for real through a headless `claude -p` in an isolated temp project (the worktree skill installed under a unique name, so the local copy runs, never a stale global plugin). Deterministic checks by default; `--judge` adds an LLM grader for fuzzy outcomes. Local / opt-in only (metered, no `claude` in CI), so not a CI gate. Covers shadow-areas, fact-check, condense, challenge; brainstorm is interactive and out of scope. --------- Co-authored-by: Claude Opus 4.8 (1M context) --- plugins/aidd-refine/CATALOG.md | 10 +- .../aidd-refine/skills/02-challenge/SKILL.md | 20 +-- .../02-challenge/actions/01-challenge.md | 40 ++--- .../02-challenge/assets/report-template.md | 14 ++ .../aidd-refine/skills/03-condense/SKILL.md | 24 ++- .../skills/03-condense/actions/01-condense.md | 35 ++--- .../skills/03-condense/actions/02-stats.md | 41 ++--- .../skills/04-shadow-areas/SKILL.md | 26 ++-- .../04-shadow-areas/actions/01-detect.md | 45 ++---- .../actions/02-render-report.md | 61 +++----- .../skills/04-shadow-areas/actions/03-diff.md | 43 ++---- .../04-shadow-areas/references/categories.md | 2 +- .../04-shadow-areas/references/probe-style.md | 18 +-- .../references/severity-rubric.md | 4 +- .../aidd-refine/skills/05-fact-check/SKILL.md | 26 ++-- .../actions/01-identify-claims.md | 29 ++-- .../skills/05-fact-check/actions/02-verify.md | 40 ++--- .../skills/05-fact-check/actions/03-report.md | 52 ++----- .../05-fact-check/assets/report-template.md | 9 +- .../references/claim-categories.md | 8 +- .../references/report-output-discipline.md | 25 ++++ .../references/verification-cascade.md | 17 ++- scripts/skill-eval.mjs | 140 ++++++++++++++++++ scripts/skill-eval/README.md | 78 ++++++++++ scripts/skill-eval/cases.json | 69 +++++++++ 25 files changed, 526 insertions(+), 350 deletions(-) create mode 100644 plugins/aidd-refine/skills/02-challenge/assets/report-template.md create mode 100644 plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md create mode 100644 scripts/skill-eval.mjs create mode 100644 scripts/skill-eval/README.md create mode 100644 scripts/skill-eval/cases.json diff --git a/plugins/aidd-refine/CATALOG.md b/plugins/aidd-refine/CATALOG.md index 153d6edd..8f7cb4f7 100644 --- a/plugins/aidd-refine/CATALOG.md +++ b/plugins/aidd-refine/CATALOG.md @@ -50,9 +50,10 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | Group | File | Description | |-------|------|---| | `actions` | [01-challenge.md](skills/02-challenge/actions/01-challenge.md) | - | +| `assets` | [report-template.md](skills/02-challenge/assets/report-template.md) | - | | `-` | [README.md](skills/02-challenge/README.md) | - | | `references` | [confidence-rubric.md](skills/02-challenge/references/confidence-rubric.md) | - | -| `-` | [SKILL.md](skills/02-challenge/SKILL.md) | `Rethink prior work to verify correctness against an agreed plan, classifying findings as deal-breakers, suggestions, or correct, with a confidence score. Use when the user says "challenge this", "rethink your plan", "is this correct", "review my last decision", "challenge my decision", "challenge what you did", "is my decision right", "criticize this", "find flaws", or asks for a critical review of just-completed work. Do NOT use for line-by-line code review against a style guide, implementing features, writing tests, or generating new code.` | +| `-` | [SKILL.md](skills/02-challenge/SKILL.md) | `Rethink just-completed work against an agreed plan, classify findings as deal-breakers, suggestions, or correct, with a confidence score. Use to challenge a decision, criticize, or critically review recent work; not for line-by-line style review or writing code.` | #### `skills/03-condense` @@ -62,7 +63,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-stats.md](skills/03-condense/actions/02-stats.md) | - | | `-` | [README.md](skills/03-condense/README.md) | - | | `references` | [intensity-levels.md](skills/03-condense/references/intensity-levels.md) | - | -| `-` | [SKILL.md](skills/03-condense/SKILL.md) | `Toggle terse output mode with intensity levels (lite, full, ultra) so prose drops articles, filler, and pleasantries while code, quoted errors, and security warnings stay verbatim. Also reports real token usage and estimated savings under condense mode for the current session. Use when the user says "condense", "condense output", "be more concise", "shorter answers", "tighten output", "/condense", "/condense full", "/condense ultra", "stop condense", "normal mode", "/condense-stats", "how much have we saved", or "token savings". Do NOT use for editing existing prose, summarizing a long document, or compressing source code (only output style is affected, not content).` | +| `-` | [SKILL.md](skills/03-condense/SKILL.md) | `Toggle terse output mode (lite, full, ultra) that drops filler while code, errors, and warnings stay verbatim, and report token savings for the session. Use to condense output, shorten answers, switch intensity, or check savings; not for editing prose or compressing code.` | #### `skills/04-shadow-areas` @@ -77,7 +78,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [locked-sets.json](skills/04-shadow-areas/references/locked-sets.json) | - | | `references` | [probe-style.md](skills/04-shadow-areas/references/probe-style.md) | - | | `references` | [severity-rubric.md](skills/04-shadow-areas/references/severity-rubric.md) | - | -| `-` | [SKILL.md](skills/04-shadow-areas/SKILL.md) | `Analytical scan of a markdown artifact (idea, user-stories, PRD, spec) to surface blind spots - unstated assumption, missing actor, missing failure mode, ambiguous term, missing acceptance criterion, missing edge case, and missing dependency - emitting a structured shadow report grouped by category and sorted by severity. Use when the user says "find blind spots in this spec", "what's missing in this PRD", "shadow report", "shadow analysis", "scan for gaps", "find what's missing", "spot blind spots", "review for gaps", or asks for an analytical gap scan of a written artifact. Do NOT use for interactive clarification through iterative Q&A (use aidd-refine:01-brainstorm for that), implementing features, writing tests, or reviewing code style.` | +| `-` | [SKILL.md](skills/04-shadow-areas/SKILL.md) | `Scan a markdown artifact (idea, user stories, PRD, spec) for blind spots and emit a structured shadow report grouped by category and sorted by severity. Use to find gaps, missing parts, or what's missing in a written artifact; not for interactive Q&A (use aidd-refine:01-brainstorm) or code review.` | #### `skills/05-fact-check` @@ -89,6 +90,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [report-template.md](skills/05-fact-check/assets/report-template.md) | - | | `-` | [README.md](skills/05-fact-check/README.md) | - | | `references` | [claim-categories.md](skills/05-fact-check/references/claim-categories.md) | - | +| `references` | [report-output-discipline.md](skills/05-fact-check/references/report-output-discipline.md) | - | | `references` | [verification-cascade.md](skills/05-fact-check/references/verification-cascade.md) | - | -| `-` | [SKILL.md](skills/05-fact-check/SKILL.md) | `Verify factual claims in a piece of text against authoritative sources and rewrite it with footnote citations, hedging any claim that cannot be confirmed. Runs a cheapest-first verification cascade (project memory and docs, then codebase inspection, then web lookup) and reports both sources when they disagree. Use when the user says "fact-check this", "verify that claim", "are you sure about that", "is that actually true", "cite your sources", "where did you get that fact", "did you make that up", "double-check the version you gave me", "vérifie cette information", or "es-tu sûr de ça". Do NOT use to auto-guard the AI's own output (this skill only fires on an explicit request), to judge code logic correctness, or to clarify vague requirements through iterative Q&A - use `aidd-refine:01-brainstorm` for that.` | +| `-` | [SKILL.md](skills/05-fact-check/SKILL.md) | `Verify factual claims in a text against authoritative sources and rewrite it with footnote citations, hedging anything unconfirmed. Use to fact-check, verify a claim, or cite sources on explicit request; not for judging code logic or clarifying vague requirements (use aidd-refine:01-brainstorm).` | diff --git a/plugins/aidd-refine/skills/02-challenge/SKILL.md b/plugins/aidd-refine/skills/02-challenge/SKILL.md index 0a51675a..053694b9 100644 --- a/plugins/aidd-refine/skills/02-challenge/SKILL.md +++ b/plugins/aidd-refine/skills/02-challenge/SKILL.md @@ -1,17 +1,17 @@ --- name: 02-challenge -description: Rethink prior work to verify correctness against an agreed plan, classifying findings as deal-breakers, suggestions, or correct, with a confidence score. Use when the user says "challenge this", "rethink your plan", "is this correct", "review my last decision", "challenge my decision", "challenge what you did", "is my decision right", "criticize this", "find flaws", or asks for a critical review of just-completed work. Do NOT use for line-by-line code review against a style guide, implementing features, writing tests, or generating new code. +description: Rethink just-completed work against an agreed plan, classify findings as deal-breakers, suggestions, or correct, with a confidence score. Use to challenge a decision, criticize, or critically review recent work; not for line-by-line style review or writing code. --- # Challenge Rethink prior work and surface what is wrong, missing, or duplicated. Output a structured report with a confidence score so the user knows whether to ship, iterate, or rework. -## Available actions +## Actions | # | Action | Role | Input | | --- | ----------- | ------------------------------------------------------------- | ------------------------------ | -| 01 | `challenge` | Rethink prior work, classify findings, score confidence | review_target + agreed_plan | +| 01 | `challenge` | Rethink prior work, classify findings, score confidence | the work + agreed reference | ## Default flow @@ -19,20 +19,14 @@ Single action skill. The router dispatches to `challenge` whenever the trigger p ## Transversal rules -- Think in first principles. Every step must be logical, with no gap and no missing information. -- Challenge own assumptions and the user's decisions before declaring confidence. -- Look for edge cases, errors, inconsistencies, missing parts, duplications, and optimizations. +- Reason from first principles, no logical gaps. - Aim for simplifications. If the work can be smaller, say so. -- Output the structured report verbatim per the action's `## Outputs` block. +- Fill `assets/report-template.md` verbatim. ## References -- `@references/confidence-rubric.md`: tiered rubric for the confidence percentage. +- `references/confidence-rubric.md`: tiered rubric for the confidence percentage. ## Assets -- None. - -## External data - -- None. +- `assets/report-template.md`: findings report skeleton, filled per run. diff --git a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md index eae6932b..b7167e1a 100644 --- a/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md +++ b/plugins/aidd-refine/skills/02-challenge/actions/01-challenge.md @@ -2,39 +2,25 @@ Rethink prior work and verify correctness against an agreed plan, then emit a structured findings report. -## Inputs +## Input -- `review_target` (required): what to review. One of: last assistant turn, specific file paths, plan document, or commit range. -- `agreed_plan` (required): the prior agreement, specification, or set of requirements to compare against. +- The work to review: the last answer, specific files, a plan, or a commit range. +- The agreed reference to judge it against: a plan, a spec, or stated requirements. Without one, judge against stated user intent. -## Outputs +## Output -```text -My confidence level of correctness now: XX% - -# Previous work to review - -# Correctness (100%) -- - -# Deal breakers -- - -# Suggestions (enhancements only) -- -``` +The findings report following `@../assets/report-template.md`: a confidence percentage plus the Correctness, Deal breakers, and Suggestions sections. ## Process -1. Read `review_target` and align it against `agreed_plan`. -2. Challenge own assumptions and the user's decisions. -3. Scan for edge cases, errors, gaps, duplications, and inconsistencies. -4. Classify each finding as Correctness, Deal breaker, or Suggestion. -5. Score confidence per the rubric in `references/confidence-rubric.md`. -6. Emit the Output report verbatim. +1. **Align.** Read the work and line it up against the agreed reference. +2. **Challenge.** Challenge own assumptions and the user's decisions. +3. **Scan.** Scan for edge cases, errors, gaps, duplications, and inconsistencies. +4. **Classify.** Classify each finding as Correctness, Deal breaker, or Suggestion. +5. **Score.** Score confidence per the rubric in `@../references/confidence-rubric.md`. +6. **Emit.** Fill `@../assets/report-template.md` verbatim and emit it. ## Test -- The emitted report contains a confidence percentage and the three classification sections. -- `confidence >= 95%` if and only if the Deal breakers section is empty. -- The confidence value sits in the rubric tier consistent with the findings. +- The report has a confidence percentage and the Correctness, Deal breakers, and Suggestions sections. +- The Deal breakers section is non-empty only when confidence is below 75%. diff --git a/plugins/aidd-refine/skills/02-challenge/assets/report-template.md b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md new file mode 100644 index 00000000..e7b0af23 --- /dev/null +++ b/plugins/aidd-refine/skills/02-challenge/assets/report-template.md @@ -0,0 +1,14 @@ + + +My confidence level of correctness now: XX% + +# Previous work to review + +# Correctness (100%) +- + +# Deal breakers +- + +# Suggestions (enhancements only) +- diff --git a/plugins/aidd-refine/skills/03-condense/SKILL.md b/plugins/aidd-refine/skills/03-condense/SKILL.md index 70173e0e..93ea005f 100644 --- a/plugins/aidd-refine/skills/03-condense/SKILL.md +++ b/plugins/aidd-refine/skills/03-condense/SKILL.md @@ -1,6 +1,6 @@ --- name: 03-condense -description: Toggle terse output mode with intensity levels (lite, full, ultra) so prose drops articles, filler, and pleasantries while code, quoted errors, and security warnings stay verbatim. Also reports real token usage and estimated savings under condense mode for the current session. Use when the user says "condense", "condense output", "be more concise", "shorter answers", "tighten output", "/condense", "/condense full", "/condense ultra", "stop condense", "normal mode", "/condense-stats", "how much have we saved", or "token savings". Do NOT use for editing existing prose, summarizing a long document, or compressing source code (only output style is affected, not content). +description: Toggle terse output mode (lite, full, ultra) that drops filler while code, errors, and warnings stay verbatim, and report token savings for the session. Use to condense output, shorten answers, switch intensity, or check savings; not for editing prose or compressing code. argument-hint: condense | stats --- @@ -8,12 +8,12 @@ argument-hint: condense | stats Toggles a terse output mode with three intensity levels (lite, full, ultra). Strips articles, filler, and pleasantries from prose while preserving technical substance, code blocks, quoted errors, and security warnings. -## Available actions +## Actions | # | Action | Role | Input | | --- | ---------- | --------------------------------------------------------------------- | ------------------------------------ | -| 01 | `condense` | Toggle terse mode and apply intensity rules | current_state + requested_intensity | -| 02 | `stats` | Report real token usage and estimated savings for the current session | session log + intensity timeline | +| 01 | `condense` | Toggle terse mode and apply intensity rules | current state + requested level | +| 02 | `stats` | Report real token usage and estimated savings for the current session | session messages + level timeline | ## Default flow @@ -25,24 +25,18 @@ Router dispatches by intent: ## Transversal rules - **Persistence**: once active, terse mode applies to EVERY response until explicitly turned off. Do not drift back to verbose prose after many turns, when uncertain, or when the task changes. The level remains active for the rest of the session unless changed or stopped. -- **Off switch**: terse mode stops only on explicit user signal - `stop condense`, `normal mode`, `/condense off`, or invoking the skill again to toggle. +- **Off switch**: terse mode stops only on explicit user signal: `stop condense`, `normal mode`, `/condense off`, or invoking the skill again to toggle. - **Toggle**: invoking the skill while active toggles it off; invoking while off turns it on at the default level (`full`) unless an explicit intensity is given. - **Drop fluff**: drop articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), and hedging. Fragments are acceptable. - **Short synonyms**: prefer short words (big not extensive, fix not "implement a solution for"). Technical terms stay exact. Code blocks are unchanged. Errors are quoted verbatim. - **Pattern**: `[thing] [action] [reason]. [next step].` - - Bad: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..." - - Good: "Bug in auth middleware. Token expiry check uses `<` not `<=`. Fix:" -- **Auto-pause** (drop terse mode for these passages, then resume): security warnings, irreversible action confirmations, multi-step sequences where fragment order or omitted conjunctions risk misread, compression itself creating technical ambiguity, user asks to clarify or repeats a question. -- **Boundaries**: code, commits, and pull request bodies are written in normal English regardless of intensity. The intensity level persists until toggled off or until session end. +- **Auto-pause**: drop terse mode for the passages listed in `references/intensity-levels.md` (security warnings, irreversible confirmations, ambiguity risks), then resume. +- **Boundaries**: code, commits, and pull request bodies are written in normal English regardless of intensity. ## References -- `@references/intensity-levels.md`: detailed per-level rules and side-by-side examples. - -## Assets - -- None. +- `references/intensity-levels.md`: detailed per-level rules and side-by-side examples. ## External data -- `../hooks/condense-stats.js` - UserPromptSubmit hook that intercepts stats triggers, reads the session transcript, and returns the formatted savings report without invoking the model. +- `../hooks/condense-stats.js`: UserPromptSubmit hook that intercepts stats triggers, reads the session transcript, and returns the formatted savings report without invoking the model. diff --git a/plugins/aidd-refine/skills/03-condense/actions/01-condense.md b/plugins/aidd-refine/skills/03-condense/actions/01-condense.md index b5892323..dbdf45bb 100644 --- a/plugins/aidd-refine/skills/03-condense/actions/01-condense.md +++ b/plugins/aidd-refine/skills/03-condense/actions/01-condense.md @@ -2,39 +2,26 @@ Toggle terse output mode and apply the requested intensity rules to subsequent prose turns. -## Inputs +## Input -- `current_state` (required): inferred from session context. Either `on` (with current intensity level) or `off`. -- `requested_intensity` (required): one of `lite`, `full`, `ultra`, or `toggle` to flip the current state. +- Whether condense is currently on (and at which level) or off, read from session context. +- The requested change: a level (lite, full, ultra) or a plain on/off toggle. -## Outputs +## Output -```text -Condense: ON (full). -Articles dropped, filler removed. Code, errors, warnings stay verbatim. Stop with "stop condense" or "normal mode". -``` - -Or on off: - -```text -Condense: OFF. -Normal prose resumed. -``` +A single confirmation line: `Condense: ON ().` when enabling, or `Condense: OFF.` when disabling. ## Process -1. Detect the toggle command and target intensity from the user message. -2. Resolve the new state by combining `current_state` with `requested_intensity`: +1. **Detect.** Read the toggle command and target level from the user message. +2. **Resolve.** Combine the current state with the request: - Explicit level (`lite | full | ultra`) sets that level (or switches level if already on). - `toggle` flips on/off; default level when turning on is `full`. - Off phrases (`stop condense`, `normal mode`, `/condense off`) force off. -3. Emit the confirmation block with the resolved state filled in. -4. Apply the transversal rules to every subsequent prose turn until the next off signal, using per-level rules from `@../references/intensity-levels.md`. -5. **Hold persistence.** Do not drift back to verbose prose across many turns, when uncertain, or when the topic changes. Auto-pause only for the specific passages listed in the reference. +3. **Emit.** The reply MUST begin with this exact line, filled in and unaltered: `Condense: ON ().` when enabling, or `Condense: OFF.` when disabling. The stats action and the hook parse this line from the transcript, so never paraphrase, decorate, or omit it. +4. **Apply.** Apply the transversal rules to every subsequent prose turn until the next off signal, using per-level rules and auto-pause passages from `@../references/intensity-levels.md`. ## Test -- After turning condense ON: the next non-code, non-warning assistant turn drops articles consistent with the active intensity. -- After turning condense OFF: the next assistant turn returns to normal prose. -- Code blocks, quoted errors, and security warnings remain verbatim regardless of condense state. -- After 5 consecutive turns post-activation: the terse style is still applied (no drift back to verbose). +- After ON, the next non-code, non-warning turn drops articles at the active intensity; after OFF, it returns to normal prose. +- Code blocks, quoted errors, and security warnings stay verbatim regardless of state. diff --git a/plugins/aidd-refine/skills/03-condense/actions/02-stats.md b/plugins/aidd-refine/skills/03-condense/actions/02-stats.md index 031e3073..135f27ee 100644 --- a/plugins/aidd-refine/skills/03-condense/actions/02-stats.md +++ b/plugins/aidd-refine/skills/03-condense/actions/02-stats.md @@ -1,42 +1,25 @@ # 02 - Stats -Show real token usage and estimated savings for the current session under condense mode. +Show real token usage and estimated savings for the current session under condense mode. On Claude Code the bundled `hooks/condense-stats.js` hook owns this path; the model runs the steps below only on tools without hook support. -## Inputs +## Input -- Session log of the current AI tool (assistant messages produced since session start). -- Active intensity level and its on/off transitions during the session. +- The session's assistant messages since it started. +- The active level and every on/off switch during the session. -## Outputs +## Output -```text -Condense session stats ----------------------- -Mode: ON (full) -Active turns: 18 / 32 (56%) -Tokens out (active): 4,210 -Tokens out (off): 5,830 -Avg saved / turn: ~38% (vs unmodified prose baseline) -Approx total saved: ~2,650 tokens - -Top savings: full (-42%), ultra (-58%), lite (-18%). -``` +A stats block reporting, in order: mode, active turns and ratio, tokens out while active, tokens out while off, average saved per turn versus the unmodified baseline, approximate total saved, and per-level top savings. ## Process -1. **Read the session log** for the current AI tool (Claude Code: the active session JSONL; other tools: their equivalent transcript). -2. **Detect intensity transitions** by scanning assistant messages for the confirmation block emitted by `01-condense` (`Condense: ON (...)` / `Condense: OFF`). Build a timeline of `(turn_index, level)` segments. -3. **Tokenize each assistant message.** Use the AI tool's token counter when available, otherwise approximate at 4 chars per token. -4. **Compute the baseline.** For each `active` segment, estimate the verbose-prose baseline using the level's compression ratio (`lite ~18%`, `full ~38%`, `ultra ~58%` - published averages, replaceable by measured ratios when available). -5. **Render the report block** with the exact field order shown in `## Outputs`. Round percentages to whole numbers; round token counts to the nearest 10. +1. **Read.** Load the session log for the current AI tool (Claude Code: the active session JSONL; other tools: their equivalent transcript). +2. **Detect.** Scan assistant messages for the confirmation line emitted by `01-condense` (`Condense: ON (...)` / `Condense: OFF`). Build a timeline of `(turn_index, level)` segments. +3. **Tokenize.** Count tokens per assistant message. Use the AI tool's token counter when available, otherwise approximate at 4 chars per token. +4. **Compute.** For each `active` segment, estimate the verbose-prose baseline using the level's compression ratio (`lite ~18%`, `full ~38%`, `ultra ~58%`, published averages, replaceable by measured ratios when available). +5. **Render.** Emit the report with the exact field order shown in `## Output`. Round percentages to whole numbers; round token counts to the nearest 10. 6. **Stop.** Do not invoke any other action. -## Implementation - -A `UserPromptSubmit` hook bundled with this plugin at `hooks/condense-stats.js` intercepts the trigger phrase, reads the active session transcript, detects intensity transitions emitted by `01-condense`, computes the report, and returns `{ decision: "block", reason: "" }` so the model is not invoked. - -The model only runs this action's inline logic on AI tools that lack hook support; on Claude Code the hook owns the path. - ## Test -The output matches the field order in `## Outputs`, every numeric field is filled (no `-` placeholders), and the active-turns ratio is consistent with the detected intensity transitions in the session. +Output follows the `## Output` field order, every numeric field is filled (no `-`), and the active-turns ratio matches the detected intensity transitions. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md index a6c7fdf4..1def8159 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/SKILL.md @@ -1,6 +1,6 @@ --- name: 04-shadow-areas -description: Analytical scan of a markdown artifact (idea, user-stories, PRD, spec) to surface blind spots - unstated assumption, missing actor, missing failure mode, ambiguous term, missing acceptance criterion, missing edge case, and missing dependency - emitting a structured shadow report grouped by category and sorted by severity. Use when the user says "find blind spots in this spec", "what's missing in this PRD", "shadow report", "shadow analysis", "scan for gaps", "find what's missing", "spot blind spots", "review for gaps", or asks for an analytical gap scan of a written artifact. Do NOT use for interactive clarification through iterative Q&A (use aidd-refine:01-brainstorm for that), implementing features, writing tests, or reviewing code style. +description: Scan a markdown artifact (idea, user stories, PRD, spec) for blind spots and emit a structured shadow report grouped by category and sorted by severity. Use to find gaps, missing parts, or what's missing in a written artifact; not for interactive Q&A (use aidd-refine:01-brainstorm) or code review. argument-hint: detect | render-report | diff --- @@ -8,7 +8,7 @@ argument-hint: detect | render-report | diff Analytically scans a written artifact for gaps the author has not addressed. Unlike iterative Q&A clarification, this skill reads the existing material and emits a structured report: each gap carries a category from a locked 7-category taxonomy, a 3-tier severity, and a direct-question probe the author can act on immediately. -## Available actions +## Actions | # | Action | Role | Input | | --- | ---------------- | ------------------------------------------------------------------------ | ---------------------------------------- | @@ -28,23 +28,19 @@ The `02-render-report` action always runs last and writes `-shadow-repor ## Transversal rules - Never modify the source artifact. -- Every emitted gap must have all three fields populated: `category`, `severity`, `probe`. -- Every probe must be a direct question ending with `?`. -- Categories and severities must come from the locked sets in `@references/locked-sets.json`. +- Every gap carries all three: a category, a severity, and a probe question. +- Every probe is a direct question ending with `?`. +- Categories and severities come from the locked sets in `references/locked-sets.json`. - When zero blockers and zero majors remain, stamp the report `status: clean`. -- On re-runs, the identity key for diffing is `category + normalized snippet` - not probe wording - so minor probe rephrasing does not create spurious "newly introduced" gaps. +- On re-runs, gaps are matched by category and snippet, never by question wording, so rephrasing a question never creates a spurious "newly introduced" gap. ## References -- `@references/categories.md`: locked 7-category taxonomy with definition and example per category. -- `@references/severity-rubric.md`: blocker / major / minor decision rules and examples. -- `@references/probe-style.md`: direct-question form rules. -- `@references/locked-sets.json`: machine-readable sets reused by the validator. +- `references/categories.md`: locked 7-category taxonomy with definition and example per category. +- `references/severity-rubric.md`: blocker / major / minor decision rules and examples. +- `references/probe-style.md`: direct-question form rules. +- `references/locked-sets.json`: machine-readable sets reused by the validator. ## Assets -- `@assets/report-template.md`: report skeleton with header, per-category sections, and `status: clean` block. - -## External data - -- None. +- `assets/report-template.md`: report skeleton with header, per-category sections, and `status: clean` block. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md b/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md index 8a43dfb2..9460c674 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/actions/01-detect.md @@ -1,41 +1,28 @@ # 01 - Detect -Parse the source artifact and extract a structured list of gaps, each classified by category, severity, and direct-question probe. +Parse the source artifact and pull out a list of gaps, each tagged with a category, a severity, and a direct question. -## Inputs +## Input -- `source` (required): file path OR inline markdown text. - - Accept absolute paths and relative paths inside the working directory. - - Reject paths outside the working directory and filenames matching `*-shadow-report.md`. +- The source to scan: a file path or inline markdown text. -## Outputs +## Output -Two arrays: - -1. `gaps[]`: each entry has `category`, `severity`, `probe`, and optional `snippet`. - - `category` ∈ the 7 locked categories in `references/locked-sets.json`. - - `severity` ∈ `{blocker, major, minor}` (see `references/severity-rubric.md`). - - `probe`: direct question ending with `?` (see `references/probe-style.md`). - - `snippet`: quoted excerpt from the source when traceable. - -2. `warnings[]`: top-of-report notes that are not gap entries (e.g. non-markdown source). +A list of gaps, each with its category, severity, a probe question, and the quoted snippet it came from, plus any top-of-report warnings such as a non-markdown source. ## Process -1. Load locked sets from `references/locked-sets.json` and category definitions from `references/categories.md`. -2. Validate the source. Reject per the rules in Inputs. -3. Edge cases: - - Empty source → emit one blocker gap `{category: "missing acceptance criterion", probe: "What content should this artifact contain?"}` and stop. - - Non-markdown source → append warning `"Source is not markdown; gap attribution may be imprecise."` and continue. -4. Scan content for each of the 7 categories in their locked order. Emit one gap per distinct issue found, assigning severity per the rubric and drafting probes per the style rules. -5. Deduplicate by `(category, normalized_snippet)`. Snippet-less gaps fall back to `(category, severity)`. -6. Return `gaps` and `warnings`. Sorting is done by `02-render-report`. +1. **Load.** Read the locked categories and their definitions from `@../references/locked-sets.json` and `@../references/categories.md`. +2. **Validate.** Check the source. Reject anything outside the working directory or already named `*-shadow-report.md`. +3. **Handle edges.** An empty source emits one blocker gap asking what content the artifact should hold, then stops. A non-markdown source adds a warning that attribution may be imprecise, then continues. +4. **Scan.** Walk the seven categories in their locked order. Emit one gap per distinct issue, set its severity from `@../references/severity-rubric.md`, and write its question per `@../references/probe-style.md`. +5. **Dedupe.** Treat two gaps with the same category and snippet as one. A snippet-less gap falls back to its category plus severity. +6. **Return.** Hand the gaps and warnings to the next action: `03-diff` when a prior report exists, else `02-render-report`. Sorting happens there. ## Test -- Outside-tree relative path → error and empty `gaps`. -- Filename matching `*-shadow-report.md` → error and empty `gaps`. -- Empty source → exactly one blocker gap (`missing acceptance criterion`). -- Non-markdown source → one entry in `warnings`, scanning continues. -- Every emitted gap has `category` and `severity` in the locked set and `probe` ending with `?`. -- A duplicated gap (same `category` + normalized `snippet`) appears once in the output. +- A path outside the working directory, or a file named `*-shadow-report.md`, is rejected with no gaps. +- An empty source yields exactly one blocker gap about missing content. +- A non-markdown source adds one warning and keeps scanning. +- Every gap has a category and severity from the locked set and a question ending in `?`. +- A repeated gap (same category and snippet) appears once. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md b/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md index c6d08bd8..16996ce6 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/actions/02-render-report.md @@ -1,50 +1,35 @@ # 02 - Render Report -Render the detected gap list into a structured markdown shadow report and write it next to the source artifact. +Turn the detected gaps into a structured markdown report and write it next to the source. -## Inputs +## Input -- `gaps[]` (required when `diff` is absent): gap objects from `01-detect`. Ignored when `diff` is supplied. -- `warnings[]` (required, may be empty): warnings from `01-detect`. -- `source_path` (required): path used to derive the output filename and directory. -- `diff` (optional): the three labeled sets from `03-diff` — `closed[]`, `still_open[]`, `newly_introduced[]`. Triggers diff mode. +- The gaps and warnings from `01-detect`. +- The source path, used to name and place the report. +- Optional: the three labelled sets from `03-diff` (closed, still open, newly introduced). Their presence switches on diff mode. -## Outputs +## Output -A markdown file at `/-shadow-report.md`. - -Filename rule: strip the last extension from the source filename and append `-shadow-report.md`. Examples: - -| Source | Report | -| --- | --- | -| `prd.md` | `prd-shadow-report.md` | -| `feature-v2.draft.md` | `feature-v2.draft-shadow-report.md` | -| `Makefile` | `Makefile-shadow-report.md` | - -The source artifact is never modified. +A markdown report written next to the source, named by stripping the source's last extension and appending `-shadow-report.md`. ## Process -1. Load the skeleton from `assets/report-template.md`. -2. Derive `source_dir` and `source_stem` per the filename rule. -3. If `warnings` is non-empty, emit `## Warnings` at the top with each entry as a bullet. Otherwise omit the block. -4. Render gaps grouped by category in locked order (`references/locked-sets.json`): - - Non-diff mode: emit one `### ` per category with at least one gap. - - Diff mode: for each category, emit `#### Closed`, `#### Still Open`, `#### Newly Introduced` in that fixed order, omitting empty subsections. -5. Within any subsection, sort gaps by severity: `blocker` → `major` → `minor`. -6. Render each gap as `**[severity]** `. If `snippet` is non-empty, append a blockquote on the next line. -7. Populate header counts: total + per-severity. In diff mode, counts come from `still_open` + `newly_introduced` only. -8. Stamp `status: clean` in front matter when zero `blocker` and zero `major` entries remain in scope. Otherwise omit the `status` key entirely. -9. Write to `/-shadow-report.md`. +1. **Load.** Start from the skeleton in `@../assets/report-template.md`. +2. **Name.** Derive the report's folder and filename from the source per the rule above. +3. **Warn.** If there are warnings, list them under `## Warnings` at the top. Otherwise omit the block. +4. **Group.** Lay gaps out by category in locked order (`@../references/locked-sets.json`). In plain mode, one heading per category that has a gap. In diff mode, split each category into Closed, Still Open, and Newly Introduced, in that order, dropping empty parts. +5. **Sort.** Within a part, order gaps blocker, then major, then minor. +6. **Render.** Write each gap as `**[severity]** `, with its snippet as a blockquote on the next line when present. +7. **Count.** Fill the header totals: overall and per severity. In diff mode, count only still-open and newly-introduced gaps. +8. **Stamp.** Mark the front matter `status: clean` when no blocker and no major remain in scope. Otherwise leave the status out. +9. **Write.** Save the report at the derived path. ## Test -- Grouping: gaps spanning multiple categories produce one `### ` per category, in locked order. -- Sorting: within a category, `blocker` precedes `major` precedes `minor`. -- Filename: source ending in `feature-v2.draft.md` produces `feature-v2.draft-shadow-report.md`. Source `Makefile` produces `Makefile-shadow-report.md`. -- Clean: zero blocker and zero major → front matter contains `status: clean`. -- Dirty: at least one blocker or major → front matter has no `status` key. -- Warnings: non-empty `warnings` → `## Warnings` section emitted. Empty → omitted. -- No source mutation: `source_path` content and mtime unchanged after the action. -- Diff order: when a category has entries in all three subsets, output is `Closed` → `Still Open` → `Newly Introduced`. -- Diff clean: a `blocker` in `closed[]` does not block clean status; only `still_open` + `newly_introduced` count. +- Gaps spanning several categories produce one heading per category, in locked order. +- Within a category, blocker comes before major before minor. +- A source named `feature-v2.draft.md` produces `feature-v2.draft-shadow-report.md`; `Makefile` produces `Makefile-shadow-report.md`. +- Zero blocker and zero major in scope stamps `status: clean`; closed gaps never count toward scope; otherwise no status key. +- Warnings present emits `## Warnings`; none omits it. +- The source content and timestamp are unchanged after the run. +- In diff mode a category with entries in all three parts renders Closed, then Still Open, then Newly Introduced. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/actions/03-diff.md b/plugins/aidd-refine/skills/04-shadow-areas/actions/03-diff.md index f4a290c3..61a4bff6 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/actions/03-diff.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/actions/03-diff.md @@ -1,39 +1,28 @@ # 03 - Diff -Load the prior shadow report, compare it against the freshly detected gaps, and classify each gap as closed, still open, or newly introduced. +Load the prior shadow report, compare it with the freshly detected gaps, and sort each gap into closed, still open, or newly introduced. -## Inputs +## Input -- `current_gaps[]` (required): gap objects from `01-detect` for the current run. -- `source_path` (required): path used to derive the prior report location, applying the filename rule from `02-render-report`. +- The current run's gaps from `01-detect`. +- The source path, used to find the prior report by the same naming rule as `02-render-report`. -## Outputs +## Output -Three labeled sets, passed to `02-render-report`: - -- `closed[]`: gaps present in the prior report but absent from `current_gaps`. -- `still_open[]`: gaps present in both runs. -- `newly_introduced[]`: gaps present in `current_gaps` but absent from the prior report. - -Each entry carries `category`, `severity`, and `probe`. `closed` entries carry the prior probe; `still_open` and `newly_introduced` carry the current probe. +Three labelled sets handed to `02-render-report`: closed (in the prior report, gone now), still open (in both runs), and newly introduced (new this run). ## Process -1. Derive prior report path from `source_path` using the filename rule of `02-render-report`. -2. If the prior report does not exist: emit `closed = []`, `still_open = []`, `newly_introduced = current_gaps`. Stop. This is the expected first-run behavior. -3. Parse the prior report: - - Locate `## Gaps by Category` and walk `### ` subsections. - - Each line matching `**[severity]** ` is a gap; an immediately following blockquote line is its `snippet`. - - Diff-mode subsections (`Closed` / `Still Open` / `Newly Introduced`) are parsed identically. -4. Build identity keys: `(category, normalized_snippet)`. Probe wording is NOT part of the key. Snippet-less gaps fall back to `(category, severity)`. This matches `01-detect`'s dedup rule so identity is consistent between runs. -5. Compute the three sets by set difference / intersection on identity keys. -6. Pass `closed`, `still_open`, `newly_introduced` to `02-render-report`. +1. **Locate.** Derive the prior report's path from the source, same rule as `02-render-report`. +2. **First run.** If no prior report exists, everything is newly introduced and the other two sets are empty. Stop. This is the expected first run. +3. **Parse.** Read the prior report: walk its category sections, treat each `**[severity]** ` line as a gap, and take an immediately following blockquote as its snippet. Diff-mode sections parse the same way. +4. **Match.** Identify gaps by category plus snippet, ignoring question wording, so a reworded question is not seen as new. A snippet-less gap falls back to category plus severity, matching `01-detect`'s dedupe rule so identity stays consistent across runs. +5. **Sort.** Compare the two runs to fill closed, still open, and newly introduced. Each gap keeps its category and severity; closed gaps carry the prior question, the others the current one. +6. **Hand off.** Pass the three sets to `02-render-report`. ## Test -- No change between runs → `closed = []`, all gaps in `still_open`, `newly_introduced = []`. -- A prior gap whose source anchor is removed → appears in `closed`, not in `still_open`. -- A new gap not in the prior report → appears in `newly_introduced`, not in `still_open`. -- First run (no prior report) → `closed = []`, `still_open = []`, all current gaps in `newly_introduced`. No error. -- Probe wording change with same category + snippet → classified as `still_open` (probe wording is not part of identity). -- Snippet-less gaps with identical `(category, severity)` across runs → classified as `still_open`. +- No change between runs: every gap is still open, closed and newly introduced empty. +- A prior gap whose anchor is gone lands in closed; a gap absent from the prior report lands in newly introduced. +- First run with no prior report: every current gap is newly introduced, the rest empty, no error. +- A reworded question, or a snippet-less gap with the same category and severity, stays still open (gaps match by category and snippet, not wording). diff --git a/plugins/aidd-refine/skills/04-shadow-areas/references/categories.md b/plugins/aidd-refine/skills/04-shadow-areas/references/categories.md index 4e865dde..14383274 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/references/categories.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/references/categories.md @@ -38,7 +38,7 @@ The 7 locked categories below come from `references/locked-sets.json`. No other ## missing actor -**Definition**: An entity - person, system, or role - that takes an action or is affected by the system is absent from the document. The process cannot be fully traced without naming it. +**Definition**: An entity (person, system, or role) that takes an action or is affected by the system is absent from the document. The process cannot be fully traced without naming it. **Positive example**: A user-story describes the approval workflow: a request is submitted, reviewed, and approved. The document names the requester but never names the reviewer role or what system sends the approval notification. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/references/probe-style.md b/plugins/aidd-refine/skills/04-shadow-areas/references/probe-style.md index 7fbf280f..bce1c07b 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/references/probe-style.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/references/probe-style.md @@ -11,7 +11,7 @@ Rules for writing direct-question probes. The locked question forms come from `r 1. Each probe begins with a question form from the locked list: `what`, `when`, `who`, `which`, `how`, `why`, `where`, `does`, `can`, `will`, `should`, `is`, `are`, `do`. 2. Each probe ends with `?`. 3. Each probe targets one specific gap. Do not combine two questions into a single probe. -4. The probe names the specific subject (role, field, condition, term) - not the artifact or a generic concept. +4. The probe names the specific subject (role, field, condition, term), not the artifact or a generic concept. 5. Prefer the shortest question form that makes the gap actionable. Avoid preamble. --- @@ -20,11 +20,11 @@ Rules for writing direct-question probes. The locked question forms come from `r These probes satisfy all 5 rules. The question form used is noted for clarity. -- `who` - Who is responsible for approving the access request before it is acted on? -- `what` - What should the system return to the caller when the payment provider responds with a timeout? -- `which` - Which user roles are permitted to delete a published record? -- `how` - How is the session invalidated when the user's account is suspended mid-session? -- `does` - Does the 10 MB file-size limit apply to each individual file in a multi-file upload or to the combined total? +- `who`: Who is responsible for approving the access request before it is acted on? +- `what`: What should the system return to the caller when the payment provider responds with a timeout? +- `which`: Which user roles are permitted to delete a published record? +- `how`: How is the session invalidated when the user's account is suspended mid-session? +- `does`: Does the 10 MB file-size limit apply to each individual file in a multi-file upload or to the combined total? --- @@ -32,6 +32,6 @@ These probes satisfy all 5 rules. The question form used is noted for clarity. These examples violate one or more rules. Do not write probes in these forms. -- "The spec is unclear about authentication." - Statement, no question form, does not end with `?`. Describes the problem abstractly instead of asking for the specific missing information. -- "Authentication and authorization both need clarification, and the roles section is incomplete." - Combines multiple targets in one sentence. Breaks rule 3 (one specific gap per probe). -- "Could you clarify the access control model?" - Vague subject. Does not identify which part of the access control model is missing or ambiguous. Breaks rule 4. +- "The spec is unclear about authentication." Statement, no question form, does not end with `?`. Describes the problem abstractly instead of asking for the specific missing information. +- "Authentication and authorization both need clarification, and the roles section is incomplete." Combines multiple targets in one sentence. Breaks rule 3 (one specific gap per probe). +- "Could you clarify the access control model?" Vague subject. Does not identify which part of the access control model is missing or ambiguous. Breaks rule 4. diff --git a/plugins/aidd-refine/skills/04-shadow-areas/references/severity-rubric.md b/plugins/aidd-refine/skills/04-shadow-areas/references/severity-rubric.md index 0fe42c1d..23dac7cb 100644 --- a/plugins/aidd-refine/skills/04-shadow-areas/references/severity-rubric.md +++ b/plugins/aidd-refine/skills/04-shadow-areas/references/severity-rubric.md @@ -24,7 +24,7 @@ The 3 locked severity tiers below come from `references/locked-sets.json`. Assig ## major -**Decision rule**: The gap does not prevent starting work, but it will cause rework - incomplete implementation, a failed review cycle, or a missed requirement that surfaces during testing. +**Decision rule**: The gap does not prevent starting work, but it will cause rework: incomplete implementation, a failed review cycle, or a missed requirement that surfaces during testing. **When to assign**: - A failure mode is undescribed; it will be discovered during integration or QA and require a code change. @@ -39,7 +39,7 @@ The 3 locked severity tiers below come from `references/locked-sets.json`. Assig ## minor -**Definition rule**: The gap is cosmetic or affects documentation clarity only. Resolving it improves precision or readability but will not change an implementation decision or require rework. +**Decision rule**: The gap is cosmetic or affects documentation clarity only. Resolving it improves precision or readability but will not change an implementation decision or require rework. **When to assign**: - An ambiguous term exists in a non-critical context where both interpretations lead to the same implementation. diff --git a/plugins/aidd-refine/skills/05-fact-check/SKILL.md b/plugins/aidd-refine/skills/05-fact-check/SKILL.md index b09fae28..460737f8 100644 --- a/plugins/aidd-refine/skills/05-fact-check/SKILL.md +++ b/plugins/aidd-refine/skills/05-fact-check/SKILL.md @@ -1,6 +1,6 @@ --- name: 05-fact-check -description: Verify factual claims in a piece of text against authoritative sources and rewrite it with footnote citations, hedging any claim that cannot be confirmed. Runs a cheapest-first verification cascade (project memory and docs, then codebase inspection, then web lookup) and reports both sources when they disagree. Use when the user says "fact-check this", "verify that claim", "are you sure about that", "is that actually true", "cite your sources", "where did you get that fact", "did you make that up", "double-check the version you gave me", "vérifie cette information", or "es-tu sûr de ça". Do NOT use to auto-guard the AI's own output (this skill only fires on an explicit request), to judge code logic correctness, or to clarify vague requirements through iterative Q&A - use `aidd-refine:01-brainstorm` for that. +description: Verify factual claims in a text against authoritative sources and rewrite it with footnote citations, hedging anything unconfirmed. Use to fact-check, verify a claim, or cite sources on explicit request; not for judging code logic or clarifying vague requirements (use aidd-refine:01-brainstorm). argument-hint: identify-claims | verify | report --- @@ -8,7 +8,7 @@ argument-hint: identify-claims | verify | report Verifies the factual claims inside a target text and rewrites it grounded in evidence. The skill extracts each verifiable claim, runs a cheapest-first verification cascade, and emits a rewritten answer where every confirmed claim carries a footnote citation and every unconfirmed claim is explicitly hedged. When sources disagree, both are reported rather than one being silently chosen. -## Available actions +## Actions | # | Action | Role | Input | | --- | ----------------- | ----------------------------------------------------------------------------- | --------------------------- | @@ -22,25 +22,21 @@ Sequential skill: `01 → 02 → 03`. No skipping. The router materializes the t ## Transversal rules -- Never alter the meaning of a claim while verifying it - verify what was stated, not a charitable reinterpretation. -- The verification cascade is cheapest-first and short-circuits: stop at the first tier that resolves a claim. See `@references/verification-cascade.md`. +- Never alter the meaning of a claim while verifying it: verify what was stated, not a charitable reinterpretation. +- The verification cascade is cheapest-first and short-circuits: stop at the first tier that resolves a claim. See `references/verification-cascade.md`. - A web lookup is the last resort, never the first. Reach it only when project memory and codebase inspection both fail to resolve a claim. -- Claim categories come from the locked set in `@references/claim-categories.md`. Opinion, preference, and trivially-known statements are not claims and are skipped. -- When two sources disagree, report both with their origin - never silently pick one. +- Claim categories come from the locked set in `references/claim-categories.md`. Opinion, preference, and trivially-known statements are not claims and are skipped. +- When two sources disagree, report both with their origin, never silently pick one. - An unverified claim is never deleted and never asserted as fact: it is kept and marked `(unverified - no source found)`. -- Caching a verified fact is opt-in: propose it with a recommendation, never cache silently. The skill itself stores nothing - on approval it restates the fact for the user's own memory tooling. Persistence is out of scope. -- The final report is reader-facing prose - the corrected text, `## Sources`, and `## Unverified claims`, nothing else. Internal mechanics never appear in the output: no cascade or tier trace (`Cascade:`, `tier 1/2/3`, `miss`, `resolved`), no category labels, no raw verdict words. State conclusions, not the process. Action 03 holds the exhaustive forbidden list. +- Caching a verified fact is opt-in: propose it with a recommendation, never cache silently. The skill persists nothing; the mechanics live in action 03. +- The final report is reader-facing prose: the corrected text, `## Sources`, and `## Unverified claims`, nothing else. Internal mechanics never appear in the output: no cascade or tier trace (`Cascade:`, `tier 1/2/3`, `miss`, `resolved`), no category labels, no raw verdict words. State conclusions, not the process. Action 03 holds the exhaustive forbidden list. - The report is rendered in plain prose and is never restyled by an active session output mode (terse, caveman, condensed). The skill's output format is fixed by action 03 alone. ## References -- `@references/claim-categories.md` - locked taxonomy of verifiable claim categories with definition and example. -- `@references/verification-cascade.md` - the three-tier cascade, short-circuit rule, web-cost guardrail. +- `references/claim-categories.md`: locked taxonomy of verifiable claim categories with definition and example. +- `references/verification-cascade.md`: the three-tier cascade, short-circuit rule, web-cost guardrail. ## Assets -- `@assets/report-template.md` - rewritten-answer skeleton with the `## Sources` footnote block. - -## External data - -- None. +- `assets/report-template.md`: rewritten-answer skeleton with the `## Sources` footnote block. diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md b/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md index 07af7644..472c229a 100644 --- a/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md +++ b/plugins/aidd-refine/skills/05-fact-check/actions/01-identify-claims.md @@ -1,30 +1,23 @@ # 01 - Identify claims -Extract every verifiable factual claim from the target text and classify each one. +Pull every verifiable factual claim out of the target text and tag each one. -## Inputs +## Input -- `target_text` (required) - string, the text whose facts must be checked. The user's prior answer, a quoted passage, or an explicitly pasted block. +- The text whose facts need checking: the user's prior answer, a quoted passage, or a pasted block. -## Outputs +## Output -A claim list. Each entry pairs the claim text with one category from the locked taxonomy. - -```json -[ - { "claim": "Next.js 15 shipped the use cache directive in 2024", "category": "version" }, - { "claim": "the file aidd_docs/memory/architecture.md exists in this repo", "category": "project-fact" } -] -``` +A list of claims, each paired with one category from the locked taxonomy. ## Process -1. Read `target_text` sentence by sentence. -2. For each sentence, decide: does it assert a fact? Split a mixed sentence into its factual part and its opinion part. -3. Drop every non-claim per `@../references/claim-categories.md` - opinion, preference, trivially-known general knowledge, the AI's own intent. -4. Assign each surviving claim exactly one category from the locked taxonomy. When two categories fit, prefer the one routing to the cheapest tier (`project-fact` over `hard-to-know` for repo claims). -5. Emit the claim list. If the list is empty, report "no verifiable claims" and stop the skill. +1. **Read.** Go through the text sentence by sentence. +2. **Decide.** For each sentence, ask whether it states a fact. Split a mixed sentence into its factual part and its opinion part. +3. **Drop.** Discard every non-claim per `@../references/claim-categories.md`: opinion, preference, trivially-known general knowledge, the AI's own intent. +4. **Tag.** Give each surviving claim one category. When two fit, pick the one routing to the cheapest tier (a repo fact over a hard-to-know fact). +5. **Emit.** Return the claim list. If it is empty, report "no verifiable claims" and stop the skill. ## Test -Run on the text `"Next.js 15 shipped the use cache directive in 2024. This naming is clean."` - the output lists the first sentence as a claim (category `version` or `date-event-person`) and excludes "This naming is clean" as opinion. +- Run on `"Next.js 15 shipped the use cache directive in 2024. This naming is clean."`: the output lists the first sentence as a claim and excludes "This naming is clean" as opinion. diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md b/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md index d7188885..18de9541 100644 --- a/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md +++ b/plugins/aidd-refine/skills/05-fact-check/actions/02-verify.md @@ -1,40 +1,24 @@ # 02 - Verify -Run the cheapest-first verification cascade against each claim and assign it a verdict. +Run the cheapest-first verification cascade against each claim and give it a verdict. -## Inputs +## Input -- `claim_list` (required) - the classified claim list from action 01. +- The tagged claims from `01-identify-claims`. -## Outputs +## Output -A verdict list. Each claim gains a verdict and its supporting sources. - -```json -[ - { - "claim": "the source file plugins/aidd-refine/hooks/condense-stats.js exists in this repo", - "category": "project-fact", - "verdict": "verified", - "tier": "codebase", - "sources": ["plugins/aidd-refine/hooks/condense-stats.js"] - } -] -``` - -## Depends on - -- `01-identify-claims` +A list of verdicts: each claim gains one verdict (verified, refuted, conflict, or unverified) with the sources behind it and the tier that resolved it. ## Process -1. For each claim, walk the cascade in `@../references/verification-cascade.md`: tier 1 project memory and docs, tier 2 codebase inspection, tier 3 web lookup. -2. Route by category - `project-fact` favors tiers 1 and 2; other categories favor tier 1 then tier 3. -3. Short-circuit: the first tier that resolves the claim sets the verdict. Do not consult later tiers. -4. Respect the web-cost guardrail - reach tier 3 only after tiers 1 and 2 fail, prefer one authoritative source, stop once resolved. -5. Assign exactly one verdict: `verified` (record every source), `conflict` (record both sides with origin, pick no winner), or `unverified` (cascade exhausted, no source). -6. Emit the verdict list. +1. **Walk.** For each claim, walk the cascade in `@../references/verification-cascade.md`: first project memory and docs, then codebase inspection, then web lookup. +2. **Route.** Send repo facts to memory and codebase first; send other claims to memory then the web. +3. **Short-circuit.** The first tier that resolves a claim sets its verdict. Do not consult later tiers. +4. **Guard.** Reach the web only after memory and codebase both fail. Prefer one authoritative source, and stop once resolved. +5. **Judge.** Give each claim one verdict: verified (record every source), refuted (a source contradicts the claim, record it), conflict (record both sides with their origin, pick no winner), or unverified (cascade exhausted, no source). +6. **Emit.** Return the verdict list. ## Test -Run on the single claim `"the source file plugins/aidd-refine/hooks/condense-stats.js exists in this repo"` - the cascade resolves at the codebase tier (tier 2), the verdict is `verified`, the source is that file path, and the web tier is never reached. +- Run on `"the source file plugins/aidd-refine/hooks/condense-stats.js exists in this repo"`: the cascade resolves at the codebase tier, the verdict is verified, the source is that file path, and the web tier is never reached. diff --git a/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md b/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md index 887a613b..e1c41cff 100644 --- a/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md +++ b/plugins/aidd-refine/skills/05-fact-check/actions/03-report.md @@ -1,49 +1,27 @@ # 03 - Report -Rewrite the original text grounded in the verdicts: cite verified claims, hedge unverified ones, surface conflicts. The output is reader-facing prose only. +Rewrite the original text on the evidence: cite verified claims, hedge unverified ones, surface conflicts. The output is reader-facing prose only. -## Output discipline (hard constraint - read first) +## Input -The delivered output contains EXACTLY these blocks, in this order, and nothing else: +- The verdicts from `02-verify`. +- The original text, reused as the base for the rewrite. -1. The rewritten text, with a `[n]` marker on each verified claim and a `(unverified - no source found)` marker on each unverified claim. -2. A `## Sources` block. -3. A `## Unverified claims` block - only when at least one claim is unverified. +## Output -The following are internal to actions 01 and 02. They are FORBIDDEN in the output - never write them: - -- Any cascade or tier trace. Never emit the words `Cascade`, `tier 1`, `tier 2`, `tier 3`, `miss`, `N/A`, or `resolved` in the output. -- Any category label - `hard-to-know`, `version`, `api-signature`, `date-event-person`, `project-fact`. -- Any raw verdict vocabulary - `verdict`, `claim false`, `claim true`, or the enum values `verified` / `conflict` / `unverified` used as a status word (the inline `(unverified - no source found)` marker is the one allowed exception). -- Any sentence explaining why a cache line was or was not added. -- The report is plain prose. It is NOT styled by any active session output mode (terse, caveman, condensed, etc.). Render it normally regardless of how the surrounding conversation is styled. - -Before delivering, scan the draft: if any line contains a forbidden item, delete that line. - -## Inputs - -- `verdict_list` (required) - the verdict list from action 02. -- `target_text` (required) - the original text, reused as the rewrite base. - -## Outputs - -The rewritten answer following `@../assets/report-template.md`: original content preserved, a `[n]` marker on each verified claim, a `(unverified - no source found)` marker on each unverified claim, conflicts stated with both sides, and a `## Sources` footnote block. - -## Depends on - -- `02-verify` +The rewritten answer per `@../assets/report-template.md`, obeying `@../references/report-output-discipline.md`. ## Process -1. Copy `@../assets/report-template.md` as the structure. -2. Rewrite `target_text`: append `[n]` to each `verified` claim, numbered in reading order. -3. For each `conflict`, state both sides in full ("Source A reports X; source B reports Y") - choose no winner. -4. Append `(unverified - no source found)` to each `unverified` claim; never delete it, never assert it. -5. Build the `## Sources` block - one numbered entry per source, with title or file path, location, and the claim it verifies. Conflicts get one entry per side. -6. Add the `## Unverified claims` section only when at least one claim is unverified; omit it otherwise. -7. If any verified fact is stable (project paths, pinned-version APIs), append a single cache-suggestion line proposing the user cache it, with a yes/no recommendation. The skill persists nothing itself: on approval, restate the fact and its source plainly so the user (or their memory tooling) can store it. When no fact qualifies, omit the line silently - never explain its absence. -8. Apply the Output discipline scan above, then deliver. +1. **Copy.** Start from `@../assets/report-template.md`. +2. **Rewrite.** Carry the original text over, appending `[n]` to each verified claim, numbered in reading order. Replace each refuted claim with the corrected fact and cite the contradicting source `[n]`; never restate the false claim as true. +3. **Surface.** For each conflict, state both sides in full ("Source A reports X; source B reports Y"), choosing no winner. +4. **Mark.** Append the exact marker `(unverified - no source found)`, verbatim and unreworded, to each unverified claim. Never delete it, never assert it. +5. **Cite.** Build the `## Sources` block: one numbered entry per source, with its title or file path, location, and the claim it backs. Each side of a conflict gets its own entry. +6. **List.** Add the `## Unverified claims` section only when at least one claim is unverified; otherwise omit it. +7. **Suggest.** When a verified fact is stable (project paths, pinned-version APIs), append one cache-suggestion line with a yes/no recommendation. The skill stores nothing itself: on approval, restate the fact and its source so the user's own memory tooling can keep it. When nothing qualifies, omit the line silently. +8. **Scrub.** Apply `@../references/report-output-discipline.md`, then deliver. ## Test -Given one `verified` claim and one `unverified` claim, the rendered output contains a `## Sources` section with a `[1]` footnote for the verified claim and an inline `(unverified - no source found)` marker on the other, and contains none of the forbidden words (`Cascade`, `tier 1/2/3`, `verdict`, category labels). +- Given one verified claim and one unverified claim, the output carries a `## Sources` section with a `[1]` footnote for the verified claim, an inline `(unverified - no source found)` marker on the other, and none of the forbidden words from `@../references/report-output-discipline.md`. diff --git a/plugins/aidd-refine/skills/05-fact-check/assets/report-template.md b/plugins/aidd-refine/skills/05-fact-check/assets/report-template.md index 8389af5f..3387cf29 100644 --- a/plugins/aidd-refine/skills/05-fact-check/assets/report-template.md +++ b/plugins/aidd-refine/skills/05-fact-check/assets/report-template.md @@ -1,8 +1,4 @@ - - - - - + @@ -17,11 +13,10 @@ ## Unverified claims -- "" - cascade exhausted (memory, codebase, web), no source found. +- "": no source found. - > Cache suggestion: "" looks stable - cache it for reuse? (recommended: ) diff --git a/plugins/aidd-refine/skills/05-fact-check/references/claim-categories.md b/plugins/aidd-refine/skills/05-fact-check/references/claim-categories.md index 7518ec93..14bfec38 100644 --- a/plugins/aidd-refine/skills/05-fact-check/references/claim-categories.md +++ b/plugins/aidd-refine/skills/05-fact-check/references/claim-categories.md @@ -9,10 +9,10 @@ Locked taxonomy. Every extracted claim is assigned exactly one category. A state | `version` | A version, release number, or the existence of a package or tool | "React 19 is released", "the `zod` package exists" | | `api-signature` | A function or method signature, its parameters, return type, or documented behavior | "`useEffect` runs after paint", "`fetch` returns a Promise" | | `date-event-person` | A date, event, release timeline, or a fact about a person | "Node 22 shipped in 2024", "X wrote library Y" | -| `project-fact` | A claim about this repository - a file, function, config value, or structure | "the file `src/auth.ts` exists", "the API runs on port 3000" | -| `hard-to-know` | Any non-trivially-knowable fact not covered above - statistics, quotes, external facts | "this framework has 40k stars", "the RFC says Z" | +| `project-fact` | A claim about this repository: a file, function, config value, or structure | "the file `src/auth.ts` exists", "the API runs on port 3000" | +| `hard-to-know` | Any non-trivially-knowable fact not covered above: statistics, quotes, external facts | "this framework has 40k stars", "the RFC says Z" | -## Not claims - skip +## Not claims to skip - Opinion, preference, or aesthetic judgment ("this naming is clean", "the design feels heavy"). - Trivially-known general knowledge a competent reader would never dispute ("HTTP 404 means not found"). @@ -21,4 +21,4 @@ Locked taxonomy. Every extracted claim is assigned exactly one category. A state ## Classification rule -When a sentence mixes a fact and an opinion, split it: verify the fact, drop the opinion. When a claim could fit two categories, pick the one that drives the cheapest verification tier - `project-fact` over `hard-to-know` whenever the claim concerns this repository. +When a sentence mixes a fact and an opinion, split it: verify the fact, drop the opinion. When a claim could fit two categories, pick the one that drives the cheapest verification tier: `project-fact` over `hard-to-know` whenever the claim concerns this repository. diff --git a/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md b/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md new file mode 100644 index 00000000..05cf3955 --- /dev/null +++ b/plugins/aidd-refine/skills/05-fact-check/references/report-output-discipline.md @@ -0,0 +1,25 @@ +# Report output discipline + +The hard constraint on what the `03-report` action may deliver. Read it before drafting the report. + +## What the output contains + +Exactly these blocks, in this order, and nothing else: + +1. The rewritten text, with a `[n]` marker on each verified or corrected claim and a `(unverified - no source found)` marker on each unverified claim. +2. A `## Sources` block. +3. A `## Unverified claims` block, only when at least one claim is unverified. + +## What is forbidden + +These belong to the earlier actions and never appear in the output: + +- Any cascade or tier trace. Never write `Cascade`, `tier 1`, `tier 2`, `tier 3`, `miss`, `N/A`, or `resolved`. +- Any category label: `hard-to-know`, `version`, `api-signature`, `date-event-person`, `project-fact`. +- Any raw verdict word: `verdict`, `claim false`, `claim true`, or the values `verified` / `refuted` / `conflict` / `unverified` used as a status (the inline `(unverified - no source found)` marker is the one allowed exception). +- How a claim was checked: shell commands, `ls` / `find` / grep output, or phrases like "by inspection" or "codebase inspection". Cite the source and state the conclusion, not the method. +- Any sentence explaining why a cache line was or was not added. + +The report is plain prose. No active session output mode (terse, caveman, condensed) restyles it; render it normally however the surrounding conversation is styled. + +Before delivering, scan the draft: if a line carries any forbidden item, delete that line. diff --git a/plugins/aidd-refine/skills/05-fact-check/references/verification-cascade.md b/plugins/aidd-refine/skills/05-fact-check/references/verification-cascade.md index 08b90fb8..dd5af0c4 100644 --- a/plugins/aidd-refine/skills/05-fact-check/references/verification-cascade.md +++ b/plugins/aidd-refine/skills/05-fact-check/references/verification-cascade.md @@ -1,6 +1,6 @@ # Verification cascade -Claims are verified cheapest-first. The cascade short-circuits: as soon as a tier resolves a claim, stop - do not consult the remaining tiers. +Claims are verified cheapest-first. The cascade short-circuits: as soon as a tier resolves a claim, stop and skip the remaining tiers. ## Tiers @@ -12,12 +12,12 @@ Claims are verified cheapest-first. The cascade short-circuits: as soon as a tie ## Short-circuit rule -For each claim, walk tiers in order. The first tier that produces a clear answer resolves the claim - record the verdict and the source, move to the next claim. Never run a later tier once an earlier one has resolved. +For each claim, walk tiers in order. The first tier that produces a clear answer resolves the claim: record the verdict and the source, then move to the next claim. Never run a later tier once an earlier one has resolved. ## Tier routing by category -- `project-fact` - tier 1, then tier 2. A web lookup is almost never needed and must be skipped once tier 1 or 2 resolves. -- `version`, `api-signature`, `date-event-person`, `hard-to-know` - tier 1 first (a pinned version or doc may already answer it), then tier 3. Tier 2 only helps when the project itself embeds the fact. +- `project-fact`: tier 1, then tier 2. A web lookup is almost never needed and must be skipped once tier 1 or 2 resolves. +- `version`, `api-signature`, `date-event-person`, `hard-to-know`: tier 1 first (a pinned version or doc may already answer it), then tier 3. Tier 2 only helps when the project itself embeds the fact. ## Web-cost guardrail @@ -25,12 +25,13 @@ A web lookup is a last resort, never an opener. - Reach tier 3 only when tiers 1 and 2 both failed to resolve the claim. - Prefer one authoritative source (official documentation, the package registry, the primary publication) over many low-quality pages. -- Stop as soon as the claim is resolved or a contradiction is found - do not keep fetching for extra confirmation. +- Stop as soon as the claim is resolved or a contradiction is found; do not keep fetching for extra confirmation. ## Verdicts Each verified claim ends in exactly one verdict: -- `verified` - one or more sources confirm the claim. Record every source. -- `conflict` - sources disagree. Record both sides with their origin; do not pick a winner. -- `unverified` - no tier produced a source. The claim is kept and hedged, never asserted and never deleted. +- `verified`: one or more sources confirm the claim. Record every source. +- `refuted`: a source contradicts the claim. Record the contradicting source. +- `conflict`: sources disagree. Record both sides with their origin; do not pick a winner. +- `unverified`: no tier produced a source. The claim is kept and hedged, never asserted and never deleted. diff --git a/scripts/skill-eval.mjs b/scripts/skill-eval.mjs new file mode 100644 index 00000000..ab66e1f7 --- /dev/null +++ b/scripts/skill-eval.mjs @@ -0,0 +1,140 @@ +#!/usr/bin/env node +// Behavioral eval harness for aidd-refine skills. +// +// Each case runs the skill for real through a headless `claude -p`, in an +// isolated temp project where the skill is installed under a unique name as a +// project skill (`.claude/skills//`). The unique name guarantees the +// worktree copy runs, never a globally-installed plugin of the same name. +// +// Usage: +// node scripts/skill-eval.mjs # run every case (deterministic checks) +// node scripts/skill-eval.mjs 04-shadow-areas # run cases for one skill +// node scripts/skill-eval.mjs --judge # also run LLM-judge criteria (metered) +// node scripts/skill-eval.mjs --keep # keep temp dirs for inspection +// +// Local / opt-in only: needs an authenticated `claude` CLI and spends tokens. +// Not a CI gate. + +import { mkdtempSync, mkdirSync, writeFileSync, cpSync, rmSync, readFileSync, existsSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join, dirname, resolve } from "node:path"; +import { spawnSync } from "node:child_process"; +import { fileURLToPath } from "node:url"; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const ROOT = resolve(HERE, ".."); +const SKILLS_DIR = join(ROOT, "plugins", "aidd-refine", "skills"); +const CASES = JSON.parse(readFileSync(join(HERE, "skill-eval", "cases.json"), "utf8")); + +const args = process.argv.slice(2); +const JUDGE = args.includes("--judge"); +const KEEP = args.includes("--keep"); +const filter = args.find((a) => !a.startsWith("--")); +const cases = CASES.filter((c) => !filter || c.skill === filter); + +if (cases.length === 0) { + console.error(`No cases match ${filter ? `"${filter}"` : "(any)"}.`); + process.exit(2); +} + +function runClaude(prompt, cwd) { + const res = spawnSync( + "claude", + // --setting-sources project,local isolates the run from the user's global + // settings (hooks, output modes) so results are reproducible across machines. + ["-p", prompt, "--setting-sources", "project,local", "--add-dir", cwd, "--dangerously-skip-permissions"], + { cwd, input: "", encoding: "utf8", timeout: 600000, maxBuffer: 10 * 1024 * 1024 }, + ); + if (res.error) throw res.error; + return (res.stdout || "") + (res.stderr || ""); +} + +function has(haystack, needle) { + return haystack.toLowerCase().includes(String(needle).toLowerCase()); +} + +// One assertion = { ok: boolean, label: string } +function evaluate(expect, ctx) { + const checks = []; + const fileText = (name) => (existsSync(join(ctx.tmp, name)) ? readFileSync(join(ctx.tmp, name), "utf8") : null); + + for (const name of expect.filesExist || []) { + checks.push({ ok: existsSync(join(ctx.tmp, name)), label: `file exists: ${name}` }); + } + for (const [name, subs] of Object.entries(expect.fileContains || {})) { + const text = fileText(name); + for (const s of subs) checks.push({ ok: text != null && has(text, s), label: `${name} contains "${s}"` }); + } + for (const [name, subs] of Object.entries(expect.fileNotContains || {})) { + const text = fileText(name); + for (const s of subs) checks.push({ ok: text != null && !has(text, s), label: `${name} omits "${s}"` }); + } + for (const s of expect.stdoutContains || []) { + checks.push({ ok: has(ctx.stdout, s), label: `stdout contains "${s}"` }); + } + for (const s of expect.stdoutNotContains || []) { + checks.push({ ok: !has(ctx.stdout, s), label: `stdout omits "${s}"` }); + } + for (const re of expect.stdoutMatches || []) { + checks.push({ ok: new RegExp(re, "i").test(ctx.stdout), label: `stdout matches /${re}/` }); + } + + if (expect.judge) { + if (!JUDGE) { + checks.push({ ok: true, skipped: true, label: `judge (skipped, pass --judge): ${expect.judge}` }); + } else { + const evidence = [ctx.stdout, ...(expect.judgeFiles || []).map((n) => fileText(n) || "")].join("\n\n"); + const verdict = runClaude( + `You grade a test. Criterion: "${expect.judge}". Output under test follows between <<< and >>>.\n` + + `Reply with exactly PASS or FAIL on the first line, then one line of reason.\n<<<\n${evidence}\n>>>`, + ctx.tmp, + ); + checks.push({ ok: /^\s*pass\b/i.test(verdict), label: `judge: ${expect.judge}`, note: verdict.split("\n")[0].trim() }); + } + } + return checks; +} + +function setupCase(c) { + const tmp = mkdtempSync(join(tmpdir(), "skilleval-")); + const skillDst = join(tmp, ".claude", "skills", c.evalName); + mkdirSync(skillDst, { recursive: true }); + cpSync(join(SKILLS_DIR, c.skill), skillDst, { recursive: true }); + // Rewrite the frontmatter name so it matches the unique eval folder. + const skillMd = join(skillDst, "SKILL.md"); + const rewritten = readFileSync(skillMd, "utf8").replace(/^name:.*$/m, `name: ${c.evalName}`); + writeFileSync(skillMd, rewritten); + for (const [rel, content] of Object.entries(c.setup?.files || {})) { + const dst = join(tmp, rel); + mkdirSync(dirname(dst), { recursive: true }); + writeFileSync(dst, content); + } + return tmp; +} + +console.log(`Running ${cases.length} case(s)${JUDGE ? " with --judge" : ""}.\n`); +let failed = 0; +for (const c of cases) { + const tmp = setupCase(c); + let checks; + try { + const prompt = c.prompt.replaceAll("{{SKILL}}", c.evalName); + const stdout = runClaude(prompt, tmp); + checks = evaluate(c.expect, { tmp, stdout }); + } catch (err) { + checks = [{ ok: false, label: `run error: ${err.message}` }]; + } + const caseFailed = checks.some((k) => !k.ok); + if (caseFailed) failed++; + console.log(`${caseFailed ? "FAIL" : "PASS"} ${c.skill} :: ${c.name}`); + for (const k of checks) { + const mark = k.skipped ? "~" : k.ok ? "✓" : "✗"; + console.log(` ${mark} ${k.label}${k.note ? ` (${k.note})` : ""}`); + } + if (KEEP) console.log(` tmp: ${tmp}`); + else rmSync(tmp, { recursive: true, force: true }); + console.log(""); +} + +console.log(`${cases.length - failed}/${cases.length} cases passed.`); +process.exit(failed ? 1 : 0); diff --git a/scripts/skill-eval/README.md b/scripts/skill-eval/README.md new file mode 100644 index 00000000..663cda8e --- /dev/null +++ b/scripts/skill-eval/README.md @@ -0,0 +1,78 @@ +# skill-eval + +Behavioral eval harness for the `aidd-refine` skills. Runs each skill for real +through a headless `claude -p` and asserts the outcomes its action `## Test` +blocks describe. + +## Run + +```bash +node scripts/skill-eval.mjs # every case, deterministic checks +node scripts/skill-eval.mjs 04-shadow-areas # one skill +node scripts/skill-eval.mjs --judge # also run LLM-judge criteria (metered) +node scripts/skill-eval.mjs --keep # keep temp dirs to inspect +``` + +Local and opt-in. Needs an authenticated `claude` CLI and spends tokens, so it +is not a CI gate. + +## How it works + +Each case runs in a throwaway temp project. The skill under test is copied into +`.claude/skills//` and its frontmatter `name` is rewritten to a unique +`xeval-*` value. The unique name guarantees the worktree copy runs, never a +globally-installed plugin of the same name. The harness writes the case setup +files, runs `claude -p` in that project, then checks the written files and the +output. + +## Cases + +`cases.json` holds the cases. Each one: + +```json +{ + "skill": "04-shadow-areas", + "evalName": "xeval-shadow", + "name": "short description", + "setup": { "files": { "prd.md": "..." } }, + "prompt": "Use the {{SKILL}} skill on ./prd.md ...", + "expect": { + "filesExist": ["prd-shadow-report.md"], + "fileContains": { "prd-shadow-report.md": ["## Gaps by Category"] }, + "fileNotContains": { "report.md": ["..."] }, + "stdoutContains": ["..."], + "stdoutNotContains": ["tier 1"], + "stdoutMatches": ["\\d+%"], + "judge": "natural-language criterion, only checked under --judge", + "judgeFiles": ["prd-shadow-report.md"] + } +} +``` + +`{{SKILL}}` is replaced with the case `evalName`. Deterministic checks run +always; `judge` criteria run only with `--judge` and use a second `claude -p` +as grader, for outcomes that cannot be matched literally. + +## Coverage and limits + +- Deterministic where possible (file written, filename rule, required sections, + hedged unverified claim, forbidden mechanics absent). Fuzzy outcomes + (claim-extraction quality, terseness) go to `--judge` and can flake. +- `01-brainstorm` is interactive (multi-turn Q&A) and is not covered here; a + single headless turn cannot exercise its loop. + +## Known findings + +The harness surfaced two limitations worth tracking: + +- **condense's `Condense: ON ().` line is model-emitted, not guaranteed.** + `02-stats` and the `condense-stats.js` hook parse that exact line from the + transcript, but the model paraphrases it ("Condense mode on, level full") + even when the action mandates the literal. So the condense case gates on + semantics (mentions condense + the level), not the literal, and stats + detection is best-effort. A robust fix would emit the marker from the hook + rather than rely on model output. +- **empty-source scanning varies.** Most runs produce exactly one blocker, but + the exact count/header drifts between runs. The case asserts deterministically + only that a report is written, and gates the "exactly one blocker" semantics + behind `--judge`. diff --git a/scripts/skill-eval/cases.json b/scripts/skill-eval/cases.json new file mode 100644 index 00000000..ad8bd4b8 --- /dev/null +++ b/scripts/skill-eval/cases.json @@ -0,0 +1,69 @@ +[ + { + "skill": "04-shadow-areas", + "evalName": "xeval-shadow", + "name": "scans a PRD and writes a structured report", + "setup": { + "files": { + "prd.md": "# Checkout PRD\n\nUsers can buy items. The system must respond quickly when the cart is submitted.\nOn submit, the order is created and a confirmation is shown.\n" + } + }, + "prompt": "Use the {{SKILL}} skill on ./prd.md to find blind spots and write the shadow report file next to it.", + "expect": { + "filesExist": ["prd-shadow-report.md"], + "fileContains": { "prd-shadow-report.md": ["# Shadow Areas Report", "## Gaps by Category", "Total gaps:", "[blocker]"] } + } + }, + { + "skill": "04-shadow-areas", + "evalName": "xeval-shadow", + "name": "filename rule keeps a dotless name (Makefile)", + "setup": { "files": { "Makefile": "build:\n\techo hi\n" } }, + "prompt": "Use the {{SKILL}} skill on ./Makefile to find blind spots and write the shadow report next to it.", + "expect": { "filesExist": ["Makefile-shadow-report.md"] } + }, + { + "skill": "04-shadow-areas", + "evalName": "xeval-shadow", + "name": "empty source yields a single blocker", + "setup": { "files": { "empty.md": "" } }, + "prompt": "Use the {{SKILL}} skill on ./empty.md to find blind spots and write the shadow report next to it.", + "expect": { + "filesExist": ["empty-shadow-report.md"], + "judge": "The report flags exactly one blocker gap, asking what content the (empty) artifact should contain.", + "judgeFiles": ["empty-shadow-report.md"] + } + }, + { + "skill": "05-fact-check", + "evalName": "xeval-factcheck", + "name": "verifies a real file, refutes a fake one, hedges the unknowable, hides mechanics", + "setup": { "files": { "src/auth.ts": "export const auth = true;\n" } }, + "prompt": "Use the {{SKILL}} skill to fact-check this text and rewrite it with citations: \"The file src/auth.ts exists in this repo. The file src/ghost9000.ts exists in this repo. The lead maintainer of this project owns exactly 47 cats.\"", + "expect": { + "stdoutContains": ["## Sources", "(unverified - no source found)"], + "stdoutNotContains": ["tier 1", "tier 2", "tier 3", "Cascade", "codebase inspection"], + "judge": "src/auth.ts is confirmed with a citation; the src/ghost9000.ts claim is corrected as not present (never restated as true); the 47-cats claim is marked unverified; no shell commands or inspection methods appear.", + "judgeFiles": [] + } + }, + { + "skill": "03-condense", + "evalName": "xeval-condense", + "name": "turning on confirms condense at the full level", + "prompt": "Use the {{SKILL}} skill to turn condense mode on, set to the full level (not lite, not ultra).", + "expect": { + "stdoutContains": ["condense", "full"] + } + }, + { + "skill": "02-challenge", + "evalName": "xeval-challenge", + "name": "flags a plan violation as a deal breaker with low confidence", + "prompt": "Use the {{SKILL}} skill. Agreed plan: the function must RETURN THE SUM of a and b. Work to review: function add(a, b) { return a - b }. Challenge the work against the plan and emit the report.", + "expect": { + "stdoutContains": ["confidence", "Deal breakers"], + "judge": "A confidence percentage below 75% is stated, and the subtraction (returning a - b instead of a + b) is listed as a deal breaker." + } + } +] From 79ebfddc28f3c3e076b5a3e260e727c845e06a3f Mon Sep 17 00:00:00 2001 From: Baptiste LAFOURCADE <119650761+blafourcade@users.noreply.github.com> Date: Wed, 24 Jun 2026 21:53:54 +0200 Subject: [PATCH 12/14] refactor(framework): executor/checker agents + SDLC orchestration redesign (#314) Collapse the SDLC agent trio (planner/implementer/reviewer) into two leaf agents, executor + checker, with the 00-sdlc orchestrator owning planning itself. Enforce recipe-not-spawn: only the orchestrator spawns, recipe skills focus on themselves and never name other skills or the SDLC. - executor runs 02-implement, checker runs 05-review (embedded checklist). - executor never holds 01-plan (structural immutability). - 05-review gains a relevancy axis (fit/conform/rot) into one review.md. - commit, pull-request, and assert defer to project memory (vcs.md, coding-assertions.md) over bundled defaults; ship stops dictating the commit format. - pull-request is fully VCS-tool-agnostic. - all flow skills renormalized to the skill-authoring contract; orphan assets and a leaked user-stories WIP duplicate removed. Net +673/-1269. Refs #253. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 4 +- docs/ARCHITECTURE.md | 14 ++ docs/CATALOG.md | 15 ++- docs/GLOSSARY.md | 2 +- .../assets/agent-template.md | 2 +- .../references/agent-authoring.md | 4 +- plugins/aidd-dev/.claude-plugin/plugin.json | 5 +- plugins/aidd-dev/CATALOG.md | 28 ++-- plugins/aidd-dev/README.md | 9 +- plugins/aidd-dev/agents/checker.md | 44 +++++++ plugins/aidd-dev/agents/executor.md | 33 +++++ plugins/aidd-dev/agents/implementer.md | 103 --------------- plugins/aidd-dev/agents/planner.md | 107 --------------- plugins/aidd-dev/agents/reviewer.md | 123 ------------------ plugins/aidd-dev/skills/00-sdlc/README.md | 21 +-- plugins/aidd-dev/skills/00-sdlc/SKILL.md | 104 +++------------ .../skills/00-sdlc/actions/01-spec.md | 28 ++-- .../skills/00-sdlc/actions/02-plan.md | 26 ++-- .../skills/00-sdlc/actions/03-implement.md | 32 ++--- .../skills/00-sdlc/actions/04-review.md | 30 ++--- .../skills/00-sdlc/actions/05-ship.md | 26 ++-- plugins/aidd-dev/skills/01-plan/SKILL.md | 2 +- .../skills/01-plan/actions/01-gather.md | 4 +- .../skills/01-plan/actions/02-explore.md | 6 +- .../skills/01-plan/actions/03-wireframe.md | 2 +- .../skills/01-plan/actions/04-plan.md | 4 +- .../skills/01-plan/references/plan-status.md | 14 +- .../aidd-dev/skills/02-implement/README.md | 43 +++--- plugins/aidd-dev/skills/02-implement/SKILL.md | 26 ++-- .../02-implement/actions/01-implement.md | 39 ------ .../skills/02-implement/actions/01-prepare.md | 23 ++++ .../skills/02-implement/actions/02-execute.md | 25 ++++ .../02-implement/actions/03-finalize.md | 21 +++ .../skills/02-implement/references/blocked.md | 3 +- plugins/aidd-dev/skills/03-assert/README.md | 28 ++-- plugins/aidd-dev/skills/03-assert/SKILL.md | 34 +++-- .../skills/03-assert/actions/01-assert.md | 31 ++--- .../actions/02-assert-architecture.md | 48 ++----- .../03-assert/actions/03-assert-frontend.md | 42 ++---- .../skills/03-assert/assets/task-template.md | 8 +- plugins/aidd-dev/skills/05-review/README.md | 56 ++++---- plugins/aidd-dev/skills/05-review/SKILL.md | 42 +++--- .../05-review/actions/01-review-code.md | 33 ++--- .../05-review/actions/02-review-functional.md | 45 ++----- .../05-review/actions/03-review-relevancy.md | 24 ++++ .../05-review/assets/review-code-template.md | 47 ------- .../assets/review-functional-template.md | 53 -------- .../05-review/assets/review-template.md | 43 ++++++ .../05-review/references/review-rubric.md | 27 ++++ .../09-for-sure/assets/plan-template.md | 2 +- plugins/aidd-dev/skills/10-todo/README.md | 2 +- plugins/aidd-dev/skills/10-todo/SKILL.md | 2 +- .../skills/10-todo/actions/01-todo.md | 2 +- plugins/aidd-pm/CATALOG.md | 2 +- plugins/aidd-pm/skills/04-spec/README.md | 25 ++-- plugins/aidd-pm/skills/04-spec/SKILL.md | 47 +++---- .../skills/04-spec/actions/01-build.md | 36 ++--- .../skills/04-spec/actions/02-refine.md | 34 ++--- .../skills/04-spec/assets/spec-validator.yml | 2 +- plugins/aidd-vcs/CATALOG.md | 6 +- plugins/aidd-vcs/skills/01-commit/SKILL.md | 17 +-- .../skills/01-commit/actions/01-commit.md | 59 +++------ .../aidd-vcs/skills/02-pull-request/SKILL.md | 17 +-- .../actions/01-pull-request.md | 54 +++----- .../02-pull-request/assets/CONTRIBUTING.md | 67 ---------- .../skills/02-pull-request/assets/README.md | 33 ----- scripts/check-markdown-links.js | 2 +- 67 files changed, 673 insertions(+), 1269 deletions(-) create mode 100644 plugins/aidd-dev/agents/checker.md create mode 100644 plugins/aidd-dev/agents/executor.md delete mode 100644 plugins/aidd-dev/agents/implementer.md delete mode 100644 plugins/aidd-dev/agents/planner.md delete mode 100644 plugins/aidd-dev/agents/reviewer.md delete mode 100644 plugins/aidd-dev/skills/02-implement/actions/01-implement.md create mode 100644 plugins/aidd-dev/skills/02-implement/actions/01-prepare.md create mode 100644 plugins/aidd-dev/skills/02-implement/actions/02-execute.md create mode 100644 plugins/aidd-dev/skills/02-implement/actions/03-finalize.md create mode 100644 plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md delete mode 100644 plugins/aidd-dev/skills/05-review/assets/review-code-template.md delete mode 100644 plugins/aidd-dev/skills/05-review/assets/review-functional-template.md create mode 100644 plugins/aidd-dev/skills/05-review/assets/review-template.md create mode 100644 plugins/aidd-dev/skills/05-review/references/review-rubric.md delete mode 100644 plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md delete mode 100644 plugins/aidd-vcs/skills/02-pull-request/assets/README.md diff --git a/README.md b/README.md index b11a07f0..44c32135 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@

🇫🇷 The first French open-source framework for AI-driven development.

- 7 plugins · 40 skills · 3 agents · MIT + 7 plugins · 41 skills · 2 agents · MIT

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -189,7 +189,7 @@ Commits, pull / merge requests, release tags, issue creation. ### 📋 [aidd-pm](plugins/aidd-pm/README.md) -`4 skills` · stable +`5 skills` · stable Ticket info, user stories, PRD, spec drafting. diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bbdeb4bd..709cda3c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -124,6 +124,20 @@ flowchart LR Each action is a self-contained markdown file with inputs, outputs, depends-on, process steps, and a test checklist. Actions can call other skills via the `Skill` tool, so a skill discovers a capability it needs at runtime (by matching skill descriptions, never by hardcoded plugin name) and delegates to it. +## Skills and agents + +- A **skill** is a caller-agnostic recipe; it runs in the context of whoever invokes it. +- An **agent** is an isolated executor; it runs in its own context and returns only a result. + +Choose by context, not complexity: keep the work visible to the caller → skill; isolate it and take only the result → agent. + +Composition rules: + +- **Spawning is an orchestration decision, never a skill's.** A recipe skill never spawns an agent; it runs in the caller's context. Only a high-level orchestrator skill (for example the SDLC) spawns agents, and it decides per step whether to isolate the work in an agent or run the recipe inline. +- An orchestrator spawns each step as a leaf agent that runs a recipe, or runs the recipe itself when the step needs no isolation. The SDLC owns planning (runs `01-plan` in its own context) and spawns two workers: `executor` (runs `02-implement`) and `checker` (runs `05-review`). The agent is the isolation; the recipe inside it never spawns again. +- An agent invokes only the recipe skills it declares under `# Skills you may invoke`, never an orchestrator skill, and never reads a skill's files. It names a same-plugin skill by its `plugin:folder` address (deterministic); it names a cross-plugin skill by capability, per cross-plugin orthogonality. +- An agent never delegates flow work to another agent and never invokes an orchestrator skill. It may spawn a read-only recon helper (for example `Explore`) that mutates nothing and spawns nothing. So the write path stays two layers deep and delegation can never cycle. + ## Cross-plugin orthogonality Plugins do not reference each other by name. When skill A needs a capability owned by skill B, it discovers a candidate at runtime through description matching. This rule keeps the marketplace forkable, the plugins swappable, and the docs maintainable. diff --git a/docs/CATALOG.md b/docs/CATALOG.md index afd90865..74b3212d 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -20,14 +20,20 @@ Bootstrap, project init, context-artifact generation, diagrams, learning, and ex | `00-onboard` | Detect project state and open a hub of project actions | `01-detect-state`, `02-recommend-next`, `03-execute-or-handoff` | | `01-bootstrap` | Imagine and validate a new SaaS architecture, output an `INSTALL.md` | `01-gather-needs`, `02-propose-candidates`, `03-audit-candidates`, `04-pick-and-design`, `05-write-install-md` | | `02-project-memory` | Initialize or refresh the memory bank and AI context files | `01-init-context-file`, `02-scaffold-docs`, `03-generate-memory`, `04-review-memory`, `05-sync-memory` | -| `03-context-generate` | Generate context artifacts across the host AI tool(s) | sub-generators: `agents`, `commands`, `hooks`, `marketplaces`, `plugins`, `rules`, `skills` | -| `04-mermaid` | Generate Mermaid diagrams via a plan-validate workflow | `01-mermaid` | -| `05-learn` | Capture learnings, conventions, and decisions into memory, decisions, rules | `01-scope`, `02-write`, `03-sync` | +| `03-context-generate` | Router that dispatches an artifact-generation request to the dedicated generator below | delegates to `04`–`08` (and plugins / marketplaces) | +| `04-skill-generate` | Generate a router-based skill across the host AI tool(s) | `01-capture-intent`, `02-decompose-actions`, `03-draft-skill`, `04-write-actions`, `05-validate` | +| `05-rule-generate` | Generate a coding rule that governs editor and agent behavior | `01-capture-rule`, `02-write-rule`, `03-validate` | +| `06-agent-generate` | Generate an agent across the host AI tool(s) | `01-capture-agent`, `02-write-agent`, `03-validate` | +| `07-command-generate` | Generate a flat slash command across the host AI tool(s) | `01-capture-command`, `02-write-command`, `03-validate` | +| `08-hook-generate` | Generate a lifecycle hook across the host AI tool(s) | `01-capture-hook`, `02-write-hook`, `03-validate` | +| `09-mermaid` | Generate Mermaid diagrams via a plan-validate workflow | `01-mermaid` | +| `10-learn` | Capture learnings, conventions, and decisions into memory, decisions, rules | `01-gather`, `02-assess`, `03-write`, `04-sync` | | `11-explore` | Survey the project across tooling, context, and codebase, then drill into one axis | `01-survey`, `02-drill` | +| `12-cook` | Manage the project's recipes/ how-to sheets: list, create, or update one | `01-list`, `02-upsert` | ## aidd-dev -The development SDLC: plan, implement, assert, audit, review, test, refactor, debug. +The development SDLC: plan, implement, assert, audit, review, test, refactor, debug, for-sure, todo. | Skill | Role | Actions | | --------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | @@ -41,6 +47,7 @@ The development SDLC: plan, implement, assert, audit, review, test, refactor, de | `07-refactor` | Improve code without changing behavior across four axes | `01-performance`, `02-security`, `03-cleanup`, `04-architecture` | | `08-debug` | Reproduce and fix bugs with a test-driven workflow | `01-reproduce`, `02-debug`, `03-reflect-issue` | | `09-for-sure` | Iterative loop that retries until a success condition is met | `01-init-tracking`, `02-auto-accept`, `03-autonomous-loop` | +| `10-todo` | Split the prompt into independent todos, run one implementer agent per todo in parallel | `01-todo` | ## aidd-pm diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md index 195804a7..19a57100 100644 --- a/docs/GLOSSARY.md +++ b/docs/GLOSSARY.md @@ -28,7 +28,7 @@ A single atomic step inside a skill, stored at `plugins//skills//agents/.md`. Agents are scoped (for example `planner`, `implementer`, `reviewer`) and called from skills when a step needs a dedicated role rather than the main thread. Currently agents ship only in `aidd-dev`. +A specialized AI persona under `plugins//agents/.md`. Agents are scoped (for example `executor`, `checker`) and spawned by an orchestrator when a step needs isolation in a dedicated role rather than the main thread. Currently agents ship only in `aidd-dev`. ## Rule diff --git a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md index 77152f8f..e3c19a16 100644 --- a/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md +++ b/plugins/aidd-context/skills/06-agent-generate/assets/agent-template.md @@ -16,7 +16,7 @@ model: # optional, per tool-paths.md # Inputs: what it receives when invoked # Outputs: what it returns # Guardrails: what it must never do -# Skills you may invoke: other skills it may run, named by description, never a hardcoded plugin name +# Skills you may invoke: a same-plugin skill by its plugin:folder address, a cross-plugin skill by capability For an orchestration agent only: # Definition of Ready, # Definition of Done, # Decisions in scope, # Decisions out of scope, # Handoffs. See references/agent-authoring.md. --> diff --git a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md index 20728d5d..28fae750 100644 --- a/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md +++ b/plugins/aidd-context/skills/06-agent-generate/references/agent-authoring.md @@ -12,7 +12,7 @@ The contract every generated agent must satisfy. An agent is a focused role with ## Naming -- Short and catchy, a single word where possible: `reviewer`, `planner`, `implementer`. +- Short and catchy, a single word where possible: `executor`, `checker`, `auditor`. - Fits the role at a glance. Propose three options for the user to pick. ## Body shape @@ -22,7 +22,7 @@ Short imperative sentences. Optional sections, added only when they earn their p - `# Inputs`: what it receives. - `# Outputs`: what it returns. - `# Guardrails`: what it must never do. -- `# Skills you may invoke`: name a skill by its description, never a hardcoded plugin name. The agent discovers it at runtime. +- `# Skills you may invoke`: name a same-plugin skill by its `plugin:folder` address, for deterministic resolution. Name a cross-plugin skill by its capability, discovered at runtime, never hardcoded. - `# Definition of Ready` / `# Definition of Done`: start and finish gates. - `# Decisions in scope` / `# Decisions out of scope`: what it may decide, what it must defer. - `# Handoffs`: who it returns to. diff --git a/plugins/aidd-dev/.claude-plugin/plugin.json b/plugins/aidd-dev/.claude-plugin/plugin.json index a851b8ae..3518598f 100644 --- a/plugins/aidd-dev/.claude-plugin/plugin.json +++ b/plugins/aidd-dev/.claude-plugin/plugin.json @@ -21,9 +21,8 @@ "./skills/10-todo" ], "agents": [ - "./agents/implementer.md", - "./agents/planner.md", - "./agents/reviewer.md" + "./agents/executor.md", + "./agents/checker.md" ], "keywords": [ "sdlc", diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index f428707a..7f745f1b 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -33,9 +33,8 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | File | Description | |------|---| -| [implementer.md](agents/implementer.md) | `Milestone executor. Use when a planner has handed off a milestone, a fix list, or items_remaining from a previous incomplete pass. Codes, tests, repairs. Returns what's done, what's remaining, and a completion score. Never replans, never judges.` | -| [planner.md](agents/planner.md) | `Planning agent. Use when a validated spec must be turned into executable milestone plans, or when a top-level SDLC orchestrator needs a replan. Writes plans and decisions only. Never writes code, never judges code, never spawns implementer/reviewer agents.` | -| [reviewer.md](agents/reviewer.md) | `Independent critic in fresh context. Use when an artifact (code, spec, plan, doc) needs verification against a validator (acceptance criteria, checklist file, or any explicit ruleset). Returns reviewed items, findings, completion score and quality score. Never edits the artifact, never decides what to do next.` | +| [checker.md](agents/checker.md) | `Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix.` | +| [executor.md](agents/executor.md) | `Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work.` | ### `skills` @@ -49,7 +48,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [04-review.md](skills/00-sdlc/actions/04-review.md) | - | | `actions` | [05-ship.md](skills/00-sdlc/actions/05-ship.md) | - | | `-` | [README.md](skills/00-sdlc/README.md) | - | -| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated.` | +| `-` | [SKILL.md](skills/00-sdlc/SKILL.md) | `Orchestrate the full dev flow, a free-form request to shipped code, every step delegated. Use to take a request end to end, not a single step. Interactive by default; say auto for unattended.` | #### `skills/01-plan` @@ -65,16 +64,18 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `references` | [mermaid-conventions.md](skills/01-plan/references/mermaid-conventions.md) | `Rules for generating valid, high-quality Mermaid diagrams. Apply when creating or reviewing any Mermaid diagram (flowchart, state, ER, sequence, gantt).` | | `references` | [plan-status.md](skills/01-plan/references/plan-status.md) | `Plan lifecycle status field - values, meaning, who writes each, and when.` | | `references` | [wireframe-conventions.md](skills/01-plan/references/wireframe-conventions.md) | - | -| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan: gather the source, explore the codebase, optionally wireframe a screen, then plan. Use when the user wants to plan a feature, turn a ticket or requirements into a phased plan, or wireframe a screen before building. Do NOT use to write code (use 02-implement), review a diff (use 05-review), or audit code (use 04-audit).` | +| `-` | [SKILL.md](skills/01-plan/SKILL.md) | `Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code or review a diff.` | #### `skills/02-implement` | Group | File | Description | |-------|------|---| -| `actions` | [01-implement.md](skills/02-implement/actions/01-implement.md) | - | +| `actions` | [01-prepare.md](skills/02-implement/actions/01-prepare.md) | - | +| `actions` | [02-execute.md](skills/02-implement/actions/02-execute.md) | - | +| `actions` | [03-finalize.md](skills/02-implement/actions/03-finalize.md) | - | | `-` | [README.md](skills/02-implement/README.md) | - | | `references` | [blocked.md](skills/02-implement/references/blocked.md) | `Conditions that make a plan blocked (needs a human).` | -| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness.` | +| `-` | [SKILL.md](skills/02-implement/SKILL.md) | `Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff.` | #### `skills/03-assert` @@ -83,9 +84,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-assert.md](skills/03-assert/actions/01-assert.md) | - | | `actions` | [02-assert-architecture.md](skills/03-assert/actions/02-assert-architecture.md) | - | | `actions` | [03-assert-frontend.md](skills/03-assert/actions/03-assert-frontend.md) | - | -| `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | `Task tracking system to ensure all tasks are categorized and addressed` | +| `assets` | [task-template.md](skills/03-assert/assets/task-template.md) | - | | `-` | [README.md](skills/03-assert/README.md) | - | -| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert features work as intended - general assertions, architecture conformance, and frontend UI validation.` | +| `-` | [SKILL.md](skills/03-assert/SKILL.md) | `Assert the work behaves: iterate the project's coding assertions until they pass, plus optional architecture and frontend facets. Use to validate an implementation. Do NOT use to review or write tests.` | #### `skills/04-audit` @@ -108,10 +109,11 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-review-code.md](skills/05-review/actions/01-review-code.md) | - | | `actions` | [02-review-functional.md](skills/05-review/actions/02-review-functional.md) | - | -| `assets` | [review-code-template.md](skills/05-review/assets/review-code-template.md) | `Code review report template for a diff` | -| `assets` | [review-functional-template.md](skills/05-review/assets/review-functional-template.md) | `Functional review report template for a diff against a plan` | +| `actions` | [03-review-relevancy.md](skills/05-review/actions/03-review-relevancy.md) | - | +| `assets` | [review-template.md](skills/05-review/assets/review-template.md) | - | | `-` | [README.md](skills/05-review/README.md) | - | -| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert).` | +| `references` | [review-rubric.md](skills/05-review/references/review-rubric.md) | - | +| `-` | [SKILL.md](skills/05-review/SKILL.md) | `Read-only review of a diff on three axes, code, behavior versus the plan, and relevancy, into one verdict report. Use before shipping a change. Do NOT use to fix findings or audit a codebase.` | #### `skills/06-test` @@ -162,5 +164,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-todo.md](skills/10-todo/actions/01-todo.md) | - | | `-` | [README.md](skills/10-todo/README.md) | - | -| `-` | [SKILL.md](skills/10-todo/SKILL.md) | `Split the user prompt into independent todos, run one implementer agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations.` | +| `-` | [SKILL.md](skills/10-todo/SKILL.md) | `Split the user prompt into independent todos, run one executor agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations.` | diff --git a/plugins/aidd-dev/README.md b/plugins/aidd-dev/README.md index 976e7ac9..99939744 100644 --- a/plugins/aidd-dev/README.md +++ b/plugins/aidd-dev/README.md @@ -16,10 +16,10 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert |---|---|---| | [2.0] | [sdlc](skills/00-sdlc/README.md) | Dev SDLC orchestrator (code-shipping pipeline): spec, plan, implement, test, review, commit, PR. | | [2.1] | [plan](skills/01-plan/README.md) | Turn a request, ticket, or file into a phased implementation plan, gathering the source first and optionally wireframing a screen before planning. | -| [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness. | +| [2.2] | [implement](skills/02-implement/README.md) | Execute an implementation plan phase by phase, recipe-style, iterating until 100% completeness. | | [2.3] | [assert](skills/03-assert/README.md) | Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. | | [2.4] | [audit](skills/04-audit/README.md) | Perform deep codebase analysis to identify technical debt, dead code, and improvement opportunities. | -| [2.5] | [review](skills/05-review/README.md) | Review code quality against project rules and validate feature behavior against plan specifications. | +| [2.5] | [review](skills/05-review/README.md) | Review a diff along three axes: code quality, feature behavior against the plan, and relevancy (fit to the need, declared-rule conformance, no rot). | | [2.6] | [test](skills/06-test/README.md) | Write and iterate on tests until they pass, and validate user journeys end-to-end in the browser. | | [2.7] | [refactor](skills/07-refactor/README.md) | Optimize code for performance and fix security vulnerabilities following OWASP guidelines. | | [2.8] | [debug](skills/08-debug/README.md) | Reproduce and fix bugs systematically using test-driven workflow, root cause analysis, and hypothesis validation. | @@ -29,6 +29,5 @@ Covers the full SDLC coding loop: orchestrator, planning, implementation, assert | Agent | Description | |---|---| -| planner | Orchestrator. Turns a validated spec into milestones, drives the implementer/reviewer loop, escalates blocked decisions. Never writes code, never judges code. | -| implementer | Milestone executor. Codes, tests, repairs within the milestone scope. Commits atomically per ticked checkbox. Returns completion score. | -| reviewer | Independent critic in fresh context. Verifies an artifact against an explicit validator (acceptance criteria or checklist). Returns findings, completion and quality scores. Never edits the artifact. | +| executor | Dispatched doer in its own context. Turns a scoped task into working, validated code that fits the project, deciding how, never what. Never authors a plan, never judges its own work. | +| checker | Independent critic in fresh context. Judges finished work against its validator and the real need, leaving nothing unchecked. Returns findings, scores, and a verdict. Never edits the work, never implements the fix. | diff --git a/plugins/aidd-dev/agents/checker.md b/plugins/aidd-dev/agents/checker.md new file mode 100644 index 00000000..6ed4cf32 --- /dev/null +++ b/plugins/aidd-dev/agents/checker.md @@ -0,0 +1,44 @@ +--- +name: checker +description: Judges finished work against its validator and the real need, leaving nothing unchecked. Use when code or a deliverable needs independent verification before it ships. Never edits the work, never implements the fix. +model: opus +--- + +# Role + +You are the checker. Your job is to judge finished work against its validator and the real need, in a fresh context with no memory of how it was built, and to leave nothing unchecked. + +# Behavior + +- Build your validator stack first: the acceptance criteria and the need the work is meant to serve. Extend the checklist below with the project's own review checklist when it provides one. +- Judge each criterion: inspect, run validation commands when they exist, and mark it fulfilled, partial, or unfulfilled with evidence. +- Run the checklist on every code or diff, leaving no item unchecked. +- Then check the layer the reviews miss: does the delivered logic serve the actual need, end to end, even when code review and functional review both pass? Name any gap between intent and result. +- Demand command output or file evidence, never bare claims. Lean strict: a false alarm costs less than a missed defect. +- Return your verdict, findings, and score to whoever invoked you. Hold yourself accountable for whatever you pass. + +# Checklist + +This is the behavioral baseline. Apply it to every code or diff, and extend it with the project's own checklist when one exists. + +- [ ] No information duplication. DRY across code and docs; link to the canonical home instead of copying. +- [ ] No incoherence or contradiction. Naming, behavior, and docs-versus-code stay consistent. +- [ ] No over-engineering. The simplest solution that meets the need; no speculative generality, no unused abstraction. +- [ ] No dead code or debug leftovers. No commented-out blocks, stray logs, or silent TODOs. + +# Scoring + +- If the validator defines weights and thresholds, apply them exactly, and let any hard violation force the score to zero. +- Otherwise score the proportion of fulfilled criteria, adjusted for the severity of the findings, with your reasoning. +- The pass threshold is the caller's gate, not yours. You report the score; you do not declare pass or fail. + +# Guardrails + +- Never edit the work or its validator. Never implement the fix. Never delegate to another agent. +- Never pass on vibes: tie every verdict to a stated criterion, a checklist item, or a named need-gap. +- Flag an ambiguous criterion instead of guessing. Do not go easy because the work looks impressive. + +# Skills you may invoke + +- `aidd-dev:05-review` +- `aidd-dev:04-audit` diff --git a/plugins/aidd-dev/agents/executor.md b/plugins/aidd-dev/agents/executor.md new file mode 100644 index 00000000..d9f3ad86 --- /dev/null +++ b/plugins/aidd-dev/agents/executor.md @@ -0,0 +1,33 @@ +--- +name: executor +description: Turns a dispatched task into working, validated code that fits the project. Use when an approved scope must become code. Never plans, never judges its own work. +model: sonnet +--- + +# Role + +You are the executor. Your job is to turn a dispatched task into working, validated code that fits the project. You decide how, never what. + +# Behavior + +- Honour the project's own conventions where it defines them, and match the code around you. Where it stays silent, follow the prevailing idiom. +- Internalize the acceptance criteria before writing anything. If the scope is ambiguous, surface it instead of guessing. +- Work in a tight loop: build a substep, validate it, repair on red, and only then move on. Validation passing is the gate, never your own say-so. +- Commit per coherent unit, code and its status together, one unit one commit. +- When you finish or stall, return to whoever invoked you with what is done, what is left, and why. + +# Guardrails + +- Never author or edit a plan, spec, or acceptance criterion. That authority is the caller's. On any drift, stop and hand it back to be replanned. +- Stay strictly in the scope you are handed. Declare anything you bypass: no silent TODO, skipped test, or placeholder mock. +- Never judge your own work, and never start a review. The caller handles that. +- Never delegate to another agent. +- When the work is physically impossible for the AI, stop and say so plainly: a real payment, a human login, an unreadable secret, anything behind hardware or 2FA. Do not fake progress. + +# Skills you may invoke + +- `aidd-dev:02-implement` +- `aidd-dev:03-assert` +- `aidd-dev:06-test` +- `aidd-dev:08-debug` +- `commit` (cross-plugin, by capability) diff --git a/plugins/aidd-dev/agents/implementer.md b/plugins/aidd-dev/agents/implementer.md deleted file mode 100644 index ae744ae0..00000000 --- a/plugins/aidd-dev/agents/implementer.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -name: implementer -description: Milestone executor. Use when a planner has handed off a milestone, a fix list, or items_remaining from a previous incomplete pass. Codes, tests, repairs. Returns what's done, what's remaining, and a completion score. Never replans, never judges. -model: sonnet ---- - -# Role - -You build what the top-level SDLC orchestrator or Planner specifies, within the boundaries of the input. You decide how to implement, never what. You report back honestly: what you finished, what you couldn't, and why. - -You implement directly in your context. Do not spawn other agents. Do not search for `Task` or `Agent`; they are not part of this role. - -# Inputs - -When invoked, you receive: - -- A milestone description with explicit acceptance criteria, OR a fix list, OR an `items_remaining` set -- A relevant slice of the spec (for reference) -- Optionally, validation commands (lint, type check, tests, build) - -# Outputs - -When you return, your output is structured: - -```yaml -items_implemented: - - -items_remaining: - - -completion_score: <0-100> # percentage of input scope actually delivered -notes: -``` - -# Definition of Ready - -You may start when: - -- The input scope is identified with explicit acceptance criteria -- Validation commands are available (or you can derive them from project conventions) - -If the scope is ambiguous, return immediately with `completion_score: 0` and an explanation in `notes`. Don't guess. - -# Definition of Done - -Your output is complete when: - -- Every item in the input scope has been attempted (or explicitly skipped with reason) -- Every attempted item has been validated locally (lint, types, tests, build pass) -- The output accurately reports `items_implemented`, `items_remaining`, and `completion_score` - -# Behavior - -- Internalize acceptance criteria before writing code. -- If a fix list or items_remaining was provided, focus only on those. No scope expansion. -- Implement substep by substep. Validate after each substep. Repair before moving on. No accumulation. -- Before package installation or generated build work, make sure `.gitignore` excludes `.env`, `.env.local`, `.env.*.local`, `node_modules/`, `dist/`, `.astro/`, coverage output, and tool caches. -- Never stage or commit generated artifacts (`node_modules/`, `dist/`, `.astro/`, coverage output, caches). -- If generated artifacts were already tracked before your work, remove them from version control in a dedicated hygiene commit before implementation or package installation. Do not mix those deletions with feature commits. If the caller explicitly says hygiene was already handled, verify with `git ls-files node_modules dist .astro coverage`. -- **After every ticked acceptance criterion, commit atomically** via `aidd-vcs:01-commit` with `mode: auto`, `message: "/: "`, `push: false`, or plain `git commit` if the VCS skill is unavailable. One acceptance criterion = one commit. Tasks within a phase guide HOW to implement and do not trigger commits - only the verified-state checkboxes (acceptance criteria) do. This is non-negotiable: the audit trail is the safety net. -- If the milestone involves providers, unit tests must use fixtures while integration tests must exercise the real provider code path. HTTP mocks/cassettes are acceptable only at the network boundary. -- If you cannot complete an item (technical blocker, ambiguity, missing dependency), record it in `items_remaining` and explain in `notes`. Don't fake completion. -- Be honest about `completion_score`. Underreporting is acceptable. Overreporting breaks the loop and produces silent failures. -- When done (fully or partially), return your output. The Planner decides what happens next. - -# Decisions in scope - -- Implementation choices: libraries, patterns, file layout, naming -- Substep decomposition inside the input scope -- Local refactors strictly within the input scope -- Atomic commit messages (one commit per ticked checkbox is mandatory; you decide the message wording) - -# Decisions out of scope - -- Modifying acceptance criteria - Planner -- Judging your own work - Reviewer -- Replanning, pivoting, expanding scope - surface in `items_remaining` + `notes` - -# Skills you may invoke - -- `aidd-dev:01-plan` (read-only - for context) -- `aidd-dev:03-assert` -- `aidd-dev:06-test` -- `aidd-dev:08-debug` -- `aidd-dev:04-audit` -- `aidd-dev:07-refactor` -- `aidd-vcs:01-commit` - -Anything else is out of bounds. - -# Handoffs - -- None. You return your output to the Planner who spawned you. - -# Guardrails - -- No TODOs in code, no skipped tests, no placeholder mocks. -- No silent workarounds. If you bypass a constraint, declare it in `notes`. -- When the work is physically impossible for the AI (see the implement skill's blocked reference for what counts), return `completion_score: 0` with `notes: "BLOCKED: "` — do not fake progress. You decide this block; the implement layer writes `status: blocked`. -- Stay strictly inside the input scope. -- Never modify the spec. -- Never start the Reviewer yourself - the Planner handles that based on your output. -- Never batch checkbox completions into a single commit. One ticked box = one commit, always. -- Never block because `Task`/`Agent` is unavailable; you do not need those tools. diff --git a/plugins/aidd-dev/agents/planner.md b/plugins/aidd-dev/agents/planner.md deleted file mode 100644 index d9532799..00000000 --- a/plugins/aidd-dev/agents/planner.md +++ /dev/null @@ -1,107 +0,0 @@ ---- -name: planner -description: Planning agent. Use when a validated spec must be turned into executable milestone plans, or when a top-level SDLC orchestrator needs a replan. Writes plans and decisions only. Never writes code, never judges code, never spawns implementer/reviewer agents. -model: opus ---- - -# Role - -You are the Planner. Your job is to turn an immutable spec into an executable plan with clear milestones, acceptance criteria, validation commands, and recorded decisions. - -The top-level `aidd-dev:00-sdlc` skill owns the implementation loop. Do not try to spawn implementer or reviewer agents. In Claude Code, agents spawned from `Agent` may not have `Agent` or `Task`; treating that as a blocker wastes the run. Return plans and structured decisions only. - -# Inputs - -When invoked, you receive: - -- A spec (path or inline content) - the immutable target -- Optionally, a working directory for plan and decision artifacts -- Optionally, a previous output from Implementer or Reviewer to interpret for replanning -- Optionally, a human message for clarification or replan - -# Outputs - -When you return, your output is a structured table: - -```yaml -plan_path: -child_paths: [] -decisions_made: - - id: - topic: - decision: - rationale: -decisions_blocked: - - id: - topic: - blocker: - needs: human_approval | clarification | external_input -notes: -``` - -`plan_path` and `child_paths` reflect what `aidd-dev:01-plan` actually wrote - the skill saves them in one feature folder `aidd_docs/tasks//_/`, the plan as `plan.md` and one phase file `phase-.md` next to it per phase. Capture them from the skill's output and surface them so the SDLC orchestrator can commit, summarize, and route to Phase 3 correctly. - -# Definition of Ready - -You may start when: - -- The spec exists and is non-empty -- The spec contains target, hard constraints, non-goals, and a "done-when" section -- If any of these are missing, escalate before producing anything - -# Definition of Done - -The plan is complete when: - -- Every milestone required by the spec is represented. -- Every milestone has tasks, acceptance criteria, validation commands, dependencies, and expected commit boundaries. -- The decisions table reflects all planning decisions made; blocked decisions are surfaced. - -# Behavior - -- Treat the spec as immutable. If it must change, escalate. -- Decompose the spec into milestones small enough for one Implementer pass. Each milestone has acceptance criteria and validation commands the Reviewer can execute. -- If the repo may contain tracked generated artifacts (`node_modules`, `dist`, `.astro`, coverage), include a preflight hygiene task or milestone that removes them from version control in a dedicated commit before any package install or feature work. -- If previous implementer/reviewer output is supplied, update the plan or produce a focused replan. Do not execute the fix yourself. -- Decide what counts as "satisfactory" based on the spec and the milestone, not on hardcoded numbers when the spec asks for tighter or looser standards. -- Keep the plan small enough to execute. Let the work decide the milestone count, each one a coherent unit sized for a single Implementer pass. -- Record any structural decision (architectural pivot, scope reduction, ambiguity resolution) in the decisions table. - -# Decisions in scope - -- Milestone decomposition and ordering -- Acceptance criteria granularity -- Intended architecture (high-level) -- What counts as "satisfactory quality" for this spec -- Decision records - -# Decisions out of scope - -- Implementation choices (libraries, patterns, file layout) - Implementer -- Quality scoring methodology - Reviewer -- Whether to start a new run - Gardener or human via `sdlc` -- Modifying the spec - escalate - -# Skills you may invoke - -- `aidd-refine:01-brainstorm` -- `aidd-refine:02-challenge` -- `aidd-context:09-mermaid` -- `aidd-context:10-learn` -- `aidd-dev:01-plan` - -Anything else is out of bounds. - -# Handoffs - -- Return `plan_path`, `child_paths`, `decisions_made`, and `decisions_blocked`. -- The top-level SDLC orchestrator will spawn `aidd-dev:implementer` and `aidd-dev:reviewer` itself. -- If a decision can be made conservatively, make it and record it. Prefer progress over escalation. -- Use `decisions_blocked` only for decisions that would make implementation unsafe or impossible. - -# Guardrails - -- Never edit the spec. -- Never touch source code. -- Never invoke or search for `Task`, `Agent`, or other spawn tools. They are not required in this role. -- No passive blocking. When in doubt, make a conservative planning assumption and record it unless the spec explicitly forbids that. diff --git a/plugins/aidd-dev/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md deleted file mode 100644 index 6abcc8ea..00000000 --- a/plugins/aidd-dev/agents/reviewer.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -name: reviewer -description: Independent critic in fresh context. Use when an artifact (code, spec, plan, doc) needs verification against a validator (acceptance criteria, checklist file, or any explicit ruleset). Returns reviewed items, findings, completion score and quality score. Never edits the artifact, never decides what to do next. -model: opus ---- - -# Role - -You start with no memory of how the artifact was produced. You judge what was delivered against an explicit validator. Skeptical by default. You describe what's wrong; you never fix it. You don't decide the next step - the caller (typically the Planner or SDLC) does. - -You review directly in your context. Do not spawn other agents. Do not search for `Task` or `Agent`; they are not part of this role. - -# Inputs - -When invoked, you receive: - -- An **artifact** to review - code changes, a spec document, a plan document, a doc, or any reviewable scope -- A **validator** - either explicit acceptance criteria (e.g., a milestone's criteria) OR a checklist file (YAML, JSON, or markdown) that enumerates the criteria -- Optionally, **context** - e.g., the spec when reviewing a plan, or the plan when reviewing code - -# Outputs - -When you return, your output is structured: - -```yaml -items_reviewed: - - criterion: - status: fulfilled | partial | unfulfilled - evidence: -findings: - - severity: critical | major | minor - description: - location: - suggested_fix: -completion_score: <0-100> # % of criteria you actually reviewed -quality_score: <0-100> # your overall quality assessment -notes: -``` - -# Definition of Ready - -You may start when: - -- The artifact is readable -- The validator is explicit (criteria are listed and unambiguous) - -If the validator is missing or ambiguous, return immediately with `completion_score: 0` and explain in `notes`. Don't guess. - -# Definition of Done - -Your output is complete when: - -- Every criterion has been judged (or explicitly skipped with reason in `notes`) -- A `completion_score` and a `quality_score` are reported with justification -- Findings are precise enough to act on without further investigation - -# Behavior - -- Start fresh. Don't try to reconstruct how the artifact was produced. Read the artifact, not the production history. -- For each criterion: inspect the relevant part of the artifact, run validation commands when applicable, mark as `fulfilled` / `partial` / `unfulfilled`. -- Surface incoherences (artifact contradicting context or other criteria) and omissions (criteria with no corresponding content). -- When reviewing any added instruction, criterion, finding, documentation sentence, or code rule, check whether an existing element already covers, overrides, contradicts, or makes it impossible. If so, report the parallel element and suggest deleting it, merging it into the stronger element, or rewriting the set with explicit scope, priority, and exception. - -| Case | What to detect | Example | Action | -| --- | --- | --- | --- | -| Subsumption | A stronger element already implies a weaker one. | "All fixtures must be TypeScript" plus "Do not add legacy fixture formats." | Delete the weaker element, or convert it into an example under the stronger one. | -| Override | A specific element changes a general one. | "All docs are English" plus "Onboarding examples may stay French." | Rewrite with explicit scope, priority, and exception. | -| Invalidation | One element makes another obsolete, impossible, or false. | A doc explains an active command that another doc says was removed. | Remove the invalid element, or mark it historical with a current replacement. | - -- For provider work, verify that fixture unit tests and real-provider integration tests are separated. Mocks/cassettes only pass if they exercise the real provider implementation and transformer. -- For frontend work, verify build/routing/design/accessibility contracts when they are in the validator. Do not accept screenshots or claims without command output or file evidence when a command can be run. -- Report findings with enough detail that the next pass can fix without guessing. -- When uncertain on a criterion, mark it `partial` and explain in `notes`. Don't bluff. -- Lean toward stricter scoring. False positives on quality cost less than false negatives. - -## Scoring protocol - -The way you compute `quality_score` depends on the validator format. - -- **YAML validator with `weights`, `hard_thresholds`, `scoring.pass_threshold`** (e.g. `spec-validator.yml`): - apply the file's protocol exactly. Don't substitute judgment. - 1. Score each criterion `fulfilled` (full weight) / `partial` (half weight) / `unfulfilled` (zero). - 2. Sum the weighted scores, normalize to 0–100 → that is `quality_score`. - 3. Apply `hard_thresholds`: any condition flagged forces `quality_score: 0` and `notes: "hard threshold violated: "`. Hard thresholds override the weighted sum, no exceptions. - 4. Required criteria unfulfilled → also forces `quality_score: 0`. - 5. The `scoring.pass_threshold` is the caller's gate - you don't decide pass/fail, you report the score. -- **Plain checklist (markdown bullets, no weights)**: - fall back to your earlier rule - `quality_score` is the proportion of fulfilled criteria, adjusted for severity of findings, with justification in `notes`. -- **Free-form criteria embedded in a milestone**: - same fall-back. Lean strict. - -# Decisions in scope - -- Per-criterion status with evidence -- Severity classification of each finding -- `completion_score` and `quality_score` with justification - -# Decisions out of scope - -- What to do next - caller (Planner or SDLC) -- Modifying the artifact -- Modifying the validator -- Escalating to human - caller - -# Skills you may invoke - -- `aidd-dev:05-review` -- `aidd-dev:04-audit` - -Anything else is out of bounds. - -# Handoffs - -- None. You return your output to the caller. - -# Guardrails - -- Never edit the artifact under review. -- Never modify the validator. -- Never block because `Task`/`Agent` is unavailable; you do not need those tools. -- If a criterion is ambiguous, flag in `notes`. Don't guess. -- Don't be lenient because the work "looks impressive". Score what's verifiable. -- Don't read production logs or status artifacts that would bias judgment. diff --git a/plugins/aidd-dev/skills/00-sdlc/README.md b/plugins/aidd-dev/skills/00-sdlc/README.md index f181f2f1..f588e49f 100644 --- a/plugins/aidd-dev/skills/00-sdlc/README.md +++ b/plugins/aidd-dev/skills/00-sdlc/README.md @@ -11,8 +11,8 @@ Holds no business logic of its own; every step is delegated. - A human (or upstream orchestrator) hands over a free-form request and you need to drive it end-to-end: spec, plan, implement, review, ship. -- You want the default autonomous run (`auto` mode) with no human prompts. -- You want the same flow but with confirmation gates (`interactive` mode). +- You want the default run with confirmation gates (`interactive` mode). +- You want an unattended run with no human prompts (`auto` mode). ## When NOT to use @@ -29,17 +29,18 @@ Holds no business logic of its own; every step is delegated. ## How to invoke ``` -/sdlc # auto mode (default) -/sdlc interactive # pauses at each gate for human confirmation +/sdlc # interactive (default): pauses at each gate +/sdlc auto # unattended: no human prompts ``` The skill walks 5 actions: 1. `spec` - consolidate sources, draft or refine the contract (skippable if the source ticket already carries objective + acceptance criteria). -2. `plan` - produce the mandatory plan file via the `planner` agent. -3. `implement` - loop milestones via the `implementer` agent until complete. -4. `review` - verdict `ship` or `iterate` via the `reviewer` agent; on +2. `plan` - produce the mandatory plan file by running `aidd-dev:01-plan` in + the orchestrator's own context (it owns the plan). +3. `implement` - loop milestones via the `executor` agent until complete. +4. `review` - verdict `ship` or `iterate` via the `checker` agent; on `iterate`, loop back to step 3 with findings. 5. `ship` - commit and open the pull request. @@ -47,15 +48,15 @@ The skill walks 5 actions: - A spec file (unless skipped). - A plan file in `aidd_docs/tasks/`. -- Atomic commits on the active branch, one per ticked checkbox. +- Atomic commits on the active branch, one per phase. - A pull request with title, body, base branch, and draft state. -- Findings + completion + quality scores from the reviewer. +- Findings + completion + quality scores from the checker. ## Prerequisites - HEAD is on a non-default branch when the run is meant to ship. `05-ship` aborts with `contract_violation: on_default_branch` otherwise. -- The `planner`, `implementer`, and `reviewer` agents are available. +- The `executor` and `checker` agents are available. - A VCS-providing capability is loaded at runtime for the ship step (commit + pull-request creation). diff --git a/plugins/aidd-dev/skills/00-sdlc/SKILL.md b/plugins/aidd-dev/skills/00-sdlc/SKILL.md index 6f650312..e7265a02 100644 --- a/plugins/aidd-dev/skills/00-sdlc/SKILL.md +++ b/plugins/aidd-dev/skills/00-sdlc/SKILL.md @@ -1,100 +1,30 @@ --- name: 00-sdlc -description: Pure orchestrator for the full AIDD development flow. Use when a human (or Gardener) needs to take a free-form request from idea to shipped code, end-to-end. Coordinates spec generation, planning, implementation, review, and shipping by composing other skills and agents. Supports two modes - `auto` (default, no human interaction) and `interactive` (pauses for human confirmation at key gates). Holds no business logic of its own; every step is delegated. +description: Orchestrate the full dev flow, a free-form request to shipped code, every step delegated. Use to take a request end to end, not a single step. Interactive by default; say auto for unattended. argument-hint: spec | plan | implement | review | ship --- # Skill: sdlc -Complete end-to-end software delivery. Defaults to autonomous; switches to interactive on demand. - -## Iron rule - -**You are the conductor, not a player.** - -You orchestrate skills and agents; you never write code yourself. - -You call agents by role: - -- `planner` - when scope must be planned -- `implementer` - when code must be written -- `reviewer` - when completed work must be verified - -## Mandatory steps (enforce - never skip) - -The flow has exactly ONE skippable step. Every other step is MANDATORY: it runs on every host (including weak-model hosts), in every mode (including `auto`), and for every change (including trivial ones). - -- `01-spec` - the ONLY skippable step, and only when the source ticket already carries an explicit objective + acceptance criteria (it then returns `spec_status = skipped`). -- `02-plan`, `03-implement`, `04-review`, `05-ship` - MANDATORY. Never skip, never collapse two into one, never declare the run done with one missing. Skipping any of them is a FAILED run, not a shortcut. - -Enforcement (self-check, not optional): - -- A mandatory step closes only when its `## Test` passes and its artifact exists: a plan file (02), implemented + validated milestones (03), a `04-review` verdict on the final diff (04), an opened change request (05). -- **`04-review` is non-negotiable: code is never shipped unreviewed.** If you arrive at `05-ship` without a `04-review` verdict on the final diff, STOP and run `04-review` first. -- Before declaring the SDLC complete, verify all four mandatory steps produced their artifact. If any is missing, the run is NOT done - resume at the missing step. Do not report success with a skipped step. - -## Modes - -| Mode | Trigger | Behavior | -| ------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------- | -| `auto` | default; `/sdlc `; orchestrator invocation | Never asks the human. All decisions yours. | -| `interactive` | `/sdlc interactive `; user says "interactive sdlc" | Pause at each gate listed below; wait for explicit human approval to proceed. | - -Detect the mode from `$ARGUMENTS` once, at skill entry, before dispatching the first action. +Take a request from idea to shipped code, delegating every step. Interactive by default, autonomous when you say `auto`. ## Actions -| # | Action | Role | Delegate | -| --- | ----------- | ---------------------------------------------------------------------- | ------------------------------ | -| 01 | `spec` | Consolidate sources, draft or refine the contract (skippable) | spec | -| 02 | `plan` | Produce the mandatory plan file | plan via `planner` | -| 03 | `implement` | Loop milestones until complete | implement via `implementer` | -| 04 | `review` | Verdict `ship` or `iterate` | review via `reviewer` | -| 05 | `ship` | Commit and open a change request via the project's VCS | commit, pull-request | - -Files: `@actions/01-spec.md` ... `@actions/05-ship.md`. - -## Default flow - -`01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop back to `03` with the findings as the implementer's fix list. After each action, run its `## Test` before moving to the next. - -`01-spec` self-skips (returns `spec_status = skipped`) when the source ticket already carries an explicit objective + acceptance criteria. It is the ONLY skippable step. `02-plan`, `03-implement`, `04-review`, `05-ship` are mandatory and never skipped (see **Mandatory steps**). - -## Interactive gates - -Activate only in `interactive` mode. In `auto` mode, never pause. - -1. **After `01-spec`** - show the spec (or the extracted objective + acceptance criteria when skipped); confirm contract. -2. **After `02-plan`** - show the plan; confirm scope before any code change. -3. **After each phase of `03-implement`** - show the phase output; confirm before continuing. -4. **After `04-review`** - show findings and verdict; confirm ship vs iterate. -5. **Before `05-ship` opens the change request** - show title, body, base branch, draft state; confirm before creation. - -If the human pushes back at a gate, route their feedback into the relevant action (spec refinement, plan revision, implementation rerun, review re-spawn) before re-proposing the next gate. - -## Runtime tracking - -Materialize the flow as a task list at skill entry; it MUST contain every mandatory step (02-plan, 03-implement, 04-review, 05-ship) plus 01-spec unless skipped. A task closes only when its `## Test` passes and its artifact exists; a mandatory task is never closed by skipping it. - -## Rules - -- In `auto` mode, you are alone and never ask the human; all decisions are yours. -- In `interactive` mode, the human owns the gate decisions; you still decide everything between gates. -- Always run `02-plan`. Minimum: frontmatter + M/C/D + rules table + phases. Never inline ticket or spec as plan. -- Skip allowed: `01-spec` only (when the source already carries objective + acceptance criteria). `02-plan`, `03-implement`, `04-review`, `05-ship` are mandatory and enforced (see **Mandatory steps**); skipping any is a failed run. -- Choose the best decision based on the facts. -- Open a change request (pull or merge request) via the project's VCS once implementation is reviewed and complete. -- **Branch discipline (caller responsibility).** SDLC runs on whatever branch is checked out when invoked; it never auto-branches. The caller (manual user or upstream orchestrator) is responsible for putting HEAD on a non-default branch before invoking SDLC when the run is meant to ship through a PR. - -## References +| # | Action | Role | Delegate | +| --- | ----------- | ------------------------------------- | --------------------------------------- | +| 01 | `spec` | Consolidate sources into the contract | a spec capability | +| 02 | `plan` | Produce the plan file | self, via `aidd-dev:01-plan` | +| 03 | `implement` | Build the plan's code | `executor`, via `aidd-dev:02-implement` | +| 04 | `review` | Verdict `ship` or `iterate` | `checker`, via `aidd-dev:05-review` | +| 05 | `ship` | Open the change request | a commit and change-request capability | -- `spec` -- `plan` -- `implement` -- `review` -- `commit` -- `pull-request` +Run `01 → 02 → 03 → 04 → 05`. On `04 = iterate`, loop to `03` then re-run `04`. -## Assets +## Transversal rules -- None. +- Delegate every step; never write or judge code yourself. +- Mode: default `interactive`, pausing for approval at each step; switch to `auto` only when the caller says so, then decide alone and never ask. +- Every step runs; only `01-spec` self-skips when the source already states an objective and acceptance criteria. +- Drive the plan status `pending → in-progress → implemented → reviewed`, or `blocked`. +- Every artifact (spec, plan, phases, review) lands in one feature folder, `aidd_docs/tasks//_/`, resolved at entry. +- Never auto-branch; the caller sets a non-default branch before shipping. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md index bf458b02..bb5483a2 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/01-spec.md @@ -2,30 +2,24 @@ Consolidate every available source into the normalized contract consumed downstream. -**Skip condition:** if the source ticket already carries an explicit objective + at least one acceptance criterion, set `spec_status = skipped`, surface them verbatim, jump to action 02. +**Skip condition:** when the source ticket already carries an explicit objective and at least one acceptance criterion, set `spec_status = skipped`, surface them verbatim, and jump to `02`. -## Inputs +## Input -- `request` - raw `$ARGUMENTS` (free-form text or ticket URL) -- `sources` - one or more of: ticket body, existing PRD, in-session conversation, prior reviewer findings -- `working_dir` - repo root +The raw `$ARGUMENTS` (free-form text or a ticket URL), any available sources (ticket body, existing PRD, in-session conversation, prior checker findings), and the repo root. -## Outputs +## Output -```yaml -spec_path: -spec_status: drafted | refined | skipped -objective: -acceptance_criteria: [] -``` +The spec path on disk with its status (`drafted`, `refined`, or `skipped`), the one-sentence objective, and the acceptance criteria. The path is null when skipped. ## Process -1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot reviewer findings, capture conversation turns. Concatenate into a single brief. -2. **Skip check.** Apply the skip condition above. If skipped, return. -3. **Delegate.** Hand the consolidated brief and `working_dir` to `spec`; let it own contract generation and refinement. -4. **Return** `spec_path`, `spec_status`, `objective`, `acceptance_criteria` to the SDLC orchestrator. +1. **Collect.** Resolve every non-empty source: fetch ticket bodies, read PRD files, snapshot checker findings, capture conversation turns. Concatenate them into one brief. +2. **Skip.** Apply the skip condition above. If it holds, return the extracted objective and criteria. +3. **Delegate.** Hand the consolidated brief and the repo root to a spec capability, discovered at runtime by description. Let it own contract generation and refinement. +4. **Return.** Surface the spec path, status, objective, and acceptance criteria. ## Test -When `spec_status` is `drafted` or `refined`, `spec_path` exists on disk and the file's frontmatter carries the same `objective` and non-empty `acceptance_criteria` returned by this action; when `skipped`, `spec_path` is null and both fields are extracted verbatim from the source ticket. +- When the status is `drafted` or `refined`, the spec file exists and its frontmatter carries the same objective and non-empty acceptance criteria this action returns. +- When `skipped`, the path is null and both fields are taken verbatim from the source ticket. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md index 18cd89ed..b67b2b45 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/02-plan.md @@ -1,29 +1,21 @@ # 02 - Plan -Turn the spec (or raw request when spec was skipped) into a validated plan file. Mandatory. +Turn the spec, or the raw request when spec was skipped, into a validated plan file. Mandatory. -## Inputs +## Input -- `spec_path` (from 01) - null when skipped -- `objective`, `acceptance_criteria` (from 01) - required -- `request` - raw `$ARGUMENTS`, required when `spec_path` is null -- `working_dir` - repo root +The spec path from `01` (null when skipped), the objective and acceptance criteria from `01`, the raw `$ARGUMENTS` (needed when there is no spec), and the repo root. -## Outputs +## Output -```yaml -plan_path: -child_paths: [] -decisions_made: [...] -decisions_blocked: [...] -``` +The plan path and its phase paths, plus the decisions you made and any you could not make alone. ## Process -1. **Spawn planner** (`planner` agent) with the inputs above. Brief: run `plan` end to end (URL detection, ticket fetch, normalization, architecture projection, rules selection, phase breakdown). Never inline raw ticket or spec as the plan body. -2. **Read output.** Capture the YAML returned by the planner. -3. **Return** it as-is to the SDLC orchestrator. +1. **Author.** Run `aidd-dev:01-plan` end to end in your own context. You own the plan: it is the contract the executor may not rewrite, so you write it, never a worker. Never inline a raw ticket or spec as the plan body. +2. **Capture.** Read the plan path, the phase paths, and the decisions the plan records. +3. **Return.** Surface them for the next step. ## Test -`plan_path` exists on disk; its frontmatter contains `objective`, `status: pending`; the plan's `objective` matches the spec's `objective` (or the request when spec was skipped). +- The plan file exists, its frontmatter carries `objective` and `status: pending`, and the plan's objective matches the spec's (or the request when spec was skipped). diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md index 8e04a447..41c686c8 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/03-implement.md @@ -1,31 +1,25 @@ # 03 - Implement -Build a milestone, apply a fix list, or finish a remaining scope via the implementer agent. Mandatory. +Build the plan's code by spawning the `executor` agent to run the `aidd-dev:02-implement` recipe, which loops the phases, drives status, and validates. Mandatory. -## Inputs +## Input -- one of `milestone` (with acceptance criteria), `fix_list`, `items_remaining` - required -- `spec_slice` - relevant portion of the spec (optional) -- `validation_commands` - shell commands the implementer must run before reporting done (optional) -- `plan_path` (from 02) +The plan path from `02` (required), and on an `iterate` loop-back the review findings to hand over as a fix list (optional). -## Outputs +## Output -```yaml -items_implemented: [...] -items_remaining: [...] -completion_score: 0-100 -``` +The plan reaches `status: implemented`, every phase `done`, validation green. Or it stops at `status: blocked` when a human is needed. ## Process -1. **Mark in-progress.** Set `status: in-progress` in the plan frontmatter at `plan_path` (skip if already set). Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -2. **Spawn implementer** (`implementer` agent) with the inputs above. Brief: run `implement` for the milestone or fix list, then `assert` + `test`. -3. **On failure**, run `debug` and re-spawn the implementer with the diagnostic notes until tests pass. -4. **Blocked.** If the implementer surfaces `BLOCKED` in `notes`, write `status: blocked` in the plan frontmatter at `plan_path`, stop (do NOT proceed to 04), and escalate to a human. -5. **Mark implemented.** When the whole plan is implemented (no milestones remain, last pass `items_remaining` empty), set `status: implemented` in the plan frontmatter at `plan_path`. -6. **Return** the implementer's YAML as-is to the SDLC orchestrator. +1. **Implement.** Spawn the `executor` agent and brief it to run the `aidd-dev:02-implement` recipe on `plan_path`. The agent branches, codes every phase, commits the code and the status transitions, and validates. +2. **Iterate.** When the step runs after an `iterate` verdict, spawn the `executor` again and hand it the findings as a fix list. It codes the fixes against the current diff, then asserts and validates them before returning, exactly as the recipe gates a phase: a fix is finished only when it passes. Do not edit the plan or its phases: the loop fixes what was implemented, not the plan. +3. **Resolve.** Read the plan's final `status`. + - `implemented`: the step is done. + - `blocked`: a human-only condition stopped the run. Do not continue. Escalate to a human. ## Test -`completion_score` is an integer between 0 and 100; `items_implemented` and `items_remaining` are present; the validation commands return exit code 0; when fully implemented the plan's frontmatter `status` is `implemented` (or `blocked` if it surfaced a blocker, stopping before 04). +- The plan `status` is `implemented`, or `blocked` when a human-only condition stopped it. +- Every phase reads `status: done`. +- The validation commands return exit code 0. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md index 91ce3f92..1e48469b 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/04-review.md @@ -2,29 +2,25 @@ Judge the completed work against an explicit validator and emit a ship-or-iterate verdict. -## Inputs +## Input -- `artifact` - working diff or paths produced by 03 (required) -- `validator` - `plan_path` + `acceptance_criteria` from upstream (required) -- `context` - related artifacts the reviewer needs to inspect (optional) +The working diff or paths produced by `03`, the validator (the plan path and acceptance criteria), and any related context the checker needs. -## Outputs +## Output -```yaml -verdict: ship | iterate -items_reviewed: [...] -findings: [...] -completion_score: 0-100 -quality_score: 0-100 -``` +A `ship` or `iterate` verdict with the reviewed items, the findings, the completion and quality scores, and the reviewed `HEAD` SHA (the commit the checker actually saw). The plan reaches `status: reviewed` on ship, and stays `implemented` on iterate. ## Process -1. **Spawn reviewer** (`reviewer` agent) with the inputs above. Brief: run `review` (code + functional) and return the YAML. -2. **Map verdict.** All checks pass → `verdict = ship`. Any blocking finding → `verdict = iterate`. -3. **Write status.** `ship` → set `status: reviewed` in the plan frontmatter at `plan_path`. `iterate` → set `status: in-progress` before looping back. Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -4. **Iterate loop.** When `verdict = iterate`, return the findings as the next `fix_list` for action 03. +1. **Capture.** Record `git rev-parse HEAD` as the reviewed SHA. This is the exact code the checker judges, and the anchor `05-ship` checks against. +2. **Spawn.** Spawn the `checker` agent with the inputs above. Brief it to run `aidd-dev:05-review`, code, functional, and relevancy, on that diff, and return its verdict. +3. **Map.** When every check passes, the verdict is `ship`. On any blocking finding, the verdict is `iterate`. +4. **Mark.** On `ship`, set the plan frontmatter `status: reviewed` and commit it. Carry the reviewed SHA in the verdict. On `iterate`, leave the plan `implemented`: the loop fixes the diff, not the plan. +5. **Iterate.** On `iterate`, return the findings as the fix list for `03`. The next `04` re-captures the SHA on the fixed diff; ship is reached only when a review of the current diff passes. ## Test -`verdict` is `ship` or `iterate`; `completion_score` and `quality_score` are integers between 0 and 100; `findings` is non-empty when `verdict = iterate`; the plan's frontmatter `status` is `reviewed` on `ship`, `in-progress` on `iterate`. +- The verdict is `ship` or `iterate`, and the scores are integers between 0 and 100. +- The verdict carries the reviewed `HEAD` SHA. +- The findings are non-empty on `iterate`. +- The plan frontmatter reads `status: reviewed` only after a `ship` verdict on the current diff. diff --git a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md index beccb625..91c7d816 100644 --- a/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md +++ b/plugins/aidd-dev/skills/00-sdlc/actions/05-ship.md @@ -2,26 +2,24 @@ Commit and open a change request (pull or merge request) via the project's VCS once the review verdict is `ship`. -## Inputs +## Input -- `verdict = ship` (from 04) - required -- `plan_path` (from 02) - required -- `phase_results` (from 03) - optional, drives the commit and change-request body +The `ship` verdict from `04` including its reviewed `HEAD` SHA, the plan path from `02`, and the phase results from `03` that drive the commit and the change-request body. -## Outputs +## Output -```yaml -commit_sha: -change_request_url: -``` +The commit SHA and the change-request URL on the project's VCS host. ## Process -0. **Review gate (mandatory, run first).** Confirm `04-review` produced a verdict on the FINAL diff and that verdict is `ship`. If no review verdict exists, or it covers an older diff, or the verdict is `iterate`, STOP: do not commit, do not open a request. Run `04-review` first (loop back to `03-implement` on `iterate`). Code is never shipped unreviewed. -1. **Commit.** Invoke `commit` with a Conventional Commits message derived from the plan's `objective`. -2. **Push and open.** Invoke `pull-request` to push the branch and open the change request. Reference `plan_path` in the body. -3. **Return** `commit_sha` and `change_request_url` to the SDLC orchestrator. +1. **Gate.** Confirm `04` produced a `ship` verdict and that no code landed after the reviewed SHA it carries. Run `git diff --name-only HEAD`: it must list only plan-tracking files (the `chore(plan): reviewed` commit and the like). Any source-code change means the reviewed verdict is stale and the new code is unreviewed: stop, run `04` on the current diff, looping back to `03` on `iterate`. If no verdict exists or it is `iterate`, stop the same way. Code is never shipped unreviewed. +2. **Commit.** Invoke a commit capability, discovered at runtime, with the plan's objective. It picks the message format; never dictate one here. +3. **Open.** Invoke a change-request capability, discovered at runtime, to push the branch and open the request. Reference the plan path in the body. +4. **Return.** Surface the commit SHA and the change-request URL. ## Test -`commit_sha` exists in `git log` of the working branch; `change_request_url` is a non-empty URL pointing to the project's VCS host; the change-request body references `plan_path`. +- `git diff --name-only HEAD` lists only plan-tracking files: no source change shipped unreviewed. +- The commit SHA exists in `git log` of the working branch. +- The change-request URL is non-empty and points to the project's VCS host. +- The change-request body references the plan path. diff --git a/plugins/aidd-dev/skills/01-plan/SKILL.md b/plugins/aidd-dev/skills/01-plan/SKILL.md index ba696e19..1633df04 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,6 +1,6 @@ --- name: 01-plan -description: Turn a request, ticket, or file into a phased implementation plan: gather the source, explore the codebase, optionally wireframe a screen, then plan. Use when the user wants to plan a feature, turn a ticket or requirements into a phased plan, or wireframe a screen before building. Do NOT use to write code (use 02-implement), review a diff (use 05-review), or audit code (use 04-audit). +description: Turn a request, ticket, or file into a phased implementation plan. Use to plan a feature before building, or to turn a ticket into phases. Do NOT use to write code or review a diff. argument-hint: gather | explore | wireframe | plan --- diff --git a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md index becde37e..22d9571c 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/01-gather.md +++ b/plugins/aidd-dev/skills/01-plan/actions/01-gather.md @@ -12,8 +12,8 @@ The source restated in a few bullets: what is asked and the hard constraints it ## Process -1. **Find the source.** Identify what the request points to: a file path, a ticket URL or id, or raw text. When nothing concrete is given, ask once for a file, a ticket, or a description. Do not start without a source. -2. **Pull it in.** Read the file, fetch the ticket, or take the text as given. Never invent content the source does not contain. +1. **Find.** Identify what the request points to: a file path, a ticket URL or id, or raw text. When nothing concrete is given, ask once for a file, a ticket, or a description. Do not start without a source. +2. **Pull.** Read the file, fetch the ticket, or take the text as given. Never invent content the source does not contain. 3. **Restate.** Summarize the source in a few bullets: what is asked, and the hard constraints it states. No solution, no phases, no plan. ## Test diff --git a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md index 8f3226d7..33a6916d 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/02-explore.md +++ b/plugins/aidd-dev/skills/01-plan/actions/02-explore.md @@ -12,9 +12,9 @@ The architecture projection (files to modify, create, delete, each with a one-li ## Process -1. **Read the codebase.** Explore the code the source touches. Build the projection and list the infrastructure assumptions. -2. **Check feasibility.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks. -3. **Select rules.** Keep the project rules that apply to the projection. +1. **Read.** Explore the code the source touches. Build the projection and list the infrastructure assumptions. +2. **Check.** Verify against the official docs or the in-repo code. Keep each source and what it settled. Flag blockers and risks. +3. **Select.** Keep the project rules that apply to the projection. ## Test diff --git a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md index 5aa3bf1a..53d8b3a5 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md +++ b/plugins/aidd-dev/skills/01-plan/actions/03-wireframe.md @@ -12,7 +12,7 @@ A low-fidelity ASCII wireframe of each screen, its regions and key elements in p ## Process -1. **Pick the screens.** List the screens the feature needs. Skip the action entirely when there is no UI. +1. **Pick.** List the screens the feature needs. Skip the action entirely when there is no UI. 2. **Draw.** Sketch each screen per `@../references/wireframe-conventions.md`. The wireframe feeds the plan. ## Test diff --git a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md index 214791ec..d37c8c10 100644 --- a/plugins/aidd-dev/skills/01-plan/actions/04-plan.md +++ b/plugins/aidd-dev/skills/01-plan/actions/04-plan.md @@ -8,11 +8,11 @@ The explore output from `02-explore` (projection, rules, feasibility, risks), pl ## Output -A feature folder `aidd_docs/tasks//_/` holding `plan.md` from `@../assets/plan-template.md` and one `phase-.md` per phase from `@../assets/phase-template.md`. +A feature folder, always at `aidd_docs/tasks//_/`, 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. +1. **Phases.** Break the work into phases, each a coherent unit of work that ships and verifies on its own, sized for one executor pass. Let the work decide how many. 2. **Write.** Resolve the feature folder: reuse the one the source already lives in, otherwise create it. Scaffold from the templates and fill the placeholders. Fill only the sections the template defines, add nothing it does not, and omit any section that stays empty (for example resources when nothing was consulted). Slice the projection into each phase, put the resources consulted (docs or in-repo files) in the resources table, and embed any wireframe in its phase's Wireframe section. Display the paths. 3. **Review.** Show the complete plan and its phases with a confidence score (0 to 10, ✓ reasons and ✗ risks). Take feedback, revise the files, and re-show until approved. The score is never written to the plan. diff --git a/plugins/aidd-dev/skills/01-plan/references/plan-status.md b/plugins/aidd-dev/skills/01-plan/references/plan-status.md index 7d537560..51e98bf1 100644 --- a/plugins/aidd-dev/skills/01-plan/references/plan-status.md +++ b/plugins/aidd-dev/skills/01-plan/references/plan-status.md @@ -9,15 +9,15 @@ The plan's `status` frontmatter field tracks its lifecycle for kanban views. The | status | meaning | written by | when | | ------------- | ----------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------- | -| `pending` | created, not started | `01-plan` | at plan creation | -| `in-progress` | implementation started | implement layer (SDLC `03-implement`; standalone `02-implement`) | when implementation starts | -| `implemented` | implemented, not yet reviewed | implement layer | all phases complete / all acceptance criteria ticked | -| `reviewed` | reviewed and approved | review layer (SDLC `04-review`) | the review passes (approved) | -| `blocked` | cannot proceed; needs a human | implement layer | a blocking condition holds (see the implement skill's blocked reference) | +| `pending` | created, not started | plan creation | at plan creation | +| `in-progress` | implementation started | the implement step | when implementation starts | +| `implemented` | implemented, not yet reviewed | the implement step | all phases complete / all acceptance criteria ticked | +| `reviewed` | reviewed and approved | the review step | the review passes (approved) | +| `blocked` | cannot proceed; needs a human | the implement step | a blocking condition holds | ## Rules - Linear: `pending → in-progress → implemented → reviewed`. `blocked` is reachable from any active state. -- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed` → status returns to `in-progress`. +- Review reject (`iterate` / `changes-requested`) does NOT set `reviewed`. The plan stays `implemented` while the loop fixes the diff, not the plan. - `implemented` ≠ reviewed. Only the review layer sets `reviewed`. -- The reviewer and implementer agents never write `status`; only plan creation (`01-plan`) and the orchestration layers do. +- Workers never write `status`; only plan creation and the orchestration layers do. diff --git a/plugins/aidd-dev/skills/02-implement/README.md b/plugins/aidd-dev/skills/02-implement/README.md index 8708a777..7184125d 100644 --- a/plugins/aidd-dev/skills/02-implement/README.md +++ b/plugins/aidd-dev/skills/02-implement/README.md @@ -2,23 +2,18 @@ # 02 - implement -Executes an existing implementation plan phase by phase via the `implementer` -agent, iterating until every acceptance criterion is satisfied. Each phase -loops until the agent reports 100 % completion. +Executes an existing implementation plan phase by phase, iterating until every acceptance criterion is satisfied. Tracks status in the plan and phase frontmatter as it goes. ## When to use -- A plan produced by [01-plan](../01-plan/README.md) is ready and you need - the code written end-to-end against it. -- An iteration of [00-sdlc](../00-sdlc/README.md) is delegating the - `implement` step to this skill. +- A plan produced by [01-plan](../01-plan/README.md) is ready and you need the code written against it. +- An iteration of [00-sdlc](../00-sdlc/README.md) delegates the implement step. ## When NOT to use - No plan exists yet → use [01-plan](../01-plan/README.md) first. -- The plan is wrong and needs replanning → amend the plan, not the code. -- The task is a bug fix without a plan surface → use - [08-debug](../08-debug/README.md). +- The plan is wrong and needs replanning → replan with [01-plan](../01-plan/README.md); this skill never rewrites the plan. +- A bug fix with no plan surface → use [08-debug](../08-debug/README.md). ## How to invoke @@ -26,29 +21,25 @@ loops until the agent reports 100 % completion. Use skill aidd-dev:02-implement ``` -Pass the plan path or content as `$ARGUMENTS`. The skill exposes 1 action: +Pass the plan path or content as `$ARGUMENTS`. The skill runs three actions in order: -1. `implement` - loop each plan phase: spawn the `implementer` agent, wait - for structured output, re-spawn with `items_remaining` until the phase - hits 100 %. Branching is the caller's responsibility; this skill never - creates branches. Plan amendments are made inline and tagged with the - robot marker. +1. **prepare**: fails fast when the plan is missing (never fabricates one); puts `HEAD` on a feature branch when it is on the default branch, otherwise keeps the current branch; sets the plan `status: in-progress`. +2. **execute**: loops the plan's phases: per phase it sets `status: in-progress` as a runtime marker, codes the phase, asserts it clean, then commits the phase and sets `status: done`; stops at `status: blocked` on a human-only condition. +3. **finalize**: runs validation, then marks the plan `status: implemented` once every phase is done. + +**Commits**: code and status are committed together, one commit per phase, plus a final `implemented` commit. The `in-progress` marks are runtime-only, so the tree is never left dirty at a phase boundary. ## Outputs -- Code changes on the active branch, one phase at a time. -- `phases_completed` count and `acceptance_satisfied: true` when done. -- Plan amendments inline in the plan file when the loop discovers gaps. +- Code for the feature, one phase at a time, committed on the active feature branch, one commit per phase. +- Plan and phase frontmatter status driven `pending → in-progress → done / implemented`, or `blocked`. +- A `replan needed` report when the plan no longer matches reality; this recipe never rewrites the plan. ## Prerequisites -- A plan file with phases, M/C/D, and acceptance criteria. -- The `implementer` agent available in context. -- Project rules already loaded for the implementer to respect. +- A plan file with phases and acceptance criteria, from `01-plan`. +- Project conventions honoured by whoever runs the recipe. ## Technical details -See [`SKILL.md`](SKILL.md) and -[`actions/01-implement.md`](actions/01-implement.md) for the phase loop -contract, the re-spawn rule, and the boundary constraints (no formatting, -no dev mode). +See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the prepare/execute/finalize split: the branch guard, the phase loop, the assert gate, the status lifecycle, and the boundary constraints (no formatting, no dev mode). diff --git a/plugins/aidd-dev/skills/02-implement/SKILL.md b/plugins/aidd-dev/skills/02-implement/SKILL.md index eeff95ff..65dfdd57 100644 --- a/plugins/aidd-dev/skills/02-implement/SKILL.md +++ b/plugins/aidd-dev/skills/02-implement/SKILL.md @@ -1,24 +1,28 @@ --- name: 02-implement -description: Execute an implementation plan phase by phase via the implementer agent, iterating until 100% completeness. -context: fork -agent: implementer +description: Write an existing plan's code, phase by phase, until every acceptance criterion holds. Use when a plan exists and needs implementing. Do NOT use to write a plan, review a diff. +argument-hint: prepare | execute | finalize --- # Skill: implement -Run an existing technical plan to write code, validating each phase before moving on. +Run an existing plan to write its code, one phase at a time, until every acceptance criterion holds. -## Agent delegation +## Actions -Spawn the `implementer` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `implementer` agent explicitly with this skill's content as the prompt. +| # | Action | Role | Input | +| --- | ---------- | ----------------------------------------------- | ------------- | +| 01 | `prepare` | Resolve the plan, branch, mark it in-progress | a plan path | +| 02 | `execute` | Loop the phases, code and assert each | prepared plan | +| 03 | `finalize` | Verify and mark the plan implemented | coded phases | -## Actions +Run them in order, `01 → 03`. + +## Transversal rules -```markdown -@actions/01-implement.md -``` +- Status: drive the plan through `pending → in-progress → implemented` (or `blocked`), and each phase through `pending → in-progress → done`. The `in-progress` values are runtime markers; only `done` and `implemented` need to land in a commit. +- Commits: one commit per phase, its code together with the phase reaching `done`, plus a final commit for the plan reaching `implemented`. Never leave the tree dirty at a phase boundary. Do not scatter separate `in-progress` status commits: one context now owns both code and status, so there is nothing to guard against. ## References -- `@references/blocked.md` - conditions that make a plan `blocked` (needs a human). All actions inherit it. +- `references/blocked.md`: the conditions that make a plan `blocked` and need a human. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md b/plugins/aidd-dev/skills/02-implement/actions/01-implement.md deleted file mode 100644 index bd2b87de..00000000 --- a/plugins/aidd-dev/skills/02-implement/actions/01-implement.md +++ /dev/null @@ -1,39 +0,0 @@ -# 01 - Implement - -Code the whole feature based on the implementation plan, phase by phase, sequentially, until every acceptance criterion is satisfied. - -## Inputs - -```yaml -plan: -branch: # optional; created when the plan specifies one -``` - -## Outputs - -```yaml -phases_completed: -acceptance_satisfied: true -notes: - - -``` - -## Process - -1. **Resolve the plan (fail-fast).** Resolve the plan from `$ARGUMENTS`. When it is a path, the file must exist and be readable. If neither a readable plan file nor inline plan content is available, stop immediately with the error `plan not found at ` and do nothing else. Never fabricate a substitute plan. -2. **Branch.** Create a new branch if the plan specifies one (`git checkout -b `). Set `status: in-progress` on the plan. Status values and their meaning come from the plan-status reference (`01-plan/references/plan-status.md`) - the single source of truth; never restate the table here. -3. **Phase loop.** For each phase the plan lists, in order. When the plan is a feature folder, each phase is a `phase-.md` next to `plan.md`; open it for the scope, tasks, and acceptance criteria. - - Set the phase frontmatter `status: in-progress`. - - Spawn the `implementer` agent via the `Task` tool, passing that phase's scope and acceptance criteria. - - Wait for the agent's structured output. If `completion_score < 100`, re-spawn with `items_remaining` until the phase reaches 100 %. - - Set the phase frontmatter `status: done` once it reaches 100 %. -4. **Plan amendments.** If a phase is incorrect, incomplete, or blocked by missing information, amend the plan directly. Mark every change with 🤖 and a brief rationale. -5. **Boundaries.** Never format code. Never run dev mode. Follow project rules already loaded in context. -6. **Verify the feature.** Run validation commands, tests, and any manual checks required to confirm the feature works end to end. -7. **Blocked.** If the implementer surfaces `BLOCKED` in its notes (see the blocked reference), set `status: blocked` and stop the loop. -8. **Mark implemented.** Every phase at 100% + validation passes → set `status: implemented`. - -## Test - -- A missing or unreadable plan path with no inline plan content stops the skill with `plan not found at `, and no substitute plan is fabricated. -- After the loop terminates: every phase has its acceptance criteria checked off and its frontmatter `status` is `done`, validation commands exit zero, and the plan's frontmatter `status` is `implemented` — OR, if a blocking condition held, the loop stopped and it is `blocked`. diff --git a/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md new file mode 100644 index 00000000..1879ce66 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/01-prepare.md @@ -0,0 +1,23 @@ +# 01 - Prepare + +Resolve the plan, put the workspace on a feature branch, and mark the plan in-progress. + +## Input + +A plan, passed via `$ARGUMENTS` as a path or inline content. + +## Output + +The resolved plan on a feature branch with its frontmatter `status: in-progress`, ready for the phase loop. Or a fail-fast stop when no plan resolves. + +## Process + +1. **Resolve.** Resolve the plan from `$ARGUMENTS`. A path must exist and be readable. With neither a readable file nor inline content, stop with `plan not found at `. Never fabricate a plan. +2. **Branch.** On the default branch, run `git checkout -b ` and announce it. On a non-default branch, keep it. +3. **Mark.** Set the plan frontmatter `status: in-progress` as a runtime marker. No separate commit: it rides into the first phase commit, or into the `implemented` commit if there is no phase to code. + +## Test + +- A missing or unreadable plan with no inline content stops with `plan not found at `, and no plan is fabricated. +- `git rev-parse --abbrev-ref HEAD` is not the default branch. +- The plan frontmatter reads `status: in-progress`. diff --git a/plugins/aidd-dev/skills/02-implement/actions/02-execute.md b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md new file mode 100644 index 00000000..dc020553 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/02-execute.md @@ -0,0 +1,25 @@ +# 02 - Execute + +Loop the plan's phases in order, coding each until every acceptance criterion holds. + +## Input + +The prepared plan on its feature branch, from `01-prepare`. + +## Output + +Every phase coded, asserted, and its frontmatter marked `status: done`, with the commits on the branch. Or a stop at `status: blocked` when a human is needed, or a `replan needed` report on any drift from the plan. + +## Process + +1. **Open.** Walk the phases in order. In a feature folder each is a `phase-.md` next to `plan.md`. Set its `status: in-progress` as a runtime marker; no commit yet. +2. **Code.** Build the phase scope against its acceptance criteria. +3. **Assert.** Assert the phase against its acceptance criteria. On failure, repair and repeat. The gate is the assertion passing, not a self-report. Only once it passes, set `status: done` and commit the phase as one unit, its code and its status together. +4. **Blocked.** On `BLOCKED` (see `@../references/blocked.md`), set the plan `status: blocked`, commit it, and stop the loop. +5. **Drift.** Follow the plan as written. Never rewrite it. On any mismatch, trivial or substantive, stop and report `replan needed: ` to the caller. Replanning is the caller's job, not this recipe's. + +## Test + +- A phase reaches `status: done` only after assert passes against its acceptance criteria, in one commit with its code (`git status --short` shows no dangling phase edits). +- The branch holds one commit per phase; there are no separate `in-progress` status commits. +- A blocker leaves the plan `status: blocked` with no later phase run. diff --git a/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md new file mode 100644 index 00000000..2943bc42 --- /dev/null +++ b/plugins/aidd-dev/skills/02-implement/actions/03-finalize.md @@ -0,0 +1,21 @@ +# 03 - Finalize + +Run the validation and mark the plan implemented once every phase is done. + +## Input + +A plan whose phases are all `status: done`, from `02-execute`. + +## Output + +The feature validated green with the plan frontmatter `status: implemented`. + +## Process + +1. **Verify.** Run the plan's validation commands and tests. Never format code, never run dev mode. +2. **Mark.** Every phase done and validation green, set the plan `status: implemented` and commit it. + +## Test + +- The validation commands exit zero. +- The plan reads `status: implemented`, committed (`git status --short` shows it clean). diff --git a/plugins/aidd-dev/skills/02-implement/references/blocked.md b/plugins/aidd-dev/skills/02-implement/references/blocked.md index 3bdd7dc6..505a3389 100644 --- a/plugins/aidd-dev/skills/02-implement/references/blocked.md +++ b/plugins/aidd-dev/skills/02-implement/references/blocked.md @@ -4,6 +4,7 @@ description: Conditions that make a plan blocked (needs a human). --- # When a plan is blocked -`blocked` = implementation cannot proceed; only a human can unblock. Stop, set `status: blocked`, escalate. + +`blocked` means implementation cannot proceed and only a human can unblock it. Stop, set `status: blocked`, and escalate. Physically impossible for the AI (no retry helps): real credit-card payment; human login (Google OAuth, Apple Face/Touch ID); a secret the AI cannot read; anything behind hardware or 2FA. diff --git a/plugins/aidd-dev/skills/03-assert/README.md b/plugins/aidd-dev/skills/03-assert/README.md index c0a9c069..2d79a27d 100644 --- a/plugins/aidd-dev/skills/03-assert/README.md +++ b/plugins/aidd-dev/skills/03-assert/README.md @@ -2,13 +2,13 @@ # 03 - assert -Validates implementations through iterative assertion loops. Covers general -feature assertions, architecture conformance (ADRs, diagrams, project -structure), and browser-based frontend UI checks. +A gate that validates the work behaves as intended: it iterates the project's +coding assertions until they pass, with optional architecture-conformance and +running-frontend facets. Returns a pass or fail verdict. ## When to use -- A feature is implemented and you need to assert it behaves as intended +- Work is implemented and you need to assert it behaves as intended before merging or shipping. - You need to verify code conforms to documented architecture (ADRs, diagrams, structure). @@ -30,21 +30,19 @@ structure), and browser-based frontend UI checks. Use skill aidd-dev:03-assert ``` -The skill exposes 3 actions: +The skill exposes 3 facets, run together when applicable or one when named: -1. `assert` - general assertion loop against an acceptance criterion. -2. `assert-architecture` - verify code matches architecture diagrams, - ADRs, and the project's documented structure. -3. `assert-frontend` - drive a browser to confirm a frontend feature - behaves as intended. +1. `assert` - the coding-assertion loop; always applies. +2. `assert-architecture` - report where code breaks the documented + architecture (ADRs, diagrams, structure); report only, opt-in. +3. `assert-frontend` - drive a browser to confirm the frontend + behaves as intended; needs a running frontend (it resolves the URL). ## Outputs -- A pass / fail verdict per assertion, with the failing item identified. -- Recorded findings when an assertion fails (file, line, expected vs - observed). -- Browser session artifacts (screenshots, console output) for the - frontend variant. +- A pass or fail verdict on the work (this is a gate, not a stored report). +- The fixes applied by the coding and frontend facets. +- The conformance violations from the architecture facet. ## Prerequisites diff --git a/plugins/aidd-dev/skills/03-assert/SKILL.md b/plugins/aidd-dev/skills/03-assert/SKILL.md index 6594114d..7e03bdd0 100644 --- a/plugins/aidd-dev/skills/03-assert/SKILL.md +++ b/plugins/aidd-dev/skills/03-assert/SKILL.md @@ -1,34 +1,30 @@ --- name: 03-assert -description: Assert features work as intended - general assertions, architecture conformance, and frontend UI validation. +description: Assert the work behaves: iterate the project's coding assertions until they pass, plus optional architecture and frontend facets. Use to validate an implementation. Do NOT use to review or write tests. argument-hint: assert | assert-architecture | assert-frontend model: sonnet --- # Skill: assert -Validates correctness of implementations through iterative assertion loops, architecture checks, and browser-based frontend verification. +Validate that the work behaves as intended: run the project's assertions, iterating and fixing until they pass. -## Available actions - -| # | Action | When to use | -| --- | --------------------- | ---------------------------------------------------------------------------- | -| 01 | `assert` | Iterate until a feature works by running the project's coding assertions | -| 02 | `assert-architecture` | Verify the codebase conforms to documented architecture (C4, ADRs, tree) | -| 03 | `assert-frontend` | Iterate until a frontend feature works by inspecting the running UI | +## Actions -## Routing (run first) +| # | Action | Facet | +| --- | --------------------- | ----------------------------------------------------------- | +| 01 | `assert` | Run the project's coding assertions, fixing until they pass | +| 02 | `assert-architecture` | Report where the code breaks the documented architecture | +| 03 | `assert-frontend` | Inspect the running UI, fixing until the behavior is right | -These actions are complementary facets, not mutually exclusive. This skill is run-one-OR-run-all: +Run every applicable facet by default, or one when named. Coding (`01`) always applies; add `03` when the work has a UI and a frontend is running, the facet resolving the URL itself; run `02` only when architecture conformance is asked for. Skip a facet whose precondition is absent, with a noted reason. Ask only when the intent is genuinely ambiguous. -- The user named a facet ("assert the frontend", "check architecture conformance") -> run that ONE action. -- The user asked for an unscoped assertion ("assert this works", "make the feature pass") -> ask ONE question: "Assert everything applicable, or a specific facet (coding / architecture / frontend)?" Then run all applicable, or the chosen one. -- Never silently default to action 01. Never run a blind all without offering the choice first. +## Transversal rules -When running all applicable: `01-assert` is the baseline (project coding assertions); add `03-assert-frontend` when the feature has a UI and a running frontend URL; add `02-assert-architecture` when architecture conformance is in scope. A facet whose precondition is absent (e.g. no running URL) is skipped with a noted reason, never forced. Run the selected actions in order (01, then 03, then 02). Read and follow each selected action file. +- Gate: it returns a pass or fail verdict on the work. +- Fix loop: the coding and frontend facets fix and re-run until they pass. The architecture facet only reports, never fixes. +- Stop only when every selected assertion passes a final clean sweep. -## Actions +## Assets -- `@actions/01-assert.md` -- `@actions/02-assert-architecture.md` -- `@actions/03-assert-frontend.md` +- `assets/task-template.md`: the tracking file the frontend facet fills across its fix loop. diff --git a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md index cea380da..b744f5f0 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/01-assert.md +++ b/plugins/aidd-dev/skills/03-assert/actions/01-assert.md @@ -1,32 +1,23 @@ # 01 - Assert -Iterate until a feature works as intended by running the project's coding assertions and fixing every failure. +Iterate the project's coding assertions until the work passes every one, fixing each failure. -## Inputs +## Input -```yaml -feature: -``` +The work to assert, named or described, from `$ARGUMENTS` or the context. -## Outputs +## Output -```yaml -assertions_total: -assertions_passing: -iterations: -fixes_applied: - - { file: , change: } -``` +A pass or fail verdict: every applicable assertion passing in a final clean sweep, with the fixes applied listed. ## Process -1. **Enumerate assertions.** From the current context (project conventions and coding-assertions memory), list the assertions that apply to the feature. -2. **Iterate per assertion.** For each one: - - Fix any issues preventing it from passing. - - Re-run the assertion to confirm it passes. -3. **Full re-check.** Once every assertion has passed at least once, re-run all of them in one sweep to confirm none regressed. -4. **Boundary.** Do not stop until every assertion passes in the final sweep. +1. **Enumerate.** List the assertions that apply, from the project conventions and `aidd_docs/memory/coding-assertions.md` when it exists. +2. **Iterate.** For each assertion, fix what blocks it, then re-run it until it passes. +3. **Sweep.** Once each has passed at least once, re-run them all in one pass to confirm none regressed. +4. **Boundary.** Do not stop until every assertion passes the final sweep. ## Test -The final sweep reports `assertions_passing == assertions_total`; the recorded `fixes_applied` list cites real diffs (no empty or placeholder entries when fixes were claimed). +- The final sweep passes every applicable assertion. +- The fixes listed cite real diffs, with no placeholder entries. diff --git a/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md b/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md index 8125bcd1..1500fa60 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md +++ b/plugins/aidd-dev/skills/03-assert/actions/02-assert-architecture.md @@ -1,48 +1,24 @@ # 02 - Assert Architecture -Verify that the codebase (or a specific scope) conforms to the documented architecture: C4 diagrams, ADRs, and project tree structure. +Report where the codebase breaks the documented architecture: C4 diagrams, ADRs, and the project tree. -## Inputs +## Input -```yaml -scope: # optional; defaults to the entire project -``` +The scope to check, a module, service, or layer, from `$ARGUMENTS`; defaults to the whole project. -## Outputs +## Output -```yaml -report: - macro: - - { severity: critical|warning, file: , constraint: , fix: } - micro: - - { severity: critical|warning, file: , constraint: , fix: } -totals: - violations_total: - critical: - warning: -``` +A conformance report listing each violation, grouped macro and micro, with severity, file, the constraint broken, and a one-line fix. Report only; it never fixes. ## Process -1. **Load architecture context.** - - Remember the architecture diagrams from `aidd_docs/memory/architecture.md`. - - Read micro diagrams from `aidd_docs/memory/internal/` when the scope targets a specific module. - - Read ADRs from `aidd_docs/internal/decisions/`. - - Extract the expected project tree structure from the diagrams. -2. **Verify macro architecture (service boundaries).** - - Compare actual code structure against the documented tree. - - Flag files outside expected boundaries. - - Flag direct imports between independent services. -3. **Verify micro architecture (internal layers).** For each module in scope: - - Check that import directions match layer constraints. - - Confirm the domain layer has zero external imports. - - Confirm the application layer depends only on the domain via ports. - - Detect circular dependencies between modules. - - Verify the expected patterns (use cases have ports, adapters implement interfaces). -4. **Build the violation report.** Each entry carries severity (`critical | warning`), file path, the constraint violated, and a one-line suggested fix. Group entries macro vs micro. -5. **Boundary.** Do not fix violations - only report them. If no scope is provided, check the entire project. -6. **Summarize.** Total violations, critical count, recommended next actions. +1. **Load.** Read the architecture sources: the architecture memory, the micro diagrams for an in-scope module, and the decision records. Extract the expected project tree. +2. **Macro.** Compare the code structure against the documented tree. Flag files outside their boundary and direct imports between independent services. +3. **Micro.** For each in-scope module, check import directions against the layer constraints. The domain layer imports nothing external. The application layer reaches the domain only through ports. No circular dependencies. Adapters implement their interfaces. +4. **Report.** One entry per violation, grouped macro and micro, each with severity (`critical` or `warning`), file, constraint, and a one-line fix. Never fix, only report. +5. **Summarize.** The total violations, the critical count, and the recommended next actions. ## Test -If conformity holds: `violations_total == 0` and the report explicitly states "no violations" in both macro and micro sections. If violations exist: every report entry has a real file path that exists on disk, a referenced constraint that appears in one of the loaded architecture sources, and a non-empty `fix` field. +- On conformance, the report states "no violations" in both the macro and micro sections. +- On violations, every entry has a real file path, a constraint drawn from a loaded architecture source, and a non-empty fix. diff --git a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md index 92ae09f4..c26d9bc4 100644 --- a/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md +++ b/plugins/aidd-dev/skills/03-assert/actions/03-assert-frontend.md @@ -1,40 +1,26 @@ # 03 - Assert Frontend -Iterate until a frontend feature works as intended by inspecting the running UI, mapping the behavior to the code, and tracking attempts in a task template. +Iterate until the frontend behaves as intended by inspecting the running UI, mapping behavior to code, and tracking attempts. -## Inputs +## Input -```yaml -expected_behavior: -url: # required; the frontend must already be running -``` +The expected behavior, from `$ARGUMENTS`. The frontend's URL when the caller knows it, otherwise resolved at runtime. -## Outputs +## Output -```yaml -task_template_path: -iterations: -fixed: true|false -report: - - { iteration: , hypothesis: , fix_attempted: , validated: pass|fail } -``` +A pass or fail verdict, with the per-iteration attempts (hypothesis, fix, result) recorded in the tracking file. ## Process -Iterate over the steps below until the feature works as intended. - -1. **Parse the request.** Extract expected requirements (visual, functional, technical) from `expected_behavior`. Summarize and list action paths (e.g. user clicks button -> calls function in file1 -> updates state in file2). -2. **Inspect the running app.** Open the URL via the configured browsing tool. Inspect the page visually and technically. Take screenshots to confirm the issue. -3. **Locate the code.** Explore the codebase to find the files and snippets related to the issue. -4. **Fill the tracking template** from `@../assets/task-template.md`. List the three best potential causes with a short description and confidence level. -5. **Fix-loop.** - - Take the first potential cause. - - Apply a candidate fix. - - Validate against the expected behavior. - - If not fixed, mark the cause and move to the next. - - When the three causes are exhausted, re-evaluate, add three new causes to the template, and repeat from step 5. -6. **Boundaries.** Assume all servers are already running. Minor visual discrepancies (1-2 px differences, slight color variations) are acceptable unless explicitly specified in the initial request. Screenshots MUST be used to validate UI changes. +1. **Resolve.** Use the URL the caller gave, otherwise find the running frontend and confirm it responds. Skip this facet with a noted reason when none is running. +2. **Parse.** Extract the visual, functional, and technical requirements from the expected behavior. Trace the action paths, for example a click calls a function in one file that updates state in another. +3. **Inspect.** Open the URL with the project's configured browser tool and navigate to the screen the expected behavior targets. Inspect the page visually and technically, capturing a screenshot of the issue. +4. **Locate.** Explore the codebase for the files behind the issue. +5. **Track.** Fill the tracking file from `@../assets/task-template.md` with the three best candidate causes, each with a short description and a confidence level. +6. **Fix.** Take a cause, apply a candidate fix, validate against the expected behavior. On failure, mark it and take the next. When the three are exhausted, add three fresh causes and repeat. +7. **Boundary.** Never start or restart a server. Accept minor visual differences (1 to 2 px, slight color) unless the request specifies otherwise. Confirm every UI change with a screenshot. ## Test -The task template file exists and is updated for every iteration; the final entry in `report` has `validated: pass`; the running URL renders the expected behavior, confirmed by a screenshot recorded after the final iteration. +- The tracking file updates on every iteration. +- The final recorded attempt validates as a pass, confirmed by a screenshot taken after it. diff --git a/plugins/aidd-dev/skills/03-assert/assets/task-template.md b/plugins/aidd-dev/skills/03-assert/assets/task-template.md index cdc9e1db..dc2beec2 100644 --- a/plugins/aidd-dev/skills/03-assert/assets/task-template.md +++ b/plugins/aidd-dev/skills/03-assert/assets/task-template.md @@ -1,15 +1,11 @@ ---- -name: task -description: Task tracking system to ensure all tasks are categorized and addressed ---- + # Task [] {{Full description}} -## Main step 1} +## Main step 1 - [ ] {Task 1} - [ ] {Task 2} - [ ] {Task 3} -- ... diff --git a/plugins/aidd-dev/skills/05-review/README.md b/plugins/aidd-dev/skills/05-review/README.md index 72003c6f..e258791a 100644 --- a/plugins/aidd-dev/skills/05-review/README.md +++ b/plugins/aidd-dev/skills/05-review/README.md @@ -2,18 +2,17 @@ # 05 - review -Reviews completed work along two axes: code quality against project rules, -and feature behavior against the plan's acceptance criteria. Runs in a -fresh context via the `reviewer` agent and returns findings plus completion -and quality scores. Never edits the artifact. +Reviews a diff along three axes: code quality (clean-code), feature behavior +against the plan's acceptance criteria, and relevancy (does the change belong: +fit to the need, declared-rule conformance, no rot). Read-only: surfaces +findings and one verdict into a single report, never edits the artifact. Runs +all three axes by default, or one when named. ## When to use - A feature is implemented and you need an independent verdict before shipping. -- An iteration of [00-sdlc](../00-sdlc/README.md) is delegating the - `review` step to this skill. -- A diff needs a rule-based code review without ad-hoc opinion. +- A diff needs a grounded review without ad-hoc opinion. ## When NOT to use @@ -28,37 +27,42 @@ and quality scores. Never edits the artifact. ## How to invoke ``` -Use skill aidd-dev:05-review +Use skill aidd-dev:05-review # all three axes +Use skill aidd-dev:05-review review-relevancy # one named axis ``` -The skill exposes 2 actions: +The skill exposes 3 axes, run together by default or one when named: -1. `review-code` - grade the diff against project rules; surface - violations with file, line, and rule reference. +1. `review-code` - grade the diff against clean-code principles; surface + violations with file and line. 2. `review-functional` - verify the feature against the plan's acceptance - criteria; emit per-criterion pass / fail. + criteria; per-criterion trace plus missing / unplanned / edge-case gaps. +3. `review-relevancy` - judge whether the change belongs: fit to the need, + conformance to the project's declared rules, and no duplication or + over-engineering. ## Outputs -- A read-only report (never patches the code): - - `review-code` - a verdict (`approve` / `changes-requested` / `blocked`) - plus a findings table with 3-level severity (🔴 critical / 🟡 warning / - 🟢 minor), `file:line`, issue, and a suggested fix to hand off to - [07-refactor](../07-refactor/README.md). - - `review-functional` - a verdict (`PASS` / `PARTIAL` / `FAIL`) and a - per-criterion scoring matrix; missing or broken behaviors hand off to - [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). -- The `reviewer` agent still returns `ship` / `iterate` to the SDLC - orchestrator. +- One read-only `review.md` in the reviewed work's feature folder, beside + `plan.md`, never patches the code: + - Header: the overall verdict (`approve` / `changes-requested` / `blocked`, + the strictest across the axes run), scope, axes run, findings count. + - `Code` section: severity-rated findings (🔴 / 🟡 / 🟢) with `file:line`; + fixes hand off to [07-refactor](../07-refactor/README.md). + - `Functional` section: per-criterion matrix plus the gap lists; fixes hand + off to [02-implement](../02-implement/README.md) / [08-debug](../08-debug/README.md). + - `Relevancy` section: misfits by lens (`fit` / `conform` / `rot`), each + tied to a rule, a duplication site, a smell, or a named need-gap. + - An axis not run is marked "Not run". ## Prerequisites - A diff or a set of changes to review. - A plan file with explicit acceptance criteria for the functional axis. -- Project rules loaded in context for the code axis. +- The project's declared rules, discovered at runtime, for the relevancy axis. ## Technical details -See [`SKILL.md`](SKILL.md) and [`actions/`](actions/) for the two -review contracts. The skill runs the `reviewer` agent in fresh context to -avoid bias from the implementation conversation. +See [`SKILL.md`](SKILL.md), [`actions/`](actions/), and the report template in +[`assets/`](assets/) for the three review axes and the single report they +compose. diff --git a/plugins/aidd-dev/skills/05-review/SKILL.md b/plugins/aidd-dev/skills/05-review/SKILL.md index b5d2fdbc..6e0e4894 100644 --- a/plugins/aidd-dev/skills/05-review/SKILL.md +++ b/plugins/aidd-dev/skills/05-review/SKILL.md @@ -1,37 +1,37 @@ --- name: 05-review -description: Read-only review of a diff (a PR or working changes) - code quality against project rules, and feature behavior against the plan's acceptance criteria. Surfaces findings with a verdict; never patches. Use to review changes in progress. Do NOT use for a whole-codebase health check (use 04-audit), fixing the findings (hand off to 07-refactor / 02-implement / 08-debug), or validating a feature runs (use 03-assert). -argument-hint: review-code | review-functional +description: Read-only review of a diff on three axes, code, behavior versus the plan, and relevancy, into one verdict report. Use before shipping a change. Do NOT use to fix findings or audit a codebase. +argument-hint: review-code | review-functional | review-relevancy model: opus -context: fork -agent: reviewer --- # Skill: review -Read-only review of a diff (a PR or working changes): code quality against project rules, and feature behavior against the plan's acceptance criteria. It surfaces findings and a verdict; it never edits code. The fix hands off to the act-skills (`07-refactor` for code, `02-implement` / `08-debug` for behavior gaps). Diff-scoped - for a whole-codebase read-only diagnosis use `aidd-dev:04-audit` instead. +Read-only review of a diff along three axes, code quality, feature behavior, and relevancy, composed into one report. -## Agent delegation - -Spawn the `reviewer` agent to execute this skill. For tools that do not support `context: fork` frontmatter: invoke the `reviewer` agent explicitly with this skill's content as the prompt. +## Actions -## Available actions +| # | Action | Axis | +| --- | ------------------- | ---------------------------------------------------------------- | +| 01 | `review-code` | Clean-code quality on the changed lines | +| 02 | `review-functional` | The diff against the plan's acceptance criteria | +| 03 | `review-relevancy` | Does the change belong: fit to the need, rule conformance, no rot | -| # | Action | When to use | -| --- | ------------------- | ------------------------------------------------------------------------ | -| 01 | `review-code` | Quality review of a diff against project rules and clean-code principles | -| 02 | `review-functional` | Verify the diff matches the plan's acceptance criteria, flows, edge cases | +Run all three by default, composing one report. Run a single axis only when the caller names it; if it is unclear whether they want all or one, ask. -## Routing (run first) +## Transversal rules -Pick the ONE action matching the user's intent; do NOT default to action 01. +- Read-only: surface each finding with its fix described, never patch. +- Output: always write `review.md` to disk; the file is the deliverable, never an inline-only verdict. +- Folder: write into the reviewed work's feature folder (`aidd_docs/tasks//_/`, beside `plan.md`), or one resolved from the change when it has none. +- Sections: fill `review.md` from `@assets/review-template.md`, each axis its own section, an unrun axis marked "Not run". +- Re-run: overwrite `review.md` with the current review. It is a snapshot of the current diff, not a history; a later review of the same work replaces the earlier one. +- Verdict: one overall verdict, the strictest across the axes run, per `@references/review-rubric.md`. -- "review the code", "check code quality", "rules compliance", "clean code review" -> `01-review-code` -- "does it match the plan", "functional review", "behavior vs acceptance criteria" -> `02-review-functional` +## References -If the intent is ambiguous, ask one clarifying question before picking. Then read and follow only the matching action file. +- `references/review-rubric.md`: the severity scale, the verdict rule, the code categories, and the relevancy lenses. -## Actions +## Assets -- `@actions/01-review-code.md` -- `@actions/02-review-functional.md` +- `assets/review-template.md`: the single report the three axes fill. diff --git a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md index 0d2dc108..795e7582 100644 --- a/plugins/aidd-dev/skills/05-review/actions/01-review-code.md +++ b/plugins/aidd-dev/skills/05-review/actions/01-review-code.md @@ -1,34 +1,23 @@ # 01 - Review Code -Deep code review of a diff against project rules and clean-code principles. Read-only: surface quality violations only, never patch them - hand fixes off to `aidd-dev:07-refactor`. +Grade the diff against clean-code principles and record the findings in the review report. -## Inputs +## Input -```yaml -scope: # optional; defaults to `git diff main` -``` +The diff to review, a git ref range or path, from `$ARGUMENTS`; defaults to `git diff main`. -## Outputs +## Output -```yaml -review_path: aidd_docs/tasks//_/review.md -verdict: approve | changes-requested | blocked -findings_count: -severity_breakdown: - critical: # 🔴 - warning: # 🟡 - minor: # 🟢 -``` +The `Code` section of the feature folder's `review.md`, filled with severity-rated findings, each citing a changed `file:line`. ## Process -1. **Resolve the diff.** Use `$ARGUMENTS` when provided; otherwise fall back to `git diff main`. -2. **Deep review every changed line.** Apply project conventions and global clean-code principles. No runtime checks. -3. **Findings only.** Focus on issues on the changed lines; do not propose feature-level changes. Rate each with the 3-level severity (🔴 critical / 🟡 warning / 🟢 minor) and cite a `file:line`. Suggested fixes are described, not patched (read-only). -4. **Set the verdict** per the template: `blocked` if any unaddressed 🔴, `changes-requested` if 🟡 (or a fixable 🔴), else `approve`. -5. **Format the report** using `@../assets/review-code-template.md` (Expected changes, Findings, Coverage, Follow-up). Top fixes hand off to `aidd-dev:07-refactor`. -6. **Write to disk** at `aidd_docs/tasks//_/review.md`. Reuse the feature folder of the reviewed work when it exists, otherwise create it. +1. **Resolve.** Take the diff from `$ARGUMENTS`, otherwise `git diff main`. +2. **Review.** Read every changed line for clean-code: naming, structure, complexity, smells, error handling. No runtime checks. Declared-rule conformance belongs to the relevancy axis, not this one. +3. **Rate.** One finding per issue on the changed lines, rated and categorized per `@../references/review-rubric.md`, citing a `file:line`. Describe the fix, never patch. +4. **Record.** Write the findings into the `Code` section of `review.md`, each with its fix described. ## Test -The review file exists at the emitted `review_path`; it has a defined `verdict`; every finding row carries a 3-level severity and cites a changed `file:line`; the report contains the Findings and Coverage sections from `@../assets/review-code-template.md`. No code was patched. +- The `Code` section of `review.md` is filled, every finding rated and citing a changed `file:line`. +- No code is patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md index 4b3bd0a0..1495f071 100644 --- a/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md +++ b/plugins/aidd-dev/skills/05-review/actions/02-review-functional.md @@ -1,45 +1,24 @@ # 02 - Review Functional -Verify the implemented feature matches the plan's acceptance criteria, flows, and edge cases. Static review of the current diff against plan intent. No app execution, no browser, no code-quality checks. Read-only: surface gaps, never patch them - hand a missing behavior off to `aidd-dev:02-implement`, a broken one to `aidd-dev:08-debug`. +Verify the diff matches the plan's acceptance criteria, flows, and edge cases, and record the result in the review report. -## Inputs +## Input -```yaml -plan_path: # required via $ARGUMENTS or prompt -diff_scope: # optional; defaults to `git diff main` -``` +The plan path holding the acceptance criteria, from `$ARGUMENTS` or the prompt, and the diff to trace (a git ref range; defaults to `git diff main`). -## Outputs - -```yaml -review_path: aidd_docs/tasks//_/review-functional.md -criteria_total: -criteria_traced: -missing_behaviors: -unplanned_behaviors: -edge_case_gaps: -``` - -## Rules - -Check against: - -- Inconsistencies -- Duplications -- Non logical Flows or Steps +## Output +The `Functional` section of the feature folder's `review.md`: one row per acceptance criterion traced to the diff, plus the missing, unplanned, and edge-case gaps. ## Process -1. **Read the plan.** Use `plan_path` from `$ARGUMENTS` when provided; otherwise ask the user to supply the acceptance criteria directly. -2. **Extract acceptance criteria.** If they exist in the plan, ask the user to validate them before proceeding. If missing, ask the user to provide them. -3. **Fetch the diff.** Use `diff_scope` when provided; otherwise `git diff main`. -4. **Trace each criterion to the diff.** Fill the scoring matrix with one row per acceptance criterion. -5. **List missing behaviors** (criteria with no trace in the diff). -6. **List unplanned behaviors** (diff changes that trace to no criterion). -7. **List flow and edge-case gaps** surfaced by walking through each criterion. -8. **Format and write** the report using `@../assets/review-functional-template.md` to `aidd_docs/tasks//_/review-functional.md`. Reuse the feature folder of the reviewed work when it exists, otherwise create it. +1. **Read.** Take the plan from `$ARGUMENTS`; if absent, ask for the acceptance criteria, and mark this axis "Not run" when none are available. Static review only, no app execution or browser. +2. **Trace.** Fetch the diff, then trace each acceptance criterion to it, one matrix row per criterion: met, partial, or unmet, with evidence or the gap. +3. **Gaps.** List missing behaviors (criteria with no trace), unplanned behaviors (diff changes tracing to no criterion), and flow or edge-case gaps. An empty list reads "none", never omitted. +4. **Record.** Write the matrix and the gaps into the `Functional` section of `review.md`, each with the missing or broken behavior named. ## Test -The report file exists at the emitted `review_path`, contains a scoring matrix with exactly one row per acceptance criterion, and includes explicit `Missing behaviors`, `Unplanned behaviors`, and `Edge-case gaps` sections (empty sections show an explicit "none" rather than being omitted). +- The `Functional` section of `review.md` holds exactly one row per acceptance criterion. +- The missing, unplanned, and edge-case lists are present, each reading "none" when empty. +- No code is patched. diff --git a/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md new file mode 100644 index 00000000..f56f04cc --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/actions/03-review-relevancy.md @@ -0,0 +1,24 @@ +# 03 - Review Relevancy + +Judge whether the diff belongs, coherent with the codebase, its conventions and declared rules, serving the real need, with nothing duplicated or over-built, and record the misfits in the review report. + +## Input + +The diff to review (a git ref range or path; defaults to `git diff main`), the need it serves (the plan objective or the ticket), and the project's declared rules and conventions, discovered at runtime. + +## Output + +The `Relevancy` section of the feature folder's `review.md`, filled with misfit findings under the lenses `fit`, `conform`, and `rot`, each tied to evidence. + +## Process + +1. **Gather.** Resolve the diff from `$ARGUMENTS`, otherwise `git diff main`. Capture the need from the plan objective or the ticket. Discover the project's declared rules and conventions at runtime, never hardcoded. Fall back cleanly when a source is absent. +2. **Fit.** Check the change against the need: does it serve the actual intent end to end, or only the literal criteria? Flag any drift between intent and result. +3. **Conform.** Check the change against the declared rules and the surrounding conventions. Flag each violation with the rule or pattern it breaks. +4. **Rot.** Scan for duplication (an existing helper reinvented), over-engineering (speculative generality, unused abstraction), and incoherence (naming, docs versus code). Cite the site. +5. **Record.** Write each finding into the `Relevancy` section of `review.md`, rated and placed under its lens per `@../references/review-rubric.md`. A bare opinion is not a finding: tie each to a declared rule, a duplication site, an over-engineering smell, or a named need-gap. Describe the fix, never patch. + +## Test + +- The `Relevancy` section of `review.md` is filled, every finding under a lens and tied to a `file:line`, a declared rule, a duplication site, or a named need-gap. +- No finding is a bare opinion, and no code is patched. diff --git a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md b/plugins/aidd-dev/skills/05-review/assets/review-code-template.md deleted file mode 100644 index 2fbff291..00000000 --- a/plugins/aidd-dev/skills/05-review/assets/review-code-template.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: review-code -description: Code review report template for a diff -argument-hint: N/A ---- - -# Code Review: {{feature}} - -{{one_line_summary}} - -- **Verdict**: {{approve | changes-requested | blocked}} -- **Diff scope**: `{{base}}...{{head}}` -- **Date**: {{yyyy_mm_dd}} -- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor - -Verdict: `approve` = no critical findings, ship it; `changes-requested` = warnings or a fixable critical to address first; `blocked` = a critical that must not merge. - -## Expected changes - -What the diff was meant to deliver (from the ticket or plan). Tick what the diff actually does. - -- [ ] {{expected_change_1}} -- [ ] {{expected_change_2}} - -## Findings - -One row per issue, on the CHANGED lines only (this is a diff review, not a codebase audit). Every row cites a `file:line`. Sort by severity. Read-only: describe the fix, do not patch it - hand fixes off to `aidd-dev:07-refactor`. - -Severity: 🔴 critical (must not merge as-is), 🟡 warning (should fix), 🟢 minor (nit). -Category (one of): `standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. - -| Sev | Category | Location | Issue | Suggested fix | -| --- | ----------- | --------------------- | ------------------------------------ | ------------------------------------ | -| 🔴 | security | `src/api/user.ts:30` | Request body used without validation | Validate with the project schema lib | -| 🟡 | code-health | `LivePreview.tsx:43` | `user` recomputed on every render | Memoize with `useMemo` | - -## Coverage - -Dimensions examined on the diff (a dimension with no finding is still listed here as scanned; one not applicable to this diff is marked n/a). - -- **Scanned**: {{dimensions examined, comma-separated}} -- **Not applicable**: {{dimensions n/a for this diff, or "none"}} - -## Follow-up - -- **Top fixes** (ranked, hand off to `aidd-dev:07-refactor`): {{top_fixes}} -- **Notes**: {{additional_notes}} diff --git a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md b/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md deleted file mode 100644 index 9de9d828..00000000 --- a/plugins/aidd-dev/skills/05-review/assets/review-functional-template.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -name: review-functional -description: Functional review report template for a diff against a plan -argument-hint: N/A ---- - -# Functional Review: {{feature}} - -- **Plan**: `{{plan_path}}` -- **Diff scope**: `{{base}}...{{head}}` -- **Date**: {{yyyy_mm_dd}} - -## Verdict - -{{PASS | PARTIAL | FAIL}} - {{one_line_rationale}} - -Verdict: `PASS` = every criterion Met; `PARTIAL` = some criteria Partial or Unmet but none blocking; `FAIL` = at least one 🔴 blocking gap. - -## Scoring Matrix - -One row per acceptance criterion. Severity uses the shared 3-level scale (it applies to `Partial` / `Unmet` rows only). - -| Criterion | Files | Status | Severity | Notes | -| ---------------- | ----- | --------------------- | --------------------------------- | ----- | -| {{criterion}} | | Met / Partial / Unmet | 🔴 blocker / 🟡 major / 🟢 minor | | - -- Status - `Met`: fully implemented in the diff; `Partial`: implemented with gaps; `Unmet`: absent from the diff. -- Severity - 🔴 blocker: feature cannot ship; 🟡 major: shipping degrades UX; 🟢 minor: cosmetic or non-blocking. - -## Missing behaviors - -Acceptance criteria with no trace in the diff (hand off implementation to `aidd-dev:02-implement`; if a criterion is implemented but broken, hand off to `aidd-dev:08-debug`). - -- [ ] {{criterion not found in diff}} - -## Unplanned behaviors - -Changes present in the diff but traced to no acceptance criterion. - -- [ ] {{unplanned change - confirm scope with author}} - -## Flow / edge-case gaps - -Gaps surfaced while walking each criterion against the diff. - -- [ ] {{flow or edge-case gap}} - -## Summary - -- **Criteria covered**: {{x/y}} -- **Blockers**: {{count}} -- **Follow-up actions**: {{actions}} -- **Additional notes**: {{notes}} diff --git a/plugins/aidd-dev/skills/05-review/assets/review-template.md b/plugins/aidd-dev/skills/05-review/assets/review-template.md new file mode 100644 index 00000000..8c6df3ad --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/assets/review-template.md @@ -0,0 +1,43 @@ + + +# Review: {{feature}} + +{{one_line_summary}} + +- **Verdict**: {{approve | changes-requested | blocked}} +- **Diff scope**: `{{base}}...{{head}}` +- **Axes run**: {{code, functional, relevancy}} +- **Date**: {{yyyy_mm_dd}} +- **Findings**: {{n_critical}} critical, {{n_warning}} warning, {{n_minor}} minor + +Verdict: `approve` = ship it; `changes-requested` = fix the warnings or fixable criticals first; `blocked` = a critical that must not merge. The overall verdict is the strictest across the axes run. + +## Code + +Clean-code findings on the changed lines (or "Not run"). + +| Sev | Category | Location | Issue | Suggested fix | +| --- | -------- | -------- | ----- | ------------- | + +## Functional + +Each acceptance criterion traced to the diff (or "Not run"). + +| Criterion | Met | Evidence / gap | +| --------- | --- | -------------- | + +- **Missing behaviors**: {{criteria with no trace, or "none"}} +- **Unplanned behaviors**: {{diff changes tracing to no criterion, or "none"}} +- **Edge-case gaps**: {{gaps, or "none"}} + +## Relevancy + +Does the change belong (or "Not run"). Every finding ties to evidence, never an opinion. + +| Sev | Lens | Location / rule | Misfit | Suggested fix | +| --- | ---- | --------------- | ------ | ------------- | + +## Follow-up + +- **Top fixes** (ranked): {{top_fixes}} +- **Notes**: {{additional_notes}} diff --git a/plugins/aidd-dev/skills/05-review/references/review-rubric.md b/plugins/aidd-dev/skills/05-review/references/review-rubric.md new file mode 100644 index 00000000..759ee612 --- /dev/null +++ b/plugins/aidd-dev/skills/05-review/references/review-rubric.md @@ -0,0 +1,27 @@ +# Review rubric + +Shared definitions for the three review axes. The actions and the report template draw from here, so the scales live in one place. + +## Severity + +- 🔴 critical: must not merge as-is. +- 🟡 warning: should fix. +- 🟢 minor: nit. + +## Verdict + +One overall verdict, the strictest across the axes run: + +- `approve`: no critical finding, ship it. +- `changes-requested`: warnings, or a fixable critical to address first. +- `blocked`: a critical that must not merge. + +## Code categories + +`standards`, `architecture`, `code-health`, `security`, `error-handling`, `performance`, `frontend`, `backend`. + +## Relevancy lenses + +- `fit`: serves the real need, not only the literal criteria. +- `conform`: the project's declared rules and the surrounding conventions. +- `rot`: duplication, over-engineering, incoherence (naming, docs versus code). diff --git a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md index c8e1aad0..83c22497 100644 --- a/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md +++ b/plugins/aidd-dev/skills/09-for-sure/assets/plan-template.md @@ -52,7 +52,7 @@ status: pending ## Applicable rules - + | Tool | Name | Path | Why it applies | | ------ | ------ | ------------------------------------- | -------------- | diff --git a/plugins/aidd-dev/skills/10-todo/README.md b/plugins/aidd-dev/skills/10-todo/README.md index 727b75be..734bde80 100644 --- a/plugins/aidd-dev/skills/10-todo/README.md +++ b/plugins/aidd-dev/skills/10-todo/README.md @@ -2,7 +2,7 @@ # 10 - todo -Split one prompt into independent todos, run one implementer agent per +Split one prompt into independent todos, run one executor agent per todo in parallel (each refines its todo before coding), and report a minimal table: category, what was launched, output. diff --git a/plugins/aidd-dev/skills/10-todo/SKILL.md b/plugins/aidd-dev/skills/10-todo/SKILL.md index 85a589b7..51137ace 100644 --- a/plugins/aidd-dev/skills/10-todo/SKILL.md +++ b/plugins/aidd-dev/skills/10-todo/SKILL.md @@ -1,6 +1,6 @@ --- name: 10-todo -description: Split the user prompt into independent todos, run one implementer agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations. +description: Split the user prompt into independent todos, run one executor agent per todo in parallel (each refines its todo first), and report a minimal table. Use when the user says "todo", "/todo", or asks to fan out a multi-part request into parallel implementations. --- # Todo diff --git a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md index d918c682..504a1140 100644 --- a/plugins/aidd-dev/skills/10-todo/actions/01-todo.md +++ b/plugins/aidd-dev/skills/10-todo/actions/01-todo.md @@ -17,7 +17,7 @@ User's requirement. 1. **Read.** Take `prompt` from `$ARGUMENTS`; if empty, ask the user. 2. **Categorize.** Split the prompt into distinct, independent todos (category + task). Inline, no agent, using template. -3. **Launch.** Spawn one `implementer` agent per todo, all in parallel (one message, multiple Task calls). Each agent prompt mandates, in order: +3. **Launch.** Spawn one `executor` agent per todo, all in parallel (one message, multiple Task calls). Each agent prompt mandates, in order: ```markdown 1. Refine the todo first - discover at runtime a skill whose description covers refining or clarifying a request (never a hardcoded plugin name) and run it on the todo. 2. Implement the refined todo. diff --git a/plugins/aidd-pm/CATALOG.md b/plugins/aidd-pm/CATALOG.md index 5da05e2f..d4a73cbd 100644 --- a/plugins/aidd-pm/CATALOG.md +++ b/plugins/aidd-pm/CATALOG.md @@ -58,5 +58,5 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [02-refine.md](skills/04-spec/actions/02-refine.md) | - | | `assets` | [spec-template.md](skills/04-spec/assets/spec-template.md) | - | | `-` | [README.md](skills/04-spec/README.md) | - | -| `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec.` | +| `-` | [SKILL.md](skills/04-spec/SKILL.md) | `Generate or refine a spec, a feature's immutable contract, from a request, a PRD, or review findings. Use to draft or refine a spec. Do NOT use to write code, a full PRD, or change a locked spec.` | diff --git a/plugins/aidd-pm/skills/04-spec/README.md b/plugins/aidd-pm/skills/04-spec/README.md index 80d2829d..8a593136 100644 --- a/plugins/aidd-pm/skills/04-spec/README.md +++ b/plugins/aidd-pm/skills/04-spec/README.md @@ -2,17 +2,15 @@ # 04 - Spec -Generates or refines the immutable contract between human intent and the -downstream agents that will plan, implement, and review the work. The spec -is what a planner consumes; it stays free of implementation detail and is -locked once validated. +Generate or refine the immutable contract for a feature: its target, hard +constraints, non-goals, and done-when. The spec stays free of implementation +detail and is locked once validated. ## When to use - "draft spec", "spec for X", "generate spec from prd". -- "refine the spec" when reviewer findings come back. +- "refine the spec" when review findings come back. - Invoking `/spec`. -- When an orchestrator needs a normalized contract before triggering a plan. ## When NOT to use @@ -29,7 +27,7 @@ Build a fresh spec from a request or an existing PRD: Use skill aidd-pm:04-spec build for ``` -Refine an existing spec from reviewer findings: +Refine an existing spec from review findings: ``` Use skill aidd-pm:04-spec refine on with @@ -44,20 +42,19 @@ and `findings` triggers `refine`; otherwise `build` runs. with explicit non-goals, bulleted acceptance criteria, and `TBD: ` markers wherever information is missing. - On `refine`: the same file rewritten to address the supplied findings. -- The skill never self-validates; the caller spawns a reviewer using - [`assets/spec-validator.yml`](assets/spec-validator.yml) and feeds the - findings back through `refine` for the next iteration. +- The skill never self-validates. A spec is checked against + [`assets/spec-validator.yml`](assets/spec-validator.yml); the findings come + back through `refine` for the next iteration. ## Prerequisites - A free-form request, an existing PRD path, or an existing spec plus a - set of reviewer findings. + set of review findings. - Write access to the spec target path in the current repo. ## Technical details See [`SKILL.md`](SKILL.md) for the action contract, [`actions/01-build.md`](actions/01-build.md) and -[`actions/02-refine.md`](actions/02-refine.md) for the two atomic actions, -and [`assets/`](assets/) for the canonical template plus the validator -checklist used by reviewers. +[`actions/02-refine.md`](actions/02-refine.md) for the two actions, +and [`assets/`](assets/) for the spec template plus the validator checklist. diff --git a/plugins/aidd-pm/skills/04-spec/SKILL.md b/plugins/aidd-pm/skills/04-spec/SKILL.md index a356c7b3..1b099bc2 100644 --- a/plugins/aidd-pm/skills/04-spec/SKILL.md +++ b/plugins/aidd-pm/skills/04-spec/SKILL.md @@ -1,46 +1,31 @@ --- name: 04-spec -description: Generate or refine a project spec from a free-form human request, an existing PRD, or reviewer findings. Use when the user says "draft spec", "spec for X", "refine the spec", "generate spec from prd", "/spec", or when an orchestrator needs a normalized contract before planning. Do NOT use for writing source code, drafting a full PRD, or modifying a validated and locked spec. +description: Generate or refine a spec, a feature's immutable contract, from a request, a PRD, or review findings. Use to draft or refine a spec. Do NOT use to write code, a full PRD, or change a locked spec. argument-hint: build | refine --- -# Spec +# Skill: spec -Generates or refines the immutable contract between human intent and downstream agents. +Generate or refine the immutable contract for a feature: its target, hard constraints, non-goals, and done-when. -## Available actions +## Actions -| # | Action | Role | Input | -| --- | --------- | ----------------------------------------------------------------- | -------------------------------------- | -| 01 | `build` | Create a fresh spec from a free-form request or an existing PRD | request or prd_path, feature_name | -| 02 | `refine` | Rewrite an existing spec to address reviewer findings | existing_spec, findings | +| # | Action | Role | Input | +| --- | -------- | ---------------------------------------------------- | ---------------------------- | +| 01 | `build` | Draft a fresh spec from a request or an existing PRD | a request or a PRD path | +| 02 | `refine` | Rewrite an existing spec to address review findings | a spec path and the findings | -## Default flow - -Non-sequential. The router dispatches based on inputs: - -- `existing_spec` and `findings` present -> `refine` -- `request` or `prd_path` present -> `build` +Dispatch by input: a spec path with findings runs `refine`; a request or PRD path runs `build`. ## Transversal rules -- Never invent missing information. Mark every gap as `TBD: ` instead of guessing. -- If the request is too vague to draft a useful spec, return early and ask the user to brainstorm the request first; do not fabricate intent. -- Never modify a spec that has been validated and locked. -- The spec is the contract; it is immutable once validated. -- Keep the spec readable: clear section headers, bulleted criteria, explicit non-goals. -- Never include implementation detail (libraries, patterns, file layout); those belong to the plan. -- Do not self-validate. The caller spawns a reviewer with `@assets/spec-validator.yml`; findings come back through the `refine` action for the next iteration. - -## References - -- None. +- Never invent. Mark every gap as `TBD: ` rather than guessing. When a request is too vague to draft anything useful, stop and ask for a clearer one. +- The spec holds intent, never implementation. It is solution-agnostic: no file, component, hook, route, library, pattern, or token, and no "how". The done-when conditions are outcome-level, not steps. Keep the acceptance criteria few. All of that belongs to the plan. +- Keep it readable: clear section headers, bulleted criteria, explicit non-goals. +- Output: one `spec.md` in the feature folder (`aidd_docs/tasks//_/`), from `@assets/spec-template.md`. Reuse the folder when it exists. +- Immutable once validated: never rewrite a spec that has been locked. ## Assets -- `@assets/spec-template.md`: canonical structure of a spec. -- `@assets/spec-validator.yml`: checklist used by the reviewer to validate a spec. - -## External data - -- None. +- `assets/spec-template.md`: the spec's structure. +- `assets/spec-validator.yml`: the checklist a spec is validated against. diff --git a/plugins/aidd-pm/skills/04-spec/actions/01-build.md b/plugins/aidd-pm/skills/04-spec/actions/01-build.md index f9696608..0a177962 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/01-build.md +++ b/plugins/aidd-pm/skills/04-spec/actions/01-build.md @@ -1,35 +1,25 @@ # 01 - Build -Create a fresh spec from a free-form request or by extracting fields from an existing PRD. +Draft a fresh spec from a free-form request, or by lifting fields from an existing PRD. -## Inputs +## Input -```yaml -request: # required when prd_path is absent -prd_path: # required when request is absent -feature_name: # required; derived from the request when absent -``` +A free-form request, or a path to an existing PRD. A feature name for the folder, derived from the request when absent. -## Outputs +## Output -```yaml -spec_path: aidd_docs/tasks//_/spec.md -status: draft -notes: -``` +The path to `spec.md` in the feature folder, drafted from the template, with the ambiguities and assumptions noted. ## Process -1. **Source resolution**. Pick first match: - - `prd_path` provided -> parse the PRD, lift target, hard constraints, non-goals, and done-when into the matching template sections; drop libraries, patterns, and file-layout content - - `request` provided -> use `assets/spec-template.md` directly and map the request onto its sections -2. **Mark gaps**. Replace any missing required field with `TBD: `. Never guess. -3. **Section check**. Confirm every section listed in `assets/spec-validator.yml` is present. -4. **Write**. Resolve the feature folder: reuse the one for this feature when it already exists under `aidd_docs/tasks//_/`, otherwise create it. Save the spec there as `spec.md`. -5. **Return** the structured Outputs block with `status: draft`. +1. **Source.** From a PRD path, lift its target, hard constraints, non-goals, and done-when into the template, dropping any implementation detail. From a request, map it onto the template sections directly. Do not explore the codebase or name any file, component, or API: the spec stays solution-agnostic, intent only. +2. **Gaps.** Replace any missing required field with `TBD: `. Never guess. +3. **Check.** Confirm every section the validator requires is present. +4. **Write.** Resolve the feature folder, reusing it when it exists, and save the spec there as `spec.md`. +5. **Return.** Surface the spec path and the notes. ## Test -- **File saved**: `spec_path` exists on disk after the action completes. -- **All sections**: the file contains every section listed in `assets/spec-validator.yml`. -- **No implementation**: the file has no library names, framework patterns, or source-file layout. +- `spec.md` exists in the feature folder. +- It contains every section listed in `@../assets/spec-validator.yml`. +- It carries no library name, framework pattern, or source-file layout. diff --git a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md index 3bf1f7c8..6783f0a9 100644 --- a/plugins/aidd-pm/skills/04-spec/actions/02-refine.md +++ b/plugins/aidd-pm/skills/04-spec/actions/02-refine.md @@ -1,34 +1,24 @@ # 02 - Refine -Rewrite an existing spec in place to address reviewer findings. +Rewrite an existing spec in place to address review findings. -## Inputs +## Input -```yaml -existing_spec: # required -findings: # required; list or text -``` +The path to the current spec, and the findings to address, a list or free text. -## Outputs +## Output -```yaml -spec_path: # same as existing_spec -status: refined -notes: -``` +The refined spec at the same path, with the changes applied and any residual `TBD` questions noted. ## Process -1. **Load**. Read `existing_spec` and `findings`. -2. **Map findings**. Pair each finding with the section of the spec it touches. -3. **Rewrite**. Apply each finding in place: clarify wording, add missing fields, remove invalid claims. Preserve sections the findings do not touch. -4. **Mark gaps**. Replace any field still unanswered with `TBD: `. Never guess. -5. **Section check**. Confirm every section listed in `assets/spec-validator.yml` is present. -6. **Write**. Save the refined spec back to the same path as `existing_spec` (overwrite). -7. **Return** the structured Outputs block with `status: refined`. +1. **Load.** Read the spec and the findings. +2. **Map.** Pair each finding with the section it touches. +3. **Rewrite.** Apply each finding in place: clarify wording, add missing fields, remove invalid claims. Leave untouched sections as they are. +4. **Gaps.** Replace any field still unanswered with `TBD: `. Never guess. +5. **Check.** Confirm every section the validator requires is present, then overwrite the spec at its path. ## Test -- **File saved**: `spec_path` exists on disk after the action completes. -- **All sections**: the file contains every section listed in `assets/spec-validator.yml`. -- **Findings addressed**: every finding in `findings` is reflected by a change in the rewritten spec or by an explicit `TBD: ` if it cannot be resolved. +- The spec still exists at its path and holds every section listed in `@../assets/spec-validator.yml`. +- Every finding is reflected by a change, or by an explicit `TBD: ` when it cannot be resolved. diff --git a/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml b/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml index 364d0aba..1da8edd5 100644 --- a/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml +++ b/plugins/aidd-pm/skills/04-spec/assets/spec-validator.yml @@ -1,4 +1,4 @@ -# Checklist used by the reviewer agent to validate a spec. +# Checklist a spec is validated against. # Each criterion is independently scored. Required criteria must be `fulfilled` for the spec to pass. criteria: diff --git a/plugins/aidd-vcs/CATALOG.md b/plugins/aidd-vcs/CATALOG.md index 7a84091d..d8f484c3 100644 --- a/plugins/aidd-vcs/CATALOG.md +++ b/plugins/aidd-vcs/CATALOG.md @@ -41,7 +41,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [01-commit.md](skills/01-commit/actions/01-commit.md) | - | | `assets` | [commit-template.md](skills/01-commit/assets/commit-template.md) | `VCS commit message template` | | `-` | [README.md](skills/01-commit/README.md) | - | -| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging.` | +| `-` | [SKILL.md](skills/01-commit/SKILL.md) | `Create an atomic git commit with a conventional message, optionally pushing. Use to commit changes ("commit", "/commit push"). Do NOT use to amend, rebase, open a PR, or tag a release.` | #### `skills/02-pull-request` @@ -49,11 +49,9 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |-------|------|---| | `actions` | [01-pull-request.md](skills/02-pull-request/actions/01-pull-request.md) | - | | `assets` | [branch.md](skills/02-pull-request/assets/branch.md) | `VCS branch naming convention template` | -| `assets` | [CONTRIBUTING.md](skills/02-pull-request/assets/CONTRIBUTING.md) | `Project contribution guidelines template` | | `assets` | [pull_request.md](skills/02-pull-request/assets/pull_request.md) | `VCS pull/merge request template` | -| `assets` | [README.md](skills/02-pull-request/assets/README.md) | `Project README template` | | `-` | [README.md](skills/02-pull-request/README.md) | - | -| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`.` | +| `-` | [SKILL.md](skills/02-pull-request/SKILL.md) | `Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use to open a PR/MR ("open a pr", `/pull-request`). Do NOT use to commit, push, or merge a branch.` | #### `skills/03-release-tag` diff --git a/plugins/aidd-vcs/skills/01-commit/SKILL.md b/plugins/aidd-vcs/skills/01-commit/SKILL.md index e25cb790..2f5168e8 100644 --- a/plugins/aidd-vcs/skills/01-commit/SKILL.md +++ b/plugins/aidd-vcs/skills/01-commit/SKILL.md @@ -1,13 +1,13 @@ --- name: 01-commit -description: Create an atomic git commit with conventional message format. Use when the user says "commit", "git commit", "create a commit", "commit my changes", "commit and push", or invokes `/commit`. Do NOT use for amending existing commits, force-pushing, rebasing, opening pull requests, or release tagging. +description: Create an atomic git commit with a conventional message, optionally pushing. Use to commit changes ("commit", "/commit push"). Do NOT use to amend, rebase, open a PR, or tag a release. --- # Commit -Generates atomic git commits with conventional messages, supporting interactive splits and agent-driven auto mode. +Runs interactive with split approval, or auto for agents. -## Available actions +## Actions | # | Action | Role | Input | | --- | -------- | ------------------------------------------------------------- | ------------------------------------------- | @@ -26,22 +26,15 @@ When invoked as a slash command, the trailing argument controls the push behavio ## Transversal rules +- Project first: follow `aidd_docs/memory/vcs.md` when it exists (message convention, scopes, branch naming); the rules below and the template are the fallback. - Commits stay atomic and focused on a single concern. - Messages use imperative mood ("Add feature" not "Added feature"). - Explain "why" not "what" in the body. - Never `--force` push. `--force-with-lease` is acceptable when explicitly required. -- Follow the conventional commit format defined in `@assets/commit-template.md`. +- Follow the conventional commit format defined in `@assets/commit-template.md` when the project sets none. - Reference issues in the commit body when applicable. - `auto` mode never asks for confirmation. `interactive` mode requires user approval before staging and before committing splits. -## References - -- None. - ## Assets - `@assets/commit-template.md`: Conventional commit format reference. - -## External data - -- None. diff --git a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md index b0a8171a..33238b71 100644 --- a/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md +++ b/plugins/aidd-vcs/skills/01-commit/actions/01-commit.md @@ -1,55 +1,28 @@ # 01 - Commit -Stage files, generate or accept a commit message, run the commit, optionally push, and return the resulting sha. +Stage the change, write or accept a conventional message, commit, optionally push, and return the sha. -## Inputs +## Input -```yaml -mode: interactive | auto # default: interactive -message: # optional; when set, used as-is, no generation -push: true | false # default: false -files: [] # optional; restrict staging to these paths -``` +The mode (`interactive` default, or `auto`), an optional imposed message, whether to push (default no, set by a trailing `push` in `$ARGUMENTS`), and optional paths to restrict staging. -When invoked via slash command, parse `$ARGUMENTS`: +## Output -- contains the word `push` → set `push: true` -- empty or anything else → leave `push: false` - -## Outputs - -```yaml -commit_sha: -branch: -pushed: true | false -``` +The new commit sha, the branch, and whether it was pushed. ## Process -1. **Branch resolution**. Pick first match: - - branch already checked out -> use it - - `mode = auto` -> generate a conventional name from the change - - `mode = interactive` -> propose a name and wait for user approval -2. **Staging**. Pick first match: - - `files` set -> `git add` exactly those paths - - default -> use already-staged changes; do not add unstaged paths implicitly -3. **Message resolution**. Pick first match: - - `message` provided -> use it verbatim, skip steps 4 and 5 - - `mode = auto` -> inspect diff and `git log -5 --pretty=%B`, generate a message per `assets/commit-template.md`, no approval - - `mode = interactive` -> draft a message per the template, then proceed to steps 4 and 5 -4. **Interactive split** (when `mode = interactive` and multiple concerns are present). For each split, show: - - **Scope**: file list (proposal-only). - - **Draft message**: conventional subject; body explains "why", never lists files. - Wait for user approval. -5. **Interactive stage** (when `mode = interactive`). Run `git add -p` for each split. -6. **Commit**. Run `git commit` with the chosen message via heredoc. -7. **Hook recovery**. When a pre-commit hook fails, fix the underlying issue, re-stage, and create a new commit (do not amend). Loop until commit succeeds. -8. **Capture sha**. Read `git rev-parse HEAD`. -9. **Push**. When `push: true`, run `git push`. Use `--force-with-lease` only when explicitly required. Never `--force`. -10. **Return** the structured Outputs block. In interactive mode, also notify the user. +1. **Branch.** Use the checked-out branch. In `auto`, generate a conventional name from the change; in `interactive`, propose one and wait for approval. +2. **Stage.** With explicit paths, `git add` exactly those. Otherwise commit the already-staged changes, never staging unstaged paths implicitly. +3. **Message.** Use an imposed message verbatim. Else follow `aidd_docs/memory/vcs.md` when set, otherwise `@../assets/commit-template.md`. In `auto`, generate from the diff and log, no approval; in `interactive`, draft and confirm. +4. **Split.** In `interactive` with several concerns, propose each split (its scope, and a draft message that explains why, never lists files), wait for approval, and stage each with `git add -p`. +5. **Commit.** Run `git commit` with the chosen message. +6. **Recover.** On a pre-commit hook failure, fix the cause, re-stage, and make a new commit, never amend. Loop until it succeeds. +7. **Push.** When asked, `git push`. Use `--force-with-lease` only when explicitly required, never `--force`. +8. **Return.** Surface the sha, branch, and push state. ## Test -- **Sha match**: `git rev-parse HEAD` returns the new commit sha that matches the `commit_sha` field in Outputs. -- **Format**: `git log -1 --pretty=%s` matches the conventional commit regex `^(feat|fix|docs|style|refactor|perf|test|chore|build|ci)(\([^)]+\))?: .+`. -- **Push**: when `push: true`, `git ls-remote origin ` lists a sha equal to `commit_sha`. +- `git rev-parse HEAD` equals the returned sha. +- `git log -1 --pretty=%s` matches the conventional-commit format. +- When pushed, `git ls-remote origin ` lists the sha. diff --git a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md index 7755da96..af224d27 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/SKILL.md +++ b/plugins/aidd-vcs/skills/02-pull-request/SKILL.md @@ -1,13 +1,13 @@ --- name: 02-pull-request -description: Create a draft pull or merge request from the current branch. Use when the user ask to create a PR or invokes `/pull-request`. +description: Create a draft pull or merge request from the current branch, in whatever VCS tool the project uses. Use to open a PR/MR ("open a pr", `/pull-request`). Do NOT use to commit, push, or merge a branch. --- # Pull Request Drafts pull or merge requests from the current branch using the team's template, ready for the user to promote. -## Available actions +## Actions | # | Action | Role | Input | | --- | --------------- | ------------------------------------------------------------------- | ---------------------------------------------- | @@ -19,6 +19,7 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph ## Transversal rules +- Project first: follow `aidd_docs/memory/vcs.md` and the repo's own request-template file when they exist (body sections, base rules, labels); the rules below and the bundled templates are the fallback. - Resolve the base branch from the head branch's prefix via the project's branch-naming convention (project memory); fall back to repo state when no prefix mapping exists. Never assume `main` or `master` (common alternatives: `next`, `develop`, `staging`). - Always ask the user to validate the title, body, and base branch before creating the request. - Open the request as a draft. The user promotes it manually when ready. @@ -26,17 +27,7 @@ Single action skill. The router dispatches to `pull-request` whenever a PR/MR ph - Never commit, never push the working branch, never create new branches inside this skill. - Tool-agnostic: read the VCS tool from project memory; fall back to inspecting the remote URL. -## References - -- None. - ## Assets - `@assets/pull_request.md`: Request body template. -- `@assets/branch.md`: Branch naming conventions. -- `@assets/CONTRIBUTING.md`: Contribution guidelines template. -- `@assets/README.md`: README template. - -## External data - -- None. +- `@assets/branch.md`: Branch-naming convention, the fallback when project memory sets none. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md index cffa5b7c..e09f008e 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md @@ -1,48 +1,30 @@ # 01 - Pull Request -Detect the base branch, fill the request template with recent commits, validate with the user, and open a draft request via the configured VCS tool. +Detect the base branch, fill the request template from the recent commits, validate with the user, and open a draft request via the configured VCS tool. -## Inputs +## Input -```yaml -base_branch: # optional; auto-detect from repo state when omitted -template_overrides: # optional; override specific template sections - title: - body: -``` +An optional base branch (auto-detected when omitted), and optional title or body overrides. -## Outputs +## Output -```yaml -pr_url: -pr_number: -branch: -base: -is_draft: true -``` +The draft request's URL and number, with its head and resolved base branch. ## Process -1. **Tool resolution**. Pick first match: - - VCS tool declared in project memory -> use it - - default -> map `git remote get-url origin` to the matching configured tool -2. **Branch identity**. Read current head via `git rev-parse --abbrev-ref HEAD`. -3. **Base resolution**. Pick first match: - - `base_branch` provided -> use it - - the branch-naming convention in project memory maps the head branch's prefix to a PR target (e.g. `feat/` -> `next`, `hotfix/` -> `main`) -> use that target - - default -> inspect `git symbolic-ref refs/remotes/origin/HEAD`, then candidate list `main`, `master`, `develop`, `staging` - - surface the chosen value and the reason during validation -4. **Collect changes**. Run `git log ..HEAD --pretty=fuller` and `git diff ...HEAD --stat` to summarize commits and impacted files. -5. **Read template**. Load `assets/pull_request.md` and any contributing rules from `assets/CONTRIBUTING.md`. -6. **Fill template**. Generate a concise title and a body that follows the template structure, using the change summary from step 4. -7. **Validate with user**. Show title, body, and detected base branch. Apply `template_overrides` when provided. Wait for explicit user approval. -8. **Open draft**. Invoke the configured VCS tool to create the request as a draft, passing base, title, and body. Capture the returned URL and number. -9. **Set triage label**. When the branch-naming convention maps the head branch's prefix to a triage label (e.g. `feat/` -> `enhancement`, `fix/` -> `bug`) and that label exists in the repo, apply it. Skip silently when there is no mapping or no matching label. Labels triage only; they never change the base resolved in step 3. -10. **Return** the structured Outputs block. +1. **Tool.** Use the VCS tool declared in project memory, otherwise map `git remote get-url origin` to the matching configured tool. +2. **Head.** Read the current branch with `git rev-parse --abbrev-ref HEAD`. +3. **Base.** Resolve the base in order: a provided base; otherwise the target the head branch's prefix maps to in the project's branch-naming convention (for example `feat/` → `next`, `hotfix/` → `main`); otherwise `git symbolic-ref refs/remotes/origin/HEAD`, then `main`, `master`, `develop`, `staging`. Surface the chosen base and the reason. +4. **Collect.** Summarize the commits and impacted files with `git log ..HEAD` and `git diff ...HEAD --stat`. +5. **Fill.** Load the request template, preferring the project's own (`aidd_docs/memory/vcs.md` or the repo's request-template file) over the bundled one, plus any contributing rules; write a concise title and body from the change summary. +6. **Validate.** Show the title, body, and detected base. Apply any overrides, then wait for explicit approval. +7. **Open.** Create the request as a draft via the configured tool, passing the base, title, and body. Capture the URL and number. +8. **Label.** When the head prefix maps to a triage label that exists in the repo, apply it (for example `feat/` → `enhancement`). Skip silently otherwise. Labels triage only; they never change the base. +9. **Return.** Surface the URL, number, head, and base. ## Test -- **Tool view**: querying the configured VCS tool for the created request returns a record where `url` equals `pr_url`, `base` equals the resolved base branch, and the draft flag is true. -- **Prefix routing**: a head branch whose prefix is mapped in project memory resolves `base` to that prefix's target (e.g. `feat/*` -> `next`, `hotfix/*` -> `main`), not the `origin/HEAD` default. -- **Triage label**: when the head prefix maps to a triage label that exists in the repo, the created request carries that label. -- **Reachable**: the created request is reachable at `pr_url` and lists the head branch as the current branch. +- The created request exists with `base` equal to the resolved base and the draft flag true. +- A head branch whose prefix is mapped resolves the base to that target, not the `origin/HEAD` default. +- When the head prefix maps to an existing triage label, the request carries it. +- The request is reachable at its URL with the head branch as its source. diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md b/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md deleted file mode 100644 index 516531f5..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/CONTRIBUTING.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -name: contributing -description: Project contribution guidelines template -argument-hint: N/A ---- - -# Contributing to [Project Name] - -Welcome to the [Project Name] contribution guide! We appreciate your interest in helping us improve and grow this project. This document outlines how you can contribute effectively. - -> [Vision Statement or Mission of the Project, our Why] - -## 📐 Contributing Guidelines - -- Who can contribute? -- Roles and responsibilities? -- Code of conduct... - -## ❓ What can YOU do to help? - - - -### - -1. ... - -## 📌 Where are features to build? - -[...] - -## 💠 Onboarding in the Contributing flow - -### Documentation links - -- [](./) - -### Pre-requisites environment setup (optional) - -[...] - -### Steps to follow - -1. ... - -## 🌲 Branch naming - -- - -## 👌 Commit Guidelines - -- - -## 🧪 Testing Guidelines - -- ... - -## 🚀 Publishing (Maintainers Only) - -### Authentication Setup - -### Process to Publish diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/README.md b/plugins/aidd-vcs/skills/02-pull-request/assets/README.md deleted file mode 100644 index 35c3efaa..00000000 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/README.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: readme -description: Project README template -argument-hint: N/A ---- - -# [Project Name] - -[Summary] - -## Installation Process - -## Usage - -## Access - -## Development Workflow - -## Documentation Structure - -| File | Description | -| ----- | ----------- | -| `...` | ... | - -## Common issues - -### Troubleshooting - -## 📄 License - -## Contributing - -We welcome contributions from the community. Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines on how to contribute. diff --git a/scripts/check-markdown-links.js b/scripts/check-markdown-links.js index 783ffcec..15b7dde6 100644 --- a/scripts/check-markdown-links.js +++ b/scripts/check-markdown-links.js @@ -33,7 +33,7 @@ Examples: | Reader reference | See [explore skill](plugins/aidd-context/skills/11-explore/SKILL.md). | `; -const SKIPPED_DIRS = new Set([".git", "node_modules"]); +const SKIPPED_DIRS = new Set([".git", "node_modules", "worktrees", ".specstory"]); const SKIPPED_DIR_PREFIXES = [".tmp-check-markdown-links-"]; const MARKDOWN_EXTENSIONS = new Set([".md", ".mdx"]); function normalizePathForDisplay(filePath) { From cedb873af43eff86b3995dcaf1f781f5a1e27b28 Mon Sep 17 00:00:00 2001 From: Alex <8973343+alexsoyes@users.noreply.github.com> Date: Thu, 25 Jun 2026 08:41:54 +0200 Subject: [PATCH 13/14] feat(aidd-dev): route deletions to refactor cleanup with orphan sweep (#328) When the user asks to delete or remove code, the refactor skill is now a trigger target and routes straight to the cleanup action. The cleanup action sweeps for orphaned references a deletion leaves behind, so removals also clean up imports, tests, docs, and config that pointed at the deleted symbol. Co-authored-by: Claude Opus 4.8 (1M context) --- plugins/aidd-dev/CATALOG.md | 2 +- plugins/aidd-dev/skills/07-refactor/SKILL.md | 3 ++- plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/plugins/aidd-dev/CATALOG.md b/plugins/aidd-dev/CATALOG.md index 7f745f1b..38e7aa05 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -133,7 +133,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `actions` | [03-cleanup.md](skills/07-refactor/actions/03-cleanup.md) | - | | `actions` | [04-architecture.md](skills/07-refactor/actions/04-architecture.md) | - | | `-` | [README.md](skills/07-refactor/README.md) | - | -| `-` | [SKILL.md](skills/07-refactor/SKILL.md) | `Improve code without breaking behavior across four axes - cleanup (clean-code + tech debt), performance, security, architecture. Scans and fixes, or fixes the findings of an audit report pushed in by the caller. Use when the user wants to refactor, clean up, optimize, harden, or restructure code. Do NOT use for read-only diagnosis (use 04-audit), adding tests (use 06-test), or UI redesign (use the impeccable skill).` | +| `-` | [SKILL.md](skills/07-refactor/SKILL.md) | `Improve code without breaking behavior across four axes - cleanup (clean-code + tech debt), performance, security, architecture. Scans and fixes, or fixes the findings of an audit report pushed in by the caller. Use when the user wants to refactor, clean up, optimize, harden, restructure, or delete/remove code. Do NOT use for read-only diagnosis (use 04-audit), adding tests (use 06-test), or UI redesign (use the impeccable skill).` | #### `skills/08-debug` diff --git a/plugins/aidd-dev/skills/07-refactor/SKILL.md b/plugins/aidd-dev/skills/07-refactor/SKILL.md index 52e66b60..3a8e05d4 100644 --- a/plugins/aidd-dev/skills/07-refactor/SKILL.md +++ b/plugins/aidd-dev/skills/07-refactor/SKILL.md @@ -1,6 +1,6 @@ --- name: 07-refactor -description: Improve code without breaking behavior across four axes - cleanup (clean-code + tech debt), performance, security, architecture. Scans and fixes, or fixes the findings of an audit report pushed in by the caller. Use when the user wants to refactor, clean up, optimize, harden, or restructure code. Do NOT use for read-only diagnosis (use 04-audit), adding tests (use 06-test), or UI redesign (use the impeccable skill). +description: Improve code without breaking behavior across four axes - cleanup (clean-code + tech debt), performance, security, architecture. Scans and fixes, or fixes the findings of an audit report pushed in by the caller. Use when the user wants to refactor, clean up, optimize, harden, restructure, or delete/remove code. Do NOT use for read-only diagnosis (use 04-audit), adding tests (use 06-test), or UI redesign (use the impeccable skill). argument-hint: performance | security | cleanup | architecture --- @@ -23,6 +23,7 @@ This skill is run-one-OR-run-all: - The user named an axis ("optimize this", "harden", "clean up", "restructure") -> run that ONE action. - Unscoped ("refactor this", "improve the code") -> ask ONE question: "all applicable axes, or a specific one (cleanup / performance / security / architecture)?" Then run the chosen one, or all applicable. +- The user asked to delete or remove code ("delete X", "remove this", "drop this") -> run the `cleanup` action directly; do not ask which axis. - Never silently default to action 01. ## Audit handoff (push, never pull) diff --git a/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md b/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md index 8a1997e7..3a4c4bd6 100644 --- a/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md +++ b/plugins/aidd-dev/skills/07-refactor/actions/03-cleanup.md @@ -33,7 +33,7 @@ verification: Date: Thu, 25 Jun 2026 09:09:46 +0200 Subject: [PATCH 14/14] feat(aidd-ui): scaffold the top-to-bottom UI recipe skeleton MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the alpha smoke-test skill with the full structure of the UI recipe: six chained sections from product intent to polish, plus the two agents that drive and gate it. Structure only — action logic is stubbed and lands in follow-up PRs. Sections (each a SKILL.md with ordered steps + a product-critic exit gate, chained via requires/next/produces frontmatter): - 00-product deep interview -> PRODUCT.md (root, copy-paste template) - 01-wireframe IA flows + low-fidelity screens - 02-design-system brand board -> BRAND-BOARD.md, tokens -> DESIGN-SYSTEM.md - 03-build hi-fi UI from the design system - 04-review heuristics, a11y, responsive, visual critique - 05-polish states, motion, UX copy Agents: - ui-builder executes build and polish - product-critic ruthless design director; gates every section Templates wired from each SKILL.md; references for wireframe, UX heuristics, and a11y. Catalog and root README counts regenerated. Marketplace description updated. aidd-dev UI extraction (wireframe, audit-ui, assert-frontend) deferred to a follow-up PR. Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude-plugin/marketplace.json | 2 +- README.md | 6 +- plugins/aidd-ui/.claude-plugin/plugin.json | 15 +++- plugins/aidd-ui/CATALOG.md | 83 +++++++++++++++++-- plugins/aidd-ui/README.md | 34 ++++++-- plugins/aidd-ui/agents/product-critic.md | 26 ++++++ plugins/aidd-ui/agents/ui-builder.md | 25 ++++++ plugins/aidd-ui/skills/00-product/README.md | 32 +++++++ plugins/aidd-ui/skills/00-product/SKILL.md | 28 +++++++ .../skills/00-product/actions/01-init.md | 3 + .../skills/00-product/actions/02-interview.md | 3 + .../00-product/actions/03-define-good.md | 3 + .../skills/00-product/assets/PRODUCT.md | 31 +++++++ plugins/aidd-ui/skills/01-hello/README.md | 29 ------- plugins/aidd-ui/skills/01-hello/SKILL.md | 14 ---- .../skills/01-hello/actions/01-greet.md | 15 ---- plugins/aidd-ui/skills/01-wireframe/README.md | 32 +++++++ plugins/aidd-ui/skills/01-wireframe/SKILL.md | 31 +++++++ .../skills/01-wireframe/actions/01-flows.md | 3 + .../01-wireframe/actions/02-wireframe.md | 3 + .../01-wireframe/assets/wireframe-template.md | 16 ++++ .../references/wireframe-conventions.md | 9 ++ .../aidd-ui/skills/02-design-system/README.md | 33 ++++++++ .../aidd-ui/skills/02-design-system/SKILL.md | 30 +++++++ .../actions/01-brand-board.md | 3 + .../02-design-system/actions/02-tokens.md | 3 + .../02-design-system/actions/03-components.md | 3 + .../02-design-system/actions/04-system-doc.md | 3 + .../02-design-system/assets/BRAND-BOARD.md | 23 +++++ .../02-design-system/assets/DESIGN-SYSTEM.md | 33 ++++++++ plugins/aidd-ui/skills/03-build/README.md | 32 +++++++ plugins/aidd-ui/skills/03-build/SKILL.md | 27 ++++++ .../skills/03-build/actions/01-scaffold.md | 3 + .../skills/03-build/actions/02-screen.md | 3 + plugins/aidd-ui/skills/04-review/README.md | 32 +++++++ plugins/aidd-ui/skills/04-review/SKILL.md | 38 +++++++++ .../skills/04-review/actions/01-heuristics.md | 3 + .../04-review/actions/02-accessibility.md | 3 + .../skills/04-review/actions/03-responsive.md | 3 + .../skills/04-review/actions/04-visual.md | 3 + .../assets/review-report-template.md | 16 ++++ .../04-review/references/a11y-checklist.md | 11 +++ .../04-review/references/ux-heuristics.md | 11 +++ plugins/aidd-ui/skills/05-polish/README.md | 31 +++++++ plugins/aidd-ui/skills/05-polish/SKILL.md | 28 +++++++ .../skills/05-polish/actions/01-states.md | 3 + .../skills/05-polish/actions/02-motion.md | 3 + .../skills/05-polish/actions/03-copy.md | 3 + 48 files changed, 751 insertions(+), 76 deletions(-) create mode 100644 plugins/aidd-ui/agents/product-critic.md create mode 100644 plugins/aidd-ui/agents/ui-builder.md create mode 100644 plugins/aidd-ui/skills/00-product/README.md create mode 100644 plugins/aidd-ui/skills/00-product/SKILL.md create mode 100644 plugins/aidd-ui/skills/00-product/actions/01-init.md create mode 100644 plugins/aidd-ui/skills/00-product/actions/02-interview.md create mode 100644 plugins/aidd-ui/skills/00-product/actions/03-define-good.md create mode 100644 plugins/aidd-ui/skills/00-product/assets/PRODUCT.md delete mode 100644 plugins/aidd-ui/skills/01-hello/README.md delete mode 100644 plugins/aidd-ui/skills/01-hello/SKILL.md delete mode 100644 plugins/aidd-ui/skills/01-hello/actions/01-greet.md create mode 100644 plugins/aidd-ui/skills/01-wireframe/README.md create mode 100644 plugins/aidd-ui/skills/01-wireframe/SKILL.md create mode 100644 plugins/aidd-ui/skills/01-wireframe/actions/01-flows.md create mode 100644 plugins/aidd-ui/skills/01-wireframe/actions/02-wireframe.md create mode 100644 plugins/aidd-ui/skills/01-wireframe/assets/wireframe-template.md create mode 100644 plugins/aidd-ui/skills/01-wireframe/references/wireframe-conventions.md create mode 100644 plugins/aidd-ui/skills/02-design-system/README.md create mode 100644 plugins/aidd-ui/skills/02-design-system/SKILL.md create mode 100644 plugins/aidd-ui/skills/02-design-system/actions/01-brand-board.md create mode 100644 plugins/aidd-ui/skills/02-design-system/actions/02-tokens.md create mode 100644 plugins/aidd-ui/skills/02-design-system/actions/03-components.md create mode 100644 plugins/aidd-ui/skills/02-design-system/actions/04-system-doc.md create mode 100644 plugins/aidd-ui/skills/02-design-system/assets/BRAND-BOARD.md create mode 100644 plugins/aidd-ui/skills/02-design-system/assets/DESIGN-SYSTEM.md create mode 100644 plugins/aidd-ui/skills/03-build/README.md create mode 100644 plugins/aidd-ui/skills/03-build/SKILL.md create mode 100644 plugins/aidd-ui/skills/03-build/actions/01-scaffold.md create mode 100644 plugins/aidd-ui/skills/03-build/actions/02-screen.md create mode 100644 plugins/aidd-ui/skills/04-review/README.md create mode 100644 plugins/aidd-ui/skills/04-review/SKILL.md create mode 100644 plugins/aidd-ui/skills/04-review/actions/01-heuristics.md create mode 100644 plugins/aidd-ui/skills/04-review/actions/02-accessibility.md create mode 100644 plugins/aidd-ui/skills/04-review/actions/03-responsive.md create mode 100644 plugins/aidd-ui/skills/04-review/actions/04-visual.md create mode 100644 plugins/aidd-ui/skills/04-review/assets/review-report-template.md create mode 100644 plugins/aidd-ui/skills/04-review/references/a11y-checklist.md create mode 100644 plugins/aidd-ui/skills/04-review/references/ux-heuristics.md create mode 100644 plugins/aidd-ui/skills/05-polish/README.md create mode 100644 plugins/aidd-ui/skills/05-polish/SKILL.md create mode 100644 plugins/aidd-ui/skills/05-polish/actions/01-states.md create mode 100644 plugins/aidd-ui/skills/05-polish/actions/02-motion.md create mode 100644 plugins/aidd-ui/skills/05-polish/actions/03-copy.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 1a6128fb..b06a7fea 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -52,7 +52,7 @@ { "name": "aidd-ui", "source": "./plugins/aidd-ui", - "description": "ALPHA, not ready for use. UI and UX concern: design, review, and improve frontend interfaces.", + "description": "ALPHA, not ready for use. UI and UX concern: a top-to-bottom recipe (product, wireframe, design-system, build, review, polish) to generate a high-quality frontend.", "strict": true, "recommended": false } diff --git a/README.md b/README.md index 44c32135..a18a6c97 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@

🇫🇷 The first French open-source framework for AI-driven development.

- 7 plugins · 41 skills · 2 agents · MIT + 7 plugins · 45 skills · 4 agents · MIT

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) @@ -189,7 +189,7 @@ Commits, pull / merge requests, release tags, issue creation. ### 📋 [aidd-pm](plugins/aidd-pm/README.md) -`5 skills` · stable +`4 skills` · stable Ticket info, user stories, PRD, spec drafting. @@ -218,7 +218,7 @@ Label an issue, get a PR; re-label, get the review applied. ### 🎨 [aidd-ui](plugins/aidd-ui/README.md) 🚧 -`1 skill` · **alpha — not ready** +`6 skills` · **alpha — not ready** UI and UX: design, review, and improve frontend interfaces. ⚠️ Alpha (`0.1.0-alpha.0`), smoke-test only — do not rely on it yet. diff --git a/plugins/aidd-ui/.claude-plugin/plugin.json b/plugins/aidd-ui/.claude-plugin/plugin.json index 894d576b..e147fe29 100644 --- a/plugins/aidd-ui/.claude-plugin/plugin.json +++ b/plugins/aidd-ui/.claude-plugin/plugin.json @@ -2,9 +2,20 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "aidd-ui", "version": "0.1.0-alpha.0", - "description": "ALPHA, not ready for use. UI and UX concern for the AI-Driven Development framework. Use when the user wants to design, review, or improve a frontend interface. Do NOT use for backend-only or non-UI tasks.", + "description": "ALPHA, not ready for use. UI and UX concern for the AI-Driven Development framework. A top-to-bottom recipe to generate a high-quality UI: product, wireframe, design-system, build, review, polish. Use when the user wants to design, review, or improve a frontend interface. Do NOT use for backend-only or non-UI tasks.", "author": { "name": "AI-Driven Dev", "url": "https://github.com/ai-driven-dev" }, - "skills": ["./skills/01-hello"], + "skills": [ + "./skills/00-product", + "./skills/01-wireframe", + "./skills/02-design-system", + "./skills/03-build", + "./skills/04-review", + "./skills/05-polish" + ], + "agents": [ + "./agents/ui-builder.md", + "./agents/product-critic.md" + ], "keywords": ["ui", "ux", "design", "frontend"], "repository": "https://github.com/ai-driven-dev/framework", "homepage": "https://ai-driven.dev", diff --git a/plugins/aidd-ui/CATALOG.md b/plugins/aidd-ui/CATALOG.md index 5b18635c..3639fd6a 100644 --- a/plugins/aidd-ui/CATALOG.md +++ b/plugins/aidd-ui/CATALOG.md @@ -7,8 +7,14 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai ## Table of Contents - [`.claude-plugin`](#claude-plugin) +- [`agents`](#agents) - [`skills`](#skills) - - [`skills/01-hello`](#skills01-hello) + - [`skills/00-product`](#skills00-product) + - [`skills/01-wireframe`](#skills01-wireframe) + - [`skills/02-design-system`](#skills02-design-system) + - [`skills/03-build`](#skills03-build) + - [`skills/04-review`](#skills04-review) + - [`skills/05-polish`](#skills05-polish) --- @@ -18,13 +24,80 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai |------| | [plugin.json](.claude-plugin/plugin.json) | +### `agents` + +| File | Description | +|------|---| +| [product-critic.md](agents/product-critic.md) | `The ruthless design director. Judges a product or design artifact against an impeccable bar and refuses anything tepid, derivative, or half-finished. Use as the exit gate of every aidd-ui section before advancing. Never builds, never softens its verdict to be liked.` | +| [ui-builder.md](agents/ui-builder.md) | `Builds and polishes the interface from the design system, one screen or component at a time. Use when a wireframe and a design system exist and the UI must be written or refined. Never defines the product, never sets the visual direction, never gates its own work.` | + ### `skills` -#### `skills/01-hello` +#### `skills/00-product` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-init.md](skills/00-product/actions/01-init.md) | - | +| `actions` | [02-interview.md](skills/00-product/actions/02-interview.md) | - | +| `actions` | [03-define-good.md](skills/00-product/actions/03-define-good.md) | - | +| `assets` | [PRODUCT.md](skills/00-product/assets/PRODUCT.md) | - | +| `-` | [README.md](skills/00-product/README.md) | - | +| `-` | [SKILL.md](skills/00-product/SKILL.md) | `Define the product and what "good" means for it, by deep interview, into PRODUCT.md. Use to open the UI recipe, before any wireframe or design. Do NOT use to write a PRD or functional spec (that is the product-management concern), and not to write code.` | + +#### `skills/01-wireframe` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-flows.md](skills/01-wireframe/actions/01-flows.md) | - | +| `actions` | [02-wireframe.md](skills/01-wireframe/actions/02-wireframe.md) | - | +| `assets` | [wireframe-template.md](skills/01-wireframe/assets/wireframe-template.md) | - | +| `-` | [README.md](skills/01-wireframe/README.md) | - | +| `references` | [wireframe-conventions.md](skills/01-wireframe/references/wireframe-conventions.md) | - | +| `-` | [SKILL.md](skills/01-wireframe/SKILL.md) | `Map the information architecture and sketch each screen at low fidelity, before any visual design. Use after the product is defined, to fix structure and flow. Do NOT use to choose colors, type, or final copy (that is design-system and polish), and not to write code.` | + +#### `skills/02-design-system` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-brand-board.md](skills/02-design-system/actions/01-brand-board.md) | - | +| `actions` | [02-tokens.md](skills/02-design-system/actions/02-tokens.md) | - | +| `actions` | [03-components.md](skills/02-design-system/actions/03-components.md) | - | +| `actions` | [04-system-doc.md](skills/02-design-system/actions/04-system-doc.md) | - | +| `assets` | [BRAND-BOARD.md](skills/02-design-system/assets/BRAND-BOARD.md) | - | +| `assets` | [DESIGN-SYSTEM.md](skills/02-design-system/assets/DESIGN-SYSTEM.md) | - | +| `-` | [README.md](skills/02-design-system/README.md) | - | +| `-` | [SKILL.md](skills/02-design-system/SKILL.md) | `Set the visual direction (brand board), then the tokens and component inventory, into BRAND-BOARD.md and DESIGN-SYSTEM.md. Use after wireframes are fixed, before building. Do NOT use to write UI code (that is build) or to define the product (that is product).` | + +#### `skills/03-build` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-scaffold.md](skills/03-build/actions/01-scaffold.md) | - | +| `actions` | [02-screen.md](skills/03-build/actions/02-screen.md) | - | +| `-` | [README.md](skills/03-build/README.md) | - | +| `-` | [SKILL.md](skills/03-build/SKILL.md) | `Build the hi-fi interface from the design system, one screen or component at a time, via the ui-builder agent. Use after the design system is set. Do NOT use to write business logic, data, or architecture (that is the dev concern), nor to define product or design.` | + +#### `skills/04-review` + +| Group | File | Description | +|-------|------|---| +| `actions` | [01-heuristics.md](skills/04-review/actions/01-heuristics.md) | - | +| `actions` | [02-accessibility.md](skills/04-review/actions/02-accessibility.md) | - | +| `actions` | [03-responsive.md](skills/04-review/actions/03-responsive.md) | - | +| `actions` | [04-visual.md](skills/04-review/actions/04-visual.md) | - | +| `assets` | [review-report-template.md](skills/04-review/assets/review-report-template.md) | - | +| `-` | [README.md](skills/04-review/README.md) | - | +| `references` | [a11y-checklist.md](skills/04-review/references/a11y-checklist.md) | - | +| `references` | [ux-heuristics.md](skills/04-review/references/ux-heuristics.md) | - | +| `-` | [SKILL.md](skills/04-review/SKILL.md) | `Critique the built UI on four axes — heuristics, accessibility, responsive, visual — into one report, via the product-critic agent. Use after building, before polish. Do NOT use to fix the findings (that is build and polish) or to review non-UI code.` | + +#### `skills/05-polish` | Group | File | Description | |-------|------|---| -| `actions` | [01-greet.md](skills/01-hello/actions/01-greet.md) | - | -| `-` | [README.md](skills/01-hello/README.md) | - | -| `-` | [SKILL.md](skills/01-hello/SKILL.md) | `Smoke-test skill that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Do NOT use for real UI or UX design work.` | +| `actions` | [01-states.md](skills/05-polish/actions/01-states.md) | - | +| `actions` | [02-motion.md](skills/05-polish/actions/02-motion.md) | - | +| `actions` | [03-copy.md](skills/05-polish/actions/03-copy.md) | - | +| `-` | [README.md](skills/05-polish/README.md) | - | +| `-` | [SKILL.md](skills/05-polish/SKILL.md) | `Finish the UI — empty/error/loading states, motion, and UX copy — via the ui-builder agent. Use as the last section of the recipe, after review. Do NOT use to restructure the UI or change the design system.` | diff --git a/plugins/aidd-ui/README.md b/plugins/aidd-ui/README.md index f54d34cd..8db2fdb4 100644 --- a/plugins/aidd-ui/README.md +++ b/plugins/aidd-ui/README.md @@ -4,11 +4,11 @@ UI and UX concern for the AI-Driven Development framework. -> ⚠️ **ALPHA — NOT READY FOR USE.** `0.1.0-alpha.0`. This plugin ships a single smoke-test skill and no real UI/UX capability yet. Do not install it expecting to use it; it exists only to validate the scaffold. APIs, skills, and naming may change or be removed without notice. +> ⚠️ **ALPHA — NOT READY FOR USE.** `0.1.0-alpha.0`. This plugin ships the skeleton of the UI recipe; the action logic is stubbed and lands later. APIs, skills, and naming may change or be removed without notice. > Status: alpha (experimental). -This plugin is in alpha (`0.1.0-alpha.0`). It lives on a dedicated branch off `next` and is registered with `recommended: false`, so it stays off the curated install path until it stabilises and graduates to `main`. While it is not in the published marketplace yet, test it from a local checkout of this branch: +This plugin is in alpha. It lives on a dedicated branch off `next` and is registered with `recommended: false`, so it stays off the curated install path until it stabilises and graduates to `main`. Test it from a local checkout of this branch: ``` claude --plugin-dir plugins/aidd-ui # zero-marketplace, session-scoped @@ -17,12 +17,32 @@ claude --plugin-dir plugins/aidd-ui # zero-marketplace, session-scoped /plugin install aidd-ui@aidd-framework ``` -Then run `aidd-ui:01-hello` to confirm it loads. +## The recipe -One starter skill today; real UI and UX skills land as the concern stabilises. +`aidd-ui` is one recipe to generate a high-quality UI top to bottom. Each skill is a section, each action a step. You run a section's steps in order; the `product-critic` agent gates the exit; you advance to the next section. No section is skippable on quality. + +``` +00-product → 01-wireframe → 02-design-system → 03-build → 04-review → 05-polish + PRODUCT.md flows + lo-fi BRAND-BOARD.md hi-fi UI critique finition + DESIGN-SYSTEM.md +``` + +Each `SKILL.md` declares what it `requires` (the artifact before it) and what comes `next`, so the recipe chains without a central orchestrator. ## Skills -| Bracket ID | Skill | Description | -| ---------- | ----- | ----------- | -| [7.1] | [hello](skills/01-hello/README.md) | Smoke-test skill that confirms the plugin loads. | +| # | Skill | Produces | Description | +| -- | ----- | -------- | ----------- | +| 00 | [product](skills/00-product/README.md) | `PRODUCT.md` | Define the product and what "good" means, by deep interview. | +| 01 | [wireframe](skills/01-wireframe/README.md) | flows + lo-fi screens | Map the IA and sketch each screen at low fidelity. | +| 02 | [design-system](skills/02-design-system/README.md) | `BRAND-BOARD.md`, `DESIGN-SYSTEM.md` | Set the visual direction, then tokens and components. | +| 03 | [build](skills/03-build/README.md) | hi-fi UI code | Build the interface from the design system. | +| 04 | [review](skills/04-review/README.md) | review report | Critique the UI: heuristics, a11y, responsive, visual. | +| 05 | [polish](skills/05-polish/README.md) | finished UI | States, motion, and UX copy. | + +## Agents + +| Agent | Role | +| ----- | ---- | +| `ui-builder` | Executes the build and polish steps. | +| `product-critic` | The ruthless design director. Gates every section; nothing tepid passes. | diff --git a/plugins/aidd-ui/agents/product-critic.md b/plugins/aidd-ui/agents/product-critic.md new file mode 100644 index 00000000..0120de8b --- /dev/null +++ b/plugins/aidd-ui/agents/product-critic.md @@ -0,0 +1,26 @@ +--- +name: product-critic +description: The ruthless design director. Judges a product or design artifact against an impeccable bar and refuses anything tepid, derivative, or half-finished. Use as the exit gate of every aidd-ui section before advancing. Never builds, never softens its verdict to be liked. +model: opus +--- + +# Role + +You are the product-critic — the design director nobody wants in the room and every great product needs. You judge the work against one standard: is this impeccable? Not "fine", not "shippable", not "good enough". Impeccable. Anything less, you send back. + +# Behavior + +- Build your bar first: the product's own definition of "good" in `PRODUCT.md`, plus the section's artifact (`PRODUCT.md`, the wireframe, `BRAND-BOARD.md`, `DESIGN-SYSTEM.md`, or the built UI). +- Tear into it. Name every place it is generic, lazy, inconsistent, cluttered, off-brand, or merely competent. Be specific — point at the exact element, token, screen, or line. +- Demand taste, not just correctness. A thing can satisfy every requirement and still be mediocre; say so. +- Distinguish the deal-breaker from the nitpick, but do not pad the verdict with praise to cushion it. State what must change to clear the bar. +- Return a verdict — passes the gate, or does not — with the exact list of what blocks it. + +# Guardrails + +- Never build, edit, or redesign the work. You judge; the `ui-builder` makes. +- Never pass on vibes or to be liked. A tepid yes is a failure of your job. +- Tie every objection to the product's stated bar or a named craft defect, never to taste asserted without reason. +- An impressive-looking artifact gets no discount. Look harder at the ones that dazzle. + +> Stub: scoring and the exact gate protocol are filled later. The standard is set now. diff --git a/plugins/aidd-ui/agents/ui-builder.md b/plugins/aidd-ui/agents/ui-builder.md new file mode 100644 index 00000000..5959aa67 --- /dev/null +++ b/plugins/aidd-ui/agents/ui-builder.md @@ -0,0 +1,25 @@ +--- +name: ui-builder +description: Builds and polishes the interface from the design system, one screen or component at a time. Use when a wireframe and a design system exist and the UI must be written or refined. Never defines the product, never sets the visual direction, never gates its own work. +model: opus +--- + +# Role + +You are the ui-builder. You turn a validated wireframe and design system into real, high-quality interface code — and then polish it. You make; you do not decide what is good. + +# Behavior + +- Read the inputs first: `PRODUCT.md`, the wireframe, `BRAND-BOARD.md`, and `DESIGN-SYSTEM.md`. Build only what they fix. +- Implement the visual and interaction layer: layout, styling, tokens, responsive behavior, states, motion, UX copy. Pull every value from the design system; never invent a token off-book. +- Build in small, reviewable units — one screen or one component at a time — and stop at the section's exit gate. +- Stay in the UI concern: business logic, data, and architecture belong to the dev pipeline, not here. +- Return what you built and what is left, to whoever invoked you. + +# Guardrails + +- Never write `PRODUCT.md` or `DESIGN-SYSTEM.md`. You consume them; you do not author them. +- Never declare your own work done — that is the `product-critic`'s gate. +- Never reach across into backend or architecture changes. + +> Stub: behavior is intentionally high-level for the structure PR. The step logic is filled later. diff --git a/plugins/aidd-ui/skills/00-product/README.md b/plugins/aidd-ui/skills/00-product/README.md new file mode 100644 index 00000000..89b1258a --- /dev/null +++ b/plugins/aidd-ui/skills/00-product/README.md @@ -0,0 +1,32 @@ +← [aidd-framework](../../../../README.md) / [aidd-ui](../../README.md) + +# 00 - product + +Opens the UI recipe. A deep interview fixes what the product is and what "good" means for it, written into `PRODUCT.md` at the repo root — the single source the whole recipe rests on. + +## When to use + +- Starting a UI from scratch, or pinning down the product intent before any design work. + +## When NOT to use + +- You want a functional PRD or spec → use the product-management capability. +- You want to write code → that is a later section of the recipe. + +## How to invoke + +``` +Use skill aidd-ui:00-product +``` + +## Outputs + +- `PRODUCT.md` at the repo root: vision, audience, jobs, the bar for "good", design principles. + +## Prerequisites + +- None. This is the entry point of the recipe. + +## Technical details + +See [`SKILL.md`](SKILL.md) and [`assets/PRODUCT.md`](assets/PRODUCT.md). diff --git a/plugins/aidd-ui/skills/00-product/SKILL.md b/plugins/aidd-ui/skills/00-product/SKILL.md new file mode 100644 index 00000000..fc8650e8 --- /dev/null +++ b/plugins/aidd-ui/skills/00-product/SKILL.md @@ -0,0 +1,28 @@ +--- +name: 00-product +description: Define the product and what "good" means for it, by deep interview, into PRODUCT.md. Use to open the UI recipe, before any wireframe or design. Do NOT use to write a PRD or functional spec (that is the product-management concern), and not to write code. +argument-hint: init | interview | define-good +requires: "—" +next: 01-wireframe +produces: PRODUCT.md +--- + +# Skill: product + +The first section of the UI recipe. Run a deep interview to fix what the product is and what makes it *good*, captured in `PRODUCT.md` at the repo root. + +## Recipe + +Run the steps in order, `01 → 03`. Each step completes before the next. **Exit gate:** the `product-critic` agent validates `PRODUCT.md` against its own bar; it does not advance to `01-wireframe` until the critic passes it. + +## Actions + +| # | Action | Role | Input | +| --- | ------------- | ------------------------------------------------------------ | -------------------- | +| 01 | `init` | Copy the `PRODUCT.md` template to the root if absent, else load it | repo root | +| 02 | `interview` | Deep, iterative Q&A on vision, audience, jobs, expectations | `PRODUCT.md` skeleton | +| 03 | `define-good` | Articulate the "good product" criteria and design principles | interview answers | + +## Assets + +- `assets/PRODUCT.md`: the `PRODUCT.md` scaffold, copied to the repo root and filled in. diff --git a/plugins/aidd-ui/skills/00-product/actions/01-init.md b/plugins/aidd-ui/skills/00-product/actions/01-init.md new file mode 100644 index 00000000..53722a8e --- /dev/null +++ b/plugins/aidd-ui/skills/00-product/actions/01-init.md @@ -0,0 +1,3 @@ +# 01 - Init + +Copy the `PRODUCT.md` template to the repo root if absent, else load it. diff --git a/plugins/aidd-ui/skills/00-product/actions/02-interview.md b/plugins/aidd-ui/skills/00-product/actions/02-interview.md new file mode 100644 index 00000000..dead7608 --- /dev/null +++ b/plugins/aidd-ui/skills/00-product/actions/02-interview.md @@ -0,0 +1,3 @@ +# 02 - Interview + +Deep, iterative Q&A on vision, audience, jobs, and expectations. diff --git a/plugins/aidd-ui/skills/00-product/actions/03-define-good.md b/plugins/aidd-ui/skills/00-product/actions/03-define-good.md new file mode 100644 index 00000000..e4064b18 --- /dev/null +++ b/plugins/aidd-ui/skills/00-product/actions/03-define-good.md @@ -0,0 +1,3 @@ +# 03 - Define good + +Articulate the "good product" criteria and design principles. diff --git a/plugins/aidd-ui/skills/00-product/assets/PRODUCT.md b/plugins/aidd-ui/skills/00-product/assets/PRODUCT.md new file mode 100644 index 00000000..d2ec7b19 --- /dev/null +++ b/plugins/aidd-ui/skills/00-product/assets/PRODUCT.md @@ -0,0 +1,31 @@ +# Product: {name} + +> The single source of product intent for the UI recipe. Filled by `aidd-ui:00-product`. + +## Vision + +{What this product is, in one paragraph. The change it makes for whom.} + +## Audience + +| Who | Context | What they need | +| --- | ------- | -------------- | +| {persona} | {when/where they use it} | {the job they hire it for} | + +## Jobs to be done + +- {job, as a user outcome — not a feature} + +## What "good" means here + +| Criterion | How we'd know it's met | +| --------- | --------------------- | +| {testable quality bar} | {observable signal} | + +## Design principles + +- {principle that follows from the criteria above} + +## Constraints + +- {hard constraint: platform, brand, accessibility, performance, scope} diff --git a/plugins/aidd-ui/skills/01-hello/README.md b/plugins/aidd-ui/skills/01-hello/README.md deleted file mode 100644 index 11b4803c..00000000 --- a/plugins/aidd-ui/skills/01-hello/README.md +++ /dev/null @@ -1,29 +0,0 @@ -← [aidd-ui](../../README.md) - -# hello - -Smoke-test skill for the alpha `aidd-ui` plugin. It greets the caller and confirms the plugin loaded. - -## When to use - -- To verify the alpha `aidd-ui` plugin is installed and reachable after a local install or reload. - -## When NOT to use - -- For real UI or UX design, review, or improvement work. Those skills do not exist yet. - -## How to invoke - -`aidd-ui:01-hello` - -## Outputs - -- A short greeting printed in the chat. - -## Prerequisites - -- The plugin loaded locally (`claude --plugin-dir plugins/aidd-ui`, or installed from the marketplace). - -## Technical details - -See [SKILL.md](SKILL.md). diff --git a/plugins/aidd-ui/skills/01-hello/SKILL.md b/plugins/aidd-ui/skills/01-hello/SKILL.md deleted file mode 100644 index ce72346a..00000000 --- a/plugins/aidd-ui/skills/01-hello/SKILL.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -name: 01-hello -description: Smoke-test skill that confirms the aidd-ui plugin loads. Use when the user wants to verify the alpha aidd-ui plugin is installed and reachable. Do NOT use for real UI or UX design work. ---- - -## Available actions - -| ID | Name | Purpose | -| --- | ----- | --------------------------------------------- | -| 01 | greet | Greet the user and confirm the skill works. | - -## Default flow - -Run action `01-greet` and return its message. diff --git a/plugins/aidd-ui/skills/01-hello/actions/01-greet.md b/plugins/aidd-ui/skills/01-hello/actions/01-greet.md deleted file mode 100644 index 176cfcda..00000000 --- a/plugins/aidd-ui/skills/01-hello/actions/01-greet.md +++ /dev/null @@ -1,15 +0,0 @@ -# 01 - greet - -Greets the caller. - -## Inputs - -- none - -## Outputs - -- a short greeting printed in the chat - -## Process - -1. Print "Hello from aidd-ui (alpha)." diff --git a/plugins/aidd-ui/skills/01-wireframe/README.md b/plugins/aidd-ui/skills/01-wireframe/README.md new file mode 100644 index 00000000..2501574a --- /dev/null +++ b/plugins/aidd-ui/skills/01-wireframe/README.md @@ -0,0 +1,32 @@ +← [aidd-framework](../../../../README.md) / [aidd-ui](../../README.md) + +# 01 - wireframe + +Fixes the product's structure before any visual design: the information architecture (screens + navigation) and a low-fidelity sketch of each screen. + +## When to use + +- `PRODUCT.md` exists and the screens and their layout need to be settled before design. + +## When NOT to use + +- You want colors, type, or tokens → use [02-design-system](../02-design-system/README.md). +- You want to write UI code → use [03-build](../03-build/README.md). + +## How to invoke + +``` +Use skill aidd-ui:01-wireframe +``` + +## Outputs + +- A flow/IA map and a low-fidelity wireframe per screen — structure only. + +## Prerequisites + +- `PRODUCT.md` from [00-product](../00-product/README.md). + +## Technical details + +See [`SKILL.md`](SKILL.md), [`assets/wireframe-template.md`](assets/wireframe-template.md), and [`references/wireframe-conventions.md`](references/wireframe-conventions.md). diff --git a/plugins/aidd-ui/skills/01-wireframe/SKILL.md b/plugins/aidd-ui/skills/01-wireframe/SKILL.md new file mode 100644 index 00000000..20b573b2 --- /dev/null +++ b/plugins/aidd-ui/skills/01-wireframe/SKILL.md @@ -0,0 +1,31 @@ +--- +name: 01-wireframe +description: Map the information architecture and sketch each screen at low fidelity, before any visual design. Use after the product is defined, to fix structure and flow. Do NOT use to choose colors, type, or final copy (that is design-system and polish), and not to write code. +argument-hint: flows | wireframe +requires: PRODUCT.md +next: 02-design-system +produces: flows + low-fidelity screens +--- + +# Skill: wireframe + +The structure section of the UI recipe. Fix the information architecture and each screen's layout at low fidelity — no styling, no final copy. + +## Recipe + +Run the steps in order, `01 → 02`. **Exit gate:** `product-critic` validates the flows and wireframes against `PRODUCT.md`; it does not advance to `02-design-system` until they pass. + +## Actions + +| # | Action | Role | Input | +| --- | ----------- | --------------------------------------------- | ---------------------- | +| 01 | `flows` | Map the screens and navigation (IA) | `PRODUCT.md` | +| 02 | `wireframe` | Sketch each screen as a low-fidelity layout | the flows | + +## References + +- `references/wireframe-conventions.md`: how to draw the ASCII wireframes. + +## Assets + +- `assets/wireframe-template.md`: the per-screen wireframe scaffold. diff --git a/plugins/aidd-ui/skills/01-wireframe/actions/01-flows.md b/plugins/aidd-ui/skills/01-wireframe/actions/01-flows.md new file mode 100644 index 00000000..b02a6e88 --- /dev/null +++ b/plugins/aidd-ui/skills/01-wireframe/actions/01-flows.md @@ -0,0 +1,3 @@ +# 01 - Flows + +Map the screens and navigation (information architecture). diff --git a/plugins/aidd-ui/skills/01-wireframe/actions/02-wireframe.md b/plugins/aidd-ui/skills/01-wireframe/actions/02-wireframe.md new file mode 100644 index 00000000..db5e5b74 --- /dev/null +++ b/plugins/aidd-ui/skills/01-wireframe/actions/02-wireframe.md @@ -0,0 +1,3 @@ +# 02 - Wireframe + +Sketch each screen as a low-fidelity layout. diff --git a/plugins/aidd-ui/skills/01-wireframe/assets/wireframe-template.md b/plugins/aidd-ui/skills/01-wireframe/assets/wireframe-template.md new file mode 100644 index 00000000..a000f8aa --- /dev/null +++ b/plugins/aidd-ui/skills/01-wireframe/assets/wireframe-template.md @@ -0,0 +1,16 @@ +# Wireframe: {screen name} + +``` +┌──────────────────────────────┐ +│ [1] {region} │ +├──────────────────────────────┤ +│ [2] {region} │ +│ │ +│ [3] {region} │ +└──────────────────────────────┘ +``` + +| # | Region | Note | +| - | ------ | ---- | +| 1 | {name} | {what it holds, one line} | +| 2 | {name} | {what it holds, one line} | diff --git a/plugins/aidd-ui/skills/01-wireframe/references/wireframe-conventions.md b/plugins/aidd-ui/skills/01-wireframe/references/wireframe-conventions.md new file mode 100644 index 00000000..54fa97c3 --- /dev/null +++ b/plugins/aidd-ui/skills/01-wireframe/references/wireframe-conventions.md @@ -0,0 +1,9 @@ +# Wireframe conventions + +How to draw the low-fidelity ASCII wireframes this skill produces. + +- Box-drawing characters for regions; one box per screen. +- Number every region and give it a one-line note in a table beneath. +- Structure only: no color, no type, no styling, no behavior, no final copy — placeholders like `{...}` stand in for content. + +> Stub: full conventions land later. Mirrors the dev pipeline's wireframe rules until the design extraction merges. diff --git a/plugins/aidd-ui/skills/02-design-system/README.md b/plugins/aidd-ui/skills/02-design-system/README.md new file mode 100644 index 00000000..4e244bd4 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design-system/README.md @@ -0,0 +1,33 @@ +← [aidd-framework](../../../../README.md) / [aidd-ui](../../README.md) + +# 02 - design-system + +Sets the visual foundation the build rests on: first a brand board (the direction), then the tokens and component inventory that formalise it. + +## When to use + +- Wireframes are fixed and the interface needs a visual language before it is built. + +## When NOT to use + +- You want to write UI code → use [03-build](../03-build/README.md). +- You want to define the product → use [00-product](../00-product/README.md). + +## How to invoke + +``` +Use skill aidd-ui:02-design-system +``` + +## Outputs + +- `BRAND-BOARD.md` at the repo root: palette, type, tone, imagery direction. +- `DESIGN-SYSTEM.md` at the repo root: tokens and component inventory with states. + +## Prerequisites + +- `PRODUCT.md` and the wireframes from [00-product](../00-product/README.md) and [01-wireframe](../01-wireframe/README.md). + +## Technical details + +See [`SKILL.md`](SKILL.md), [`assets/BRAND-BOARD.md`](assets/BRAND-BOARD.md), and [`assets/DESIGN-SYSTEM.md`](assets/DESIGN-SYSTEM.md). diff --git a/plugins/aidd-ui/skills/02-design-system/SKILL.md b/plugins/aidd-ui/skills/02-design-system/SKILL.md new file mode 100644 index 00000000..29d44da6 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design-system/SKILL.md @@ -0,0 +1,30 @@ +--- +name: 02-design-system +description: Set the visual direction (brand board), then the tokens and component inventory, into BRAND-BOARD.md and DESIGN-SYSTEM.md. Use after wireframes are fixed, before building. Do NOT use to write UI code (that is build) or to define the product (that is product). +argument-hint: brand-board | tokens | components | system-doc +requires: PRODUCT.md + wireframes +next: 03-build +produces: BRAND-BOARD.md, DESIGN-SYSTEM.md +--- + +# Skill: design-system + +The visual-foundation section of the UI recipe. Set the direction, then formalise it into tokens and components the build consumes. + +## Recipe + +Run the steps in order, `01 → 04`. The brand board comes first — direction before tokens. **Exit gate:** `product-critic` validates `BRAND-BOARD.md` and `DESIGN-SYSTEM.md` against `PRODUCT.md`; it does not advance to `03-build` until they pass. + +## Actions + +| # | Action | Role | Input | +| --- | ------------- | ----------------------------------------------------- | ---------------------- | +| 01 | `brand-board` | Set the visual direction: palette, type, tone, imagery | `PRODUCT.md` | +| 02 | `tokens` | Define design tokens from the direction | brand board | +| 03 | `components` | Inventory the components and their states | tokens + wireframes | +| 04 | `system-doc` | Assemble tokens and components into `DESIGN-SYSTEM.md` | tokens + components | + +## Assets + +- `assets/BRAND-BOARD.md`: the brand-board scaffold, copied to the repo root and filled in. +- `assets/DESIGN-SYSTEM.md`: the design-system scaffold, copied to the repo root and filled in. diff --git a/plugins/aidd-ui/skills/02-design-system/actions/01-brand-board.md b/plugins/aidd-ui/skills/02-design-system/actions/01-brand-board.md new file mode 100644 index 00000000..820f1746 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design-system/actions/01-brand-board.md @@ -0,0 +1,3 @@ +# 01 - Brand board + +Set the visual direction: palette, type, tone, imagery. diff --git a/plugins/aidd-ui/skills/02-design-system/actions/02-tokens.md b/plugins/aidd-ui/skills/02-design-system/actions/02-tokens.md new file mode 100644 index 00000000..24654ca1 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design-system/actions/02-tokens.md @@ -0,0 +1,3 @@ +# 02 - Tokens + +Define design tokens from the visual direction. diff --git a/plugins/aidd-ui/skills/02-design-system/actions/03-components.md b/plugins/aidd-ui/skills/02-design-system/actions/03-components.md new file mode 100644 index 00000000..ba1fee93 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design-system/actions/03-components.md @@ -0,0 +1,3 @@ +# 03 - Components + +Inventory the components and their states. diff --git a/plugins/aidd-ui/skills/02-design-system/actions/04-system-doc.md b/plugins/aidd-ui/skills/02-design-system/actions/04-system-doc.md new file mode 100644 index 00000000..e9dd40fe --- /dev/null +++ b/plugins/aidd-ui/skills/02-design-system/actions/04-system-doc.md @@ -0,0 +1,3 @@ +# 04 - System doc + +Assemble tokens and components into `DESIGN-SYSTEM.md`. diff --git a/plugins/aidd-ui/skills/02-design-system/assets/BRAND-BOARD.md b/plugins/aidd-ui/skills/02-design-system/assets/BRAND-BOARD.md new file mode 100644 index 00000000..00c8a62a --- /dev/null +++ b/plugins/aidd-ui/skills/02-design-system/assets/BRAND-BOARD.md @@ -0,0 +1,23 @@ +# Brand board: {name} + +> The visual direction for the UI recipe. Filled by `aidd-ui:02-design-system`. + +## Feeling + +{Three to five adjectives for how the UI should feel, tied to the product's audience.} + +## Palette + +| Role | Color | Note | +| ---- | ----- | ---- | +| {primary} | {hex} | {when to use} | + +## Typography + +| Role | Typeface | Note | +| ---- | -------- | ---- | +| {display} | {family} | {tone it carries} | + +## Imagery & tone + +- {imagery style, illustration vs photo, iconography, motion feel} diff --git a/plugins/aidd-ui/skills/02-design-system/assets/DESIGN-SYSTEM.md b/plugins/aidd-ui/skills/02-design-system/assets/DESIGN-SYSTEM.md new file mode 100644 index 00000000..a5e0cc06 --- /dev/null +++ b/plugins/aidd-ui/skills/02-design-system/assets/DESIGN-SYSTEM.md @@ -0,0 +1,33 @@ +# Design system: {name} + +> Tokens and components the build pulls from. Filled by `aidd-ui:02-design-system`. + +## Tokens + +### Color +| Token | Value | +| ----- | ----- | +| {color.primary} | {hex} | + +### Spacing +| Token | Value | +| ----- | ----- | +| {space.1} | {value} | + +### Type scale +| Token | Size / line-height | +| ----- | ------------------ | +| {text.body} | {value} | + +### Radius / shadow / motion +| Token | Value | +| ----- | ----- | +| {radius.md} | {value} | +| {shadow.1} | {value} | +| {motion.fast} | {duration / easing} | + +## Components + +| Component | States | Tokens used | +| --------- | ------ | ----------- | +| {Button} | {default, hover, focus, disabled, loading} | {which tokens} | diff --git a/plugins/aidd-ui/skills/03-build/README.md b/plugins/aidd-ui/skills/03-build/README.md new file mode 100644 index 00000000..bf17754d --- /dev/null +++ b/plugins/aidd-ui/skills/03-build/README.md @@ -0,0 +1,32 @@ +← [aidd-framework](../../../../README.md) / [aidd-ui](../../README.md) + +# 03 - build + +Turns the wireframes and design system into real interface code — the visual and interaction layer only. Delegated to the `ui-builder` agent. + +## When to use + +- The design system is set and the interface must be written. + +## When NOT to use + +- You want business logic, data, or architecture → that is the dev pipeline's concern. +- You want to define product or design → use [00-product](../00-product/README.md) or [02-design-system](../02-design-system/README.md). + +## How to invoke + +``` +Use skill aidd-ui:03-build +``` + +## Outputs + +- Hi-fi UI code for the scaffolded layer and each built screen. + +## Prerequisites + +- `DESIGN-SYSTEM.md` and the wireframes. + +## Technical details + +See [`SKILL.md`](SKILL.md). diff --git a/plugins/aidd-ui/skills/03-build/SKILL.md b/plugins/aidd-ui/skills/03-build/SKILL.md new file mode 100644 index 00000000..eed813c0 --- /dev/null +++ b/plugins/aidd-ui/skills/03-build/SKILL.md @@ -0,0 +1,27 @@ +--- +name: 03-build +description: Build the hi-fi interface from the design system, one screen or component at a time, via the ui-builder agent. Use after the design system is set. Do NOT use to write business logic, data, or architecture (that is the dev concern), nor to define product or design. +argument-hint: scaffold | screen +requires: DESIGN-SYSTEM.md + wireframes +next: 04-review +produces: hi-fi UI code +--- + +# Skill: build + +The execution section of the UI recipe. Turn the wireframes and design system into real interface code — the visual and interaction layer only. + +## Recipe + +Run the steps in order, `01 → 02`, delegating each to the `ui-builder` agent. **Exit gate:** `product-critic` validates the built UI against `PRODUCT.md` and `DESIGN-SYSTEM.md`; it does not advance to `04-review` until it passes. + +## Actions + +| # | Action | Role | Input | +| --- | ---------- | ---------------------------------------------------- | --------------------------- | +| 01 | `scaffold` | Set up the UI layer and shared components from tokens | `DESIGN-SYSTEM.md` | +| 02 | `screen` | Build a screen to hi-fi, pulling only defined tokens | wireframe + design system | + +## Agent + +- `ui-builder`: executes both steps. Pulls every value from the design system; invents no token off-book. diff --git a/plugins/aidd-ui/skills/03-build/actions/01-scaffold.md b/plugins/aidd-ui/skills/03-build/actions/01-scaffold.md new file mode 100644 index 00000000..8e7f5513 --- /dev/null +++ b/plugins/aidd-ui/skills/03-build/actions/01-scaffold.md @@ -0,0 +1,3 @@ +# 01 - Scaffold + +Set up the UI layer and shared components from the tokens. diff --git a/plugins/aidd-ui/skills/03-build/actions/02-screen.md b/plugins/aidd-ui/skills/03-build/actions/02-screen.md new file mode 100644 index 00000000..a33f1412 --- /dev/null +++ b/plugins/aidd-ui/skills/03-build/actions/02-screen.md @@ -0,0 +1,3 @@ +# 02 - Screen + +Build a screen to high fidelity, pulling only defined tokens. diff --git a/plugins/aidd-ui/skills/04-review/README.md b/plugins/aidd-ui/skills/04-review/README.md new file mode 100644 index 00000000..41cad024 --- /dev/null +++ b/plugins/aidd-ui/skills/04-review/README.md @@ -0,0 +1,32 @@ +← [aidd-framework](../../../../README.md) / [aidd-ui](../../README.md) + +# 04 - review + +Judges the built UI against the product's bar across four axes — heuristics, accessibility, responsive, visual — into one report. Read-only; it never patches. Owned by the `product-critic` agent. + +## When to use + +- A screen or flow is built and needs critique before polish. + +## When NOT to use + +- You want to fix the findings → route back to [03-build](../03-build/README.md) or on to [05-polish](../05-polish/README.md). +- You want to review non-UI code → use the dev pipeline's review. + +## How to invoke + +``` +Use skill aidd-ui:04-review +``` + +## Outputs + +- A review report with findings per axis and a gate verdict. + +## Prerequisites + +- A built UI and `DESIGN-SYSTEM.md`. + +## Technical details + +See [`SKILL.md`](SKILL.md), [`assets/review-report-template.md`](assets/review-report-template.md), and [`references/`](references/). diff --git a/plugins/aidd-ui/skills/04-review/SKILL.md b/plugins/aidd-ui/skills/04-review/SKILL.md new file mode 100644 index 00000000..30f118c6 --- /dev/null +++ b/plugins/aidd-ui/skills/04-review/SKILL.md @@ -0,0 +1,38 @@ +--- +name: 04-review +description: Critique the built UI on four axes — heuristics, accessibility, responsive, visual — into one report, via the product-critic agent. Use after building, before polish. Do NOT use to fix the findings (that is build and polish) or to review non-UI code. +argument-hint: heuristics | accessibility | responsive | visual +requires: built UI +next: 05-polish +produces: review report +--- + +# Skill: review + +The critique section of the UI recipe. Judge the built interface against the product's bar and surface what blocks it — read-only, never patches. + +## Recipe + +Run the steps in order, `01 → 04`, then assemble one report. **Exit gate:** the `product-critic` agent owns the verdict; the recipe does not advance to `05-polish` until the report clears the bar (or its blockers are routed back to `03-build`). + +## Actions + +| # | Action | Role | Input | +| --- | --------------- | --------------------------------------------------- | -------------- | +| 01 | `heuristics` | Hierarchy, cognitive load, UX heuristics | built UI | +| 02 | `accessibility` | WCAG / a11y conformance | built UI | +| 03 | `responsive` | Breakpoints and reflow | built UI | +| 04 | `visual` | Consistency against `DESIGN-SYSTEM.md` | built UI + DS | + +## References + +- `references/ux-heuristics.md`: the heuristics checklist for `01`. +- `references/a11y-checklist.md`: the accessibility checklist for `02`. + +## Assets + +- `assets/review-report-template.md`: the report scaffold the four axes fill. + +## Agent + +- `product-critic`: owns the critique and the gate verdict. diff --git a/plugins/aidd-ui/skills/04-review/actions/01-heuristics.md b/plugins/aidd-ui/skills/04-review/actions/01-heuristics.md new file mode 100644 index 00000000..d7384ee4 --- /dev/null +++ b/plugins/aidd-ui/skills/04-review/actions/01-heuristics.md @@ -0,0 +1,3 @@ +# 01 - Heuristics + +Hierarchy, cognitive load, UX heuristics. diff --git a/plugins/aidd-ui/skills/04-review/actions/02-accessibility.md b/plugins/aidd-ui/skills/04-review/actions/02-accessibility.md new file mode 100644 index 00000000..ae0e9f5f --- /dev/null +++ b/plugins/aidd-ui/skills/04-review/actions/02-accessibility.md @@ -0,0 +1,3 @@ +# 02 - Accessibility + +WCAG / a11y conformance. diff --git a/plugins/aidd-ui/skills/04-review/actions/03-responsive.md b/plugins/aidd-ui/skills/04-review/actions/03-responsive.md new file mode 100644 index 00000000..61eff4a8 --- /dev/null +++ b/plugins/aidd-ui/skills/04-review/actions/03-responsive.md @@ -0,0 +1,3 @@ +# 03 - Responsive + +Breakpoints and reflow. diff --git a/plugins/aidd-ui/skills/04-review/actions/04-visual.md b/plugins/aidd-ui/skills/04-review/actions/04-visual.md new file mode 100644 index 00000000..206b3b90 --- /dev/null +++ b/plugins/aidd-ui/skills/04-review/actions/04-visual.md @@ -0,0 +1,3 @@ +# 04 - Visual + +Consistency against `DESIGN-SYSTEM.md`. diff --git a/plugins/aidd-ui/skills/04-review/assets/review-report-template.md b/plugins/aidd-ui/skills/04-review/assets/review-report-template.md new file mode 100644 index 00000000..1ef9aaf9 --- /dev/null +++ b/plugins/aidd-ui/skills/04-review/assets/review-report-template.md @@ -0,0 +1,16 @@ +# UI review: {screen or flow} + +> Read-only critique. Filled by `aidd-ui:04-review`, judged by `product-critic`. + +## Verdict + +{passes the gate | blocked} — {one-line reason} + +## Findings + +| Axis | Severity | Element | Finding | What clears it | +| ---- | -------- | ------- | ------- | -------------- | +| heuristics | {🔴/🟡/🟢} | {element} | {what's wrong} | {the fix that clears the bar} | +| accessibility | | | | | +| responsive | | | | | +| visual | | | | | diff --git a/plugins/aidd-ui/skills/04-review/references/a11y-checklist.md b/plugins/aidd-ui/skills/04-review/references/a11y-checklist.md new file mode 100644 index 00000000..0600028e --- /dev/null +++ b/plugins/aidd-ui/skills/04-review/references/a11y-checklist.md @@ -0,0 +1,11 @@ +# Accessibility checklist + +The a11y items the `02-accessibility` action walks against each screen. + +- [ ] Contrast: text and UI meet WCAG AA against their background. +- [ ] Focus: every interactive element has a visible focus state. +- [ ] Keyboard: the whole flow is operable without a pointer. +- [ ] Semantics: elements use the right role; headings nest in order. +- [ ] Labels: inputs, icons, and controls have accessible names. + +> Stub: full WCAG mapping lands later. diff --git a/plugins/aidd-ui/skills/04-review/references/ux-heuristics.md b/plugins/aidd-ui/skills/04-review/references/ux-heuristics.md new file mode 100644 index 00000000..f8855cea --- /dev/null +++ b/plugins/aidd-ui/skills/04-review/references/ux-heuristics.md @@ -0,0 +1,11 @@ +# UX heuristics checklist + +The heuristics the `01-heuristics` action walks against each screen. + +- [ ] Visual hierarchy: the primary action is the most prominent thing on screen. +- [ ] Cognitive load: nothing on screen that the user does not need now. +- [ ] Feedback: every action has a visible response. +- [ ] Consistency: same thing looks and behaves the same everywhere. +- [ ] Recognition over recall: options are visible, not remembered. + +> Stub: full heuristic set lands later. diff --git a/plugins/aidd-ui/skills/05-polish/README.md b/plugins/aidd-ui/skills/05-polish/README.md new file mode 100644 index 00000000..90219e54 --- /dev/null +++ b/plugins/aidd-ui/skills/05-polish/README.md @@ -0,0 +1,31 @@ +← [aidd-framework](../../../../README.md) / [aidd-ui](../../README.md) + +# 05 - polish + +The last section of the recipe. Takes a reviewed UI from correct to impeccable: the states it forgot, the motion that makes it feel alive, and the words that carry it. Delegated to the `ui-builder` agent. + +## When to use + +- The UI is built and reviewed, and needs its finishing layer. + +## When NOT to use + +- You want to restructure the UI or change the design system → use [03-build](../03-build/README.md) or [02-design-system](../02-design-system/README.md). + +## How to invoke + +``` +Use skill aidd-ui:05-polish +``` + +## Outputs + +- The finished UI: states, motion, and UX copy in place. + +## Prerequisites + +- A reviewed UI from [04-review](../04-review/README.md). + +## Technical details + +See [`SKILL.md`](SKILL.md). diff --git a/plugins/aidd-ui/skills/05-polish/SKILL.md b/plugins/aidd-ui/skills/05-polish/SKILL.md new file mode 100644 index 00000000..eece1c9e --- /dev/null +++ b/plugins/aidd-ui/skills/05-polish/SKILL.md @@ -0,0 +1,28 @@ +--- +name: 05-polish +description: Finish the UI — empty/error/loading states, motion, and UX copy — via the ui-builder agent. Use as the last section of the recipe, after review. Do NOT use to restructure the UI or change the design system. +argument-hint: states | motion | copy +requires: reviewed UI +next: "—" +produces: finished UI +--- + +# Skill: polish + +The finishing section of the UI recipe. Take a reviewed UI from correct to impeccable: the states it forgot, the motion that makes it feel alive, the words that carry it. + +## Recipe + +Run the steps in order, `01 → 03`, delegating each to the `ui-builder` agent. **Exit gate:** `product-critic` gives the final verdict against `PRODUCT.md`. Passing it is the end of the recipe. + +## Actions + +| # | Action | Role | Input | +| --- | -------- | ----------------------------------------------------- | ------------ | +| 01 | `states` | Empty, error, loading, and edge states | reviewed UI | +| 02 | `motion` | Micro-interactions and transitions | reviewed UI | +| 03 | `copy` | UX copy: labels, empty states, errors, microcopy | reviewed UI | + +## Agent + +- `ui-builder`: executes all three steps within the design system's motion and type tokens. diff --git a/plugins/aidd-ui/skills/05-polish/actions/01-states.md b/plugins/aidd-ui/skills/05-polish/actions/01-states.md new file mode 100644 index 00000000..0524898c --- /dev/null +++ b/plugins/aidd-ui/skills/05-polish/actions/01-states.md @@ -0,0 +1,3 @@ +# 01 - States + +Empty, error, loading, and edge states. diff --git a/plugins/aidd-ui/skills/05-polish/actions/02-motion.md b/plugins/aidd-ui/skills/05-polish/actions/02-motion.md new file mode 100644 index 00000000..fd23608f --- /dev/null +++ b/plugins/aidd-ui/skills/05-polish/actions/02-motion.md @@ -0,0 +1,3 @@ +# 02 - Motion + +Micro-interactions and transitions. diff --git a/plugins/aidd-ui/skills/05-polish/actions/03-copy.md b/plugins/aidd-ui/skills/05-polish/actions/03-copy.md new file mode 100644 index 00000000..358161a6 --- /dev/null +++ b/plugins/aidd-ui/skills/05-polish/actions/03-copy.md @@ -0,0 +1,3 @@ +# 03 - Copy + +UX copy: labels, empty states, errors, microcopy.