cc-codeconductor 1.7.0 → 1.7.2

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 (29) hide show
  1. package/README.md +11 -10
  2. package/dist/index.d.ts +1 -0
  3. package/dist/index.js +2689 -528
  4. package/dist/library.js +859 -715
  5. package/dist/validation/schemas.d.ts +784 -138
  6. package/dist/validation/scoped-context-schemas.d.ts +1074 -0
  7. package/package.json +3 -2
  8. package/presets/agy/skills/database-migrations/SKILL.md +64 -0
  9. package/presets/agy/skills/rust-async/SKILL.md +64 -0
  10. package/presets/agy/skills/rust-engineering/SKILL.md +69 -0
  11. package/presets/agy/skills/rust-sqlx/SKILL.md +64 -0
  12. package/presets/claude/settings.json +1 -8
  13. package/presets/claude/skills/database-migrations/SKILL.md +64 -0
  14. package/presets/claude/skills/rust-async/SKILL.md +64 -0
  15. package/presets/claude/skills/rust-engineering/SKILL.md +69 -0
  16. package/presets/claude/skills/rust-sqlx/SKILL.md +64 -0
  17. package/presets/codex/skills/database-migrations/SKILL.md +64 -0
  18. package/presets/codex/skills/rust-async/SKILL.md +64 -0
  19. package/presets/codex/skills/rust-engineering/SKILL.md +69 -0
  20. package/presets/codex/skills/rust-sqlx/SKILL.md +64 -0
  21. package/presets/cursor/skills/database-migrations/SKILL.md +64 -0
  22. package/presets/cursor/skills/rust-async/SKILL.md +64 -0
  23. package/presets/cursor/skills/rust-engineering/SKILL.md +69 -0
  24. package/presets/cursor/skills/rust-sqlx/SKILL.md +64 -0
  25. package/presets/opencode/skills/database-migrations/SKILL.md +64 -0
  26. package/presets/opencode/skills/rust-async/SKILL.md +64 -0
  27. package/presets/opencode/skills/rust-engineering/SKILL.md +69 -0
  28. package/presets/opencode/skills/rust-sqlx/SKILL.md +64 -0
  29. package/src/presets/shared-skills.yml +8 -0
@@ -0,0 +1,64 @@
1
+ ---
2
+ id: rust-async
3
+ name: rust-async
4
+ description: >
5
+ Rust async with tokio or async-std: guards across await, detached tasks,
6
+ blocking work, cancellation and shutdown.
7
+ Trigger: When writing or reviewing async Rust in a package that declares tokio or async-std.
8
+ ---
9
+
10
+ # Rust async
11
+
12
+ ## Activation
13
+
14
+ Apply when the owning package declares `tokio` or `async-std` as a normal
15
+ dependency and the change touches `async fn`, `.await`, `spawn` or channels.
16
+
17
+ ## Inputs
18
+
19
+ - Declared runtime, its features (`rt`, `rt-multi-thread`, `sync`, `time`).
20
+ - Existing shutdown path (`CancellationToken`, signal handler, `JoinSet`).
21
+
22
+ ## Procedure
23
+
24
+ 1. **Guards across await** (`rust.guard-across-await`). Condition: a
25
+ `std::sync::MutexGuard`/`RwLock` guard or `RefCell` borrow is live at an
26
+ `.await`. Action: scope the guard in a block that ends before the await, or
27
+ copy out the data. Use `tokio::sync::Mutex` only when the lock must be held
28
+ across the await. Exception: none for std guards (the future becomes `!Send`
29
+ or can deadlock). Verify: `cargo check`; a `Send` bound compile error on
30
+ `spawn` is the signal.
31
+ 2. **Detached tasks** (`rust.detached-task`). Condition: `spawn` result is
32
+ dropped. Action: dropping a `JoinHandle` detaches the task; keep the handle
33
+ or use a `JoinSet`, and decide who observes panics and errors. Exception:
34
+ fire-and-forget with logged failure and no shutdown dependency. Verify: each
35
+ `spawn` has an owner that is awaited or aborted at shutdown.
36
+ 3. **Blocking work.** Condition: CPU-heavy or blocking I/O inside async code.
37
+ Action: `tokio::task::spawn_blocking`. Exception: work shorter than a
38
+ scheduling quantum. Verify: no `std::thread::sleep` or blocking
39
+ `std::fs`/`std::net` call in an `async fn`.
40
+ 4. **Cancellation.** Condition: a future may be dropped at any `.await`. Action:
41
+ keep state consistent at every await; use cancel-safe operations in
42
+ `select!`. `abort()` does not stop a `spawn_blocking` task that already
43
+ started. Exception: none. Verify: a test that drops the future mid-operation.
44
+ 5. **Shutdown.** Condition: the service owns tasks. Action: signal, then await
45
+ handles with a timeout. Started `spawn_blocking` tasks run to completion, so
46
+ bound their runtime. Verify: a test or run that shuts down without hanging.
47
+
48
+ ## Decisions and exceptions
49
+
50
+ - Do not change runtime flavor or add features without a Task Card line.
51
+ - `async-std` and `tokio` APIs differ; follow the declared runtime only.
52
+ - Unbounded channels need a stated reason; default to bounded.
53
+
54
+ ## Evidence
55
+
56
+ `cargo test -p <package>` with the exit code, plus the named test that drops
57
+ or aborts the future. Report unverified cancellation paths as unverified.
58
+
59
+ ## References
60
+
61
+ - https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
62
+ - https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html
63
+ - https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html
64
+ - https://tokio.rs/tokio/topics/shutdown
@@ -0,0 +1,69 @@
1
+ ---
2
+ id: rust-engineering
3
+ name: rust-engineering
4
+ description: >
5
+ Rust engineering baseline: Cargo workspaces and features, error types,
6
+ unsafe, public API, lints and verification.
7
+ Trigger: When editing .rs files, Cargo.toml or Cargo.lock in a Rust package.
8
+ ---
9
+
10
+ # Rust engineering
11
+
12
+ ## Activation
13
+
14
+ Apply to any `.rs`, `Cargo.toml` or `Cargo.lock` change. Rules are defaults;
15
+ a repository rule with the same id wins over this skill.
16
+
17
+ ## Inputs
18
+
19
+ - Nearest `Cargo.toml` (package, `[features]`, `[lints]`) and workspace root.
20
+ - `rust-toolchain.toml`, `clippy.toml`, `rustfmt.toml` when present.
21
+ - The repository's existing error type and module layout.
22
+
23
+ ## Procedure
24
+
25
+ 1. **Locate the package.** Condition: a change spans crates. Action: resolve the
26
+ owning package per file and run checks with `-p <package>`. Exception: a
27
+ workspace-wide refactor named in the Task Card. Verify: `cargo metadata
28
+ --no-deps --format-version 1` lists the package.
29
+ 2. **Errors.** Condition: a function can fail. Action: return `Result` with the
30
+ crate's existing error type; add context where the error crosses a module
31
+ boundary. Exception: tests and examples may `unwrap`/`expect`. Verify:
32
+ `cargo clippy -- -D clippy::unwrap_used` on touched non-test code, or a grep
33
+ of the diff.
34
+ 3. **Public API.** Condition: a `pub` item changes. Action: treat as a breaking
35
+ change unless it only adds; update docs and CHANGELOG. Exception: crate is
36
+ `publish = false` and private to the workspace. Verify: `cargo doc --no-deps`
37
+ and, for published crates, `cargo semver-checks` if installed.
38
+ 4. **unsafe.** Condition: `unsafe` is needed. Action: smallest block, a `// SAFETY:`
39
+ comment stating the invariant, a safe wrapper. Exception: none for new
40
+ `unsafe` without an owner approval in the Task Card. Verify: Miri when the
41
+ toolchain has it, else a test of the invariant.
42
+ 5. **Features** (`cargo.feature-unification`). Condition: a dependency or
43
+ feature changes. Action: remember Cargo unifies features across the build;
44
+ never rely on a feature being off. Features must be additive. Exception:
45
+ mutually exclusive features guarded by `compile_error!`. Verify: `cargo check
46
+ -p <package>` and `cargo check --workspace --all-targets`.
47
+ 6. **Lockfile.** Condition: a dependency changes. Action: commit `Cargo.lock` for
48
+ binaries; justify each new dependency. Exception: libraries that gitignore
49
+ the lockfile. Verify: `cargo check --locked`.
50
+
51
+ ## Decisions and exceptions
52
+
53
+ - Match the repository's formatting, naming and error style; do not import
54
+ personal preferences. Edition and MSRV come from `Cargo.toml`, not this skill.
55
+ - Do not add `anyhow`/`thiserror` unless already used or approved.
56
+ - Dependency added "just in case": reject; prefer `std`.
57
+
58
+ ## Evidence
59
+
60
+ Report each command run with its exit code, per package: `cargo fmt --check`,
61
+ `cargo clippy --all-targets -- -D warnings`, `cargo test -p <package>`. A
62
+ check that was not run is reported as not run, never as passed.
63
+
64
+ ## References
65
+
66
+ - Cargo features: https://doc.rust-lang.org/cargo/reference/features.html
67
+ - Cargo workspaces: https://doc.rust-lang.org/cargo/reference/workspaces.html
68
+ - Rust API Guidelines: https://rust-lang.github.io/api-guidelines/
69
+ - Unsafe code guidelines: https://doc.rust-lang.org/nomicon/
@@ -0,0 +1,64 @@
1
+ ---
2
+ id: rust-sqlx
3
+ name: rust-sqlx
4
+ description: >
5
+ sqlx in Rust: query macros and offline metadata, pool acquisition,
6
+ transactions and migrations.
7
+ Trigger: When touching sqlx queries, pools, transactions, .sqlx metadata or migrations in a Rust package.
8
+ ---
9
+
10
+ # Rust sqlx
11
+
12
+ ## Activation
13
+
14
+ Apply when the owning package declares `sqlx` (normal dependency) and the
15
+ change touches queries, pool/transaction code, `.sqlx/` or `migrations/`. For a
16
+ dev-only `sqlx`, apply to tests only.
17
+
18
+ ## Inputs
19
+
20
+ - `sqlx` features (database driver, `migrate`, `offline`, runtime).
21
+ - `DATABASE_URL` source, `.sqlx/` directory, `migrations/` directory.
22
+
23
+ ## Procedure
24
+
25
+ 1. **Query macros.** Condition: `query!`/`query_as!` are used. Action: they check
26
+ against `DATABASE_URL` or the `.sqlx` metadata at build time. Any query or
27
+ schema change requires regenerating metadata. Exception: queries built with
28
+ non-macro `query()` are not checked at build. Verify: `cargo sqlx prepare
29
+ --check` (add `--workspace` in a workspace).
30
+ 2. **Stale metadata** (`sqlx.metadata-stale`). Condition: queries or migrations
31
+ changed. Action: run `cargo sqlx prepare` against a database migrated to the
32
+ current schema and commit `.sqlx/`. Exception: repository builds only online.
33
+ Verify: `cargo sqlx prepare --check` exits 0; CI builds with `DATABASE_URL`
34
+ unset.
35
+ 3. **Nested acquisition** (`sqlx.nested-acquisition`). Condition: code holds a
36
+ pooled connection or transaction and calls something that acquires another.
37
+ Action: pass the held `&mut` connection/transaction down; never acquire from
38
+ the pool while holding one. Exception: a pool sized above the maximum nesting,
39
+ documented. Verify: a test with `max_connections(1)` that does not time out
40
+ (`acquire_timeout` bounds the wait).
41
+ 4. **Transactions.** Condition: several statements must succeed together.
42
+ Action: one transaction, explicit `commit()`; drop without commit rolls
43
+ back. Exception: independent idempotent statements. Verify: a test forcing
44
+ an error between statements and asserting no partial write.
45
+ 5. **Migrations.** Apply `database-migrations` for content; here only: embed
46
+ with `sqlx::migrate!` and run once at startup or deploy, not per request.
47
+
48
+ ## Decisions and exceptions
49
+
50
+ - Do not edit an applied migration; add a new one (checksums are validated).
51
+ - Do not widen pool size to hide a nested-acquisition bug.
52
+ - Unknown boundary (is this a data-access layer?): ask or report it; do not guess.
53
+
54
+ ## Evidence
55
+
56
+ Exit code of `cargo sqlx prepare --check` and of `cargo test -p <package>`
57
+ with a database available. Without a database, report macros as unverified.
58
+
59
+ ## References
60
+
61
+ - https://docs.rs/sqlx/latest/sqlx/macro.query.html (offline mode)
62
+ - https://github.com/launchbadge/sqlx/blob/main/sqlx-cli/README.md
63
+ - https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
64
+ - https://docs.rs/sqlx/latest/sqlx/pool/struct.PoolOptions.html
@@ -0,0 +1,64 @@
1
+ ---
2
+ id: database-migrations
3
+ name: database-migrations
4
+ description: >
5
+ Safe schema and data migrations: ordering, immutability, locks, backfills,
6
+ persisted enums and rollback.
7
+ Trigger: When creating or editing files under migrations/, db/migrate or any .sql file.
8
+ ---
9
+
10
+ # Database migrations
11
+
12
+ ## Activation
13
+
14
+ Apply to any file under `migrations/` or `db/migrate/` and to `.sql` files,
15
+ in any language or ORM. Migration paths are high risk; do not lower it.
16
+
17
+ ## Inputs
18
+
19
+ - The migration tool and its ordering/checksum rules.
20
+ - Target engine and version; table size and traffic when known.
21
+ - Code that reads or writes the changed columns.
22
+
23
+ ## Procedure
24
+
25
+ 1. **Immutability.** Condition: a migration was already applied anywhere
26
+ shared. Action: add a new migration; never edit the old one. Exception:
27
+ unmerged local migration. Verify: `git diff` shows only new files in
28
+ `migrations/`.
29
+ 2. **Unique on existing data** (`migration.unique-existing-data`). Condition:
30
+ adding a unique index or constraint. Action: first query for duplicates,
31
+ deduplicate or fail with a clear message, then add the constraint. Exception:
32
+ table is provably empty in every environment. Verify: a test migrating a
33
+ fixture with duplicates.
34
+ 3. **Persisted enums** (`data.persisted-enum`). Condition: an enum is stored.
35
+ Action: store a stable code, not an ordinal or a name that may be
36
+ renamed; additions are additive, removals need a data migration. Exception:
37
+ none for stored values. Verify: a test reading a row written by the previous
38
+ version.
39
+ 4. **Locks and backfills.** Condition: large table. Action: split into add
40
+ nullable column, batched backfill, then constraint; use the engine's
41
+ non-blocking index option where available. Exception: small tables. Verify:
42
+ state the lock taken and the expected duration in the Evidence.
43
+ 5. **Rollback.** Condition: every migration. Action: write the down step or
44
+ state that the change is forward-only and why. Verify: apply, roll back
45
+ (or restore) and re-apply on a scratch database.
46
+ 6. **Code compatibility.** Condition: a column is dropped or renamed. Action:
47
+ deploy code that stops using it first (expand/contract). Verify: grep shows
48
+ no remaining reader.
49
+
50
+ ## Decisions and exceptions
51
+
52
+ - Mixing schema change and large data change in one migration: split.
53
+ - Destructive statements (`DROP`, `TRUNCATE`) need explicit Task Card approval.
54
+
55
+ ## Evidence
56
+
57
+ The command that applied the migration on a scratch database, its exit code,
58
+ and the rollback result. Without a database, report the migration as unrun.
59
+
60
+ ## References
61
+
62
+ - https://martinfowler.com/articles/evodb.html
63
+ - https://www.postgresql.org/docs/current/sql-altertable.html
64
+ - https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
@@ -0,0 +1,64 @@
1
+ ---
2
+ id: rust-async
3
+ name: rust-async
4
+ description: >
5
+ Rust async with tokio or async-std: guards across await, detached tasks,
6
+ blocking work, cancellation and shutdown.
7
+ Trigger: When writing or reviewing async Rust in a package that declares tokio or async-std.
8
+ ---
9
+
10
+ # Rust async
11
+
12
+ ## Activation
13
+
14
+ Apply when the owning package declares `tokio` or `async-std` as a normal
15
+ dependency and the change touches `async fn`, `.await`, `spawn` or channels.
16
+
17
+ ## Inputs
18
+
19
+ - Declared runtime, its features (`rt`, `rt-multi-thread`, `sync`, `time`).
20
+ - Existing shutdown path (`CancellationToken`, signal handler, `JoinSet`).
21
+
22
+ ## Procedure
23
+
24
+ 1. **Guards across await** (`rust.guard-across-await`). Condition: a
25
+ `std::sync::MutexGuard`/`RwLock` guard or `RefCell` borrow is live at an
26
+ `.await`. Action: scope the guard in a block that ends before the await, or
27
+ copy out the data. Use `tokio::sync::Mutex` only when the lock must be held
28
+ across the await. Exception: none for std guards (the future becomes `!Send`
29
+ or can deadlock). Verify: `cargo check`; a `Send` bound compile error on
30
+ `spawn` is the signal.
31
+ 2. **Detached tasks** (`rust.detached-task`). Condition: `spawn` result is
32
+ dropped. Action: dropping a `JoinHandle` detaches the task; keep the handle
33
+ or use a `JoinSet`, and decide who observes panics and errors. Exception:
34
+ fire-and-forget with logged failure and no shutdown dependency. Verify: each
35
+ `spawn` has an owner that is awaited or aborted at shutdown.
36
+ 3. **Blocking work.** Condition: CPU-heavy or blocking I/O inside async code.
37
+ Action: `tokio::task::spawn_blocking`. Exception: work shorter than a
38
+ scheduling quantum. Verify: no `std::thread::sleep` or blocking
39
+ `std::fs`/`std::net` call in an `async fn`.
40
+ 4. **Cancellation.** Condition: a future may be dropped at any `.await`. Action:
41
+ keep state consistent at every await; use cancel-safe operations in
42
+ `select!`. `abort()` does not stop a `spawn_blocking` task that already
43
+ started. Exception: none. Verify: a test that drops the future mid-operation.
44
+ 5. **Shutdown.** Condition: the service owns tasks. Action: signal, then await
45
+ handles with a timeout. Started `spawn_blocking` tasks run to completion, so
46
+ bound their runtime. Verify: a test or run that shuts down without hanging.
47
+
48
+ ## Decisions and exceptions
49
+
50
+ - Do not change runtime flavor or add features without a Task Card line.
51
+ - `async-std` and `tokio` APIs differ; follow the declared runtime only.
52
+ - Unbounded channels need a stated reason; default to bounded.
53
+
54
+ ## Evidence
55
+
56
+ `cargo test -p <package>` with the exit code, plus the named test that drops
57
+ or aborts the future. Report unverified cancellation paths as unverified.
58
+
59
+ ## References
60
+
61
+ - https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
62
+ - https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html
63
+ - https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html
64
+ - https://tokio.rs/tokio/topics/shutdown
@@ -0,0 +1,69 @@
1
+ ---
2
+ id: rust-engineering
3
+ name: rust-engineering
4
+ description: >
5
+ Rust engineering baseline: Cargo workspaces and features, error types,
6
+ unsafe, public API, lints and verification.
7
+ Trigger: When editing .rs files, Cargo.toml or Cargo.lock in a Rust package.
8
+ ---
9
+
10
+ # Rust engineering
11
+
12
+ ## Activation
13
+
14
+ Apply to any `.rs`, `Cargo.toml` or `Cargo.lock` change. Rules are defaults;
15
+ a repository rule with the same id wins over this skill.
16
+
17
+ ## Inputs
18
+
19
+ - Nearest `Cargo.toml` (package, `[features]`, `[lints]`) and workspace root.
20
+ - `rust-toolchain.toml`, `clippy.toml`, `rustfmt.toml` when present.
21
+ - The repository's existing error type and module layout.
22
+
23
+ ## Procedure
24
+
25
+ 1. **Locate the package.** Condition: a change spans crates. Action: resolve the
26
+ owning package per file and run checks with `-p <package>`. Exception: a
27
+ workspace-wide refactor named in the Task Card. Verify: `cargo metadata
28
+ --no-deps --format-version 1` lists the package.
29
+ 2. **Errors.** Condition: a function can fail. Action: return `Result` with the
30
+ crate's existing error type; add context where the error crosses a module
31
+ boundary. Exception: tests and examples may `unwrap`/`expect`. Verify:
32
+ `cargo clippy -- -D clippy::unwrap_used` on touched non-test code, or a grep
33
+ of the diff.
34
+ 3. **Public API.** Condition: a `pub` item changes. Action: treat as a breaking
35
+ change unless it only adds; update docs and CHANGELOG. Exception: crate is
36
+ `publish = false` and private to the workspace. Verify: `cargo doc --no-deps`
37
+ and, for published crates, `cargo semver-checks` if installed.
38
+ 4. **unsafe.** Condition: `unsafe` is needed. Action: smallest block, a `// SAFETY:`
39
+ comment stating the invariant, a safe wrapper. Exception: none for new
40
+ `unsafe` without an owner approval in the Task Card. Verify: Miri when the
41
+ toolchain has it, else a test of the invariant.
42
+ 5. **Features** (`cargo.feature-unification`). Condition: a dependency or
43
+ feature changes. Action: remember Cargo unifies features across the build;
44
+ never rely on a feature being off. Features must be additive. Exception:
45
+ mutually exclusive features guarded by `compile_error!`. Verify: `cargo check
46
+ -p <package>` and `cargo check --workspace --all-targets`.
47
+ 6. **Lockfile.** Condition: a dependency changes. Action: commit `Cargo.lock` for
48
+ binaries; justify each new dependency. Exception: libraries that gitignore
49
+ the lockfile. Verify: `cargo check --locked`.
50
+
51
+ ## Decisions and exceptions
52
+
53
+ - Match the repository's formatting, naming and error style; do not import
54
+ personal preferences. Edition and MSRV come from `Cargo.toml`, not this skill.
55
+ - Do not add `anyhow`/`thiserror` unless already used or approved.
56
+ - Dependency added "just in case": reject; prefer `std`.
57
+
58
+ ## Evidence
59
+
60
+ Report each command run with its exit code, per package: `cargo fmt --check`,
61
+ `cargo clippy --all-targets -- -D warnings`, `cargo test -p <package>`. A
62
+ check that was not run is reported as not run, never as passed.
63
+
64
+ ## References
65
+
66
+ - Cargo features: https://doc.rust-lang.org/cargo/reference/features.html
67
+ - Cargo workspaces: https://doc.rust-lang.org/cargo/reference/workspaces.html
68
+ - Rust API Guidelines: https://rust-lang.github.io/api-guidelines/
69
+ - Unsafe code guidelines: https://doc.rust-lang.org/nomicon/
@@ -0,0 +1,64 @@
1
+ ---
2
+ id: rust-sqlx
3
+ name: rust-sqlx
4
+ description: >
5
+ sqlx in Rust: query macros and offline metadata, pool acquisition,
6
+ transactions and migrations.
7
+ Trigger: When touching sqlx queries, pools, transactions, .sqlx metadata or migrations in a Rust package.
8
+ ---
9
+
10
+ # Rust sqlx
11
+
12
+ ## Activation
13
+
14
+ Apply when the owning package declares `sqlx` (normal dependency) and the
15
+ change touches queries, pool/transaction code, `.sqlx/` or `migrations/`. For a
16
+ dev-only `sqlx`, apply to tests only.
17
+
18
+ ## Inputs
19
+
20
+ - `sqlx` features (database driver, `migrate`, `offline`, runtime).
21
+ - `DATABASE_URL` source, `.sqlx/` directory, `migrations/` directory.
22
+
23
+ ## Procedure
24
+
25
+ 1. **Query macros.** Condition: `query!`/`query_as!` are used. Action: they check
26
+ against `DATABASE_URL` or the `.sqlx` metadata at build time. Any query or
27
+ schema change requires regenerating metadata. Exception: queries built with
28
+ non-macro `query()` are not checked at build. Verify: `cargo sqlx prepare
29
+ --check` (add `--workspace` in a workspace).
30
+ 2. **Stale metadata** (`sqlx.metadata-stale`). Condition: queries or migrations
31
+ changed. Action: run `cargo sqlx prepare` against a database migrated to the
32
+ current schema and commit `.sqlx/`. Exception: repository builds only online.
33
+ Verify: `cargo sqlx prepare --check` exits 0; CI builds with `DATABASE_URL`
34
+ unset.
35
+ 3. **Nested acquisition** (`sqlx.nested-acquisition`). Condition: code holds a
36
+ pooled connection or transaction and calls something that acquires another.
37
+ Action: pass the held `&mut` connection/transaction down; never acquire from
38
+ the pool while holding one. Exception: a pool sized above the maximum nesting,
39
+ documented. Verify: a test with `max_connections(1)` that does not time out
40
+ (`acquire_timeout` bounds the wait).
41
+ 4. **Transactions.** Condition: several statements must succeed together.
42
+ Action: one transaction, explicit `commit()`; drop without commit rolls
43
+ back. Exception: independent idempotent statements. Verify: a test forcing
44
+ an error between statements and asserting no partial write.
45
+ 5. **Migrations.** Apply `database-migrations` for content; here only: embed
46
+ with `sqlx::migrate!` and run once at startup or deploy, not per request.
47
+
48
+ ## Decisions and exceptions
49
+
50
+ - Do not edit an applied migration; add a new one (checksums are validated).
51
+ - Do not widen pool size to hide a nested-acquisition bug.
52
+ - Unknown boundary (is this a data-access layer?): ask or report it; do not guess.
53
+
54
+ ## Evidence
55
+
56
+ Exit code of `cargo sqlx prepare --check` and of `cargo test -p <package>`
57
+ with a database available. Without a database, report macros as unverified.
58
+
59
+ ## References
60
+
61
+ - https://docs.rs/sqlx/latest/sqlx/macro.query.html (offline mode)
62
+ - https://github.com/launchbadge/sqlx/blob/main/sqlx-cli/README.md
63
+ - https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
64
+ - https://docs.rs/sqlx/latest/sqlx/pool/struct.PoolOptions.html
@@ -0,0 +1,64 @@
1
+ ---
2
+ id: database-migrations
3
+ name: database-migrations
4
+ description: >
5
+ Safe schema and data migrations: ordering, immutability, locks, backfills,
6
+ persisted enums and rollback.
7
+ Trigger: When creating or editing files under migrations/, db/migrate or any .sql file.
8
+ ---
9
+
10
+ # Database migrations
11
+
12
+ ## Activation
13
+
14
+ Apply to any file under `migrations/` or `db/migrate/` and to `.sql` files,
15
+ in any language or ORM. Migration paths are high risk; do not lower it.
16
+
17
+ ## Inputs
18
+
19
+ - The migration tool and its ordering/checksum rules.
20
+ - Target engine and version; table size and traffic when known.
21
+ - Code that reads or writes the changed columns.
22
+
23
+ ## Procedure
24
+
25
+ 1. **Immutability.** Condition: a migration was already applied anywhere
26
+ shared. Action: add a new migration; never edit the old one. Exception:
27
+ unmerged local migration. Verify: `git diff` shows only new files in
28
+ `migrations/`.
29
+ 2. **Unique on existing data** (`migration.unique-existing-data`). Condition:
30
+ adding a unique index or constraint. Action: first query for duplicates,
31
+ deduplicate or fail with a clear message, then add the constraint. Exception:
32
+ table is provably empty in every environment. Verify: a test migrating a
33
+ fixture with duplicates.
34
+ 3. **Persisted enums** (`data.persisted-enum`). Condition: an enum is stored.
35
+ Action: store a stable code, not an ordinal or a name that may be
36
+ renamed; additions are additive, removals need a data migration. Exception:
37
+ none for stored values. Verify: a test reading a row written by the previous
38
+ version.
39
+ 4. **Locks and backfills.** Condition: large table. Action: split into add
40
+ nullable column, batched backfill, then constraint; use the engine's
41
+ non-blocking index option where available. Exception: small tables. Verify:
42
+ state the lock taken and the expected duration in the Evidence.
43
+ 5. **Rollback.** Condition: every migration. Action: write the down step or
44
+ state that the change is forward-only and why. Verify: apply, roll back
45
+ (or restore) and re-apply on a scratch database.
46
+ 6. **Code compatibility.** Condition: a column is dropped or renamed. Action:
47
+ deploy code that stops using it first (expand/contract). Verify: grep shows
48
+ no remaining reader.
49
+
50
+ ## Decisions and exceptions
51
+
52
+ - Mixing schema change and large data change in one migration: split.
53
+ - Destructive statements (`DROP`, `TRUNCATE`) need explicit Task Card approval.
54
+
55
+ ## Evidence
56
+
57
+ The command that applied the migration on a scratch database, its exit code,
58
+ and the rollback result. Without a database, report the migration as unrun.
59
+
60
+ ## References
61
+
62
+ - https://martinfowler.com/articles/evodb.html
63
+ - https://www.postgresql.org/docs/current/sql-altertable.html
64
+ - https://docs.rs/sqlx/latest/sqlx/macro.migrate.html
@@ -0,0 +1,64 @@
1
+ ---
2
+ id: rust-async
3
+ name: rust-async
4
+ description: >
5
+ Rust async with tokio or async-std: guards across await, detached tasks,
6
+ blocking work, cancellation and shutdown.
7
+ Trigger: When writing or reviewing async Rust in a package that declares tokio or async-std.
8
+ ---
9
+
10
+ # Rust async
11
+
12
+ ## Activation
13
+
14
+ Apply when the owning package declares `tokio` or `async-std` as a normal
15
+ dependency and the change touches `async fn`, `.await`, `spawn` or channels.
16
+
17
+ ## Inputs
18
+
19
+ - Declared runtime, its features (`rt`, `rt-multi-thread`, `sync`, `time`).
20
+ - Existing shutdown path (`CancellationToken`, signal handler, `JoinSet`).
21
+
22
+ ## Procedure
23
+
24
+ 1. **Guards across await** (`rust.guard-across-await`). Condition: a
25
+ `std::sync::MutexGuard`/`RwLock` guard or `RefCell` borrow is live at an
26
+ `.await`. Action: scope the guard in a block that ends before the await, or
27
+ copy out the data. Use `tokio::sync::Mutex` only when the lock must be held
28
+ across the await. Exception: none for std guards (the future becomes `!Send`
29
+ or can deadlock). Verify: `cargo check`; a `Send` bound compile error on
30
+ `spawn` is the signal.
31
+ 2. **Detached tasks** (`rust.detached-task`). Condition: `spawn` result is
32
+ dropped. Action: dropping a `JoinHandle` detaches the task; keep the handle
33
+ or use a `JoinSet`, and decide who observes panics and errors. Exception:
34
+ fire-and-forget with logged failure and no shutdown dependency. Verify: each
35
+ `spawn` has an owner that is awaited or aborted at shutdown.
36
+ 3. **Blocking work.** Condition: CPU-heavy or blocking I/O inside async code.
37
+ Action: `tokio::task::spawn_blocking`. Exception: work shorter than a
38
+ scheduling quantum. Verify: no `std::thread::sleep` or blocking
39
+ `std::fs`/`std::net` call in an `async fn`.
40
+ 4. **Cancellation.** Condition: a future may be dropped at any `.await`. Action:
41
+ keep state consistent at every await; use cancel-safe operations in
42
+ `select!`. `abort()` does not stop a `spawn_blocking` task that already
43
+ started. Exception: none. Verify: a test that drops the future mid-operation.
44
+ 5. **Shutdown.** Condition: the service owns tasks. Action: signal, then await
45
+ handles with a timeout. Started `spawn_blocking` tasks run to completion, so
46
+ bound their runtime. Verify: a test or run that shuts down without hanging.
47
+
48
+ ## Decisions and exceptions
49
+
50
+ - Do not change runtime flavor or add features without a Task Card line.
51
+ - `async-std` and `tokio` APIs differ; follow the declared runtime only.
52
+ - Unbounded channels need a stated reason; default to bounded.
53
+
54
+ ## Evidence
55
+
56
+ `cargo test -p <package>` with the exit code, plus the named test that drops
57
+ or aborts the future. Report unverified cancellation paths as unverified.
58
+
59
+ ## References
60
+
61
+ - https://docs.rs/tokio/latest/tokio/task/fn.spawn_blocking.html
62
+ - https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html
63
+ - https://docs.rs/tokio/latest/tokio/sync/struct.Mutex.html
64
+ - https://tokio.rs/tokio/topics/shutdown
@@ -0,0 +1,69 @@
1
+ ---
2
+ id: rust-engineering
3
+ name: rust-engineering
4
+ description: >
5
+ Rust engineering baseline: Cargo workspaces and features, error types,
6
+ unsafe, public API, lints and verification.
7
+ Trigger: When editing .rs files, Cargo.toml or Cargo.lock in a Rust package.
8
+ ---
9
+
10
+ # Rust engineering
11
+
12
+ ## Activation
13
+
14
+ Apply to any `.rs`, `Cargo.toml` or `Cargo.lock` change. Rules are defaults;
15
+ a repository rule with the same id wins over this skill.
16
+
17
+ ## Inputs
18
+
19
+ - Nearest `Cargo.toml` (package, `[features]`, `[lints]`) and workspace root.
20
+ - `rust-toolchain.toml`, `clippy.toml`, `rustfmt.toml` when present.
21
+ - The repository's existing error type and module layout.
22
+
23
+ ## Procedure
24
+
25
+ 1. **Locate the package.** Condition: a change spans crates. Action: resolve the
26
+ owning package per file and run checks with `-p <package>`. Exception: a
27
+ workspace-wide refactor named in the Task Card. Verify: `cargo metadata
28
+ --no-deps --format-version 1` lists the package.
29
+ 2. **Errors.** Condition: a function can fail. Action: return `Result` with the
30
+ crate's existing error type; add context where the error crosses a module
31
+ boundary. Exception: tests and examples may `unwrap`/`expect`. Verify:
32
+ `cargo clippy -- -D clippy::unwrap_used` on touched non-test code, or a grep
33
+ of the diff.
34
+ 3. **Public API.** Condition: a `pub` item changes. Action: treat as a breaking
35
+ change unless it only adds; update docs and CHANGELOG. Exception: crate is
36
+ `publish = false` and private to the workspace. Verify: `cargo doc --no-deps`
37
+ and, for published crates, `cargo semver-checks` if installed.
38
+ 4. **unsafe.** Condition: `unsafe` is needed. Action: smallest block, a `// SAFETY:`
39
+ comment stating the invariant, a safe wrapper. Exception: none for new
40
+ `unsafe` without an owner approval in the Task Card. Verify: Miri when the
41
+ toolchain has it, else a test of the invariant.
42
+ 5. **Features** (`cargo.feature-unification`). Condition: a dependency or
43
+ feature changes. Action: remember Cargo unifies features across the build;
44
+ never rely on a feature being off. Features must be additive. Exception:
45
+ mutually exclusive features guarded by `compile_error!`. Verify: `cargo check
46
+ -p <package>` and `cargo check --workspace --all-targets`.
47
+ 6. **Lockfile.** Condition: a dependency changes. Action: commit `Cargo.lock` for
48
+ binaries; justify each new dependency. Exception: libraries that gitignore
49
+ the lockfile. Verify: `cargo check --locked`.
50
+
51
+ ## Decisions and exceptions
52
+
53
+ - Match the repository's formatting, naming and error style; do not import
54
+ personal preferences. Edition and MSRV come from `Cargo.toml`, not this skill.
55
+ - Do not add `anyhow`/`thiserror` unless already used or approved.
56
+ - Dependency added "just in case": reject; prefer `std`.
57
+
58
+ ## Evidence
59
+
60
+ Report each command run with its exit code, per package: `cargo fmt --check`,
61
+ `cargo clippy --all-targets -- -D warnings`, `cargo test -p <package>`. A
62
+ check that was not run is reported as not run, never as passed.
63
+
64
+ ## References
65
+
66
+ - Cargo features: https://doc.rust-lang.org/cargo/reference/features.html
67
+ - Cargo workspaces: https://doc.rust-lang.org/cargo/reference/workspaces.html
68
+ - Rust API Guidelines: https://rust-lang.github.io/api-guidelines/
69
+ - Unsafe code guidelines: https://doc.rust-lang.org/nomicon/