vouchington-tooling 0.1.2 → 0.1.4

package/README.md

@@ -150,3 +150,11 @@ The runner uses monotonic elapsed time, rejects timer budgets above Node's maxim
 the dedicated process group to exit after the direct child closes so descendants cannot overlap a retry.
 `isProcessGroupAlive` and `waitForProcessGroupExit` are also available when callers need the same
 process-group probe and bounded-drain semantics outside a browser session.
+
+## Workflow skills outside plugins
+
+The package ships the canonical Vouchington workflow skill tree at
+`skills/<skill>/SKILL.md`. This stable installed path supports agents that do not
+load Claude or Codex plugins. The Claude and Codex plugin manifests continue to reference the same
+canonical source tree under `plugins/vouchington-workflow/skills`; package build materializes that tree
+without hand-copying skill content.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vouchington-tooling",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Vouchington CLI and extractable tooling libraries.",
   "homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
   "bugs": {
@@ -18,6 +18,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "scripts",
     "README.md"
   ],

package/scripts/build.mjs

@@ -1,11 +1,12 @@
 import { execFileSync } from 'node:child_process'
-import { chmod, copyFile, mkdir, rm } from 'node:fs/promises'
+import { chmod, copyFile, cp, mkdir, rm } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 
 const packageRoot = new URL('..', import.meta.url)
 const dist = new URL('../dist', import.meta.url)
 
 await rm(dist, { recursive: true, force: true })
+await rm(new URL('../skills', import.meta.url), { recursive: true, force: true })
 execFileSync('tsc', ['--project', 'tsconfig.build.json'], {
   stdio: 'inherit',
   cwd: fileURLToPath(packageRoot),
@@ -15,4 +16,9 @@ await copyFile(
   new URL('../src/runner-port-policy/runner-port-policy.json', import.meta.url),
   new URL('../dist/runner-port-policy/runner-port-policy.json', import.meta.url),
 )
+await cp(
+  new URL('../../../plugins/vouchington-workflow/skills', import.meta.url),
+  new URL('../skills', import.meta.url),
+  { recursive: true },
+)
 await chmod(new URL('../dist/cli/index.mjs', import.meta.url), 0o755)

package/skills/agent-workflow/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: agent-workflow
+description: 'Shared workflow guidance for repository implementation: inspect local instructions, keep changes bounded, validate, and prepare reviewable commits.'
+---
+
+# Agent workflow
+
+Use this skill before implementation work. It supplies portable defaults; the repository's
+`AGENTS.md`, `CLAUDE.md`, contribution guide, and CI configuration define the actual commands,
+branching, review, and release policy.
+
+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` and `CLAUDE.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.
+
+Do not invent a default branch, runner class, documentation root, review system, merge policy, or
+command catalog. A consumer wrapper or local instruction file owns those choices.

package/skills/blackboard/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: blackboard
+description: Record and retrieve concise contemporaneous session findings when the repository provides a journal or blackboard service.
+---
+
+# Session journal
+
+Use when the current repository provides a journal, blackboard, or equivalent durable session
+record. Read local `AGENTS.md` and `CLAUDE.md` for the provider, credential, retention, and
+subagent-identity rules.
+
+1. Append a concise note when a check fails, permission is denied, scope changes, a repeated fix is
+   needed, or a tool result reveals a reusable gap. Include the finding, affected paths, concrete
+   evidence, and any tracking reference.
+2. Preserve the provider's required session and parent-session identity. Never invent, guess,
+   print, search for, or persist credentials outside its documented mechanism.
+3. If the journal service cannot authenticate or persist a mandatory entry, stop and report the
+   blocker rather than silently substituting a local file or memory.
+4. Read journal entries oldest-first when preparing a retrospective or clustering follow-ups; use
+   direct evidence rather than reconstructing events from memory.
+
+This skill does not require a particular service, command, note grammar, archival policy, or issue
+destination. A consumer wrapper supplies those integrations.

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

@@ -0,0 +1,21 @@
+---
+name: git-commit-checklist
+description: Use before staging and committing changes to verify scope, validation, commit metadata, and local repository policy.
+---
+
+# Git commit checklist
+
+Use before every commit. Read local `AGENTS.md`, `CLAUDE.md`, contribution guidance, and hook
+output first; they own commit format, required trailers, file-size limits, and validation commands.
+
+1. Inspect `git status` and the complete diff. Stage only files that implement the accepted task.
+2. Confirm new or changed source and test files meet local size, formatting, and generated-file
+   policy. Do not commit credentials, build outputs, editor state, or unrelated changes.
+3. Run focused tests and required local checks. Record any permitted skipped check and why.
+4. Use the repository's conventional subject and required body/trailers. If code was extracted,
+   record the required provenance in the commit body.
+5. Re-read the staged diff and commit message before committing. Do not amend another author's
+   work or rewrite history unless local policy and explicit authorization allow it.
+
+This skill does not prescribe branch names, file-size budgets, commit conventions, PR templates,
+or push commands. Supply those through repository-local instructions or a consumer wrapper.

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

@@ -0,0 +1,24 @@
+---
+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.
+---
+
+# GitHub Actions checklist
+
+Use before editing a workflow or composite action. Repository-local instructions own runners,
+approved action pinning, concurrency naming, secrets, permissions, and workflow-only PR rules.
+
+1. Read every applicable `AGENTS.md` and `CLAUDE.md` from the repository root through the workflow,
+   plus relevant CI documentation and callers. Apply the closest instruction only when rules
+   conflict. Identify trusted and untrusted inputs and every credential boundary.
+2. Give each job the least permissions it needs. Keep untrusted pull-request content out of shell
+   interpolation, privileged tokens, and write-capable steps.
+3. Use the repository's pinned-action and runner policy. Keep checkout refs, artifact boundaries,
+   caches, and concurrency behavior explicit.
+4. Validate changed YAML with the local workflow checker and run the affected workflow tests or
+   scripts. Update local CI documentation when behavior or operator expectations change.
+5. Review the final diff for privilege escalation, accidental secret exposure, unsafe quoting,
+   unsupported runner assumptions, and unreachable workflow paths.
+
+This skill intentionally has no default runner labels, action SHAs, workflow directories,
+concurrency scheme, or release policy. A consumer wrapper supplies those values.

package/skills/github-issue/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: github-issue
+description: Search, create, update, link, or assess GitHub issues using the repository's live issue policy and taxonomy.
+---
+
+# GitHub issues
+
+Use for durable follow-ups and pull-request linkage. Read local `AGENTS.md`, `CLAUDE.md`, issue
+templates, and repository-routing policy before making any remote mutation.
+
+## Mutation authority
+
+Caller authorization is required before any issue or taxonomy mutation; credential capability does
+not grant scope. Resolve the authenticated identity, current repository, and requested target without
+owner-prefix or visibility assumptions. Immediately before every write, refetch the exact target and
+require its canonical identity to still match and the repository not to be archived. Issue operations
+also require issues to be enabled and `viewerPermission` of `TRIAGE`, `WRITE`, `MAINTAIN`, or `ADMIN`;
+issue creation additionally requires `viewerCanCreateIssues`. Applying existing metadata to a pull
+request uses the same permission set but does not require issues to be enabled. Creating, changing, or
+deleting taxonomy definitions requires `WRITE`, `MAINTAIN`, or `ADMIN` plus the operation-specific API
+capability. Treat insufficient permission or capability, missing or inaccessible data, identity
+changes, and mismatches as a hard deny that approval cannot override.
+
+When an external creation target is denied, never write there. Search for and create or reuse a
+tracking issue in the current repository, or a consumer-selected tracker. Immediately before that
+write, refetch the destination repository and apply the issue-operation gate above. Include the
+intended upstream repository and a copy-ready report so a human can decide whether to file it. Before
+copying details to a less-restricted destination, remove private repository identity, paths, links,
+code, and findings; if redaction would make the report unusable, require explicit destination approval
+or return the draft without mutation. Authorization to file the external issue includes this tracking
+fallback unless the caller opts out; report the reroute explicitly. If no tracker passes, return the
+draft without mutation. Never fall back silently or to an unverified repository.
+
+## Issue workflow
+
+1. Search open and relevant closed issues in the selected destination; return a likely duplicate
+   rather than filing one. Verify paths and current behavior named in the issue.
+2. Before editing, commenting, relating, closing, or otherwise changing state, refetch the issue and
+   its current discussion. Verify the requested mutation is still authorized and supported by that
+   evidence. Close only when the documented outcome and acceptance evidence show the work is
+   resolved; otherwise leave state unchanged and report the gap.
+3. Write a self-contained issue with the problem, desired outcome, ownership boundaries, concrete
+   areas, validation, and external context. A discovered blocker does not widen implementation scope.
+4. Fetch the complete live taxonomy. Apply matching existing labels and a selected existing milestone
+   without separate approval. Omit a missing optional milestone; a missing required milestone blocks
+   the issue, and milestone creation is a separately authorized taxonomy operation. For a
+   missing label, use [review-github-issue-taxonomy](../review-github-issue-taxonomy/SKILL.md): obtain
+   explicit approval for its exact repository, name, description, and color before creating it.
+   Omit a declined optional label; a missing required label blocks the issue.
+5. Refetch the created or updated issue and verify its metadata. Report a partial failure without
+   retrying creation. Preserve history and report the action, URL, labels, and milestone.
+6. Link a pull request with a closing reference only when it fully resolves the issue. Keep
+   cross-repository references fully qualified; PR creation authority remains separate.
+7. Use native sub-issues only for real hierarchy, blocked-by relationships only for genuine known
+   dependencies, and prose links for merely related work. Read every created relationship back.
+
+For batch creation, preflight every entry before writing any issue and fail the whole batch when one
+entry is invalid. A partial transport failure stops further creation and reports every issue already
+created; never retry successful entries.
+
+This skill supplies no repository allowlist, taxonomy, issue template, credential, or CLI wrapper.
+Consumer wrappers define local defaults and may impose stricter policy, but may not weaken this gate.

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

@@ -0,0 +1,26 @@
+---
+name: organize-github-issues
+description: Organize existing GitHub issues and pull requests with the repository's live taxonomy without inventing new taxonomy.
+---
+
+# Organize GitHub issues
+
+Use for issue hygiene, priority normalization, and milestone assignment. Read local `AGENTS.md`,
+`CLAUDE.md`, and live taxonomy guidance before acting.
+
+1. Confirm repository identity and fetch the live labels, milestone descriptions, and all required
+   in-scope issue or pull-request evidence. Before mutating, enforce the operation-specific gate from
+   [github-issue](../github-issue/SKILL.md); pull-request metadata does not require issues to be
+   enabled.
+2. Classify from the permitted metadata and discussion evidence, not implementation guesses. Keep
+   automation, ownership, and provenance labels unless local policy explicitly permits changes.
+3. Apply only existing labels and milestones without requesting separate label approval. Do not
+   create taxonomy, close work, rewrite bodies, or alter titles unless the caller separately
+   authorizes that scope.
+4. In review mode, report the exact proposed metadata changes without mutating. In apply mode, make
+   only necessary, idempotent updates.
+5. Refetch every touched item and verify the requested metadata changed while protected metadata
+   stayed intact. Report changed, unchanged, and ambiguous items separately.
+
+This skill does not define priorities, labels, milestones, clarification policy, or default scope.
+A consumer wrapper supplies the repository-specific taxonomy and permissions.

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

@@ -0,0 +1,27 @@
+---
+name: package-json-checklist
+description: Use when changing JavaScript package metadata, dependencies, scripts, workspaces, or published entrypoints.
+---
+
+# Package metadata checklist
+
+Use before changing `package.json`, a lockfile, workspace metadata, or a package entrypoint. Read
+every applicable `AGENTS.md` and `CLAUDE.md` from the repository root through the owning package,
+applying the closest file only when rules conflict. Those instructions own package-manager version,
+dependency age/version policy, registry, release process, and package layout.
+
+1. Identify the owning package and every consumer of the changed script, dependency, export, or
+   binary. Prefer existing workspace utilities before adding a dependency.
+2. Use the repository's package manager for dependency changes. Update the lockfile when it records
+   the affected metadata; avoid lockfile churn for metadata-only edits it does not record. Keep peer,
+   optional, development, and runtime dependencies in their intended sections.
+3. For a published package, verify exports, types, files, binaries, and build output match the
+   package's supported import and installation paths.
+4. Run the package manager's integrity check, focused tests, typecheck, build, and local policy
+   checks required by the affected package. Do not publish or alter registry state without explicit
+   authorization.
+5. Review the lockfile and generated metadata for unrelated churn before committing.
+
+This skill supplies no version range, workspace topology, registry, package-manager command, or
+release convention. Put those repository-specific choices in local instructions or a consumer
+wrapper.

package/skills/planning/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: planning
+description: Create an evidence-backed implementation plan for a repository change or a justified no-change recommendation.
+---
+
+# Planning
+
+Use before implementation work that needs a durable plan. Repository-local `AGENTS.md`,
+`CLAUDE.md`, issue templates, and planning conventions override this portable foundation.
+
+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.
+
+Do not invent a plan template, default repository, issue taxonomy, dependency graph tool, or
+approval workflow. A consumer wrapper owns those choices.

package/skills/pr-description/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: pr-description
+description: Draft or review a self-contained pull-request description with summary, root cause, validation, rollout, and issue context.
+---
+
+# Pull-request description
+
+Use before opening or updating a pull request, or when reviewing PR hand-off quality. Read local
+`AGENTS.md`, `CLAUDE.md`, pull-request template, and issue-linking policy first.
+
+Include enough context for a reviewer with no prior conversation:
+
+- A concise summary of what changed and why.
+- The underlying root cause for a fix, not only its visible symptom.
+- Validation performed and any intentionally skipped checks with reasons.
+- Rollout, compatibility, operational safety, and follow-up context when the change affects a live
+  or independently deployed surface.
+- Correct issue relationships: close only issues fully resolved and explain any non-closing links.
+- A compact diagram only when it materially clarifies a multi-component flow or lifecycle.
+
+Use the repository's approved PR tooling and preserve sections managed by its review automation.
+Do not invent required headings, a source issue rule, merge policy, repository command, or hosted
+review system. Consumer wrappers own those mechanics.

package/skills/retrospective/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: retrospective
+description: Produce a concise evidence-based retrospective for a completed task or session when local workflow provides a durable record.
+---
+
+# Retrospective
+
+Use at task completion or session close-out when the repository has a retrospective workflow.
+Read the local `AGENTS.md`, `CLAUDE.md`, and journal guidance first.
+
+1. Check whether a retrospective already exists and append only a material delta when local policy
+   calls for that behavior.
+2. Gather verifiable facts from the repository's approved status, validation, issue, and journal
+   sources. Do not estimate unknown facts from memory or transcripts.
+3. Summarize the outcome, plan-versus-actual differences, validation evidence, recurring friction,
+   and actionable process improvements. Keep one-off noise separate from repeatable root causes.
+4. Save through the repository's required durable mechanism and report the record identifier plus
+   any follow-up decisions.
+
+Do not prescribe transcript access, retention, a report schema, a journal provider, or issue
+filing policy. Consumer wrappers add those local contracts.

package/skills/retrospective-distill/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: retrospective-distill
+description: Distill completed session records into a small set of verified, actionable follow-up issues.
+---
+
+# Retrospective distillation
+
+Use when completed retrospectives or journals should become durable follow-up work. Read local
+`AGENTS.md`, `CLAUDE.md`, issue policy, and journal retention rules before any mutation.
+
+1. Enumerate only completed, eligible session records. Leave in-progress sessions intact.
+2. Cluster findings by root cause, favoring a few broad actionable themes over many narrow issues.
+   Treat a finding already linked to an open tracker as context, not a duplicate.
+3. Verify each candidate against the current base and search existing issues and open changes before
+   drafting. Skip work that is complete, explicitly rejected, or already covered.
+4. Draft self-contained issues with the problem, concrete proposed work, relevant areas, and
+   evidence embedded in the body. Route every authorized creation through
+   [github-issue](../github-issue/SKILL.md), including its repository gate, label approval, and
+   denied-external tracking behavior.
+5. Archive only records that were fully processed under the repository's retention rules; report
+   created, updated, skipped, and deferred themes with reasons.
+
+This skill supplies no journal API, issue repository, labels, milestones, archival command, or
+approval model. A consumer wrapper provides those details.

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

@@ -0,0 +1,23 @@
+---
+name: review-ci-logs
+description: Audit CI failures or noisy logs, identify the root cause, and recommend diagnostics-preserving fixes.
+---
+
+# Review CI logs
+
+Use when investigating CI failures, repeated workflow noise, or misleading diagnostics. Read local
+`AGENTS.md`, `CLAUDE.md`, workflow guidance, and CI documentation before inspecting runs.
+
+1. Confirm the repository and select representative failed and successful runs within a bounded
+   window. For a supplied run, inspect only that run.
+2. Download logs to a temporary directory instead of streaming archives into the working context.
+   Inspect failed steps and representative large entries, then remove temporary artifacts.
+3. Classify findings as a real error, misleading output, downstream cascade, necessary diagnostic,
+   or volume-only concern. Identify the first repository-owned root cause.
+4. Prefer one bounded fix that preserves non-zero exits, primary errors, artifacts, summaries, and
+   diagnostic evidence. Do not hide stderr, globally quiet output, or add retries to mask a cause.
+5. Add focused regression evidence, run local workflow validation, compare before and after output
+   where meaningful, and report deferred findings without creating issues unless authorized.
+
+This skill supplies no workflow names, log-retention policy, CI provider command, retry policy, or
+scheduled automation. Consumer wrappers provide those local details.

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

@@ -0,0 +1,28 @@
+---
+name: review-github-issue-taxonomy
+description: Audit GitHub labels, milestones, and path-label automation and return actionable taxonomy recommendations.
+---
+
+# Review GitHub issue taxonomy
+
+Use when the taxonomy itself needs review. Remain read-only unless the caller explicitly authorizes
+local configuration edits or live taxonomy mutation; read local `AGENTS.md` and `CLAUDE.md` first.
+
+1. Confirm repository identity and fetch live labels, descriptions, colors, usage, milestones, and
+   their current scope.
+2. Identify automation-owned labels and inspect local label automation before recommending a rename,
+   deletion, or rule change.
+3. Audit aliases, ambiguity, unused labels, missing descriptions, color consistency, milestone
+   overlap, delivery gaps, and path-label coverage.
+4. Return exact recommendations with migration impact and separate safe cleanup from decisions that
+   require product or scheduling judgment. Applying an existing label is not taxonomy creation and
+   needs no separate approval from the authorized issue operation.
+5. Before creating a label, stop for explicit approval naming its exact repository, name,
+   description, and color. Re-fetch current state and enforce the taxonomy-definition gate from
+   [github-issue](../github-issue/SKILL.md): require `WRITE`, `MAINTAIN`, or `ADMIN` and the
+   label-specific API capability immediately before the approved mutation. `viewerCanCreateIssues`
+   applies only to issue creation. Approval for an issue or another label does not transfer.
+
+Do not create or change labels, milestones, issues, or local files for a recommendation-only
+request. This skill does not define a repository's taxonomy or automation file locations; a
+consumer wrapper supplies those integrations and local mechanics.

package/skills/revisit-followups/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: revisit-followups
+description: Review recently completed work and repository instructions for genuinely deferred follow-ups, then propose verified issue candidates.
+---
+
+# Revisit follow-ups
+
+Use to turn explicit deferred work into a curated backlog. Read local `AGENTS.md`, `CLAUDE.md`,
+issue policy, and review-record conventions first.
+
+1. Confirm the requested lookback window and collect only explicit deferred-action signals from
+   completed changes, repository instructions, and closed work records.
+2. Reject settled decisions, standing policy, completed checklists, and incidental TODO-like text.
+   A zero-candidate result is valid.
+3. Verify each remaining candidate against the current base, its history, closed-work disposition,
+   existing issues, and active changes before proposing new work.
+4. Group related candidates into self-contained issue drafts that preserve the original evidence and
+   explain why the work remains needed.
+5. Remain read-only unless the caller or consumer wrapper explicitly authorizes issue creation. If
+   authorized, route every candidate through
+   [github-issue](../github-issue/SKILL.md), including its denied-external tracking behavior; do not
+   duplicate repository or label authorization. Then clean up temporary collection artifacts and
+   report skipped, covered, and created items.
+
+Do not assume a review journal format, default lookback, hosting provider, repository, issue
+taxonomy, or confirmation mechanism. Consumer wrappers own those integrations.

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

@@ -0,0 +1,23 @@
+---
+name: static-analysis-checklist
+description: Use when adding, changing, replacing, or removing static-analysis rules, configurations, fixtures, suppressions, allowlists, or repository guards.
+---
+
+# Static analysis checklist
+
+Use when changing a static-analysis invariant. Read local `AGENTS.md`, `CLAUDE.md`, analyzer
+documentation, rule inventory, and fixture conventions before selecting an implementation.
+
+1. State the invariant and search for an existing analyzer, rule, or guard that owns it. Prefer the
+   narrowest established owner over a parallel scanner.
+2. Add positive and negative fixtures before the rule. Cover path routing, parser boundaries, and
+   every allowed exception.
+3. Keep discovery limited to tracked, intended files. Make suppressions and allowlists narrow,
+   justified, and mechanically checked for freshness where practical.
+4. Run the focused fixture test and analyzer, then the local aggregate checks. Keep diagnostics
+   actionable and deterministic.
+5. Update the local inventory or documentation and delete superseded migration artifacts only when
+   the replacement invariant is demonstrably enforced.
+
+This skill does not name analyzer roots, fixture locations, commands, suppression syntax, or
+rollout policy. A consumer wrapper or local instruction file provides them.