audit-convex
Skill381 starsChanged 10 days agoISCView on GitHub
Keep Confect compatible with stable Convex releases and audit new Convex features, implementing bounded additions and tracking unresolved gaps
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- create-changesetSkill
- effectSkill
- managing-prereleasesSkill
- release-docsSkill
- upgrade-internal-depsSkill
- upgrade-published-depsSkill
- upgrade-runtime-pinsSkill
- writing-commit-messagesSkill
- writing-technical-documentationSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
14 rules. About 0 are common, 9 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 8
Check both compatibility with new Convex releases and whether their new public APIs have Confect equivalents.
- Very specific: line 24
Read AGENTS.md, REVIEW.md, and upgrade-published-deps before editing.
- Distinctive: line 34
If another run owns the same work, leave it to that run rather than duplicate it.
- Distinctive: line 36
Read npm metadata for stable releases of the in-scope packages, including publication times and peer requirements.
- Distinctive: line 40
Read the SDK changelog, each updated companion package's release notes, and Convex product updates.
- Distinctive: line 64
Never mark unavailable sources as reviewed or advance their checkpoints.
- Distinctive: line 80
Do not exclude a public API because native access works, existing tests pass, or implementation is inconvenient.
- Distinctive: line 85
Keep deferred work in the tracker with its upstream version or announcement, impact, proposed scope, and linked issue or PR.
- Very specific: line 96
Update compatible dependencies, pins, and overrides together and confirm the versions actually resolved.
- Very specific: line 99
Treat 0.x minor releases as potentially breaking.
- Very specific: line 116
Use the project's PR creation tool for new PRs targeting main.
- Distinctive: line 120
Update the tracker only when reviewed source checkpoints, findings, evidence, decisions, or delivery state change.
- Distinctive: line 125
If nothing changed, create no branch or PR and end silently.
- Distinctive: line 127
Never merge, enable auto-merge, publish packages, or deploy production.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Audit Convex compatibility and features
Check both compatibility with new Convex releases and whether their new public APIs have Confect equivalents. Equivalent Effect-based APIs count; requiring a caller to use a raw Convex client or context is interoperability, not Confect API parity. Preserve explicit user-approved exclusions, such as legacy document ID conversion, rather than reopening them under the general parity goal.
This workflow runs as a Capy automation.
Scope and shared policy
Own convex, convex-test, convex-helpers, and the @convex-dev/* packages
already declared in this workspace. Discover their manifests, development pins,
peer ranges, overrides, and fixtures rather than relying on a fixed location
list. Do not add unused ecosystem packages or upgrade unrelated dependencies.
The general dependency upgrade skills delegate these packages to this skill.
Read AGENTS.md, REVIEW.md, and upgrade-published-deps before editing. Apply
that skill's release-note, range, peer-compatibility, migration-limit,
verification, and changeset policies to this scope. This skill's feature audit
and quiet no-change behavior replace its dependency-only stopping rule.
Discover releases and resume unfinished work
- Fetch fresh
mainand inspect existing open PRs and active audit runs before starting work. Reuse an appropriate open Convex PR; do not race its active author, mutate an unrelated dependency PR, or push to a merged or closed PR. If another run owns the same work, leave it to that run rather than duplicate it. Check the PR's state again before pushing. - Read npm metadata for stable releases of the in-scope packages, including publication times and peer requirements. Skip prerelease versions and respect the repository's release-age policy. A changelog's unreleased section is not evidence that a version is published.
- Read the SDK changelog, each updated companion package's release notes, and Convex product updates. Follow relevant official documentation links. Backend features can ship without an npm version change, so do not stop just because dependency pins are current.
- Read tracker #800, the canonical inventory for historical gaps and new releases. Maintain the format in tracker-template.md, preserving human notes and decisions. If the issue cannot be read, report the access blocker rather than creating a competing tracker. Its source-review checkpoints record what was examined, not what has been implemented or published.
- Preserve the imported CONF-85 inventory, its source evidence, explicit scope
decisions, and existing work ownership. Historical IDs and the first release
audit's IDs overlap: keep their source namespaces and aliases. Do not discard
old gaps because they predate the release lookback or their dependency upgrade
already merged. If an item was not reconciled against current code, mark it
unassessedrather than copying a stale implementation claim. - Review releases and announcements since the successful checkpoints, and unresolved items whose code, upstream contract, linked work, or decision has changed. Do not re-audit every unchanged historical gap each day. Consider bounded, unowned backlog work under the implementation policy below, but do not start large historical features without a design decision. When no source checkpoint exists, review the pinned release, all newer stable releases, and the preceding 30 days of product updates, recording the limited coverage. Never mark unavailable sources as reviewed or advance their checkpoints.
Assess features, not just versions
For each relevant addition, deprecation, or behavior change, record one of:
- Already supported: identify the Confect-specific API or equivalent Effect representation, its context restrictions, and relevant implementation/tests. Raw context/client access alone does not qualify. Add focused regression coverage when the current suite cannot prove the claim.
- Needs Confect work: identify the affected modules and consumer-visible gap. Implement compatible, bounded additions that follow established APIs, with tests and documentation. Propose work requiring an API-design decision, architectural migration, or a peer-ecosystem major rather than guessing.
- Outside Confect's scope: record an upstream internal API, non-API product change, or explicit user-approved exclusion with its source and rationale. Do not exclude a public API because native access works, existing tests pass, or implementation is inconvenient. Unsettled boundaries, including CLI scope and experimental/deprecated public APIs, need a decision rather than silent exclusion.
Keep deferred work in the tracker with its upstream version or announcement,
impact, proposed scope, and linked issue or PR. An open implementation PR means
pending, not supported on main. Close a gap only after inspecting the merged
implementation and its evidence; a closed, unmerged PR does not resolve it and
must not be recreated without a new user request. Do not repeatedly request a
decision already recorded in the tracker unless new evidence changes it. Record
the released version separately: a merge is not proof of npm publication. Partial
improvements do not close an entry with remaining subfeatures.
Implement and verify
Update compatible dependencies, pins, and overrides together and confirm the
versions actually resolved. Preserve peer floors unless code or dependencies
require a higher minimum; follow create-changeset for consumer-visible changes.
Treat 0.x minor releases as potentially breaking. Defer ecosystem majors and
non-mechanical migrations with a concrete assessment.
For applied changes, run pnpm check, pnpm test, pnpm build,
pnpm test:server:mock-backend, pnpm test:server:local-backend, and
pnpm test:js:local-backend. Run the two local-backend suites sequentially
because they share ports. When Convex or CLI behavior changes, regenerate the
server's mock-backend fixtures and the shared local-backend fixtures with
pnpm codegen:server:mock-backend and pnpm codegen:local-backend, including
new untracked output. Verify affected features explicitly; green existing tests
alone are not feature-parity evidence. Follow through on the PR's CI, including
packed-consumer checks. Never claim unrun checks passed. If an upgrade fails
verification, remove it from the deliverable and retain the blocker in the
tracker instead of silently forgetting it.
Deliver without noise
- Use the project's PR creation tool for new PRs targeting
main; usewriting-commit-messagesfor commits and descriptions. Include release links, applied changes, feature dispositions, validation, and deferred work. Link the tracker. Keep unrelated feature projects out of a routine compatibility PR. - Update the tracker only when reviewed source checkpoints, findings, evidence, decisions, or delivery state change. Keep source-review checkpoints separate from implementation status. Do not add daily heartbeat comments or repeat unchanged blockers.
- Report a new PR, newly discovered gap, changed blocker, or decision needed. If nothing changed, create no branch or PR and end silently. If only the audit record changed with no actionable finding, update it without a notification.
- Never merge, enable auto-merge, publish packages, or deploy production.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

