vouchington-tooling 2.0.2 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/package.json +2 -2
  2. package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
  3. package/skills/manifest.json +15 -202
  4. package/skills/organize-github-issues/SKILL.md +20 -3
  5. package/skills/pr-description/SKILL.md +9 -65
  6. package/skills/retrospective/SKILL.md +16 -1
  7. package/skills/retrospective-distill/SKILL.md +1 -1
  8. package/skills/retrospective-distill/references/issue-body.md +6 -1
  9. package/skills/review-github-issue-taxonomy/SKILL.md +3 -4
  10. package/skills/triage-loop/SKILL.md +111 -34
  11. package/skills/triage-prs/SKILL.md +26 -28
  12. package/skills/triage-prs/references/feedback.md +14 -2
  13. package/skills/triage-prs/references/rubric.md +4 -4
  14. package/skills/triage-sweep/SKILL.md +26 -23
  15. package/skills/agent-workflow/SKILL.md +0 -72
  16. package/skills/agent-workflow/references/evidence-sweep.md +0 -12
  17. package/skills/agent-workflow/references/four-refs.md +0 -74
  18. package/skills/agent-workflow/references/implementation-and-review.md +0 -4
  19. package/skills/agent-workflow/references/implementation.md +0 -20
  20. package/skills/agent-workflow/references/review-response.md +0 -49
  21. package/skills/agent-workflow/references/review.md +0 -10
  22. package/skills/backend-vitest-test-authoring/SKILL.md +0 -22
  23. package/skills/backend-vitest-test-authoring/references/integration-boundaries.md +0 -10
  24. package/skills/bounded-iteration/SKILL.md +0 -92
  25. package/skills/bounded-iteration/references/sweep-patterns.md +0 -719
  26. package/skills/dependabot/SKILL.md +0 -117
  27. package/skills/dotnet-test-authoring/SKILL.md +0 -24
  28. package/skills/git-commit-checklist/SKILL.md +0 -29
  29. package/skills/github-actions-authoring/SKILL.md +0 -63
  30. package/skills/github-actions-checklist/SKILL.md +0 -118
  31. package/skills/github-issue/SKILL.md +0 -121
  32. package/skills/glide-mq/SKILL.md +0 -52
  33. package/skills/glide-mq/references/lease-patterns.md +0 -44
  34. package/skills/nextjs-vitest-test-authoring/SKILL.md +0 -21
  35. package/skills/nextjs-vitest-test-authoring/references/framework-boundaries.md +0 -9
  36. package/skills/npm-publishing/SKILL.md +0 -72
  37. package/skills/package-json-checklist/SKILL.md +0 -31
  38. package/skills/planning/SKILL.md +0 -37
  39. package/skills/planning/references/impact-discovery.md +0 -11
  40. package/skills/playwright-authoring/SKILL.md +0 -23
  41. package/skills/playwright-authoring/references/browser-reliability.md +0 -9
  42. package/skills/postgres-node-performance-tuning/SKILL.md +0 -35
  43. package/skills/postgres-node-performance-tuning/references/performance-patterns.md +0 -175
  44. package/skills/postgres-node-performance-tuning/references/reading-plans.md +0 -111
  45. package/skills/postgres-partitioning-uuid-v7/SKILL.md +0 -35
  46. package/skills/postgres-partitioning-uuid-v7/references/partition-lifecycle.md +0 -53
  47. package/skills/postgres-schema-design/SKILL.md +0 -31
  48. package/skills/postgres-schema-design/references/naming.md +0 -34
  49. package/skills/postgres-schema-design/references/relations.md +0 -66
  50. package/skills/postgres-schema-design/references/table-shapes.md +0 -78
  51. package/skills/pr-description/references/examples.md +0 -189
  52. package/skills/review-ci-logs/SKILL.md +0 -44
  53. package/skills/revisit-followups/SKILL.md +0 -47
  54. package/skills/stacked-prs/SKILL.md +0 -98
  55. package/skills/stacked-prs/references/drain.md +0 -177
  56. package/skills/stacked-prs/references/gh-stack.md +0 -147
  57. package/skills/static-analysis-checklist/SKILL.md +0 -32
  58. package/skills/storybook-authoring/SKILL.md +0 -22
  59. package/skills/storybook-authoring/references/component-coverage.md +0 -9
  60. package/skills/swift-test-authoring/SKILL.md +0 -23
  61. package/skills/swift-test-authoring/references/network-test-doubles.md +0 -9
  62. package/skills/test-authoring/SKILL.md +0 -27
  63. package/skills/test-authoring/references/core-practice.md +0 -16
  64. package/skills/test-authoring/references/dependency-boundaries.md +0 -38
  65. package/skills/test-authoring/references/tautological-tests.md +0 -47
  66. package/skills/triage-loop/references/shepherd.md +0 -64
  67. package/skills/vitest-test-authoring/SKILL.md +0 -22
  68. package/skills/vitest-test-authoring/references/mock-boundaries.md +0 -9
@@ -1,117 +0,0 @@
1
- ---
2
- name: dependabot
3
- description: Configure Dependabot coverage, grouping, cooldowns, and trusted automation.
4
- ---
5
-
6
- # Dependabot policy
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/dependabot/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Read every applicable `AGENTS.md`, then the repository's dependency, CI, release,
13
- and branch-protection docs. The consumer wrapper owns the accepted cooldown, package roots,
14
- first-party publishers, manual-update exceptions, runner policy, required checks, and secret source.
15
-
16
- ## Cover the dependency graph
17
-
18
- - Inventory tracked manifests, lockfiles, Dockerfiles, workflow actions, infrastructure roots, and
19
- any companion dependency bot. Add one Dependabot update entry per supported ecosystem and
20
- manifest root. Do not create a second owner for a dependency already assigned elsewhere.
21
- - Schedule version checks daily. Set `cooldown.default-days` to the consumer's release delay, or
22
- seven days when local policy does not choose another value. Cooldown applies to version updates,
23
- not security updates.
24
- - Set `open-pull-requests-limit: 5` on every update entry. The limit is per entry and covers
25
- version updates only. Use a lower value only when a serialized repair or manual validation path
26
- requires it.
27
- - Keep security updates enabled and immediate. Do not add an age gate that delays vulnerability
28
- fixes.
29
-
30
- ## Group package families
31
-
32
- Group packages that share one compatibility family or release train. Do not group by version type.
33
- Use manifests, peer dependencies, lockfiles, and upstream release practice to decide what moves
34
- together.
35
-
36
- ```yaml
37
- cooldown:
38
- default-days: 2
39
- exclude: ['@acme/*', 'acme-cli']
40
- groups:
41
- first-party:
42
- patterns: ['@acme/*', 'acme-cli']
43
- oxc:
44
- patterns: ['oxlint', 'oxfmt', 'oxlint-tsgolint']
45
- vitest:
46
- patterns: ['vitest', '@vitest/*', '@vitejs/*']
47
- react:
48
- patterns: ['react', 'react-dom']
49
- react-security:
50
- applies-to: 'security-updates'
51
- patterns: ['react', 'react-dom']
52
- react-email:
53
- patterns: ['react-email', '@react-email/*']
54
- ```
55
-
56
- - Name each group for the package, toolchain, framework, or verified release family. Prefer a narrow
57
- namespace or prefix wildcard such as `@vitest/*` when that wildcard is one family. Put more
58
- specific families before broader ones.
59
- - Do not add generic groups such as `other-minor-and-patch`, `minor-and-patch`,
60
- `security-minor-and-patch`, or `security-updates`. Do not use `patterns: ['*']` to force every
61
- update into a group. Narrow family wildcards are expected. Leave unrelated packages ungrouped.
62
- - Omit `update-types` so a family receives major, minor, and patch updates. Major updates are never
63
- auto-merged by the workflow. Leaving majors out of the group splits the release train.
64
- - Groups default to `applies-to: version-updates`. When the same family is also safe to upgrade
65
- together for security fixes, add a separate group such as `react-security` with the same patterns
66
- and `applies-to: security-updates`. Do not combine unrelated vulnerability fixes into one group.
67
- - Keep verified first-party packages in a `first-party` group. For a namespace the owner wholly
68
- controls, use its scoped wildcard, such as `@acme/*`. List unscoped packages by exact name.
69
- - Keep first-party patterns in `cooldown.exclude` so those updates have zero-day eligibility, while
70
- third-party packages keep the release delay. A grouped pull request is auto-mergeable only when
71
- every included update is eligible.
72
-
73
- ## Exempt verified first-party releases
74
-
75
- - Use `cooldown.exclude` only for first-party packages whose owning repository and default-branch
76
- release workflow have been verified.
77
- - That workflow must publish the package with OIDC, `id-token: write`, and no long-lived registry
78
- token.
79
- - Use a namespace wildcard only when the owner controls the whole namespace and intends future
80
- packages to inherit the exemption. Otherwise use exact package names.
81
- - Keep the consumer-owned registry, documentation, cooldown exclusions, and `first-party` group in
82
- sync.
83
-
84
- ## Preserve the trust boundary
85
-
86
- - Use a trusted default-branch `pull_request_target` workflow only for metadata inspection and the
87
- minimal auto-merge mutation.
88
- - Revalidate the live pull request, Dependabot identity, default base, same-repository
89
- `dependabot/` head, and immutable base and head SHAs.
90
- - Do not check out or execute pull-request code in that privileged workflow. Pin external actions
91
- per local policy.
92
- - Auto-merge only a verified semver patch, or a stable minor whose old and new majors are both at
93
- least 1. Majors, pre-1.0 minors, prereleases, downgrades, malformed or inconsistent metadata, and
94
- consumer-declared manual ecosystems need a human. The workflow never merges majors; the triage
95
- loop may merge them under its grant, as triage-sweep Phase A describes.
96
- - Enable platform auto-merge. Do not auto-approve. Required checks and branch rules remain the gate.
97
- - Store `DEPENDABOT_AUTOMERGE_TOKEN` as a Dependabot secret, not only as an Actions secret. Grant
98
- only the Contents and Pull requests access needed to enable or disable auto-merge. Fail an
99
- eligible mutation visibly when the token is missing or underprivileged.
100
- - A Dependabot-triggered workflow cannot assume ordinary Actions secrets or trusted OIDC access.
101
- Copy only the narrow credentials mandatory tests need into Dependabot secret scope.
102
- - For cloud, deployment, production, or other privileged checks, keep credential-free validation
103
- running and mark the trusted portion skipped or not applicable for Dependabot. A required fan-in
104
- job must distinguish that intentional state from an unexpected missing credential.
105
-
106
- ## Validate and roll out
107
-
108
- - Parse the YAML. Run the repository's workflow checker and policy tests.
109
- - Inspect the diff for uncovered manifests, overlapping groups, broad exemptions, secret exposure,
110
- and pull-request code crossing a privileged boundary.
111
- - Verify repository settings for dependency security updates and auto-merge.
112
- - After the configuration reaches the default branch, read Dependabot logs for every configured
113
- root. Check a representative patch, minor, major, security update, manual update, and
114
- missing-secret path.
115
-
116
- Consumer wrapper owns: cooldown, package roots, first-party publishers, manual-update exceptions,
117
- runner policy, required checks, and secret source.
@@ -1,24 +0,0 @@
1
- ---
2
- name: dotnet-test-authoring
3
- description: Author .NET unit, application, and integration tests.
4
- ---
5
-
6
- # .NET test authoring
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/dotnet-test-authoring/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Apply [test-authoring](../test-authoring/SKILL.md).
13
-
14
- - Place a test at the narrowest layer that proves the behavior.
15
- - Batch native or external selection where the project requires it.
16
- - Isolate process and filesystem state.
17
- - Assert a serialized contract. Do not assert a private implementation detail.
18
- - Keep a helper typed and reusable only when it removes repeated setup without hiding an
19
- expectation.
20
- - Keep portable library tests separate from rendered application tests.
21
- - Batch compatible native targets in one selection pass so one shared build validates that source
22
- set.
23
-
24
- Consumer wrapper owns: solution layout, test frameworks, native dependencies, and coverage policy.
@@ -1,29 +0,0 @@
1
- ---
2
- name: git-commit-checklist
3
- description: Verify scope, checks, and local policy before committing.
4
- ---
5
-
6
- # Git commit checklist
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/git-commit-checklist/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Use before every commit. Read local `AGENTS.md`, contribution guidance, and hook
13
- output first; they own commit format, required trailers, file-size limits, and validation commands.
14
-
15
- 1. Inspect `git status` and the complete diff. Stage only files that implement the accepted task.
16
- 2. Confirm new or changed source and test files meet local size, formatting, and generated-file
17
- policy. Do not commit credentials, build outputs, editor state, or unrelated changes.
18
- 3. Run focused tests and required local checks. Record any permitted skipped check and why.
19
- 4. Use the repository's conventional subject and required body/trailers. If code was extracted,
20
- record the required provenance in the commit body.
21
- 5. Re-read the staged diff and commit message before committing. Do not amend another author's
22
- work or rewrite history unless local policy and explicit authorization allow it.
23
-
24
- Local instructions or the consumer wrapper own: branch names, file-size budgets, commit
25
- conventions, pull-request templates, and push commands.
26
-
27
- When an authorized rebase push may race another writer, capture the remote tip before fetching and
28
- push with an exact expected-tip lease. A lease against a freshly fetched tracking ref can overwrite
29
- the concurrent change it was meant to protect.
@@ -1,63 +0,0 @@
1
- ---
2
- name: github-actions-authoring
3
- description: Design event-driven GitHub Actions without remote-state polling.
4
- ---
5
-
6
- # GitHub Actions authoring
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/github-actions-authoring/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Never poll in CI. A workflow reacts to a state transition. Read
13
- [github-actions-checklist](../github-actions-checklist/SKILL.md) first, then every applicable
14
- `AGENTS.md`. Repository-local policy and the consumer wrapper own runner labels,
15
- permissions, action pins, concurrency, secrets, and required-check names.
16
-
17
- ## Design the event graph
18
-
19
- - Name the producer, the durable transition it emits, and the consumer that owns the next action.
20
- - Use `needs` for jobs in one workflow. Use `workflow_call` when the caller must await a reusable
21
- workflow. When a consumer must run after failure or skip, give it an explicit status condition and
22
- read `needs.<job>.result`. The implicit success condition skips it otherwise.
23
- - Use `workflow_run` when a completed workflow is the trusted event boundary. Validate the source
24
- workflow, repository, branch or pull-request head, conclusion, and artifacts before acting.
25
- - The `workflow_run` receiver must already exist on the default branch. GitHub chains at most three
26
- `workflow_run` levels. Plan that rollout, and collapse a deeper chain into one DAG.
27
- - Use `repository_dispatch` for a cross-repository transition or an authenticated external callback.
28
- Authenticate the sender, pass immutable correlation data, validate it against the source, and make
29
- duplicate delivery safe. The receiver must already exist on the default branch before senders are
30
- enabled.
31
- - Prefer a provider-native completion event, callback, queue, or state-machine transition for a
32
- deployment or service.
33
- - A scheduled reconciliation workflow may repair a missed event. It inspects one snapshot and exits.
34
- It does not wait for convergence.
35
-
36
- ## Persistent workspaces
37
-
38
- Apply the persistent-workspace rules in
39
- [github-actions-checklist](../github-actions-checklist/SKILL.md).
40
-
41
- ## Reject polling designs
42
-
43
- - Do not add a sleep-and-read loop, a repeated query of a run, check, deployment, lease, or
44
- service, a CLI waiter, or a recursive redispatch whose purpose is to watch remote state change.
45
- - A timeout caps cost. It does not make polling event-driven.
46
- - If the producer cannot emit a usable event, add the bridge at the producer or provider boundary
47
- and let that bridge dispatch the correlated completion event.
48
- - Bounded retries are allowed only for the same failed operation, and only when the failure is
49
- transient and the operation is idempotent.
50
- - A local process readiness check is allowed when that process runs inside the job and cannot emit
51
- a workflow event.
52
- - Neither exception allows repeated observation of remote state.
53
-
54
- ## Validate the result
55
-
56
- - Test accepted, rejected, duplicate, stale, and out-of-order events.
57
- - Preserve required-check names. Prove that every terminal producer outcome causes one terminal
58
- consumer outcome.
59
- - Run the local workflow checker and affected tests. Inspect the event graph for credentials
60
- crossing an untrusted boundary, a missing correlation field, and any remaining polling path.
61
-
62
- Consumer wrapper owns: runner labels, permissions, action pins, concurrency, secrets, and
63
- required-check names.
@@ -1,118 +0,0 @@
1
- ---
2
- name: github-actions-checklist
3
- description: Check Actions triggers, permissions, runners, pins, and deadlines.
4
- ---
5
-
6
- # GitHub Actions checklist
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/github-actions-checklist/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Use before editing a workflow or composite action. Repository-local instructions own runners,
13
- approved action pins, concurrency names, secrets, permissions, and workflow-only pull-request rules.
14
- Apply this baseline unless a stricter local rule overrides it.
15
-
16
- ## Triggers and required checks
17
-
18
- - Use `pull_request` for pull-request workflows in private repositories.
19
- - Reserve `pull_request_target` for base-owned orchestration in a public repository, or for a
20
- narrowly scoped Dependabot or Renovate workflow.
21
- - A pull-request CI workflow must not subscribe to `ready_for_review` or `converted_to_draft`
22
- unless a job changes what it does on that transition. Those activity types start another run for
23
- the same head, and `cancel-in-progress: true` replaces checks that already passed. Dependabot
24
- auto-merge may keep `ready_for_review`: it enables merge and does not rerun tests.
25
- - A privileged workflow must not check out or execute untrusted pull-request content.
26
- - When changing orchestration, load
27
- [github-actions-authoring](../github-actions-authoring/SKILL.md). Do not poll remote workflow,
28
- deployment, lease, service, or health state.
29
- - Required checks must be actual workflow jobs that run or aggregate the work they report.
30
- - Workflow code must not create or publish check runs or commit statuses to synthesize a required
31
- context, copy another workflow's conclusion, or bypass the event graph.
32
- - An external CI or analysis integration may report its own result. Do not relay GitHub Actions
33
- work through its API.
34
-
35
- ## Tests, concurrency, and timeouts
36
-
37
- - On `main`, or the consumer's configured default branch, split test jobs by domain, such as web
38
- and backend. Keep required-check job names stable. Add a bounded fan-in job only when the merge
39
- contract needs one combined result.
40
- - Serialize test runs for the same pull request or default branch with one stable concurrency group.
41
- - For pull requests, set `cancel-in-progress: true`. On `main`, or the consumer's configured default
42
- branch, set `cancel-in-progress: false` so the active run finishes before the newest pending
43
- revision starts. GitHub may replace an older pending main run with the newest pending revision;
44
- preserving every intermediate queued revision is not required.
45
- - When one workflow handles both events, make `cancel-in-progress` conditional on the pull-request
46
- event. Keep the pull-request number or branch ref in the group.
47
- - Give every concrete job `timeout-minutes` of at most 30 minutes. A top-level `jobs.<job_id>.uses`
48
- caller cannot accept `timeout-minutes`; set it on every concrete job in the called workflow.
49
- - If the operation cannot finish inside that bound, split it into event-driven phases. Lowering or
50
- moving the timeout does not fix the design. Preserve a required job or check name with a bounded
51
- fan-in job when the split would otherwise change the merge contract.
52
- - Each underlying phase also has a deadline of no more than 30 minutes and supports cancellation,
53
- rollback, or an explicit terminal retained or recovery state. A callback may report completion. It
54
- must not hide a longer-running operation in another service.
55
- - Keep each job's `timeout-minutes` below any hard platform limit of its runner so the job's own
56
- cancellation fires first and `always()`/`cancelled()` cleanup steps still run. Example: no more
57
- than 14 minutes on a runner with a 15-minute hard cap that `timeout-minutes` cannot raise.
58
- - Give every long-running, network-bound, or waiting step its own `timeout-minutes` inside the job
59
- budget. Bound every network call, such as `curl --connect-timeout … --max-time …`.
60
-
61
- ## Runners and persistent workspaces
62
-
63
- - Prefer GitHub-hosted runners for public and private repositories. Choose the smallest hosted
64
- runner the job fits, such as `ubuntu-slim` for a short job that needs no Docker daemon. Use a full
65
- VM or native-architecture runner only for work the smaller runner cannot do. A consumer that still
66
- requires self-hosted or disposable runners names its approved labels in repository-local policy.
67
- - Ephemeral hosted runners start from a clean workspace. Do not add workspace-cleanup steps for
68
- them, and check out with `persist-credentials: false` unless a later step must push with that
69
- token.
70
- - Moving a job from a self-hosted or other persistent runner to a GitHub-hosted one drops every
71
- piece of runner-local state the job assumed was already there. Audit browser installs (a
72
- Playwright, Cypress, or Puppeteer cache), package-manager stores (pnpm/npm, Go modules, a Rust
73
- `target/` directory, Gradle), `apt-get install` steps that used to be a no-op because the package
74
- was already present, and Docker image pulls that used to hit a warm local image store. A comment
75
- that a tool "persists between runs so caching is not needed" describes the old runner and becomes
76
- false the moment `runs-on` changes; replace that assumption with a keyed `actions/cache` step
77
- instead. Re-derive `timeout-minutes` from a real passing run on the new runner rather than
78
- carrying over a budget calibrated on a warm host.
79
- - A persistent workspace checks out the full tree. Do not configure sparse checkout. Enforce that
80
- with a YAML-aware check over intended tracked workflow and action files, with accepted and
81
- rejected fixtures.
82
- - Fix workspace ownership at the producer. A writable workspace bind mount uses a non-root identity
83
- whose ownership and write access match the runner workspace.
84
- - Do not add an unconditional pre-checkout workspace-wide permission or ownership traversal.
85
- - Migrate a contaminated workspace once, while the runner is drained.
86
- - Routine repair may cover bounded known generated paths. A workspace-wide fallback must be
87
- failure-gated, same-filesystem, directory-only, and batched,
88
- and must record path count and timing.
89
-
90
- ## Pinning
91
-
92
- - Pin every repository-backed external `uses:` reference — anything other than a local `./...`
93
- action or a `$/` self-repository reference — to a full lowercase 40-character Git SHA and its
94
- immediate machine-maintainable version comment, such as `# v4.2.0`, so Dependabot can update both.
95
- - A `$/` reference is the same repository at the running commit. It must not include an `@ref`.
96
- - Pin `docker://...` actions to an immutable `@sha256:` image digest. Keep GitHub Actions dependency
97
- updates enabled.
98
- - Workflow tests and fixtures must not assert an action dependency's exact SHA or version. Assert
99
- the action identity and Git SHA shape, or read the ref from the workflow under test.
100
- - This does not prohibit asserting an exact source revision in `with.ref` when exact-head checkout
101
- is a workflow security invariant.
102
-
103
- ## Edit
104
-
105
- 1. Read every applicable `AGENTS.md` from the repository root through the workflow,
106
- plus CI docs and callers. On conflict, apply the closest instruction. Name trusted inputs,
107
- untrusted inputs, and every credential boundary.
108
- 2. Give each job the least permissions it needs. Keep untrusted pull-request content out of shell
109
- interpolation, privileged tokens, and write-capable steps.
110
- 3. Apply this baseline and any stricter consumer policy. Keep checkout refs, artifact boundaries,
111
- caches, and concurrency explicit.
112
- 4. Validate changed YAML with the local workflow checker and run the affected tests or scripts.
113
- Update local CI docs when behavior or operator expectations change.
114
- 5. Review the diff for privilege escalation, secret exposure, unsafe quoting, unsupported runner
115
- assumptions, and unreachable paths.
116
-
117
- Consumer wrapper owns: runner labels, action SHAs, workflow directories, concurrency scheme, and
118
- release policy.
@@ -1,121 +0,0 @@
1
- ---
2
- name: github-issue
3
- description: Search, write, and classify GitHub issues within live authorization.
4
- ---
5
-
6
- # GitHub issues
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/github-issue/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Use for durable follow-ups and pull-request linkage. Read local `AGENTS.md`, issue
13
- templates, and repository-routing policy before any remote mutation.
14
-
15
- ## Mutation authority
16
-
17
- - Caller authorization is required before any issue or taxonomy mutation. A credential does not
18
- grant scope.
19
- - Resolve the authenticated identity, current repository, and requested target. Do not assume an
20
- owner prefix or visibility.
21
- - Immediately before every write, refetch the exact target. Its canonical identity must still
22
- match, and the repository must not be archived.
23
- - Issue operations require issues to be enabled and `viewerPermission` of `TRIAGE`, `WRITE`,
24
- `MAINTAIN`, or `ADMIN`. Issue creation additionally requires `viewerCanCreateIssues`.
25
- - Applying existing metadata to a pull request uses that same permission set and does not require
26
- issues to be enabled.
27
- - Creating, changing, or deleting taxonomy definitions requires `WRITE`, `MAINTAIN`, or `ADMIN`
28
- plus the operation-specific API capability. Creating, renaming, or closing a project requires
29
- project-write.
30
- - Insufficient permission or capability, missing or inaccessible data, an identity change, or a
31
- mismatch is a hard deny. Approval cannot override it.
32
- - Adding an item to an existing project uses the same permission set as applying existing metadata,
33
- plus project-write. That add mutates project membership and needs no separate approval.
34
- - Missing project scope or capability denies the project step only. Skip it, report the gap, and
35
- do not work around it. The issue and its other metadata still proceed.
36
-
37
- ## Denied external target
38
-
39
- - Do not write to a denied external creation target.
40
- - Search for, then create or reuse, a tracking issue in the current repository or a
41
- consumer-selected tracker. Immediately before that write, refetch the destination and apply the
42
- issue-operation gate above.
43
- - Include the intended upstream repository and a copy-ready report.
44
- - Before naming that upstream repository, resolve it and compare the returned canonical name with
45
- the name being written. A rename redirect resolves under the stale name, so existence is not
46
- identity. This check is report accuracy, not the hard-deny mismatch above: write the canonical
47
- name. When the name does not resolve, route the follow-up to the current repository and do not
48
- name the unreachable target.
49
- - Before copying details to a less-restricted destination, remove private repository identity,
50
- paths, links, code, and findings. If redaction would make the report unusable, require explicit
51
- destination approval or return the draft without mutation.
52
- - Authorization to file the external issue includes this tracking fallback unless the caller opts
53
- out. Report the reroute. If no tracker passes, return the draft without mutation.
54
- - Do not fall back silently, and do not fall back to an unverified repository.
55
-
56
- ## Issue workflow
57
-
58
- 1. Search open issues and relevant closed issues in the destination. Return a likely duplicate
59
- instead of filing one. Verify the paths and current behavior the issue names.
60
- 2. Before editing, commenting, relating, closing, or otherwise changing state, refetch the issue
61
- and its discussion. Confirm the mutation is still authorized and supported. Close only when the
62
- documented outcome and acceptance evidence show the work is resolved. Otherwise leave state
63
- unchanged and report the gap.
64
- 3. Write a self-contained issue: problem, desired outcome, ownership boundaries, concrete areas,
65
- validation, and external context. A discovered blocker does not widen implementation scope.
66
- - Before absorbing a newly discovered blocker, require the calling workflow to reproduce it
67
- against the refreshed default branch and provide the evidence, then search for an existing fix
68
- or issue. If a fix resolves it, report it so the caller can use and retest it. Otherwise ask
69
- whether to widen the accepted scope or only link or record a follow-up. Filing records work;
70
- it does not amend the accepted plan or authorize implementation.
71
- - A stop condition in an issue names a real decision for a human. Adding or changing an index,
72
- or a rewrite that returns the same rows, is never one: the worker makes the change and records
73
- the plan before and after.
74
- - Verify every existing path in `## Files / areas` against `HEAD`. Mark a proposed path `New`
75
- and verify its owning parent or module. Reject absolute and parent-traversal (`..`) paths. For
76
- a target outside the current checkout, verify only redacted remote metadata through the
77
- Contents API.
78
- 4. Fetch the complete live taxonomy, including open projects. Apply matching existing labels and a
79
- selected existing milestone with no separate approval.
80
- - Use an existing open project for strategic, initiative-level tracking, and a milestone for
81
- repo-local release or sequencing. Choose by the initiative, not by how many repositories it
82
- touches. A single-repo strategic initiative can have a project. An initiative can have both.
83
- An issue belongs to at most one project, and not every issue needs one.
84
- - Before adding a project item, check that item and any item the project's automation could
85
- pull in with it, such as a parent issue's sub-issues. If any already belongs to a different
86
- project, skip the add and report the conflict.
87
- - Adding an item to an existing, described project needs no separate approval. Creating,
88
- renaming, or closing a project is a separate taxonomy operation, as is creating a milestone.
89
- - Missing project scope or permission skips the project step. Report the gap and do not work
90
- around it.
91
- - Do not set a project status that closes the issue unless closing is separately authorized.
92
- GitHub's Auto-close issue workflow closes the issue when status becomes Done.
93
- - When a plan issue's source already has a milestone, apply that same milestone. When the source
94
- already has a project, refetch memberships and apply that project only when exactly one
95
- accessible open membership exists. Otherwise skip the project and report the conflict.
96
- - Omit a missing optional milestone. A missing required milestone blocks the issue. Omit a
97
- declined optional label. A missing required label blocks the issue.
98
- - For a missing label, use
99
- [review-github-issue-taxonomy](../review-github-issue-taxonomy/SKILL.md) and get explicit
100
- approval of the exact repository, name, description, and color before creating it.
101
- 5. Refetch the created or updated issue and verify metadata, including project membership. After a
102
- project add, re-read the project: automation can pull in more items, including into a second
103
- project. Report a partial failure without retrying creation. Preserve history and report the
104
- action, URL, labels, milestone, and project.
105
- 6. Link a pull request with a closing reference only when it fully resolves the issue. Fully
106
- qualify cross-repository references. Pull-request creation authority stays separate.
107
- 7. Use native sub-issues only for a real hierarchy, blocked-by only for a known dependency, and
108
- prose links for related work. Read every created relationship back.
109
-
110
- For a batch, preflight every entry before writing any issue. One invalid entry fails the whole
111
- batch. A partial transport failure stops further creation and reports every issue already created.
112
- Do not retry an entry that succeeded.
113
-
114
- ## Bounded output
115
-
116
- - A search returns at most five `#N: title -- url` lines.
117
- - A near-duplicate returns `Duplicate of #N: <url>`.
118
- - A mutation returns the action, URL, labels, and verification, plus milestone and project when set.
119
-
120
- Consumer wrapper owns: repository allowlist, taxonomy, issue template, credential, and CLI wrapper.
121
- It may tighten this gate and may not weaken it.
@@ -1,52 +0,0 @@
1
- ---
2
- name: glide-mq
3
- description: Design glide-mq queue jobs, ordering lanes, worker concurrency, and cross-job caps when writing or reviewing queue producers, workers, and dispatchers.
4
- ---
5
-
6
- # glide-mq queues
7
-
8
- Read applicable `AGENTS.md` and the repository's local queue adapter when present.
9
- Local policy overrides these portable conventions.
10
-
11
- Names below are the glide-mq API: the job option `ordering: { key, concurrency }`, the worker
12
- option `concurrency`, `lockDuration`, and `job.moveToDelayed(timestamp)`. Read
13
- [lease patterns](references/lease-patterns.md) for the lease shape.
14
-
15
- 1. **Every shared-queue job sets `ordering`.** An ungrouped job in a shared queue competes for
16
- every worker slot, so a flood of it starves other families. Give each job an
17
- `ordering.key` prefixed with its domain name and an explicit `ordering.concurrency`.
18
- 2. **`ordering.concurrency` is a global cap; the worker `concurrency` is per process.** The key's
19
- cap holds across all workers and processes. The worker option only bounds one process's
20
- active jobs. Never size lane caps to sum to the worker option. Take caps from runtime
21
- configuration, and give batched families a low cap.
22
- 3. **Group FIFO ignores `priority`.** Jobs sharing an ordering key run in enqueue order whatever
23
- their priority. Work that must not wait behind a flood, and dispatchers that rely on
24
- priority, get their own lane. Put work that outsiders can flood in a lane of its own.
25
- Ordering keys are the orchestration layer; add none on top.
26
- 4. **`globalConcurrency` caps the whole queue.** The worker option `globalConcurrency` limits
27
- every job on the queue together, so on a shared queue it throttles all families at once. Use
28
- ordering lanes for per-family caps, and use `globalConcurrency` only when one resource bounds
29
- the whole queue.
30
- 5. **A job moved to delayed keeps its ordering slot until it completes.** A deferred job still
31
- counts against `ordering.concurrency`, so deferred jobs can fill a key and block ready work
32
- on it. A cap that must survive deferral belongs in a token-owned lease, released before
33
- `moveToDelayed`, not in the ordering key. Never fix starvation by raising the key's
34
- concurrency: overlap grows and the same number of deferred jobs still fill the slots.
35
- 6. **Lease mechanics.** Acquire a token-owned lease with `SET key token NX PX ttl` before the
36
- guarded work. Set the TTL at or above the job's `lockDuration`, renew it while the job runs,
37
- and release it with compare-and-delete in `finally`. On contention, `moveToDelayed` only this
38
- job by a short, bounded, jittered delay so it keeps its id, cursor, and dedup. Release the
39
- lease before any `moveToDelayed` for quota deferral. Reuse the repository's lease helper
40
- rather than adding a second. See [lease patterns](references/lease-patterns.md).
41
- 7. **Job count is not a KPI.** Many small jobs with a dispatcher and a sweep are fine. Do not
42
- merge or remove jobs to cut the count. Judge a design by model calls or spend per item and by
43
- how simply the jobs share a lifecycle.
44
-
45
- Dispatchers, paged fan-out, and job-id deduplication follow
46
- [bounded iteration](../bounded-iteration/SKILL.md). A lease for work that spans an external call
47
- replaces holding a PostgreSQL transaction open across it, and PostgreSQL advisory locks are never
48
- used; see
49
- [performance patterns](../postgres-node-performance-tuning/references/performance-patterns.md).
50
-
51
- Consumer policy owns queue names, lane keys, caps and their configuration source, the lease helper,
52
- and enforcement configuration.
@@ -1,44 +0,0 @@
1
- # Lease patterns
2
-
3
- A lease caps work across jobs and survives deferral, which an `ordering` slot does not: a job
4
- moved to delayed keeps its slot until it completes.
5
-
6
- ## Acquire, renew, release
7
-
8
- ```ts
9
- const token = randomUUID()
10
- // SET leaseKey token NX PX ttlMs -> null when another job holds the lease
11
- if (!(await setIfAbsent(leaseKey, token, ttlMs))) {
12
- return job.moveToDelayed(Date.now() + jitteredDelayMs) // this job only; never falls through
13
- }
14
- try {
15
- // renew while running, e.g. every ttlMs / 3, only while the stored value equals token
16
- await doGuardedWork()
17
- } finally {
18
- await compareAndDelete(leaseKey, token) // script: delete only when the value equals token
19
- }
20
- ```
21
-
22
- - The TTL is at least the job's `lockDuration`. A shorter lease can expire while the job is
23
- still active, and a second job then enters the guarded section.
24
- - Renewal and release are scripts that compare the stored value with the token. A plain `DEL`
25
- can remove a lease another job has since acquired.
26
- - The delay on contention is short, bounded, and jittered so deferred jobs do not wake together.
27
- `moveToDelayed` defers this job only and keeps its id, cursor, and dedup.
28
-
29
- ## Quota deferral
30
-
31
- When the work defers itself for a quota or rate, release the lease first, then call
32
- `moveToDelayed`. `moveToDelayed` never returns, so a release placed after it does not run, and a
33
- deferred job that keeps the lease blocks the jobs the lease exists to admit.
34
-
35
- ```ts
36
- await compareAndDelete(leaseKey, token)
37
- await job.moveToDelayed(resumeAt)
38
- ```
39
-
40
- ## Why not the ordering key
41
-
42
- Concurrency 1 on a key serializes ready work but lets deferred jobs hold the slot. Raising it to
43
- 2 lets two guarded sections overlap, and two deferred jobs still fill both slots. A lease
44
- separates the cap on active work from the queue-order slot.
@@ -1,21 +0,0 @@
1
- ---
2
- name: nextjs-vitest-test-authoring
3
- description: Test Next.js components, routes, and server boundaries with Vitest.
4
- ---
5
-
6
- # Next.js Vitest test authoring
7
-
8
- Read applicable `AGENTS.md` and their declared adapter alias, otherwise
9
- `.agents/skills/nextjs-vitest-test-authoring/SKILL.md` from the repository root if present.
10
- Local policy overrides these defaults; do not reload an already-read adapter or canonical skill.
11
-
12
- Apply [vitest-test-authoring](../vitest-test-authoring/SKILL.md) first.
13
-
14
- - Mock framework navigation, headers, and server-only boundaries at the framework edge.
15
- - Test component behavior through rendered output and user-visible state.
16
- - Keep API-response fixtures representative. Do not test framework internals.
17
- - Use a browser test for behavior the test runtime cannot represent.
18
- - Read [framework boundaries](references/framework-boundaries.md) for module shape and server-only
19
- cases.
20
-
21
- Consumer wrapper owns: framework mock helpers, render libraries, and route fixture conventions.
@@ -1,9 +0,0 @@
1
- # Framework boundaries
2
-
3
- Mock framework navigation, headers, cookies, and server-only APIs at the framework edge, not inside
4
- the component or route under test. Preserve typed module shape and use the consumer's shared mocks
5
- when they exist. Build API responses with typed factories rather than inline partial objects.
6
-
7
- Use direct rendering for component behavior. If request scope, hydration, browser APIs, or server
8
- module resolution cannot be represented faithfully, move the assertion to an integration or browser
9
- test instead of widening a unit-test mock.