@softspark/ai-toolkit 2.11.0 → 3.0.0

package/app/skills/rollback/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rollback
-description: "Roll back a deployment safely with verification"
+description: "Roll back a git commit, database migration, or deployment to a previous known-good state with safety checks and health verification. Use when the user wants to revert recent changes safely — not to undo local edits or halt the whole system."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[target: git/db/deploy]"
@@ -85,3 +85,29 @@ Before any rollback:
 ```
 
 > **CRITICAL: Always confirm with the user before executing destructive rollback operations.**
+
+## Rules
+
+- **MUST** confirm the current state AND the target state before rolling back — surface the diff in plain English
+- **MUST** verify a recent backup exists (for DB rollbacks) or explicitly warn the user that none was found
+- **NEVER** roll back without an explicit "yes" from the user — rollbacks are irreversible in the user-experience sense even when technically reversible
+- **NEVER** `git reset --hard` on a branch others have pulled from — it rewrites shared history
+- **CRITICAL**: after any rollback, run a health check (`/health` or the project's equivalent) to confirm the target state is stable — a "successful" rollback to a broken baseline is worse than the original state
+- **MANDATORY**: log the rollback with timestamp, scope, and reason — post-mortems need this trail
+
+## Gotchas
+
+- `git revert` creates a **new commit** that undoes the target commit. The reverted commit is still in history — if the target commit was sensitive (secret, PII), revert alone does not remove it. Use history rewriting tools for that.
+- Database migration rollbacks sometimes **lose data**. A forward migration that added a NOT NULL column with a default, then populated it with user data, cannot restore the column contents on rollback — the data is gone.
+- Kubernetes `kubectl rollout undo` rolls back to the previous ReplicaSet, not to a specific version. If you need "rollback to v1.2.3 specifically", track deployments by image tag and use `kubectl set image`, not `rollout undo`.
+- Heroku and similar PaaS platforms `rollback` restores the slug but not environment config that changed after the rollback target was built — new env vars or add-ons may break the rolled-back version.
+- `git reset --soft` preserves staged changes, `--mixed` (default) preserves working tree, `--hard` discards both. Wrong flag = lost work; always state the flag explicitly in the confirmation prompt.
+- Restoring a DB backup on top of an active database can cause data loss between the backup time and the restore time. Take a fresh snapshot before the restore, even when rolling back — the current (broken) state might contain post-backup user writes.
+
+## When NOT to Use
+
+- For emergency halt of all agent activity — use `/panic`
+- For undoing local uncommitted edits — use `git checkout` directly, not this skill
+- For an incident with user-facing impact — use `/workflow incident-response` for coordinated response
+- For planned schema changes — use `/migrate` with a forward rollback migration, not this skill after-the-fact
+- For a feature flag off-switch — toggle the flag; rollback is a heavier tool than needed

package/app/skills/security-patterns/SKILL.md

@@ -100,3 +100,30 @@ For authorization patterns (RBAC, ABAC), see [reference/authorization.md](refere
 For input validation patterns (SQL injection, XSS, Pydantic), see [reference/input-validation.md](reference/input-validation.md).
 
 For OAuth2 flows, CSRF protection, and audit logging, see [reference/oauth-csrf-audit.md](reference/oauth-csrf-audit.md).
+
+## Rules
+
+- **MUST** validate all input at the trust boundary, not inside business logic — deep validation allows bad data to spread before rejection
+- **MUST** use parameterized queries (prepared statements) for every SQL interaction — string concatenation is SQL injection
+- **NEVER** store secrets (API keys, tokens, passwords) in code, config files, or git history — use the platform's secret manager
+- **NEVER** log passwords, tokens, PII, or PHI — even at debug level. Logs reach aggregation systems, backups, and disk snapshots.
+- **NEVER** roll your own crypto. Use vetted libraries (bcrypt/argon2 for passwords, libsodium for crypto) and accept their defaults.
+- **CRITICAL**: authentication (who you are) and authorization (what you can do) are distinct concerns. Confusing them produces privilege escalation bugs; AuthN passes → AuthZ still runs.
+- **MANDATORY**: every endpoint is authenticated and authorized by default. Public endpoints are explicit opt-outs, not unmarked defaults.
+
+## Gotchas
+
+- JWT tokens signed with `none` algorithm are valid-looking tokens with no signature. Libraries that trust the `alg` header field accept them — always validate `alg` against an allowlist, never use the token's own declaration.
+- `bcrypt` has a 72-byte password length cap; longer passwords are silently truncated, making "UniqueLongPassword..." collide with "UniqueLong...". Pre-hash with SHA-256 before bcrypt for >72 char passwords.
+- `SameSite=Lax` cookies are **sent** on top-level navigations (including POST from a malicious site) in some browsers. CSRF protection requires either `SameSite=Strict` or explicit CSRF tokens; relying on `Lax` alone is insufficient for state-changing endpoints.
+- `Content-Security-Policy` with `unsafe-inline` allows any inline script to run — negating most of CSP's value. Remove `unsafe-inline` and refactor to external scripts, even if it means extra files.
+- Environment variables leak via `printenv` in debug endpoints, `/proc/<pid>/environ` on Linux, and process listings. Prefer mounting secrets as files (Docker secrets, Kubernetes secrets) for defense in depth.
+- Rate limiting by IP address is bypassed by CDN proxies and legitimate shared NAT. Apply rate limits at the **authenticated user** level when possible; IP-level is a coarse last resort.
+
+## When NOT to Load
+
+- For dependency vulnerability scanning — use `/cve-scan`
+- For HIPAA-specific healthcare compliance — use `/hipaa-validate`
+- For threat modeling of a new architecture — delegate to the `security-architect` agent
+- For penetration testing and CVE exploitation — delegate to `security-auditor` agent
+- For content moderation (LLM safety filters) — use `/content-moderation-patterns`

package/app/skills/skill-audit/SKILL.md

@@ -130,8 +130,25 @@ The `/skill-audit` slash command wraps this scanner with Claude's analysis for r
 
 ## Rules
 
-- Never modify files without `--fix` flag
-- HIGH severity findings should block deployment
-- This skill is READ-ONLY by default
-- Scan both `app/skills/` and `app/agents/` directories
-- Exit with non-zero status if any HIGH findings exist (for CI integration)
+- **MUST** remain read-only by default — file modifications require the explicit `--fix` flag
+- **MUST** exit with non-zero status on any HIGH finding so CI pipelines can gate merges
+- **NEVER** auto-fix HIGH-severity findings — only the human owner decides on dangerous code
+- **NEVER** silence findings by adding exceptions in the audit config; either fix the code or document why the pattern is safe in the skill body
+- **CRITICAL**: scan both `app/skills/` and `app/agents/` — agents without tool restrictions are the same risk class as skills with broad `allowed-tools`
+- **MANDATORY**: every finding names a specific fix (replace `eval()` with `ast.literal_eval()`, add missing `allowed-tools`). A finding without a fix is triage noise.
+
+## Gotchas
+
+- Regex-based secret detection catches canonical patterns (`sk-...`, `ghp_...`) but misses custom API key formats used by internal services. Augment the regex list with project-specific patterns before trusting "0 HIGH findings".
+- `--fix` on `allowed-tools` infers minimal tool sets from imports, but skills that shell out via Bash may need tools not visible in the static scan. Review auto-added restrictions before merging.
+- Knowledge skills (`user-invocable: false`) with Bash access are HIGH because they auto-load and can act without user triggering. Legitimate exceptions (e.g., `research-mastery` calling `smart_query()`) should be explicitly whitelisted in the audit config with a comment.
+- The scanner flags `eval(` even inside docstrings and commented-out code. Context-aware scanning is hard; the alternative is reviewing each HIGH flag manually — the scan errs on the side of false positives.
+- CI integration with `--ci` exits 1 on any HIGH, which **blocks the commit**. A sudden pattern match (e.g., a legitimate new use of `subprocess.run`) can block unrelated PRs. Keep a fast path for pre-approving new patterns.
+
+## When NOT to Use
+
+- For general code-quality metrics (complexity, coverage, duplication) — use `/analyze`
+- For dependency CVE scans — use `/cve-scan`
+- For HIPAA-specific audits — use `/hipaa-validate`
+- For live pentesting of a deployed app — delegate to the `security-auditor` agent
+- When the project has its own security scanner (semgrep, snyk) — prefer it; `/skill-audit` is toolkit-specific

package/app/skills/skill-creator/SKILL.md

@@ -28,15 +28,19 @@ Create a new skill following the Agent Skills standard.
 |-------|------|----------|-------------|
 | `name` | string | yes | Lowercase, hyphens only, max 64 chars |
 | `description` | string | yes | Third person, max 1024 chars, include key terms |
-| `effort` | low/medium/high/max | no | Controls model thinking budget |
+| `effort` | low/medium/high/xhigh/max | no | Controls model thinking budget (xhigh added for Opus 4.7) |
 | `disable-model-invocation` | bool | no | `true` = only user can trigger (task skills) |
 | `user-invocable` | bool | no | `false` = knowledge skill, Claude auto-loads |
-| `allowed-tools` | csv | no | Restrict tool access for safety |
-| `model` | string | no | Override default model |
+| `allowed-tools` | csv or YAML list | no | Restrict tool access for safety; YAML-style lists accepted |
+| `disallowedTools` | csv or YAML list | no | Block specific tools (plugin-shipped agents) |
+| `model` | string | no | Override default model (accepts full IDs like `claude-opus-4-7`) |
 | `context` | string | no | `fork` to run in isolated subagent |
 | `agent` | string | no | Agent type to use when `context: fork` |
+| `skills` | csv | no | Auto-load skills for the invoked subagent |
 | `argument-hint` | string | no | Shown in autocomplete, e.g. `"[target]"` |
-| `hooks` | object | no | Lifecycle hooks (PreToolUse, PostToolUse, Stop) |
+| `hooks` | object | no | Lifecycle hooks (`PreToolUse`, `PostToolUse`, `Stop`) scoped to the skill invocation |
+| `maxTurns` | int | no | Cap turns when skill spawns a subagent |
+| `memory` | user/project/local | no | Persistent memory scope (agents only) |
 
 ## Classification Guide
 
@@ -48,7 +52,7 @@ Create a new skill following the Agent Skills standard.
 
 ## Writing Guidelines
 
-- **Description**: third person ("Generates...", "Provides..."), include searchable key terms
+- **Description**: third person ("Generates...", "Provides..."), **min 50 chars**, include searchable key terms **and a trigger hint** (e.g., "Use when..."). Short descriptions cause over-triggering — adjacent skills fight for the same query.
 - **Name**: lowercase, hyphens, max 64 chars -- match the directory name
 - **Length**: SKILL.md under 500 lines; use `reference/` for overflow
 - **Be concise**: Claude is smart -- give structure, not lectures
@@ -57,6 +61,26 @@ Create a new skill following the Agent Skills standard.
 - **Use `$ARGUMENTS`**: place it early so user input is visible
 - **Tables over prose**: for options, patterns, mappings
 
+## Mandatory Sections (meta-architect audit criteria)
+
+Every SKILL.md must contain all five, or it will lower the toolkit quality score:
+
+1. **Description ≥50 chars** with trigger hint in frontmatter
+2. **At least one concrete example** — fenced code block or `## Example` section
+3. **Hard rules** using uppercase markers: `MUST`, `NEVER`, `CRITICAL`, `MANDATORY`, or `DO NOT`
+4. **"When NOT to Use" section** — list 2-3 adjacent skills and the boundary between them
+5. **Under 500 lines** — split into `reference/` if needed
+
+These map directly to the mutation strategies in `meta-architect.md`:
+`add_example`, `add_constraint`, `add_edge_case`, `restructure`.
+
+### Rules vs Gotchas — different semantic buckets
+
+Split the "hard rules" criterion into two sections when both apply:
+
+- **`## Rules`** — prescriptive process constraints (always-true MUST / NEVER): *"MUST form a testable hypothesis before changing code"*, *"NEVER force-push main"*. Required in every skill.
+- **`## Gotchas`** — environment-specific traps the agent would miss without being told, taken from [Anthropic's best practices](https://agentskills.io/skill-creation/best-practices.md#gotchas-sections). Example from their docs: *"The `users` table uses soft deletes. Queries must include `WHERE deleted_at IS NULL` or results will include deactivated accounts."* Add this section only when real domain traps exist — do not pad with a `(none)` placeholder.
+
 ## Directory Structure
 
 ```
@@ -74,7 +98,7 @@ Only create subdirectories when the skill needs them. Most skills are a single S
 ```markdown
 ---
 name: {name}
-description: "{Third-person description with key terms}"
+description: "{Third-person description, min 50 chars, with trigger hint like 'Use when...'}"
 argument-hint: "[hint]"
 allowed-tools: Read, Grep, Glob
 ---
@@ -97,25 +121,46 @@ $ARGUMENTS
 2. **Step two**
 3. **Step three**
 
-## Output Format
+## Example
 
-{Expected output structure}
+\`\`\`
+/{name} example-argument
+\`\`\`
+
+{Expected observable behavior.}
 
 ## Rules
 
-- {Constraint 1}
-- {Constraint 2}
+- **MUST** {non-negotiable rule 1}
+- **NEVER** {forbidden action}
+- **CRITICAL**: {safety constraint}
+
+## Gotchas
+
+- {environment-specific trap the agent would miss — concrete, not general}
+- {non-obvious behavior of a tool, API, or data layout}
+
+## When NOT to Use
+
+- For {adjacent use case} -- use `/{other-skill}` instead
+- For {another case} -- use `/{another-skill}`
+- If {precondition} is not met
 ```
 
+Leave out `## Gotchas` entirely when the skill has no domain-specific traps — it is not mandatory, and a stub with nothing concrete is worse than no section.
+
 ## Quality Checklist
 
 Before finalizing, verify:
 
-- [ ] Description is specific with searchable key terms
-- [ ] SKILL.md is under 500 lines
+- [ ] Description ≥50 chars, third-person, with trigger hint
+- [ ] At least one concrete code-fenced example
+- [ ] `## Rules` section with prescriptive MUST / NEVER / CRITICAL / MANDATORY
+- [ ] `## Gotchas` section when the domain has real environment-specific traps (otherwise omit)
+- [ ] `## When NOT to Use` section naming 2-3 adjacent skills
+- [ ] SKILL.md under 500 lines
 - [ ] No time-sensitive information (versions, dates)
 - [ ] Consistent terminology throughout
-- [ ] Examples are concrete, not abstract
 - [ ] File references max 1 level deep
 - [ ] Workflows have numbered steps
 - [ ] Frontmatter fields match classification type

package/app/skills/swift-patterns/SKILL.md

@@ -280,113 +280,7 @@ func testLoginFlow() {
 
 ## Common Frameworks
 
-### SwiftUI + @Observable (iOS 17+)
-
-```swift
-@Observable
-final class UserViewModel {
-    var users: [User] = []
-    var isLoading = false
-    private let service: UserService
-
-    init(service: UserService) { self.service = service }
-
-    func load() async {
-        isLoading = true
-        defer { isLoading = false }
-        users = (try? await service.fetchAll()) ?? []
-    }
-}
-
-struct UserListView: View {
-    @State private var vm: UserViewModel
-
-    init(service: UserService) {
-        _vm = State(initialValue: UserViewModel(service: service))
-    }
-
-    var body: some View {
-        NavigationStack {
-            List(vm.users) { user in
-                NavigationLink(value: user) { Text(user.name) }
-            }
-            .navigationTitle("Users")
-            .navigationDestination(for: User.self) { UserDetailView(user: $0) }
-            .task { await vm.load() }
-        }
-    }
-}
-```
-
-### Combine
-
-```swift
-class SearchVM: ObservableObject {
-    @Published var query = ""
-    @Published var results: [Item] = []
-    private var cancellables = Set<AnyCancellable>()
-
-    init(service: SearchService) {
-        $query
-            .debounce(for: .milliseconds(300), scheduler: DispatchQueue.main)
-            .removeDuplicates()
-            .filter { !$0.isEmpty }
-            .flatMap { service.search(query: $0) }
-            .receive(on: DispatchQueue.main)
-            .sink(receiveCompletion: { _ in },
-                  receiveValue: { [weak self] in self?.results = $0 })
-            .store(in: &cancellables)
-    }
-}
-```
-
-### Structured Concurrency
-
-```swift
-func fetchAllProfiles(ids: [String]) async throws -> [Profile] {
-    try await withThrowingTaskGroup(of: Profile.self) { group in
-        for id in ids { group.addTask { try await fetchProfile(id: id) } }
-        return try await group.reduce(into: []) { $0.append($1) }
-    }
-}
-
-// AsyncStream for bridging callbacks
-let locations = AsyncStream<Location> { continuation in
-    manager.onUpdate = { continuation.yield($0) }
-    continuation.onTermination = { _ in manager.stop() }
-}
-```
-
-### SwiftData
-
-```swift
-@Model
-final class Item {
-    var title: String
-    var timestamp: Date
-    @Relationship(deleteRule: .cascade) var tags: [Tag]
-    init(title: String) { self.title = title; self.timestamp = .now; self.tags = [] }
-}
-
-struct ItemListView: View {
-    @Query(sort: \Item.timestamp, order: .reverse) private var items: [Item]
-    @Environment(\.modelContext) private var context
-
-    var body: some View {
-        List(items) { Text($0.title) }
-    }
-}
-```
-
-### Vapor (Server-Side)
-
-```swift
-app.get("users", ":id") { req async throws -> User in
-    guard let id = req.parameters.get("id", as: UUID.self) else { throw Abort(.badRequest) }
-    guard let user = try await User.find(id, on: req.db) else { throw Abort(.notFound) }
-    return user
-}
-```
+For SwiftUI + `@Observable`, Combine, Structured Concurrency, SwiftData, and Vapor framework patterns with complete code examples, see [reference/frameworks.md](reference/frameworks.md).
 
 ---
 
@@ -498,3 +392,29 @@ Schemes: separate Debug/Release/Testing. Enable ASan + TSan in test schemes.
 | Blocking main thread | UI freezes | `async/await`, `Task { }` |
 | `UserDefaults` for secrets | Insecure | Keychain (`SecItemAdd`) |
 | `@ObservedObject` for owned state | Object recreated | `@StateObject` or `@State` + `@Observable` |
+
+## Rules
+
+- **MUST** use Swift concurrency primitives (`async/await`, actors, `Task`) for new code — GCD is legacy and mixes poorly with the new model
+- **MUST** annotate view models with `@MainActor` when they touch UI state — off-main mutations cause runtime warnings and flaky UI
+- **NEVER** force-unwrap (`!`) without a documented invariant in a comment; runtime crashes from unwrap are the top iOS crash category
+- **NEVER** store secrets in `UserDefaults` or plist — use Keychain APIs (`SecItemAdd`, `SecItemCopyMatching`)
+- **CRITICAL**: SwiftUI state flows downward; mutations flow through `@State`, `@Binding`, or `@Observable`. Never mutate a parent's state from a child via a captured reference — it breaks dependency tracking.
+- **MANDATORY**: every closure that captures `self` inside a reference type uses `[weak self]` or `[unowned self]` — retain cycles are the top memory-leak cause
+
+## Gotchas
+
+- `@StateObject` and `@ObservedObject` look similar but behave oppositely on parent re-render: `@StateObject` persists, `@ObservedObject` may re-initialize. Using `@ObservedObject` for view-owned state recreates the object on every render — state loss without error.
+- `Task { @MainActor in ... }` inside a non-`@MainActor` context does **not** synchronously return to main; it schedules. Code between the `await` and `Task` boundary runs on whatever actor you came from, which can race with UI updates.
+- `AsyncStream` continuations without `onTermination` leak: if the consumer cancels, the producer keeps yielding forever. Always install a termination handler.
+- SwiftData `@Query` with `@Environment(\.modelContext)` invalidates on every write; heavy reads in a watched view cause perf drops. Use `@FetchRequest`-style fetch descriptors with explicit refresh, not ambient `@Query`, for large datasets.
+- Combine's `.receive(on: DispatchQueue.main)` schedules asynchronously — if the next operator expects sync execution, order matters. Prefer moving `.receive(on:)` to just before the sink, not mid-pipeline.
+- Swift Concurrency does not compose cleanly with Objective-C completion handlers; `withCheckedContinuation` bridges but a continuation that is never resumed hangs the Task forever. Always pair resumes with all control-flow paths, including errors.
+
+## When NOT to Load
+
+- For **Flutter or React Native** cross-platform code — use `/flutter-patterns` or JS patterns; this skill is Swift-only
+- For generic iOS architecture decisions (MVC vs MVVM vs VIPER) — use `/architecture-decision`
+- For Kotlin-based cross-platform mobile (KMP) — use `/kotlin-patterns`
+- For mobile CI/CD specifics (TestFlight, Fastlane) — use `/ci-cd-patterns`
+- For Objective-C interop deep dives — outside scope; this skill focuses on modern Swift

package/app/skills/swift-patterns/reference/frameworks.md

@@ -0,0 +1,111 @@
+# Swift Framework Patterns
+
+Detailed patterns for SwiftUI, Combine, Structured Concurrency, SwiftData, and Vapor. Loaded on demand from `swift-patterns/SKILL.md`.
+
+## SwiftUI + @Observable (iOS 17+)
+
+```swift
+@Observable
+final class UserViewModel {
+    var users: [User] = []
+    var isLoading = false
+    private let service: UserService
+
+    init(service: UserService) { self.service = service }
+
+    func load() async {
+        isLoading = true
+        defer { isLoading = false }
+        users = (try? await service.fetchAll()) ?? []
+    }
+}
+
+struct UserListView: View {
+    @State private var vm: UserViewModel
+
+    init(service: UserService) {
+        _vm = State(initialValue: UserViewModel(service: service))
+    }
+
+    var body: some View {
+        NavigationStack {
+            List(vm.users) { user in
+                NavigationLink(value: user) { Text(user.name) }
+            }
+            .navigationTitle("Users")
+            .navigationDestination(for: User.self) { UserDetailView(user: $0) }
+            .task { await vm.load() }
+        }
+    }
+}
+```
+
+## Combine
+
+```swift
+class SearchVM: ObservableObject {
+    @Published var query = ""
+    @Published var results: [Item] = []
+    private var cancellables = Set<AnyCancellable>()
+
+    init(service: SearchService) {
+        $query
+            .debounce(for: .milliseconds(300), scheduler: DispatchQueue.main)
+            .removeDuplicates()
+            .filter { !$0.isEmpty }
+            .flatMap { service.search(query: $0) }
+            .receive(on: DispatchQueue.main)
+            .sink(receiveCompletion: { _ in },
+                  receiveValue: { [weak self] in self?.results = $0 })
+            .store(in: &cancellables)
+    }
+}
+```
+
+## Structured Concurrency
+
+```swift
+func fetchAllProfiles(ids: [String]) async throws -> [Profile] {
+    try await withThrowingTaskGroup(of: Profile.self) { group in
+        for id in ids { group.addTask { try await fetchProfile(id: id) } }
+        return try await group.reduce(into: []) { $0.append($1) }
+    }
+}
+
+// AsyncStream for bridging callbacks
+let locations = AsyncStream<Location> { continuation in
+    manager.onUpdate = { continuation.yield($0) }
+    continuation.onTermination = { _ in manager.stop() }
+}
+```
+
+## SwiftData
+
+```swift
+@Model
+final class Item {
+    var title: String
+    var timestamp: Date
+    @Relationship(deleteRule: .cascade) var tags: [Tag]
+    init(title: String) { self.title = title; self.timestamp = .now; self.tags = [] }
+}
+
+struct ItemListView: View {
+    @Query(sort: \Item.timestamp, order: .reverse) private var items: [Item]
+    @Environment(\.modelContext) private var context
+
+    var body: some View {
+        List(items) { Text($0.title) }
+    }
+}
+```
+
+## Vapor (Server-Side)
+
+```swift
+app.get("users", ":id") { req async throws -> User in
+    guard let id = req.parameters.get("id", as: UUID.self) else { throw Abort(.badRequest) }
+    guard let user = try await User.find(id, on: req.db) else { throw Abort(.notFound) }
+    return user
+}
+```

package/app/skills/test/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: test
-description: "Run tests with coverage analysis and reporting"
+description: "Run the project's test suite with coverage reporting, auto-detecting the framework (pytest, vitest, jest, flutter test, go test, cargo test, phpunit). Use when the user asks to run existing tests — not to author new ones test-first."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[file or pattern]"
@@ -105,3 +105,25 @@ tests/               # or test/, spec/, __tests__/
 ├── integration/     # Tests with external dependencies
 └── e2e/             # End-to-end tests
 ```
+
+## Rules
+
+- **MUST** detect the framework automatically via `detect-runner.py` — do not assume
+- **NEVER** modify tests to make them pass
+- **CRITICAL**: coverage reporting must use the project's configured tool (`--cov=src`, `--coverage`, etc.) — do not invent flags
+- **MANDATORY**: when a test fails, report the failure exactly; do not paraphrase
+
+## Gotchas
+
+- `pytest --cov=src` inflates coverage when `tests/` lives under `src/` — test files count toward covered lines. Either move `tests/` out, or use `--cov=src --cov-branch --cov-report=term-missing` with an explicit `[tool.coverage.run] omit = ["tests/*"]` in `pyproject.toml`.
+- `go test ./...` runs packages in parallel by default; a test depending on shared global state may pass alone and fail in the suite. If flakiness appears only under `./...`, suspect shared state, not a bug in the test.
+- `flutter test` without an emulator falls back to the headless "null platform" — widget tests that require a render surface are **silently skipped**. CI without a display must add `flutter test --platform vm` or a virtual framebuffer.
+- `vitest run` and `jest` interpret glob patterns differently: `*.test.ts` in vitest matches filenames, in jest matches paths. Passing the same CLI arg to both produces different test sets — use the framework-native config file when possible.
+- `pytest --lf` (last-failed) silently runs **all** tests if there is no cache from a prior run. First-time runs in CI therefore ignore `--lf` and re-run everything, which can hide "only failed tests" bugs in local runs.
+
+## When NOT to Use
+
+- To write new tests test-first — use `/tdd`
+- To author test design patterns — use `/testing-patterns` (knowledge skill)
+- To debug a failing test — use `/debug` after `/test` surfaces the failure
+- For performance/load testing — use dedicated tooling, not `/test`

package/app/skills/testing-patterns/SKILL.md

@@ -82,3 +82,29 @@ For Flutter/Dart testing patterns, see [reference/flutter-testing.md](reference/
 | "We'll add tests later" | Untested code accumulates — later means never, and coverage gaps compound |
 | "Mocking everything is fine" | Over-mocking tests the mocks, not the code — mock at boundaries only |
 | "100% coverage means no bugs" | Coverage measures execution, not correctness — focus on behavior assertions |
+
+## Rules
+
+- **MUST** follow Arrange-Act-Assert (AAA) structure in every test — unstructured tests degrade into procedural smoke tests
+- **MUST** test behavior through the public interface, not internal implementation — tests coupled to internals break on every refactor
+- **NEVER** test implementation details (private method return values, internal state flags) — they are not the contract
+- **NEVER** hit real external services in unit tests — use fakes/stubs for boundaries; save real integration for integration tests
+- **CRITICAL**: integration tests must hit real dependencies (database, message queue, external API) when mock-vs-prod divergence is a real risk. Mocked integration tests create false confidence.
+- **MANDATORY**: flaky tests are bugs, not noise. Quarantine or delete them — a tolerated flaky test erodes the suite's credibility.
+
+## Gotchas
+
+- Coverage numbers are easy to game: include generated code, test files that import but do not assert, or wide `# pragma: no cover` usage. A 95% reported coverage with 60% real behavior assertion is common.
+- Snapshot tests (Jest `.toMatchSnapshot()`, pytest-regressions) accept any output as "correct" on first run. An incorrect initial snapshot becomes the accepted baseline — review snapshots as carefully as code.
+- Mocks configured with `any` matchers (e.g., `.mock.calls[0][0]` without a schema) pass even when the production call shape changes. Assert on specific arguments, not just "was called".
+- Test isolation fails when globals leak (module-level mutable state, module-scoped fixtures, env vars set in one test). Flakiness that appears only under `pytest -n auto` or `jest --parallel` is usually shared state.
+- Property-based tests (Hypothesis, fast-check) shrink failing examples to minimal reproducers, but shrinking time can dominate the run. For complex generators, cap shrink deadlines or seed the failing example for next-run reproducibility.
+- Test pyramid vs trophy: the "right" ratio depends on stack. Frontend apps with rendering concerns benefit from more integration tests (trophy); pure backend services align better with pyramid. Don't cargo-cult one model.
+
+## When NOT to Load
+
+- For **running** the test suite — use `/test`
+- For test-first development workflow — use `/tdd`
+- For debugging a specific test failure — use `/debug` on the failure output
+- For test framework choice in a new project — use `/app-builder`
+- For performance/load testing — this skill covers correctness tests, not load

package/app/skills/triage-issue/SKILL.md

@@ -114,7 +114,25 @@ Do NOT include file paths, line numbers, or implementation details. Describe mod
 
 ## Rules
 
-- Minimal user interaction — investigate autonomously
-- No file paths or line numbers in the issue (durability)
-- TDD plan uses vertical slices, not horizontal
-- File immediately — don't ask for review
+- **MUST** explore the codebase for root cause before filing — symptoms masquerade as causes often
+- **MUST** propose a TDD fix plan with ordered RED→GREEN cycles, each a vertical slice
+- **NEVER** ask follow-up clarifying questions; one initial question maximum, then investigate autonomously
+- **NEVER** include file paths, function names, or line numbers in the issue body — they go stale before the issue is picked up
+- **CRITICAL**: the issue must be reproducible. If reproduction steps cannot be determined from the investigation, say so explicitly in the Problem section — do not fabricate them.
+- **MANDATORY**: file the issue immediately via `gh issue create` and share the URL — do not ask the user to review a draft first
+
+## Gotchas
+
+- `gh issue create` without `--body` opens `$EDITOR`. In automated flows the skill hangs — always pass the body file or inline text.
+- "Root cause" often turns out to be two concurrent issues. If the investigation keeps branching, file the most-probable primary cause and note the secondary as a follow-up in the same issue.
+- TDD plans with more than ~5 RED→GREEN cycles usually conceal a deeper design issue. Short plans (2-3 cycles) reflect confident root-cause identification; long plans reflect fishing.
+- The `debugger` agent explored autonomously but returns a narrative. Parse it for: confirmed hypothesis, code paths, and recent changes. Discard speculation.
+- Bugs in framework-adjacent code (middleware, ORM hooks) require test setup that mirrors the framework's call context. A TDD plan that writes the test "like a unit test" may not actually reproduce the framework bug.
+
+## When NOT to Use
+
+- For a conversational bug report from a non-engineer — use `/qa-session` first, which returns refined reports this skill can then process
+- For a specific reproducible error with known root cause — use `/fix` directly
+- For architectural-scale problems — use `/architecture-audit`
+- For creating issues from a PRD — use `/prd-to-issues`
+- For debugging without filing an issue — use `/debug`

package/app/skills/ubiquitous-language/SKILL.md

@@ -64,11 +64,26 @@ Extract and formalize domain terminology into a consistent glossary.
 
 ## Rules
 
-- **Be opinionated** — pick the best term, list others as aliases to avoid
-- **Flag conflicts explicitly** — call out ambiguous usage with clear recommendations
-- **Domain terms only** — skip generic programming concepts (array, function, endpoint)
-- **Tight definitions** — one sentence max, define what it IS not what it does
-- **Show relationships** — bold term names, express cardinality
-- **Group naturally** — multiple tables when clusters emerge, one table if cohesive
-- **Example dialogue** — 3-5 exchanges showing terms used precisely
-- **Keep existing** — when re-running, read existing file and update incrementally
+- **MUST** be opinionated — pick the best term and list alternatives as aliases to avoid
+- **MUST** flag every ambiguity (one word → two concepts) and every synonym (two words → one concept) with an explicit recommendation
+- **MUST** write tight definitions (one sentence) that define what the term **is**, not what it does
+- **NEVER** include generic programming concepts (array, function, endpoint, class) — this glossary is for the **domain**, not the toolchain
+- **NEVER** silently overwrite an existing `UBIQUITOUS_LANGUAGE.md` — read the current file first, then update incrementally preserving prior decisions
+- **CRITICAL**: show relationships with cardinality ("an Order belongs to exactly one Customer"). Vocabulary without relationships is a word list, not a language.
+- **MANDATORY**: include 3-5 example dialogue exchanges showing correct usage. Abstract glossaries without dialogue rarely get adopted.
+
+## Gotchas
+
+- Domain terms often **overlap** with framework jargon (e.g., "Service" in DDD vs "Service" in Angular). If the framework already claims a term, prefer a domain-specific alternative to avoid collision.
+- Stakeholders resist terminology change even when their current terms are ambiguous. "Account" replacing "User" triggers more discussion than expected — plan for negotiation in the example dialogue section.
+- Glossaries rot when features ship without updating them. A `UBIQUITOUS_LANGUAGE.md` last updated 6 months ago is a snapshot, not a source of truth. Flag staleness in the header and re-run this skill periodically.
+- Relationships between terms are easy to hand-wave with "related to". Pin down the cardinality (`0..1`, `1..*`, `1..1`) — vague relationships produce schema ambiguity later.
+- The opinionated canonical choice may contradict marketing or legal language. Note conflicts explicitly rather than hiding them; the domain model and the marketing site can legitimately diverge.
+
+## When NOT to Use
+
+- For writing a **PRD** (full requirements) — use `/write-a-prd`
+- For generating user-facing documentation — use `/docs`
+- For implementation planning — use `/plan` or `/prd-to-plan`
+- For enforcing language in commit messages or code reviews — use `/brand-voice` (distinct concern: writing style, not domain terms)
+- When the project is a single-developer throwaway — glossary overhead is not justified