fix(framework): point skill README symlinks to SKILL.md

aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-1.md

@@ -0,0 +1,76 @@
+---
+status: done
+---
+
+# Instruction: Convert Existing Skill READMEs
+
+Part of [`plan.md`](./plan.md).
+
+## Architecture projection
+
+```txt
+plugins/
+  aidd-*/
+    README.md
+    skills/
+      <skill>/
+        README.md -> SKILL.md
+        SKILL.md
+        actions/
+        references/
+        assets/
+          README.md          # unchanged when present
+```
+
+## Tasks to do
+
+### `1)` Inventory direct skill README files
+
+> Build the exact direct-skill README target list without accidentally including nested asset/template READMEs.
+
+1. Use a filesystem-depth scan for `plugins/<plugin>/skills/<skill>/README.md`.
+2. Confirm each owning `plugins/<plugin>/README.md` exists.
+3. Record any direct skill README that is already a symlink and preserve it if it resolves correctly.
+
+### `2)` Replace direct README files with symlinks
+
+> Convert every direct skill README landing page into the local SKILL.md symlink convention.
+
+1. For every direct regular file at `plugins/<plugin>/skills/<skill>/README.md`, remove the file and create a symlink named `README.md` targeting `SKILL.md`.
+2. Do not touch deeper README files under `assets/`, `references/`, templates, or generated-project templates.
+3. Ensure Git records the symlink mode change rather than a copied README file.
+
+### `3)` Refresh generated catalogs if required
+
+> Bring catalog output into sync with the converted tree.
+
+1. Run the plugin catalog generation command used by `lefthook`.
+2. Review catalog diffs for expected changes only.
+3. If catalogs still list direct skill README entries as ordinary files, leave that for Phase 3 validation/catalog handling.
+
+## Acceptance criteria
+
+| Task | Acceptance criteria |
+| --- | --- |
+| 1 | The direct target list includes only paths exactly shaped as `plugins/<plugin>/skills/<skill>/README.md`; nested asset/template READMEs are excluded. |
+| 2 | Each direct skill `README.md` is a symlink whose `readlink` target is `SKILL.md`, and `realpath` resolves to the local `SKILL.md`. |
+| 2 | `git status --short` shows mode/content changes for direct skill README paths only, with no accidental deletion of nested asset README files. |
+| 3 | Regenerated catalogs are either unchanged or changed only in ways explained by symlink handling. |
+
+## Validation commands
+
+```sh
+find plugins -mindepth 4 -maxdepth 4 -path 'plugins/*/skills/*/README.md' -print | sort
+find plugins -mindepth 5 -path 'plugins/*/skills/*/README.md' -print | sort
+while IFS= read -r f; do expected="$(cd "$(dirname "$f")" && pwd -P)/SKILL.md"; test -L "$f" || { echo "not symlink: $f"; exit 1; }; target="$(readlink "$f")"; test "$target" = "SKILL.md" || { echo "bad target: $f -> $target"; exit 1; }; actual="$(cd "$(dirname "$f")" && realpath "$target")"; test "$actual" = "$expected" || { echo "bad resolution: $f -> $actual, expected $expected"; exit 1; }; done < <(find plugins -mindepth 4 -maxdepth 4 -path 'plugins/*/skills/*/README.md' -print | sort)
+find plugins -mindepth 5 -path 'plugins/*/skills/*/README.md' -type f -print | sort
+for plugin in plugins/*/; do name=$(basename "$plugin"); node scripts/summarize-markdown.js "$plugin" "${plugin}CATALOG.md" --depth=4 --fields=description,argument-hint --title="$name catalog" --tagline="Auto-generated index of skills, agents, references and assets shipped by the \`$name\` plugin." >/dev/null; done
+```
+
+## Dependencies
+
+- None.
+
+## Expected commit boundary
+
+Commit after every direct per-skill README has been converted to a symlink and any immediately required catalog refresh is complete.

aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-2.md

@@ -0,0 +1,80 @@
+---
+status: done
+---
+
+# Instruction: Update Generation And Documentation Assumptions
+
+Part of [`plan.md`](./plan.md).
+
+## Architecture projection
+
+```txt
+plugins/aidd-context/skills/04-skill-generate/
+  SKILL.md
+  actions/
+    01-capture-intent.md
+    03-draft-skill.md
+    05-validate.md
+  references/
+    skill-authoring.md
+    tool-paths.md
+  assets/
+    skill-template.md
+
+plugins/<plugin>/skills/<generated-skill>/
+  README.md -> SKILL.md     # plugin-source mode only
+  SKILL.md
+  actions/
+```
+
+## Tasks to do
+
+### `1)` Update skill-generation write behavior
+
+> Make plugin-source skill generation create or preserve the symlink convention without writing substantive per-skill README prose.
+
+1. Update `plugins/aidd-context/skills/04-skill-generate/actions/03-draft-skill.md` so plugin-source rendering writes `SKILL.md` and ensures `README.md -> SKILL.md`.
+2. Keep host-project skill generation focused on the target tool's `SKILL.md`; do not require a README.
+3. In modify mode, preserve a correct symlink, replace only a direct regular per-skill README in plugin-source mode, and avoid touching nested README templates.
+
+### `2)` Update capture, authoring, and seed guidance
+
+> Remove stale assumptions that a new skill needs dedicated README prose.
+
+1. Update skill-generate capture/reference wording if it asks for or implies substantive per-skill README content.
+2. Add seed guidance in `03-draft-skill.md` or the relevant reference so new plugin-source skills create `README.md` as a symlink to `SKILL.md` immediately after `SKILL.md` is written.
+3. Keep asset README references in unrelated skills intact when they describe generated project docs or templates.
+
+### `3)` Update plugin/docs references that describe per-skill READMEs as content surfaces
+
+> Align documentation with `SKILL.md` as the canonical skill file.
+
+1. Search `plugins/`, `scripts/`, `aidd_docs/`, and root docs for wording like `skill README`, `per-skill README`, or links that imply unique per-skill content.
+2. Rewrite stale prose to reference `SKILL.md`, catalog entries, or the symlink convention.
+3. Leave historical changelog entries unchanged unless they are part of generated current docs.
+
+## Acceptance criteria
+
+| Task | Acceptance criteria |
+| --- | --- |
+| 1 | Plugin-source skill generation instructions explicitly ensure `README.md -> SKILL.md` and do not ask the user for README prose. |
+| 1 | Host-project skill generation instructions do not create or require README files. |
+| 2 | Creation guidance explicitly seeds the plugin-source skill README symlink before the action reports files written. |
+| 2 | References to asset README templates remain intact where they are not direct skill landing pages. |
+| 3 | Current docs no longer claim direct skill READMEs contain distinct per-skill documentation. |
+
+## Validation commands
+
+```sh
+rg -n "skill README|per-skill README|substantive per-skill|skills/.*/README.md" plugins scripts aidd_docs README.md -g '!**/CHANGELOG.md'
+rg -n "README" plugins/aidd-context/skills/04-skill-generate
+pnpm exec lefthook run pre-commit --all-files --force
+```
+
+## Dependencies
+
+- Phase 1 should be complete so docs/generator updates can refer to the actual symlink convention.
+
+## Expected commit boundary
+
+Commit after skill generation instructions and current docs consistently describe the symlink convention.

aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/phase-3.md

@@ -0,0 +1,82 @@
+---
+status: done
+---
+
+# Instruction: Validate Catalogs, Distribution, And Checks
+
+Part of [`plan.md`](./plan.md).
+
+## Architecture projection
+
+```txt
+scripts/
+  summarize-markdown.js        # may need symlink-aware catalog behavior
+  validate-*.mjs
+.github/workflows/
+  validate.yml                 # runs lefthook over all files
+plugins/
+  <plugin>/
+    CATALOG.md                 # generated, deterministic
+    README.md
+    skills/<skill>/README.md -> SKILL.md
+```
+
+## Tasks to do
+
+### `1)` Make cataloging symlink-aware where needed
+
+> Ensure generated catalogs and docs do not misrepresent symlinked skill READMEs as unique source files.
+
+1. Run catalog generation for every plugin and inspect how direct skill README symlinks appear.
+2. If catalog rows are misleading or duplicate `SKILL.md` metadata through the symlink, update `scripts/summarize-markdown.js` to handle symlinked direct skill READMEs deliberately.
+3. Preserve catalog coverage for nested asset/template README files, because those remain substantive files.
+
+### `2)` Confirm generator seeding is the durable guardrail
+
+> Ensure new plugin-source skills seed the README symlink at creation instead of relying on a repository-wide validator.
+
+1. Keep `lefthook.yml` free of a dedicated skill README symlink validator.
+2. Confirm `04-skill-generate` seeds `README.md -> SKILL.md` in plugin-source creation mode.
+3. Confirm modify mode preserves a correct symlink and does not touch nested asset/template README files.
+
+### `3)` Validate repository and build-relevant surfaces
+
+> Prove the change works with the repository's available checks and release packaging assumptions.
+
+1. Run the same local check path CI uses.
+2. Run a one-off symlink assertion across all direct skill README paths for this migration.
+3. If practical in the environment, smoke-test the framework build command used by release packaging for at least one target; otherwise record why it was skipped.
+4. Review `git diff --stat` and `git diff --check`.
+
+## Acceptance criteria
+
+| Task | Acceptance criteria |
+| --- | --- |
+| 1 | `plugins/*/CATALOG.md` files are deterministic after regeneration and do not depend on stale per-skill README contents. |
+| 1 | Nested asset/template README entries still appear when catalog rules include them. |
+| 2 | `04-skill-generate` creation guidance seeds `README.md -> SKILL.md` at creation time. |
+| 2 | No dedicated repository validator script or lefthook command is committed for this convention. |
+| 3 | `pnpm exec lefthook run pre-commit --all-files --force` passes. |
+| 3 | One-off symlink assertion passes for every direct skill README in this migration. |
+| 3 | `git diff --check` passes, and any skipped build smoke test is justified in the implementation notes. |
+
+## Validation commands
+
+```sh
+pnpm exec lefthook run pre-commit --all-files --force
+while IFS= read -r f; do expected="$(cd "$(dirname "$f")" && pwd -P)/SKILL.md"; test -L "$f" || { echo "not symlink: $f"; exit 1; }; target="$(readlink "$f")"; test "$target" = "SKILL.md" || { echo "bad target: $f -> $target"; exit 1; }; actual="$(cd "$(dirname "$f")" && realpath "$target")"; test "$actual" = "$expected" || { echo "bad resolution: $f -> $actual, expected $expected"; exit 1; }; done < <(find plugins -mindepth 4 -maxdepth 4 -path 'plugins/*/skills/*/README.md' -print | sort)
+find plugins -mindepth 4 -maxdepth 4 -path 'plugins/*/skills/*/README.md' -type f -print | grep . && { echo "regular direct skill README remains"; exit 1; } || true
+find plugins -mindepth 5 -path 'plugins/*/skills/*/README.md' -type f -print | sort
+git diff --check
+git diff --stat
+npx --yes @ai-driven-dev/cli@4.6.1 framework build --source . --target codex --out "$(mktemp -d)" --flat
+```
+
+## Dependencies
+
+- Phase 1 must provide the symlinked tree.
+- Phase 2 must update generation/docs assumptions before final validation.
+
+## Expected commit boundary
+
+Commit after validation/catalog handling is complete and all checks have been run or explicitly documented as skipped.

aidd_docs/tasks/2026_06/2026_06_26_remove-skill-readmes/plan.md

@@ -0,0 +1,77 @@
+---
+objective: "Remove substantive per-skill README files and standardize direct skill README.md entries as symlinks to SKILL.md."
+status: reviewed
+---
+
+# Plan: Remove Skill READMEs
+
+## Overview
+
+| Field | Value |
+| --- | --- |
+| **Goal** | Direct skill directories keep `README.md` only as a symlink to local `SKILL.md`, and generators/catalogs/docs stop treating per-skill READMEs as substantive files. |
+| **Source** | Inline SDLC request from 2026-06-26. |
+
+## Scope
+
+Target:
+
+- Replace committed files matching direct skill README paths (`plugins/<plugin>/skills/<skill>/README.md`) with symlinks resolving to the same directory's `SKILL.md`.
+- Update skill generation behavior so plugin-source skill creation creates or preserves the symlink convention without asking for or writing substantive per-skill README content.
+- Update cataloging and docs that assume direct skill READMEs contain unique content.
+- Validate with repository checks plus a one-off migration assertion for the current symlink tree.
+
+Hard constraints:
+
+- Do not edit nested asset/template READMEs such as `plugins/*/skills/*/assets/README.md`; those are not direct per-skill README landing pages.
+- Use a local symlink target of `SKILL.md` for every direct skill README so plugin directories remain relocatable.
+- Keep generated catalogs deterministic and compatible with `pnpm exec lefthook run pre-commit`.
+
+Non-goals:
+
+- Do not remove or rewrite plugin-level `plugins/*/README.md` files except link/reference updates required by the symlink convention.
+- Do not remove asset README templates used by skills to generate project docs.
+- Do not change skill runtime semantics unrelated to README generation and discovery.
+
+Done when:
+
+- Every direct skill README in committed plugin skill directories is a symlink resolving to the same directory's `SKILL.md`.
+- No direct committed skill README remains a regular file.
+- Skill generation no longer asks for or writes standalone per-skill README prose, and plugin-source generation seeds the symlink at creation time.
+- Catalogs/docs reflect the symlink convention and no stale per-skill README assumption remains.
+- Repository checks pass.
+
+## Phases
+
+| # | Phase | File |
+| --- | --- | --- |
+| 1 | Convert Existing Skill READMEs | [`phase-1.md`](./phase-1.md) |
+| 2 | Update Generation And Documentation Assumptions | [`phase-2.md`](./phase-2.md) |
+| 3 | Validate Catalogs, Distribution, And Checks | [`phase-3.md`](./phase-3.md) |
+
+## Resources
+
+| Source | Verified |
+| --- | --- |
+| `plugins/*/skills/*/README.md` direct filesystem scan | There were 37 direct skill README regular files to convert and one direct skill directory missing the symlink. |
+| `plugins/*/skills/*/assets/**/README.md` scan | Nested asset/template READMEs exist and are outside the conversion scope. |
+| `plugins/aidd-context/skills/04-skill-generate/**` | Skill generation writes `SKILL.md` and actions; plugin-source behavior needs explicit README symlink handling and docs. |
+| `scripts/summarize-markdown.js` | Catalog generation currently scans symlink targets via `fs.statSync`; cataloging must account for the symlink convention. |
+| `.github/workflows/validate.yml` | CI runs `pnpm exec lefthook run pre-commit --all-files --force` after install. |
+
+## Decisions
+
+| Decision | Why |
+| --- | --- |
+| Use `SKILL.md` as the symlink target for direct skill READMEs. | The README alias stays local to the skill directory and follows the canonical skill file. |
+| Keep nested asset/template READMEs as regular files. | They are templates or documentation for generated assets, not per-skill landing pages. |
+| Keep plugin README skill-table links pointing at `skills/<skill>/README.md` unless implementation discovers a tool incompatibility. | The path remains valid through the local `SKILL.md` symlink while preserving existing public link shape. |
+| Do not add a dedicated repository validator. | The durable guarantee belongs in skill generation seeding; repository checks should stay focused on existing JSON, YAML, frontmatter, catalogs, and counts. |
+
+## Expected Commit Boundaries
+
+| Commit | Contents |
+| --- | --- |
+| 1 | Convert existing direct skill README files to symlinks and update generated catalogs if needed. |
+| 2 | Update skill generation instructions/templates and any stale docs or catalog assumptions. |
+| 3 | Adjust catalog handling for the symlink convention and refresh generated outputs after checks. |

docs/ARCHITECTURE.md

@@ -63,7 +63,7 @@ plugins/<plugin>/
 ├── skills/                # router-based skills
 │   └── <NN>-<name>/
 │       ├── SKILL.md        # contract (name, description, actions table)
-│       ├── README.md       # human-facing skill landing
+│       ├── README.md       # symlink to SKILL.md
 │       ├── actions/        # atomic actions invoked by the router
 │       ├── assets/         # templates and static files
 │       └── references/     # extended docs the skill links into

docs/CREATE_PLUGIN.md

@@ -41,7 +41,7 @@ plugins/aidd-example/
 ├── skills/
 │   └── 01-hello/
 │       ├── SKILL.md
-│       ├── README.md
+│       ├── README.md -> SKILL.md
 │       └── actions/
 │           └── 01-greet.md
 ├── agents/               # optional
@@ -97,7 +97,13 @@ 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.
+Create this as a local symlink to the skill file:
+
+```sh
+ln -s SKILL.md plugins/aidd-example/skills/01-hello/README.md
+```
+
+Do not write standalone per-skill README prose. Keep execution details in `SKILL.md`, `actions/`, `references/`, and `assets/`.
 
 ### `skills/01-hello/actions/01-greet.md`
 
@@ -166,7 +172,7 @@ Once the PR merges to `main`, `release-please` will propose a release PR for you
 
 - English only in committed prose.
 - No em-dash characters in text (hyphen instead).
-- No cross-plugin references in skill descriptions or READMEs.
+- No cross-plugin references in skill descriptions or plugin README prose.
 - One sentence per `Use when ... / Do NOT use for ...` cue in `description` frontmatter.
 - A skill's `name:` is the **folder slug** (`01-hello`), not a prefixed id. The **invocation** token is `<plugin>:<folder>` with a single colon, e.g. `aidd-example:01-hello`.