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/aidd_docs/review-checklist.md b/aidd_docs/review-checklist.md new file mode 100644 index 00000000..94f313e5 --- /dev/null +++ b/aidd_docs/review-checklist.md @@ -0,0 +1,11 @@ +# Review Checklist + +Recurring defects the reviewer ticks on every code/diff review, so they get caught in any diff. + +- [ ] **No information duplication** — DRY across code *and* docs; link to the canonical home instead of copying. +- [ ] **No incoherence / contradiction** — naming, behavior, and docs-vs-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 TODOs left silently. +- [ ] **Consistent with existing patterns** — follows the conventions already established in the codebase. +- [ ] **Clear, explicit naming** — names reveal intent; no misleading or vague identifiers. +- [ ] **Errors handled** — no swallowed exceptions, no ignored failure paths. 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/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/CATALOG.md b/plugins/aidd-context/CATALOG.md index 3ce4b47f..33717088 100644 --- a/plugins/aidd-context/CATALOG.md +++ b/plugins/aidd-context/CATALOG.md @@ -79,6 +79,7 @@ Auto-generated index of skills, agents, references and assets shipped by the `ai | `assets` | [CONTRIBUTING.md](skills/02-project-memory/assets/CONTRIBUTING.md) | - | | `assets` | [GUIDELINES.md](skills/02-project-memory/assets/GUIDELINES.md) | - | | `assets` | [README.md](skills/02-project-memory/assets/README.md) | - | +| `assets` | [review-checklist.md](skills/02-project-memory/assets/review-checklist.md) | - | | `-` | [README.md](skills/02-project-memory/README.md) | - | | `references` | [capability-signals.md](skills/02-project-memory/references/capability-signals.md) | - | | `references` | [mapping-ai-context-file.md](skills/02-project-memory/references/mapping-ai-context-file.md) | - | 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..20dab626 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 @@ -41,4 +42,5 @@ The core concerns load always. The `internal/` and `external/` directories are l - `assets/AGENTS.md`: the context-file template. - `assets/README.md`, `assets/GUIDELINES.md`, `assets/CONTRIBUTING.md`: the `aidd_docs/` doc templates. +- `assets/review-checklist.md`: the `aidd_docs/review-checklist.md` template — baseline rules the reviewer agent applies on code reviews. - `assets/templates/memory/`: the memory templates, one folder per capability (`core` always, the rest gated by signal). diff --git a/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md b/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md index b2f99bc4..e5ae0555 100644 --- a/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md +++ b/plugins/aidd-context/skills/02-project-memory/actions/02-scaffold-docs.md @@ -8,15 +8,15 @@ The project root. ## Output -`aidd_docs/` with `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md`, `memory/README.md`, and `memory/{internal,external}/.gitkeep`. +`aidd_docs/` with `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md`, `review-checklist.md`, `memory/README.md`, and `memory/{internal,external}/.gitkeep`. ## Process -1. **Docs.** For each of `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md`: write it from the matching `@../assets/` template if absent, or update it in place while preserving the user's customizations. +1. **Docs.** For each of `README.md`, `GUIDELINES.md`, `CONTRIBUTING.md`, `review-checklist.md`: write it from the matching `@../assets/` template if absent, or update it in place while preserving the user's customizations. 2. **Memory dirs.** Ensure `aidd_docs/memory/internal/` and `aidd_docs/memory/external/` exist, each with a `.gitkeep`. 3. **Memory readme.** Write `aidd_docs/memory/README.md` from `@../assets/templates/memory/README.md` if absent, leaving an existing one untouched. 4. **Report.** Print a table: path, action taken (created, updated, or skipped). ## Test -- `aidd_docs/` holds the three docs, `memory/README.md`, and both memory subdirectories with their `.gitkeep`. +- `aidd_docs/` holds the four docs, `memory/README.md`, and both memory subdirectories with their `.gitkeep`. 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/02-project-memory/assets/review-checklist.md b/plugins/aidd-context/skills/02-project-memory/assets/review-checklist.md new file mode 100644 index 00000000..94f313e5 --- /dev/null +++ b/plugins/aidd-context/skills/02-project-memory/assets/review-checklist.md @@ -0,0 +1,11 @@ +# Review Checklist + +Recurring defects the reviewer ticks on every code/diff review, so they get caught in any diff. + +- [ ] **No information duplication** — DRY across code *and* docs; link to the canonical home instead of copying. +- [ ] **No incoherence / contradiction** — naming, behavior, and docs-vs-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 TODOs left silently. +- [ ] **Consistent with existing patterns** — follows the conventions already established in the codebase. +- [ ] **Clear, explicit naming** — names reveal intent; no misleading or vague identifiers. +- [ ] **Errors handled** — no swallowed exceptions, no ignored failure paths. 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/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-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..f428707a 100644 --- a/plugins/aidd-dev/CATALOG.md +++ b/plugins/aidd-dev/CATALOG.md @@ -53,18 +53,19 @@ 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-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.` | +| `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` @@ -88,29 +89,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 +147,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/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/agents/reviewer.md b/plugins/aidd-dev/agents/reviewer.md index 6724f012..1e59e87e 100644 --- a/plugins/aidd-dev/agents/reviewer.md +++ b/plugins/aidd-dev/agents/reviewer.md @@ -18,6 +18,8 @@ When invoked, you receive: - 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 +On every review, read the project review checklist at `aidd_docs/review-checklist.md` (path relative to the repository root, your working directory) with your Read tool, and apply each item; skip silently if the file is absent. Render the checklist ticked in your output — `- [x]` when met, `- [ ]` with the offending `file:line` when not. + # Outputs When you return, your output is structured: @@ -59,6 +61,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. 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/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/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 9fd3e2d9..ba696e19 100644 --- a/plugins/aidd-dev/skills/01-plan/SKILL.md +++ b/plugins/aidd-dev/skills/01-plan/SKILL.md @@ -1,43 +1,31 @@ --- name: 01-plan -description: Generate technical implementation plans, define component behaviors, and extract design details from images. -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/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/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-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-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 d7d77ef6..94b10962 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 | 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. 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."); +}