feat(framework): add review checklist consumed by the reviewer agent

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
 

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.

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

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

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

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

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

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

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

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
 

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.

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

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.

plugins/aidd-context/skills/04-skill-generate/actions/04-write-actions.md

@@ -14,11 +14,13 @@ One file per action, per confirmed tool, at `<skills root>/<name>/actions/<NN>-<
 
 1. **Resolve.** Host mode: for each confirmed tool, resolve the skills root from `@../references/tool-paths.md`. Plugin source: use `plugins/<plugin>/skills/<name>/`.
 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 `@<path>`. Never "read X then apply".
-4. **Validate.** Run the write-target validation (`@../references/tool-paths.md`).
+4. **Compose.** Include any template or reference via `@<path>`. 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.

plugins/aidd-context/skills/04-skill-generate/assets/skill-template.md

@@ -1,6 +1,7 @@
 ---
 name: <skill-name>
 description: <What the skill does, third person, one clause>. Use when <explicit, slightly pushy trigger phrases users actually type; the model under-triggers, so over-list>. <Optional: "Not for <X>, use <Y>" 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: <action-name-1 | action-name-2> # omit when the skill has only one action
 ---
 
 # <Skill Name>

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.
 

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

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.

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
 

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

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

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

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

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

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