Docs: the layout trees, the tag facts, and two pointers the release procedure left behind

[mmcky]

#28 rewrote how releases work without updating either picture of what a plugin contains. This is the catch-up — nothing here ships, which is why it is separate from the plugin-status PR.

Both layout trees were wrong in the same way

README.md § Layout and docs/developing-skills.md § Repo layout both still showed a plugin as manifest + skills + scripts + references, with no CHANGELOG.md — while CI now fails any PR that omits one. They are fixed together on purpose: leaving one right and one wrong is worse than both being stale, because a contributor cannot tell which to trust. scripts/validate.py becomes scripts/ in both, since it is no longer the only thing in there.

"Only SKILL.md is required." was true when written and is not now — the manifest and the changelog are both required. It now says so, rather than being quietly contradicted by the CI guard three sections further down.

§ Tags — creating the tags falsified it

It opened "The repo has no git tags today". Three now exist (qe--v0.2.1, benchmark--v0.3.1, audit--v0.1.4), so the section documents the scheme as adopted, with the command and what it refuses.

It also records why only current versions were tagged, because that decision will otherwise look like an oversight. Several historical versions cannot be tagged honestly: some name two different published trees — content shipped twice under one version, before the guard existed — and others sit at commits that fail today's validation. Each CHANGELOG.md already carries that ambiguity in prose with PR numbers, which is more than a tag can carry.

Two stale pointers

• developing-skills said issue PLAN: benchmark — from v0 outline to operational /benchmark:review-acceleration #4 "tracks the ${CLAUDE_PLUGIN_ROOT} pattern". It shipped, and has a worked example — now pointed at instead.
• "which is the existing precedent", about the catalogue version, claimed a consistency the history does not have: adding qe did not move it, adding audit did. The rule stands, so it is now stated rather than inferred from a precedent that contradicts itself.

Two smaller ones

The audit tutorial was the only guide missing from README's documentation table while being present in AGENTS.md's doc map. And the tutorial's Step 7 gave one hardcoded filename as if it were the instruction; it now reads as the convention, with run 1's file as the example.

No version bumps — README.md and docs/ ship to nobody. The guard agrees: no plugin directory touched. Links resolve and validate.py passes.

[Copilot]

Pull request overview

Updates repository documentation to match the post-#28 release/versioning model, correcting stale layout diagrams, tag guidance, and a couple of outdated pointers so contributor-facing docs reflect current CI/enforcement behavior.

Changes:

• Fixes the repo/plugin layout trees in README.md and docs/developing-skills.md to include required CHANGELOG.md files and reflect scripts/ as a directory.
• Updates docs/developing-skills.md “Tags” guidance to document the adopted {name}--v{version} scheme and the rationale for tagging only current versions.
• Clarifies the audit tutorial’s run-record filename as a convention with a concrete example link.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
README.md	Updates documentation index and repo layout tree to reflect current required plugin contents and scripts/ usage.
docs/tutorial-run-an-audit.md	Updates Step 7 to describe the run-record filename convention and link to the first run as an example.
docs/developing-skills.md	Updates repo layout guidance, self-contained plugin pointer, catalogue-version note, and tag scheme documentation to align with current release procedure.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.