@softspark/ai-toolkit 2.11.0 → 3.0.0

package/app/skills/briefing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: briefing
-description: "Generate executive daily briefing across all agents"
+description: "Generate an executive daily briefing that aggregates reports from all agents into a short, decision-focused summary. Use when the user asks for a status update across the whole system — not for one-agent activity reports."
 effort: medium
 disable-model-invocation: true
 agent: chief-of-staff
@@ -25,3 +25,43 @@ Triggers the Chief of Staff to generate an executive summary.
 2. **Synthesize**: Group by category (Ops, Strategy, Actions).
 3. **Filter**: Remove low-priority success logs.
 4. **Present**: Render the Daily Brief.
+
+## Example
+
+```
+## Daily Brief — 2026-04-23
+
+### Ops
+- night-watch: 3 dep updates shipped, 1 rolled back (breaking change in `x-pkg@2.0`)
+- health: all green except `mailpit` (degraded, non-critical)
+
+### Strategy
+- predict: new PR #42 overlaps with in-flight refactor in `/src/auth`
+
+### Actions needed
+- Review rollback from night-watch (ETA: 5 min)
+- Decide on `x-pkg` pin strategy (open question on GitHub #41)
+```
+
+## Rules
+
+- **MUST** stay under 200 words unless the user explicitly asks for more detail
+- **MUST** lead with decision-relevant facts, not chronology — "what should I act on" before "what happened"
+- **NEVER** invent agent activity — report only what the logs show; absence of logs means "no data", not "nothing happened"
+- **CRITICAL**: separate Ops (what ran) from Strategy (what was decided) from Actions (what needs a human) — mixing them defeats the brief
+- **MANDATORY**: when no material activity exists for a category, omit the category heading instead of writing "none"
+
+## Gotchas
+
+- `kb/learnings/` often mixes drafts with completed entries. Filter by frontmatter `status: final` or by filename convention before aggregating.
+- `maintenance/` branch logs from `/night-watch` use a different format (Shift Report markdown) than agent run logs. Do not concatenate blindly — parse each source separately and normalize.
+- "Recent runs" without an explicit time bound defaults to **everything** on some log backends. Always pass `--since` or a date filter, or you will read a week into yesterday's memory.
+- Successful runs outnumber interesting runs by an order of magnitude. Aggressively filter green/noop entries — they are the signal's noise floor.
+
+## When NOT to Use
+
+- For a specific production incident — use `/workflow incident-response`
+- For one-agent activity detail — read that agent's logs directly (`kb/learnings/<agent>/`)
+- For planning future work — use `/plan` or `/prd-to-plan`
+- For a technical system-up/down status — use `/health`
+- When no agents have produced logs in the window — say so and stop; do not pad

package/app/skills/build/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: build
-description: "Build the project with auto-detected toolchain"
+description: "Build the project with auto-detected toolchain (npm, poetry, cargo, go, flutter, Docker). Use when the user asks to compile, bundle, or produce artifacts — not to run tests or deploy."
 effort: low
 disable-model-invocation: true
 argument-hint: "[target]"
@@ -95,3 +95,26 @@ After build configuration changes, update documentation:
 - [ ] Build successful
 - [ ] **README build instructions updated** (if changed)
 - [ ] **CI/CD config documented**
+
+## Rules
+
+- **MUST** detect the build system automatically (`detect-build.py`) before invoking any command
+- **NEVER** run a `clean` build when incremental works — clean only on explicit user request
+- **CRITICAL**: surface the first build error literally, including the stack trace and file:line. Paraphrasing loses the diagnostic.
+- **MANDATORY**: on success, report the artifact paths (compiled binaries, bundled output, built images) — callers downstream need them
+
+## Gotchas
+
+- `npm run build` does not refresh `node_modules`. If `package-lock.json` is out of sync, the build runs against stale dependencies and "succeeds" with wrong versions. In CI always precede with `npm ci`.
+- `cargo build --release` takes 5-10× longer than debug. Never use `--release` in a dev loop; reserve it for CI artifacts and benchmarks.
+- `docker compose build` keys layer cache per service. A change to a shared context file (e.g., root `COPY . .`) invalidates every service's cache. Structure Dockerfiles to copy dependency manifests first, source last.
+- `flutter build apk` without `--split-per-abi` produces a fat APK ~3× larger than needed. Production builds should always split unless explicitly bundling.
+- `go build ./...` succeeds with a warning when a package has no Go files (e.g., pure-doc subdir). Downstream tools that expect every listed package to compile a binary fail silently — check `go build -v` for the list of built packages.
+
+## When NOT to Use
+
+- For running tests — use `/test`
+- For deployment or artifact push — use `/deploy`
+- For scaffolding a new build system — use `/app-builder` or `/ci`
+- For CI pipeline generation — use `/ci`
+- When the project has no build step (interpreted code, pure docs) — this skill has nothing to do

package/app/skills/chaos/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: chaos
-description: "Inject controlled faults for resilience testing"
+description: "Inject controlled faults for resilience testing on non-production targets. Use when the user explicitly asks for a chaos experiment, latency injection, or dependency kill — never implicit."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[target]"
@@ -30,3 +30,24 @@ Triggers a controlled resilience experiment.
 4. **Observe**: Monitor logs/metrics for 60s.
 5. **Recover**: Restore system health.
 6. **Report**: Did we survive?
+
+## Rules
+
+- **MUST** verify target environment is non-production before injecting
+- **NEVER** run against a system without a healthy baseline
+- **CRITICAL**: abort immediately if recovery does not complete within the observation window
+- **MANDATORY**: log every injected fault with timestamp and scope
+
+## Gotchas
+
+- `NODE_ENV=production` on a developer's machine is common — checking that env var alone is not enough proof of non-prod. Combine with kubeconfig context, cloud account ID, or a project-specific env file check before injecting.
+- `docker stats` reports cached values; the first sample immediately after injection is often pre-fault. Wait at least 5 seconds before reading metrics.
+- Kubernetes liveness probes may self-heal the faulted pod inside the 60s observation window — the report shows green while the workload is still flapping. Check pod restart counters, not just health endpoints.
+- Latency injected with `tc` (Linux traffic control) persists across container restarts on the host and across SIGTERM. Always pair the inject step with an explicit `tc qdisc del dev <iface> root` cleanup in the recover step — the `fork` context will not undo it for you.
+
+## When NOT to Use
+
+- In production without an explicit, written runbook — use `/workflow incident-response` for real incidents
+- When the system has no observability (no metrics, no logs) — fix observability first
+- For load testing — use dedicated load-test tooling, not chaos injection
+- During an active incident — stabilize first with `/panic`, then investigate

package/app/skills/ci/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ci
-description: "Detect and run CI pipeline with status reporting"
+description: "Detect, generate, or troubleshoot CI/CD pipeline configuration for the current project type (GitHub Actions, GitLab CI). Use when the user asks to set up, update, or debug a build pipeline — not for running tests locally."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[platform]"
@@ -75,3 +75,24 @@ Returns JSON with:
 
 ## Reference Skill
 Use `ci-cd-patterns` skill for pipeline templates and best practices.
+
+## Rules
+
+- **MUST** detect existing CI platform before generating a new config — do not overwrite silently
+- **NEVER** commit generated CI configs that embed hardcoded secrets or tokens
+- **CRITICAL**: preserve existing job names and triggers unless the user explicitly asks for a restructure
+- **MANDATORY**: every generated pipeline must include lint + test stages at minimum
+
+## Gotchas
+
+- GitHub Actions YAML parses `on:` as a reserved word only when unquoted. Writing `"on":` (quoted) produces a valid-looking file whose workflow **never triggers**. YAML anchors in this field also silently break.
+- GitLab CI's `rules:` and `only:/except:` are mutually exclusive at the job level. Mixing them fails parse on pipeline run but not at `git push` time — test with `gitlab-ci-lint` before committing.
+- `secrets.*` in GitHub Actions is undefined in workflows triggered from **forked** PRs (security boundary). Jobs that need secrets must gate on `github.event.pull_request.head.repo.full_name == github.repository` or use `pull_request_target` carefully.
+- `actions/checkout@v4` defaults to `fetch-depth: 1` (shallow). Commands that need history (`git log`, `git describe`, conventional-commit tools) fail with misleading errors — set `fetch-depth: 0` for those jobs.
+
+## When NOT to Use
+
+- For running tests locally — use `/test`
+- For general CI/CD patterns and theory — use `/ci-cd-patterns` (knowledge skill)
+- For deployment orchestration only — use `/deploy`
+- When the project has no VCS-hosted CI platform — generate locally-runnable scripts instead

package/app/skills/ci-cd-patterns/SKILL.md

@@ -308,3 +308,28 @@ env:
 - Manual deployments to production
 - No rollback strategy
 - Skipping linting/type-checking in CI
+
+## Rules
+
+- **MUST** include lint, test, and build stages in every pipeline — deploy-only pipelines defer failure to production
+- **MUST** cache dependencies by lockfile hash, not by branch name — branch keys grow unbounded and leak cache across unrelated work
+- **NEVER** commit secrets to the pipeline config — use the platform's secret store and reference by name
+- **NEVER** echo secrets to job logs; GitHub Actions masks known secrets only if they came from `secrets.*`, not from arbitrary env vars
+- **CRITICAL**: every deployment path has a defined rollback — "we'll figure it out" is not a plan and will cost hours during an incident
+- **MANDATORY**: PR builds run the same checks as `main` builds; drift between the two hides failures until merge
+
+## Gotchas
+
+- GitHub Actions masks secret values sourced from `${{ secrets.X }}` only. Secrets routed through `env:` and then transformed (base64, JSON) lose the mask and appear in logs verbatim.
+- Workflows triggered by `pull_request` from forks run **without** repository secrets by default (security). Jobs that need secrets either gate on `github.event.pull_request.head.repo.full_name == github.repository` or use `pull_request_target` with explicit code-review — the latter is easy to get wrong and allow token theft.
+- `actions/cache` restore is best-effort — a cache miss is silent. Jobs that rely on the cache (e.g., skipping tests when nothing changed) must verify cache hits explicitly via the `cache-hit` output.
+- GitLab CI's `rules:` and `only:/except:` are mutually exclusive at the job level. Mixing parses only at pipeline run, not at `git push`.
+- Semantic-release assumes a linear history. Merge commits on `main` confuse the commit parser and produce no release — stick to squash merges if you rely on it.
+
+## When NOT to Load
+
+- For **generating** a pipeline file for the current project — use `/ci` (this skill is knowledge, not code)
+- For one-off deployment commands — use `/deploy`
+- For language-specific build toolchain nuances — pair with `/typescript-patterns`, `/python` rules, etc.
+- For observability or alerting around deploys — use `/observability-patterns`
+- For security scanning (SAST, SCA) steps in pipelines — use `/security-patterns` and `/cve-scan`

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

@@ -49,12 +49,15 @@ model: sonnet
 - Prefer numbered phases for multi-step workflows
 - List required checks explicitly (`lint`, `tests`, `docs`, etc.)
 - Avoid hidden assumptions about project structure unless the command is project-specific
+- **Description ≥50 chars** with a trigger hint (`Use when…`) — short descriptions cause adjacent commands to fight for the same query
+- Include **hard rules** (MUST / NEVER / CRITICAL) so the agent cannot improvise around safety boundaries
+- Include **"When NOT to use"** naming 2-3 adjacent commands, to prevent over-triggering
 
 ## Minimal Template
 
 ```markdown
 ---
-description: "{one-line description}"
+description: "{Third-person description, min 50 chars, with trigger hint like 'Use when...'}"
 argument-hint: "[arguments]"
 allowed-tools: Read, Grep, Bash
 ---
@@ -70,12 +73,38 @@ Perform the requested task using this workflow:
 3. Execute the task using the smallest safe set of changes.
 4. Validate the result.
 5. Summarize outcome and follow-up actions.
+
+## Example
+
+\`\`\`
+/{command} example-argument
+\`\`\`
+
+## Rules
+
+- **MUST** {non-negotiable rule}
+- **NEVER** {forbidden action}
+
+## Gotchas
+
+- {environment-specific trap — only if the command has one; omit the section otherwise}
+
+## When NOT to Use
+
+- For {adjacent use case} -- use `/{other-command}` instead
+- If {precondition} is not met
 ```
 
+Follow [Anthropic's Gotchas guidance](https://agentskills.io/skill-creation/best-practices.md#gotchas-sections): *"concrete corrections to mistakes the agent will make without being told otherwise"* — not general advice. Omit the section when no domain traps exist.
+
 ## Validation Checklist
 
 - [ ] Command file uses markdown and valid YAML frontmatter
-- [ ] Help text is concise and searchable
+- [ ] Description ≥50 chars, third-person, with trigger hint
+- [ ] At least one concrete code-fenced example
+- [ ] `## Rules` with MUST / NEVER / CRITICAL (prescriptive)
+- [ ] `## Gotchas` when the command has real environment-specific traps (optional)
+- [ ] `## When NOT to Use` section naming 2-3 adjacent commands
 - [ ] Body is instruction-oriented, not user-facing prose
 - [ ] `$ARGUMENTS` is present when arguments are expected
 - [ ] Validation steps are explicit

package/app/skills/content-moderation-patterns/SKILL.md

@@ -139,3 +139,28 @@ Build a golden set of ~500 examples per category with ground truth. Track:
 - `prompt-caching-patterns` — cache the policy doc
 - `model-routing-patterns` — when to escalate from Haiku to Sonnet
 - Anthropic docs: https://docs.claude.com/en/docs/about-claude/use-case-guides/content-moderation
+
+## Rules
+
+- **MUST** pre-filter the obvious cases (regex, deny-lists, length caps) before sending to an LLM — LLM moderation on a 500MB comment is unusable
+- **MUST** return a structured JSON classification (category, confidence, reason), not a prose verdict — prose breaks audit trails
+- **NEVER** ship a moderation pipeline without a human-in-the-loop escalation path for ambiguous cases
+- **NEVER** hide the policy in the user message; the policy belongs in the cached system prompt so it is versioned and auditable
+- **CRITICAL**: log every decision (input, category, confidence, model, policy version, timestamp) — moderation without an audit trail cannot be improved or appealed
+- **MANDATORY**: calibrate confidence thresholds per category; harassment FP is cheap, clean-content FP is expensive
+
+## Gotchas
+
+- False positives on clean content are **much more expensive** than false negatives on borderline content, in user-trust terms. Optimize for recall on hard-fail categories (CSAM, doxing) but precision on soft-fail categories (spam, rudeness).
+- Haiku is sufficient for most moderation classification; using Opus inflates cost 10× with no measurable accuracy gain on this task. Reach for Opus only for edge cases that Haiku consistently misclassifies.
+- Prompt caching on the policy doc only hits when the cache window is still warm (5 minutes). Bursty traffic with long quiet periods loses the cache every window — amortize by keeping a heartbeat call.
+- Structured JSON output via tool-use is more reliable than free-form JSON in the response — parse errors happen ~1-3% of the time with free-form, near zero with tool-use schemas.
+- The golden test set drifts. Policy changes, new attack patterns, and new product surfaces all invalidate old examples. Refresh quarterly or after any policy update.
+
+## When NOT to Load
+
+- For **structured JSON output** design in general — use `/json-mode-patterns`
+- For **security** input validation (SQLi, XSS) — use `/security-patterns`
+- For caching the policy doc mechanics — use `/prompt-caching-patterns`
+- For picking the model tier (Haiku vs Sonnet vs Opus) — use `/model-routing-patterns`
+- For moderation of voice/audio content — this skill covers text; audio adds a transcription failure mode not covered here

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

@@ -306,3 +306,28 @@ client.create_payload_index(
 | "NoSQL is faster" | NoSQL trades consistency for speed — if you need joins, use a relational DB |
 | "We don't need migrations, we'll update the schema directly" | Direct schema changes are irreversible and untestable — migrations are the safety net |
 | "One big table is simpler" | Denormalization without measurement creates update anomalies — normalize first, denormalize with data |
+
+## Rules
+
+- **MUST** profile queries with `EXPLAIN (ANALYZE, BUFFERS)` before adding an index — indexes chosen by intuition miss the real hot path half the time
+- **MUST** design the schema around the dominant access pattern, not the logical entity graph — storage follows queries, not the other way round
+- **NEVER** write to production with raw SQL when a migration file fits — ad-hoc changes break rollback and audit
+- **NEVER** add a `SELECT *` in a loop — N+1 is the most common performance regression in code review
+- **CRITICAL**: every foreign key has an index on the referencing column. Postgres does not create one automatically, and `ON DELETE CASCADE` without the index causes full-table scans on delete.
+- **MANDATORY**: numeric IDs use `bigint` (or `bigserial`) in new tables unless there is a stated reason to cap at 2^31. Integer overflow on a growing table is a late, painful surprise.
+
+## Gotchas
+
+- `EXPLAIN` without `ANALYZE` shows the planner's estimate, not the actual execution. A query plan that "looks good" with `EXPLAIN` can still be slow in practice — always use `ANALYZE` for real diagnosis.
+- ORM-generated queries often look efficient in one row but emit N+1 at scale. `prisma`, `sequelize`, `activerecord` all have "eager loading" switches that must be explicit — the default is lazy and bites under load.
+- Postgres transactions hold **row locks** until commit or rollback. A long-running transaction that reads rows another writer needs blocks progress silently. Investigate `pg_stat_activity` for `state=idle in transaction` when writes stall.
+- Index-only scans require both the query columns AND the filter to be in the index (or in the visibility map for heap tuples). Adding a single column to `WHERE` can demote an index-only scan to an index scan with a 10× slowdown.
+- MySQL implicit collation on JOIN across tables with different `utf8mb4` collations forces a row-by-row collation conversion — a 100× slowdown that shows as a full scan in the plan. Align collations during schema design.
+
+## When NOT to Load
+
+- For **schema evolution** (zero-downtime, expand-contract, backfill) — use `/migration-patterns`
+- For running migrations as a task — use `/migrate`
+- For query-plan profiling and the four golden signals — use `/performance-profiling`
+- For vector/embedding-specific schema — this skill covers the mechanics; use `/rag-patterns` for retrieval design
+- For observability of DB metrics (slow query log, connection pool saturation) — use `/observability-patterns`

package/app/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: "Debug errors and trace root causes systematically"
+description: "Debug errors and trace root causes systematically using logs, health checks, and hypothesis-driven investigation. Use when a bug or error message is in hand — not for architectural questions or when there is no reproducible symptom."
 user-invocable: true
 effort: medium
 argument-hint: "[symptom]"
@@ -163,6 +163,28 @@ Report consensus when done.
 - [ ] Formed hypothesis
 - [ ] Tested fix
 
+## Rules
+
+- **MUST** form a testable hypothesis before changing code
+- **NEVER** apply fixes without first reproducing the symptom
+- **CRITICAL**: trace from symptom to root cause — do not stop at the first plausible explanation
+- **MANDATORY**: if the bug is intermittent, log enough state to reproduce it deterministically before fixing
+
+## Gotchas
+
+- `docker compose logs` with no `--since` shows logs from **the current container lifecycle plus anything buffered**. After a restart you may read stale logs that look like the current error. Always filter: `docker compose logs --since 5m`.
+- `tail -f` stops emitting after a log rotation unless you pass `-F` (GNU) or `--follow=name` — the file descriptor points at the renamed inode. On rotated logs, always use `-F`.
+- `curl -f <url>` exits non-zero on 4xx/5xx but discards the response body — you lose the exact error. Debug with `curl -s -o /tmp/body -w 'HTTP %{http_code}\n'` and then inspect `/tmp/body`.
+- Stack traces from uvicorn/gunicorn/WSGI show framework frames first; the first few frames are almost always irrelevant. Scroll past framework internals and find the first frame inside your own package.
+- A 500 with "Internal Server Error" and no body usually means the error happened before the logger was initialized — check service start-up logs, not request logs.
+
+## When NOT to Use
+
+- For triaging an unreported bug without a known symptom — use `/triage-issue` instead
+- For writing a fix once the cause is already known — use `/fix`
+- For performance-specific investigation — use `/performance-profiling` or `/analyze --type=complexity`
+- For a live production incident — use `/workflow incident-response` (coordinated response)
+
 ## Related Skills
 - Bug fixed? → `/review` to verify the fix quality
 - Need a regression test? → `/tdd` to write it test-first

package/app/skills/design-engineering/SKILL.md

@@ -256,3 +256,28 @@ Deliberate actions stay slow (2s linear for hold-to-delete), system responses sn
 - Same duration for enter and exit — exits should be faster
 - Hover effects without `@media (hover: hover)` — breaks touch devices
 - Framer Motion shorthands under load — drops frames on main thread
+
+## Rules
+
+- **MUST** specify exact properties in `transition` (`transition: transform 200ms ease-out`) — never `transition: all`
+- **MUST** use `ease-out` (or a custom curve) on UI appearances; `ease-in` delays feedback at the moment the user's attention peaks
+- **NEVER** animate `height`, `width`, `margin`, or `top/left` — animate `transform` and `opacity` only. Layout-triggering properties drop frames under load.
+- **NEVER** add motion for decorative reasons alone — every animation must serve meaning (status change, spatial relationship, progress)
+- **CRITICAL**: exit is faster than enter. A 2s linear enter (hold-to-delete) needs a 200ms ease-out exit. Symmetrical durations feel sluggish.
+- **MANDATORY**: any animation longer than 300ms for UI feedback needs an explicit justification — the user perceives >300ms as "laggy", not "smooth"
+
+## Gotchas
+
+- `transform: translateX(-50%)` on an element that will animate `opacity` triggers a paint on every frame because the browser cannot composite the layer. Add `will-change: transform, opacity` to hint the compositor — but only during the animation, not permanently (it consumes GPU memory).
+- Framer Motion's `x={100}` prop is a shortcut for `transform: translateX(100px)`, but under load it falls back to the main thread. Use the longhand `style={{ transform: "translateX(100px)" }}` for guaranteed compositor path.
+- `@media (prefers-reduced-motion: reduce)` is widely supported but often forgotten. Users with vestibular disorders or pointer-device sensitivity will notice; include a reduced-motion override for every non-trivial animation.
+- Chrome's Performance tab samples animations, but the sampling rate is 1kHz — sub-millisecond jank is invisible. For micro-animations, prefer `performance.mark` and `measure` with explicit timestamps.
+- CSS keyframe animations re-trigger on every class toggle. On rapidly-updating state (drag, hover), transitions are cheaper and smoother; keyframes are for one-shot entries/exits.
+
+## When NOT to Load
+
+- For **accessibility** beyond motion (contrast, focus, ARIA) — use `/a11y-validate`
+- For component-library architecture (Radix, Headless UI, ShadCN) — use `/frontend-specialist` agent
+- For **information architecture** and user flows — use `/ux-designer` agent
+- For generic CSS patterns without motion — this skill is motion-specific
+- For **brand voice** / content tone — use `/brand-voice`

package/app/skills/docker-devops/SKILL.md

@@ -302,3 +302,29 @@ HEALTHCHECK --interval=30s --timeout=10s --retries=3 \
 - [ ] Resource limits defined
 - [ ] Health checks configured
 - [ ] Logs to stdout/stderr
+
+## Rules
+
+- **MUST** use multi-stage builds for any production image — shipping build tools in the final layer is wasteful and insecure
+- **MUST** pin base images by digest (`@sha256:...`), not just by tag — tags are mutable and reproducibility collapses on every `latest` update
+- **NEVER** run a container as `root` in production — `USER appuser` with a non-zero UID is the default, not an optimization
+- **NEVER** `COPY . .` before the dependency manifest — layer cache becomes useless and every source change re-downloads packages
+- **CRITICAL**: logs go to stdout/stderr. Containers writing to log files require volumes, lose on crash, and break 12-factor assumptions.
+- **MANDATORY**: every Dockerfile has a `HEALTHCHECK`, every compose service has `restart: unless-stopped` (or `always` in production)
+
+## Gotchas
+
+- `alpine` uses `musl` libc, not `glibc`. Python wheels compiled for glibc fail to install on alpine — use `python:3.12-slim` (glibc-based, small) instead of `python:3.12-alpine` unless you know every dependency ships a musl wheel.
+- `docker compose build` caches layers per service. A change to a shared file (e.g., root `COPY . .` used by two services) invalidates both caches. Structure Dockerfiles to copy manifests first, source last.
+- `HEALTHCHECK` in a Dockerfile is only respected by Docker and Compose, **not by Kubernetes**. K8s uses its own `livenessProbe` / `readinessProbe`. Maintaining both costs duplicate logic.
+- `docker compose up -d` streams build output only to the terminal, not to a build log. CI that captures `docker compose up -d` silently misses build errors — use `docker compose build` as a separate step with log redirection.
+- Container time is host time unless you mount `/etc/localtime` — a container running on a UTC host is UTC regardless of its `TZ` env var for anything reading `/etc/localtime`. For Python `datetime.now(timezone.utc)` is safer than `datetime.now()` inside containers.
+- `volumes: ./data:/app/data` on macOS with VirtioFS mounts with inverted ownership (host UID vs container UID). Containers that chmod/chown the volume fail silently in dev, succeed in Linux CI.
+
+## When NOT to Load
+
+- For **CI/CD pipeline** design that uses Docker — use `/ci-cd-patterns`
+- For generating a project-specific Dockerfile — use `/app-builder`
+- For Kubernetes-specific manifests beyond Docker — this skill covers compose + basics; use `/devops-implementer` agent for k8s depth
+- For **observability** of containers (metrics, logs, traces) — use `/observability-patterns`
+- For **secret management** at runtime — use `/security-patterns`

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

@@ -208,3 +208,29 @@ Product → Indexer → Search Index (Elasticsearch/OpenSearch)
 - [ ] Enable flat tables
 - [ ] Configure CDN
 - [ ] Index optimization
+
+## Rules
+
+- **MUST** model order lifecycle as an explicit state machine (pending → authorized → captured → fulfilled → refunded) — ad-hoc booleans produce inconsistent states on retry
+- **MUST** separate payment capture from inventory decrement — reserve stock on order placement, commit stock on payment success. Coupling them causes stuck-stock bugs during payment retries.
+- **NEVER** store CVV, full PAN, or track data — ever. PCI scope expands to any system that sees them, even "temporarily in memory".
+- **NEVER** use floating-point for money calculations. Use `decimal.Decimal`, `BigDecimal`, or integer minor units (cents). Float rounding produces $0.01 discrepancies that accumulate into angry customer emails.
+- **CRITICAL**: every cart mutation is idempotent via an `Idempotency-Key` or natural key — users double-click checkout buttons, networks retry, and duplicate orders are expensive to reconcile.
+- **MANDATORY**: tax and shipping calculations live in isolated services or modules. Inlining them into cart logic prevents caching and creates compliance drift.
+
+## Gotchas
+
+- Promotion codes with stackable rules explode combinatorially — "20% off + free shipping + first-time buyer" can produce negative totals if the ordering of applications is not defined. Always normalize to a pipeline with a fixed evaluation order.
+- Tax jurisdictions change **after** the order is placed (shipping address edits). A cart that recalculates on every update but not on address change silently under-collects tax.
+- Inventory reservations must expire — otherwise abandoned carts hold stock forever. 15-30 minutes is typical; longer reservations need explicit business approval.
+- Currency rounding rules differ by locale. Japanese Yen has 0 decimal places, Kuwaiti Dinar has 3. Defaulting to 2 decimals produces off-by-one-unit bugs in non-USD markets.
+- Refunds are **not** negative orders. Payment processors treat them as separate resources with their own state machine and timing (Stripe refunds can take 5-10 business days to settle). Model accordingly.
+- Magento's flat-table option speeds reads but silently stops auto-syncing if a reindex fails — stale product data in production. Monitor reindex job success, not just page latency.
+
+## When NOT to Load
+
+- For **payment provider** protocol specifics (Stripe, Adyen, PayPal) — use the provider's SDK docs; this skill is pattern-level
+- For generic API design — use `/api-patterns`
+- For database schema of orders/inventory — use `/database-patterns`
+- For promotions and segmentation at scale — use `/data-analyst` agent
+- For PCI compliance audit — this skill flags the traps but is not a substitute for a QSA audit

package/app/skills/evaluate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: evaluate
-description: "Evaluate skill quality and RAG retrieval accuracy"
+description: "Evaluate RAG retrieval accuracy and LLM-as-a-judge quality metrics (faithfulness, relevancy, context precision) against a golden dataset. Use when the user asks to measure RAG quality or detect knowledge gaps — not for evaluating generic LLM outputs."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[--threshold N]"
@@ -130,3 +130,24 @@ Knowledge Gaps Detected:
 - [ ] Relevancy >70%
 - [ ] Context Precision >60%
 - [ ] No critical knowledge gaps
+
+## Rules
+
+- **MUST** use a golden dataset — never evaluate on synthetic queries only
+- **NEVER** report a score without listing the failed queries alongside it
+- **CRITICAL**: if the golden dataset is missing, stop and ask the user to provide one
+- **MANDATORY**: thresholds come from project config, not hardcoded defaults, when available
+
+## Gotchas
+
+- LLM-as-a-judge scores are **non-deterministic**; a single run fluctuates by ±10 points even with `temperature=0`. Always report the average and stddev over ≥3 runs, not a one-shot number.
+- The default threshold trio (0.7 / 0.7 / 0.6) was calibrated on English KBs. Multilingual corpora (Polish + English in the same index) score systematically 5-15 points lower — recalibrate per language, or split the golden dataset by language.
+- Golden datasets **drift**: when the KB is reindexed or documents are renamed, `expected_sources` may point at moved or deleted paths. A sudden drop in `context_precision` across unrelated queries usually means dataset rot, not RAG regression — validate the dataset paths first.
+- Judges often reward verbose answers as "more faithful" because there is more text to ground. Tune the judge prompt to penalize padding, or cap answer length in the generator before evaluation.
+
+## When NOT to Use
+
+- For auditing skill quality (the 5-criteria check) — that lives in `scripts/evaluate_skills.py`
+- For general-purpose LLM output scoring without a KB — use `/review` or a tailored prompt
+- For unit tests or code correctness — use `/test`
+- For continuous evaluation without a golden dataset — build the dataset first

package/app/skills/evolve/SKILL.md

@@ -65,3 +65,28 @@ Create a summary documenting what evolved:
   - `app/agents/[name].md`: [what changed and why]
 - **Validation**: passed / failed
 ```
+
+## Rules
+
+- **MUST** delegate file edits to the `meta-architect` agent — this command is the trigger, the agent owns the changes
+- **MUST** have a concrete failure signal (recurring error, named incident, repeated correction) before evolving — do not mutate based on vibes
+- **NEVER** evolve an agent based on a **single** failure instance — evolution is pattern-matching, not reaction
+- **NEVER** touch `.claude/agents/*` files directly from this skill; `meta-architect` is the only agent with that authority
+- **CRITICAL**: every evolution names the trigger, the change, and the expected measurable shift (e.g., "reduces false routing of `/debug` to `/fix`")
+- **MANDATORY**: run `scripts/validate.py --strict` after every applied change; roll back if the score drops
+
+## Gotchas
+
+- Small changes to an agent's description can silently re-route a dozen adjacent queries. After an evolution, run the skill router against a saved set of representative queries to confirm no drift.
+- `kb/learnings/` entries without a `status: final` frontmatter field are often drafts — aggregating them treats speculative observations as validated patterns. Filter by status before mining.
+- "Last-failure" often points at the **symptom**, not the root cause. A route-to-wrong-agent failure may actually be a description-field ambiguity; fix the description, not the router.
+- Changes to agent frontmatter fields (`tools`, `model`) propagate to the installed global config only after `ai-toolkit update`. A locally-evolved agent still runs old behavior until the user reinstalls.
+- Evolution in isolation invites regression. Keep a changelog (`kb/learnings/` entries or `CHANGELOG.md`) so future sessions can see what was tried and reverted.
+
+## When NOT to Use
+
+- For a specific, known agent edit — call `meta-architect` directly
+- For fixing a failing test — use `/fix` or `/debug`
+- For auditing **current** skill/agent quality — use `scripts/evaluate_skills.py` and `scripts/audit_skills.py --ci`
+- For creating a **new** agent — use `/agent-creator`
+- When no recurring pattern exists (single data point) — wait and observe; do not over-fit to noise

package/app/skills/explain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explain
-description: "Explain code, architecture, or concepts with diagrams"
+description: "Explain code, architecture, or concepts with Mermaid diagrams and sequence flows. Use when the user asks 'what does X do' or 'how does Y work' — not to critique code quality or implement changes."
 user-invocable: true
 effort: medium
 argument-hint: "[file or module path]"
@@ -52,3 +52,28 @@ Run the bundled script to extract imports and generate a Mermaid diagram:
 ```bash
 python3 ${CLAUDE_SKILL_DIR}/scripts/dependency-graph.py src/auth.py
 ```
+
+## Rules
+
+- **MUST** start from what the user already knows — if it is unclear, ask one question before explaining
+- **MUST** ground the explanation in the actual code (file:line references), not in generic framework theory
+- **NEVER** use an analogy when a direct definition is clearer — analogies add a translation step for the reader
+- **NEVER** produce a diagram that the text does not already justify — diagrams illustrate, they do not replace the explanation
+- **CRITICAL**: when the code base is large, scope the explanation to one entry point plus its immediate collaborators. Explaining "the whole system" in one pass fails for any non-trivial project.
+- **MANDATORY**: if the user asks for a short answer, give a one-paragraph summary without diagrams — not every request needs a Mermaid graph
+
+## Gotchas
+
+- Mermaid renders differently across GitHub, VS Code preview, and static generators. Features added post-2023 (e.g., class diagram relations, `accTitle`) may render as raw text on older renderers. Stick to the basic subset unless you know the target.
+- `dependency-graph.py` parses imports statically; dynamic imports (`__import__`, `importlib.import_module`, JavaScript `await import()`) are invisible. Note explicitly when the generated graph is likely incomplete.
+- Sequence diagrams have no notion of async vs sync. Two parallel calls render as sequential; distinguish with a `par` block or a note.
+- Architectural explanations that name "the service layer" or "the controller" leak framework jargon. If the project does not use those terms, use the project's own names — otherwise the reader is translating twice.
+- Long Mermaid graphs wrap awkwardly on narrow screens. For >20 nodes, split into a high-level graph and drill-down graphs rather than one giant diagram.
+
+## When NOT to Use
+
+- To critique or improve the code — use `/review` or `/refactor`
+- To find a specific function across the codebase — use `/search` or `/explore`
+- To write the documentation that the explanation turns into — use `/docs`
+- For a full architecture audit or redesign — use `/architecture-audit`
+- When the user asks "why is this broken" — use `/debug`, not `/explain`

package/app/skills/explore/SKILL.md

@@ -110,3 +110,28 @@ This generates `codebase-map.html` with collapsible directories, file sizes, and
 smart_query("codebase analysis: {technology}")
 hybrid_search_kb("project structure {framework}")
 ```
+
+## Rules
+
+- **MUST** use `Glob` and `Grep` before `Read` — scan for shape before opening files
+- **MUST** deliver a map of the codebase (entry points, layers, module boundaries), not a file listing — a tree without interpretation is noise
+- **NEVER** read every file sequentially; target reads via grep patterns and filename globs
+- **NEVER** modify any file — this is a read-only skill
+- **CRITICAL**: when the repo contains generated code (`node_modules`, `vendor/`, `dist/`, `build/`), exclude it from scans or the signal drowns in generated noise
+- **MANDATORY**: summarize the stack once at the top (language, framework, package manager, test runner) before diving into structure
+
+## Gotchas
+
+- `find .` and `ls -R` ignore `.gitignore` by default and include `node_modules`, `vendor/`, `.venv/`, `target/`. Use `git ls-files` or `fd` / `rg` for a git-aware listing, or explicitly prune.
+- `package.json` says `"type": "module"` → ESM; absence → CommonJS. Mixing them without noticing produces "Cannot use import statement outside a module" errors later; call out the setting in the report.
+- Frameworks with file-based routing (Next.js, Nuxt, SvelteKit) treat the `app/` or `pages/` tree as the router. A directory listing alone does not reveal routes — the framework convention does. Name the framework first, then the routes.
+- `pyproject.toml` can declare multiple project layouts (src/, flat, namespace packages). "Where is the main code" is not obvious without reading `[tool.setuptools.packages]` or `[tool.poetry.packages]`.
+- Large monorepos use workspaces (`pnpm-workspace.yaml`, `nx.json`, `turbo.json`) with apps and packages. Treating the root as the project conceals the actual component boundaries — surface the workspace topology first.
+
+## When NOT to Use
+
+- To explain a specific module's design — use `/explain`
+- To find a specific identifier or symbol — use `Grep` directly or `/search`
+- To audit architecture for deepening candidates — use `/architecture-audit`
+- To scaffold a new project — use `/app-builder`
+- When the user already knows the codebase — skip the overview and jump to the concrete task

package/app/skills/fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fix
-description: "Auto-fix lint errors, type issues, and simple bugs"
+description: "Apply a targeted fix to a known bug or lint error and verify it with the same command that surfaced the problem. Use when the root cause is already identified — not for unknown symptoms or open-ended debugging."
 effort: low
 disable-model-invocation: true
 argument-hint: "[test or lint target]"
@@ -76,3 +76,28 @@ Agent: Fixing app.py (Import missing module)
 Agent: Running tests... PASS
 Agent: Fixed NameError in app.py
 ```
+
+## Rules
+
+- **MUST** know the exact symptom (error message, failing test, lint code) before editing — guessing is not fixing
+- **MUST** verify the fix by rerunning **the same command** that exposed the problem, not a different validator
+- **NEVER** modify tests to make them pass — fixing the test is not fixing the bug
+- **NEVER** touch files outside the declared scope — scope creep hides regressions
+- **CRITICAL**: hard-stop after 3 iterations. If the fix loop has not converged, the problem is deeper than `/fix` handles — escalate to `/debug`.
+- **MANDATORY**: if new, unrelated errors appear during a fix attempt, stop and ask the user — do not chase them
+
+## Gotchas
+
+- `ruff check --fix` reorders imports and rewrites them. On files with circular imports or conditional-imports-under-TYPE_CHECKING, the "fix" can break things silently. Run `--check` first, inspect the diff, then apply.
+- `eslint --fix --cache` skips already-cached files even if their content changed (cache invalidation by mtime). On first-run misses, clear the cache with `--no-cache` to force a complete pass.
+- `mypy --install-types` auto-installs stub packages, adding dependencies to the environment the user did not request. Reserve it for explicit opt-in; in CI, pass `--non-interactive` to prevent surprise installs.
+- `npm test -- path/to/test` in a workspace repo runs the **root** workspace's test runner, not the leaf package's. Use `npm test --workspace=<name>` or the per-package `cd packages/foo && npm test` form.
+- Fix loops occasionally produce **cycle diffs** — iteration 1 fixes A which triggers B, iteration 2 fixes B which re-breaks A. After every iteration compare the diff to the previous; identical or inverse diffs mean a cycle — stop.
+
+## When NOT to Use
+
+- When the root cause is unknown — use `/debug` first, then `/fix` with a clear target
+- For systemic refactoring across modules — use `/refactor` or `/refactor-plan`
+- For writing new features test-first — use `/tdd`
+- For CI failures spanning many files — use `/workflow debugging` (coordinated)
+- When the failing validation is itself broken — repair the validator separately, do not patch code to satisfy it