refactor(framework): canonical action shape, model-A rules, plugin audit sweep

Action shape (R8). Every skill-internal action across aidd-context, aidd-dev, aidd-pm, aidd-vcs, aidd-refine, aidd-orchestrator now follows the canonical Inputs / Outputs / Process / Test shape. 20 legacy command-style actions converted in aidd-dev (01-plan, 02-implement, 03-assert, 04-audit, 05-review, 06-test, 07-refactor, 08-debug, 09-for-sure), 1 in aidd-context (04-mermaid), 2 in aidd-context:03:context-generate (agents, rules). Frontmatter stripped from every skill-internal action; kept only on context-generate sub-domain entries that are routed standalone.

Rules surface (Model A). Rules live in tool-native locations only - no aidd_docs/rules/ master, no bare rules/ scaffold. aidd-dev/scripts/list-rules.mjs rewritten to scan every installed AI tool (.claude/rules/, .cursor/rules/*.mdc, .github/instructions/*.instructions.md, .opencode/rules/) and emit a normalised tool-tagged JSON inventory; inline YAML array parser added for paths/globs/applyTo. Script moved from framework root to plugins/aidd-dev/scripts/ so installs reach it. aidd-context:02:project-init drops 05-init-rules-skeleton and shortens to five actions (memory-only scaffold); aidd-context:03:context-generate:rules:01-generate-rules creates rules root + category dirs on demand. aidd-context:03:context-generate references/rule-structure.md path-convention generalised: file location encodes category and slug, root and ext defer to ai-mapping.md. aidd-dev:01:plan rules-inventory step now consumes the tool-tagged JSON; plan-template Applicable Rules table gains a Tool column.

Discovery (aidd-context:06). Skill expanded from one find-skill action to five: 01-find-skill, 02-find-agent, 03-find-command, 04-find-plugin, 05-find-mcp. SKILL.md routes by user phrasing; find-agent filters template artefacts. Evals cover all five surfaces + cross-skill negatives.

Condense (aidd-refine:03). Adopted relevant pieces of the caveman plugin without cloning it. Description re-anchored on durable project rules / conventions / decisions with concrete trigger phrases; persistence section + explicit off-switch phrases ("stop condense", "normal mode", "/condense off"); per-level examples (React, DB pool, debounce) and an Auto-pause walkthrough in references/intensity-levels.md. New 02-stats action plus a UserPromptSubmit hook at hooks/condense-stats.js that reads the session transcript, detects intensity transitions, computes approximate token savings, and returns the formatted report so the model is not invoked.

Cross-plugin sweep. aidd-orchestrator: redundant actions/skills/ subdir flattened across the three async-dev skills (21 actions moved), broken @-ref in 03-review-async-dev/SKILL.md fixed, "Generated by aidd-orchestrator:03:review-async-dev" leak dropped from PR comment template. aidd-pm: 05-spec renamed to 04-spec to close the gap left by the deleted 04-clarity (SKILL.md name + three external refs updated). aidd-dev/agents: 22 em-dashes purged from planner / reviewer / implementer; cross-plugin invocations (aidd-vcs:01:commit, aidd-refine, aidd-context:04:mermaid, aidd-context:05:learn) kept where functional (agent orchestration). aidd-context:01:bootstrap and aidd-orchestrator:03:review-async-dev drop "Generated by <skill-id>" footers from generated artefacts.

Project-init memory description (`aidd-context:02:project-init` SKILL.md) trimmed: scaffold no longer claims to create a rules directory. CONTRIBUTING.md refs updated alongside the aidd-pm rename. learn (aidd-context:05) gate now respects explicit user invocation: the worth-learning check runs only on auto-trigger; explicit invocation bypasses it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: blafourcade

aidd_docs/CONTRIBUTING.md

@@ -23,7 +23,7 @@ All templates live alongside the skill that owns them, under `plugins/<plugin>/s
 | `aidd-context:03:context-generate/assets/agents/`  | Agent file template                                      |
 | `aidd-context:03:context-generate/assets/rules/`   | Rule file template                                       |
 | `aidd-pm:03:prd/assets/`                           | PRD body template                                        |
-| `aidd-pm:05:spec/assets/`                          | Spec template and validator                              |
+| `aidd-pm:04:spec/assets/`                          | Spec template and validator                              |
 | `aidd-dev:01:plan/assets/`                         | Plan and master-plan templates                           |
 | `aidd-vcs:01:commit/assets/`                       | Conventional commit message template                     |
 | `aidd-vcs:02:pull-request/assets/`                 | Pull/merge request body template, contributing example   |

plugins/aidd-context/skills/02-project-init/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: aidd-context:02:project-init
-description: Initialize or refresh the project memory bank, scaffold the rules directory, and ensure AI context files contain the project memory block. Use when running `aidd init` for the first time, bootstrapping a new project, or re-running the init flow on an existing project. Do NOT use for updating individual memory files after they exist - use `aidd-context:05:learn` instead; do NOT use for editing a single rule - edit the file directly.
+description: Initialize or refresh the project memory bank and ensure AI context files contain the project memory block. Use when running `aidd init` for the first time, bootstrapping a new project, or re-running the init flow on an existing project. Do NOT use for updating individual memory files after they exist - use `aidd-context:05:learn` instead; do NOT use for editing a single rule - edit the file directly.
 model: opus
 ---
 
 # Project Init
 
-Bootstraps the full AIDD context layer for a project: AI context files with memory block, `aidd_docs/` documentation structure, memory bank files, and rules directory skeleton.
+Bootstraps the AIDD context layer for a project: AI context files with memory block, `aidd_docs/` documentation structure, and the memory bank files. Rule directories are created lazily by `aidd-context:03:context-generate` when the first rule is written; project-init does not pre-scaffold them.
 
 ## Available actions
 
@@ -16,12 +16,11 @@ Bootstraps the full AIDD context layer for a project: AI context files with memo
 | 02  | `scaffold-docs`       | Create `aidd_docs/` structure with README and GUIDELINES          | project root                |
 | 03  | `generate-memory`     | Detect project type and generate memory files in parallel         | `aidd_docs/memory/` from 02 |
 | 04  | `review-memory`       | Cross-file consistency review of all generated memory files       | `aidd_docs/memory/` from 03 |
-| 05  | `init-rules-skeleton` | Create `rules/` skeleton with 10 numbered phase directories       | project root                |
-| 06  | `sync-memory`         | Execute `update_memory.js` to fill `<aidd_project_memory>` blocks | context files from 01       |
+| 05  | `sync-memory`         | Execute `update_memory.js` to fill `<aidd_project_memory>` blocks | context files from 01       |
 
 ## Default flow
 
-`01 → 02 → 03 → 04 → 05 → 06`. Run each action's `## Test` before moving to the next.
+`01 → 02 → 03 → 04 → 05`. Run each action's `## Test` before moving to the next.
 
 ## Transversal rules
 

plugins/aidd-context/skills/02-project-init/actions/05-init-rules-skeleton.md

@@ -23,7 +23,7 @@ All templates live alongside the skill that owns them, under `plugins/<plugin>/s
 | `aidd-context:03:context-generate/assets/agents/`  | Agent file template                                      |
 | `aidd-context:03:context-generate/assets/rules/`   | Rule file template                                       |
 | `aidd-pm:03:prd/assets/`                           | PRD body template                                        |
-| `aidd-pm:05:spec/assets/`                          | Spec template and validator                              |
+| `aidd-pm:04:spec/assets/`                          | Spec template and validator                              |
 | `aidd-dev:01:plan/assets/`                         | Plan and master-plan templates                           |
 | `aidd-vcs:01:commit/assets/`                       | Conventional commit message template                     |
 | `aidd-vcs:02:pull-request/assets/`                 | Pull/merge request body template, contributing example   |

…2-project-init/actions/06-sync-memory.md …2-project-init/actions/05-sync-memory.mdplugins/aidd-context/skills/02-project-init/actions/06-sync-memory.md renamed to plugins/aidd-context/skills/02-project-init/actions/05-sync-memory.md plugins/aidd-context/skills/02-project-init/actions/06-sync-memory.md renamed to plugins/aidd-context/skills/02-project-init/actions/05-sync-memory.md

@@ -109,7 +109,7 @@ A typical change cycles through skills from several plugins. The order below is
 
 1. **Bootstrap** (only for a brand-new project): `aidd-context:01:bootstrap` imagines the stack and architecture, comparing candidate stacks and writing an `INSTALL.md`. Skip this step on an existing project.
 2. **Project init** (once per project, re-runnable to refresh): `aidd-context:02:project-init` scaffolds `aidd_docs/`, the memory bank, and the AI context files for the tools you use. Re-running later refreshes the scaffold without overwriting your customizations.
-3. **Frame the request**: `aidd-refine:01:brainstorm` to clarify, `aidd-pm:01:ticket-info` to pull tracker data, `aidd-pm:02:user-stories-create` and `aidd-pm:03:prd` or `aidd-pm:05:spec` to formalize scope.
+3. **Frame the request**: `aidd-refine:01:brainstorm` to clarify, `aidd-pm:01:ticket-info` to pull tracker data, `aidd-pm:02:user-stories-create` and `aidd-pm:03:prd` or `aidd-pm:04:spec` to formalize scope.
 4. **Plan**: `aidd-dev:01:plan` produces the technical plan, component behavior model, or design-image extraction.
 5. **Implement and assert**: `aidd-dev:02:implement` writes code against the plan; `aidd-dev:03:assert` verifies the result.
 6. **Review**: `aidd-dev:05:review` for code and functional review; `aidd-refine:02:challenge` to stress-test the result.

plugins/aidd-context/skills/02-project-init/assets/CONTRIBUTING.md

@@ -1,49 +1,36 @@
----
-name: generate_agent
-description: Generates a customized agent based on user-defined parameters.
-model: sonnet
----
+# 01 - Generate agent
 
-# Goal
+Generate a specialized agent file tailored to user requirements, validated with the user before write, and saved to every installed AI tool's native agents location.
 
-Generate a specialized agent template tailored to specific user requirements.
+## Inputs
 
-## Context
-
-### Coordination with other agents
-
-```markdown
-@../../references/agents-coordination.md
-```
-
-### Agent template
-
-```markdown
-@../../assets/agents/agent-template.md
+```yaml
+agent_request: <free-form description of the agent's purpose, tools, and instructions>
 ```
 
-### AI Mapping
-
-Apply tool-native conventions for agent file paths, naming, and extensions.
+## Outputs
 
-```markdown
-@../../references/ai-mapping.md
+```yaml
+agent_path: <tool-specific agents location>/<generated-agent-name>.<ext>
+name_proposals:
+  - <short catchy name 1>
+  - <short catchy name 2>
+  - <short catchy name 3>
+quality_score: 1-10
 ```
 
-## Rules
+## Process
 
-- Input and Output for the agent MUST be ULTRA concise and precise.
-- Ask clarifying questions if the user's request is ambiguous or lacks detail.
-- When mentioning templates in `aidd_docs`, always provide full path
+1. **Gather requirements.** Ask the user clarifying questions until the agent template is fillable. Iterate until the agent's purpose, tools, inputs, and instructions are unambiguous.
+2. **Fill the template** at `@../../assets/agents/agent-template.md`. Apply the coordination conventions in `@../../references/agents-coordination.md`.
+3. **Review.** Score the generated agent 1-10 on clarity and completeness. Boundaries:
+   - Inputs and outputs MUST be ultra concise and precise.
+   - When mentioning templates in `aidd_docs/`, always provide the full path.
+4. **Wait for user confirmation** before finalizing.
+5. **Propose 3 first names** for the agent. Each name must be short and catchy, making sense with the agent's purpose (word game, acronym, etc.).
+6. **Save.** Write the completed agent file to every installed AI tool's native agents location using its path, naming, and extension conventions from `@../../references/ai-mapping.md`. Skip tools whose agents surface is marked "not supported".
+7. **Update the catalog.** Add the new agent entry into `@aidd_docs/CATALOG.md`.
 
-## Instruction steps
+## Test
 
-1. Ask following questions to the user until you gather all necessary information in agent's template.
-   1. Discuss with the user until you have a clear understanding of the agent's purpose, tools, and instructions.
-   2. Use the gathered information to fill in the agent template.
-2. Review the generated agent to ensure it is straightforward with 0 ambiguity.
-   1. Affect a note between 1 and 10 to the generated agent based on its relevance and completeness.
-3. **Wait for user confirmation before finalizing the agent.**
-4. Propose 3 real first names for the agent, each name must be short and catchy, making sense with the agent's purpose (could be word game, acronym, etc.).
-5. Provide the completed agent template as the final output, written to the AI tool's native agents directory as `<generated-agent-name>.md`.
-6. Add the new prompt into the `@aidd_docs/CATALOG.md` to keep documentation up to date.
+The agent file exists at `agent_path` in every installed tool's agents location (skipping unsupported surfaces); the file matches the structure of `@../../assets/agents/agent-template.md`; `quality_score >= 8`; `@aidd_docs/CATALOG.md` contains a new row referencing the generated agent.

plugins/aidd-context/skills/02-project-init/assets/README.md

@@ -1,104 +1,61 @@
----
-name: generate_rules
-description: Generate or modify coding rules manually or auto-scan the codebase to propose rules
-argument-hint: "Rule topic to write, or 'auto' to scan codebase and propose rules"
-model: sonnet
----
+# 01 - Generate rules
 
-# Generate Rules
+Generate or modify coding rules, either from user input (manual mode) or by scanning the codebase (auto mode), then write each rule into every installed AI tool's native rules surface.
 
-## Goal
+## Inputs
 
-Generate or modify coding rules, either from user input (manual) or by scanning the codebase (auto).
-
-## Outcome
-
-Create structured markdown rule (.mdc or .md depending on the IDE) files with proper front-matter and content, plus IDE bridge files.
-
-## Resources
-
-### Template
-
-```markdown
-@../../assets/rules/rule-template.md
+```yaml
+arguments: <rule topic to write, or "auto"/"scan" to scan the codebase and propose rules>
 ```
 
-### IDE Mapping
-
-Apply tool-native conventions for rule file paths, naming, and extensions.
-
-```markdown
-@../../references/ai-mapping.md
-```
-
-## Context
-
-### User input
+## Outputs
 
-```text
-$ARGUMENTS
+```yaml
+mode: auto | manual
+files_written:
+  - { tool: <id>, path: <tool rules root>/<category>/<slug>.<ext> }
+  - ...
 ```
 
-### Example rule file structure
+## Process
 
-```text
-03-frameworks-and-libraries/
-├── 3-react@19-components-structure.md (globs: ['**/*.tsx', '**/components/**', ...])
-│   ├── Component definition basics
-│   ├── Export patterns
-│   ├── Props and typing
-│   └── Naming conventions
-└── ...
-```
-
-## Rules
-
-- Be concise, less is more
-- If multiple examples, then multiple rule files
-- Frontmatter and tool-specific syntax (extensions, paths, globs) live in the references below
-
-### Rule writing standards
-
-```markdown
-@../../references/rule-writing.md
-```
-
-### Rule file structure
-
-```markdown
-@../../references/rule-structure.md
-```
+1. **Detect mode.**
+   - `arguments` is `auto` or `scan` -> auto mode (step 2A).
+   - Otherwise -> manual mode (step 2B).
 
-## Steps
+2A. **Auto mode - scan codebase.**
+   - Scan source files, configs, dependencies, and directory structure.
+   - Identify patterns, conventions, tech stack usage, existing rules.
+   - Propose a complete rules architecture: list categories and rule files, show groups and sub-groups per file, display the proposed file tree.
+   - WAIT FOR USER APPROVAL before proceeding to step 3.
 
-### Step 1: Detect mode
+2B. **Manual mode - user-guided.**
+   - Remind project context: tech stack, versions, architecture, existing rules.
+   - Define categories, one file per category.
+   - Look for existing rules to update.
+   - Plan the new rule(s) structure: file, groups and sub-groups, display the proposed architecture.
+   - WAIT FOR USER APPROVAL before proceeding to step 3.
 
-- If `$ARGUMENTS` is "auto" or "scan" → **Auto mode** (Step 2A)
-- Otherwise → **Manual mode** (Step 2B)
+3. **Generate.** For every installed AI tool, write the rule file inside that tool's rules root using `@../../assets/rules/rule-template.md` and the conventions in `@../../references/ai-mapping.md` (path, naming, extension, frontmatter). Skip any tool whose rules surface is marked "not supported". Create the rules root and the category subdirectory on demand (`mkdir -p`) before writing; do not assume the directory tree has been pre-scaffolded.
 
-### Step 2A: Auto mode - Scan codebase
+   The category subdirectory and the slug stay identical across tools; only the root, extension, and frontmatter shape differ. Refer to `@../../references/rule-structure.md` and `@../../references/rule-writing.md` for content conventions.
 
-1. Scan project: source files, configs, dependencies, directory structure
-2. Identify patterns, conventions, tech stack usage, and existing rules
-3. Propose a complete rules architecture:
-   - List categories and rule files
-   - Show groups and sub-groups per file
-   - Display proposed file tree
-4. **Wait for user approval** before proceeding
-5. → Go to Step 3
+   Reference example rule file structure (illustrative):
 
-### Step 2B: Manual mode - User-guided
+   ```text
+   03-frameworks-and-libraries/
+   ├── 3-react@19-components-structure.<ext> (paths: ['**/*.tsx', '**/components/**', ...])
+   │   ├── Component definition basics
+   │   ├── Export patterns
+   │   ├── Props and typing
+   │   └── Naming conventions
+   └── ...
+   ```
 
-1. Remind project context: tech stack, versions, architecture, existing rules
-2. Define categories, 1 file per category
-3. Look for existing rules to update
-4. Plan the new rule(s) structure:
-   - File
-   - Define groups and sub-groups
-   - Display proposed architecture
-5. **Wait for user approval** before proceeding
-6. → Go to Step 3
+4. **Boundaries.**
+   - Be concise. Less is more.
+   - If multiple examples warrant separate files, create multiple rule files.
 
-### Step 3: Generate
+## Test
 
-Generate the rules based on the template, following the IDE mapping conventions for file path, naming and extension.
+For every installed AI tool whose rules surface is supported, the generated rule file exists at `<tool rules root>/<category>/<slug>.<ext>` with frontmatter matching the tool-specific shape from `@../../references/ai-mapping.md`. Content follows the conventions in `@../../references/rule-writing.md` and `@../../references/rule-structure.md`.

plugins/aidd-context/skills/03-context-generate/actions/agents/01-generate-agent.md

@@ -37,6 +37,12 @@ Naming pattern for React rules in `03-frameworks-and-libraries` category:
 - `3-react@19-hooks`
 - `3-react@19.1-hooks`
 
+## Path convention
+
+The physical location of a rule encodes its `category` and `slug`. The category is the subdirectory; the slug is the file name (`<#-slug[@version][-specificity]>.<ext>`). Frontmatter never carries the rule path; downstream tools derive it from the file location alone.
+
+The base directory and the file extension are tool-specific. Refer to `@ai-mapping.md` for the exact path per AI tool, including tools where rules are not supported.
+
 ## Frontmatter and tool-specific syntax
 
 Frontmatter fields, file extensions, glob path syntax, and on-disk locations are tool-specific. Refer to `@ai-mapping.md` for the exact shape per AI tool.