chore(deps-dev): bump @commitlint/cli from 21.0.2 to 21.2.0

.github/workflows/codeql.yml

@@ -31,15 +31,15 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
         with:
           languages: ${{ matrix.language }}
           queries: security-and-quality
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/autobuild@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/analyze@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
         with:
           category: "/language:${{ matrix.language }}"

aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-1.md

@@ -0,0 +1,84 @@
+---
+status: done
+---
+
+# Instruction: Remove per-skill READMEs and fix every reference
+
+## Architecture projection
+
+> ✅ create · ✏️ modify · ❌ delete
+
+```txt
+.
+├── plugins/
+│   ├── aidd-context/
+│   │   ├── README.md                         ✏️ retarget 13 skill-table links -> SKILL.md
+│   │   ├── CATALOG.md                         ✏️ regenerate (auto)
+│   │   └── skills/*/README.md                 ❌ delete 13 (NOT assets/**/README.md)
+│   ├── aidd-dev/
+│   │   ├── README.md                         ✏️ retarget 11 skill-table links -> SKILL.md
+│   │   ├── CATALOG.md                         ✏️ regenerate (auto)
+│   │   └── skills/*/README.md                 ❌ delete 11
+│   ├── aidd-orchestrator/{README,CATALOG}.md  ✏️ retarget / regenerate
+│   │   └── skills/00-async-dev/README.md      ❌ delete 1
+│   ├── aidd-pm/{README,CATALOG}.md            ✏️ retarget / regenerate
+│   │   └── skills/*/README.md                 ❌ delete 4
+│   ├── aidd-refine/{README,CATALOG}.md        ✏️ retarget / regenerate
+│   │   └── skills/*/README.md                 ❌ delete 5
+│   ├── aidd-ui/{README,CATALOG}.md            ✏️ retarget / regenerate
+│   │   └── skills/01-hello/README.md          ❌ delete 1
+│   └── aidd-vcs/{README,CATALOG}.md           ✏️ retarget / regenerate
+│       └── skills/*/README.md                 ❌ delete 4
+└── docs/CREATE_PLUGIN.md                       ✏️ drop per-skill README from structure + section, retarget links
+```
+
+Do NOT touch: `plugins/*/README.md` as skills (plugin-level, kept), the top-level framework `README.md`, or asset READMEs (`plugins/aidd-context/skills/02-project-memory/assets/README.md`, `.../assets/templates/memory/README.md`).
+
+## Tasks to do
+
+### `1)` Spot-check the 7 outlier READMEs before deleting
+
+> 7 READMEs lack the breadcrumb header, so they may carry prose their SKILL.md does not. Merge unique content, then delete. Do not blind-delete these.
+
+Outliers: `aidd-context/skills/{00-onboard,09-mermaid,10-learn,11-explore,12-cook}`, `aidd-ui/skills/01-hello`, `aidd-vcs/skills/00-repo-init`.
+
+1. Diff each README against its sibling SKILL.md.
+2. If the README holds substantive info absent from SKILL.md (e.g. `01-hello` documents an install prerequisite / `claude --plugin-dir` invocation), fold the essential line into the SKILL.md, matching that file's terse style.
+3. Pure mirrors (heading + when-to/not-to that the SKILL description already states): nothing to merge.
+
+### `2)` Delete the 39 per-skill READMEs
+
+> Direct children of a skill directory only.
+
+1. Remove every file matching `plugins/*/skills/*/README.md`.
+2. Leave the two asset READMEs and all plugin-level / framework READMEs in place.
+
+### `3)` Retarget the plugin-level README skill tables
+
+> Each of the 7 `plugins/<plugin>/README.md` has a Skills table linking `skills/<x>/README.md`. Point them at `SKILL.md`.
+
+1. In every `plugins/*/README.md`, replace `skills/<skill>/README.md` link targets with `skills/<skill>/SKILL.md`. Link text and table rows stay unchanged.
+
+### `4)` Update `docs/CREATE_PLUGIN.md`
+
+> The doc prescribes a per-skill README; drop that so the convention does not reintroduce them.
+
+1. Remove the per-skill `README.md` entry from the structure diagram (keep the plugin-level `README.md` entry).
+2. Remove or rewrite the `### skills/01-hello/README.md` section so it no longer instructs authors to ship a per-skill README; keep the plugin-level README guidance.
+3. Retarget any `skills/<x>/README.md` link in the doc to `SKILL.md`.
+
+### `5)` Regenerate the CATALOGs
+
+> `CATALOG.md` is auto-generated; do not hand-edit. Regenerate so the README rows drop out.
+
+1. For each plugin run `node scripts/summarize-markdown.js "plugins/<name>/" "plugins/<name>/CATALOG.md" --depth=4 --fields=description --title="<name> catalog" --tagline="Auto-generated index of skills, agents, references and assets shipped by the \`<name>\` plugin."` (identical to the `lefthook.yml` block), or let the pre-commit hook run it.
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria                                                                                          |
+| ---- | ----------------------------------------------------------------------------------------------------------- |
+| 1    | Each outlier's unique content is either merged into its SKILL.md or confirmed to be a pure mirror.          |
+| 2    | `find plugins -path '*/skills/*/README.md'` returns zero results; both asset READMEs still exist.           |
+| 3    | No `plugins/*/README.md` skill table links to a `skills/*/README.md`; all point to `SKILL.md`.              |
+| 4    | `docs/CREATE_PLUGIN.md` no longer prescribes a per-skill README and links to no removed file.               |
+| 5    | Regenerated `CATALOG.md` files list no `skills/*/README.md` row.                                            |

aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/phase-2.md

@@ -0,0 +1,47 @@
+---
+status: done
+---
+
+# Instruction: Verify and guard
+
+## Architecture projection
+
+> No file changes; this phase runs the gates that prove the QA holds.
+
+```txt
+.
+└── (verification only — scripts/check-markdown-links.js, sync scripts)
+```
+
+## Tasks to do
+
+### `1)` Broken-link gate (the QA#3 proof)
+
+> Every markdown link that resolved to a now-deleted README must be gone.
+
+1. Run `node scripts/check-markdown-links.js` from the repo root. It resolves relative links across all markdown; a dangling link to a removed README fails it.
+2. Fix any residual dangling reference it reports (retarget to `SKILL.md` or drop), then re-run until clean.
+
+### `2)` No per-skill README, no orphan skill
+
+1. `find plugins -path '*/skills/*/README.md'` returns nothing.
+2. Every skill directory that lost its README still has a `SKILL.md` (no orphaned skill dir).
+3. The two asset READMEs and all plugin-level / framework READMEs remain.
+
+### `3)` Generated artifacts consistent
+
+1. `node scripts/sync-readme-counts.mjs --check` exits 0 (top-level counts unaffected).
+2. Regenerated CATALOGs contain no `skills/*/README.md` rows.
+
+### `4)` Durability
+
+1. Confirm `aidd-context/04-skill-generate` does not scaffold a per-skill README (a newly generated skill would not reintroduce one).
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria                                                                     |
+| ---- | -------------------------------------------------------------------------------------- |
+| 1    | `node scripts/check-markdown-links.js` exits 0 with no dangling README link reported.  |
+| 2    | Zero `skills/*/README.md`; every affected skill dir still has `SKILL.md`; asset READMEs intact. |
+| 3    | `sync-readme-counts.mjs --check` exits 0; no CATALOG lists a per-skill README.          |
+| 4    | The skill generator emits no per-skill README.                                          |

aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/plan.md

@@ -0,0 +1,38 @@
+---
+objective: "Every per-skill README.md that mirrors its SKILL.md is gone, and no link, doc, or generator points at a removed file."
+status: reviewed
+---
+
+# Plan: Remove per-skill README.md
+
+## Overview
+
+| Field      | Value                                                                 |
+| ---------- | --------------------------------------------------------------------- |
+| **Goal**   | Delete the 39 per-skill `README.md` mirrors; keep navigation intact.  |
+| **Source** | GitHub issue #302 (ai-driven-dev/framework)                           |
+
+## Phases
+
+| #   | Phase                        | File                         |
+| --- | ---------------------------- | ---------------------------- |
+| 1   | Remove READMEs, fix all refs | [`phase-1.md`](./phase-1.md) |
+| 2   | Verify and guard             | [`phase-2.md`](./phase-2.md) |
+
+## Resources
+
+| Source                                              | Verified                                                                                   |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| GitHub issue #302                                   | Objective + QA acceptance criteria; symlink is optional and droppable.                      |
+| `lefthook.yml`                                      | Pre-commit runs `check-markdown-links.js` (link gate), regenerates every `CATALOG.md`, and syncs `README.md` counts. |
+| `scripts/summarize-markdown.js`                     | `CATALOG.md` is fully auto-generated from the file tree; deleted READMEs vanish on regen.   |
+| `scripts/sync-readme-counts.mjs`                    | Counts skills by directory, README-independent; only touches the top-level `README.md`.     |
+| `plugins/aidd-context/skills/04-skill-generate/*`   | Does not scaffold a per-skill README; removal is durable for future skills.                 |
+
+## Decisions
+
+| Decision                                            | Why                                                                                                                            |
+| --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| Delete the READMEs, do not symlink to SKILL.md      | Plugin ships cross-OS (symlink fragile); a symlink would render SKILL.md's raw YAML frontmatter on GitHub; issue accepts clean removal. |
+| Retarget plugin-README skill-table links to SKILL.md | Preserves folder navigation after the README is gone; these tables are hand-written, not generated.                          |
+| Regenerate CATALOG.md, never hand-edit it           | `CATALOG.md` is auto-generated; hand edits are overwritten by the pre-commit hook.                                            |

aidd_docs/tasks/2026_07/2026_07_06_remove-per-skill-readme/review.md

@@ -0,0 +1,39 @@
+# Review: Remove per-skill README.md
+
+- **Verdict**: approve
+- **Diff**: `484928c...9b327eb`
+- **Axes run**: code, functional, relevancy
+- **Date**: 2026_07_06
+- **Findings**: 0 critical, 0 warning, 1 minor
+
+## Phases
+
+### Phase 1 — Remove READMEs, fix all refs
+
+- [x] Task 1: each outlier's unique content merged into SKILL.md or confirmed a pure mirror — 00-onboard/SKILL.md:36 (Requires folded), 01-hello/SKILL.md:19-21 (prereq folded), 00-repo-init/SKILL.md:9,30-33 (status + prereq folded); 09-mermaid/10-learn/11-explore/12-cook confirmed pure mirrors (prereq already in SKILL.md)
+- [x] Task 2: no direct-child `skills/*/README.md` remains; both asset READMEs present — direct-child loop returns nothing; `plugins/aidd-context/skills/02-project-memory/assets/README.md` + `.../assets/templates/memory/README.md` intact
+- [x] Task 3: no `plugins/*/README.md` skill table links to `skills/*/README.md`; all point to SKILL.md — grep of `plugins/*/README.md` returns none; aidd-orchestrator/README.md:19,21 retargeted
+- [x] Task 4: `docs/CREATE_PLUGIN.md` no longer prescribes a per-skill README, links to no removed file — docs/CREATE_PLUGIN.md:41,94 (structure line + section removed)
+- [x] Task 5: regenerated CATALOG.md files list no `skills/*/README.md` row — grep returns only the retained asset README row (aidd-context/CATALOG.md:81), not a per-skill mirror
+
+### Phase 2 — Verify and guard
+
+- [x] Task 1: `node scripts/check-markdown-links.js` exits 0, no dangling README link — "Links: 0 broken in 364 files", exit 0
+- [x] Task 2: zero direct-child `skills/*/README.md`; every affected skill dir keeps SKILL.md; asset READMEs intact — orphan loop returns nothing; asset READMEs present
+- [x] Task 3: `sync-readme-counts.mjs --check` exits 0; no CATALOG lists a per-skill README — exit 0; CATALOG regen produced zero drift (proves generated, not hand-edited)
+- [x] Task 4: skill generator emits no per-skill README — `grep -rniE readme plugins/aidd-context/skills/04-skill-generate/` returns nothing; templates scaffold SKILL.md + actions only
+
+## Findings
+
+| Sev | Kind | Phase | Location | Issue | Fix |
+| --- | ---- | ----- | -------- | ----- | --- |
+| 🟢 | rot | 1 | plugins/aidd-context/skills/09-mermaid/SKILL.md | Deleted README's `## Requires` elaborated the input as "a paragraph, a list, or a section"; SKILL.md keeps the essential "written source" (description + Actions input) but drops that parenthetical granularity. Judged a pure mirror; noted for completeness. | Optional: none required — essential prerequisite is preserved. |
+
+## Verification
+
+| Metric        | Value                                             |
+| ------------- | ------------------------------------------------- |
+| Verified      | 100% (9/9)                                         |
+| Files checked | 39 deleted skill READMEs, 7 plugin READMEs, 7 CATALOG.md, 3 SKILL.md merges (00-onboard, 01-hello, 00-repo-init), docs/CREATE_PLUGIN.md, plugins/aidd-context/skills/04-skill-generate/* |
+| Unchecked     | none |
+| Unplanned     | none (60 files = 39 deletions + 3 plan docs added + 18 modified; exactly scoped, no creep) |

docs/CREATE_PLUGIN.md

@@ -41,7 +41,6 @@ plugins/aidd-example/
 ├── skills/
 │   └── 01-hello/
 │       ├── SKILL.md
-│       ├── README.md
 │       └── actions/
 │           └── 01-greet.md
 ├── agents/               # optional
@@ -95,10 +94,6 @@ description: One-sentence summary. Use when ... Do NOT use for ...
 Run action `01-greet` and return its message.
 ```
 
-### `skills/01-hello/README.md`
-
-Mirror the sibling pattern: title, paragraph, When to use, When NOT to use, How to invoke, Outputs, Prerequisites, Technical details (link to SKILL.md). ~30-50 lines.
-
 ### `skills/01-hello/actions/01-greet.md`
 
 ```markdown

package.json

@@ -31,11 +31,11 @@
     "prepare": "lefthook install || true"
   },
   "devDependencies": {
-    "@commitlint/cli": "^21.0.2",
+    "@commitlint/cli": "^21.2.0",
     "@commitlint/config-conventional": "^21.0.2",
     "ajv": "8.20.0",
     "ajv-formats": "3.0.1",
-    "js-yaml": "5.0.0",
+    "js-yaml": "5.2.1",
     "lefthook": "^2.1.9"
   }
 }