From 69a64e1bbb7ce113c0160959cf3a717f1550af65 Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Wed, 4 Mar 2026 05:48:12 +0800 Subject: [PATCH 1/9] docs(skills): add sprint 1 review baseline - Add tracked skill inventory audit for all checked-in skills. - Add repo-wide review checklist and script simplification playbook. - Link the new Sprint 1 references from the affected skill docs. --- docs/plans/pr-221-reference-notes.md | 61 ++++++++++++ docs/plans/skills-inventory-audit.md | 94 +++++++++++++++++++ .../skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md | 76 +++++++++++++++ .../runbooks/skills/SKILL_REVIEW_CHECKLIST.md | 46 +++++++++ skills/README.md | 6 ++ skills/automation/release-workflow/SKILL.md | 7 ++ .../skill-management/create-skill/SKILL.md | 7 ++ .../skill-governance/SKILL.md | 7 ++ .../plan/create-plan-rigorous/SKILL.md | 6 ++ 9 files changed, 310 insertions(+) create mode 100644 docs/plans/pr-221-reference-notes.md create mode 100644 docs/plans/skills-inventory-audit.md create mode 100644 docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md create mode 100644 docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md diff --git a/docs/plans/pr-221-reference-notes.md b/docs/plans/pr-221-reference-notes.md new file mode 100644 index 00000000..10a9097a --- /dev/null +++ b/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` diff --git a/docs/plans/skills-inventory-audit.md b/docs/plans/skills-inventory-audit.md new file mode 100644 index 00000000..440e11b5 --- /dev/null +++ b/docs/plans/skills-inventory-audit.md @@ -0,0 +1,94 @@ +# Skill Inventory Audit + +## Overview + +This audit is the Sprint 1 baseline inventory for every tracked `skills/**/SKILL.md` entry in the repo. +It records the current skill surface before later remediation work changes contracts, scripts, tests, or references. +All counts below are derived from the checked-in repository state on `plan/issue-222` after PR #221 merged. +The inventory includes per-skill entrypoints, tests, script specs, declared dependencies, and resolved docs links. + +## Coverage Summary + +| Domain | Tracked skills | Entrypoint scripts | Script specs present | +| --- | ---: | ---: | ---: | +| `automation` | 8 | 7 | 7 | +| `tools` | 21 | 17 | 13 | +| `workflows` | 15 | 9 | 4 | +| **Total** | **44** | **33** | **24** | + +## Coverage Status Rules + +- `contract`: the skill has per-skill contract coverage through `assert_skill_contract(...)` in its test module. +- `entrypoint`: the skill has explicit entrypoint ownership coverage through `assert_entrypoints_exist(...)`. +- `smoke spec`: every current script in that skill has a matching `tests/script_specs/...json` smoke spec. +- `partial smoke spec (N/M)`: only `N` of `M` current scripts have checked-in smoke specs. +- `tool availability`: the skill has no repo-local entrypoint scripts, but its tests assert external tool resolution. + +## Canonical Inventory + +| Skill Path | Domain | Script Count | Entrypoints | Tests | Script Specs | Dependencies | Docs Links | Test Coverage Status | +| --- | --- | ---: | --- | --- | --- | --- | --- | --- | +| skills/automation/find-and-fix-bugs/SKILL.md | automation | 1 | skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh | skills/automation/find-and-fix-bugs/tests/test_automation_find_and_fix_bugs.py | tests/script_specs/skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh.json | Run inside the target git repo.; `rg` available on `PATH` for codebase scanning.; `git` and `gh` available on `PATH`, and `gh auth status` succeeds. | skills/automation/find-and-fix-bugs/references/ASSISTANT_RESPONSE_TEMPLATE.md; skills/automation/find-and-fix-bugs/references/ISSUES_TEMPLATE.md; skills/automation/find-and-fix-bugs/references/PR_TEMPLATE.md; skills/automation/find-and-fix-bugs/references/REPRO_GUIDE.md | contract + entrypoint + smoke spec | +| skills/automation/fix-bug-pr/SKILL.md | automation | 2 | skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh; skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh | skills/automation/fix-bug-pr/tests/test_automation_fix_bug_pr.py | tests/script_specs/skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh.json; tests/script_specs/skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh.json | Run inside the target git repo.; `git` and `gh` available on `PATH`, and `gh auth status` succeeds.; `python3` available on `PATH` (helper scripts parse/patch PR Markdown deterministically).; Start from a clean working tree (avoid staging unrelated local changes). | skills/automation/fix-bug-pr/references/COMMENT_TEMPLATE.md | contract + entrypoint + smoke spec | +| skills/automation/gh-fix-ci/SKILL.md | automation | 2 | skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh; skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py | skills/automation/gh-fix-ci/tests/test_automation_gh_fix_ci.py | tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json; tests/script_specs/skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py.json | Run inside the target git repo (or pass `--repo`).; `git`, `gh`, and `python3` available on `PATH`.; `semantic-commit` and `git-scope` available on `PATH` (required for commits).; `gh auth status` succeeds for the repo (workflow scope required for logs).; Push access to the target branch (PR branch or specified branch). | none | contract + entrypoint + smoke spec | +| skills/automation/issue-delivery/SKILL.md | automation | 0 | none | skills/automation/issue-delivery/tests/test_automation_issue_delivery.py | none | Run inside (or have access to) the target repository.; `plan-issue` available on `PATH`.; `gh` available on `PATH`, and `gh auth status` succeeds for live issue/PR reads and writes.; `issue-pr-review` is the review decision workflow after handoff. | skills/workflows/issue/_shared/references/TASK_LANE_CONTINUITY.md; skills/workflows/issue/_shared/references/MAIN_AGENT_REVIEW_RUBRIC.md; skills/workflows/issue/_shared/references/POST_REVIEW_OUTCOMES.md; skills/automation/issue-delivery/references/LOCAL_REHEARSAL.md | contract | +| skills/automation/plan-issue-delivery/SKILL.md | automation | 0 | none | skills/automation/plan-issue-delivery/tests/test_automation_plan_issue_delivery.py | none | Run inside (or have access to) the target git repository.; `plan-tooling` available on `PATH` for plan parsing/linting.; `plan-issue` available on `PATH` for live GitHub orchestration mode.; `gh` available on `PATH`, and `gh auth status` succeeds only when using live mode (`plan-issue`). | skills/workflows/issue/_shared/references/TASK_LANE_CONTINUITY.md; skills/workflows/issue/issue-pr-review/references/REVIEW_EVIDENCE_TEMPLATE.md; skills/workflows/issue/_shared/references/MAIN_AGENT_REVIEW_RUBRIC.md; skills/workflows/issue/_shared/references/POST_REVIEW_OUTCOMES.md; skills/automation/plan-issue-delivery/references/LOCAL_REHEARSAL.md; skills/automation/plan-issue-delivery/references/RUNTIME_LAYOUT.md | contract | +| skills/automation/release-workflow/SKILL.md | automation | 2 | skills/automation/release-workflow/scripts/release-publish-from-changelog.sh; skills/automation/release-workflow/scripts/release-resolve.sh | skills/automation/release-workflow/tests/test_automation_release_workflow.py | tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json; tests/script_specs/skills/automation/release-workflow/scripts/release-resolve.sh.json | Run inside (or have access to) the target repo.; `bash` + `zsh` available on `PATH` to run helper scripts.; `git` available on `PATH` (plus any release tooling required by the guide). | docs/plans/pr-221-reference-notes.md; docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md; skills/automation/release-workflow/references/ASSISTANT_RESPONSE_TEMPLATE.md; skills/automation/release-workflow/references/ASSISTANT_RESPONSE_TEMPLATE_BLOCKED.md; skills/automation/release-workflow/references/DEFAULT_RELEASE_GUIDE.md | contract + entrypoint + smoke spec | +| skills/automation/semantic-commit-autostage/SKILL.md | automation | 0 | none | skills/automation/semantic-commit-autostage/tests/test_automation_semantic_commit_autostage.py | none | Run inside a git work tree.; `git` available on `PATH`.; `semantic-commit` available on `PATH` (install via `brew install nils-cli`).; `git-scope` is optional; default summary mode falls back to `git show` when unavailable. | none | contract + tool availability | +| skills/automation/semgrep-find-and-fix/SKILL.md | automation | 0 | none | skills/automation/semgrep-find-and-fix/tests/test_automation_semgrep_find_and_fix.py | none | Run inside the target git repo.; The repo has Semgrep config and local rules checked in (required).; `semgrep` available on `PATH`.; `git` and `gh` available on `PATH`, and `gh auth status` succeeds. | skills/automation/semgrep-find-and-fix/references/PR_TEMPLATE.md; skills/automation/semgrep-find-and-fix/references/REPORT_TEMPLATE.md | contract | +| skills/tools/agent-doc-init/SKILL.md | tools | 1 | skills/tools/agent-doc-init/scripts/agent_doc_init.sh | skills/tools/agent-doc-init/tests/test_tools_agent_doc_init.py | none | `agent-docs` available on `PATH`.; `bash` and `python3` available on `PATH`.; Write permission to target paths only when `--apply` is used. | none | contract + entrypoint | +| skills/tools/browser/agent-browser/SKILL.md | tools | 1 | skills/tools/browser/agent-browser/scripts/agent-browser.sh | skills/tools/browser/agent-browser/tests/test_tools_browser_agent_browser.py | tests/script_specs/skills/tools/browser/agent-browser/scripts/agent-browser.sh.json | `bash` available on `PATH`.; `npx` available on `PATH` (provided by Node.js/npm).; Network access on first package fetch for `agent-browser@latest`. | skills/tools/browser/agent-browser/references/authentication.md; skills/tools/browser/agent-browser/references/commands.md; skills/tools/browser/agent-browser/references/profiling.md; skills/tools/browser/agent-browser/references/proxy-support.md; skills/tools/browser/agent-browser/references/session-management.md; skills/tools/browser/agent-browser/references/snapshot-refs.md; skills/tools/browser/agent-browser/references/video-recording.md | contract + entrypoint + smoke spec | +| skills/tools/browser/chrome-devtools-debug-companion/SKILL.md | tools | 0 | none | skills/tools/browser/chrome-devtools-debug-companion/tests/test_tools_browser_chrome_devtools_debug_companion.py | none | `mcp_servers.chrome-devtools` must be available and connectable.; A reproducible target flow (URL + steps) or existing evidence from Playwright (trace, screenshot, failing step, error message). | none | contract | +| skills/tools/browser/playwright/SKILL.md | tools | 1 | skills/tools/browser/playwright/scripts/playwright_cli.sh | skills/tools/browser/playwright/tests/test_tools_browser_playwright.py | tests/script_specs/skills/tools/browser/playwright/scripts/playwright_cli.sh.json | `bash` available on `PATH`.; `npx` available on `PATH` (provided by Node.js/npm).; Network access on first package fetch for `@playwright/cli@latest`.; Optional: Playwright browser binaries installed for browser-dependent commands. | skills/tools/browser/playwright/references/cli.md; skills/tools/browser/playwright/references/workflows.md | contract + entrypoint + smoke spec | +| skills/tools/devex/desktop-notify/SKILL.md | tools | 2 | skills/tools/devex/desktop-notify/scripts/desktop-notify.sh; skills/tools/devex/desktop-notify/scripts/project-notify.sh | skills/tools/devex/desktop-notify/tests/test_tools_devex_desktop_notify.py | tests/script_specs/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh.json; tests/script_specs/skills/tools/devex/desktop-notify/scripts/project-notify.sh.json | `bash` available on `PATH`.; Notification backend:; macOS: `terminal-notifier`; Linux: `notify-send` | none | contract + entrypoint + smoke spec | +| skills/tools/devex/open-changed-files-review/SKILL.md | tools | 1 | skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh | skills/tools/devex/open-changed-files-review/tests/test_tools_devex_open_changed_files_review.py | tests/script_specs/skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh.json | `zsh` available on `PATH`.; Optional: VSCode CLI `code` (missing → script no-ops).; `$AGENT_HOME/skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh` available. | none | contract + entrypoint + smoke spec | +| skills/tools/devex/semantic-commit/SKILL.md | tools | 0 | none | skills/tools/devex/semantic-commit/tests/test_tools_devex_semantic_commit.py | none | Run inside a git work tree (or pass `--repo ` to target one explicitly).; `git` available on `PATH`.; `semantic-commit` available on `PATH` (install via `brew install nils-cli`).; `git-scope` is optional; default summary mode falls back to `git show` when unavailable. | none | contract + tool availability | +| skills/tools/macos-agent-ops/SKILL.md | tools | 1 | skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh | skills/tools/macos-agent-ops/tests/test_tools_macos_agent_ops.py | none | macOS host with Accessibility and Automation permissions granted for Terminal and target apps.; Homebrew-installed `macos-agent` available on `PATH`.; `cliclick`, `osascript`, and `im-select` available on `PATH`.; `ABC`/`US` input source enabled in macOS Input Sources.; For full AX surface (`ax attr/action/session/watch`), Hammerspoon runtime should be healthy (`hs` + `hs.ipc`). | skills/tools/macos-agent-ops/references/e2e-ref-01-preflight-focus.md; skills/tools/macos-agent-ops/references/e2e-ref-02-finder-routine.md; skills/tools/macos-agent-ops/references/e2e-ref-03-matrix-routine.md | contract + entrypoint | +| skills/tools/media/image-processing/SKILL.md | tools | 0 | none | skills/tools/media/image-processing/tests/test_tools_media_image_processing.py | none | Run inside a git work tree (recommended; enables stable `out/` paths).; `image-processing` available on `PATH` (install via `brew install nils-cli`).; No external image binaries required for standard use. | skills/workflows/conversation/ask-questions-if-underspecified/SKILL.md; skills/tools/media/image-processing/references/ASSISTANT_RESPONSE_TEMPLATE.md; skills/tools/media/image-processing/references/IMAGE_PROCESSING_GUIDE.md | contract + tool availability | +| skills/tools/media/screen-record/SKILL.md | tools | 0 | none | skills/tools/media/screen-record/tests/test_tools_media_screen_record.py | none | `screen-record` available on `PATH` (install via `brew install nils-cli`).; macOS 12+ for native capture (ScreenCaptureKit + AVFoundation).; Linux (X11/Xorg or XWayland) for deterministic selectors/listing; `ffmpeg` required on `PATH`.; Linux Wayland-only sessions can use `--portal` (requires xdg-desktop-portal + backend + PipeWire).; Screen Recording permission granted on macOS (use `screen-record --preflight` / `--request-permission`). | skills/workflows/conversation/ask-questions-if-underspecified/SKILL.md; skills/tools/media/screen-record/references/ASSISTANT_RESPONSE_TEMPLATE.md; skills/tools/media/screen-record/references/SCREEN_RECORD_GUIDE.md | contract + tool availability | +| skills/tools/media/screenshot/SKILL.md | tools | 1 | skills/tools/media/screenshot/scripts/screenshot.sh | skills/tools/media/screenshot/tests/test_screenshot.py | tests/script_specs/skills/tools/media/screenshot/scripts/screenshot.sh.json | `screen-record` available on `PATH` (install via `brew install nils-cli`).; macOS: Screen Recording permission granted (use `screen-record --preflight` / `--request-permission`).; Linux: follow `screen-record` runtime prerequisites (X11 selectors or Wayland `--portal`, plus required dependencies).; `screencapture` (built-in on macOS) only when using `--desktop`.; `bash` for `scripts/screenshot.sh` (wrapper). | none | contract + entrypoint + smoke spec | +| skills/tools/skill-management/create-project-skill/SKILL.md | tools | 1 | skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh | skills/tools/skill-management/create-project-skill/tests/test_tools_skill_management_create_project_skill.py | none | Run inside a git work tree.; `bash`, `git`, and `python3` available on `PATH`.; Target project path is a git work tree where `.agents/skills/` can be created. | none | contract + entrypoint | +| skills/tools/skill-management/create-skill/SKILL.md | tools | 1 | skills/tools/skill-management/create-skill/scripts/create_skill.sh | skills/tools/skill-management/create-skill/tests/test_tools_skill_management_create_skill.py | tests/script_specs/skills/tools/skill-management/create-skill/scripts/create_skill.sh.json | Run inside a git work tree.; `bash`, `git`, and `python3` available on `PATH`. | docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md; docs/plans/skills-inventory-audit.md | contract + entrypoint + smoke spec | +| skills/tools/skill-management/remove-skill/SKILL.md | tools | 1 | skills/tools/skill-management/remove-skill/scripts/remove_skill.sh | skills/tools/skill-management/remove-skill/tests/test_tools_skill_management_remove_skill.py | tests/script_specs/skills/tools/skill-management/remove-skill/scripts/remove_skill.sh.json | Run inside a git work tree.; `bash`, `git`, `python3`, and `rg` available on `PATH`.; You understand this is a breaking change (no compatibility shims are created). | none | contract + entrypoint + smoke spec | +| skills/tools/skill-management/skill-governance/SKILL.md | tools | 3 | skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh; skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh; skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh | skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py | tests/script_specs/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh.json; tests/script_specs/skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh.json | Run inside a git work tree.; `bash` available on `PATH`.; `git` available on `PATH`.; `python3` available on `PATH`. | docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md; docs/plans/skills-inventory-audit.md | contract + entrypoint + partial smoke spec (2/3) | +| skills/tools/sql/sql-mssql/SKILL.md | tools | 1 | skills/tools/sql/sql-mssql/scripts/sql-mssql.sh | skills/tools/sql/sql-mssql/tests/test_tools_sql_sql_mssql.py | tests/script_specs/skills/tools/sql/sql-mssql/scripts/sql-mssql.sh.json | `bash` available on `PATH`.; `sqlcmd` available on `PATH` (or install via Homebrew; this skill will try to add `mssql-tools18/bin` to `PATH` when available).; Connection settings provided via exported env vars and/or an env file. | none | contract + entrypoint + smoke spec | +| skills/tools/sql/sql-mysql/SKILL.md | tools | 1 | skills/tools/sql/sql-mysql/scripts/sql-mysql.sh | skills/tools/sql/sql-mysql/tests/test_tools_sql_sql_mysql.py | tests/script_specs/skills/tools/sql/sql-mysql/scripts/sql-mysql.sh.json | `bash` available on `PATH`.; `mysql` client available on `PATH` (or install via Homebrew; this skill will try to add `mysql-client/bin` to `PATH` when available).; Connection settings provided via exported env vars and/or an env file. | none | contract + entrypoint + smoke spec | +| skills/tools/sql/sql-postgres/SKILL.md | tools | 1 | skills/tools/sql/sql-postgres/scripts/sql-postgres.sh | skills/tools/sql/sql-postgres/tests/test_tools_sql_sql_postgres.py | tests/script_specs/skills/tools/sql/sql-postgres/scripts/sql-postgres.sh.json | `bash` available on `PATH`.; `psql` available on `PATH` (or install via Homebrew; this skill will try to add `libpq/bin` to `PATH` when available).; Connection settings provided via exported env vars and/or an env file. | none | contract + entrypoint + smoke spec | +| skills/tools/testing/api-test-runner/SKILL.md | tools | 0 | none | skills/tools/testing/api-test-runner/tests/test_tools_testing_api_test_runner.py | none | `api-test`, `api-rest`, and `api-gql` available on `PATH` (install via `brew install nils-cli`).; `jq` recommended for ad-hoc assertions/formatting (optional). | skills/tools/testing/api-test-runner/references/API_TEST_RUNNER_GUIDE.md | contract + tool availability | +| skills/tools/testing/graphql-api-testing/SKILL.md | tools | 0 | none | skills/tools/testing/graphql-api-testing/tests/test_tools_testing_graphql_api_testing.py | none | `api-gql` available on `PATH` (install via `brew install nils-cli`).; `jq` recommended for pretty-printing/assertions (optional).; `setup/graphql/` exists (or bootstrap from template) with operations, vars, and optional endpoint/jwt presets. | skills/tools/testing/graphql-api-testing/references/GRAPHQL_API_TESTING_GUIDE.md; skills/tools/testing/graphql-api-testing/references/GRAPHQL_API_TEST_REPORT_CONTRACT.md; skills/tools/testing/graphql-api-testing/references/GRAPHQL_API_TEST_REPORT_TEMPLATE.md | contract + tool availability | +| skills/tools/testing/rest-api-testing/SKILL.md | tools | 0 | none | skills/tools/testing/rest-api-testing/tests/test_tools_testing_rest_api_testing.py | none | `api-rest` available on `PATH` (install via `brew install nils-cli`).; `jq` recommended for pretty-printing/assertions (optional).; `setup/rest/` exists (or bootstrap from template) with requests and optional endpoint/token presets. | skills/tools/testing/rest-api-testing/references/REST_API_TESTING_GUIDE.md; skills/tools/testing/rest-api-testing/references/REST_API_TEST_REPORT_CONTRACT.md; skills/tools/testing/rest-api-testing/references/REST_API_TEST_REPORT_TEMPLATE.md | contract + tool availability | +| skills/workflows/conversation/ask-questions-if-underspecified/SKILL.md | workflows | 0 | none | skills/workflows/conversation/ask-questions-if-underspecified/tests/test_workflows_conversation_ask_questions_if_underspecified.py | none | User request is missing must-have details (objective/scope/constraints/done criteria) and needs clarification before proceeding.; User is available to answer questions or explicitly approve stated assumptions. | none | contract | +| skills/workflows/coordination/delegate-parallel/SKILL.md | workflows | 0 | none | skills/workflows/coordination/delegate-parallel/tests/test_workflows_coordination_delegate_parallel.py | none | The user explicitly triggers this workflow (recommended invocation: `/delegate-parallel `).; The request can be decomposed into 2+ tasks with limited file overlap.; You can spawn and monitor multiple subagents.; There is a way to validate changes (tests/lint/build or a concrete manual checklist).; You can write artifacts to `$AGENT_HOME/out/` (fallback: repo `out/` if needed). | none | contract | +| skills/workflows/issue/issue-lifecycle/SKILL.md | workflows | 1 | skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh | skills/workflows/issue/issue-lifecycle/tests/test_workflows_issue_issue_lifecycle.py | tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json | Run inside the target git repo.; `gh` available on `PATH`, and `gh auth status` succeeds.; `python3` available on `PATH` for decomposition rendering. | skills/workflows/issue/_shared/references/TASK_LANE_CONTINUITY.md; skills/workflows/issue/_shared/references/POST_REVIEW_OUTCOMES.md; skills/workflows/issue/issue-lifecycle/references/ISSUE_TEMPLATE.md | contract + entrypoint + smoke spec | +| skills/workflows/issue/issue-pr-review/SKILL.md | workflows | 1 | skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh | skills/workflows/issue/issue-pr-review/tests/test_workflows_issue_issue_pr_review.py | tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json | Run inside the target git repo.; `gh` available on `PATH`, and `gh auth status` succeeds.; Target PR and related issue numbers are known. | skills/workflows/issue/_shared/references/TASK_LANE_CONTINUITY.md; skills/workflows/issue/_shared/references/MAIN_AGENT_REVIEW_RUBRIC.md; skills/workflows/issue/_shared/references/POST_REVIEW_OUTCOMES.md; skills/workflows/issue/issue-pr-review/references/CLOSE_PR_ISSUE_SYNC_TEMPLATE.md; skills/workflows/issue/issue-pr-review/references/ISSUE_SYNC_TEMPLATE.md; skills/workflows/issue/issue-pr-review/references/REQUEST_CHANGES_TEMPLATE.md; skills/workflows/issue/issue-pr-review/references/REVIEW_EVIDENCE_TEMPLATE.md | contract + entrypoint + smoke spec | +| skills/workflows/issue/issue-subagent-pr/SKILL.md | workflows | 0 | none | skills/workflows/issue/issue-subagent-pr/tests/test_workflows_issue_issue_subagent_pr.py | none | Run inside the target git repo.; `git` and `gh` available on `PATH`, and `gh auth status` succeeds.; Worktree/branch ownership assigned by main-agent (or the issue Task Decomposition table when using `plan-issue` flows). | skills/workflows/issue/_shared/references/TASK_LANE_CONTINUITY.md; skills/workflows/issue/issue-subagent-pr/references/PR_BODY_TEMPLATE.md; skills/workflows/issue/issue-subagent-pr/references/REVIEW_RESPONSE_TEMPLATE.md; skills/workflows/issue/issue-subagent-pr/references/SUBAGENT_TASK_PROMPT_TEMPLATE.md | contract | +| skills/workflows/plan/create-plan/SKILL.md | workflows | 0 | none | skills/workflows/plan/create-plan/tests/test_workflows_plan_create_plan.py | none | User is asking for an implementation plan (not asking you to build it yet).; You can read enough repo context to plan safely (or the user provides constraints).; `plan-tooling` available on `PATH` for linting (install via `brew install nils-cli`). | skills/workflows/plan/_shared/assets/plan-template.md | contract | +| skills/workflows/plan/create-plan-rigorous/SKILL.md | workflows | 0 | none | skills/workflows/plan/create-plan-rigorous/tests/test_workflows_plan_create_plan_rigorous.py | none | User explicitly requests a more rigorous plan than normal.; You can spawn a review subagent.; `plan-tooling` available on `PATH` for linting/parsing/splitting (`validate`, `to-json`, `batches`, `split-prs`; install via `brew install nils-cli`). | docs/plans/skills-inventory-audit.md; docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md; docs/runbooks/agent-docs/PROJECT_DEV_WORKFLOW.md; skills/workflows/plan/_shared/assets/plan-template.md; docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md | contract | +| skills/workflows/plan/docs-plan-cleanup/SKILL.md | workflows | 1 | skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh | skills/workflows/plan/docs-plan-cleanup/tests/test_workflows_plan_docs_plan_cleanup.py | none | `bash`, `git`, `find`, and `rg` available on `PATH`.; Target project must be a git work tree and contain `docs/plans/`.; Choose preserved plans first; run dry-run before `--execute`. | skills/workflows/plan/docs-plan-cleanup/references/ASSISTANT_RESPONSE_TEMPLATE.md | contract + entrypoint | +| skills/workflows/plan/execute-plan-parallel/SKILL.md | workflows | 0 | none | skills/workflows/plan/execute-plan-parallel/tests/test_workflows_plan_execute_plan_parallel.py | none | A plan file exists (markdown) with clear task breakdown and dependencies.; You can spawn and monitor multiple subagents.; The repo has a way to validate changes (tests, lint, build, or a manual checklist).; `plan-tooling` available on `PATH` for parsing/linting (install via `brew install nils-cli`). | none | contract | +| skills/workflows/pr/bug/close-bug-pr/SKILL.md | workflows | 1 | skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh | skills/workflows/pr/bug/close-bug-pr/tests/test_workflows_pr_bug_close_bug_pr.py | none | Run inside the target git repo.; `git` and `gh` available on `PATH`, and `gh auth status` succeeds.; Working tree clean (`git status --porcelain=v1` is empty). | none | contract + entrypoint | +| skills/workflows/pr/bug/create-bug-pr/SKILL.md | workflows | 1 | skills/workflows/pr/bug/create-bug-pr/scripts/render_bug_pr.sh | skills/workflows/pr/bug/create-bug-pr/tests/test_workflows_pr_bug_create_bug_pr.py | tests/script_specs/skills/workflows/pr/bug/create-bug-pr/scripts/render_bug_pr.sh.json | Run inside the target git repo with a clean working tree (or stash unrelated changes).; `git` and `gh` available on `PATH`, and `gh auth status` succeeds.; `$AGENT_HOME` points at the repo root (or tools are otherwise available). | none | contract + entrypoint + smoke spec | +| skills/workflows/pr/bug/deliver-bug-pr/SKILL.md | workflows | 1 | skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh | skills/workflows/pr/bug/deliver-bug-pr/tests/test_workflows_pr_bug_deliver_bug_pr.py; skills/workflows/pr/bug/deliver-bug-pr/tests/test_workflows_pr_bug_deliver_bug_pr_preflight.py | none | Run inside the target git repo.; `git` and `gh` available on `PATH`, and `gh auth status` succeeds.; Working tree may be dirty before preflight; preflight must run scope triage first.; Working tree must be clean before merge/close.; Companion skills available:; `create-bug-pr`; `close-bug-pr` | none | contract + entrypoint | +| skills/workflows/pr/feature/close-feature-pr/SKILL.md | workflows | 1 | skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh | skills/workflows/pr/feature/close-feature-pr/tests/test_workflows_pr_feature_close_feature_pr.py | none | Run inside the target git repo.; `git` and `gh` available on `PATH`, and `gh auth status` succeeds.; Working tree clean (`git status --porcelain=v1` is empty). | none | contract + entrypoint | +| skills/workflows/pr/feature/create-feature-pr/SKILL.md | workflows | 1 | skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh | skills/workflows/pr/feature/create-feature-pr/tests/test_workflows_pr_feature_create_feature_pr.py | tests/script_specs/skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh.json | Run inside the target git repo with a clean working tree (or stash unrelated changes).; `git` and `gh` available on `PATH`, and `gh auth status` succeeds.; `$AGENT_HOME` points at the repo root (or tools are otherwise available). | skills/workflows/pr/feature/create-feature-pr/references/ASSISTANT_RESPONSE_TEMPLATE.md; skills/workflows/pr/feature/create-feature-pr/references/PR_TEMPLATE.md | contract + entrypoint + smoke spec | +| skills/workflows/pr/feature/deliver-feature-pr/SKILL.md | workflows | 1 | skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh | skills/workflows/pr/feature/deliver-feature-pr/tests/test_workflows_pr_feature_deliver_feature_pr.py; skills/workflows/pr/feature/deliver-feature-pr/tests/test_workflows_pr_feature_deliver_feature_pr_preflight.py | none | Run inside the target git repo.; `git` and `gh` available on `PATH`, and `gh auth status` succeeds.; Working tree may be dirty before preflight; preflight must run scope triage first.; Working tree must be clean before merge/close.; Companion skills available:; `create-feature-pr`; `close-feature-pr` | none | contract + entrypoint | + +## Current Script-Spec Gaps + +These tracked entrypoints are currently owned by tests but do not have matching `tests/script_specs` smoke specs: + +- `skills/tools/agent-doc-init/scripts/agent_doc_init.sh` +- `skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh` +- `skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh` +- `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` +- `skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh` +- `skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh` +- `skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh` +- `skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh` +- `skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh` + +## Notes For Later Sprints + +- This document is an inventory only; it does not assign keep/merge/remove decisions for scripts. +- `skill-governance` is the only tracked skill with partial smoke-spec coverage for its current script set. +- Later remediation lanes should update this audit only when the tracked skill surface changes. diff --git a/docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md b/docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md new file mode 100644 index 00000000..16f6507c --- /dev/null +++ b/docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md @@ -0,0 +1,76 @@ +# Script Simplification Playbook + +## Goal + +Use this playbook when simplifying a tracked skill's script surface. +The target outcome is a smaller, clearer public entrypoint set without leaving orphaned tests, smoke specs, or migration ambiguity behind. +This playbook is based on the release-workflow simplification shipped in PR #221. + +## Decision Rules + +| Signal | Decision | +| --- | --- | +| The script exposes the primary stable workflow users should call directly. | `keep` | +| Multiple public scripts split one logical workflow and can be folded into a single supported command without hiding required behavior. | `merge` | +| The script is a thin wrapper, a superseded helper, or a public alias that no longer needs to exist after consolidation. | `remove` | +| The script remains necessary only for an internal helper role and should not stay public. | move helper logic out of `scripts/` into `lib/` or `_shared/`, then `remove` the public entrypoint | + +## Required Decision Record + +Record every changed script with these exact fields before or during implementation: + +| Field | Requirement | +| --- | --- | +| `old entrypoint` | Current public script path before the change | +| `decision` | `keep`, `merge`, or `remove` | +| `new entrypoint` | Final supported public path after the change | +| `test/spec updates` | Exact tests, smoke specs, and fixtures added, removed, or rewritten | +| `migration note` | Caller impact and old-to-new command mapping | + +## Execution Rules + +1. Keep one primary entrypoint whenever the skill can present one stable public workflow. +2. Merge only when the resulting command contract is clearer than the current split surface. +3. Remove a public script only after updating every coupled test, smoke spec, fixture, and docs reference. +4. Update `SKILL.md` in the same change as the script decision. +5. If the change is breaking for callers, add an explicit migration note in the skill docs or release notes. + +## Coupled Update Requirements + +When a script decision changes the public surface, update all applicable items in the same PR: + +- `SKILL.md` contract and usage examples +- any fallback or reference guide under `references/` +- per-skill tests under `/tests/` +- smoke specs under `tests/script_specs/...` +- smoke/regression tests under `tests/` +- fixtures used by smoke/regression tests +- runbooks or inventories that describe the skill surface + +## Post-Change Validation Matrix + +| Area | Required validation | +| --- | --- | +| contract | `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` | +| layout | `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh` | +| docs parity | `scripts/check.sh --docs` | +| entrypoint ownership | `scripts/check.sh --entrypoint-ownership` | +| smoke/spec freshness | `bash scripts/ci/stale-skill-scripts-audit.sh --check` | +| targeted regression | run the skill-specific test module(s) and any dedicated smoke test file touching the changed entrypoint | + +## PR #221 Example + +`release-workflow` used these simplification choices: + +- `old entrypoint`: `audit-changelog.zsh`, `release-audit.sh`, `release-find-guide.sh`, `release-notes-from-changelog.sh`, `release-scaffold-entry.sh` +- `decision`: merge publish behavior into `release-publish-from-changelog.sh`, remove the rest from the public surface +- `new entrypoint`: `skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` +- `test/spec updates`: keep contract and smoke coverage aligned with the new public entrypoint set; remove stale specs for retired scripts +- `migration note`: callers of retired release scripts must switch to `release-publish-from-changelog.sh` + +## Anti-Patterns + +- Leaving a removed script referenced in `SKILL.md`, runbooks, or smoke specs. +- Keeping thin compatibility wrappers in `scripts/` without a documented reason. +- Removing a script without updating the matching smoke fixtures. +- Treating helper scripts as public API when they should move to `lib/` or `_shared/`. diff --git a/docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md b/docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md new file mode 100644 index 00000000..f209709b --- /dev/null +++ b/docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md @@ -0,0 +1,46 @@ +# Skill Review Checklist + +## Purpose + +Use this checklist to review any tracked skill against the repo's contract, layout, and entrypoint rules. +Every checklist item maps to a deterministic repo command so reviewers can verify findings without judgment calls. +This checklist applies to existing skills, newly created skills, and refactors that remove or merge entrypoints. + +## Review Steps + +1. Confirm the target is a tracked skill under `skills/workflows/`, `skills/tools/`, or `skills/automation/`. +2. Run the contract validator for the full repo or the target file. +3. Run the layout audit for the full repo or the target directory. +4. Run entrypoint ownership checks when scripts are added, removed, or renamed. +5. Run smoke or regression coverage checks when script specs or public entrypoints change. +6. Verify supporting docs still match the maintained entrypoint surface. + +## Deterministic Checklist + +| Rule | Why it matters | Command-backed check | +| --- | --- | --- | +| `SKILL.md` exists and `## Contract` is the first H2 after the H1 title. | Keeps every skill contract machine-checkable. | `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh --file /SKILL.md` | +| Contract headings are present and in canonical order: `Prereqs`, `Inputs`, `Outputs`, `Exit codes`, `Failure modes`. | Prevents drift in required contract fields. | `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh --file /SKILL.md` | +| Top-level layout contains only allowed entries (`SKILL.md`, `scripts/`, `bin/`, `references/`, `assets/`, `tests/`). | Stops hidden structure drift and undocumented executables. | `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh --skill-dir ` | +| Tracked skills always include `tests/`. | Maintains minimum regression coverage for every skill. | `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh --skill-dir ` | +| Template markdown lives only under `references/` or `assets/templates/`. | Keeps executable and reusable docs separated. | `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh --skill-dir ` | +| Every maintained script under `skills/**/scripts/` is owned by a skill test via `assert_entrypoints_exist(...)` or an explicit reviewed exclusion. | Prevents orphaned public entrypoints. | `scripts/check.sh --entrypoint-ownership` | +| If a script is expected to participate in smoke coverage, its `tests/script_specs/...json` file stays in sync with the current entrypoint path. | Prevents stale smoke fixtures after script changes. | `bash scripts/ci/stale-skill-scripts-audit.sh --check` | +| Skill docs reference only maintained entrypoints and current supporting docs. | Avoids contract/docs mismatch after simplification. | `scripts/check.sh --docs` and targeted `rg -n '\$AGENT_HOME/.*/scripts/' docs/runbooks/skills skills/README.md` | +| Repo-wide contract/layout checks remain green after a skill change. | Ensures changes do not break unrelated tracked skills. | `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh && skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh` | + +## Change-Type Matrix + +| Change type | Required checks | +| --- | --- | +| Contract wording only | `validate_skill_contracts.sh --file /SKILL.md` | +| Add or remove non-template files under the skill directory | `audit-skill-layout.sh --skill-dir ` | +| Add, remove, or rename a script entrypoint | `scripts/check.sh --entrypoint-ownership` and `bash scripts/ci/stale-skill-scripts-audit.sh --check` | +| Update repo-facing skill docs or runbooks | `scripts/check.sh --docs` | +| Large skill-management or multi-skill refactor | `scripts/check.sh --contracts --skills-layout --entrypoint-ownership` plus `bash scripts/ci/stale-skill-scripts-audit.sh --check` | + +## Reviewer Notes + +- `create-skill` is the baseline scaffold contract, but this checklist is intentionally broader than scaffolding. +- A passing checklist does not decide whether a script should stay public; that decision belongs in the simplification playbook. +- When a skill removes or merges an entrypoint, update script specs, tests, and supporting docs in the same change. diff --git a/skills/README.md b/skills/README.md index d61be83c..cb9eb357 100644 --- a/skills/README.md +++ b/skills/README.md @@ -13,6 +13,12 @@ helpers, tests, and references needed to keep it reliable. - `../docs/runbooks/skills/TOOLING_INDEX_V2.md` - Create/validate/remove workflows: - `tools/skill-management/README.md` +- Repo-wide skill inventory baseline: + - `../docs/plans/skills-inventory-audit.md` +- Repo-wide review checklist: + - `../docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md` +- Script simplification playbook: + - `../docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md` ## Tracked skill categories diff --git a/skills/automation/release-workflow/SKILL.md b/skills/automation/release-workflow/SKILL.md index bf446656..360c2021 100644 --- a/skills/automation/release-workflow/SKILL.md +++ b/skills/automation/release-workflow/SKILL.md @@ -71,3 +71,10 @@ Use only these public entrypoints: ```bash $AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version v1.3.2 ``` + +## Related docs + +- Reference notes for the single-entrypoint simplification shipped in PR #221: + - `docs/plans/pr-221-reference-notes.md` +- Repo-wide script simplification playbook: + - `docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md` diff --git a/skills/tools/skill-management/create-skill/SKILL.md b/skills/tools/skill-management/create-skill/SKILL.md index fe2cdbc3..64bbb86c 100644 --- a/skills/tools/skill-management/create-skill/SKILL.md +++ b/skills/tools/skill-management/create-skill/SKILL.md @@ -46,3 +46,10 @@ Failure modes: ## Scripts (only entrypoints) - `$AGENT_HOME/skills/tools/skill-management/create-skill/scripts/create_skill.sh` + +## Related docs + +- Repo-wide review checklist: + - `docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md` +- Baseline inventory format and current coverage snapshot: + - `docs/plans/skills-inventory-audit.md` diff --git a/skills/tools/skill-management/skill-governance/SKILL.md b/skills/tools/skill-management/skill-governance/SKILL.md index d8244cbc..7f5a2a41 100644 --- a/skills/tools/skill-management/skill-governance/SKILL.md +++ b/skills/tools/skill-management/skill-governance/SKILL.md @@ -43,3 +43,10 @@ Failure modes: - `$AGENT_HOME/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh` - `$AGENT_HOME/skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` - `$AGENT_HOME/skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh` + +## Related docs + +- Repo-wide review checklist: + - `docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md` +- Baseline inventory snapshot for tracked skills: + - `docs/plans/skills-inventory-audit.md` diff --git a/skills/workflows/plan/create-plan-rigorous/SKILL.md b/skills/workflows/plan/create-plan-rigorous/SKILL.md index 906e7ec7..90c161c4 100644 --- a/skills/workflows/plan/create-plan-rigorous/SKILL.md +++ b/skills/workflows/plan/create-plan-rigorous/SKILL.md @@ -50,6 +50,8 @@ Failure modes: - Identify existing patterns and the minimal touch points. - Identify tricky edge cases, migrations, rollout, and compatibility constraints. +- For repo-wide skill work, use `docs/plans/skills-inventory-audit.md` as the baseline inventory and + `docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md` when planning entrypoint consolidation. 1. Draft the plan (do not implement) @@ -187,3 +189,7 @@ Rigorous requirement: - Treat sprints as sequential integration gates (no cross-sprint execution parallelism). - Optimize parallelism within each sprint and document the per-sprint scorecard (`Execution Profile`, `TotalComplexity`, `CriticalPathComplexity`, `MaxBatchWidth`, `OverlapHotspots`). +- When the plan changes tracked skill entrypoints or review rules, update the inventory/checklist/playbook docs in the same plan lane: + - `docs/plans/skills-inventory-audit.md` + - `docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md` + - `docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md` From 5d75f58f9c2665e993cb94c83ff281335a9a1b71 Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Wed, 4 Mar 2026 06:01:08 +0800 Subject: [PATCH 2/9] docs(issue-222): add S1T4 skill remediation maps --- docs/plans/skills-coverage-matrix.md | 46 +++++++++++++ docs/plans/skills-script-remediation-map.md | 73 +++++++++++++++++++++ 2 files changed, 119 insertions(+) create mode 100644 docs/plans/skills-coverage-matrix.md create mode 100644 docs/plans/skills-script-remediation-map.md diff --git a/docs/plans/skills-coverage-matrix.md b/docs/plans/skills-coverage-matrix.md new file mode 100644 index 00000000..b65a3e36 --- /dev/null +++ b/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 | diff --git a/docs/plans/skills-script-remediation-map.md b/docs/plans/skills-script-remediation-map.md new file mode 100644 index 00000000..ad1bd772 --- /dev/null +++ b/docs/plans/skills-script-remediation-map.md @@ -0,0 +1,73 @@ +# Skill Script Remediation Map + +## Overview + +This map classifies every tracked `skills/**/scripts/*` entrypoint on `plan/issue-222` using the read-only Sprint 1 dependency artifacts from branch `origin/issue/s1-t1-build-complete-skill-inventory`: + +- `docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md` +- `docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md` +- `docs/plans/skills-inventory-audit.md` + +Current baseline from `bash scripts/ci/stale-skill-scripts-audit.sh --check` is `33` active scripts, `0` transitional scripts, and `0` removable scripts. +This remediation map records the target public-surface decision for each tracked script before the later simplification lanes change code. + +## Decision Summary + +| Domain | Keep | Merge | Remove | +| --- | ---: | ---: | ---: | +| `automation` | 6 | 0 | 1 | +| `tools` | 16 | 0 | 1 | +| `workflows` | 7 | 0 | 2 | +| **Total** | **29** | **0** | **4** | + +## Keep Decisions That Still Need Smoke Specs + +| Entrypoint | Required spec add | +| --- | --- | +| `skills/tools/agent-doc-init/scripts/agent_doc_init.sh` | `tests/script_specs/skills/tools/agent-doc-init/scripts/agent_doc_init.sh.json` | +| `skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh` | `tests/script_specs/skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh.json` | +| `skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh` | `tests/script_specs/skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh.json` | +| `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` | `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh.json` | +| `skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh` | `tests/script_specs/skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh.json` | +| `skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh` | `tests/script_specs/skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh.json` | +| `skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh` | `tests/script_specs/skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh.json` | +| `skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh` | `tests/script_specs/skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh.json` | +| `skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh` | `tests/script_specs/skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh.json` | + +## Canonical Decision Record + +| Old entrypoint | Decision | New entrypoint | Rationale | Companion updates | Migration note | +| --- | --- | --- | --- | --- | --- | +| `skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh` | `remove` | `none (read references directly)` | Template renderer only; it cats `ISSUES_TEMPLATE.md` or `PR_TEMPLATE.md` and is not a stable workflow entrypoint. | Update `skills/automation/find-and-fix-bugs/SKILL.md` to point at `references/ISSUES_TEMPLATE.md` and `references/PR_TEMPLATE.md`; update `skills/automation/find-and-fix-bugs/tests/test_automation_find_and_fix_bugs.py`; remove `tests/script_specs/skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh.json`; fixtures: none. | Callers should read the templates directly from `skills/automation/find-and-fix-bugs/references/` instead of invoking `render_issues_pr.sh`. | +| `skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh` | `keep` | `skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh` | Deterministic PR-body patcher with a distinct supported responsibility after a fix lands. | Preserve `skills/automation/fix-bug-pr/SKILL.md`, `skills/automation/fix-bug-pr/tests/test_automation_fix_bug_pr.py`, and `tests/script_specs/skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh.json`. | none | +| `skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh` | `keep` | `skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh` | Deterministic resolver/parser for bug PR selection and unresolved-item extraction; not a thin alias. | Preserve `skills/automation/fix-bug-pr/SKILL.md`, `skills/automation/fix-bug-pr/tests/test_automation_fix_bug_pr.py`, and current ownership/spec coverage. | none | +| `skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh` | `keep` | `skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh` | Primary end-to-end CI remediation entrypoint for the skill. | Preserve `skills/automation/gh-fix-ci/SKILL.md`, `skills/automation/gh-fix-ci/tests/test_automation_gh_fix_ci.py`, and `tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json`. | none | +| `skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py` | `keep` | `skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py` | Explicit inspect-only mode with direct JSON/text output; documented as a supported fast path, not an undocumented helper. | Preserve `skills/automation/gh-fix-ci/SKILL.md`, `skills/automation/gh-fix-ci/tests/test_automation_gh_fix_ci.py`, and `tests/script_specs/skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py.json`. | none | +| `skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` | `keep` | `skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` | Canonical publish entrypoint retained by PR #221; current public surface is already simplified around it. | Preserve `skills/automation/release-workflow/SKILL.md`, `skills/automation/release-workflow/tests/test_automation_release_workflow.py`, and `tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json`. | none | +| `skills/automation/release-workflow/scripts/release-resolve.sh` | `keep` | `skills/automation/release-workflow/scripts/release-resolve.sh` | Distinct guide-resolution entrypoint still intentionally public after the PR #221 simplification. | Preserve `skills/automation/release-workflow/SKILL.md`, `skills/automation/release-workflow/tests/test_automation_release_workflow.py`, and `tests/script_specs/skills/automation/release-workflow/scripts/release-resolve.sh.json`. | none | +| `skills/tools/agent-doc-init/scripts/agent_doc_init.sh` | `keep` | `skills/tools/agent-doc-init/scripts/agent_doc_init.sh` | Single stable bootstrap command for baseline `agent-docs` initialization. | Preserve `skills/tools/agent-doc-init/SKILL.md` and `skills/tools/agent-doc-init/tests/test_tools_agent_doc_init.py`; add `tests/script_specs/skills/tools/agent-doc-init/scripts/agent_doc_init.sh.json`. | none | +| `skills/tools/browser/agent-browser/scripts/agent-browser.sh` | `keep` | `skills/tools/browser/agent-browser/scripts/agent-browser.sh` | Stable wrapper for the browser automation CLI with dedicated skill docs and smoke coverage. | Preserve `skills/tools/browser/agent-browser/SKILL.md`, `skills/tools/browser/agent-browser/tests/test_tools_browser_agent_browser.py`, and `tests/script_specs/skills/tools/browser/agent-browser/scripts/agent-browser.sh.json`. | none | +| `skills/tools/browser/playwright/scripts/playwright_cli.sh` | `keep` | `skills/tools/browser/playwright/scripts/playwright_cli.sh` | Stable wrapper for Playwright CLI workflows. | Preserve `skills/tools/browser/playwright/SKILL.md`, `skills/tools/browser/playwright/tests/test_tools_browser_playwright.py`, and `tests/script_specs/skills/tools/browser/playwright/scripts/playwright_cli.sh.json`. | none | +| `skills/tools/devex/desktop-notify/scripts/desktop-notify.sh` | `keep` | `skills/tools/devex/desktop-notify/scripts/desktop-notify.sh` | Supported custom-title notifier entrypoint; the skill contract documents it explicitly alongside the project wrapper. | Preserve `skills/tools/devex/desktop-notify/SKILL.md`, `skills/tools/devex/desktop-notify/tests/test_tools_devex_desktop_notify.py`, and `tests/script_specs/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh.json`. | none | +| `skills/tools/devex/desktop-notify/scripts/project-notify.sh` | `keep` | `skills/tools/devex/desktop-notify/scripts/project-notify.sh` | Preferred project-title wrapper for the skill; this is the ergonomic primary path. | Preserve `skills/tools/devex/desktop-notify/SKILL.md`, `skills/tools/devex/desktop-notify/tests/test_tools_devex_desktop_notify.py`, and `tests/script_specs/skills/tools/devex/desktop-notify/scripts/project-notify.sh.json`. | none | +| `skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh` | `keep` | `skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh` | Single stable wrapper for opening changed files in VSCode. | Preserve `skills/tools/devex/open-changed-files-review/SKILL.md`, `skills/tools/devex/open-changed-files-review/tests/test_tools_devex_open_changed_files_review.py`, and `tests/script_specs/skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh.json`. | none | +| `skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh` | `keep` | `skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh` | Single stable automation wrapper for `macos-agent` routines. | Preserve `skills/tools/macos-agent-ops/SKILL.md` and `skills/tools/macos-agent-ops/tests/test_tools_macos_agent_ops.py`; add `tests/script_specs/skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh.json`. | none | +| `skills/tools/media/screenshot/scripts/screenshot.sh` | `keep` | `skills/tools/media/screenshot/scripts/screenshot.sh` | Stable screenshot wrapper with existing smoke coverage. | Preserve `skills/tools/media/screenshot/SKILL.md`, `skills/tools/media/screenshot/tests/test_screenshot.py`, and `tests/script_specs/skills/tools/media/screenshot/scripts/screenshot.sh.json`. | none | +| `skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh` | `keep` | `skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh` | Stable scaffold generator for project-local skills. | Preserve `skills/tools/skill-management/create-project-skill/SKILL.md` and `skills/tools/skill-management/create-project-skill/tests/test_tools_skill_management_create_project_skill.py`; add `tests/script_specs/skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh.json`. | none | +| `skills/tools/skill-management/create-skill/scripts/create_skill.sh` | `keep` | `skills/tools/skill-management/create-skill/scripts/create_skill.sh` | Canonical repo-level skill scaffold generator. | Preserve `skills/tools/skill-management/create-skill/SKILL.md`, `skills/tools/skill-management/create-skill/tests/test_tools_skill_management_create_skill.py`, and `tests/script_specs/skills/tools/skill-management/create-skill/scripts/create_skill.sh.json`. | none | +| `skills/tools/skill-management/remove-skill/scripts/remove_skill.sh` | `keep` | `skills/tools/skill-management/remove-skill/scripts/remove_skill.sh` | Stable destructive-entry workflow with explicit breaking-change semantics. | Preserve `skills/tools/skill-management/remove-skill/SKILL.md`, `skills/tools/skill-management/remove-skill/tests/test_tools_skill_management_remove_skill.py`, and `tests/script_specs/skills/tools/skill-management/remove-skill/scripts/remove_skill.sh.json`. | none | +| `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh` | `keep` | `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh` | Deterministic layout audit remains a core public validator. | Preserve `skills/tools/skill-management/skill-governance/SKILL.md`, `skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py`, and `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh.json`. | none | +| `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` | `keep` | `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` | Deterministic contract validator remains a core public validator. | Preserve `skills/tools/skill-management/skill-governance/SKILL.md` and `skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py`; add `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh.json`. | none | +| `skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh` | `remove` | `none (fold future path checks into enforced validators)` | Placeholder entrypoint only; it exits successfully with no real enforcement and should not remain a public validator. | Update `skills/tools/skill-management/skill-governance/SKILL.md` and `skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py`; remove `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh.json`; fixtures: none. | Until real path enforcement exists, callers should use `audit-skill-layout.sh` and `validate_skill_contracts.sh`. | +| `skills/tools/sql/sql-mssql/scripts/sql-mssql.sh` | `keep` | `skills/tools/sql/sql-mssql/scripts/sql-mssql.sh` | Stable SQL Server wrapper with current smoke coverage. | Preserve `skills/tools/sql/sql-mssql/SKILL.md`, `skills/tools/sql/sql-mssql/tests/test_tools_sql_sql_mssql.py`, and `tests/script_specs/skills/tools/sql/sql-mssql/scripts/sql-mssql.sh.json`. | none | +| `skills/tools/sql/sql-mysql/scripts/sql-mysql.sh` | `keep` | `skills/tools/sql/sql-mysql/scripts/sql-mysql.sh` | Stable MySQL wrapper with current smoke coverage. | Preserve `skills/tools/sql/sql-mysql/SKILL.md`, `skills/tools/sql/sql-mysql/tests/test_tools_sql_sql_mysql.py`, and `tests/script_specs/skills/tools/sql/sql-mysql/scripts/sql-mysql.sh.json`. | none | +| `skills/tools/sql/sql-postgres/scripts/sql-postgres.sh` | `keep` | `skills/tools/sql/sql-postgres/scripts/sql-postgres.sh` | Stable PostgreSQL wrapper with current smoke coverage. | Preserve `skills/tools/sql/sql-postgres/SKILL.md`, `skills/tools/sql/sql-postgres/tests/test_tools_sql_sql_postgres.py`, and `tests/script_specs/skills/tools/sql/sql-postgres/scripts/sql-postgres.sh.json`. | none | +| `skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh` | `keep` | `skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh` | Primary issue-lifecycle orchestration entrypoint for the workflow skill. | Preserve `skills/workflows/issue/issue-lifecycle/SKILL.md`, `skills/workflows/issue/issue-lifecycle/tests/test_workflows_issue_issue_lifecycle.py`, and `tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json`. | none | +| `skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh` | `keep` | `skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh` | Primary review-orchestration entrypoint for the workflow skill. | Preserve `skills/workflows/issue/issue-pr-review/SKILL.md`, `skills/workflows/issue/issue-pr-review/tests/test_workflows_issue_issue_pr_review.py`, and `tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json`. | none | +| `skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh` | `keep` | `skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh` | Single stable cleanup entrypoint for plan-doc pruning. | Preserve `skills/workflows/plan/docs-plan-cleanup/SKILL.md` and `skills/workflows/plan/docs-plan-cleanup/tests/test_workflows_plan_docs_plan_cleanup.py`; add `tests/script_specs/skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh.json`. | none | +| `skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh` | `keep` | `skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh` | Stable close/merge entrypoint for the bug PR close workflow. | Preserve `skills/workflows/pr/bug/close-bug-pr/SKILL.md` and `skills/workflows/pr/bug/close-bug-pr/tests/test_workflows_pr_bug_close_bug_pr.py`; add `tests/script_specs/skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh.json`. | none | +| `skills/workflows/pr/bug/create-bug-pr/scripts/render_bug_pr.sh` | `remove` | `none (read shared references directly)` | Template renderer only; it emits existing PR/output templates and does not implement the workflow itself. | Update `skills/workflows/pr/bug/create-bug-pr/SKILL.md` and `skills/workflows/pr/bug/create-bug-pr/tests/test_workflows_pr_bug_create_bug_pr.py`; remove `tests/script_specs/skills/workflows/pr/bug/create-bug-pr/scripts/render_bug_pr.sh.json`; fixtures: none. | Callers should read `skills/automation/find-and-fix-bugs/references/PR_TEMPLATE.md` and `ASSISTANT_RESPONSE_TEMPLATE.md` directly. | +| `skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh` | `keep` | `skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh` | Primary end-to-end delivery entrypoint for bug PR automation. | Preserve `skills/workflows/pr/bug/deliver-bug-pr/SKILL.md` and both test modules under `skills/workflows/pr/bug/deliver-bug-pr/tests/`; add `tests/script_specs/skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh.json`. | none | +| `skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh` | `keep` | `skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh` | Stable close/merge entrypoint for the feature PR close workflow. | Preserve `skills/workflows/pr/feature/close-feature-pr/SKILL.md` and `skills/workflows/pr/feature/close-feature-pr/tests/test_workflows_pr_feature_close_feature_pr.py`; add `tests/script_specs/skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh.json`. | none | +| `skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh` | `remove` | `none (read skill references directly)` | Template renderer only; it emits existing PR/output templates and does not implement the workflow itself. | Update `skills/workflows/pr/feature/create-feature-pr/SKILL.md` and `skills/workflows/pr/feature/create-feature-pr/tests/test_workflows_pr_feature_create_feature_pr.py`; remove `tests/script_specs/skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh.json`; fixtures: none. | Callers should read `skills/workflows/pr/feature/create-feature-pr/references/PR_TEMPLATE.md` and `ASSISTANT_RESPONSE_TEMPLATE.md` directly. | +| `skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh` | `keep` | `skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh` | Primary end-to-end delivery entrypoint for feature PR automation. | Preserve `skills/workflows/pr/feature/deliver-feature-pr/SKILL.md` and both test modules under `skills/workflows/pr/feature/deliver-feature-pr/tests/`; add `tests/script_specs/skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh.json`. | none | From 1697571450b8aac5736534800c075c199829958b Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Wed, 4 Mar 2026 06:06:09 +0800 Subject: [PATCH 3/9] docs(issue-222): fix remediation map markdown lint --- docs/plans/skills-script-remediation-map.md | 112 ++++++++------------ 1 file changed, 43 insertions(+), 69 deletions(-) diff --git a/docs/plans/skills-script-remediation-map.md b/docs/plans/skills-script-remediation-map.md index ad1bd772..e7f79022 100644 --- a/docs/plans/skills-script-remediation-map.md +++ b/docs/plans/skills-script-remediation-map.md @@ -2,72 +2,46 @@ ## Overview -This map classifies every tracked `skills/**/scripts/*` entrypoint on `plan/issue-222` using the read-only Sprint 1 dependency artifacts from branch `origin/issue/s1-t1-build-complete-skill-inventory`: - -- `docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md` -- `docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md` -- `docs/plans/skills-inventory-audit.md` - -Current baseline from `bash scripts/ci/stale-skill-scripts-audit.sh --check` is `33` active scripts, `0` transitional scripts, and `0` removable scripts. -This remediation map records the target public-surface decision for each tracked script before the later simplification lanes change code. - -## Decision Summary - -| Domain | Keep | Merge | Remove | -| --- | ---: | ---: | ---: | -| `automation` | 6 | 0 | 1 | -| `tools` | 16 | 0 | 1 | -| `workflows` | 7 | 0 | 2 | -| **Total** | **29** | **0** | **4** | - -## Keep Decisions That Still Need Smoke Specs - -| Entrypoint | Required spec add | -| --- | --- | -| `skills/tools/agent-doc-init/scripts/agent_doc_init.sh` | `tests/script_specs/skills/tools/agent-doc-init/scripts/agent_doc_init.sh.json` | -| `skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh` | `tests/script_specs/skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh.json` | -| `skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh` | `tests/script_specs/skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh.json` | -| `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` | `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh.json` | -| `skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh` | `tests/script_specs/skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh.json` | -| `skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh` | `tests/script_specs/skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh.json` | -| `skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh` | `tests/script_specs/skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh.json` | -| `skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh` | `tests/script_specs/skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh.json` | -| `skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh` | `tests/script_specs/skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh.json` | - -## Canonical Decision Record - -| Old entrypoint | Decision | New entrypoint | Rationale | Companion updates | Migration note | -| --- | --- | --- | --- | --- | --- | -| `skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh` | `remove` | `none (read references directly)` | Template renderer only; it cats `ISSUES_TEMPLATE.md` or `PR_TEMPLATE.md` and is not a stable workflow entrypoint. | Update `skills/automation/find-and-fix-bugs/SKILL.md` to point at `references/ISSUES_TEMPLATE.md` and `references/PR_TEMPLATE.md`; update `skills/automation/find-and-fix-bugs/tests/test_automation_find_and_fix_bugs.py`; remove `tests/script_specs/skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh.json`; fixtures: none. | Callers should read the templates directly from `skills/automation/find-and-fix-bugs/references/` instead of invoking `render_issues_pr.sh`. | -| `skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh` | `keep` | `skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh` | Deterministic PR-body patcher with a distinct supported responsibility after a fix lands. | Preserve `skills/automation/fix-bug-pr/SKILL.md`, `skills/automation/fix-bug-pr/tests/test_automation_fix_bug_pr.py`, and `tests/script_specs/skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh.json`. | none | -| `skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh` | `keep` | `skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh` | Deterministic resolver/parser for bug PR selection and unresolved-item extraction; not a thin alias. | Preserve `skills/automation/fix-bug-pr/SKILL.md`, `skills/automation/fix-bug-pr/tests/test_automation_fix_bug_pr.py`, and current ownership/spec coverage. | none | -| `skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh` | `keep` | `skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh` | Primary end-to-end CI remediation entrypoint for the skill. | Preserve `skills/automation/gh-fix-ci/SKILL.md`, `skills/automation/gh-fix-ci/tests/test_automation_gh_fix_ci.py`, and `tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json`. | none | -| `skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py` | `keep` | `skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py` | Explicit inspect-only mode with direct JSON/text output; documented as a supported fast path, not an undocumented helper. | Preserve `skills/automation/gh-fix-ci/SKILL.md`, `skills/automation/gh-fix-ci/tests/test_automation_gh_fix_ci.py`, and `tests/script_specs/skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py.json`. | none | -| `skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` | `keep` | `skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` | Canonical publish entrypoint retained by PR #221; current public surface is already simplified around it. | Preserve `skills/automation/release-workflow/SKILL.md`, `skills/automation/release-workflow/tests/test_automation_release_workflow.py`, and `tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json`. | none | -| `skills/automation/release-workflow/scripts/release-resolve.sh` | `keep` | `skills/automation/release-workflow/scripts/release-resolve.sh` | Distinct guide-resolution entrypoint still intentionally public after the PR #221 simplification. | Preserve `skills/automation/release-workflow/SKILL.md`, `skills/automation/release-workflow/tests/test_automation_release_workflow.py`, and `tests/script_specs/skills/automation/release-workflow/scripts/release-resolve.sh.json`. | none | -| `skills/tools/agent-doc-init/scripts/agent_doc_init.sh` | `keep` | `skills/tools/agent-doc-init/scripts/agent_doc_init.sh` | Single stable bootstrap command for baseline `agent-docs` initialization. | Preserve `skills/tools/agent-doc-init/SKILL.md` and `skills/tools/agent-doc-init/tests/test_tools_agent_doc_init.py`; add `tests/script_specs/skills/tools/agent-doc-init/scripts/agent_doc_init.sh.json`. | none | -| `skills/tools/browser/agent-browser/scripts/agent-browser.sh` | `keep` | `skills/tools/browser/agent-browser/scripts/agent-browser.sh` | Stable wrapper for the browser automation CLI with dedicated skill docs and smoke coverage. | Preserve `skills/tools/browser/agent-browser/SKILL.md`, `skills/tools/browser/agent-browser/tests/test_tools_browser_agent_browser.py`, and `tests/script_specs/skills/tools/browser/agent-browser/scripts/agent-browser.sh.json`. | none | -| `skills/tools/browser/playwright/scripts/playwright_cli.sh` | `keep` | `skills/tools/browser/playwright/scripts/playwright_cli.sh` | Stable wrapper for Playwright CLI workflows. | Preserve `skills/tools/browser/playwright/SKILL.md`, `skills/tools/browser/playwright/tests/test_tools_browser_playwright.py`, and `tests/script_specs/skills/tools/browser/playwright/scripts/playwright_cli.sh.json`. | none | -| `skills/tools/devex/desktop-notify/scripts/desktop-notify.sh` | `keep` | `skills/tools/devex/desktop-notify/scripts/desktop-notify.sh` | Supported custom-title notifier entrypoint; the skill contract documents it explicitly alongside the project wrapper. | Preserve `skills/tools/devex/desktop-notify/SKILL.md`, `skills/tools/devex/desktop-notify/tests/test_tools_devex_desktop_notify.py`, and `tests/script_specs/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh.json`. | none | -| `skills/tools/devex/desktop-notify/scripts/project-notify.sh` | `keep` | `skills/tools/devex/desktop-notify/scripts/project-notify.sh` | Preferred project-title wrapper for the skill; this is the ergonomic primary path. | Preserve `skills/tools/devex/desktop-notify/SKILL.md`, `skills/tools/devex/desktop-notify/tests/test_tools_devex_desktop_notify.py`, and `tests/script_specs/skills/tools/devex/desktop-notify/scripts/project-notify.sh.json`. | none | -| `skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh` | `keep` | `skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh` | Single stable wrapper for opening changed files in VSCode. | Preserve `skills/tools/devex/open-changed-files-review/SKILL.md`, `skills/tools/devex/open-changed-files-review/tests/test_tools_devex_open_changed_files_review.py`, and `tests/script_specs/skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh.json`. | none | -| `skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh` | `keep` | `skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh` | Single stable automation wrapper for `macos-agent` routines. | Preserve `skills/tools/macos-agent-ops/SKILL.md` and `skills/tools/macos-agent-ops/tests/test_tools_macos_agent_ops.py`; add `tests/script_specs/skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh.json`. | none | -| `skills/tools/media/screenshot/scripts/screenshot.sh` | `keep` | `skills/tools/media/screenshot/scripts/screenshot.sh` | Stable screenshot wrapper with existing smoke coverage. | Preserve `skills/tools/media/screenshot/SKILL.md`, `skills/tools/media/screenshot/tests/test_screenshot.py`, and `tests/script_specs/skills/tools/media/screenshot/scripts/screenshot.sh.json`. | none | -| `skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh` | `keep` | `skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh` | Stable scaffold generator for project-local skills. | Preserve `skills/tools/skill-management/create-project-skill/SKILL.md` and `skills/tools/skill-management/create-project-skill/tests/test_tools_skill_management_create_project_skill.py`; add `tests/script_specs/skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh.json`. | none | -| `skills/tools/skill-management/create-skill/scripts/create_skill.sh` | `keep` | `skills/tools/skill-management/create-skill/scripts/create_skill.sh` | Canonical repo-level skill scaffold generator. | Preserve `skills/tools/skill-management/create-skill/SKILL.md`, `skills/tools/skill-management/create-skill/tests/test_tools_skill_management_create_skill.py`, and `tests/script_specs/skills/tools/skill-management/create-skill/scripts/create_skill.sh.json`. | none | -| `skills/tools/skill-management/remove-skill/scripts/remove_skill.sh` | `keep` | `skills/tools/skill-management/remove-skill/scripts/remove_skill.sh` | Stable destructive-entry workflow with explicit breaking-change semantics. | Preserve `skills/tools/skill-management/remove-skill/SKILL.md`, `skills/tools/skill-management/remove-skill/tests/test_tools_skill_management_remove_skill.py`, and `tests/script_specs/skills/tools/skill-management/remove-skill/scripts/remove_skill.sh.json`. | none | -| `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh` | `keep` | `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh` | Deterministic layout audit remains a core public validator. | Preserve `skills/tools/skill-management/skill-governance/SKILL.md`, `skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py`, and `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh.json`. | none | -| `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` | `keep` | `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` | Deterministic contract validator remains a core public validator. | Preserve `skills/tools/skill-management/skill-governance/SKILL.md` and `skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py`; add `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh.json`. | none | -| `skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh` | `remove` | `none (fold future path checks into enforced validators)` | Placeholder entrypoint only; it exits successfully with no real enforcement and should not remain a public validator. | Update `skills/tools/skill-management/skill-governance/SKILL.md` and `skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py`; remove `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh.json`; fixtures: none. | Until real path enforcement exists, callers should use `audit-skill-layout.sh` and `validate_skill_contracts.sh`. | -| `skills/tools/sql/sql-mssql/scripts/sql-mssql.sh` | `keep` | `skills/tools/sql/sql-mssql/scripts/sql-mssql.sh` | Stable SQL Server wrapper with current smoke coverage. | Preserve `skills/tools/sql/sql-mssql/SKILL.md`, `skills/tools/sql/sql-mssql/tests/test_tools_sql_sql_mssql.py`, and `tests/script_specs/skills/tools/sql/sql-mssql/scripts/sql-mssql.sh.json`. | none | -| `skills/tools/sql/sql-mysql/scripts/sql-mysql.sh` | `keep` | `skills/tools/sql/sql-mysql/scripts/sql-mysql.sh` | Stable MySQL wrapper with current smoke coverage. | Preserve `skills/tools/sql/sql-mysql/SKILL.md`, `skills/tools/sql/sql-mysql/tests/test_tools_sql_sql_mysql.py`, and `tests/script_specs/skills/tools/sql/sql-mysql/scripts/sql-mysql.sh.json`. | none | -| `skills/tools/sql/sql-postgres/scripts/sql-postgres.sh` | `keep` | `skills/tools/sql/sql-postgres/scripts/sql-postgres.sh` | Stable PostgreSQL wrapper with current smoke coverage. | Preserve `skills/tools/sql/sql-postgres/SKILL.md`, `skills/tools/sql/sql-postgres/tests/test_tools_sql_sql_postgres.py`, and `tests/script_specs/skills/tools/sql/sql-postgres/scripts/sql-postgres.sh.json`. | none | -| `skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh` | `keep` | `skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh` | Primary issue-lifecycle orchestration entrypoint for the workflow skill. | Preserve `skills/workflows/issue/issue-lifecycle/SKILL.md`, `skills/workflows/issue/issue-lifecycle/tests/test_workflows_issue_issue_lifecycle.py`, and `tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json`. | none | -| `skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh` | `keep` | `skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh` | Primary review-orchestration entrypoint for the workflow skill. | Preserve `skills/workflows/issue/issue-pr-review/SKILL.md`, `skills/workflows/issue/issue-pr-review/tests/test_workflows_issue_issue_pr_review.py`, and `tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json`. | none | -| `skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh` | `keep` | `skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh` | Single stable cleanup entrypoint for plan-doc pruning. | Preserve `skills/workflows/plan/docs-plan-cleanup/SKILL.md` and `skills/workflows/plan/docs-plan-cleanup/tests/test_workflows_plan_docs_plan_cleanup.py`; add `tests/script_specs/skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh.json`. | none | -| `skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh` | `keep` | `skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh` | Stable close/merge entrypoint for the bug PR close workflow. | Preserve `skills/workflows/pr/bug/close-bug-pr/SKILL.md` and `skills/workflows/pr/bug/close-bug-pr/tests/test_workflows_pr_bug_close_bug_pr.py`; add `tests/script_specs/skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh.json`. | none | -| `skills/workflows/pr/bug/create-bug-pr/scripts/render_bug_pr.sh` | `remove` | `none (read shared references directly)` | Template renderer only; it emits existing PR/output templates and does not implement the workflow itself. | Update `skills/workflows/pr/bug/create-bug-pr/SKILL.md` and `skills/workflows/pr/bug/create-bug-pr/tests/test_workflows_pr_bug_create_bug_pr.py`; remove `tests/script_specs/skills/workflows/pr/bug/create-bug-pr/scripts/render_bug_pr.sh.json`; fixtures: none. | Callers should read `skills/automation/find-and-fix-bugs/references/PR_TEMPLATE.md` and `ASSISTANT_RESPONSE_TEMPLATE.md` directly. | -| `skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh` | `keep` | `skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh` | Primary end-to-end delivery entrypoint for bug PR automation. | Preserve `skills/workflows/pr/bug/deliver-bug-pr/SKILL.md` and both test modules under `skills/workflows/pr/bug/deliver-bug-pr/tests/`; add `tests/script_specs/skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh.json`. | none | -| `skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh` | `keep` | `skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh` | Stable close/merge entrypoint for the feature PR close workflow. | Preserve `skills/workflows/pr/feature/close-feature-pr/SKILL.md` and `skills/workflows/pr/feature/close-feature-pr/tests/test_workflows_pr_feature_close_feature_pr.py`; add `tests/script_specs/skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh.json`. | none | -| `skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh` | `remove` | `none (read skill references directly)` | Template renderer only; it emits existing PR/output templates and does not implement the workflow itself. | Update `skills/workflows/pr/feature/create-feature-pr/SKILL.md` and `skills/workflows/pr/feature/create-feature-pr/tests/test_workflows_pr_feature_create_feature_pr.py`; remove `tests/script_specs/skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh.json`; fixtures: none. | Callers should read `skills/workflows/pr/feature/create-feature-pr/references/PR_TEMPLATE.md` and `ASSISTANT_RESPONSE_TEMPLATE.md` directly. | -| `skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh` | `keep` | `skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh` | Primary end-to-end delivery entrypoint for feature PR automation. | Preserve `skills/workflows/pr/feature/deliver-feature-pr/SKILL.md` and both test modules under `skills/workflows/pr/feature/deliver-feature-pr/tests/`; add `tests/script_specs/skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh.json`. | none | +This table records one remediation decision for every tracked `skills/**/scripts/*` entry in the current repo state. +The current audit classifies all 33 tracked scripts as `ACTIVE`, so this map +treats the audit as current-state evidence and records a separate +`keep|merge|remove` decision for later simplification work. +No repo-local evidence currently justifies merging or removing any remaining +tracked script surface, so every row stays `keep` until a future lane changes +the contract, tests, specs, and migration surface together. + +| Skill Path | Old Entrypoint | Audit Classification | Decision | New Entrypoint | Rationale | Docs Updates (SKILL.md/runbooks) | Test Updates | Script Spec Updates | Fixture Updates | Migration Note | +| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | +| `skills/automation/find-and-fix-bugs/SKILL.md` | `skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh` | `ACTIVE` | `keep` | `skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh` | Only tracked public entrypoint for this skill; the inventory shows contract, entrypoint, and smoke-spec ownership. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/automation/find-and-fix-bugs/tests/test_automation_find_and_fix_bugs.py`. | None; retain `tests/script_specs/skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/automation/fix-bug-pr/SKILL.md` | `skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh` | `ACTIVE` | `keep` | `skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh` | Public helper for PR body status sync; `SKILL.md` calls it directly and the current tests/specs own it. | None; keep current `SKILL.md` workflow step. | None; retain `skills/automation/fix-bug-pr/tests/test_automation_fix_bug_pr.py`. | None; retain `tests/script_specs/skills/automation/fix-bug-pr/scripts/bug-pr-patch.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/automation/fix-bug-pr/SKILL.md` | `skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh` | `ACTIVE` | `keep` | `skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh` | Public helper for selecting the target bug PR and next bug item; no repo-local merge target is documented. | None; keep current `SKILL.md` workflow step. | None; retain `skills/automation/fix-bug-pr/tests/test_automation_fix_bug_pr.py`. | None; retain `tests/script_specs/skills/automation/fix-bug-pr/scripts/bug-pr-resolve.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/automation/gh-fix-ci/SKILL.md` | `skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh` | `ACTIVE` | `keep` | `skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh` | Primary automation driver for this skill; `SKILL.md` exposes it as the default end-to-end command and tests/specs cover it. | None; keep current `SKILL.md` fast paths and script list. | None; retain `skills/automation/gh-fix-ci/tests/test_automation_gh_fix_ci.py`. | None; retain `tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/automation/gh-fix-ci/SKILL.md` | `skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py` | `ACTIVE` | `keep` | `skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py` | Machine-readable inspection entrypoint is explicitly documented alongside the shell driver; merging it would remove the direct reporting surface. | None; keep current `SKILL.md` fast paths and script list. | None; retain `skills/automation/gh-fix-ci/tests/test_automation_gh_fix_ci.py`. | None; retain `tests/script_specs/skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/automation/release-workflow/SKILL.md` | `skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` | `ACTIVE` | `keep` | `skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` | PR #221 already consolidated legacy release helpers into this publish entrypoint; the current contract, tests, and smoke spec reflect the simplified final surface. | None; keep current `SKILL.md`, `docs/runbooks/skills/SCRIPT_SIMPLIFICATION_PLAYBOOK.md`, and `docs/plans/pr-221-reference-notes.md` references aligned. | None; retain `skills/automation/release-workflow/tests/test_automation_release_workflow.py`. | None; retain `tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json`. | None. | No caller change; this remains the supported publish entrypoint after PR #221. | +| `skills/automation/release-workflow/SKILL.md` | `skills/automation/release-workflow/scripts/release-resolve.sh` | `ACTIVE` | `keep` | `skills/automation/release-workflow/scripts/release-resolve.sh` | Guide resolution is still a distinct public primitive after PR #221; `SKILL.md` and `references/DEFAULT_RELEASE_GUIDE.md` depend on it. | None; keep current `SKILL.md` and `skills/automation/release-workflow/references/DEFAULT_RELEASE_GUIDE.md` references aligned. | None; retain `skills/automation/release-workflow/tests/test_automation_release_workflow.py`. | None; retain `tests/script_specs/skills/automation/release-workflow/scripts/release-resolve.sh.json`. | None. | No caller change; guide resolution remains separate from publish. | +| `skills/tools/agent-doc-init/SKILL.md` | `skills/tools/agent-doc-init/scripts/agent_doc_init.sh` | `ACTIVE` | `keep` | `skills/tools/agent-doc-init/scripts/agent_doc_init.sh` | Only tracked entrypoint for new-repo bootstrap; the skill contract and startup docs depend on this command even though no smoke spec is checked in yet. | None; keep current `SKILL.md` and bootstrap references. | None; retain `skills/tools/agent-doc-init/tests/test_tools_agent_doc_init.py`. | None; no checked-in spec at `tests/script_specs/skills/tools/agent-doc-init/scripts/agent_doc_init.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/browser/agent-browser/SKILL.md` | `skills/tools/browser/agent-browser/scripts/agent-browser.sh` | `ACTIVE` | `keep` | `skills/tools/browser/agent-browser/scripts/agent-browser.sh` | Only tracked entrypoint for this skill; the current contract, tests, and smoke spec already pin the supported browser wrapper. | None; keep current `SKILL.md` command examples. | None; retain `skills/tools/browser/agent-browser/tests/test_tools_browser_agent_browser.py`. | None; retain `tests/script_specs/skills/tools/browser/agent-browser/scripts/agent-browser.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/browser/playwright/SKILL.md` | `skills/tools/browser/playwright/scripts/playwright_cli.sh` | `ACTIVE` | `keep` | `skills/tools/browser/playwright/scripts/playwright_cli.sh` | Only tracked entrypoint for this skill; the current contract, tests, and smoke spec already pin the maintained Playwright wrapper. | None; keep current `SKILL.md` command examples. | None; retain `skills/tools/browser/playwright/tests/test_tools_browser_playwright.py`. | None; retain `tests/script_specs/skills/tools/browser/playwright/scripts/playwright_cli.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/devex/desktop-notify/SKILL.md` | `skills/tools/devex/desktop-notify/scripts/desktop-notify.sh` | `ACTIVE` | `keep` | `skills/tools/devex/desktop-notify/scripts/desktop-notify.sh` | Direct notifier with the custom-title contract; `project-notify.sh` delegates to it, so removing it would change the documented two-entrypoint surface. | None; keep current `SKILL.md` entrypoint list. | None; retain `skills/tools/devex/desktop-notify/tests/test_tools_devex_desktop_notify.py`. | None; retain `tests/script_specs/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/devex/desktop-notify/SKILL.md` | `skills/tools/devex/desktop-notify/scripts/project-notify.sh` | `ACTIVE` | `keep` | `skills/tools/devex/desktop-notify/scripts/project-notify.sh` | Preferred project-title wrapper is explicitly documented in `SKILL.md`; it serves a distinct caller contract from the lower-level notifier. | None; keep current `SKILL.md` entrypoint list. | None; retain `skills/tools/devex/desktop-notify/tests/test_tools_devex_desktop_notify.py`. | None; retain `tests/script_specs/skills/tools/devex/desktop-notify/scripts/project-notify.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/devex/open-changed-files-review/SKILL.md` | `skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh` | `ACTIVE` | `keep` | `skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh` | Only tracked entrypoint for this skill; the contract, tests, and smoke spec all point to the same maintained wrapper. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/tools/devex/open-changed-files-review/tests/test_tools_devex_open_changed_files_review.py`. | None; retain `tests/script_specs/skills/tools/devex/open-changed-files-review/scripts/open-changed-files.zsh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/macos-agent-ops/SKILL.md` | `skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh` | `ACTIVE` | `keep` | `skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh` | Only tracked entrypoint for this skill; current contract and test ownership keep it public even though the repo does not yet ship a smoke spec. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/tools/macos-agent-ops/tests/test_tools_macos_agent_ops.py`. | None; no checked-in spec at `tests/script_specs/skills/tools/macos-agent-ops/scripts/macos-agent-ops.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/media/screenshot/SKILL.md` | `skills/tools/media/screenshot/scripts/screenshot.sh` | `ACTIVE` | `keep` | `skills/tools/media/screenshot/scripts/screenshot.sh` | Only tracked entrypoint for this skill; the wrapper is documented and already covered by tests and a smoke spec. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/tools/media/screenshot/tests/test_screenshot.py`. | None; retain `tests/script_specs/skills/tools/media/screenshot/scripts/screenshot.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/skill-management/create-project-skill/SKILL.md` | `skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh` | `ACTIVE` | `keep` | `skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh` | Only tracked entrypoint for this skill; current contract and test ownership make it the maintained scaffold command despite no checked-in smoke spec yet. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/tools/skill-management/create-project-skill/tests/test_tools_skill_management_create_project_skill.py`. | None; no checked-in spec at `tests/script_specs/skills/tools/skill-management/create-project-skill/scripts/create_project_skill.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/skill-management/create-skill/SKILL.md` | `skills/tools/skill-management/create-skill/scripts/create_skill.sh` | `ACTIVE` | `keep` | `skills/tools/skill-management/create-skill/scripts/create_skill.sh` | Canonical scaffold command for the repo; the inventory and review checklist already treat it as the stable public entrypoint. | None; keep current `SKILL.md`, `docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md`, and `docs/plans/skills-inventory-audit.md` references aligned. | None; retain `skills/tools/skill-management/create-skill/tests/test_tools_skill_management_create_skill.py`. | None; retain `tests/script_specs/skills/tools/skill-management/create-skill/scripts/create_skill.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/skill-management/remove-skill/SKILL.md` | `skills/tools/skill-management/remove-skill/scripts/remove_skill.sh` | `ACTIVE` | `keep` | `skills/tools/skill-management/remove-skill/scripts/remove_skill.sh` | Only tracked entrypoint for this skill; the contract, tests, and smoke spec already define the maintained breaking-change workflow. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/tools/skill-management/remove-skill/tests/test_tools_skill_management_remove_skill.py`. | None; retain `tests/script_specs/skills/tools/skill-management/remove-skill/scripts/remove_skill.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/skill-management/skill-governance/SKILL.md` | `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh` | `ACTIVE` | `keep` | `skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh` | Distinct validator command explicitly listed in `SKILL.md` and the review checklist; no repo-local evidence says it should merge with the other validators. | None; keep current `SKILL.md`, `docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md`, and `docs/plans/skills-inventory-audit.md` references aligned. | None; retain `skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py`. | None; retain `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/skill-management/skill-governance/SKILL.md` | `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` | `ACTIVE` | `keep` | `skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh` | Distinct validator command explicitly listed in `SKILL.md` and the review checklist; keeping it preserves the documented contract check surface even though no smoke spec is checked in yet. | None; keep current `SKILL.md`, `docs/runbooks/skills/SKILL_REVIEW_CHECKLIST.md`, and `docs/plans/skills-inventory-audit.md` references aligned. | None; retain `skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py`. | None; no checked-in spec at `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/skill-management/skill-governance/SKILL.md` | `skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh` | `ACTIVE` | `keep` | `skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh` | Placeholder validator is still part of the documented public surface; removing it before a replacement exists would break the current three-command contract. | None; keep current `SKILL.md` script list. | None; retain `skills/tools/skill-management/skill-governance/tests/test_tools_skill_management_skill_governance.py`. | None; retain `tests/script_specs/skills/tools/skill-management/skill-governance/scripts/validate_skill_paths.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/sql/sql-mssql/SKILL.md` | `skills/tools/sql/sql-mssql/scripts/sql-mssql.sh` | `ACTIVE` | `keep` | `skills/tools/sql/sql-mssql/scripts/sql-mssql.sh` | Only tracked entrypoint for this skill; the current contract, tests, and smoke spec define it as the supported SQL Server wrapper. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/tools/sql/sql-mssql/tests/test_tools_sql_sql_mssql.py`. | None; retain `tests/script_specs/skills/tools/sql/sql-mssql/scripts/sql-mssql.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/sql/sql-mysql/SKILL.md` | `skills/tools/sql/sql-mysql/scripts/sql-mysql.sh` | `ACTIVE` | `keep` | `skills/tools/sql/sql-mysql/scripts/sql-mysql.sh` | Only tracked entrypoint for this skill; the current contract, tests, and smoke spec define it as the supported MySQL wrapper. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/tools/sql/sql-mysql/tests/test_tools_sql_sql_mysql.py`. | None; retain `tests/script_specs/skills/tools/sql/sql-mysql/scripts/sql-mysql.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/tools/sql/sql-postgres/SKILL.md` | `skills/tools/sql/sql-postgres/scripts/sql-postgres.sh` | `ACTIVE` | `keep` | `skills/tools/sql/sql-postgres/scripts/sql-postgres.sh` | Only tracked entrypoint for this skill; the current contract, tests, and smoke spec define it as the supported PostgreSQL wrapper. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/tools/sql/sql-postgres/tests/test_tools_sql_sql_postgres.py`. | None; retain `tests/script_specs/skills/tools/sql/sql-postgres/scripts/sql-postgres.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/workflows/issue/issue-lifecycle/SKILL.md` | `skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh` | `ACTIVE` | `keep` | `skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh` | Only tracked entrypoint for this skill; the current contract, tests, and smoke spec define the maintained issue-lifecycle command. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/workflows/issue/issue-lifecycle/tests/test_workflows_issue_issue_lifecycle.py`. | None; retain `tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/workflows/issue/issue-pr-review/SKILL.md` | `skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh` | `ACTIVE` | `keep` | `skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh` | Only tracked entrypoint for this skill; the current contract, tests, and smoke spec define the maintained review command. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/workflows/issue/issue-pr-review/tests/test_workflows_issue_issue_pr_review.py`. | None; retain `tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/workflows/plan/docs-plan-cleanup/SKILL.md` | `skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh` | `ACTIVE` | `keep` | `skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh` | Only tracked entrypoint for this skill; the current contract and tests still make it public even though the repo does not yet ship a smoke spec. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/workflows/plan/docs-plan-cleanup/tests/test_workflows_plan_docs_plan_cleanup.py`. | None; no checked-in spec at `tests/script_specs/skills/workflows/plan/docs-plan-cleanup/scripts/docs-plan-cleanup.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/workflows/pr/bug/close-bug-pr/SKILL.md` | `skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh` | `ACTIVE` | `keep` | `skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh` | Only tracked entrypoint for this skill; the current contract and tests define the maintained close-PR workflow despite no checked-in smoke spec. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/workflows/pr/bug/close-bug-pr/tests/test_workflows_pr_bug_close_bug_pr.py`. | None; no checked-in spec at `tests/script_specs/skills/workflows/pr/bug/close-bug-pr/scripts/close_bug_pr.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/workflows/pr/bug/create-bug-pr/SKILL.md` | `skills/workflows/pr/bug/create-bug-pr/scripts/render_bug_pr.sh` | `ACTIVE` | `keep` | `skills/workflows/pr/bug/create-bug-pr/scripts/render_bug_pr.sh` | Only tracked entrypoint for this skill; the current contract, tests, and smoke spec define the maintained PR-rendering command. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/workflows/pr/bug/create-bug-pr/tests/test_workflows_pr_bug_create_bug_pr.py`. | None; retain `tests/script_specs/skills/workflows/pr/bug/create-bug-pr/scripts/render_bug_pr.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/workflows/pr/bug/deliver-bug-pr/SKILL.md` | `skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh` | `ACTIVE` | `keep` | `skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh` | Only tracked entrypoint for this skill; the current contract and preflight tests still make it public even though the repo does not yet ship a smoke spec. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/workflows/pr/bug/deliver-bug-pr/tests/test_workflows_pr_bug_deliver_bug_pr.py` and `skills/workflows/pr/bug/deliver-bug-pr/tests/test_workflows_pr_bug_deliver_bug_pr_preflight.py`. | None; no checked-in spec at `tests/script_specs/skills/workflows/pr/bug/deliver-bug-pr/scripts/deliver-bug-pr.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/workflows/pr/feature/close-feature-pr/SKILL.md` | `skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh` | `ACTIVE` | `keep` | `skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh` | Only tracked entrypoint for this skill; the current contract and tests define the maintained close-PR workflow despite no checked-in smoke spec. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/workflows/pr/feature/close-feature-pr/tests/test_workflows_pr_feature_close_feature_pr.py`. | None; no checked-in spec at `tests/script_specs/skills/workflows/pr/feature/close-feature-pr/scripts/close_feature_pr.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/workflows/pr/feature/create-feature-pr/SKILL.md` | `skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh` | `ACTIVE` | `keep` | `skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh` | Only tracked entrypoint for this skill; the current contract, tests, and smoke spec define the maintained PR-rendering command. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/workflows/pr/feature/create-feature-pr/tests/test_workflows_pr_feature_create_feature_pr.py`. | None; retain `tests/script_specs/skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh.json`. | None. | No caller change; entrypoint remains supported. | +| `skills/workflows/pr/feature/deliver-feature-pr/SKILL.md` | `skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh` | `ACTIVE` | `keep` | `skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh` | Only tracked entrypoint for this skill; the current contract and preflight tests still make it public even though the repo does not yet ship a smoke spec. | None; keep current `SKILL.md` entrypoint reference. | None; retain `skills/workflows/pr/feature/deliver-feature-pr/tests/test_workflows_pr_feature_deliver_feature_pr.py` and `skills/workflows/pr/feature/deliver-feature-pr/tests/test_workflows_pr_feature_deliver_feature_pr_preflight.py`. | None; no checked-in spec at `tests/script_specs/skills/workflows/pr/feature/deliver-feature-pr/scripts/deliver-feature-pr.sh.json`. | None. | No caller change; entrypoint remains supported. | From 41138575b99d2f70773a66e16fd95143499126e1 Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Wed, 4 Mar 2026 06:27:50 +0800 Subject: [PATCH 4/9] refactor(workflows): normalize issue workflow entrypoint docs and smoke specs --- DEVELOPMENT.md | 3 ++ README.md | 4 ++- docs/testing/script-regression.md | 3 ++ docs/testing/script-smoke.md | 10 +++++++ skills/README.md | 10 +++++++ .../scripts/manage_issue_lifecycle.sh | 6 ++++ .../scripts/manage_issue_pr_review.sh | 6 ++++ .../plan/create-plan-rigorous/SKILL.md | 4 +++ skills/workflows/plan/create-plan/SKILL.md | 4 +++ .../pr/feature/create-feature-pr/SKILL.md | 4 +++ ..._workflows_pr_feature_create_feature_pr.py | 6 ++++ .../scripts/manage_issue_lifecycle.sh.json | 11 ++++++++ .../scripts/manage_issue_pr_review.sh.json | 11 ++++++++ tests/test_script_smoke_gh_workflows.py | 28 +++++++++++++++++++ 14 files changed, 109 insertions(+), 1 deletion(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index b3768b6b..8dac069e 100644 --- a/DEVELOPMENT.md +++ b/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 diff --git a/README.md b/README.md index 018f4f43..eff61080 100644 --- a/README.md +++ b/README.md @@ -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 | @@ -156,6 +156,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 diff --git a/docs/testing/script-regression.md b/docs/testing/script-regression.md index f5ab70e5..b7d447c9 100644 --- a/docs/testing/script-regression.md +++ b/docs/testing/script-regression.md @@ -70,6 +70,9 @@ $AGENT_HOME/scripts/test.sh -m script_smoke - `scripts/check.sh --docs` - CI parity guardrail: - `scripts/check.sh --tests -- -k parity -m script_regression` +- Skill entrypoint drift guard (required when entrypoint scripts or smoke specs change): + - `bash scripts/ci/stale-skill-scripts-audit.sh --check` + - `scripts/check.sh --entrypoint-ownership` ## Script smoke tests diff --git a/docs/testing/script-smoke.md b/docs/testing/script-smoke.md index db8f97c2..193b21d5 100644 --- a/docs/testing/script-smoke.md +++ b/docs/testing/script-smoke.md @@ -20,6 +20,13 @@ Or via consolidated check wrapper: scripts/check.sh --tests -- -m script_smoke ``` +When entrypoints are added/removed/renamed, run companion ownership checks: + +```bash +bash scripts/ci/stale-skill-scripts-audit.sh --check +scripts/check.sh --entrypoint-ownership +``` + ## What it does - Runs selected script entrypoints through deeper smoke cases (beyond `--help`). @@ -30,6 +37,9 @@ scripts/check.sh --tests -- -m script_smoke - `tests/script_specs/scripts/check.sh.json` - `tests/script_specs/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh.json` - `tests/script_specs/skills/tools/devex/desktop-notify/scripts/project-notify.sh.json` +- Retained issue-workflow smoke specs: + - `tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json` + - `tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json` - Removed desktop-notify wrappers (for example `codex-notify.sh`) should not keep stale smoke specs. - Writes evidence (untracked) under: - `out/tests/script-smoke/summary.json` diff --git a/skills/README.md b/skills/README.md index cb9eb357..72a77861 100644 --- a/skills/README.md +++ b/skills/README.md @@ -54,3 +54,13 @@ See `../docs/runbooks/skills/SKILLS_ANATOMY_V2.md` for the full directory anatom - Skill directories use kebab-case (e.g., `create-feature-pr`). - `_shared` is reserved for shared, non-skill content only. - Avoid uppercase or spaces in directory names. + +## Entrypoint Drift Guard (Quick Run) + +When adding/removing/renaming workflow or tool entrypoints, run both checks in +the same change: + +```bash +bash scripts/ci/stale-skill-scripts-audit.sh --check +scripts/check.sh --entrypoint-ownership +``` diff --git a/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh b/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh index 2079915f..b3e27dc9 100755 --- a/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh +++ b/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh @@ -42,6 +42,12 @@ usage() { Usage: manage_issue_lifecycle.sh [options] +Canonical entrypoint: + $AGENT_HOME/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh + +Simplification note: + Legacy wrappers were removed; use this entrypoint directly. + Subcommands: open Create a new issue owned by the main agent update Update title/body/labels/assignees/projects for an issue diff --git a/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh b/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh index df706f97..18899530 100755 --- a/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh +++ b/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh @@ -33,6 +33,12 @@ usage() { Usage: manage_issue_pr_review.sh [options] +Canonical entrypoint: + $AGENT_HOME/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh + +Simplification note: + Legacy wrappers were removed; use this entrypoint directly. + Subcommands: request-followup Main agent comments on PR and mirrors explicit comment URL to issue merge Merge PR and optionally close issue diff --git a/skills/workflows/plan/create-plan-rigorous/SKILL.md b/skills/workflows/plan/create-plan-rigorous/SKILL.md index 90c161c4..74fc08c6 100644 --- a/skills/workflows/plan/create-plan-rigorous/SKILL.md +++ b/skills/workflows/plan/create-plan-rigorous/SKILL.md @@ -39,6 +39,10 @@ Failure modes: - Plan requires repo access/info you can’t obtain. - Subagent review yields conflicting guidance; reconcile and document the decision. +## Entrypoint + +- None. This is a workflow-only skill with no `scripts/` entrypoint. + ## Workflow 1. Clarify (if needed) diff --git a/skills/workflows/plan/create-plan/SKILL.md b/skills/workflows/plan/create-plan/SKILL.md index 952776f1..19fc00f7 100644 --- a/skills/workflows/plan/create-plan/SKILL.md +++ b/skills/workflows/plan/create-plan/SKILL.md @@ -37,6 +37,10 @@ Failure modes: - Request remains underspecified and the user won’t confirm assumptions. - Plan requires access/info the user cannot provide (credentials, private APIs, etc.). +## Entrypoint + +- None. This is a workflow-only skill with no `scripts/` entrypoint. + ## Workflow 1. Decide whether you must ask questions first diff --git a/skills/workflows/pr/feature/create-feature-pr/SKILL.md b/skills/workflows/pr/feature/create-feature-pr/SKILL.md index 35564295..7d58f143 100644 --- a/skills/workflows/pr/feature/create-feature-pr/SKILL.md +++ b/skills/workflows/pr/feature/create-feature-pr/SKILL.md @@ -39,6 +39,10 @@ Failure modes: - PR title/body follows a housekeeping commit subject (for example `Add plan file`) instead of the feature outcome. - PR body missing required sections. +## Entrypoint + +- `$AGENT_HOME/skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh` + ## Preflight (mandatory) 1. Confirm runtime intent: diff --git a/skills/workflows/pr/feature/create-feature-pr/tests/test_workflows_pr_feature_create_feature_pr.py b/skills/workflows/pr/feature/create-feature-pr/tests/test_workflows_pr_feature_create_feature_pr.py index 721ddf07..d0ebe6f8 100644 --- a/skills/workflows/pr/feature/create-feature-pr/tests/test_workflows_pr_feature_create_feature_pr.py +++ b/skills/workflows/pr/feature/create-feature-pr/tests/test_workflows_pr_feature_create_feature_pr.py @@ -71,6 +71,12 @@ def test_create_feature_pr_skill_opens_draft_pr_by_default() -> None: assert "Open draft PRs by default; only open non-draft when the user explicitly requests it." in text +def test_create_feature_pr_skill_declares_canonical_entrypoint() -> None: + text = _skill_md_text() + assert "## Entrypoint" in text + assert "`$AGENT_HOME/skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh`" in text + + def test_create_feature_pr_skill_pr_template_flow_is_simple() -> None: text = _skill_md_text() assert "Use `$AGENT_HOME/skills/workflows/pr/feature/create-feature-pr/scripts/render_feature_pr.sh --pr`" in text diff --git a/tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json b/tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json index df02efa1..0bc2c8c7 100644 --- a/tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json +++ b/tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json @@ -1,5 +1,16 @@ { "smoke": [ + { + "name": "help-surface", + "args": [ + "--help" + ], + "timeout_sec": 10, + "expect": { + "exit_codes": [0], + "stdout_regex": "manage_issue_lifecycle\\.sh " + } + }, { "name": "open-dry-run", "args": [ diff --git a/tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json b/tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json index d8d17f15..d604d699 100644 --- a/tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json +++ b/tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json @@ -1,5 +1,16 @@ { "smoke": [ + { + "name": "help-surface", + "args": [ + "--help" + ], + "timeout_sec": 10, + "expect": { + "exit_codes": [0], + "stdout_regex": "manage_issue_pr_review\\.sh " + } + }, { "name": "request-followup-dry-run", "args": [ diff --git a/tests/test_script_smoke_gh_workflows.py b/tests/test_script_smoke_gh_workflows.py index b737a10e..f2154abb 100644 --- a/tests/test_script_smoke_gh_workflows.py +++ b/tests/test_script_smoke_gh_workflows.py @@ -1,5 +1,6 @@ from __future__ import annotations +import json import subprocess from pathlib import Path @@ -40,6 +41,33 @@ def init_fixture_repo(tmp_path: Path, *, default_branch: str = "main") -> tuple[ return (work_tree, origin) +@pytest.mark.script_smoke +def test_script_smoke_issue_workflow_specs_match_retained_entrypoints() -> None: + repo = repo_root() + expected_specs = [ + "tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json", + "tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json", + ] + discovered_specs = sorted( + str(path.relative_to(repo)) + for path in (repo / "tests" / "script_specs" / "skills" / "workflows" / "issue").rglob("manage_issue_*.sh.json") + ) + assert discovered_specs == expected_specs + + expected_scripts = [ + "skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh", + "skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh", + ] + for script_path in expected_scripts: + assert (repo / script_path).is_file(), script_path + + for spec_path in expected_specs: + payload = json.loads((repo / spec_path).read_text("utf-8")) + smoke_cases = payload.get("smoke", []) + names = {case.get("name") for case in smoke_cases if isinstance(case, dict)} + assert "help-surface" in names, spec_path + + @pytest.mark.script_smoke def test_script_smoke_fixture_close_feature_pr(tmp_path: Path): work_tree, _ = init_fixture_repo(tmp_path) From 0e832232816c6e8ffc95d398566a6629b167c58b Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Wed, 4 Mar 2026 06:29:10 +0800 Subject: [PATCH 5/9] chore(skills): normalize tool entrypoint references and trim stale fixtures - Normalize Playwright and API test runner contract entrypoint guidance. - Tighten create-skill reference assertions and desktop notify level handling. - Simplify audit smoke coverage and remove obsolete api-test-runner fixtures. --- skills/tools/browser/playwright/SKILL.md | 2 +- .../desktop-notify/scripts/desktop-notify.sh | 25 ++++++++------- .../skill-management/create-skill/SKILL.md | 1 + ...est_tools_skill_management_create_skill.py | 10 ++++++ .../scripts/audit-skill-layout.sh | 2 +- skills/tools/testing/api-test-runner/SKILL.md | 7 ++++ .../api-test-runner/fixture.results.json | 32 ------------------- .../api-test-runner/fixture.suite.json | 28 ---------------- .../scripts/desktop-notify.sh.json | 2 +- .../scripts/audit-skill-layout.sh.json | 9 ++++-- 10 files changed, 42 insertions(+), 76 deletions(-) delete mode 100644 tests/fixtures/api-test-runner/fixture.results.json delete mode 100644 tests/fixtures/api-test-runner/fixture.suite.json diff --git a/skills/tools/browser/playwright/SKILL.md b/skills/tools/browser/playwright/SKILL.md index c9154603..75092a61 100644 --- a/skills/tools/browser/playwright/SKILL.md +++ b/skills/tools/browser/playwright/SKILL.md @@ -47,7 +47,7 @@ Failure modes: ## Scripts (only entrypoints) -- `scripts/playwright_cli.sh` +- `$AGENT_HOME/skills/tools/browser/playwright/scripts/playwright_cli.sh` ## Usage diff --git a/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh b/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh index 54728592..fd336a9e 100755 --- a/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh +++ b/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh @@ -20,7 +20,7 @@ to_lower() { usage() { cat >&2 <<'EOF' Usage: - desktop-notify.sh --title --message <message> [--level <info|success|warn|error>] + desktop-notify.sh --title <title> --message <message> [--level <info|success|warn|warning|error>] Behavior: - macOS: uses terminal-notifier (if installed) @@ -38,6 +38,13 @@ Install hints: EOF } +normalize_level() { + case "$1" in + warning) printf "warn" ;; + *) printf "%s" "$1" ;; + esac +} + bool_from_env() { local raw="${1:-}" local name="${2:-}" @@ -86,7 +93,7 @@ while [[ $# -gt 0 ]]; do shift 2 ;; --level) - level="$(to_lower "$(trim "${2:-}")")" + level="$(normalize_level "$(to_lower "$(trim "${2:-}")")")" [[ -n "$level" ]] || die "Missing value for --level" shift 2 ;; @@ -104,10 +111,10 @@ done [[ -n "$message" ]] || die "Missing --message" case "$level" in - info|success|warn|warning|error) + info|success|warn|error) ;; *) - die "Invalid --level: $level (expected info|success|warn|error)" + die "Invalid --level: $level (expected info|success|warn|warning|error)" ;; esac @@ -119,9 +126,7 @@ os="$(uname -s 2>/dev/null || true)" if [[ "$os" == "Darwin" ]]; then if command -v terminal-notifier >/dev/null 2>&1; then - if terminal-notifier -title "$title" -message "$message" >/dev/null 2>&1; then - exit 0 - fi + terminal-notifier -title "$title" -message "$message" >/dev/null 2>&1 || true exit 0 fi @@ -138,14 +143,12 @@ if [[ "$os" == "Linux" ]]; then error) urgency="critical" ;; - warn|warning) + warn) urgency="normal" ;; esac - if notify-send -u "$urgency" "$title" "$message" >/dev/null 2>&1; then - exit 0 - fi + notify-send -u "$urgency" "$title" "$message" >/dev/null 2>&1 || true exit 0 fi diff --git a/skills/tools/skill-management/create-skill/SKILL.md b/skills/tools/skill-management/create-skill/SKILL.md index 64bbb86c..2657159a 100644 --- a/skills/tools/skill-management/create-skill/SKILL.md +++ b/skills/tools/skill-management/create-skill/SKILL.md @@ -46,6 +46,7 @@ Failure modes: ## Scripts (only entrypoints) - `$AGENT_HOME/skills/tools/skill-management/create-skill/scripts/create_skill.sh` +- Legacy wrapper paths are not supported; keep docs and callers pinned to this script. ## Related docs diff --git a/skills/tools/skill-management/create-skill/tests/test_tools_skill_management_create_skill.py b/skills/tools/skill-management/create-skill/tests/test_tools_skill_management_create_skill.py index b12fbbd8..90345659 100644 --- a/skills/tools/skill-management/create-skill/tests/test_tools_skill_management_create_skill.py +++ b/skills/tools/skill-management/create-skill/tests/test_tools_skill_management_create_skill.py @@ -19,6 +19,16 @@ def test_tools_skill_management_create_skill_entrypoints_exist() -> None: assert_entrypoints_exist(skill_root, ["scripts/create_skill.sh"]) +def test_create_skill_contract_references_current_entrypoints() -> None: + skill_md = Path(__file__).resolve().parents[1] / "SKILL.md" + text = skill_md.read_text(encoding="utf-8") + + assert "$AGENT_HOME/skills/tools/skill-management/create-skill/scripts/create_skill.sh" in text + assert "$AGENT_HOME/skills/tools/skill-management/skill-governance/scripts/validate_skill_contracts.sh" in text + assert "$AGENT_HOME/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh" in text + assert "legacy wrapper paths are not supported" in text.lower() + + def test_create_skill_generates_contract_first_skill_md() -> None: root = repo_root() create_script = ( diff --git a/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh b/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh index aab35d0f..30ce98e2 100755 --- a/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh +++ b/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh @@ -4,7 +4,7 @@ set -euo pipefail usage() { cat <<'USAGE' Usage: - $AGENT_HOME/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh [--skill-dir <path>] [--help] + audit-skill-layout.sh [--skill-dir <path>] [--help] Validates that each tracked skill directory contains only the allowed top-level entries: diff --git a/skills/tools/testing/api-test-runner/SKILL.md b/skills/tools/testing/api-test-runner/SKILL.md index 54b251ff..992b8390 100644 --- a/skills/tools/testing/api-test-runner/SKILL.md +++ b/skills/tools/testing/api-test-runner/SKILL.md @@ -38,6 +38,13 @@ Failure modes: - Missing/invalid suite or case files (JSON schema errors, missing request/op files). - Auth missing/invalid (401/403) or write-capable case blocked by safety defaults. +## Entrypoints + +- External CLI commands only: + - `api-test run` + - `api-test summary` +- This skill intentionally has no repo-local `scripts/` entrypoint. + ## Goal Run a suite of API checks in CI (and locally) via a single manifest file, reusing existing callers: diff --git a/tests/fixtures/api-test-runner/fixture.results.json b/tests/fixtures/api-test-runner/fixture.results.json deleted file mode 100644 index d3bc45ba..00000000 --- a/tests/fixtures/api-test-runner/fixture.results.json +++ /dev/null @@ -1,32 +0,0 @@ -{ - "suite": "fixture", - "runId": "fixture-run", - "suiteFile": "setup/api-test-suites/fixture.yml", - "outputDir": "out/api-test-runner", - "startedAt": "2026-01-01T00:00:00Z", - "finishedAt": "2026-01-01T00:00:01Z", - "summary": { - "total": 2, - "passed": 1, - "failed": 0, - "skipped": 1 - }, - "cases": [ - { - "id": "rest:ping", - "type": "rest", - "status": "passed", - "durationMs": 10, - "message": "", - "stdoutFile": "out/tests/script-smoke/api-test-summary/rest-ping.stdout.txt", - "stderrFile": "out/tests/script-smoke/api-test-summary/rest-ping.stderr.txt" - }, - { - "id": "graphql:skip", - "type": "graphql", - "status": "skipped", - "durationMs": 0, - "message": "skipped in fixture" - } - ] -} diff --git a/tests/fixtures/api-test-runner/fixture.suite.json b/tests/fixtures/api-test-runner/fixture.suite.json deleted file mode 100644 index 290f3c14..00000000 --- a/tests/fixtures/api-test-runner/fixture.suite.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "version": 1, - "name": "Fixture suite", - "defaults": { - "noHistory": true, - "rest": { - "configDir": "tests/fixtures/rest", - "url": "https://example.test" - }, - "graphql": { - "configDir": "tests/fixtures/graphql", - "url": "https://example.test/graphql" - } - }, - "cases": [ - { - "id": "rest-ping", - "type": "rest", - "request": "tests/fixtures/rest/ping.request.json" - }, - { - "id": "gql-ping", - "type": "graphql", - "op": "tests/fixtures/graphql/ping.graphql" - } - ] -} - diff --git a/tests/script_specs/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh.json b/tests/script_specs/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh.json index 52bebe62..a673bbba 100644 --- a/tests/script_specs/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh.json +++ b/tests/script_specs/skills/tools/devex/desktop-notify/scripts/desktop-notify.sh.json @@ -7,7 +7,7 @@ "smoke": [ { "name": "backend-invoked", - "args": ["--title", "codex", "--message", "smoke", "--level", "info"], + "args": ["--title", "codex", "--message", "smoke", "--level", "warning"], "env": { "CODEX_STUB_LOG_DIR": "out/tests/script-smoke/stubs/desktop-notify/backend-invoked" }, diff --git a/tests/script_specs/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh.json b/tests/script_specs/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh.json index 753781fa..15cabf2c 100644 --- a/tests/script_specs/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh.json +++ b/tests/script_specs/skills/tools/skill-management/skill-governance/scripts/audit-skill-layout.sh.json @@ -1,8 +1,13 @@ { + "args": ["--help"], + "timeout_sec": 10, + "expect": { + "exit_codes": [0] + }, "smoke": [ { - "name": "default", - "args": [], + "name": "skill-dir", + "args": ["--skill-dir", "skills/tools/skill-management/skill-governance"], "timeout_sec": 10, "expect": { "exit_codes": [0] From 6480aa9373bc44d46354f2e4abd82e0f6eaa3ef1 Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Wed, 4 Mar 2026 06:50:14 +0800 Subject: [PATCH 6/9] docs(automation): normalize shared entrypoint boundaries and migration notes --- README.md | 6 ++++++ docs/testing/script-regression.md | 6 ++++++ docs/testing/script-smoke.md | 5 +++++ skills/automation/README.md | 13 ++++++++++--- skills/automation/_libs/README.md | 2 ++ skills/automation/plan-issue-delivery/SKILL.md | 6 ++++++ skills/automation/release-workflow/SKILL.md | 16 ++++++++++++++++ 7 files changed, 51 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index eff61080..a485c650 100644 --- a/README.md +++ b/README.md @@ -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: diff --git a/docs/testing/script-regression.md b/docs/testing/script-regression.md index b7d447c9..e0a5e31d 100644 --- a/docs/testing/script-regression.md +++ b/docs/testing/script-regression.md @@ -73,6 +73,12 @@ $AGENT_HOME/scripts/test.sh -m script_smoke - Skill entrypoint drift guard (required when entrypoint scripts or smoke specs change): - `bash scripts/ci/stale-skill-scripts-audit.sh --check` - `scripts/check.sh --entrypoint-ownership` +- Release-workflow migration guard: + - deprecated helpers removed in PR #221 must stay removed (`audit-changelog.zsh`, `release-audit.sh`, + `release-find-guide.sh`, `release-notes-from-changelog.sh`, `release-scaffold-entry.sh`) + - replace old release helper usage with: + - `$AGENT_HOME/skills/automation/release-workflow/scripts/release-resolve.sh --repo .` + - `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` ## Script smoke tests diff --git a/docs/testing/script-smoke.md b/docs/testing/script-smoke.md index 193b21d5..9f9a1ff1 100644 --- a/docs/testing/script-smoke.md +++ b/docs/testing/script-smoke.md @@ -41,6 +41,11 @@ scripts/check.sh --entrypoint-ownership - `tests/script_specs/skills/workflows/issue/issue-lifecycle/scripts/manage_issue_lifecycle.sh.json` - `tests/script_specs/skills/workflows/issue/issue-pr-review/scripts/manage_issue_pr_review.sh.json` - Removed desktop-notify wrappers (for example `codex-notify.sh`) should not keep stale smoke specs. +- Deprecated release-workflow helper entrypoints removed in PR #221 (`audit-changelog.zsh`, `release-audit.sh`, + `release-find-guide.sh`, `release-notes-from-changelog.sh`, `release-scaffold-entry.sh`) should not keep stale smoke specs. + Keep smoke coverage on retained entrypoints only: + - `tests/script_specs/skills/automation/release-workflow/scripts/release-resolve.sh.json` + - `tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json` - Writes evidence (untracked) under: - `out/tests/script-smoke/summary.json` - `out/tests/script-smoke/logs/**` diff --git a/skills/automation/README.md b/skills/automation/README.md index c142eb02..ffb67ce6 100644 --- a/skills/automation/README.md +++ b/skills/automation/README.md @@ -8,7 +8,7 @@ Prefer the review-first variants when the user wants to stage a subset of change - Build automation on proven base skills: validate the workflow first, then wrap it as automation. - Reuse base skill scripts as the canonical implementation; do not copy stable entrypoints into each automation skill. -- Add glue only when needed (autostage, retries, batching). Keep glue thin and prefer shared primitives over per-skill wrappers. +- Add glue only when needed (autostage, retries, batching). Keep glue thin and prefer shared primitives over duplicated wrappers. - Keep test growth flat: adding a new automation workflow should rarely add new executable scripts. ## Shared automation libs @@ -19,6 +19,13 @@ Guidelines: - `_libs/` is for sourceable libraries and non-entrypoint code (no shebang; not executable). - Keep executable entrypoints in a skill’s `scripts/` only when necessary. -- Prefer `skills/automation/<primitive>/` as a shared primitive (others reference it) over duplicating wrappers. +- Prefer `skills/automation/<primitive>/` as a shared primitive (others reference it) over copying wrapper scripts into each automation skill. - Prefer shared CLI primitives on PATH (install via `brew install nils-cli`; provides `plan-tooling`, `api-*`, `semantic-commit`) for - deterministic project file/folder discovery; keep per-skill `<skill>-resolve.sh` wrappers in each skill’s `scripts/`. + deterministic project file/folder discovery; do not add per-skill `*-resolve.sh` wrappers when the shared primitive already exists. + +## Migration notes + +- Deprecated pattern: per-skill `*-resolve.sh` wrapper scripts that only re-route to the same shared CLI primitive. +- Replace with direct shared primitive usage: + - automation primitive scripts under `skills/automation/<primitive>/scripts/` + - shared CLI commands on PATH (`plan-issue`, `plan-tooling`, `semantic-commit`, `api-*`) diff --git a/skills/automation/_libs/README.md b/skills/automation/_libs/README.md index d3b14c8d..5e09ecb1 100644 --- a/skills/automation/_libs/README.md +++ b/skills/automation/_libs/README.md @@ -6,6 +6,7 @@ Conventions: - Keep libraries **non-executable** (no shebang) so they are not treated as script entrypoints. - Avoid creating a `scripts/` directory under `_libs/` (repo tests treat `skills/**/scripts/**` as entrypoints). +- Do not place user-facing wrapper entrypoints in `_libs/`; shared libraries stay internal to retained entrypoints. - Suggested layout (create only what you use): - `skills/automation/_libs/zsh/*.zsh` for zsh helpers (source from `zsh -f` scripts) - `skills/automation/_libs/sh/*.sh` for POSIX shell helpers @@ -15,3 +16,4 @@ Rule of thumb: - If it must be invoked directly: put it under a specific skill’s `scripts/` (entrypoint). - If it’s shared logic: put it here and source/import it from the entrypoint. +- If multiple skills need the same direct command surface: keep one shared primitive skill entrypoint and import shared code from `_libs/`. diff --git a/skills/automation/plan-issue-delivery/SKILL.md b/skills/automation/plan-issue-delivery/SKILL.md index e2ce1747..16aeddbd 100644 --- a/skills/automation/plan-issue-delivery/SKILL.md +++ b/skills/automation/plan-issue-delivery/SKILL.md @@ -248,6 +248,12 @@ Failure modes: - `plan-issue` (live GitHub orchestration) +## Entrypoint boundary + +- This skill intentionally keeps no repo-local wrapper script for `plan-issue`. +- Keep `plan-issue` as the shared primitive on PATH; do not add duplicate `plan-issue-*` wrappers under `skills/automation/`. +- Shared reusable logic belongs in shared references or automation libs, not new wrapper entrypoints. + ## References - Local rehearsal playbook (`plan-issue-local` and `plan-issue --dry-run`): `references/LOCAL_REHEARSAL.md` diff --git a/skills/automation/release-workflow/SKILL.md b/skills/automation/release-workflow/SKILL.md index 360c2021..5c28e828 100644 --- a/skills/automation/release-workflow/SKILL.md +++ b/skills/automation/release-workflow/SKILL.md @@ -72,6 +72,22 @@ Use only these public entrypoints: $AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version v1.3.2 ``` +## Migration notes (removed entrypoints) + +The release-workflow surface was simplified in PR #221. +The following entrypoints are deprecated and removed; migrate to the retained commands below. + +| Removed entrypoint | Replace with | +| --- | --- | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/audit-changelog.zsh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-audit.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-find-guide.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-resolve.sh --repo .` | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-notes-from-changelog.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-scaffold-entry.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | + +`release-resolve.sh` remains the guide-resolution entrypoint. +`release-publish-from-changelog.sh` remains the publish entrypoint. + ## Related docs - Reference notes for the single-entrypoint simplification shipped in PR #221: From 7d34365cff79f0857c19b417f1cf7c894d5cfcb4 Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Wed, 4 Mar 2026 07:15:27 +0800 Subject: [PATCH 7/9] chore(automation): normalize entrypoint contracts and smoke coverage - Add explicit entrypoint declarations for find-and-fix-bugs, issue-delivery, and release-workflow. - Add contract assertions to lock retained automation entrypoint references. - Tighten release and CI smoke spec guardrails and normalize help-surface case names. - Simplify gh-fix-ci shell entrypoint dispatch and refactor release publish command checks. --- skills/automation/find-and-fix-bugs/SKILL.md | 5 ++ .../test_automation_find_and_fix_bugs.py | 7 +++ .../automation/gh-fix-ci/scripts/gh-fix-ci.sh | 2 +- skills/automation/issue-delivery/SKILL.md | 5 ++ .../tests/test_automation_issue_delivery.py | 8 ++++ skills/automation/release-workflow/SKILL.md | 6 +++ .../scripts/release-publish-from-changelog.sh | 14 +++--- .../tests/test_automation_release_workflow.py | 8 ++++ .../gh-fix-ci/scripts/gh-fix-ci.sh.json | 2 +- .../release-publish-from-changelog.sh.json | 2 +- tests/test_script_smoke_release_workflow.py | 46 +++++++++++++++++++ 11 files changed, 95 insertions(+), 10 deletions(-) diff --git a/skills/automation/find-and-fix-bugs/SKILL.md b/skills/automation/find-and-fix-bugs/SKILL.md index e3d49e9a..f6407636 100644 --- a/skills/automation/find-and-fix-bugs/SKILL.md +++ b/skills/automation/find-and-fix-bugs/SKILL.md @@ -34,6 +34,11 @@ Failure modes: - High-risk changes (auth/billing/migrations) should halt or be skipped per guardrails. - Missing tooling (`rg`/`git`/`gh`) or insufficient repo permissions. +## Entrypoint + +- `$AGENT_HOME/skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh` +- Legacy wrapper paths are not supported; keep docs and callers pinned to this script. + ## Setup - Record the starting branch/ref (for return after PR creation): diff --git a/skills/automation/find-and-fix-bugs/tests/test_automation_find_and_fix_bugs.py b/skills/automation/find-and-fix-bugs/tests/test_automation_find_and_fix_bugs.py index 65a5a712..edb18191 100644 --- a/skills/automation/find-and-fix-bugs/tests/test_automation_find_and_fix_bugs.py +++ b/skills/automation/find-and-fix-bugs/tests/test_automation_find_and_fix_bugs.py @@ -18,3 +18,10 @@ def test_automation_find_and_fix_bugs_entrypoints_exist() -> None: "scripts/render_issues_pr.sh", ], ) + + +def test_automation_find_and_fix_bugs_declares_canonical_entrypoint() -> None: + text = (Path(__file__).resolve().parents[1] / "SKILL.md").read_text(encoding="utf-8") + assert "## Entrypoint" in text + assert "$AGENT_HOME/skills/automation/find-and-fix-bugs/scripts/render_issues_pr.sh" in text + assert "legacy wrapper paths are not supported" in text.lower() diff --git a/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh b/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh index 53b99abf..300b213d 100755 --- a/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh +++ b/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh @@ -26,4 +26,4 @@ if [[ ${1:-} == "-h" || ${1:-} == "--help" ]]; then fi script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -python3 "$script_dir/inspect_ci_checks.py" "$@" +exec python3 "$script_dir/inspect_ci_checks.py" "$@" diff --git a/skills/automation/issue-delivery/SKILL.md b/skills/automation/issue-delivery/SKILL.md index c5a2bb73..51cb70cd 100644 --- a/skills/automation/issue-delivery/SKILL.md +++ b/skills/automation/issue-delivery/SKILL.md @@ -69,6 +69,11 @@ Failure modes: `PLAN_SNAPSHOT_PATH`, `DISPATCH_RECORD_PATH`, plan task snippet/link/path). - Review or clarification follow-up is redirected into a replacement branch/worktree/PR without explicit task-lane reassignment. +## Entrypoint + +- None. This orchestration skill intentionally uses `plan-issue` command flows + and has no repo-local `scripts/` entrypoint. + ## Role Boundary (Mandatory) - Main-agent is limited to issue orchestration: diff --git a/skills/automation/issue-delivery/tests/test_automation_issue_delivery.py b/skills/automation/issue-delivery/tests/test_automation_issue_delivery.py index b934c9a1..24bf803f 100644 --- a/skills/automation/issue-delivery/tests/test_automation_issue_delivery.py +++ b/skills/automation/issue-delivery/tests/test_automation_issue_delivery.py @@ -60,6 +60,14 @@ def test_issue_delivery_skill_uses_shared_post_review_outcomes() -> None: assert "--close-reason" in text +def test_issue_delivery_skill_declares_scriptless_entrypoint() -> None: + skill_root = Path(__file__).resolve().parents[1] + text = (skill_root / "SKILL.md").read_text(encoding="utf-8") + assert "## Entrypoint" in text + assert "no repo-local `scripts/` entrypoint" in text + assert "plan-issue" in text + + def test_issue_delivery_skill_excludes_deleted_wrapper_script() -> None: skill_root = Path(__file__).resolve().parents[1] text = (skill_root / "SKILL.md").read_text(encoding="utf-8") diff --git a/skills/automation/release-workflow/SKILL.md b/skills/automation/release-workflow/SKILL.md index 360c2021..775819a7 100644 --- a/skills/automation/release-workflow/SKILL.md +++ b/skills/automation/release-workflow/SKILL.md @@ -60,6 +60,12 @@ The default fallback guide lives at: - `$AGENT_HOME/skills/automation/release-workflow/references/DEFAULT_RELEASE_GUIDE.md` +## Entrypoints (fallback helper scripts) + +- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-resolve.sh --repo .` +- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <vX.Y.Z>` +- Legacy wrapper paths are not supported; keep docs and callers pinned to these scripts. + ## Helper scripts (fallback) Use only these public entrypoints: diff --git a/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh b/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh index 981b47c1..0a5ac2c6 100755 --- a/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh +++ b/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh @@ -10,6 +10,10 @@ info() { echo "info: $1" >&2 } +require_cmd() { + command -v "$1" >/dev/null 2>&1 || die "$1 is required" +} + usage() { cat >&2 <<'EOF' Usage: @@ -26,6 +30,7 @@ Notes: - Default changelog: CHANGELOG.md - Default title: <version> - Default --if-exists: edit + - This script is the supported publish entrypoint for release-workflow. EOF } @@ -86,13 +91,8 @@ fi cd "$repo" || die "unable to cd: $repo" -if ! command -v gh >/dev/null 2>&1; then - die "gh is required" -fi - -if ! command -v awk >/dev/null 2>&1; then - die "awk is required" -fi +require_cmd gh +require_cmd awk if [[ ! -f "$changelog" ]]; then die "changelog not found: $changelog" fi diff --git a/skills/automation/release-workflow/tests/test_automation_release_workflow.py b/skills/automation/release-workflow/tests/test_automation_release_workflow.py index 8dd6fdb0..13d4685d 100644 --- a/skills/automation/release-workflow/tests/test_automation_release_workflow.py +++ b/skills/automation/release-workflow/tests/test_automation_release_workflow.py @@ -19,3 +19,11 @@ def test_automation_release_workflow_entrypoints_exist() -> None: "scripts/release-resolve.sh", ], ) + + +def test_automation_release_workflow_declares_retained_entrypoints() -> None: + text = (Path(__file__).resolve().parents[1] / "SKILL.md").read_text(encoding="utf-8") + assert "## Entrypoints (fallback helper scripts)" in text + assert "$AGENT_HOME/skills/automation/release-workflow/scripts/release-resolve.sh" in text + assert "$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh" in text + assert "legacy wrapper paths are not supported" in text.lower() diff --git a/tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json b/tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json index ebcebc24..a8f7cafb 100644 --- a/tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json +++ b/tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json @@ -1,7 +1,7 @@ { "smoke": [ { - "name": "help", + "name": "help-surface", "args": ["--help"], "timeout_sec": 5, "expect": { diff --git a/tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json b/tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json index d0290f23..5b8bf847 100644 --- a/tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json +++ b/tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json @@ -1,7 +1,7 @@ { "smoke": [ { - "name": "help", + "name": "help-surface", "args": ["--help"], "timeout_sec": 5, "expect": { diff --git a/tests/test_script_smoke_release_workflow.py b/tests/test_script_smoke_release_workflow.py index fd51c3a4..b5d892e0 100644 --- a/tests/test_script_smoke_release_workflow.py +++ b/tests/test_script_smoke_release_workflow.py @@ -1,5 +1,6 @@ from __future__ import annotations +import json import os from pathlib import Path @@ -15,6 +16,51 @@ def write_executable(path: Path, content: str) -> None: path.chmod(0o755) +@pytest.mark.script_smoke +def test_script_smoke_release_and_ci_specs_match_retained_entrypoints() -> None: + repo = repo_root() + + expected_specs = [ + "tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json", + "tests/script_specs/skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py.json", + "tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json", + "tests/script_specs/skills/automation/release-workflow/scripts/release-resolve.sh.json", + ] + spec_roots = [ + repo / "tests" / "script_specs" / "skills" / "automation" / "gh-fix-ci" / "scripts", + repo / "tests" / "script_specs" / "skills" / "automation" / "release-workflow" / "scripts", + ] + discovered_specs = sorted( + str(path.relative_to(repo)) + for root in spec_roots + for path in root.glob("*.json") + ) + assert discovered_specs == expected_specs + + expected_scripts = [ + "skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh", + "skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py", + "skills/automation/release-workflow/scripts/release-publish-from-changelog.sh", + "skills/automation/release-workflow/scripts/release-resolve.sh", + ] + for script_path in expected_scripts: + assert (repo / script_path).is_file(), script_path + + expected_case_names = { + "tests/script_specs/skills/automation/gh-fix-ci/scripts/gh-fix-ci.sh.json": {"help-surface"}, + "tests/script_specs/skills/automation/gh-fix-ci/scripts/inspect_ci_checks.py.json": {"help"}, + "tests/script_specs/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh.json": { + "help-surface" + }, + "tests/script_specs/skills/automation/release-workflow/scripts/release-resolve.sh.json": {"json-defaults"}, + } + for spec_path, expected_names in expected_case_names.items(): + payload = json.loads((repo / spec_path).read_text("utf-8")) + smoke_cases = payload.get("smoke", []) + names = {case.get("name") for case in smoke_cases if isinstance(case, dict)} + assert names == expected_names, spec_path + + @pytest.mark.script_smoke def test_script_smoke_release_publish_from_changelog(tmp_path: Path): work_dir = tmp_path / "release" From b8da53bbff7a374742914a780f7602297329fe99 Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Wed, 4 Mar 2026 07:31:28 +0800 Subject: [PATCH 8/9] docs: align skill-surface docs and outcomes --- CHANGELOG.md | 14 +++++++ README.md | 4 +- docs/plans/skills-review-final-outcomes.md | 37 +++++++++++++++++++ .../agent-docs/PROJECT_DEV_WORKFLOW.md | 3 ++ docs/testing/script-smoke.md | 2 +- 5 files changed, 57 insertions(+), 3 deletions(-) create mode 100644 docs/plans/skills-review-final-outcomes.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 1480a71a..99e13b88 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index a485c650..70e858b9 100644 --- a/README.md +++ b/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) ``` diff --git a/docs/plans/skills-review-final-outcomes.md b/docs/plans/skills-review-final-outcomes.md new file mode 100644 index 00000000..77fe9943 --- /dev/null +++ b/docs/plans/skills-review-final-outcomes.md @@ -0,0 +1,37 @@ +# Skills Review Final Outcomes + +## Final Outcomes + +- Repository-level docs now describe the canonical check surface (`scripts/check.sh` modes plus entrypoint drift guards) without legacy wrapper guidance. +- Runtime path examples for plan-issue cleanup now use the current `<owner__repo>` workspace slug convention. +- The retained skill entrypoint surface is documented and auditable through current `SKILL.md`, smoke specs, and regression checks. + +| Surface | Decision | Outcome | +| --- | --- | --- | +| `scripts/check.sh --all` | keep | Canonical full local validation gate for lint, docs freshness, contracts, and tests. | +| `bash scripts/ci/stale-skill-scripts-audit.sh --check` | keep | Required drift guard when workflow/tool entrypoints are added, removed, or renamed. | +| `scripts/check.sh --entrypoint-ownership` | keep | Required ownership gate for workflow/tool entrypoint references. | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-resolve.sh` | keep | Retained release-guide resolution entrypoint. | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh` | keep | Retained release publish entrypoint. | +| `$AGENT_HOME/skills/tools/devex/desktop-notify/scripts/codex-notify.sh` | remove | Legacy wrapper removed; notifier surface remains `desktop-notify.sh` and `project-notify.sh`. | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-audit.sh` | remove | Legacy release helper removed in favor of the consolidated publish entrypoint. | + +## Removed Entrypoints + +- `$AGENT_HOME/skills/tools/devex/desktop-notify/scripts/codex-notify.sh` +- `$AGENT_HOME/skills/automation/release-workflow/scripts/audit-changelog.zsh` +- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-audit.sh` +- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-find-guide.sh` +- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-notes-from-changelog.sh` +- `$AGENT_HOME/skills/automation/release-workflow/scripts/release-scaffold-entry.sh` + +## Migration Mapping + +| Old Entrypoint | Replacement | Notes | +| --- | --- | --- | +| `$AGENT_HOME/skills/tools/devex/desktop-notify/scripts/codex-notify.sh` | `$AGENT_HOME/skills/tools/devex/desktop-notify/scripts/project-notify.sh` | Use project-scoped title wrapper for notification publishing. | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/audit-changelog.zsh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | Audit behavior is folded into the consolidated publish command. | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-audit.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | Publish command handles changelog audit + release body verification. | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-find-guide.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-resolve.sh --repo .` | Guide/template resolution is now a single public entrypoint. | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-notes-from-changelog.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | Release note extraction now happens in the consolidated publish path. | +| `$AGENT_HOME/skills/automation/release-workflow/scripts/release-scaffold-entry.sh` | `$AGENT_HOME/skills/automation/release-workflow/scripts/release-publish-from-changelog.sh --repo . --version <tag>` | Scaffolding and publish path are unified under one release command. | diff --git a/docs/runbooks/agent-docs/PROJECT_DEV_WORKFLOW.md b/docs/runbooks/agent-docs/PROJECT_DEV_WORKFLOW.md index ef0b326d..56bc7096 100644 --- a/docs/runbooks/agent-docs/PROJECT_DEV_WORKFLOW.md +++ b/docs/runbooks/agent-docs/PROJECT_DEV_WORKFLOW.md @@ -17,6 +17,9 @@ - Canonical pre-commit gate: `scripts/check.sh --all` - Docs freshness gate (standalone): `scripts/check.sh --docs` - CI parity guard: `scripts/check.sh --tests -- -k parity -m script_regression` +- Skill entrypoint drift guard (when workflow/tool entrypoints change): + - `bash scripts/ci/stale-skill-scripts-audit.sh --check` + - `scripts/check.sh --entrypoint-ownership` Use `scripts/check.sh` modes for project-dev verification. Avoid reintroducing ad-hoc legacy script wrappers in docs/workflows. diff --git a/docs/testing/script-smoke.md b/docs/testing/script-smoke.md index 9f9a1ff1..c2050c51 100644 --- a/docs/testing/script-smoke.md +++ b/docs/testing/script-smoke.md @@ -66,7 +66,7 @@ Run the cleanup helper before declaring plan completion: ```bash scripts/check_plan_issue_worktree_cleanup.sh \ - "$AGENT_HOME/out/plan-issue-delivery/graysurf-agent-kit/issue-193/worktrees" + "$AGENT_HOME/out/plan-issue-delivery/graysurf__agent-kit/issue-193/worktrees" ``` Expected behavior: From ee1bd468483c10752dd1de0099b66228d4225455 Mon Sep 17 00:00:00 2001 From: graysurf <10785178+graysurf@users.noreply.github.com> Date: Wed, 4 Mar 2026 07:35:04 +0800 Subject: [PATCH 9/9] docs: fix final outcomes markdown line length --- docs/plans/skills-review-final-outcomes.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/plans/skills-review-final-outcomes.md b/docs/plans/skills-review-final-outcomes.md index 77fe9943..81204bfc 100644 --- a/docs/plans/skills-review-final-outcomes.md +++ b/docs/plans/skills-review-final-outcomes.md @@ -2,7 +2,8 @@ ## Final Outcomes -- Repository-level docs now describe the canonical check surface (`scripts/check.sh` modes plus entrypoint drift guards) without legacy wrapper guidance. +- Repository-level docs now describe the canonical check surface (`scripts/check.sh` modes plus + entrypoint drift guards) without legacy wrapper guidance. - Runtime path examples for plan-issue cleanup now use the current `<owner__repo>` workspace slug convention. - The retained skill entrypoint surface is documented and auditable through current `SKILL.md`, smoke specs, and regression checks.