@softspark/ai-toolkit 2.11.0 → 3.0.0

package/app/skills/git-mastery/SKILL.md

@@ -78,3 +78,29 @@ git cherry-pick --continue
 | "One big commit is simpler" | Big commits are impossible to review, bisect, or revert — keep them atomic |
 | "Merge conflicts mean someone else's problem" | Conflicts mean you diverged too long — rebase frequently to stay aligned |
 | "Commit messages don't matter" | Messages are documentation — future you needs to understand why, not just what |
+
+## Rules
+
+- **MUST** use `--force-with-lease` instead of `--force` for any force operation on a shared branch
+- **MUST** create a backup branch before interactive rebase, reset --hard, or filter-repo: `git branch backup/<name>-pre-rebase`
+- **NEVER** force-push to `main`, `master`, or `develop` — these are shared trunk branches by convention
+- **NEVER** rewrite history that has already been pushed AND consumed by others — you will orphan their clones
+- **CRITICAL**: the reflog is a 90-day safety net (`gc.reflogExpire`) — tag anything you want to keep longer. Do not rely on reflog for multi-month recovery.
+- **MANDATORY**: commit messages follow Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`) — drift defeats automated changelog and release tooling
+
+## Gotchas
+
+- `git bisect` relies on each commit being testable. Flaky tests corrupt the bisection silently — a flaky "bad" mark sends `bisect` down the wrong half. Run the test 3× at the boundary commits if flakiness is known.
+- `git cherry-pick <sha>` of a merge commit fails without `--mainline 1` (or 2). The error is cryptic ("commit is a merge but no -m option was given"); the fix is simple but non-obvious.
+- `git reflog` entries expire by default in 90 days (`gc.reflogExpire`) and unreferenced commits get garbage-collected after 30 days (`gc.reflogExpireUnreachable`). Long-term recovery of "lost" commits from reflog is not guaranteed.
+- `git rebase -i --root` is supposed to include the very first commit, but on **shallow clones** (`--depth N`) the "root" is the shallow boundary, not the actual initial commit. Run `git fetch --unshallow` before rebasing --root.
+- `git filter-branch` is **deprecated** and slow (shell-based, re-forks per commit). Use `git filter-repo` for history rewriting — it is a separate tool (`pip install git-filter-repo`) but 100× faster and endorsed by the Git maintainers.
+- `git pull --rebase` on a branch with unpushed merge commits rewrites those merges into linear history, silently losing the merge metadata. If a merge was intentional (e.g., to preserve feature-branch context), use `git pull --no-rebase` or set `pull.ff=only` globally.
+
+## When NOT to Load
+
+- For simple commits on a ready branch — use `/commit`
+- For opening a PR after commits are clean — use `/pr`
+- For a specific failed operation needing root-cause analysis — use `/debug` on the git output
+- For CI-specific git behavior (shallow clones, LFS on runners) — use `/ci-cd-patterns`
+- For the in-repo `.git/hooks/*` content — this skill is user-facing Git; hook mechanics live in `/hook-creator` and `install_git_hooks.py`

package/app/skills/grill-me/SKILL.md

@@ -29,10 +29,25 @@ Interview relentlessly about every aspect of the plan until reaching shared unde
 
 ## Rules
 
-- Ask questions **one at a time**
-- For each question, provide your **recommended answer**
-- If a question can be answered by **exploring the codebase**, explore instead of asking
-- Resolve dependencies between decisions — don't skip ahead
-- Be relentless — don't settle for vague or hand-wavy answers
-- Challenge assumptions, not just surface decisions
-- Apply Devil's Advocate critique to every major decision
+- **MUST** ask questions one at a time — batching defeats the Socratic process
+- **MUST** provide a recommended answer with every question so the user can accept, refine, or reject
+- **NEVER** settle for vague or hand-wavy answers — press for specifics ("what does 'scale' mean here — 10k req/s or 10M?")
+- **NEVER** skip ahead before the current branch is resolved — dependencies between decisions matter
+- **CRITICAL**: if a question can be answered by **exploring the codebase**, explore instead of asking. Do not outsource verifiable facts to the user.
+- **MANDATORY**: apply Devil's Advocate critique to every major decision — the default answer ("let's ship it") is almost always the one that needs challenging
+
+## Gotchas
+
+- Grilling can feel adversarial. Frame questions as "what if X happens" not "your plan is wrong because X" — the goal is shared understanding, not winning.
+- Fatigue kicks in around 10 questions deep. For larger plans, pause and summarize every ~7 questions so the user can reorient before continuing.
+- Some disagreements cannot be resolved by argument — they need data. If a question loops (user defends A, grill defends B, repeat), recommend a spike or experiment instead of more questions.
+- The user's "final answer" after heavy grilling may be reluctant compliance, not genuine agreement. Watch for hedging language ("I guess", "sure, fine") and probe once more.
+- Grilling a plan that is already detailed and well-vetted produces diminishing returns and annoyance. Know when to stop — exit condition is "shared understanding", not "exhaustive coverage".
+
+## When NOT to Use
+
+- For **implementation** — use `/plan`, `/refactor-plan`, or `/prd-to-plan`
+- For code review after the code is written — use `/review`
+- For architecture decisions with 2-3 named options — use `/architecture-decision` (structured trade-off) rather than open-ended grilling
+- When the plan is crystal-clear and the user just needs a sanity check — grilling overkills trivial decisions
+- In a production incident — use `/workflow incident-response`, speed beats thoroughness there

package/app/skills/health/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: health
-description: "Report service and infrastructure health status"
+description: "Report service and infrastructure health status via liveness/readiness checks, resource usage, and quick diagnostics. Use when the user asks whether services are up or degraded — not for deep debugging of a known error."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[service]"
@@ -89,3 +89,24 @@ services:
     memory: XMB
     notes: "any issues"
 ```
+
+## Rules
+
+- **MUST** report measured values — never mark a service healthy without a successful probe
+- **NEVER** restart a degraded service without the user's explicit go-ahead
+- **CRITICAL**: separate liveness (process up) from readiness (accepting traffic) in the report
+- **MANDATORY**: if a health endpoint times out, classify as `degraded`, not `healthy`
+
+## Gotchas
+
+- `docker compose ps` shows `Up` even when a container is **crash-looping** via restart policy — look at the `STATUS` column for `(unhealthy)` or `Restarting` rather than trusting "Up" alone.
+- Many `/health` endpoints return 200 as long as the web server answers, even when the DB connection is down. If the service exposes a `/ready` or `/healthz?deep=true` endpoint, prefer it — shallow health is a lie.
+- `pg_isready` reports success the moment Postgres accepts TCP, which happens seconds before the DB is actually query-ready after a restart. Chain it with a trivial `SELECT 1`.
+- `docker stats --no-stream` needs cgroups v2 access; on older hosts or LXC containers it returns 0% CPU/memory silently instead of erroring. Verify at least one non-zero value before trusting the report.
+
+## When NOT to Use
+
+- To debug a specific failing service — use `/debug` after the health check narrows it down
+- For performance bottlenecks — use `/performance-profiling`
+- For a production incident with page/alert — use `/workflow incident-response`
+- For CI pipeline status — use `/ci`

package/app/skills/hipaa-validate/SKILL.md

@@ -346,14 +346,31 @@ This distinction helps compliance officers prioritize immediate remediation (def
 
 ## Rules
 
-- **Read-only**: Never modify any files. Report findings only.
-- **HIPAA rule citation**: Every finding must reference a specific HIPAA section (§ number).
-- **Skip non-source files**: Binary files, lock files (`*.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`), vendored directories (`node_modules/`, `vendor/`, `.git/`, `dist/`, `build/`, `out/`, `.next/`).
-- **Respect `.hipaaignore`**: Honor exclusion patterns in the project's `.hipaaignore` file.
-- **No false confidence**: Clearly label heuristic findings as `POTENTIAL` and mark confidence as `heuristic`.
-- **Context before identifiers**: Always run the healthcare keyword context gate before applying PHI identifier regex patterns (Category 4) to avoid false positives.
-- **Warn on missing secrets management**: Flag PHI-adjacent config files without `.env` or secret manager references.
-- **No auto-fix in v1**: Auto-fixing HIPAA issues requires project-specific knowledge of logging/audit infrastructure. Planned for v2.
+- **MUST** remain read-only — never modify any file. This skill reports findings only.
+- **MUST** cite a specific HIPAA rule section (§ number) for every finding — uncited findings are not actionable
+- **MUST** run the healthcare keyword context gate before applying PHI identifier regex (Category 4) — without it, false-positive rate is ~90%
+- **NEVER** label a heuristic finding as "definitive" — clearly mark `POTENTIAL` and `confidence: heuristic`
+- **NEVER** scan binary files, lock files (`*.lock`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`), or vendored dirs (`node_modules/`, `vendor/`, `.git/`, `dist/`, `build/`, `out/`, `.next/`) — noise and zero signal
+- **CRITICAL**: respect `.hipaaignore` exclusion patterns — teams use it to mark known-safe data fixtures
+- **MANDATORY**: flag PHI-adjacent config files without `.env` or secret-manager references as a WARN category, even when no PHI pattern matches
+- **NEVER** auto-fix in this version. Auto-fixing requires project-specific knowledge of logging and audit infrastructure that regex alone cannot provide.
+
+## Gotchas
+
+- Test fixtures and seed data often contain **synthetic** PHI that looks real (SSN-shaped IDs, formatted phone numbers, sample email addresses). Flag them but lower severity — production code handling the same patterns is the actual risk.
+- HIPAA §164.312(b) requires audit logging but does not specify a format. "Logs exist" is not evidence of compliance — the logs must capture WHO (authenticated user), WHAT (action), WHEN (timestamp), WHERE (resource), and they must be immutable (append-only or write-once storage).
+- Encryption-at-rest varies silently by storage layer. RDS auto-encrypts new volumes since 2017, but older DB snapshots may not be; S3 bucket policies can override instance-level encryption. Treat "encryption enabled" as a claim to verify with the cloud provider, not a state to trust.
+- PHI identifiers 1-18 differ from HIPAA's "limited data set" rules — date of service and city are permitted in a limited dataset but not in full PHI. Do not auto-flag any date as PHI without context; check for surrounding patient-name or diagnosis proximity.
+- PHI detection via regex misses data encoded in BLOBs, base64-embedded JSON, or encrypted-at-application-layer columns. A clean regex scan does not prove absence of PHI — document this explicitly in the report.
+- Healthcare keyword context gate has dialect drift: "patient" in a veterinary codebase is a dog, not a person under HIPAA. Review context before escalating findings from multi-tenant or vertical-adjacent codebases.
+
+## When NOT to Use
+
+- For generic security patterns (XSS, SQLi, CSRF) — use `/security-patterns`
+- For dependency vulnerabilities — use `/cve-scan`
+- For non-healthcare compliance regimes (PCI-DSS, SOC2, GDPR) — this skill is HIPAA-specific
+- For **legal interpretation** of compliance — this skill flags technical controls; only a QSA or attorney interprets compliance status
+- For PII/GDPR outside the HIPAA scope — overlapping but distinct; HIPAA covers PHI specifically
 
 ## Reference Documents
 

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

@@ -1,6 +1,6 @@
 ---
 name: hook-creator
-description: "Creates new Claude Code hooks with guided workflow, strict conventions, and validation"
+description: "Create a new Claude Code lifecycle hook (PreToolUse, PostToolUse, Stop, SessionStart, etc.) with a bash script and hooks.json registration. Use when the user wants automated behavior tied to a specific event — not for one-off commands."
 effort: high
 disable-model-invocation: true
 argument-hint: "[hook event or description]"
@@ -15,19 +15,90 @@ Create a new Claude Code hook following ai-toolkit conventions.
 
 ## Supported Hook Events
 
+### Core lifecycle
+
 | Event | Fires When | Matcher | Typical Use |
 |-------|-----------|---------|-------------|
-| `SessionStart` | Session begins or resumes after compact | `startup\|compact` | Context injection, rules reminder |
+| `SessionStart` | Session begins, resumes, or clears | `startup\|resume\|clear` | Context injection, rules reminder |
+| `SessionEnd` | Session is closing | any | Flush logs, save transcripts |
+| `UserPromptSubmit` | User submits a prompt | any | Prompt governance, usage tracking |
 | `Notification` | Claude sends a notification | any | OS alerts, Slack pings |
-| `PreToolUse` | Before a tool executes | tool name (e.g. `Bash`) | Safety guards, validation |
-| `PostToolUse` | After a tool executes | tool name | Feedback loops, logging |
+
+### Tool lifecycle
+
+| Event | Fires When | Matcher | Typical Use |
+|-------|-----------|---------|-------------|
+| `PreToolUse` | Before a tool executes | tool name (e.g. `Bash`) or `if:` rule | Safety guards, validation, `"defer"` for headless |
+| `PostToolUse` | After a tool executes | tool name | Feedback loops, logging, format-on-save |
+
+### Turn lifecycle
+
+| Event | Fires When | Matcher | Typical Use |
+|-------|-----------|---------|-------------|
 | `Stop` | Claude finishes responding | any | Quality checks, session save |
-| `PreCompact` | Before context compaction | any | Context preservation |
+| `StopFailure` | Turn ends due to an API error (rate limit, auth) | any | Alerting, fallback behavior |
+
+### Subagent lifecycle
+
+| Event | Fires When | Matcher | Typical Use |
+|-------|-----------|---------|-------------|
+| `SubagentStart` | Subagent launches | any | Observability |
 | `SubagentStop` | Subagent completes | any | Result validation |
-| `UserPromptSubmit` | User submits a prompt | any | Prompt governance |
-| `TaskCompleted` | Agent Teams task done | any | Lint, type check |
+
+### Compaction
+
+| Event | Fires When | Matcher | Typical Use |
+|-------|-----------|---------|-------------|
+| `PreCompact` | Before context compaction; can block with exit 2 or `{"decision":"block"}` | any | Context preservation |
+| `PostCompact` | After compaction completes | any | Re-inject state that was summarized away |
+
+### Permissions & elicitation
+
+| Event | Fires When | Matcher | Typical Use |
+|-------|-----------|---------|-------------|
+| `PermissionRequest` | Tool awaiting permission; can return `updatedInput` | any | Headless approval flows |
+| `PermissionDenied` | Auto-mode classifier denied a tool call; return `{retry: true}` to allow retry | any | Coach the model, log denials |
+| `Elicitation` | MCP `elicitation/create` request arrives | any | Intercept / override MCP UI prompts |
+| `ElicitationResult` | Elicitation response ready to be sent back | any | Validate / transform elicitation replies |
+
+### Agent Teams
+
+| Event | Fires When | Matcher | Typical Use |
+|-------|-----------|---------|-------------|
+| `TaskCreated` | New task registered via `TaskCreate` | any | Audit, assignment routing |
+| `TaskCompleted` | Agent Teams task finished | any | Lint, type check, notify |
 | `TeammateIdle` | Agent Teams member idle | any | Completeness reminder |
 
+### Worktrees & environment
+
+| Event | Fires When | Matcher | Typical Use |
+|-------|-----------|---------|-------------|
+| `WorktreeCreate` | Worktree is being created; `type: "http"` can return `hookSpecificOutput.worktreePath` | any | Provision worktree dirs |
+| `WorktreeRemove` | Worktree is being removed | any | Cleanup |
+| `CwdChanged` | Working directory changes during a session | any | Reactive env management (e.g., direnv) |
+| `FileChanged` | Tracked file is modified on disk | any | Re-lint, reload config |
+| `ConfigChange` | Settings / config file changed | any | Re-validate, warn on drift |
+
+### Setup / bootstrap
+
+| Event | Fires When | Matcher | Typical Use |
+|-------|-----------|---------|-------------|
+| `Setup` | First-run / initialization | any | Project bootstrap |
+| `InstructionsLoaded` | CLAUDE.md / AGENTS.md loaded into context | any | Verify presence of mandatory rules |
+
+## Hook Handler Types
+
+Claude Code supports four handler `type` values in `hooks.json`:
+
+| Type | Purpose | Required fields |
+|------|---------|-----------------|
+| `command` | Run a shell script / binary | `command` (path + args) |
+| `prompt` | Inject a prompt to the fast inline model and use its verdict | Handler-managed |
+| `agent` | Spawn a full subagent to evaluate the event (must target `Stop` / `SubagentStop`) | `agent` (agent name) |
+| `mcp_tool` | Invoke an MCP tool directly (no subprocess) | `server`, `tool`, `arguments` |
+
+`command` remains the default and ai-toolkit's hook entries all use it. The other types are documented here so you can author them by hand when needed.
+
 ## Workflow
 
 1. **Capture intent** -- ask: what should the hook do? Which lifecycle event?
@@ -66,8 +137,13 @@ Create a new Claude Code hook following ai-toolkit conventions.
 Required fields:
 - `_source`: always `"ai-toolkit"` (used by merge/strip logic)
 - `matcher`: tool name or regex for Pre/PostToolUse, empty string for global events
-- `hooks[].type`: always `"command"`
-- `hooks[].command`: path to script using `$HOME/.softspark/ai-toolkit/hooks/` prefix
+- `hooks[].type`: `"command"`, `"prompt"`, `"agent"`, or `"mcp_tool"` (ai-toolkit uses `"command"`)
+- `hooks[].command`: path to script using `$HOME/.softspark/ai-toolkit/hooks/` prefix (for `type: command`)
+
+Optional fields (read from Claude Code docs, not emitted by ai-toolkit by default):
+- `hooks[].timeout`: seconds to wait before killing the hook (global default applies if omitted)
+- `hooks[].if`: permission-rule filter (e.g. `"Bash(git push*)"`) to reduce process spawning
+- `hooks[].statusMessage`: short message surfaced in the UI while the hook runs
 
 ## Script Template
 
@@ -89,11 +165,20 @@ exit 0
 
 ## Rules
 
-- One script per hook entry (no inline multi-line commands)
-- Script filename must use kebab-case matching the event purpose
-- Pre* hooks can block operations -- keep them fast and deterministic
-- Never write secrets or credentials to stdout (output goes to LLM context)
-- Test the script standalone before registering: `bash app/hooks/{name}.sh`
+- **MUST** use one script per hook entry — no inline multi-line commands inside `hooks.json`
+- **MUST** keep `Pre*` hooks fast and deterministic — they gate every matching tool call, slow hooks throttle the whole agent
+- **NEVER** write secrets, tokens, or credentials to stdout — hook output is injected into LLM context and can be extracted
+- **NEVER** exit non-zero from a `Post*` or `Stop` hook unless you intend to block further processing; exit 0 is the safe default
+- **CRITICAL**: respect the `TOOLKIT_HOOK_PROFILE` env var. Profile `minimal` must be a no-op for non-essential hooks.
+- **MANDATORY**: test the script standalone (`bash app/hooks/{name}.sh`) before adding it to `hooks.json`
+
+## Gotchas
+
+- `PreToolUse` hooks that exit non-zero **block** the tool call. A slow or flaky hook (network call, lock contention) becomes a DoS against Claude's own workflow. Keep Pre hooks to pure-bash checks of local state.
+- Hook output (stdout) is injected verbatim into the model's context. A hook that runs `git log --all` prints hundreds of lines the model then has to wade through — be surgical, print only what matters.
+- The path in `hooks.json` is resolved relative to the user's machine, not the ai-toolkit repo. Use `$HOME/.softspark/ai-toolkit/hooks/<name>.sh` as the canonical location (installer symlinks there).
+- `SessionStart` with matcher `startup|compact` fires on both fresh starts AND after context compaction. Hooks that assume "new session" will mis-fire after compaction — check for explicit context markers if the distinction matters.
+- Bash hooks on Windows (without WSL) will not run. If the hook must work cross-platform, wrap it in a Node or Python script and call from the bash stub — or flag the hook as `posix-only` in the description.
 
 ## Validation Checklist
 
@@ -105,3 +190,11 @@ After creating the hook:
 - [ ] `scripts/validate.py` passes
 - [ ] Script runs without errors: `bash app/hooks/{name}.sh`
 - [ ] Hook count in README.md and docs updated if needed
+
+## When NOT to Use
+
+- For a **skill** (slash command) — use `/skill-creator`
+- For an **agent** definition — use `/agent-creator`
+- For a git pre-commit hook (not a Claude Code hook) — use `/git-mastery` or `scripts/install_git_hooks.py`
+- For one-off automation that is not tied to a Claude Code event — use a plain shell script outside the toolkit
+- To modify an existing toolkit hook — edit the file directly; this skill is create-only

package/app/skills/index/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: index
-description: "Index codebase into the knowledge base"
+description: "Reindex the knowledge base for semantic search via the configured vector store (e.g., Qdrant). Use only when the user explicitly asks to reindex — never trigger speculative rebuilds."
 effort: low
 disable-model-invocation: true
 argument-hint: "[path or scope]"
@@ -72,3 +72,24 @@ last_updated: "YYYY-MM-DD"
 | Missing documents | Verify frontmatter is valid |
 | Slow indexing | Check embedding service performance |
 | No vector store | Set up Qdrant or compatible vector DB |
+
+## Rules
+
+- **MUST** require explicit user permission before running `make index` or `make index-full` — never self-trigger
+- **NEVER** trigger a full rebuild to "clean up" unless the user asked for it
+- **CRITICAL**: validate KB frontmatter before indexing — abort on invalid documents rather than indexing a broken state
+- **MANDATORY**: respect change-detection hashes; do not force reindexing of unchanged documents
+
+## Gotchas
+
+- Content-hash change detection keys on the file's content AND path. A **moved** document (same content, new path) looks new to the indexer — both the old path vector and the new one will exist until a full rebuild. Plan a full rebuild after mass reorganizations.
+- Deleting a document on disk does not automatically remove its vectors from Qdrant; the indexer emits tombstones only if run with a directory scan. Without `--delete-missing`, orphan vectors stay for weeks.
+- Embedding providers rate-limit by requests-per-minute AND by tokens-per-minute. A reindex of 1000+ docs hits the token cap first and stalls silently — watch for 429s in the indexer log before concluding "slow indexing".
+- `make index-full` truncates the collection before re-embedding; if the embedding job crashes mid-way, the collection is left partially populated with no query-time indicator of the gap.
+
+## When NOT to Use
+
+- For searching the KB — use `/search` or call `smart_query()` via the rag-mcp tool
+- For fixing indexing bugs — use `/debug` on the indexer pipeline
+- To evaluate RAG quality after reindexing — use `/evaluate`
+- When no vector store is configured — document the gap, do not invent one

package/app/skills/instinct-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: instinct-review
-description: "Review and manage learned instincts from past sessions"
+description: "Review, promote, or remove learned instincts extracted from past sessions (`.claude/instincts/*.md`). Use when the user wants to curate the instinct list — not to extract new instincts or edit memory."
 effort: low
 user-invocable: true
 argument-hint: "[--list | --promote <id> | --remove <id> | --clear]"
@@ -75,3 +75,27 @@ Last seen: 2026-03-25
    - `--clear`: delete all files in `.claude/instincts/`
    - no args: interactive review of each instinct
 4. Report summary of changes made
+
+## Rules
+
+- **MUST** list instincts with their source (session ID or date) so the user can judge provenance — anonymous instincts cannot be curated
+- **MUST** confirm before `--clear` — this action is irreversible without a backup
+- **NEVER** invent or edit instinct content — this skill curates existing files, it does not generate new ones
+- **NEVER** promote an instinct with confidence < 0.7 without explicit user approval — low-confidence patterns are often one-off noise
+- **CRITICAL**: the user owns the instinct list. Propose changes in interactive mode; apply silently only for explicit `--promote`, `--remove`, `--clear` flags.
+- **MANDATORY**: after any destructive operation, print the deleted or modified filenames so the user has an audit trail
+
+## Gotchas
+
+- Instincts live in **project-local** `.claude/instincts/`, not in `~/.softspark/ai-toolkit/`. Running this skill in a different project sees a different set — do not treat the list as global state.
+- The Stop hook that extracts instincts may write draft files even when no meaningful pattern was observed. A `.claude/instincts/` with 40 files is usually 35 noise + 5 signal — curate ruthlessly.
+- Promoted instincts (confidence = 1.0) load into every session's context, costing tokens. Too many pinned instincts bloat startup. Keep ≤10 pinned.
+- Instinct files are plain markdown but the extraction format may evolve between ai-toolkit versions. A `--clear` after a version bump is often cleaner than trying to migrate old formats.
+- The filename (`<pattern-name>.md`) is the identity used by `--promote` and `--remove`. Renaming files manually breaks those flags until the user reopens the review UI.
+
+## When NOT to Use
+
+- To **extract** new instincts — extraction is automatic via the Stop hook
+- To search past session memory — use `/mem-search`
+- To edit global toolkit memory files — those live in `~/.claude/projects/*/memory/` and are managed by the auto-memory system, not this skill
+- To permanently disable the instinct system — edit `settings.json` to remove the Stop hook; `--clear` only wipes current state, extraction continues on the next session

package/app/skills/introspect/SKILL.md

@@ -99,7 +99,24 @@ Output exactly this format:
 
 ---
 
-## Self-Correction Rules
+## Rules
+
+- **MUST** name a specific failure pattern (Loop / Drift / Assumption Error / Tool Misuse / Context Overflow / Wrong Abstraction / Missing Information) — vague self-diagnosis is useless
+- **MUST** ground the diagnosis in concrete evidence (action traces, error messages, tool outputs) — not in feelings or hunches
+- **NEVER** retry the exact same action. If it failed once, it will fail again. Change something.
+- **NEVER** continue a loop "hoping it will work this time". Hope is not a strategy.
+- **CRITICAL**: after 3 failed attempts, escalate to the user with a concrete report of what was tried, what failed, and what you need — do not keep flailing
+- **MANDATORY**: the recovery action is ONE concrete next step, not a multi-phase plan. If you need a plan, use `/plan`.
+
+## Gotchas
+
+- "Introspection" invoked mid-task can itself become a procrastination loop — spending effort diagnosing instead of acting. If the report takes longer to write than the next concrete action, skip the report and just change approach.
+- Context overflow is often invisible from inside the session — the model cannot reliably detect its own forgetting. External signals (user frustration, repeated explanations of the same fact) are the real diagnostic.
+- "Wrong abstraction" is frequently misdiagnosed as "Missing information". If adding data does not unlock the next step but simplifying the code does, the abstraction is the problem.
+- Ask-the-user is the escape hatch but it has a cost: user context-switching, latency, fatigue. Use it when you truly cannot proceed, not as a habit to avoid commitment.
+- The "fresh start" thought experiment works best when written down. Articulating "if starting over, my first action would be X" out loud often reveals the current approach's sunk-cost fallacy.
+
+## Self-Correction Checklist
 
 These rules are non-negotiable during recovery:
 
@@ -111,6 +128,14 @@ These rules are non-negotiable during recovery:
 6. **Check if the goal is still correct** before optimizing the approach. Sometimes the task itself needs clarification.
 7. **If stuck for more than 3 attempts, escalate.** Tell the user what you tried, what failed, and what you need.
 
+## When NOT to Use
+
+- For debugging user code (not agent self-debugging) — use `/debug`
+- For analyzing past sessions to find patterns — use `/mem-search` or `/instinct-review`
+- For writing a recovery **plan** that spans multiple steps — use `/plan`
+- When the user has already described the failure — respond directly, skip the structured introspection
+- As a procrastination mechanism — if the next action is obvious, take it instead of writing a report
+
 ---
 
 ## Quick Self-Check (Use Before Retrying Anything)

package/app/skills/lint/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lint
-description: "Lint code with auto-detected tools and fix suggestions"
+description: "Run the project's linter and type-checker with auto-detected toolchain (ruff/mypy, eslint/tsc, phpstan, golangci-lint, clippy, dart analyze). Use when the user asks for static-analysis feedback — not to run tests or refactor."
 effort: low
 disable-model-invocation: true
 argument-hint: "[path]"
@@ -101,3 +101,29 @@ docker exec {container} make typecheck
 | Unused imports | Remove or use `# noqa: F401` |
 | Line too long | Break line or disable for that line |
 | Import order | Let linter fix with `--fix` |
+
+## Rules
+
+- **MUST** auto-detect the linter from project config (`pyproject.toml`, `package.json`, `.eslintrc.*`, `composer.json`, `go.mod`, `Cargo.toml`, `pubspec.yaml`) — do not assume
+- **MUST** show the diff before applying any `--fix` run; the user owns the decision to accept auto-fixes
+- **NEVER** suppress lint errors with blanket `# noqa` or `eslint-disable-next-line` without naming the specific rule and a reason
+- **NEVER** run the formatter (ruff format, prettier, dprint) inside a lint pass unless the project has that wired explicitly — formatting and linting are separate concerns
+- **CRITICAL**: report the error count **before and after** any auto-fix — delta visibility is what makes the run trustworthy
+- **MANDATORY**: respect the project's lint config (`.ruff.toml`, `eslint.config.js`, `phpstan.neon`) — overriding project rules on the fly produces arguments during code review
+
+## Gotchas
+
+- `ruff check .` and `ruff format .` are **separate** commands in modern ruff (>0.1.0). Running only `ruff check` misses formatting drift; some repos expect both as part of "lint".
+- `mypy` without `--strict` has a permissive default: missing annotations count as `Any`, so the type checker silently accepts untyped functions. Check whether the project pins `strict = true` in `pyproject.toml` before declaring "0 type errors".
+- `eslint` follows `eslint.config.js` (flat config, ESLint 9+) OR `.eslintrc.*` (legacy). Mixing produces mysterious "no rules applied" errors. Check ESLint version first (`npx eslint --version`).
+- `phpstan` levels (0-10) silently affect which rules apply. A repo at level 5 has different expectations than level 9; report the level alongside the error count.
+- `golangci-lint` composes many linters; disabling one at the project level may still show its warnings if invoked with `--enable-all` flag. Check `.golangci.yml` before treating a warning as a new regression.
+- Dart analyze reports on **all** files including generated `*.g.dart`. Some projects expect generated files to be excluded via `analysis_options.yaml`; without it, lint noise dominates real issues.
+
+## When NOT to Use
+
+- To **fix** the errors — use `/fix` after this skill surfaces them
+- To run tests — use `/test`
+- For code review of logic and design — use `/review`
+- For security-specific static analysis (SAST) — use `/cve-scan` or `/security-patterns`
+- For project-specific rule authoring — edit the linter's config directly

package/app/skills/mcp-builder/SKILL.md

@@ -130,6 +130,33 @@ Claude Desktop: same JSON, placed in `~/Library/Application Support/Claude/claud
 | `exit 1` on transient errors | Retry with exponential backoff, surface final error |
 | Stdout pollution (MCP stdio) | All logs go to **stderr**, stdout is JSON-RPC only |
 
+## Rules
+
+- **MUST** pick 5-15 workflow-oriented tools, not a 1:1 API mirror. The model routes by task, not by endpoint.
+- **MUST** use strict input schemas (Zod for TS, Pydantic for Python). `additionalProperties: true` lets the model invent fields and drift.
+- **MUST** set correct tool annotations: `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` — the host uses these for safety UIs and auto-approval policies
+- **NEVER** expose an MCP server on a public network without auth. MCP clients default to trusting the transport — attackers reach tools directly.
+- **NEVER** log API keys, tokens, or env vars in error messages. A verbose error thrown at the model becomes a stored credential in the conversation.
+- **CRITICAL**: with `stdio` transport, **all** logs go to stderr. Any stdout write that is not a JSON-RPC message breaks the client.
+- **MANDATORY**: every server ships with a README documenting env vars, required scopes, rate limits, and a minimal invocation example.
+
+## Gotchas
+
+- `stdio` transport sends the server's stdout directly to the client as protocol frames. A stray `print()` or `console.log()` crashes the client with a parse error and no clear diagnostic. Route all logs through a logger that writes to stderr.
+- MCP tool descriptions are the only thing the LLM sees when routing. `description: "calls POST /api/v2/tickets"` tells the model nothing about intent. Describe **when to use**, not what it does at the HTTP level.
+- Annotations (`readOnlyHint`, etc.) are optional in the spec but some hosts (Claude Desktop, Cursor) gate auto-approval on them. Missing `destructiveHint: true` on a delete tool may cause the client to run it silently.
+- `streamable-http` with SSE requires the server to handle client reconnects with a `Last-Event-ID` header. Many quick-start templates skip this and drop events on flaky networks.
+- Pagination cursors must be opaque from the client's perspective but stable across retries. A timestamp cursor that advances on every poll fails if the client retries the same cursor after a transient error.
+- Claude Desktop caches server capabilities on first connection. After changing tool schemas, users must explicitly reload the server (quit + reopen or remove/re-add the server) — simply restarting the server process is not enough.
+
+## When NOT to Use
+
+- For **in-toolkit skills** (slash commands, knowledge docs) — use `/skill-creator`
+- For **agents** inside ai-toolkit — use `/agent-creator`
+- For plugin packs bundling multiple agents/skills — use `/plugin-creator`
+- For protocol-level MCP theory and transport trade-offs — use `/mcp-patterns` (knowledge skill)
+- For conformance/integration testing of an MCP server — delegate to the `mcp-testing-engineer` agent
+
 ## Related
 
 - `mcp-patterns` — protocol reference (auto-loaded knowledge skill)

package/app/skills/mem-search/SKILL.md

@@ -68,3 +68,43 @@ This skill queries the SQLite FTS5 full-text search index at `~/.softspark/ai-to
 - FTS5 supports prefix matching: `migrat*` matches "migration", "migrate"
 - Boolean operators: `database AND NOT test`
 - Column filters: `tool_name:Edit` to search only Edit tool observations
+
+## Example
+
+```bash
+/mem-search "postgres migration rollback"
+```
+
+Typical output:
+
+```
+## Memory Search: "postgres migration rollback"
+Found 3 results across 2 sessions.
+
+| # | Session | Project          | Tool | Time       | Preview                              |
+|---|---------|------------------|------|------------|--------------------------------------|
+| 1 | abc123  | magento2-os      | Edit | 2026-03-12 | Rolled back 0042_add_tax_col...      |
+| 2 | def456  | magento2-b2b     | Bash | 2026-02-28 | pg_dump before schema migration...   |
+| 3 | abc123  | magento2-os      | Read | 2026-03-12 | Reviewed migration safety checklist  |
+```
+
+## Rules
+
+- **MUST** escape single quotes in queries by doubling (`it''s`) — SQL injection into the FTS5 call will break the query
+- **NEVER** return the raw database path — treat `~/.softspark/ai-toolkit/memory.db` as internal
+- **CRITICAL**: if the database does not exist, initialize it silently and return zero results — do not fail the skill
+- **MANDATORY**: present Stage 1 (summary table) first; only expand to Stage 2 on follow-up
+
+## Gotchas
+
+- FTS5 `MATCH` is picky: hyphens, slashes, and dots are parsed as operator separators and will reject queries like `mem-search api/v1` with a cryptic `malformed MATCH expression`. Wrap multi-token phrases with double-quotes: `"api/v1"` or `"mem-search"`.
+- Results are ordered by `rank` (FTS5 relevance), **not** by `created_at`. A stale but high-ranked match outranks a fresh but weak one — include the `created_at` column and consider `ORDER BY rank, created_at DESC` for time-sensitive queries.
+- The database path is static at `~/.softspark/ai-toolkit/memory.db`. If the user runs from a container, `~` resolves to the container's home, not the host's — the observation list will look empty. Check the env var `SOFTSPARK_HOME` before assuming the DB is missing.
+- `observations_fts` is a separate virtual table; when observations are deleted directly (not via the SDK) the FTS index can drift. If counts between `observations` and `observations_fts` differ, rebuild with `INSERT INTO observations_fts(observations_fts) VALUES('rebuild');`.
+
+## When NOT to Use
+
+- To search the KB or documentation — use `/search` or `smart_query()`
+- To find a specific commit — use `git log --grep` or `/git-mastery`
+- To list agent tasks — use `TaskList` or `/plan`
+- When memory-pack hooks are not installed — direct the user to install them first

package/app/skills/migrate/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate
-description: "Run database migrations with backup verification"
+description: "Run or create database migrations with the detected tool (Alembic, Prisma, Laravel, Django, Flyway, Drizzle) and verify backups exist first. Use when the user asks to apply, roll back, or generate a migration — not for general schema design."
 effort: medium
 disable-model-invocation: true
 argument-hint: "[direction]"
@@ -88,3 +88,29 @@ Returns JSON with: `tool`, `config_file`, `migrations_dir`, `total_migrations`,
 
 ## Reference Skill
 Use `migration-patterns` skill for zero-downtime strategies and best practices.
+
+## Rules
+
+- **MUST** verify a recent backup exists (or confirmed in-progress) before any forward migration on production
+- **MUST** show the generated SQL (dry-run / `--pretend` / `--sql`) before applying — the user approves the diff, not just the command
+- **NEVER** run destructive migrations (DROP TABLE/COLUMN, NOT NULL on existing column, type change) without a tested rollback path
+- **NEVER** mix schema changes and data backfill in the same migration — they fail differently and roll back differently
+- **CRITICAL**: large-table operations use the concurrent/online variant (`ALTER TABLE ... ALGORITHM=INPLACE`, `CREATE INDEX CONCURRENTLY`) — table locks in production cause outages, not slowdowns
+- **MANDATORY**: migrations test on a non-production environment first with representative data volume
+
+## Gotchas
+
+- `alembic upgrade head` silently skips migrations with `branches` if the branch head is not explicit. Multi-head migrations need `alembic upgrade <revision>@head` or a merge migration first.
+- Prisma's `prisma migrate dev` auto-generates migrations AND applies them AND reseeds the dev database. Running it on a production-connected config destroys data. Always use `prisma migrate deploy` in non-dev.
+- Laravel's `migrate` command without `--force` refuses to run in `APP_ENV=production`. Scripts that blindly run `migrate` hang on interactive prompts in prod — always use `artisan migrate --force` in automation.
+- Django's `migrate --fake` marks a migration as applied **without running it**. Intended for manual data fixes, but accidentally using it skips real schema changes and silently diverges production from code.
+- `CREATE INDEX CONCURRENTLY` (Postgres) cannot run inside a transaction. Alembic wraps each migration in a transaction by default — concurrent index creation needs `op.execute()` with `autocommit_block()` or a manual `COMMIT`.
+- Rolling back a forward migration that added a NOT NULL column deletes the column; data in that column is gone. "Rollback" is not "undo" if the column held user data during the forward window.
+
+## When NOT to Use
+
+- For **zero-downtime schema evolution** strategy (expand-contract, double-write) — use `/migration-patterns`
+- For designing the schema from scratch — use `/database-patterns`
+- For application-layer rollback (deploying previous code) — use `/rollback`
+- For CI-triggered migrations — use `/ci` or `/deploy`
+- When no migration tool is detected — propose one from `/app-builder` instead of ad-hoc SQL

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

@@ -259,3 +259,29 @@ docker service rollback api
 - Not testing rollback path
 - Deploying code before migration completes
 - Dropping columns before removing code references
+
+## Rules
+
+- **MUST** use **expand-contract** for any column rename, type change, or NOT NULL addition in production — single-step migrations block deploys
+- **MUST** test the **rollback** migration on staging with production-like data — an untested rollback is a wish, not a plan
+- **NEVER** drop a column while code still references it — the deploy window overlaps and some requests will fail
+- **NEVER** backfill in one big transaction on a large table — batch with explicit progress tracking and resumability
+- **CRITICAL**: schema changes deploy **before** the code that uses them. Code deploys before the schema means 500 errors until both complete.
+- **MANDATORY**: any migration that affects >1M rows or takes >30 seconds on staging runs behind a feature flag — not a schema lock
+
+## Gotchas
+
+- `ALTER TABLE ... ADD COLUMN NOT NULL DEFAULT <value>` in Postgres rewrites the whole table before version 11 (fast since 11 for non-volatile defaults). On older versions this locks the table for minutes. Add as NULL + default, backfill, then apply NOT NULL.
+- `CREATE INDEX CONCURRENTLY` cannot run inside a transaction, which means many migration tools (Alembic default, Rails) need an override to use it. Check the tool's docs for non-transactional migrations.
+- Double-write strategies need explicit reconciliation. "Write to both old and new, then cut over" leaves stale data in the old store unless you schedule a reconciliation pass before the cutover.
+- Feature flags for migration safety must be **per-row** or **per-tenant**, not global. A global flag gates the whole deploy; a per-row flag lets a small cohort validate before full rollout.
+- Rolling back an expand-contract migration mid-transition is ambiguous — the reverse direction depends on which phase was partially applied. Document the allowed rollback points in the migration itself.
+- ORM query caches may retain the old schema shape. After an additive migration, services often need a cache flush or restart to see the new column — plan this into the deploy sequence.
+
+## When NOT to Load
+
+- For executing a migration with the detected tool — use `/migrate`
+- For **schema design** from scratch — use `/database-patterns`
+- For pipeline migrations outside the database (config, file formats) — generic patterns here do not apply; use `/refactor-plan`
+- For zero-downtime **application** deploys (blue-green, canary) — use `/ci-cd-patterns`
+- When the database is small and can tolerate downtime — simpler single-step migrations are fine; expand-contract is overhead for tables with <100k rows and no concurrent writers