vouchington-tooling 0.22.0 → 0.22.1

package/README.md

@@ -462,6 +462,14 @@ Codex plugins. The package build materializes plugin source trees without hand-c
 and writes sorted schema-v1 provenance to `skills/manifest.json`.
 Each manifest entry may declare its ordered `prerequisites`; ordinary Markdown links remain
 cross-references and never cause additional skills to be linked.
+Prerequisites ensure installation closure; they do not require eagerly reading every installed
+skill. Follow the invoked skill's conditional instructions for the current task.
+
+Canonical entrypoints direct agents to applicable local instructions and adapters before using
+portable policy. Local `AGENTS.md` may name an adapter alias; an already-read canonical skill or
+adapter is not loaded again. `linkSkill` still links files only: it does not load instructions,
+resolve local aliases, or execute a workflow. Validate observed agent loading separately from
+installation and packaged-resource checks.
 
 Use `readSkillManifest(skillsRoot)` to discover installed skills or
 `linkSkill({ name, sourceRoot, targetRoot })` to link one into an explicit consumer directory. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {

package/skills/agent-workflow/SKILL.md

@@ -1,35 +1,25 @@
 ---
 name: agent-workflow
-description: 'Shared workflow guidance for repository implementation: inspect local instructions, keep changes bounded, validate, and prepare reviewable commits.'
+description: Implement and review repository changes within local policy.
 ---
 
 # Agent workflow
 
-Use this skill before implementation work. It supplies portable defaults; the repository's
-`AGENTS.md`, contribution guide, and CI configuration define the actual commands,
-branching, review, and release policy.
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/agent-workflow/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
 
-1. Inspect the current checkout and its status without discarding local work. Follow the consumer
-   repository's instructions for branch and worktree topology; do not create either implicitly.
-2. Read every applicable `AGENTS.md` from the repository root through each changed
-   file, then relevant documentation and tests. Apply the closest instruction only when rules
-   conflict, and treat all applicable local instructions as higher priority than this skill.
-3. Confirm the accepted task's boundary. Reuse existing ownership and utilities; ask before
-   widening scope or making an irreversible external change.
-4. Write a focused test first when behavior can be tested. Keep source, tests, docs, and generated
-   artifacts within the repository's stated size and formatting rules.
-5. Run the focused checks, then the local commands required for the changed surface. Report skipped
-   checks with a concrete reason.
-6. Review the diff for accidental files, secrets, generated output, broken documentation links,
-   and assumptions that belong in local instructions instead.
-7. When feedback arrives on an open change, give every surfaced item a disposition and drive it to
-   closure before hand-off; do not leave items unaddressed or silently absorb or defer them.
+Use before implementation. Inspect checkout status without discarding work; follow local branch,
+worktree, contribution, and CI policy. Read every applicable `AGENTS.md` from the repository root
+through changed files, plus relevant documentation and tests. Local instructions govern this skill.
 
-For portable implementation and review checks, read [implementation](references/implementation.md),
-[review](references/review.md), [review response](references/review-response.md), and
-[evidence sweep](references/evidence-sweep.md). The older
-[implementation and review](references/implementation-and-review.md) remains a compact overview.
-Local instructions remain authoritative for commands, commits, review systems, and release policy.
+- During implementation, use [implementation](references/implementation.md).
+- Before handoff, use [evidence sweep](references/evidence-sweep.md).
+- For review, use [review](references/review.md).
+- For surfaced feedback, use [review response](references/review-response.md).
+
+Load only the references required by the current phase. Keep scope changes explicit; a discovered
+blocker or follow-up does not authorize widening the task.
 
 Consumer wrapper or local instructions own: default branch, runner class, documentation root,
 review system, merge policy, and command catalog.

package/skills/agent-workflow/references/evidence-sweep.md

@@ -6,3 +6,7 @@ finding: state the blocker, affected surface, and remaining risk.
 
 Before handoff, compare the final diff to the accepted decision ledger and verify documentation,
 generated output, and public contracts agree with the implementation.
+
+When one semantic defect is found, search sibling call and write sites for the same shape; record
+why remaining matches are safe. Keep large logs and analysis artifacts outside the agent context,
+and report bounded findings and their evidence rather than raw payloads.

package/skills/agent-workflow/references/implementation-and-review.md

@@ -1,9 +1,4 @@
 # Implementation and review
 
-Before editing, map callers, tests, configuration, and documentation that own the behavior. Keep the
-change within the accepted boundary; record a new dependency or product decision before widening it.
-
-After focused validation, inspect the complete diff for accidental generated files, secret exposure,
-dead paths, and documentation drift. Validate the public interface and failure paths, not only the
-happy path. Before a reviewable commit, run the repository-required checks and state any skipped
-checks with their concrete blocker.
+Use [implementation](implementation.md) while editing, [evidence sweep](evidence-sweep.md) before
+handoff, and [review](review.md) for an independent review.

package/skills/agent-workflow/references/implementation.md

@@ -1,8 +1,15 @@
 # Implementation
 
-Keep an accepted-decision ledger for interfaces, data boundaries, validation, and ownership choices
-that could otherwise be lost during coding. Start from a failing behavioral test when practical and
+For cross-cutting work, track accepted interface, data, validation, and ownership decisions that
+could otherwise be lost during coding. Start from a failing behavioral test when practical and
 complete the real path rather than adding placeholders or compatibility shims without a requirement.
 
 When behavior changes, update the public contract, documentation, fixtures, and generated artifacts
 that describe it. Keep local commands, branch policy, and release mechanics in the consumer wrapper.
+
+Resolve rebase conflicts semantically: identify the upstream invariant, integrate both changes,
+and rerun the tests for that invariant. Do not treat the conflict as a choice of whole-file versions.
+
+Removing a deadline or abort bound needs a replacement on the same path, or evidence and a test
+showing every caller supplies its own bound. When changing a policy table, check sibling rows for
+contradictory conventions.

package/skills/backend-vitest-test-authoring/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: backend-vitest-test-authoring
-description: Apply backend Vitest patterns for service, provider, persistence, and queue boundaries.
+description: Test backend persistence, providers, services, and queues with Vitest.
 ---
 
 # Backend Vitest test authoring
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/backend-vitest-test-authoring/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Apply [vitest-test-authoring](../vitest-test-authoring/SKILL.md) first.
 
 - Exercise a real integration boundary only when the test environment controls its lifecycle.

package/skills/blackboard/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: blackboard
-description: Record and retrieve concise contemporaneous session findings when the repository provides a journal or blackboard service.
+description: Record and retrieve contemporaneous findings in the repository journal.
 ---
 
 # Session journal
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/blackboard/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use when the current repository provides a journal, blackboard, or equivalent durable session
 record. Read local `AGENTS.md` for the provider, credential, retention, and
 subagent-identity rules.

package/skills/dependabot/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: dependabot
-description: Configure or audit Dependabot coverage, cooldowns, package-family grouping, trusted CI, and conservative auto-merge policy for a repository.
+description: Configure Dependabot coverage, grouping, cooldowns, and trusted automation.
 ---
 
 # Dependabot policy
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/dependabot/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Read every applicable `AGENTS.md`, then the repository's dependency, CI, release,
 and branch-protection docs. The consumer wrapper owns the accepted cooldown, package roots,
 first-party publishers, manual-update exceptions, runner policy, required checks, and secret source.

package/skills/dotnet-test-authoring/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: dotnet-test-authoring
-description: Add maintainable .NET tests with appropriate unit, app, and integration boundaries.
+description: Author .NET unit, application, and integration tests.
 ---
 
 # .NET test authoring
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/dotnet-test-authoring/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Apply [test-authoring](../test-authoring/SKILL.md).
 
 - Place a test at the narrowest layer that proves the behavior.

package/skills/git-commit-checklist/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: git-commit-checklist
-description: Use before staging and committing changes to verify scope, validation, commit metadata, and local repository policy.
+description: Verify scope, checks, and local policy before committing.
 ---
 
 # Git commit checklist
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/git-commit-checklist/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use before every commit. Read local `AGENTS.md`, contribution guidance, and hook
 output first; they own commit format, required trailers, file-size limits, and validation commands.
 
@@ -19,3 +23,7 @@ output first; they own commit format, required trailers, file-size limits, and v
 
 Local instructions or the consumer wrapper own: branch names, file-size budgets, commit
 conventions, pull-request templates, and push commands.
+
+When an authorized rebase push may race another writer, capture the remote tip before fetching and
+push with an exact expected-tip lease. A lease against a freshly fetched tracking ref can overwrite
+the concurrent change it was meant to protect.

package/skills/github-actions-authoring/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: github-actions-authoring
-description: Author or redesign GitHub Actions workflows around event-driven orchestration, with remote-state polling prohibited.
+description: Design event-driven GitHub Actions without remote-state polling.
 ---
 
 # GitHub Actions authoring
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/github-actions-authoring/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Never poll in CI. A workflow reacts to a state transition. Read
 [github-actions-checklist](../github-actions-checklist/SKILL.md) first, then every applicable
 `AGENTS.md`. Repository-local policy and the consumer wrapper own runner labels,

package/skills/github-actions-checklist/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: github-actions-checklist
-description: Use when editing GitHub Actions workflows or composite actions to keep security, runner, permissions, concurrency, and validation aligned with local policy.
+description: Check Actions triggers, permissions, runners, pins, and deadlines.
 ---
 
 # GitHub Actions checklist
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/github-actions-checklist/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use before editing a workflow or composite action. Repository-local instructions own runners,
 approved action pins, concurrency names, secrets, permissions, and workflow-only pull-request rules.
 Apply this baseline unless a stricter local rule overrides it.
@@ -14,6 +18,10 @@ Apply this baseline unless a stricter local rule overrides it.
 - Use `pull_request` for pull-request workflows in private repositories.
 - Reserve `pull_request_target` for base-owned orchestration in a public repository, or for a
   narrowly scoped Dependabot or Renovate workflow.
+- A pull-request CI workflow must not subscribe to `ready_for_review` or `converted_to_draft`
+  unless a job changes what it does on that transition. Those activity types start another run for
+  the same head, and `cancel-in-progress: true` replaces checks that already passed. Dependabot
+  auto-merge may keep `ready_for_review`: it enables merge and does not rerun tests.
 - A privileged workflow must not check out or execute untrusted pull-request content.
 - When changing orchestration, load
   [github-actions-authoring](../github-actions-authoring/SKILL.md). Do not poll remote workflow,

package/skills/github-issue/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: github-issue
-description: Search, create, update, link, or assess GitHub issues using the repository's live issue policy and taxonomy.
+description: Search, write, and classify GitHub issues within live authorization.
 ---
 
 # GitHub issues
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/github-issue/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use for durable follow-ups and pull-request linkage. Read local `AGENTS.md`, issue
 templates, and repository-routing policy before any remote mutation.
 

package/skills/manifest.json

@@ -4,180 +4,191 @@
     {
       "name": "agent-workflow",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "agent-workflow/SKILL.md",
       "prerequisites": ["github-issue"]
     },
     {
       "name": "backend-vitest-test-authoring",
       "plugin": "vouchington-testing",
-      "pluginVersion": "0.1.0",
+      "pluginVersion": "0.2.0",
       "path": "backend-vitest-test-authoring/SKILL.md",
       "prerequisites": ["vitest-test-authoring"]
     },
     {
       "name": "blackboard",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "blackboard/SKILL.md"
     },
     {
       "name": "dependabot",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "dependabot/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "dotnet-test-authoring",
       "plugin": "vouchington-testing",
-      "pluginVersion": "0.1.0",
-      "path": "dotnet-test-authoring/SKILL.md"
+      "pluginVersion": "0.2.0",
+      "path": "dotnet-test-authoring/SKILL.md",
+      "prerequisites": ["test-authoring"]
     },
     {
       "name": "git-commit-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "git-commit-checklist/SKILL.md"
     },
     {
       "name": "github-actions-authoring",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "github-actions-authoring/SKILL.md",
       "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "github-actions-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "github-actions-checklist/SKILL.md"
     },
     {
       "name": "github-issue",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "github-issue/SKILL.md"
     },
     {
       "name": "nextjs-vitest-test-authoring",
       "plugin": "vouchington-testing",
-      "pluginVersion": "0.1.0",
+      "pluginVersion": "0.2.0",
       "path": "nextjs-vitest-test-authoring/SKILL.md",
       "prerequisites": ["vitest-test-authoring"]
     },
     {
       "name": "npm-publishing",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "npm-publishing/SKILL.md"
     },
     {
       "name": "organize-github-issues",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
-      "path": "organize-github-issues/SKILL.md"
+      "pluginVersion": "0.8.0",
+      "path": "organize-github-issues/SKILL.md",
+      "prerequisites": ["github-issue"]
     },
     {
       "name": "package-json-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "package-json-checklist/SKILL.md"
     },
     {
       "name": "planning",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
-      "path": "planning/SKILL.md"
+      "pluginVersion": "0.8.0",
+      "path": "planning/SKILL.md",
+      "prerequisites": ["github-issue"]
     },
     {
       "name": "playwright-authoring",
       "plugin": "vouchington-testing",
-      "pluginVersion": "0.1.0",
-      "path": "playwright-authoring/SKILL.md"
+      "pluginVersion": "0.2.0",
+      "path": "playwright-authoring/SKILL.md",
+      "prerequisites": ["test-authoring"]
     },
     {
       "name": "postgres-node-performance-tuning",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.1.0",
+      "pluginVersion": "0.2.0",
       "path": "postgres-node-performance-tuning/SKILL.md"
     },
     {
       "name": "postgres-partitioning-uuid-v7",
       "plugin": "vouchington-database",
-      "pluginVersion": "0.1.0",
+      "pluginVersion": "0.2.0",
       "path": "postgres-partitioning-uuid-v7/SKILL.md"
     },
     {
       "name": "pr-description",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "pr-description/SKILL.md"
     },
     {
       "name": "retrospective",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "retrospective/SKILL.md"
     },
     {
       "name": "retrospective-distill",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
-      "path": "retrospective-distill/SKILL.md"
+      "pluginVersion": "0.8.0",
+      "path": "retrospective-distill/SKILL.md",
+      "prerequisites": ["github-issue"]
     },
     {
       "name": "review-ci-logs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
-      "path": "review-ci-logs/SKILL.md"
+      "pluginVersion": "0.8.0",
+      "path": "review-ci-logs/SKILL.md",
+      "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "review-github-issue-taxonomy",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
-      "path": "review-github-issue-taxonomy/SKILL.md"
+      "pluginVersion": "0.8.0",
+      "path": "review-github-issue-taxonomy/SKILL.md",
+      "prerequisites": ["github-issue"]
     },
     {
       "name": "revisit-followups",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
-      "path": "revisit-followups/SKILL.md"
+      "pluginVersion": "0.8.0",
+      "path": "revisit-followups/SKILL.md",
+      "prerequisites": ["github-issue"]
     },
     {
       "name": "stacked-prs",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
+      "pluginVersion": "0.8.0",
       "path": "stacked-prs/SKILL.md"
     },
     {
       "name": "static-analysis-checklist",
       "plugin": "vouchington-workflow",
-      "pluginVersion": "0.7.0",
-      "path": "static-analysis-checklist/SKILL.md"
+      "pluginVersion": "0.8.0",
+      "path": "static-analysis-checklist/SKILL.md",
+      "prerequisites": ["github-actions-checklist"]
     },
     {
       "name": "storybook-authoring",
       "plugin": "vouchington-testing",
-      "pluginVersion": "0.1.0",
-      "path": "storybook-authoring/SKILL.md"
+      "pluginVersion": "0.2.0",
+      "path": "storybook-authoring/SKILL.md",
+      "prerequisites": ["test-authoring"]
     },
     {
       "name": "swift-test-authoring",
       "plugin": "vouchington-testing",
-      "pluginVersion": "0.1.0",
-      "path": "swift-test-authoring/SKILL.md"
+      "pluginVersion": "0.2.0",
+      "path": "swift-test-authoring/SKILL.md",
+      "prerequisites": ["test-authoring"]
     },
     {
       "name": "test-authoring",
       "plugin": "vouchington-testing",
-      "pluginVersion": "0.1.0",
+      "pluginVersion": "0.2.0",
       "path": "test-authoring/SKILL.md"
     },
     {
       "name": "vitest-test-authoring",
       "plugin": "vouchington-testing",
-      "pluginVersion": "0.1.0",
+      "pluginVersion": "0.2.0",
       "path": "vitest-test-authoring/SKILL.md",
       "prerequisites": ["test-authoring"]
     }

package/skills/nextjs-vitest-test-authoring/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: nextjs-vitest-test-authoring
-description: Apply Vitest patterns for Next.js components, routes, and server-side modules.
+description: Test Next.js components, routes, and server boundaries with Vitest.
 ---
 
 # Next.js Vitest test authoring
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/nextjs-vitest-test-authoring/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Apply [vitest-test-authoring](../vitest-test-authoring/SKILL.md) first.
 
 - Mock framework navigation, headers, and server-only boundaries at the framework edge.

package/skills/npm-publishing/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: npm-publishing
-description: Bootstrap an npm package and give a human the exact commands to publish it publicly and configure GitHub trusted publishing.
+description: Prepare npm bootstrap and trusted publishing commands for a human.
 ---
 
 # npm publishing bootstrap
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/npm-publishing/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Prepare the local package. Leave public registry writes and trusted-publisher mutations to the
 human. Read every applicable `AGENTS.md` from the repository root through the
 package. Repository-local policy and the consumer wrapper own the package path and name, npm scope,

package/skills/organize-github-issues/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: organize-github-issues
-description: Organize existing GitHub issues and pull requests with the repository's live taxonomy without inventing new taxonomy.
+description: Apply existing issue and PR taxonomy within the requested scope.
 ---
 
 # Organize GitHub issues
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/organize-github-issues/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use for issue hygiene, priority normalization, milestone assignment, and project membership. Read
 local `AGENTS.md`, and live taxonomy guidance before acting.
 

package/skills/package-json-checklist/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: package-json-checklist
-description: Use when changing JavaScript package metadata, dependencies, scripts, workspaces, or published entrypoints.
+description: Check package metadata, dependencies, entrypoints, and lockfiles.
 ---
 
 # Package metadata checklist
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/package-json-checklist/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use before changing `package.json`, a lockfile, workspace metadata, or a package entrypoint. Read
 every applicable `AGENTS.md` from the repository root through the owning package,
 applying the closest file only when rules conflict. Those instructions own package-manager version,

package/skills/planning/SKILL.md

@@ -1,28 +1,33 @@
 ---
 name: planning
-description: Create an evidence-backed implementation plan for a repository change or a justified no-change recommendation.
+description: Plan a repository change and save the decision outside Git.
 ---
 
 # Planning
 
-Use before implementation work that needs a durable plan. Repository-local `AGENTS.md`,
-`AGENTS.md`, issue templates, and planning conventions override this portable foundation.
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/planning/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
+Use when a task needs a plan. Scale detail to uncertainty and impact; no fixed headings, tables,
+diagram, independent reviewer, or separate issue are required by this skill.
 
 1. State the desired outcome and compare no change, reuse, and alternative approaches. Choose the
    smallest durable option; ask before treating an unresolved product choice as settled.
 2. Read applicable instructions, documentation, current code, tests, and recent changes from a
    fresh base. Record which evidence supports each proposed path.
-3. Map affected owners, public contracts, migrations, operational boundaries, and tests. Use
-   independent review or exploration when the change is cross-cutting or uncertain.
-4. Specify implementation steps, file-level intent, validation, rollout, and any follow-up that is
-   truly outside the accepted scope. Distinguish existing paths from new paths.
-5. Validate and save the plan using the repository's required issue or document workflow before
-   implementation when local policy requires one. When creating a plan issue from a source issue
+3. Map affected owners, contracts, operational boundaries, and tests. Use independent review or
+   exploration when the change is cross-cutting or uncertain and local policy calls for it.
+4. Record the chosen approach, steps, validation, and unresolved decisions. Add rollout details
+   only when an established deployment contract requires them.
+5. Save the plan once outside Git: an existing issue, a PR description, or a durable native plan
+   file outside the repository. Do not commit task plans or count temporary scratch files as saved
+   plans. If no durable record is available, use an issue through the local issue workflow. Link
+   the record from the handoff instead of duplicating it. When creating a plan issue from a source issue
    that already has a milestone or project, apply that same existing milestone or project through
    [github-issue](../github-issue/SKILL.md).
 
 For cross-cutting changes, read [impact discovery](references/impact-discovery.md) before selecting
 tests or concluding that a surface has no dependents.
 
-Consumer wrapper owns: plan template, default repository, issue taxonomy, dependency graph tool,
-and approval workflow.
+Consumer wrapper owns: durable plan storage, repository, taxonomy, discovery tools, and approval.

package/skills/planning/references/impact-discovery.md

@@ -5,5 +5,7 @@ tests. Use the repository's graph or search tools where available; otherwise rec
 used and the uncertainty that remains. Select focused tests from real dependents, then include
 broader validation when a shared contract, package boundary, or generated artifact changes.
 
+Check source-issue paths against current source before relying on them; issue text is a snapshot.
+
 Do not treat a tool's incomplete graph as proof that no dependent exists. Escalate uncertain
 high-risk boundaries for independent review or a broader test selection.

package/skills/playwright-authoring/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: playwright-authoring
-description: Author reliable Playwright browser tests, fixtures, selectors, and user flows.
+description: Author reliable Playwright flows, fixtures, and assertions.
 ---
 
 # Playwright authoring
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/playwright-authoring/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Apply [test-authoring](../test-authoring/SKILL.md).
 
 - Use a stable, accessible locator. Assert a user-observable outcome.

package/skills/postgres-node-performance-tuning/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: postgres-node-performance-tuning
-description: Diagnose and improve PostgreSQL performance in Node.js applications with large data volumes.
+description: Measure and improve PostgreSQL queries in Node.js services.
 ---
 
 # PostgreSQL and Node.js performance
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/postgres-node-performance-tuning/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Measure the query plan and the workload shape before changing code.
 
 - Select only the required columns.

package/skills/postgres-partitioning-uuid-v7/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: postgres-partitioning-uuid-v7
-description: Design PostgreSQL partitions and indexes that use time-ordered UUIDv7 identifiers efficiently.
+description: Design PostgreSQL partitions and pruning around UUIDv7.
 ---
 
 # PostgreSQL partitioning with UUIDv7
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/postgres-partitioning-uuid-v7/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Partition only after lifecycle, retention, and query predicates show that it helps.
 
 - Treat a UUIDv7 as time ordered. Where the meaning matters, keep an explicit business timestamp.

package/skills/pr-description/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: pr-description
-description: Draft or review a self-contained pull-request description with summary, root cause, validation, rollout, and issue context.
+description: Write a self-contained PR description backed by the final diff.
 ---
 
 # Pull-request description
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/pr-description/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use before opening or updating a pull request, or when reviewing PR hand-off quality. Read local
 `AGENTS.md`, pull-request template, and issue-linking policy first.
 

package/skills/retrospective/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: retrospective
-description: Produce a concise evidence-based retrospective for a completed task or session when local workflow provides a durable record.
+description: Summarize completed work from verified facts and the session journal.
 ---
 
 # Retrospective
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/retrospective/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use at task completion or session close-out when the repository has a retrospective workflow. Read
 local `AGENTS.md`, and journal guidance first.
 

package/skills/retrospective-distill/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: retrospective-distill
-description: Distill completed session records into a small set of verified, actionable follow-up issues.
+description: Turn completed session records into verified follow-up candidates.
 ---
 
 # Retrospective distillation
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/retrospective-distill/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use when completed retrospectives or journals should become durable follow-up work. Read local
 `AGENTS.md`, issue policy, and journal retention rules before any mutation.
 

package/skills/review-ci-logs/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: review-ci-logs
-description: Audit CI failures or noisy logs, identify the root cause, and recommend diagnostics-preserving fixes.
+description: Diagnose CI failures and noise without weakening diagnostics.
 ---
 
 # Review CI logs
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/review-ci-logs/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use when investigating a CI failure, repeated workflow noise, or misleading diagnostics. Read local
 `AGENTS.md`, workflow guidance, and CI documentation before inspecting runs.
 

package/skills/review-github-issue-taxonomy/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: review-github-issue-taxonomy
-description: Audit GitHub labels, milestones, projects, and path-label automation and return actionable taxonomy recommendations.
+description: Audit labels, milestones, projects, and path-label ownership.
 ---
 
 # Review GitHub issue taxonomy
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/review-github-issue-taxonomy/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use when the taxonomy itself needs review. Stay read-only unless the caller explicitly authorizes
 local configuration edits or a live taxonomy mutation. Read local `AGENTS.md` first.
 

package/skills/revisit-followups/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: revisit-followups
-description: Review recently completed work and repository instructions for genuinely deferred follow-ups, then propose verified issue candidates.
+description: Find verified deferred work in completed changes and instructions.
 ---
 
 # Revisit follow-ups
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/revisit-followups/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use to turn explicit deferred work into a curated backlog. Read local `AGENTS.md`,
 issue policy, and review-record conventions first.
 

package/skills/stacked-prs/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: stacked-prs
-description: Recognize a native GitHub stacked pull request and drain it from the bottom-most ready layer up, rather than waiting for the whole stack to be ready first.
+description: Drain native GitHub stacks from the bottom ready layer.
 ---
 
 # Stacked pull requests
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/stacked-prs/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use when a change is a chain of native GitHub stacked pull requests. Read local `AGENTS.md` and
 `AGENTS.md` first. They own whether this repository stacks, which tool creates, rebases, and merges
 a stack, and who may authorize a merge.

package/skills/static-analysis-checklist/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: static-analysis-checklist
-description: Use when adding, changing, replacing, or removing static-analysis rules, configurations, fixtures, suppressions, allowlists, or repository guards.
+description: Place, author, and validate static-analysis invariants.
 ---
 
 # Static analysis checklist
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/static-analysis-checklist/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use when changing a static-analysis invariant. Read local `AGENTS.md`, analyzer
 documentation, rule inventory, and fixture conventions before selecting an implementation.
 

package/skills/storybook-authoring/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: storybook-authoring
-description: Add maintainable Storybook stories and browser-mode component coverage.
+description: Author component stories and browser coverage for real states.
 ---
 
 # Storybook authoring
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/storybook-authoring/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Apply [test-authoring](../test-authoring/SKILL.md).
 
 - Show a meaningful supported state with realistic args and fixtures.

package/skills/swift-test-authoring/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: swift-test-authoring
-description: Add Swift and SwiftUI tests with deterministic state, networking, and view inspection.
+description: Test Swift and SwiftUI state, networking, and view behavior.
 ---
 
 # Swift test authoring
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/swift-test-authoring/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Apply [test-authoring](../test-authoring/SKILL.md).
 
 - Test public behavior with deterministic inputs and injected dependencies.

package/skills/test-authoring/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: test-authoring
-description: Write focused, maintainable tests and test fixtures for application or library behavior.
+description: Choose meaningful tests, fixtures, and observable boundaries.
 ---
 
 # Test authoring
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/test-authoring/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Use the repository's test conventions and the matching runner skill.
 
 - Test observable behavior, boundary failures, and regressions. Do not test implementation details.

package/skills/test-authoring/references/core-practice.md

@@ -12,3 +12,5 @@
 - For every acceptance criterion, keep evidence from a focused test, a review, or an explicitly
   justified manual check. Evidence counts only when it is falsifiable. Confirm the assertion is not
   [tautological](tautological-tests.md) before treating it as coverage.
+- For instruction and documentation contracts, test real paths, links, rendered markers, or
+  executable behavior. Do not freeze prose wording unless a real consumer parses that exact text.

package/skills/vitest-test-authoring/SKILL.md

@@ -1,10 +1,14 @@
 ---
 name: vitest-test-authoring
-description: Apply Vitest-specific patterns when adding or changing Vitest tests, mocks, or fixtures.
+description: Author deterministic Vitest assertions, mocks, and factories.
 ---
 
 # Vitest test authoring
 
+Read applicable `AGENTS.md` and their declared adapter alias, otherwise
+`.agents/skills/vitest-test-authoring/SKILL.md` from the repository root if present.
+Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
+
 Apply [test-authoring](../test-authoring/SKILL.md) first.
 
 - Isolate tests with Vitest lifecycle hooks. Restore spies and globals after each test.