docs(issue-222): integrate skills review simplification plan

CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## v2.3.8 - 2026-03-04
+
+### Added
+
+- Final outcomes artifact at `docs/plans/skills-review-final-outcomes.md` with auditable keep/remove decisions and explicit migration mapping
+  for removed entrypoints.
+
+### Changed
+
+- Repo-level docs were aligned to the finalized skill/check surface, including canonical `scripts/check.sh` gates and entrypoint-drift guards
+  in `PROJECT_DEV_WORKFLOW.md`.
+- `README.md` structure notes now reflect current tracked directories and remove stale progress-log wording.
+- `docs/testing/script-smoke.md` plan-issue cleanup example now uses the current `<owner__repo>` workspace slug convention.
+
 ## v2.3.7 - 2026-03-04
 
 ### Added

DEVELOPMENT.md

@@ -72,6 +72,9 @@ Notes:
 - `scripts/check-pre-commit.sh` always includes skill entrypoint checks to avoid conditional misses.
 - If you run only the canonical minimum gate (`scripts/check.sh --all`), remember that `stale-skill-scripts-audit` and
   `--entrypoint-ownership` are still required whenever skill entrypoint scripts are added/removed.
+- When workflow/tool entrypoint scripts change, update the matching
+  `tests/script_specs/skills/**/scripts/*.json` smoke specs in the same PR to
+  keep spec coverage aligned with retained entrypoints.
 
 ## CI Notes
 

README.md

@@ -10,10 +10,10 @@ agent-kit tracks AI agent setup to keep workflows consistent across machines. It
 .
 ├── .github/    # CI workflows (GitHub Actions)
 ├── prompts/    # prompt presets
-├── skills/     # skills (tools/, workflows/, automation/, .system/, _shared/, _projects/, openai/)
+├── skills/     # skills (tools/, workflows/, automation/, .system/, _shared/, _projects/)
 ├── scripts/    # loader + helper scripts
 ├── docker/     # Docker images + env tooling
-├── docs/       # docs, templates, progress logs
+├── docs/       # runbooks, plans, and testing docs
 ├── tests/      # pytest regression/smoke tests
 └── AGENTS.md   # global agent rules (response/tooling)
 ```
@@ -94,7 +94,7 @@ Core skills are grouped under [skills/workflows/](skills/workflows), [skills/too
 | Planning     | [docs-plan-cleanup](./skills/workflows/plan/docs-plan-cleanup/)                                     | Prune outdated docs/plans markdown with dry-run-first safeguards and related-doc reconciliation                                           |
 | Planning     | [execute-plan-parallel](./skills/workflows/plan/execute-plan-parallel/)                             | Execute a markdown plan by spawning parallel subagents for unblocked tasks, then validate                                                 |
 | Issue        | [issue-lifecycle](./skills/workflows/issue/issue-lifecycle/)                                        | Main-agent workflow for opening, maintaining, decomposing, and closing GitHub Issues as the planning source of truth                      |
-| Issue        | [issue-subagent-pr](./skills/workflows/issue/issue-subagent-pr/)                                    | Subagent workflow for isolated worktree implementation, draft PR creation, and review-response updates linked to the owning issue         |
+| Issue        | [issue-subagent-pr](./skills/workflows/issue/issue-subagent-pr/)                                    | Subagent workflow for assigned task-lane implementation (pr-shared/per-sprint/pr-isolated), draft PR creation, and review-response updates linked to the owning issue |
 | Issue        | [issue-pr-review](./skills/workflows/issue/issue-pr-review/)                                        | Main-agent PR review workflow with explicit PR comment links mirrored to the issue timeline                                               |
 | PR / Feature | [create-feature-pr](./skills/workflows/pr/feature/create-feature-pr/)                               | Create feature branches and open a PR with a standard template                                                                            |
 | PR / Feature | [close-feature-pr](./skills/workflows/pr/feature/close-feature-pr/)                                 | Merge and close PRs after a quick PR hygiene review; delete the feature branch                                                            |
@@ -142,6 +142,12 @@ Core skills are grouped under [skills/workflows/](skills/workflows), [skills/too
 | Maintenance | [semgrep-find-and-fix](./skills/automation/semgrep-find-and-fix/)           | Scan a repo using its local Semgrep config, triage findings, and open a fix PR or report-only PR                                                                                           |
 | Release     | [release-workflow](./skills/automation/release-workflow/)                   | Execute project release workflows by following a repo release guide (with a bundled fallback)                                                                                              |
 
+Automation migration note:
+deprecated release-workflow helpers from PR #221 were removed; replace old commands with:
+`$AGENT_HOME/skills/automation/release-workflow/scripts/release-resolve.sh --repo .`
+and
+`$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>`.
+
 ## ✅ Local and CI Check Entrypoints
 
 Use `scripts/check.sh` as the canonical local check entrypoint:
@@ -156,6 +162,8 @@ Common focused runs:
 scripts/check.sh --docs
 scripts/check.sh --markdown
 scripts/check.sh --tests -- -m script_smoke
+bash scripts/ci/stale-skill-scripts-audit.sh --check
+scripts/check.sh --entrypoint-ownership
 ```
 
 Lint CI (`.github/workflows/lint.yml`) maps its phases to `scripts/check.sh` modes. Keep docs and CI guidance aligned with these modes

docs/plans/pr-221-reference-notes.md

@@ -0,0 +1,61 @@
+# PR #221 Reference Notes
+
+## Reference
+
+- PR: `#221`
+- Title: `Simplify release-workflow to a single publish entrypoint`
+- URL: `https://github.com/graysurf/agent-kit/pull/221`
+- Merge commit: `7a9ccb19f71c58bb2439a2534ac7353ea24b5a62`
+- Head branch: `feat/release-workflow-single-entrypoint`
+- Base branch: `main`
+
+## What Changed
+
+PR #221 used `release-workflow` as the reference simplification lane for turning
+a multi-script skill into a smaller public surface.
+The resulting public interface kept `release-resolve.sh` for guide resolution
+and made `release-publish-from-changelog.sh` the single publish entrypoint.
+Legacy single-purpose release scripts and their dependent smoke fixtures were removed in the same change.
+
+## Concrete Change Record
+
+| Field | Result in PR #221 |
+| --- | --- |
+| `old entrypoint` | `audit-changelog.zsh`, `release-audit.sh`, `release-find-guide.sh`, `release-notes-from-changelog.sh`, `release-scaffold-entry.sh` |
+| `decision` | `merge` helper behavior into `release-publish-from-changelog.sh` where needed; otherwise `remove` |
+| `new entrypoint` | `skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` |
+| `test/spec updates` | updated `skills/automation/release-workflow/tests/test_automation_release_workflow.py`, updated `tests/test_script_smoke_release_workflow.py`, removed stale smoke specs for retired scripts, added spec for the kept publish entrypoint |
+| `migration note` | callers invoking removed release scripts must migrate to `release-publish-from-changelog.sh`; guide resolution remains on `release-resolve.sh` |
+
+## Signals To Reuse
+
+- Prefer one primary public command per skill when the workflow can stay coherent.
+- Remove helper scripts only when their behavior is absorbed or no longer needed.
+- Delete stale smoke specs and fixtures in the same change that removes the corresponding script.
+- Update the `SKILL.md` contract, fallback guide, and tests in the same PR as the script change.
+- Include an explicit migration note when callers may still be using the retired command path.
+
+## Validation Evidence Carried By PR #221
+
+- `scripts/check.sh --all`
+- `scripts/test.sh skills/automation/release-workflow/tests/test_automation_release_workflow.py`
+- `scripts/test.sh tests/test_script_smoke_release_workflow.py`
+- `scripts/test.sh tests/test_script_smoke.py -k release-workflow`
+
+## Files Changed In The Reference PR
+
+- `skills/automation/release-workflow/SKILL.md`
+- `skills/automation/release-workflow/references/DEFAULT_RELEASE_GUIDE.md`
+- `skills/automation/release-workflow/scripts/audit-changelog.zsh`
+- `skills/automation/release-workflow/scripts/release-audit.sh`
+- `skills/automation/release-workflow/scripts/release-find-guide.sh`
+- `skills/automation/release-workflow/scripts/release-notes-from-changelog.sh`
+- `skills/automation/release-workflow/scripts/release-publish-from-changelog.sh`
+- `skills/automation/release-workflow/scripts/release-scaffold-entry.sh`
+- `skills/automation/release-workflow/tests/test_automation_release_workflow.py`
+- `tests/fixtures/release-workflow/project-root-guide/RELEASE_GUIDE.md`
+- `tests/script_specs/skills/automation/release-workflow/scripts/audit-changelog.zsh.json`
+- `tests/script_specs/skills/automation/release-workflow/scripts/release-find-guide.sh.json`
+- `tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json`
+- `tests/script_specs/skills/automation/release-workflow/scripts/release-scaffold-entry.sh.json`
+- `tests/test_script_smoke_release_workflow.py`

docs/plans/skills-coverage-matrix.md

@@ -0,0 +1,46 @@
+| Skill Path | Primary Remediation Task | Simplification Task | Docs/Final-State Tasks |
+| --- | --- | --- | --- |
+| `skills/automation/find-and-fix-bugs/SKILL.md` | Task 3.1 | Task 3.2 | Task 3.4, Task 4.1, Task 4.2 |
+| `skills/automation/fix-bug-pr/SKILL.md` | Task 3.1 | Task 3.2 | Task 3.4, Task 4.1, Task 4.2 |
+| `skills/automation/gh-fix-ci/SKILL.md` | Task 3.1 | Task 3.2 | Task 3.4, Task 4.1, Task 4.2 |
+| `skills/automation/issue-delivery/SKILL.md` | Task 3.1 | Task 3.2 | Task 3.4, Task 4.1, Task 4.2 |
+| `skills/automation/plan-issue-delivery/SKILL.md` | Task 3.1 | Task 3.2 | Task 3.4, Task 4.1, Task 4.2 |
+| `skills/automation/release-workflow/SKILL.md` | Task 3.1 | Task 3.2 | Task 3.4, Task 4.1, Task 4.2 |
+| `skills/automation/semantic-commit-autostage/SKILL.md` | Task 3.1 | Task 3.2 | Task 3.4, Task 4.1, Task 4.2 |
+| `skills/automation/semgrep-find-and-fix/SKILL.md` | Task 3.1 | Task 3.2 | Task 3.4, Task 4.1, Task 4.2 |
+| `skills/tools/agent-doc-init/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/browser/agent-browser/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/browser/chrome-devtools-debug-companion/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/browser/playwright/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/devex/desktop-notify/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/devex/open-changed-files-review/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/devex/semantic-commit/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/macos-agent-ops/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/media/image-processing/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/media/screen-record/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/media/screenshot/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/skill-management/create-project-skill/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/skill-management/create-skill/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/skill-management/remove-skill/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/skill-management/skill-governance/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/sql/sql-mssql/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/sql/sql-mysql/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/sql/sql-postgres/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/testing/api-test-runner/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/testing/graphql-api-testing/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/tools/testing/rest-api-testing/SKILL.md` | Task 2.3 | Task 2.4 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/conversation/ask-questions-if-underspecified/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/coordination/delegate-parallel/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/issue/issue-lifecycle/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/issue/issue-pr-review/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/issue/issue-subagent-pr/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/plan/create-plan-rigorous/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/plan/create-plan/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/plan/docs-plan-cleanup/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/plan/execute-plan-parallel/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/pr/bug/close-bug-pr/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/pr/bug/create-bug-pr/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/pr/bug/deliver-bug-pr/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/pr/feature/close-feature-pr/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/pr/feature/create-feature-pr/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |
+| `skills/workflows/pr/feature/deliver-feature-pr/SKILL.md` | Task 2.1 | Task 2.2 | Task 2.5, Task 4.1, Task 4.2 |