@softspark/ai-toolkit 4.30.2 → 4.31.0

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

@@ -16,15 +16,71 @@ Based on Emil Kowalski's design engineering philosophy — UI polish, component
 - **Invisible details create love.** Most UI refinements users never consciously register — but combined they produce something stunning.
 - **Beauty differentiates.** When functionality is table stakes, aesthetic excellence becomes genuine leverage.
 
-## Anti-Slop Visual Checklist
+## Anti-Slop Visual & Structural Checklist
 
-Defaults that signal machine-generated UI. Each is a falsifiable thing to avoid:
+Defaults that signal machine-generated UI ("AI slop"). Each is a falsifiable rule to uphold:
 
-- **Avoid** full-bleed saturated gradient backgrounds (purple-to-pink hero washes). A flat surface or a near-flat tonal shift reads as intentional; a loud gradient reads as a template.
-- **Avoid** emoji as load-bearing decoration — emoji standing in for icons, bullet markers, or section badges. Use a real icon set or typographic hierarchy instead.
-- **Avoid** the rounded-card-with-left-accent-border cliche repeated across every block. If three sections share that exact treatment, vary the layout or drop the accent.
+- **Avoid** full-bleed saturated gradient backgrounds (purple-to-pink/blue hero washes) and gradient headlines (`background-clip: text`). Use solid ink or warm neutral tinting.
+- **Avoid** emoji as load-bearing decoration (emoji as icons, bullet markers, or section badges). Use a real icon set (Lucide/Phosphor/Heroicons) or typographic hierarchy.
+- **Avoid** the 3-equal-column card grid with icon-above-heading tiles, nested cards-in-cards, or cards with thick coloured left-edge side stripes.
 - **Avoid** hand-drawn fake imagery in SVG (synthetic "photos", invented logos, faux screenshots). Use a real asset or an honest labeled placeholder.
-- **Avoid** the overused default font stack (Inter/Roboto on system-ui for everything with no scale or weight intent). Pick type with a reason and lift the actual stack from source when one exists.
+- **Avoid** fake re-drawn UI chrome (mock browser bars with traffic-light dots, mock IDE title bars, faux phone frames). Let content stand cleanly or use real screenshots in a `<figure>`.
+- **Avoid** default-attractor sameness (Hero → 3 features → CTA → footer). Pick intentional macrostructures and vary heading placement, column rhythm, and divider language.
+- **Avoid** the overused default font stack (Inter/Roboto on system-ui with no pairing). Apply the **2+1 rule** (display + body + at most 1 outlier face in <=2 slots).
+- **Avoid** italic headers: headings and display type are always roman (`font-style: normal`). Never use single-word italic emphasis inside a headline.
+
+## Pre-Emit Self-Critique (Six Axes)
+
+Before marking any UI output complete, score it 1–5 on these six axes (score <3 on any axis triggers a revision pass):
+
+| # | Axis | Assessment |
+|---|---|---|
+| **P** | **Philosophy** | Clear position and intent ("why"), not just arbitrary decoration |
+| **H** | **Hierarchy** | Clear primary / secondary / tertiary weight distinguishable in 2 seconds |
+| **E** | **Execution** | Exact rule weights, contrast ratios, focus rings, zero layout shifts |
+| **S** | **Specificity** | Tailored specifically to this brief, not a generic interchangeable template |
+| **R** | **Restraint** | Removed anything unearned (decorative bloat, redundant cards, excess padding) |
+| **V** | **Variety** | Structurally distinct from previous layouts in the project (not just a color swap) |
+
+## The 8 Interactive States Discipline
+
+Every interactive element (button, input, select, card, tab, switch) must explicitly handle all 8 states in code. Styling only default + hover is an immediate defect:
+
+| State | Trigger | Required Treatment |
+|---|---|---|
+| **1. Default** | At rest | Clean base styling, defined token bindings |
+| **2. Hover** | Pointer over (`@media (hover: hover)`) | Subtle background shift (4–6%) or 1px translate, no layout jump |
+| **3. Focus** | Keyboard navigation | Visible `:focus-visible` ring (2px solid, 1–2px offset), instant appearance |
+| **4. Active** | Pressed | Pressed-in feel: slight darken, `transform: translateY(1px)` or `scale(0.98)` |
+| **5. Disabled** | Inactive (`disabled`, `aria-disabled`) | 3 channels: `opacity: 0.55`, `cursor: not-allowed`, muted token color |
+| **6. Loading** | Async in-flight (`data-state="loading"`) | Inline spinner replacing icon/badge, label preserved, submit disabled |
+| **7. Error** | Validation failure (`aria-invalid="true"`) | Distinct error token border/message, helper text replaced, error icon |
+| **8. Success** | Operation completed (`data-state="success"`) | Quiet confirmation: subtle green/accent indicator or checkmark, auto-dismiss |
+
+## Input Fields & Zero Layout Shift
+
+Input fields, textareas, and selects are where almost-right UIs break:
+
+- **Constant border width (1px everywhere)**: Never change `border-width` between default, hover, focus, error, or disabled states. State changes go to `background-color`, `outline`, `box-shadow`, or `border-color`.
+- **Reserved transparent outline**: Initialize with `outline: 2px solid transparent; outline-offset: 1px;` so activating `:focus-visible` never shifts layout or thrashes paint.
+- **Matched component heights**: Input height MUST equal adjacent button height (base floor 44px for touch targets).
+- **Reserved helper-text slot**: Allocate `min-height: 1lh` for helper/error text so appearing validation messages do not push downstream page content.
+
+## Responsive Non-Negotiables
+
+Verify every layout at **320px, 375px, 414px, and 768px**:
+
+- **No horizontal scroll**: Apply `overflow-x: clip` (never `hidden`) on **both** `html` and `body`.
+- **Single-line clickable affordances**: Buttons, primary nav links, footer links, and CTAs must never wrap to two lines. Shorten label or reflow parent container.
+- **Image grid tracks**: Always use `minmax(0, 1fr)` instead of bare `1fr` to prevent image intrinsic dimensions from blowing out the grid.
+- **Header wrapping**: Display headers must include `overflow-wrap: anywhere; min-width: 0;`.
+
+## Locked Tokens Discipline
+
+- All colors and typography must bind to declared tokens (`var(--color-accent)`, `var(--font-display)`).
+- Never improvise inline hex / rgb / OKLCH values in components mid-build.
+- Keep accent footprint under **~5%** of viewport area (accent is for focal emphasis, not surface fill).
+- Tint neutral surfaces toward the primary anchor hue (minimum 0.005 chroma in OKLCH) — avoid flat `#000` / `#fff`.
 
 ## Minimum-Scale Floors
 
@@ -38,13 +94,13 @@ Accessibility-grounded hard thresholds. Going below these is a defect, not a sty
 
 Treat these as the lower bound, not the target. Captions and footnotes may approach the floor; primary content should sit comfortably above it.
 
-## Context-First Discipline
+## Context-First & Pre-Flight Discipline
 
-High-fidelity work MUST be rooted in real context before any pixels are produced. This mirrors the toolkit's verify-don't-recall ethos:
+High-fidelity work MUST be rooted in real context before any pixels are produced:
 
-- **Read the source first.** Inspect the codebase, design tokens, UI kit, and screenshots that already exist before generating anything.
-- **Lift exact values.** Copy real hex codes, the spacing scale, the font stack, and radii straight from source. Do NOT reconstruct token values from memory — recalled values drift.
-- **Mock from scratch only as a last resort.** Building a screen with no reference is the fallback when no codebase, kit, or screenshot exists, not the default.
+- **Run Pre-Flight Scan**: Inspect existing `design.md`, package font stacks, palette tokens (`:root`, Tailwind `@theme`), motion libraries (`framer-motion`, `motion`, `gsap`), and spacing scale.
+- **Preserve existing design systems**: Never overwrite established tokens or typography unless explicitly asked.
+- **Lift exact values**: Copy real token variable names and spacing classes straight from source. Do NOT reconstruct token values from memory.
 
 ## Question-Budget Gate
 
@@ -158,66 +214,9 @@ Exception: modals keep centered origin (viewport-anchored, not trigger-anchored)
 
 Initial tooltip includes delay; subsequent hovers skip both delay and animation via `[data-instant]` attribute — perceived speed without defeating accidental activation prevention.
 
-## Transform Mastery
-
-### Percentage translations
-
-```css
-/* Moves by own height — perfect for toasts, drawers */
-transform: translateY(100%);
-```
-
-No hardcoded pixel values needed.
-
-### Scale affects children
-
-Unlike `width`/`height`, `scale()` proportionally scales content, icons, and text. Intentional feature, not a bug.
-
-### 3D transforms
-
-```css
-.orbit {
-  transform-style: preserve-3d;
-}
-```
-
-Enables orbit animations and coin flips without JavaScript.
-
-## Clip-path Animation
-
-`clip-path: inset(top right bottom left)` creates rectangular clipping regions:
-
-### Tab color transitions
-
-Stack tab lists, clip the active copy, animate clip-path on change for seamless color shifting.
-
-### Hold-to-delete
-
-```css
-.delete-overlay {
-  clip-path: inset(0 100% 0 0);
-  transition: clip-path 200ms ease-out; /* fast snap-back on release */
-}
-.delete-button:active .delete-overlay {
-  clip-path: inset(0 0 0 0);
-  transition: clip-path 2s linear; /* slow fill while holding */
-}
-```
-
-### Image reveals
-
-```css
-.reveal {
-  clip-path: inset(0 0 100% 0); /* hidden */
-}
-.reveal.visible {
-  clip-path: inset(0 0 0 0); /* revealed */
-}
-```
-
-### Comparison sliders
+## Advanced Animation Techniques
 
-Overlay images, clip top one by adjusting right inset based on drag position.
+For advanced transform mastery, 3D orbits, and clip-path animation recipes (tabs, hold-to-delete, image reveals, sliders), see [reference/animation-recipes.md](reference/animation-recipes.md).
 
 ## Performance Rules
 
@@ -274,21 +273,7 @@ Touch triggers false hover positives — always gate hover animations.
 
 ## Building Loved Components
 
-Five principles (from Sonner, 13M+ weekly downloads):
-
-1. **Developer experience first** — minimal setup friction, insert once, use globally
-2. **Excellent defaults** — ship beautifully configured out-of-box
-3. **Identity through naming** — a memorable name resonates
-4. **Invisible edge cases** — pause timers when hidden, handle pointer capture during drag
-5. **Transitions over keyframes** — rapid additions cause keyframe restart from zero; transitions retarget smoothly
-
-### Cohesion
-
-Animation personality should match component identity. Playful components can bounce; professional dashboards stay crisp.
-
-### Asymmetric timing
-
-Deliberate actions stay slow (2s linear for hold-to-delete), system responses snap fast (200ms ease-out for release).
+For component craftsmanship principles (developer experience, defaults, edge cases, asymmetric timing), see [reference/component-craft.md](reference/component-craft.md).
 
 ## Review Checklist
 
@@ -326,26 +311,25 @@ Visual work ships through two passes, mirroring the toolkit's verification-befor
 
 - **MUST** specify exact properties in `transition` (`transition: transform 200ms ease-out`) — never `transition: all`
 - **MUST** use `ease-out` (or a custom curve) on UI appearances; `ease-in` delays feedback at the moment the user's attention peaks
-- **NEVER** animate `height`, `width`, `margin`, or `top/left` — animate `transform` and `opacity` only. Layout-triggering properties drop frames under load.
-- **NEVER** add motion for decorative reasons alone — every animation must serve meaning (status change, spatial relationship, progress)
-- **CRITICAL**: exit is faster than enter. A 2s linear enter (hold-to-delete) needs a 200ms ease-out exit. Symmetrical durations feel sluggish.
-- **MANDATORY**: any animation longer than 300ms for UI feedback needs an explicit justification — the user perceives >300ms as "laggy", not "smooth"
-- **MUST** lift exact values (hex, spacing, font stack, radii) from the real codebase, tokens, UI kit, or screenshots before high-fidelity work — never reconstruct token values from memory; mock from scratch only when no source exists
-- **MUST** keep slide body text at ~24px+, print at ~12pt+, and mobile touch targets at 44px+ — these are accessibility floors, not preferences
-- **NEVER** ship the slop defaults — saturated full-bleed gradients, emoji as decoration, repeated rounded-card-with-accent-border, hand-drawn fake imagery in SVG, or the unconsidered default font stack
-- **NEVER** add filler (dummy stats, decorative sections, lorem) to fill space, and never fabricate assets — an honest labeled placeholder beats an invented icon or fake image; ask for the real one
-- **MUST** match the existing UI's vocabulary (palette, states, motion, shadow/density, copy tone) when editing a live surface instead of imposing a new style
-- **MUST** ask about goals, audience, and which dimension to diverge on (UX vs. visuals vs. copy) before building an open-ended ask; skip questions only when context is rich and the ask is bounded
-- **CARVE-OUT**: a sanctioned design audit, accessibility-failure demonstration, or authorized red-team mockup may deliberately reproduce a slop pattern or sub-floor scale to illustrate the defect — label it as such; the bans above target shipped UI, not sanctioned analysis
-- **SHOULD** produce 3+ atomic variations across distinct axes (layout, color, type, interaction), ordered basic → advanced, for any exploratory or open design ask
+- **NEVER** animate `height`, `width`, `margin`, or `top/left` — animate `transform` and `opacity` only
+- **CRITICAL**: exit is faster than enter. A 2s linear enter (hold-to-delete) needs a 200ms ease-out exit
+- **MANDATORY**: any animation longer than 300ms for UI feedback needs an explicit justification
+- **MUST** implement all 8 interactive states (default, hover, focus-visible, active, disabled, loading, error, success) for every interactive element
+- **MUST** keep `border-width: 1px` constant across all input states (default/hover/focus/error/disabled) with a reserved transparent outline to guarantee zero layout shift
+- **MUST** apply `overflow-x: clip` on both `html` and `body` to eliminate horizontal viewport scrolling on mobile (320px–768px)
+- **MUST** ensure clickable affordance text (buttons, nav links, CTAs) remains single-line across all viewports
+- **MUST** keep all display headings roman (`font-style: normal`) — never use single-word italic emphasis inside headlines
+- **MUST** adhere to the 2+1 typography rule (max 3 families, outlier face used in at most 2 slots)
+- **MUST** lock all colors to named CSS variable tokens — never improvise inline hex/rgb/OKLCH values mid-render
+- **MUST** lift exact values (hex, spacing, font stack, radii) from real source — never reconstruct tokens from memory
+- **MUST** keep mobile touch targets at 44px+ minimum floor
+- **NEVER** ship slop defaults (purple/blue gradient hero washes, gradient text headlines, emoji as icons, cards-in-cards, side-stripe cards, centered-everything 100vh heroes)
+- **NEVER** add filler (dummy stats, fake testimonials, invented logos, lorem) — use honest labeled placeholders
+- **MUST** run pre-emit self-critique scoring (P/H/E/S/R/V) before completing UI implementation
 
 ## Gotchas
 
-- `transform: translateX(-50%)` on an element that will animate `opacity` triggers a paint on every frame because the browser cannot composite the layer. Add `will-change: transform, opacity` to hint the compositor — but only during the animation, not permanently (it consumes GPU memory).
-- Framer Motion's `x={100}` prop is a shortcut for `transform: translateX(100px)`, but under load it falls back to the main thread. Use the longhand `style={{ transform: "translateX(100px)" }}` for guaranteed compositor path.
-- `@media (prefers-reduced-motion: reduce)` is widely supported but often forgotten. Users with vestibular disorders or pointer-device sensitivity will notice; include a reduced-motion override for every non-trivial animation.
-- Chrome's Performance tab samples animations, but the sampling rate is 1kHz — sub-millisecond jank is invisible. For micro-animations, prefer `performance.mark` and `measure` with explicit timestamps.
-- CSS keyframe animations re-trigger on every class toggle. On rapidly-updating state (drag, hover), transitions are cheaper and smoother; keyframes are for one-shot entries/exits.
+For compositor edge cases, Framer Motion GPU optimizations, and reduced-motion gotchas, see [reference/animation-recipes.md](reference/animation-recipes.md).
 
 ## When NOT to Load
 
@@ -354,3 +338,4 @@ Visual work ships through two passes, mirroring the toolkit's verification-befor
 - For **information architecture** and user flows — use `/ux-designer` agent
 - For generic CSS patterns without motion — this skill is motion-specific
 - For **brand voice** / content tone — use `/brand-voice`
+

package/app/skills/design-engineering/reference/animation-recipes.md

@@ -0,0 +1,67 @@
+# Animation Recipes & Advanced Techniques
+
+Supplementary reference for `design-engineering` skill covering transform techniques, clip-path animations, and advanced interaction recipes.
+
+## Transform Mastery
+
+### Percentage Translations
+```css
+/* Moves by own height — perfect for toasts, drawers */
+transform: translateY(100%);
+```
+No hardcoded pixel values needed.
+
+### Scale Affects Children
+Unlike `width`/`height`, `scale()` proportionally scales content, icons, and text. Intentional feature, not a bug.
+
+### 3D Transforms
+```css
+.orbit {
+  transform-style: preserve-3d;
+}
+```
+Enables orbit animations and coin flips without JavaScript.
+
+---
+
+## Clip-Path Animation
+
+`clip-path: inset(top right bottom left)` creates rectangular clipping regions:
+
+### Tab Color Transitions
+Stack tab lists, clip the active copy, animate clip-path on change for seamless color shifting.
+
+### Hold-to-Delete
+```css
+.delete-overlay {
+  clip-path: inset(0 100% 0 0);
+  transition: clip-path 200ms ease-out; /* fast snap-back on release */
+}
+.delete-button:active .delete-overlay {
+  clip-path: inset(0 0 0 0);
+  transition: clip-path 2s linear; /* slow fill while holding */
+}
+```
+
+### Image Reveals
+```css
+.reveal {
+  clip-path: inset(0 0 100% 0); /* hidden */
+}
+.reveal.visible {
+  clip-path: inset(0 0 0 0); /* revealed */
+}
+```
+
+### Comparison Sliders
+Overlay images, clip top one by adjusting right inset based on drag position.
+
+---
+
+## Gotchas & Performance Edge Cases
+
+- `transform: translateX(-50%)` on an element that will animate `opacity` triggers a paint on every frame because the browser cannot composite the layer. Add `will-change: transform, opacity` during animation only.
+- Framer Motion's `x={100}` prop falls back to the main thread under load. Use `style={{ transform: "translateX(100px)" }}` for guaranteed GPU compositor path.
+- `@media (prefers-reduced-motion: reduce)` is widely supported but often forgotten; include reduced-motion overrides for every non-trivial animation.
+- Chrome's Performance tab samples animations at 1kHz — sub-millisecond jank is invisible. Prefer `performance.mark` and `measure` with explicit timestamps.
+- CSS keyframe animations re-trigger on every class toggle; transitions are cheaper and smoother on rapidly-updating state (drag, hover).

package/app/skills/design-engineering/reference/component-craft.md

@@ -0,0 +1,28 @@
+# Component Craft & Design Principles
+
+Supplementary reference for `design-engineering` skill covering principles for loved UI components and microinteraction cohesion.
+
+## Building Loved Components
+
+Five core principles (inspired by Sonner):
+
+1. **Developer experience first** — minimal setup friction, insert once, use globally
+2. **Excellent defaults** — ship beautifully configured out-of-box
+3. **Identity through naming** — a memorable name resonates
+4. **Invisible edge cases** — pause timers when hidden, handle pointer capture during drag
+5. **Transitions over keyframes** — rapid additions cause keyframe restart from zero; transitions retarget smoothly
+
+---
+
+## Personality & Cohesion
+
+Animation personality should match component identity:
+- **Playful components**: Can use slightly softer curves or playful timing.
+- **Professional tools & dashboards**: Stay crisp, deterministic, and fast (150–200ms).
+
+---
+
+## Asymmetric Timing
+
+- **Deliberate user actions**: Stay controlled/slow (e.g., 2s linear for hold-to-delete).
+- **System feedback / release**: Snaps fast (e.g., 200ms ease-out).

package/app/skills/documentation-standards/SKILL.md

@@ -47,7 +47,7 @@ and never authoritative on its own.
 |----------|-----------|---------|----------|
 | `reference` | `kb/reference/` | Technical specifications, catalogs, architecture notes, API docs | `agents-catalog.md`, `architecture-overview.md` |
 | `howto` | `kb/howto/` | Step-by-step task guides | `use-corrective-rag.md`, `configure-mcp-server.md` |
-| `procedures` | `kb/procedures/` | SOPs a person follows: release, migration, review | `maintenance-sop.md`, `sop-release.md` |
+| `procedures` | `kb/procedures/` | SOPs a person follows: release, migration, review | `sop-maintenance.md`, `sop-release.md` |
 | `troubleshooting` | `kb/troubleshooting/` | Problem resolution, debugging guides | `database-connection-issues.md` |
 | `best-practices` | `kb/best-practices/` | Guidelines, recommendations, standards | `security-checklist.md` |
 | `decisions` | `kb/decisions/` | Architecture decision records and design rationale | `adr-004-kb-migration.md` |

package/app/skills/edit-discipline/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: edit-discipline
+description: "Change files with the edit and write tools, never by rewriting them through bash (sed, awk, tee, heredoc, redirection), and show `git diff` before reporting a file-changing task as done. Triggers: edit, write, modify, refactor, patch, fix, diff, review changes."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Edit Discipline
+
+This rule comes from `app/rules/edit-discipline.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Edit Discipline & Reviewable Changes
+
+## Edit files with the editing tools, not the shell
+
+Use the `edit` and `write` tools to change a file. Do not rewrite tracked files
+through `bash` with `sed`, `awk`, `tee`, a heredoc, or `>` redirection.
+
+This is not a style preference. A shell rewrite is opaque to the host: the
+session records a command, not a change. An `edit` call records which file
+changed and how, so the interface can render it, a reviewer can read it, and a
+later turn can cite it. A `sed` line records none of that, and the only way to
+find out what happened is to read the file again.
+
+The shell remains correct for what it is for: running builds, tests, linters,
+git, package managers, and generators that own their own output.
+
+## Show the change before calling the work done
+
+Before reporting a file-changing task as finished, show what changed:
+
+```bash
+git diff -- <paths>          # tracked files
+git status --short           # what is new or removed
+```
+
+Paste the diff into the reply, or state precisely why it is too large and
+summarise it by file with the counts. A task that reports success without
+showing the change asks the reader to take the result on trust, and the reader
+is the one who has to decide whether to commit it.
+
+For an untracked file, show the content you wrote, not a description of it.
+
+## Why both halves matter together
+
+Editing through the tools makes a change *recordable*; showing the diff makes it
+*reviewed*. Either alone leaves the person deciding whether to ship blind to
+something they are accountable for.

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

@@ -0,0 +1,18 @@
+---
+name: git-conventions
+description: "Conventional Commits only (feat, fix, docs, refactor, test, chore); no AI co-authorship trailer and no AI signature in a commit message. Triggers: commit, git, message, changelog, release, pull request."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Git Conventions
+
+This rule comes from `app/rules/git-conventions.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Git Conventions
+
+- Do NOT add `Co-Authored-By: Claude` or any AI co-authorship to commits
+- Do NOT add Claude signatures or attribution to commit messages
+- Conventional commits format: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`

package/app/skills/output-mode/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: output-mode
+description: "Answer concisely: lead with the result, no preamble, tables over prose, no trailing restatement of a diff the reader can already see. Triggers: response style, verbosity, summary, explanation, report."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Output Mode
+
+This rule comes from `app/rules/output-mode.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Output Mode
+
+`output-mode: concise`
+
+Default response mode for this project is **concise**. The `brand-voice` skill (when present in ai-toolkit) auto-loads its `concise` rules; assistants without that skill should still apply the directives below.
+
+## Concise Mode Directives
+
+- **No preamble.** Skip "I'll now...", "Sure, let me...", "Great question!" and similar warm-ups. Start with the answer.
+- **Lead with the result.** Conclusion or output first; explanation only if asked or non-obvious.
+- **Max 3 sentences per closed question.** Yes/no, single-fact, or "where is X" answers stay under three sentences.
+- **Tables and lists over prose** when comparing options, listing steps, or showing values.
+- **No trailing summaries.** If the diff or output already shows what changed, do not restate it.
+- **Drop filler adjectives.** No "nice", "great", "powerful", "robust" unless the user asked for evaluation.
+- **Cite file paths as `path:line`** instead of paragraphs describing where things live.
+- **Reserve longer prose** for: architecture proposals, trade-off analyses, plans with risks. Everything else: terse.
+
+## When to escalate to verbose
+
+- User explicitly asks: "explain in detail", "walk me through", "give me the full picture".
+- Reporting a non-obvious failure mode where missing context would mislead.
+- Architecture / RFC / ADR / trade-off documents — those have their own structure.
+
+## How to override
+
+- Per-session: `/brand-voice default` (or `/brand-voice strict` for even tighter)
+- Per-project: change this rule's `output-mode:` value in the project's `CLAUDE.md`
+- Permanent removal: re-run `ai-toolkit install --skip rules` or strip the `<!-- TOOLKIT:output-mode -->` block manually

package/app/skills/quality-gates/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: quality-gates
+description: "Plan before work over an hour, and hold the gates: ruff clean, mypy --strict clean, pytest coverage above 70 percent, no secrets in code. Triggers: quality, lint, mypy, pytest, coverage, gate, definition of done."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Quality Gates
+
+This rule comes from `app/rules/quality-gates.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Quality Gates & Mandatory Practices
+
+## MANDATORY PRACTICES
+1.  **Plan First:** Tasks >1h require Plan, Success Criteria, and Pre-Mortem.
+2.  **Quality Gates:**
+    *   `ruff check .` (0 errors)
+    *   `mypy --strict src/` (0 errors)
+    *   `pytest --cov=src` (>70% coverage)
+    *   **Type Safety:** 100% public APIs, >60% internal.
+3.  **Security:** No secrets in code, sanitization, auth z/n.

package/app/skills/review/SKILL.md

@@ -146,6 +146,16 @@ After all reviewers complete:
 - [ ] No memory leaks
 - [ ] Optimized loops
 
+### Frontend & UI Craft (Anti-Slop Gates)
+- [ ] No gradient text headlines (`background-clip: text`) or saturated purple/blue hero washes
+- [ ] No cliché 3-column card grids with icon-above-title tiles, card-in-card nesting, or side-stripe cards
+- [ ] Interactive elements implement all 8 states (default, hover, focus-visible, active, disabled, loading, error, success)
+- [ ] Input fields maintain constant 1px `border-width` across all states (zero layout shift) and reserve 2px transparent outline
+- [ ] Mobile responsive: `overflow-x: clip` on `html` and `body`; no buttons/links wrapping to 2 lines; image grid tracks use `minmax(0, 1fr)`
+- [ ] Typography: headings are roman (`font-style: normal`, no italic emphasis in headers); max 3 font families (2+1 rule)
+- [ ] Content honesty: no invented metrics ("+47% conversion"), fake testimonials, or placeholder stock logos
+- [ ] No fake re-drawn browser/OS chrome; no emoji used as load-bearing icons
+
 ### Testing
 - [ ] Tests for new code
 - [ ] Edge cases covered

package/kb/procedures/{ecosystem-sync-sop.md → sop-ecosystem-sync.md}

@@ -253,5 +253,5 @@ jobs:
 
 - [Supported Tools Registry](../reference/supported-tools-registry.md) — human-readable per-tool breakdown
 - [MCP Editor Compatibility](../reference/mcp-editor-compatibility.md) — MCP-specific adapter table
-- [Maintenance SOP](maintenance-sop.md) — general toolkit upkeep
-- [Release Preparation SOP](release-preparation-sop.md) — run the doctor before tagging
+- [Maintenance SOP](sop-maintenance.md) — general toolkit upkeep
+- [Release Preparation SOP](sop-release.md) — run the doctor before tagging

package/kb/procedures/{post-release-testing-sop.md → sop-post-release-testing.md}

@@ -16,7 +16,7 @@ actually install, from npm, rather than the working tree.
 
 Sibling procedures exist for `jira-mcp` and `legal-pl-pack`; this is the
 ai-toolkit equivalent. It complements
-[Release Verification](release-verification-sop.md), which checks the toolkit
+[Release Verification](sop-release-verification.md), which checks the toolkit
 from the maintainer's own installed copy. The difference that matters: this one
 never writes to the maintainer's `~/.claude` or `~/.softspark`.
 
@@ -310,6 +310,6 @@ print(f'removed {sb} ({n} files)')
 
 ## Related
 
-- [Release Preparation](release-preparation-sop.md) — run before tagging
-- [Release Verification](release-verification-sop.md) — the maintainer-install checks
+- [Release Preparation](sop-release.md) — run before tagging
+- [Release Verification](sop-release-verification.md) — the maintainer-install checks
 - [rtk-pack Retirement](../history/completed/rtk-pack-retirement-20260727.md) — what happened the one time this SOP was written and not run

package/kb/procedures/sop-pre-commit.md

@@ -0,0 +1,96 @@
+---
+title: "SOP: Pre-Commit Gate"
+category: procedures
+service: ai-toolkit
+tags: [pre-commit, quality-gate, shellcheck, bats, validation, secrets]
+version: "1.0.0"
+created: "2026-09-02"
+last_updated: "2026-09-02"
+description: "The local gate to run before every commit to ai-toolkit: staged-file and secret scan, ShellCheck, Python syntax, toolkit validation, and the Bats suite. Runs the same checks CI runs, so main does not go red after a push."
+---
+
+# SOP: Pre-Commit Gate
+
+## Why this exists
+
+CI runs on `main` and on pull requests, but it runs *after* the push. Every
+check below already exists in `.github/workflows/ci.yml`; running them locally
+first is what keeps `main` green and keeps a release from becoming a debug
+session. The v4.5.1 postmortem in `sop-release.md` is the case
+where a hook lint failure published while reddening `main` CI.
+
+This gate is not a substitute for `sop-release.md`. That SOP gates
+a *tag*; this one gates a *commit*.
+
+## Prerequisites
+
+`shellcheck`, `python3` and `bats` must be on `PATH`. The suite is the one
+check that silently does nothing when its runner is absent, so install it
+before relying on this gate:
+
+```bash
+brew install bats-core shellcheck    # macOS
+sudo apt-get install -y bats shellcheck   # Debian / Ubuntu
+```
+
+## The gate
+
+Run all five from the repository root. Each mirrors a CI job.
+
+```bash
+# 1. Staged files: secrets, large blobs, commit-type suggestion
+python3 app/skills/commit/scripts/pre-commit-check.py
+
+# 2. ShellCheck hooks -- the CI job that has published while red before
+shellcheck --severity=warning app/hooks/*.sh app/plugins/*/hooks/*.sh
+
+# 3. Python syntax across every script the toolkit ships
+python3 -m py_compile scripts/*.py app/skills/*/scripts/*.py
+
+# 4. Toolkit integrity: agents, skills, registry drift, content quality
+npm run validate
+
+# 5. The suite. Run it ONCE -- see the single-run discipline below
+npm test
+```
+
+A non-zero exit from any of them is a stop, not a warning to note and push past.
+
+## Single-run discipline
+
+`npm test` runs the Bats suite with `--jobs 4`. Running it repeatedly to see
+whether a failure is "flaky" hides real ordering bugs and wastes minutes. Run
+it once. If it fails, read the failure and fix the cause; if the same test
+passes on a re-run without a code change, that instability is itself the bug
+and belongs in an issue, not in a retry.
+
+## What this gate does not cover
+
+- **Cross-platform.** The suite here runs on your machine only. Both
+  `ubuntu-latest` and `macos-latest` must be green before a tag; that gate
+  lives in `sop-release.md`, Phase 7, and is bound to the exact
+  release commit.
+- **Required files.** The `required-files` CI job checks that every file the
+  module template mandates is present and that the version is in sync across
+  all four manifests. It is cheap and runs on every push.
+- **Provenance and SARIF.** Release-time concerns; see
+  `sop-release.md`.
+
+## Commit message
+
+Conventional Commits, and no AI co-authorship trailer:
+
+```
+feat(scope): summary in the imperative
+fix(scope): summary in the imperative
+docs|refactor|test|chore(scope): ...
+```
+
+`pre-commit-check.py` suggests a type from the staged paths. It is a
+suggestion; the scope and the summary are yours.
+
+## Related
+
+- `sop-release.md` -- the pre-tag gate, including cross-platform CI
+- `sop-post-release-testing.md` -- what to verify after a release ships
+- `sop-release-verification.md` -- end-to-end smoke test of an installed build