@softspark/ai-toolkit 2.11.0 → 3.0.0

package/app/skills/night-watch/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: night-watch
-description: "Run autonomous maintenance and dependency updates"
+description: "Run autonomous maintenance tasks (dependency updates, dead code removal, small refactors) in an isolated branch. Use only when the user triggers it explicitly — typically off-hours; never auto-invoked."
 effort: medium
 disable-model-invocation: true
 context: fork
@@ -26,3 +26,24 @@ Triggers the autonomous maintenance agent.
 2. **Execute**: Run `night-watchman` agent skills.
 3. **Verify**: Run full test suite.
 4. **Report**: Generate Shift Report.
+
+## Rules
+
+- **MUST** work on a dedicated `maintenance/` branch — never commit to `main` or the user's active branch
+- **NEVER** push without the full test suite passing
+- **CRITICAL**: stop on the first failing test and surface it — do not try to "fix" tests opportunistically
+- **MANDATORY**: every change lands in a discrete commit with a conventional message
+
+## Gotchas
+
+- `npm audit fix` bumps to the latest **major** version when `--force` is set — quietly introducing breaking changes. Always use plain `npm audit fix` first and only escalate to `--force` after the user approves each named package.
+- `pip install --upgrade` without a constraints file resolves differently each run due to transitive dependencies. Pin via `pip-compile` and commit the lockfile, otherwise maintenance runs produce "mysterious" unrelated changes.
+- `git add -A` on a maintenance run can pull in build artifacts and IDE caches if `.gitignore` is incomplete. Prefer explicit `git add <path>` per change category (deps, docs, lint-fixes) to keep commits attributable.
+- Pre-commit hooks that format on commit may re-modify files AFTER your edit — the resulting commit may differ from the planned diff. Run the formatter as a separate step and verify `git diff --staged` before committing.
+
+## When NOT to Use
+
+- For planned refactors with a known scope — use `/refactor-plan`
+- For immediate bug fixes — use `/fix` or `/debug`
+- In a repo the user is actively working in — wait for idle time
+- When there are uncommitted changes on the current branch — abort until clean

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

@@ -202,3 +202,29 @@ groups:
 - Include runbook links in annotations
 - Set appropriate severity: page only for user-impacting issues
 - Use `for` duration to avoid flapping
+
+## Rules
+
+- **MUST** emit logs as structured JSON with a `trace_id` (or correlation ID) propagated across service boundaries — unstructured logs are unsearchable at scale
+- **MUST** alert on symptoms (user-visible latency/errors), not causes (high CPU, queue depth) — causes change, symptoms are stable
+- **NEVER** log PII, PHI, or credentials — even at debug level. Logs leak to aggregation systems, backups, and disk snapshots.
+- **NEVER** use histograms without explicit buckets tuned to the expected range — default buckets either miss the p99 or waste cardinality
+- **CRITICAL**: SLOs define alerts, not metrics. An SLO of "99.9% of requests under 200ms" produces one alert ("burn rate exceeded") — not six alerts on each constituent metric.
+- **MANDATORY**: every alert includes a runbook link in its annotations. An alert without a runbook pages someone who then has to invent a response at 3am.
+
+## Gotchas
+
+- `trace_id` must propagate via headers (`traceparent` / `X-Correlation-ID`) AND be added to every log line AND span. Partial propagation produces broken traces — one missing middleware and the span disappears from the UI.
+- OpenTelemetry SDK defaults to `otlp/grpc` on port 4317. Many corporate networks block it; `otlp/http` on 4318 with `traces` path works through proxies. Check connectivity before debugging app-level issues.
+- High-cardinality labels (user IDs, request IDs) on Prometheus metrics explode the time-series database. Prefer exemplars or traces for per-request data; keep metric labels to bounded categorical values.
+- `for: 5m` in Prometheus delays alerts by 5 minutes AND requires the condition to hold throughout — a 4m59s spike does not alert, even if it re-occurs. Use shorter `for` on critical alerts with a higher severity threshold.
+- Log-based metrics (counting log lines matching a regex) are expensive and brittle. A log format change silently breaks the metric; prefer direct instrumentation from the code.
+- Sampled traces (probability = 0.1) miss rare errors by design. For error-path visibility, use "always-sample on error" (tail sampling or head-based with error flag).
+
+## When NOT to Load
+
+- For **implementing** an alert rule or log aggregator — use the tool's docs (Prometheus, Grafana, Datadog); this skill is pattern-level
+- For performance tuning (profiling, flame graphs) — use `/performance-profiling`
+- For incident response mechanics during an outage — use `/workflow incident-response`
+- For generic logging library choice in a new project — use `/app-builder` which handles scaffolding
+- For security auditing of log content (PII leaks) — use `/security-patterns` and `/hipaa-validate`

package/app/skills/onboard/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: onboard
-description: "Generate project onboarding materials"
+description: "Guide setup of ai-toolkit in a new project: install symlinks, create CLAUDE.md, capture undocumented intent via interview. Use when the user starts a fresh project or migrates an existing one to ai-toolkit."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[project-path]"
@@ -91,3 +91,24 @@ Edit `.claude/settings.local.json` for project-specific settings:
 /onboard verify       # Just verify existing installation
 /onboard update       # Update toolkit symlinks
 ```
+
+## Rules
+
+- **MUST** run the intent-capture interview before creating any files — skip only if the user provides answers up front
+- **NEVER** overwrite an existing `CLAUDE.md` without confirming
+- **CRITICAL**: prefer project-local installation (`--local`) unless the user asks for global
+- **MANDATORY**: verify installation at the end with the toolkit's validate script
+
+## Gotchas
+
+- On Windows without WSL, symlink creation requires either Developer Mode or admin privileges. The installer **silently skips** agents and skills that cannot be linked — verify with `ai-toolkit doctor` after install on Windows hosts.
+- If `.claude/` already exists as a real directory (not a symlink), `ai-toolkit install` will not replace it. Old files linger. Check `ls -la .claude/` for mixed symlink + real-file state before onboarding.
+- `settings.local.json` is per-user and gitignored, but `settings.json` is shared. Users who edit the wrong file lose their overrides on `git pull`.
+- When the target project is a **git submodule**, the toolkit's notion of "project root" (outermost `.git`) differs from the developer's — symlinks may land in the parent repo instead of the submodule. Confirm `git rev-parse --show-toplevel` before installing.
+
+## When NOT to Use
+
+- To update an already-onboarded project — use `/onboard update`
+- To scaffold a new app from scratch — use `/app-builder`
+- For plugin development inside ai-toolkit — use `/plugin-creator`
+- When the project already has its own CLAUDE.md conventions — discuss migration before overwriting

package/app/skills/panic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: panic
-description: "Emergency stabilization via system-governor agent"
+description: "Emergency kill switch that halts all agent activity via a lockfile gate. Use when agents are looping, misbehaving, or the user wants to stop everything NOW — not for normal workflow interruptions."
 effort: low
 disable-model-invocation: true
 agent: system-governor
@@ -28,3 +28,23 @@ To resume operations:
 ```bash
 rm .claude/HALT
 ```
+
+## Rules
+
+- **MUST** create the lockfile at `.claude/HALT` — agents check this path to gate execution
+- **NEVER** bypass the lockfile silently once it exists
+- **CRITICAL**: emit a clear, single-line notification so the user knows the system is halted
+- **MANDATORY**: include the provided reason (if any) in the notification
+
+## Gotchas
+
+- The lockfile is **project-local** (`./.claude/HALT`). Agents running in a different working directory, or globally-invoked tools, will not see it and will keep running. `/panic` is not a system-wide kill switch.
+- The lockfile check relies on the `PreToolUse` hook from `ai-toolkit`; if the user disabled hooks in `settings.json` or ejected without keeping hooks, `touch .claude/HALT` does nothing. Verify the hook is present after invocation.
+- Removing `.claude/HALT` mid-task resumes agents that were blocked, but they resume with potentially **stale context** (conversation moved on, tool results orphaned). Prefer restarting the session cleanly if possible.
+
+## When NOT to Use
+
+- For cancelling a single agent — use the task's own stop mechanism
+- For a production incident — use `/workflow incident-response`
+- As a rollback tool — use `/rollback`
+- To pause for a short clarification — just ask the question, do not halt the system

package/app/skills/performance-profiling/SKILL.md

@@ -67,3 +67,37 @@ Always measure -> change -> measure.
 | "Caching will fix it" | Caching masks problems and adds complexity — fix the root cause first |
 | "It's fast enough in dev" | Dev has 1 user — production has thousands and cold caches |
 | "We'll optimize later" | Performance debt compounds — a 100ms regression per sprint = 5s in a year |
+
+## Example
+
+```bash
+# Capture a 30-second CPU flamegraph from a running Python service
+py-spy record -o profile.svg --duration 30 --pid "$(pgrep -f my-service)"
+
+# Identify top 3 hot functions
+py-spy top --pid "$(pgrep -f my-service)"
+```
+
+Then, per the optimization hierarchy, start with DB/IO fixes (indexing, batching, caching the right layer) before touching algorithm-level changes.
+
+## Rules
+
+- **MUST** capture a baseline measurement before proposing any change
+- **NEVER** optimize code without profiler data pointing at it as the bottleneck
+- **CRITICAL**: report p95/p99, not just p50 — averages hide real user pain
+- **MANDATORY**: follow the hierarchy — DB/IO before algorithm before micro-optimization
+
+## Gotchas
+
+- `py-spy` needs `CAP_SYS_PTRACE` on Linux and SIP-disabled codesigning on macOS to attach to another process. Containerized services usually run without ptrace privileges — profiling requires a `--cap-add=SYS_PTRACE` on the container or an in-process alternative (`cProfile`, `yappi`).
+- Production hosts frequently set `/proc/sys/kernel/perf_event_paranoid=2` or higher, which disables user-space perf events. Tools that rely on perf (`perf`, `bcc`, `bpftrace`) silently produce empty output — check `cat /proc/sys/kernel/perf_event_paranoid` first.
+- Node.js `--prof` output gets interleaved across worker threads and child processes. A single `isolate-*.log` mixes samples from multiple isolates unless each worker writes its own — filter by PID or use `clinic flame` which handles the split.
+- Chrome DevTools samples at ~1kHz; operations faster than ~1ms vanish. For microbenchmarks, prefer `performance.now()` with manual markers, not the Performance tab.
+- `EXPLAIN ANALYZE` on Postgres **executes** the query, including `INSERT`/`UPDATE`/`DELETE` — wrap write queries in a transaction that you roll back, or use `EXPLAIN (ANALYZE, BUFFERS) ... ; ROLLBACK;` in one statement.
+
+## When NOT to Use
+
+- For correctness bugs (wrong output) — use `/debug`
+- For frontend render bugs without timing data — measure with DevTools first
+- For infrastructure capacity planning — use load testing, not profiling
+- For generic code quality — use `/analyze`

package/app/skills/persona/SKILL.md

@@ -51,7 +51,24 @@ Unlike `--persona` at install time (which injects into CLAUDE.md permanently), `
 
 ## Rules
 
-- This skill is READ-ONLY — it never writes files
-- Persona stays active for the current session only
-- Only one persona active at a time — switching replaces the previous one
-- Valid personas are defined by `.md` files in `app/personas/`
+- **MUST** remain read-only — this skill never writes files, only loads persona content into the session
+- **MUST** state the active persona explicitly at switch time so the user knows which lens is in effect
+- **NEVER** keep the previous persona active after a switch — replace, do not stack
+- **NEVER** mix personas in a single response — each persona has internally consistent priorities that clash if blended
+- **CRITICAL**: personas apply for the **current session only**. `/persona --clear` resets; a new session starts from default.
+- **MANDATORY**: valid personas are defined by `.md` files in `app/personas/` — do not invent or describe a persona that has no file
+
+## Gotchas
+
+- The persona file lives in `app/personas/<name>.md` relative to the toolkit root. When the toolkit is globally installed, that root is at `~/.claude/skills/persona/../../../app/personas/` — fallback paths matter.
+- Switching personas mid-task can produce a jarring tone shift in the user's output. Announce the switch, briefly restate the current task in the new persona, then continue.
+- `/persona --clear` only resets the **in-session** persona. If the user ran `ai-toolkit install --persona <name>` at install time, that persona is injected into CLAUDE.md and survives session clears. Clearing requires editing CLAUDE.md directly.
+- Personas are **style overlays**, not skill enablers. Activating `devops-eng` does not give access to `/deploy` if it was not already installed; it only biases which skills the agent reaches for first.
+- A persona that contradicts project-level CLAUDE.md rules (e.g. `junior-dev` asking for explanations in a project that says "no pleasantries") creates a tone conflict. Project rules win; adjust the persona or the project rules, not both silently.
+
+## When NOT to Use
+
+- For **permanent** persona injection at install time — use `ai-toolkit install --persona <name>` (project or global)
+- For multi-agent parallel work with different specialists — use `/orchestrate` or `/teams`
+- For a specific language or framework context (not a general engineering stance) — use the language-pattern skills (`/typescript-patterns`, etc.)
+- To edit or create a persona file — edit `app/personas/<name>.md` directly; this skill only switches between existing ones

package/app/skills/plan/SKILL.md

@@ -52,3 +52,29 @@ hybrid_search_kb("architecture {pattern}")
 - Need requirements first? -> `/write-a-prd` for structured product requirements
 - Want to stress-test the plan? -> `/grill-me` for Socratic questioning
 - Ready to break into issues? -> `/prd-to-plan` -> `/triage-issue`
+
+## Rules
+
+- **MUST** break work into phases where each phase is independently shippable (tracer-bullet discipline) — waterfall phases defer all risk to the end
+- **MUST** define measurable success criteria per phase before proposing tasks — "the user is happy" is not a criterion
+- **NEVER** write code in this skill — the output is a plan document, not a patch
+- **NEVER** invent an agent; every task lists a real agent from `app/agents/` or a real skill from `app/skills/` with a reason for the choice
+- **CRITICAL**: every phase has an explicit rollback or scope-cut option. A plan with no way to stop mid-project is a sunk-cost trap.
+- **MANDATORY**: dependencies between phases are explicit edges (`Phase 1 → Phase 2`). Circular dependencies are always a planning bug, not a valid state.
+
+## Gotchas
+
+- "SMART" tasks are often too small to be strategic and too vague to be tactical. Tasks at the plan level should be phase-aligned outcomes ("authentication ships behind a feature flag"), not implementation steps ("add JWT middleware").
+- Agent assignment drifts during execution — the agent named in the plan may be unavailable or wrong when the work starts. Document the **role** (`backend-specialist`) alongside the assigned agent, so a substitute is unambiguous.
+- Plans that start with a Research phase often consume 80% of the timeline without producing shippable output. If research is truly needed, cap it with a timebox and a concrete artifact (ADR, spike doc).
+- Dependency graphs with diamond patterns (A→B, A→C, B→D, C→D) silently serialize D. If parallel phases feel slow, check for an unintended diamond.
+- Success criteria based on code metrics (coverage, lint count) incentivize gaming them. Prefer user-facing criteria (p95 latency, first-time-success rate on the happy path).
+
+## When NOT to Use
+
+- For writing a **PRD** (product requirements) first — use `/write-a-prd`
+- For breaking a PRD into phases — use `/prd-to-plan`
+- For filing issues against a plan — use `/prd-to-issues`
+- For stress-testing an existing plan — use `/grill-me`
+- For executing a plan with agents — use `/orchestrate` or `/workflow`
+- For a refactor with incremental commits — use `/refactor-plan`

package/app/skills/plan-writing/SKILL.md

@@ -200,3 +200,29 @@ Before finalizing plan:
 - [ ] Agents assigned
 - [ ] Risks documented
 - [ ] Success criteria defined
+
+## Rules
+
+- **MUST** include a Success Criteria section with measurable, verifiable conditions — subjective criteria are not criteria
+- **MUST** include a Rollback Plan for any work that touches production data or shared infrastructure
+- **MUST** write a Pre-Mortem when estimated effort exceeds 1 day — "what could go wrong" surfaces real risks cheaply
+- **NEVER** estimate in hours for work longer than a week. Use T-shirt sizes (S/M/L/XL) or tracer-bullet slices — precise long-horizon estimates are false confidence
+- **CRITICAL**: every risk has an owner AND a mitigation. A risk register with named risks but no mitigations is decorative.
+- **MANDATORY**: explicit scope boundaries — "not in this plan" is as important as "in this plan"
+
+## Gotchas
+
+- SMART criteria look complete but often omit the "relevant" dimension — a task can be Specific, Measurable, Achievable, Time-bound and still irrelevant to the outcome. Check relevance explicitly.
+- Pre-mortems feel pessimistic and get shortened under deadline pressure. Make the pre-mortem a first-class section with at least 5 named failure modes — a 2-bullet pre-mortem is theater.
+- Risk registers bloat when stakeholders add low-probability items to be safe. Cap the register at 10 risks ranked by (probability × impact); everything below line 10 is noise.
+- Plans authored by the person who will execute them are biased toward feasibility (they want to do it). Plans authored by someone who won't execute are biased toward ambition (they don't pay the cost). Mix both perspectives.
+- "Success criteria: deploy to production" is the weakest criterion — it measures effort, not outcome. Replace with user-facing or metric-based criteria ("20% reduction in p95 latency sustained for 7 days").
+
+## When NOT to Use
+
+- For **actually generating** a plan with phases and task breakdown — use `/plan`
+- For requirements capture before planning — use `/write-a-prd`
+- For turning a plan into filed issues — use `/prd-to-issues`
+- For stress-testing a plan's assumptions — use `/grill-me`
+- For executing plans with agents — use `/orchestrate` or `/workflow`
+- For a single-step fix that does not warrant a document — skip the plan entirely

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

@@ -60,12 +60,21 @@ app/plugins/<plugin-name>/
 
 ## Authoring Rules
 
-- Keep packs **domain-scoped**, not generic junk drawers
-- Prefer referencing existing toolkit assets before duplicating them
-- Pack manifests must be valid JSON with `name`, `description`, `version`, `domain`, `type`, `status`, and `includes`
-- Optional hooks must be executable and documented in the pack README
-- If the pack introduces policy or hook behavior, document install/opt-in semantics clearly, including supported runtimes (`claude`, `codex`, or `all`) and that the pack is not part of the default install
-- Experimental packs should remain opt-in and must not silently alter default global install behavior
+- **MUST** keep packs domain-scoped — "security-pack", "mobile-pack", not "misc-pack"
+- **MUST** reference existing toolkit assets before duplicating — packs extend, they do not fork
+- **MUST** ship a valid `plugin.json` with `name`, `description`, `version`, `domain`, `type`, `status`, and `includes`
+- **NEVER** have a pack silently alter default global install behavior — experimental packs are **opt-in only**
+- **NEVER** copy an agent or skill file into a pack when referencing the toolkit-level version suffices; duplication creates drift
+- **CRITICAL**: optional hooks bundled in a pack must be executable (`chmod +x`) and documented in the pack README with their install semantics
+- **MANDATORY**: the pack README names supported runtimes (`claude`, `codex`, or `all`) and explains that the pack is not part of the default install
+
+## Gotchas
+
+- Plugin packs are discovered by scanning `app/plugins/*/plugin.json`. A pack with a missing or malformed `plugin.json` is silently ignored — no error surfaces. Check with `ls app/plugins/*/plugin.json` and `jq . app/plugins/*/plugin.json`.
+- The `status: experimental` flag gates visibility in some install paths — marking a pack "stable" before it is audited can make it install by default for every user. Keep `experimental` until the pack has eaten its own dogfood.
+- Packs that include hooks inherit the toolkit's hook merge rules (`_source: "ai-toolkit"`). Hooks without the `_source` tag survive `ai-toolkit update` and can leak into other packs' merge pools.
+- Versions in `plugin.json` are separate from the toolkit version. A pack at v1.2 running inside toolkit v2.11 may still satisfy `requires.ai-toolkit: >=1.0.0` but mean nothing about actual compatibility — test against the current toolkit before tagging.
+- Codex-runtime packs need matching `.agents/rules/` and `.codex/hooks.json` variants; a plugin that only ships Claude assets looks broken under Codex CLI. Declare runtime support explicitly.
 
 ## Validation Checklist
 
@@ -75,3 +84,11 @@ app/plugins/<plugin-name>/
 - [ ] Optional hooks are executable and use `#!/bin/bash`
 - [ ] `scripts/validate.py` passes
 - [ ] Public docs mention the pack only after the manifest and README exist
+
+## When NOT to Use
+
+- For an individual **skill** (slash command or knowledge doc) — use `/skill-creator`
+- For an individual **agent** — use `/agent-creator`
+- For a single **hook** (not a pack) — use `/hook-creator`
+- For an MCP server — use `/mcp-builder`
+- For modifying an existing plugin pack — edit its files directly; this skill is create-only

package/app/skills/pr/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pr
-description: "Create pull requests with pre-flight validation"
+description: "Create a GitHub pull request after running pre-flight checks (lint, typecheck, tests) and generating a structured summary from commit history. Use when the branch is ready to merge — not for drafting work-in-progress."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[title or branch]"
@@ -127,3 +127,26 @@ gh pr edit --add-reviewer username
 # Merge PR
 gh pr merge --squash
 ```
+
+## Rules
+
+- **MUST** run lint + typecheck + tests locally before opening the PR
+- **NEVER** force-push `main` or `master`
+- **NEVER** add `Co-Authored-By: Claude` or other AI attribution to commits
+- **CRITICAL**: PR body must include a Test plan checklist — no exceptions
+- **MANDATORY**: commit messages follow conventional commits (`feat:`, `fix:`, `docs:` etc.)
+
+## Gotchas
+
+- `gh pr merge --squash` **drops** all original commit trailers, including `Co-Authored-By:` lines. If the PR had legitimate co-authors, note them in the squashed commit body or use `--rebase` instead.
+- `gh` defaults to `github.com`; for GitHub Enterprise the host must be set per-repo with `gh auth login --hostname <host>` and `gh repo set-default`. Silent failures on enterprise usually mean the wrong host.
+- Running `gh pr create` without `--body` opens an editor (`$EDITOR` or `vi`) — in non-interactive contexts this hangs indefinitely. Always pass `--body` or `--body-file`.
+- The pre-flight `ruff check .` walks respecting `.gitignore` by default but `mypy src/` does not — if `src/` contains generated code excluded from git, mypy will still scan it and report spurious errors.
+- `git diff main...HEAD` (triple dot) shows commits on HEAD since the merge-base; `git diff main..HEAD` (double dot) shows all differences including main's newer commits. Use triple-dot for PR-scope diffs.
+
+## When NOT to Use
+
+- For creating a commit (without a PR) — use `/commit`
+- For reviewing a PR someone else opened — use `/review`
+- For drafting release notes across many PRs — use `/docs` or a release script
+- When the branch has uncommitted changes — commit first, then open the PR

package/app/skills/prd-to-issues/SKILL.md

@@ -100,9 +100,25 @@ Reference by number from the parent PRD:
 
 ## Rules
 
-- Every issue must be a VERTICAL slice — never horizontal
-- Create in dependency order for real issue number references
-- Do NOT close or modify the parent PRD issue
-- Do NOT ask user to review before creating — file and share URLs
-- Maximize parallelism — independent issues should have no blockers
-- No file paths or line numbers in issue bodies
+- **MUST** slice vertically — every issue cuts through schema, API, UI, tests end-to-end. Horizontal slices (all-schema, then all-API) defer integration risk.
+- **MUST** create issues in dependency order so blockers have real issue numbers to reference
+- **NEVER** close or modify the parent PRD issue — it is the reference anchor for every child issue
+- **NEVER** include file paths, line numbers, or function names in issue bodies — they go stale before the issue is picked up
+- **CRITICAL**: maximize parallelism. Independent issues have zero `Blocked by` entries; if every issue has blockers, the slicing is wrong.
+- **MANDATORY**: every issue lists the user stories it addresses by number from the parent PRD — traceability matters more than brevity
+
+## Gotchas
+
+- `gh issue create` opens `$EDITOR` without `--body` or `--body-file`. In automation, this hangs silently. Always pass the body explicitly.
+- Dependency chains longer than 3 hops (A blocks B blocks C blocks D) almost always mean the slicing is too thin. Collapse the chain into fewer, wider slices.
+- GitHub issue numbers increment globally in the repo. Creating 5 issues with forward references (#124 blocks #125) requires the blocker to land before the blocked — order matters, and a mid-batch failure leaves dangling references.
+- AFK issues (no human interaction) appear attractive but the label is aspirational. Real AFK requires green CI, clear acceptance criteria, and no design ambiguity — misclassifying HITL as AFK creates reopens.
+- User stories referenced by "number from the PRD" drift if the PRD gets edited. Quote the story text inline if it is short, or pin to a PRD anchor (`#issue-42 > User Story 7`) to resist drift.
+
+## When NOT to Use
+
+- For breaking a PRD into a **plan** (phases, no issues yet) — use `/prd-to-plan`
+- For writing the PRD itself — use `/write-a-prd`
+- For filing a single bug — use `/qa-session` or `/triage-issue`
+- For a plan that exists but has no PRD — use `/plan` then revisit this skill
+- For triaging existing issues (not creating new ones) — this skill is create-only

package/app/skills/prd-to-plan/SKILL.md

@@ -114,7 +114,25 @@ Concise description of this vertical slice. End-to-end behavior, not layer-by-la
 
 ## Rules
 
-- Every phase must be a VERTICAL slice (all layers), never HORIZONTAL (one layer)
-- No file paths or implementation details that couple to current code
-- Each phase must be independently demoable
-- Get user approval before writing the plan file
+- **MUST** slice vertically — every phase cuts through all layers (schema, API, UI, tests). Horizontal layer-by-layer phases defer integration risk to the end.
+- **MUST** identify Architectural Decisions **before** slicing — decisions that apply across phases live in their own section, not repeated in each phase
+- **NEVER** embed file paths, function names, or implementation details that couple the plan to current code — the plan outlives the code it describes
+- **NEVER** write the plan file before the user approves the slicing — drafts burn tokens and invite scope drift
+- **CRITICAL**: each phase is independently demoable on its own. If phase N only makes sense in combination with phase N+1, merge them.
+- **MANDATORY**: the first phase ships **end-to-end** (however thin). Deferring any layer to a later phase defeats tracer-bullet discipline.
+
+## Gotchas
+
+- Architectural Decisions feel like premature commitment — "we can decide routes later". In practice, every phase needs a route to hit, so postponing them creates conflicting guesses across phases. Decide once, apply everywhere.
+- PRDs with long lists of user stories tempt the planner to make each story a phase. User stories are requirements, not phases — group several stories into one vertical slice when they share architecture.
+- "Demoable" means an external stakeholder can watch the feature work, not that a unit test passes. If a phase only ships backend API with no UI to exercise it, it is not demoable.
+- Fetching the PRD with `gh issue view <n>` captures the body but not the comments. Crucial clarifications often live in the comments — include `--comments` or remind the user to paste important threads.
+- Plans written against a moving PRD (the PRD is still being edited) invalidate on every edit. Freeze the PRD snapshot at plan-write time, reference the snapshot commit or comment ID.
+
+## When NOT to Use
+
+- For filing GitHub issues from a plan — use `/prd-to-issues`
+- For writing the PRD itself — use `/write-a-prd`
+- For planning without a PRD — use `/plan` (general-purpose)
+- For stress-testing a plan that already exists — use `/grill-me`
+- For refactor planning — use `/refactor-plan` (incremental commits, not tracer bullets)

package/app/skills/predict/SKILL.md

@@ -76,3 +76,28 @@ Output a markdown report:
 - [ ] Review [high-dependent file] with extra scrutiny
 - [ ] Run integration tests covering [affected area]
 ```
+
+## Rules
+
+- **MUST** base risk scores on measurable signals (dependent count, coverage, diff size) — not vibes or adjective scales
+- **MUST** name at least one specific action per high-risk file — "review carefully" is not an action
+- **NEVER** predict regressions beyond what the signals justify. A single file with 20 dependents is a signal; a generic "this might break things" is noise.
+- **NEVER** skip the test-coverage factor — a high-dependent file with 100% coverage is lower risk than a low-dependent file with none
+- **CRITICAL**: the report ranks files by weighted risk score, not alphabetically. Readers will stop after the first 5 entries.
+- **MANDATORY**: state the confidence level explicitly. Predictions from a 5-line diff are HIGH confidence; predictions from 500-line refactors are LOW.
+
+## Gotchas
+
+- `grep -rl "import.*from.*[target]"` is easily fooled by comments and string literals. Use the language's real AST tools (`ts-morph`, `ast-grep`, `pyflakes`) for accurate dependency graphs on anything beyond trivial diffs.
+- Dynamic imports (`importlib.import_module`, `require(variable)`, JavaScript `await import()`) are invisible to grep. Flag explicitly when the target uses them.
+- Test coverage reported by CI may exclude generated code, migrations, and `__init__.py`. "Has dedicated test = score 1" assumes a real assertion exists — check the test file rather than just the path match.
+- A 5-line diff in a "core" file is often more dangerous than a 500-line diff in a leaf file. The `change_surface` weight alone is misleading; combine with `shared/core` weight for meaningful signals.
+- Predictions about regressions are calibrated against the current test suite, not unknown production behaviors. A "low-risk" verdict means "tests likely pass", not "users will not notice".
+
+## When NOT to Use
+
+- For **executing** a change after prediction — use `/fix`, `/refactor`, or the relevant skill
+- For PR review of logic quality — use `/review`
+- For CI pipeline risk analysis — use `/ci-cd-patterns`
+- For code quality metrics (complexity, duplication) — use `/analyze`
+- For a brand-new codebase with no change history — this skill needs dependents to measure; use `/explore` first

package/app/skills/qa-session/SKILL.md

@@ -101,10 +101,26 @@ After filing, share URLs and ask: "Next issue, or are we done?"
 
 ## Rules
 
-- **No file paths or line numbers** in issues — they go stale
-- **Use project domain language** (check UBIQUITOUS_LANGUAGE.md)
-- **Describe behaviors, not code** — "sync service fails to apply patch" not "applyPatch() throws"
-- **Reproduction steps mandatory** — ask if you can't determine them
-- **Keep concise** — developer should read issue in 30 seconds
-- **Maximize parallelism** — independent issues have no blockers
-- **Create in dependency order** — blockers first for real issue numbers
+- **MUST** use the project's domain language from `UBIQUITOUS_LANGUAGE.md` — framework jargon in issues excludes non-engineering stakeholders
+- **MUST** describe behaviors, not code — "sync service fails to apply patch" not "applyPatch() throws"
+- **MUST** include reproduction steps — if they are not clear, ask the user rather than guess
+- **NEVER** include file paths, line numbers, or function names in issue bodies — they go stale before triage
+- **NEVER** over-interview. Cap clarifying questions at 2-3 per bug; more than that is signal the bug needs a QA session with a product owner, not more questions.
+- **CRITICAL**: the developer who picks up the issue should understand it in 30 seconds. Wall-of-text reports get reopened for clarification.
+- **MANDATORY**: when breaking one report into multiple issues, file them in dependency order so blockers have real issue numbers to reference
+
+## Gotchas
+
+- Domain language in `UBIQUITOUS_LANGUAGE.md` may be out of date. If it was last updated months ago and new features have shipped, the glossary is an input hint, not a source of truth — confirm terms with the user when unsure.
+- "Intermittent" reports are often environmental (one user's browser, one region's data) rather than truly random. Always ask for "how often" and "when did it start" before labeling as race condition.
+- `gh issue create` opens `$EDITOR` without `--body`. In automation this hangs — always pass the body file or inline body.
+- Users often describe the **workaround** as if it were the bug ("I have to refresh the page"). Drill to the underlying behavior — "what fails before the refresh?" — otherwise the fix targets the symptom.
+- Independent sub-issues from one bug report can duplicate work if each gets a different developer. Mention the parent QA session in every sub-issue so reviewers notice the pattern.
+
+## When NOT to Use
+
+- For triaging a **single** known bug with a proposed fix — use `/triage-issue`
+- For creating issues from a PRD — use `/prd-to-issues`
+- For debugging a reproducible error — use `/debug`
+- For code review of a PR that addresses a bug — use `/review`
+- For architecture-level problems — use `/architecture-audit`, not bug reports

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

@@ -202,3 +202,29 @@ docker exec {api-container} python3 scripts/evaluate_rag.py
 # Detect gaps
 docker exec {api-container} python3 scripts/knowledge_gaps.py --detect
 ```
+
+## Rules
+
+- **MUST** chunk by document structure (headers, lists, code fences), not by fixed byte/token count — structure-aware chunking recovers 20-40% of retrieval quality on technical docs
+- **MUST** always use **hybrid search** (BM25 + vector) for keyword-heavy queries — pure vector search misses exact identifiers (function names, config keys)
+- **NEVER** trust a single embedding model on multilingual corpora; pair with a bilingual model or translate queries at the edge
+- **NEVER** index without content-hash change detection — full rebuilds on every change waste embedding budget and corrupt orphan tracking
+- **CRITICAL**: every response includes verifiable citations (source path + exact chunk). A RAG answer without traceable sources is a hallucination wearing a badge.
+- **MANDATORY**: evaluate with a golden dataset (faithfulness, relevancy, context precision) before promoting any pipeline change to production
+
+## Gotchas
+
+- Top-k cosine similarity is **not** relevance — semantically close chunks may be topically wrong. Always compare hybrid vs pure-vector scores on a held-out set before committing to one.
+- Default embedding models (e.g., `text-embedding-ada-002`) underperform on long technical docs (>8k tokens). For long-form content consider chunking before embedding, not embedding then slicing.
+- Chunk overlap (10-20%) helps narrative text but duplicates storage and token cost. Code and structured tables do not benefit from overlap — disable per content type.
+- Cross-encoder rerankers (e.g., `bge-reranker`) add 100-300ms per query. For real-time UX, rerank only the top-20 candidates, not the top-100.
+- RAG failure modes are structural (retrieval, routing, chunking), not prompt-level. Before "tuning the prompt", check retrieval metrics — a prompt fix on top of broken retrieval is theater.
+- Query rewriting (HyDE, hypothetical doc generation) improves some queries and degrades others. A/B test before enabling globally; a blanket "always rewrite" often regresses simple lookups.
+
+## When NOT to Load
+
+- For **executing** a reindex — use `/index` (task skill)
+- For measuring RAG quality — use `/evaluate` (task skill)
+- For chunking documentation strategy without an index — this skill assumes you already have a vector store; use `/architecture-decision` for pipeline choice
+- For MCP-specific retrieval via `smart_query()` — the tool is already built; reach for this skill only when tuning the underlying index
+- For prompt engineering alone without retrieval concerns — use `/prompt-caching-patterns` or the relevant language skill

package/app/skills/refactor/SKILL.md

@@ -138,3 +138,29 @@ Teammate 1 completes first, then Teammate 2 acts on the plan.
 - Want to validate architecture? → `/analyze` for code quality metrics
 - Need tests before refactoring? → `/tdd` to build safety net first
 - Architecture decision needed? → `/council` for multi-perspective evaluation
+
+## Rules
+
+- **MUST** run the full test suite before starting — a green baseline is the only way to tell the refactor did not break anything
+- **MUST** preserve behavior end-to-end; if behavior must change, stop and ask — "while we're here" changes are how refactors introduce bugs
+- **NEVER** mix refactoring with feature changes in the same commit — they fail review and rollback differently
+- **NEVER** refactor untested code without adding tests first — the refactor has nothing to assert against
+- **CRITICAL**: commits stay small and individually reversible. A 2000-line refactor commit cannot be code-reviewed and cannot be bisected.
+- **MANDATORY**: dead-code cleanup is part of the refactor per Constitution Art. VI.1 — orphaned references left behind from a refactor are a quality regression, not "later work"
+
+## Gotchas
+
+- "Behavior-preserving" refactors still change **observable** things: timing, memory allocation, error message text, log line format. Downstream consumers may rely on these — scan for log parsers or monitoring rules before changing prose in exceptions.
+- IDE rename refactors miss dynamic references (string-keyed dicts, reflection, `getattr`, dynamic imports). After a rename, grep for the old name in strings and comments — the IDE will not.
+- Git history diffing is confused by combined move + content changes. Split moves into their own commit (`git mv` + tiny commit) so later reviewers can use `git log --follow`.
+- Preserving backward compatibility is a spectrum. "Keep the old function as a thin wrapper" sounds safe but often defers the cleanup forever — prefer deprecate-with-warning followed by a scheduled removal.
+- Refactor-to-DRY abstractions made from 2 use cases often need to be torn down when the 3rd use case arrives (Rule of Three). Resist abstracting until the third repetition makes the shape obvious.
+- Test suites that rely on mocks frequently pass during refactors that silently break real behavior (the mock reflects the old shape). Run integration tests, not just unit, before marking done.
+
+## When NOT to Use
+
+- For **planning** a refactor (no execution) — use `/refactor-plan`
+- For architectural audit of shallow modules — use `/architecture-audit`
+- For fixing a specific bug — use `/fix` or `/debug`
+- For adding a feature — use `/plan` then the relevant language skill
+- When tests do not exist or are red — write tests first (`/tdd`) before refactoring

package/app/skills/refactor-plan/SKILL.md

@@ -105,9 +105,26 @@ What is explicitly NOT part of this refactor.
 
 ## Rules
 
-- Present >=3 alternatives before committing to an approach
-- Tiny commits — each step keeps codebase working
-- No file paths or code snippets in the issue (durability)
-- File immediately via `gh issue create` — don't ask for review
-- Interview thoroughly before planning
-- **Dead code cleanup is mandatory per step, not deferred** (Constitution Art. VI.1): every refactor step must leave the repo with zero orphaned references. "We'll delete the old code in a later step" is only acceptable for transitional double-write / expand-contract phases where both paths are temporarily live — and the cleanup step must be explicitly listed in the plan, not implied.
+- **MUST** present >=3 alternative approaches with trade-offs before committing to one
+- **MUST** break the refactor into commits small enough to roll back individually — a commit that cannot be reverted is not tiny
+- **MUST** verify test coverage of the affected area before planning; insufficient coverage is a blocker, not a warning
+- **NEVER** embed file paths, code snippets, or function names in the issue body — the plan outlives the code
+- **NEVER** ask for review after creating the issue — file it immediately, share the URL, iterate in comments
+- **CRITICAL**: dead-code cleanup is **per step**, not deferred (Constitution Art. VI.1). "We'll delete the old code later" is only acceptable during explicit expand-contract phases, and the cleanup step must be in the plan.
+- **MANDATORY**: the Out of Scope section names what is NOT part of this refactor — scope clarity prevents reviewer confusion
+
+## Gotchas
+
+- "Tiny" is relative to the reviewer's context. A 20-line commit that touches the hot path is not tiny in practice — tiny means **tractable**, not short.
+- Tests for refactors are often omitted with "the existing tests cover it". Verify by running the suite with coverage in the affected area, not by asking.
+- Rebasing a long chain of tiny commits is painful when the target branch moves. Recommend landing the chain weekly and rebasing on `main` before each review round.
+- GitHub issue RFCs tend to get stale if the refactor drags. Add a "Status" line that updates with each landed commit so readers see progress without scrolling through comments.
+- Expand-contract refactors with double-writes silently leak cost — both paths are live, both pay resources. Set a hard deadline in the plan for when the old path is removed.
+
+## When NOT to Use
+
+- For **executing** a refactor directly — use `/refactor`
+- For architecture-level audit without a specific refactor in mind — use `/architecture-audit`
+- For creating a PRD (product requirements) — use `/write-a-prd`
+- For a plan without the GitHub RFC step — use `/plan` or `/plan-writing`
+- For interface design of a single module — use `/design-an-interface`