@softspark/ai-toolkit 2.11.0 → 2.12.0

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`

package/app/skills/rollback/SKILL.md

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

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

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

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

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

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

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