agentleFS
rjdelleceserjdellecese/confect/.agents/skills/audit-convex/SKILL.md

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

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
  1. Very specific:

    Check both compatibility with new Convex releases and whether their new public APIs have Confect equivalents.

    line 8
  2. Very specific:

    Read AGENTS.md, REVIEW.md, and upgrade-published-deps before editing.

    line 24
  3. Distinctive:

    If another run owns the same work, leave it to that run rather than duplicate it.

    line 34
  4. Distinctive:

    Read npm metadata for stable releases of the in-scope packages, including publication times and peer requirements.

    line 36
  5. Distinctive:

    Read the SDK changelog, each updated companion package's release notes, and Convex product updates.

    line 40
  6. Distinctive:

    Never mark unavailable sources as reviewed or advance their checkpoints.

    line 64
  7. Distinctive:

    Do not exclude a public API because native access works, existing tests pass, or implementation is inconvenient.

    line 80
  8. Distinctive:

    Keep deferred work in the tracker with its upstream version or announcement, impact, proposed scope, and linked issue or PR.

    line 85
  9. Very specific:

    Update compatible dependencies, pins, and overrides together and confirm the versions actually resolved.

    line 96
  10. Very specific:

    Treat 0.x minor releases as potentially breaking.

    line 99
  11. Very specific:

    Use the project's PR creation tool for new PRs targeting main.

    line 116
  12. Distinctive:

    Update the tracker only when reviewed source checkpoints, findings, evidence, decisions, or delivery state change.

    line 120
  13. Distinctive:

    If nothing changed, create no branch or PR and end silently.

    line 125
  14. Distinctive:

    Never merge, enable auto-merge, publish packages, or deploy production.

    line 127

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

  1. Fetch fresh main and 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 unassessed rather than copying a stale implementation claim.
  6. 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; use writing-commit-messages for 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.