@softspark/ai-toolkit 4.30.2 → 4.31.0

package/CHANGELOG.md

@@ -7,6 +7,63 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.31.0 - Toolkit rules reach every editor (2026-09-03)
+
+### Added
+
+- The five top-level rule files in `app/rules/` ship as knowledge skills,
+  generated by `scripts/generate_toolkit_rules_skills.py` and wired as
+  `npm run generate:toolkit-rules`. Ten bats tests cover generation,
+  idempotence, and the content of the new rule.
+- `app/rules/edit-discipline.md`: change files with the `edit` and `write`
+  tools rather than rewriting them through `bash`, and show `git diff` before
+  reporting a file-changing task as done.
+
+### Fixed
+
+- **Every toolkit rule was inert outside Claude Code.** They existed only as
+  Claude Code user-level files under `~/.claude/rules/`, and the global
+  `CLAUDE.md` carried a pointer to them rather than their content — a Claude
+  Code idiom that assumes `/memory`. DeepSeek Harness reads `AGENTS.md`,
+  `AGENTS.local.md`, `CLAUDE.md` and `CLAUDE.local.md` and has no
+  rules-directory support at all, so under DSH the rules were named in an
+  injected file and never loaded. That is why an agent there kept rewriting
+  tracked files with `sed` while a rule forbidding exactly that sat unread.
+
+  Skills are discovered by every editor that reads the shared catalogue, and
+  the catalogue injects each skill's *description* into the session. The
+  descriptions are therefore written as the rule itself in one imperative
+  line: in context whether or not the body is loaded.
+
+  Verified against a live DSH session — the agent loaded `edit-discipline`
+  unprompted, used `write` and `edit` instead of `bash`, and rendered the
+  change as a diff.
+
+---
+
+## v4.30.3 - Copilot health-check compatibility (2026-09-02)
+
+### Fixed
+
+- **`doctor` accepts sentence punctuation after runtime SemVer.** The official
+  Copilot CLI output `GitHub Copilot CLI 1.0.80.` now reports version `1.0.80`
+  instead of an invalid-SemVer warning.
+- **Complete-token validation remains strict.** Extra version segments, invalid
+  prerelease identifiers, and leading-zero numeric fields are still rejected.
+- **DSH cold-add timing gate is runner-safe.** The regression still proves a
+  cold package add can outlive the legacy scaled timeout while leaving enough
+  headroom for macOS CI process startup.
+
+### Changed
+
+- **Test count.** Increased from 1920 to 1921 with the exact Copilot output
+  regression.
+- **Release tags require green cross-platform branch CI.** The preparation SOP
+  now binds the gate to the exact release commit and requires both Ubuntu and
+  macOS Bats matrix jobs before creating or pushing a tag.
+
+---
+
 ## v4.30.2 - Portable Linux release gates (2026-09-02)
 
 ### Fixed

package/README.md

@@ -1,33 +1,32 @@
 # ai-toolkit
 
-> AI coding toolkit with machine-enforced safety, 109 skills, 44 agents, lifecycle hooks, persona presets, opt-in plugin packs, and benchmark tooling. DSH is available as a separate explicit developer-preview target.
+> AI coding toolkit with machine-enforced safety, 114 skills, 44 agents, lifecycle hooks, persona presets, opt-in plugin packs, and benchmark tooling. DSH is available as a separate explicit developer-preview target.
 
 [![CI](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/softspark/ai-toolkit/actions/workflows/ci.yml)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
-[![Skills](https://img.shields.io/badge/skills-109-brightgreen)](app/skills/)
+[![Skills](https://img.shields.io/badge/skills-114-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1920%20passing-success)](tests/)
-
-## What's New in v4.30.2
-
-**v4.30.2** publishes the managed DSH and plugin-owned MCP release with Linux-portable recovery gates:
-
-- `install --local --editors dsh` emits the managed `.agents/skills` surface,
-  while `ai-toolkit dsh install|update|doctor|uninstall --profile web` owns the
-  exact DSH `0.1.1-rc.2`, dsh-codex `1.0.0`, dsh-orchestrator `1.0.1`, and preset
-  lifecycle. DSH remains explicit-only and never handles vendor credentials.
-- Plugin packs can ship MCP templates and native rules for Claude, Codex, Cursor,
-  and Gemini. Two localhost RAG templates are included, bringing the built-in MCP
-  catalogue to 28.
-- Cross-file plugin operations and DSH package mutations now use ownership CAS,
-  pinned paths, process-tree teardown, durable recovery gates, and conservative
-  rollback that preserves concurrent or user-authored data.
-- Recovery verification and interrupted preset relocation now emit deterministic,
-  non-empty diagnostics on both macOS and Linux. File-mode assertions and malformed
-  ownership diagnostics also use the same portable contract. The public `v4.30.0`
-  and `v4.30.1` workflows stopped before npm publication; neither registry artifact
-  was created.
-- Test count: 1675 -> 1920.
+[![Tests](https://img.shields.io/badge/tests-1931%20passing-success)](tests/)
+
+## What's New in v4.31.0
+
+**v4.31.0** corrects the post-release health check for the managed DSH and
+plugin-owned MCP release:
+
+- `ai-toolkit doctor` now extracts `1.0.80` from the official Copilot CLI output
+  `GitHub Copilot CLI 1.0.80.` instead of treating sentence punctuation as an
+  invalid SemVer suffix.
+- Complete-token validation remains fail closed for malformed versions such as
+  `1.2.3.4`, invalid prerelease identifiers, and leading-zero numeric fields.
+- The DSH cold-add regression keeps its legacy-timeout coverage with macOS CI
+  process-startup headroom, removing the release-blocking timing flake.
+- Release tags now require green Ubuntu and macOS branch CI for the exact commit
+  before the publish workflow can start.
+- The release retains the explicit DSH lifecycle, plugin-owned MCP/rules, portable
+  recovery gates, and the exact DSH package set published in v4.30.2. Test count:
+  1920 -> 1931.
+
+See [CHANGELOG.md](CHANGELOG.md) for full history.
 
 ## Table of Contents
 
@@ -61,7 +60,7 @@ ai-toolkit install
 npx @softspark/ai-toolkit install
 ```
 
-**That's it.** Claude Code picks up 109 skills, 44 agents, quality hooks, and the safety constitution automatically.
+**That's it.** Claude Code picks up 114 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
 **Windows:** WSL is the recommended runtime. Native Windows works when Git Bash is available for hook scripts; dependency hints cover `winget`, Chocolatey, and Scoop. See [Windows Support](kb/reference/windows-support.md).
 
@@ -187,7 +186,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 |-----------|-------|-------------|
 | `skills/` (task) | 32 | Slash commands: `/commit`, `/build`, `/deploy`, `/test`, `/mcp-builder`, ... |
 | `skills/` (hybrid) | 31 | Slash commands with agent knowledge base |
-| `skills/` (knowledge) | 46 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
+| `skills/` (knowledge) | 51 | Domain knowledge auto-loaded by agents (includes 13 `<lang>-rules` skills) |
 | `agents/` | 44 | Specialized agents across 10 categories |
 | `hooks/` | 28 entries / 14 events + statusLine | Quality gates, path safety, prompt governance, loop guard, session lifecycle |
 | `plugins/` | 2 packs | Opt-in packs that install files of their own (memory, enterprise) |
@@ -203,7 +202,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
-│   ├── skills/          # 109 skills (task / hybrid / knowledge)
+│   ├── skills/          # 114 skills (task / hybrid / knowledge)
 │   ├── rules/           # Source rules synced into Claude/editor rule files
 │   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
 │   ├── claude-app/      # Generated Chat/Cowork plugin rules, hooks, instructions
@@ -342,7 +341,7 @@ Need multi-agent coordination?
 | opencode Compatibility | [kb/reference/opencode-compatibility.md](kb/reference/opencode-compatibility.md) |
 | GitHub Copilot Compatibility | [kb/reference/copilot-compatibility.md](kb/reference/copilot-compatibility.md) |
 | DSH Compatibility | [kb/reference/dsh-compatibility.md](kb/reference/dsh-compatibility.md) |
-| Maintenance SOP | [kb/procedures/maintenance-sop.md](kb/procedures/maintenance-sop.md) |
+| Maintenance SOP | [kb/procedures/sop-maintenance.md](kb/procedures/sop-maintenance.md) |
 
 ---
 

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.30.2",
+  "version": "4.31.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/agents/code-reviewer.md

@@ -59,6 +59,13 @@ Before reviewing, gather context using available tools:
 - Secrets management
 - IAM/permissions scope
 
+### 5. Frontend & UI Craft (Anti-Slop Audit)
+- Generic AI tells: gradient text headlines, purple/blue washes, 3-column card clichés, nested cards
+- Missing interactive states: lacking focus-visible, active, disabled, loading, error, success
+- Input stability: layout shifts caused by changing border-widths
+- Mobile responsiveness: horizontal scroll risk, clickable affordance text wrapping
+- Fabricated content: invented metrics, fake testimonials, mock OS/browser chrome
+
 ## Review Checklist
 
 ### Security (check first)
@@ -78,6 +85,13 @@ Before reviewing, gather context using available tools:
 - [ ] Tests cover critical paths
 - [ ] Documentation is accurate
 
+### Frontend & UI Craft
+- [ ] No gradient headlines (`background-clip: text`) or purple/blue gradient heroes
+- [ ] Interactive elements implement all 8 states
+- [ ] Inputs maintain constant 1px border-width (zero layout shift)
+- [ ] Mobile responsive: `overflow-x: clip`, single-line button text
+- [ ] No invented metrics, fake testimonials, or mock chrome
+
 ### Performance
 - [ ] No obvious N+1 queries
 - [ ] Resources are properly cleaned up

package/app/agents/frontend-specialist.md

@@ -104,15 +104,17 @@ hybrid_search_kb("[UI patterns, accessibility]")
 - Image optimization
 - Bundle analysis
 
-### Design Craft (impeccable-inspired — guidance, not mandate)
-Frontend is craft as much as system. Seven domains, one concrete rule each:
-- **Typography** — reject Arial/Inter defaults; pair display + text on a modular scale; enable OpenType features when they serve content
-- **Color** — prefer OKLCH; tint neutrals; no pure `#000`; verify gray-on-color contrast
-- **Spatial** — consistent spacing scale (4/8/12/16/24/32/48); do not nest cards in cards
-- **Motion** — no bounce/elastic easing; stagger reveals; respect `prefers-reduced-motion`
-- **Interaction** — replace default focus outlines, never just remove; loaders show progress; errors name the remedy
-- **Responsive** — mobile-first; `clamp()` for fluid type; container queries for component-level behavior
-- **UX Writing** — button labels = verb + object; errors = cause + remedy; empty states earn their screen
+### Design Craft & Anti-Slop Standards
+Frontend is craft as much as system. Core non-negotiables:
+- **Typography (2+1 Rule)** — Reject Inter/system-default with no pairing; pair display + text on a modular scale; display headers are strictly roman (`font-style: normal`, never italic emphasis words in headlines); max 3 font families, outlier face in at most 2 slots.
+- **Color & Locked Tokens** — Prefer OKLCH; tint neutral surfaces toward anchor hue (>=0.005 chroma); no pure `#000`/`#fff`; lock tokens to CSS variables (`var(--color-accent)`) without inline hex/rgb improvisation; accent area <=5% of viewport.
+- **Spatial & Macrostructures** — Reject default-attractor rhythm (Hero → 3 features → CTA → footer); choose distinct macrostructures (Bento Grid, Long Document, Marquee, Stat-Led, Workbench, FAQ, Manifesto); do not nest cards in cards or use thick side stripes.
+- **8 Interactive States** — Every interactive component MUST implement all 8 states: default, hover, focus-visible, active, disabled, loading, error, success.
+- **Input Stability (Zero Layout Shift)** — Constant 1px `border-width` across all states; reserve 2px transparent outline at rest; input height = button height (>=44px floor); reserve 1lh helper text slot.
+- **Responsive Non-Negotiables** — Mobile-first (320px–768px verified); `overflow-x: clip` on `html` and `body`; clickable buttons/links never wrap to 2 lines; image grid tracks use `minmax(0, 1fr)`.
+- **Motion** — No bounce/elastic easing; GPU-accelerated transforms; faster exit than enter; respect `prefers-reduced-motion`.
+- **Content Honesty & No Fake Chrome** — Never invent metrics, testimonials, or fake logos; do not hand-draw fake browser/phone frames.
+- **Pre-Emit Self-Critique** — Score output 1–5 on Philosophy, Hierarchy, Execution, Specificity, Restraint, Variety (all >=3).
 
 ### AI-Native UI (inspired by 21st.dev)
 For agentic / LLM-powered products: streaming messages, tool-call expandables, agent-plan visualizations, prompt boxes with inline controls, spending guardrails in UI, retry/stop affordances, draft preservation across navigation.
@@ -122,13 +124,13 @@ For agentic / LLM-powered products: streaming messages, tool-call expandables, a
 ### Component Design
 ✅ Single responsibility per component
 ✅ Props interface with TypeScript
-✅ Accessible by default (ARIA, keyboard)
-✅ Responsive mobile-first
+✅ Accessible by default (ARIA, keyboard, focus-visible)
+✅ Responsive mobile-first with 8 interactive states
 ✅ Error boundaries for failure handling
 
 ❌ Don't create god components
-❌ Don't inline all styles
-❌ Don't skip accessibility
+❌ Don't inline all styles or improvise tokens mid-render
+❌ Don't skip accessibility or interactive states
 
 ### State Management
 ✅ Colocate state near usage
@@ -138,7 +140,7 @@ For agentic / LLM-powered products: streaming messages, tool-call expandables, a
 
 ### Performance
 ✅ Lazy load routes and heavy components
-✅ Optimize images (next/image, @nuxt/image)
+✅ Optimize images (next/image, @nuxt/image, fetchpriority for LCP)
 ✅ Minimize bundle size
 ✅ Use virtualization for long lists
 
@@ -147,18 +149,19 @@ For agentic / LLM-powered products: streaming messages, tool-call expandables, a
 ### Engineering
 ❌ **Prop drilling** → Use context or state management
 ❌ **Unnecessary re-renders** → Memoize appropriately
-❌ **Layout shift** → Reserve space, use skeleton
+❌ **Layout shift** → Reserve space, use skeleton, constant 1px input borders
 ❌ **Giant components** → Split into smaller units
 
-### Taste (the LLM defaults — reject on sight)
-❌ Arial / Inter / system-default type with no intentional pairing
-❌ Gray text on colored backgrounds (contrast failure)
-❌ Pure `#000` black — use tinted near-black
-❌ Cards nested inside cards — flatten with type + spacing hierarchy
-❌ Bounce / elastic easing curves (feel dated)
-❌ Purple gradients (the generic-LLM tell)
-❌ Motion that ignores `prefers-reduced-motion`
-❌ Generic stock illustrations for empty states
+### Taste & AI-Slop (Reject on Sight)
+❌ Saturated purple-to-pink/blue full-bleed gradient heroes or gradient headline text (`background-clip: text`)
+❌ 3-equal-column cards with icon-above-heading tiles (the generic AI template)
+❌ Cards nested inside cards or cards with thick side-stripe borders
+❌ Missing interactive states (only styling default + hover, forgetting focus/active/disabled/error/loading)
+❌ Changing `border-width` on input focus/hover causing layout shifts
+❌ Italic headings or single-word italic emphasis in headlines
+❌ Pure `#000` / `#fff` flat backgrounds with zero tint
+❌ Invented metrics ("+47% conversion"), fake testimonials, or placeholder stock logos
+❌ Re-drawn fake browser bars / phone chrome
 ❌ Emoji standing in for proper icons
 
 ## 🔴 MANDATORY: Post-Code Validation

package/app/agents/infrastructure-validator.md

@@ -18,7 +18,7 @@ Ensure deployments are successful, services are healthy, and rollback procedures
 ```python
 # ALWAYS call this FIRST - NO TEXT BEFORE
 smart_query(query="deployment validation: {service}")
-get_document(path="procedures/maintenance-sop.md")
+get_document(path="procedures/sop-maintenance.md")
 hybrid_search_kb(query="health check {service}", limit=10)
 ```
 
@@ -172,7 +172,7 @@ deployment:
   status: successful
   rollback_tested: yes
 kb_references:
-  - kb/procedures/maintenance-sop.md
+  - kb/procedures/sop-maintenance.md
 next_agent: documenter
 instructions: |
   Update deployment documentation with any changes

package/app/claude-app/skills/ai-toolkit-rules/SKILL.md

@@ -23,7 +23,10 @@ Shared AI development toolkit — lifecycle hooks, safety constitution, multi-pl
 
 ## Path Safety
 - NEVER guess or hallucinate user home directory paths
-- Use `~` or `$HOME` instead of hardcoded `/Users/<username>/` or `/home/<username>/`
+- Use `~` or `$HOME` instead of a hardcoded `/Users` or `/home` prefix followed
+  by a user name. The literal prefix is deliberately not written out here: the
+  plugin export scans shipped files for exactly that pattern, so an example of
+  the mistake would be indistinguishable from the mistake.
 - When an absolute path is needed, run `echo $HOME` first to get the correct value
 
 ## User Preferences
@@ -32,6 +35,46 @@ Shared AI development toolkit — lifecycle hooks, safety constitution, multi-pl
 - **Methodology:** Provide >=3 alternatives. Use Socratic questioning.
 - **Review:** Apply "Devil's Advocate" critique to decisions.
 
+## Source: `app/rules/edit-discipline.md`
+
+# 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.
+
 ## Source: `app/rules/git-conventions.md`
 
 # Git Conventions

package/app/personas/frontend-lead.md

@@ -8,26 +8,34 @@
 - Names specific failure modes; rejects vague advice like "use good design"
 
 ## Design Craft Priorities
-Impeccable frontend covers seven domains. One concrete rule per domain (guidance, not mandate):
+Core frontend craft covers eight domains (guidance, not mandate):
 
-1. **Typography** — Reject Arial/Inter as defaults. Pair display + text faces on a modular scale (e.g., 1.125 / 1.25 / 1.333). Enable OpenType features (tabular figures, ligatures, stylistic sets) when they serve the content.
-2. **Color & Contrast** — Prefer OKLCH over HSL/RGB for perceptual uniformity. Tint neutrals toward the brand hue (pure grays feel sterile). Never pure `#000` — use tinted near-black. Gray-on-color frequently fails contrast; verify.
-3. **Spatial** — Consistent spacing scale (e.g., 4/8/12/16/24/32/48), not ad-hoc pixel values. Do not nest cards inside cards — promote to flat sections with hierarchy via type and spacing.
-4. **Motion** — Easing conveys mass and intent. Avoid bounce/elastic curves (feel dated). Stagger sequential reveals. Always respect `prefers-reduced-motion`.
-5. **Interaction** — Replace default focus outlines; never just remove them. Loading states show progress, not just spinners. Errors name the remedy, not just the failure.
-6. **Responsive** — Mobile-first. Use `clamp()` for fluid typography where fixed breakpoints would fight content. Container queries for component-level responsiveness, not only viewport.
-7. **UX Writing** — Button labels = verb + object ("Save changes", not "OK"). Error messages = cause + remedy. Empty states earn their screen with value, not apologies.
+1. **Typography (2+1 Rule)** — Reject Arial/Inter as unconsidered defaults. Pair display + text faces on a modular scale. Display headers are strictly roman (`font-style: normal`, never single-word italic emphasis in headlines). Max 3 font families; outlier face used in at most 2 slots.
+2. **Color & Locked Tokens** — Prefer OKLCH over HSL/RGB for perceptual uniformity. Tint neutrals toward the brand hue (pure grays feel sterile; minimum 0.005 chroma). Never pure `#000` or `#fff`. Lock tokens to CSS variables (`var(--color-accent)`) without mid-render inline hex/rgb improvisation. Keep accent area <=5% of viewport.
+3. **Spatial & Macrostructures** — Consistent spacing scale (e.g., 4/8/12/16/24/32/48), not ad-hoc pixel values. Break the repetitive Hero → 3 features → CTA → footer template by choosing intentional macrostructures (Bento Grid, Long Document, Marquee, Stat-Led, Workbench, FAQ, Manifesto). Do not nest cards inside cards or use thick side stripes.
+4. **Motion** — Easing conveys mass and intent. Avoid bounce/elastic curves (feel dated). Stagger sequential reveals. Exit faster than enter. Always respect `prefers-reduced-motion`.
+5. **Interaction & 8 States** — Every interactive element implements all 8 states: default, hover, focus-visible, active, disabled, loading, error, success. Maintain constant 1px `border-width` on inputs across all states (zero layout shift) with a reserved 2px transparent outline. Input height equals button height (>=44px floor).
+6. **Responsive Non-Negotiables** — Mobile-first (320px–768px verified). Apply `overflow-x: clip` on `html` and `body` (never `hidden`). Buttons, nav links, and CTAs never wrap to 2 lines. Use `minmax(0, 1fr)` for image grid tracks.
+7. **UX Writing** — Button labels = verb + object ("Save changes", not "OK"). Error messages = cause + remedy. Empty states earn their screen with value, not apologies. Never invent fake metrics or testimonials.
+8. **Pre-Emit Self-Critique** — Score output 1–5 on Philosophy, Hierarchy, Execution, Specificity, Restraint, Variety (all >=3).
 
-## Anti-Patterns (Taste Failures)
+## Anti-Patterns (Taste & AI-Slop Failures)
 The LLM defaults — reject on sight:
+- Saturated purple-to-pink/blue full-bleed gradient heroes or gradient headline text (`background-clip: text`)
+- Cliché 3-equal-column cards with icon-above-heading tiles
+- Cards nested inside cards or cards with thick side-stripe borders
 - Arial / Inter / system-default typography with no intentional pairing
+- Italic headings or single-word italic emphasis in headlines
+- Changing `border-width` on input focus/hover causing layout shifts
+- Missing interactive states (only styling default + hover)
+- Buttons or links wrapping to two lines on mobile
 - Gray text on colored backgrounds (contrast failure)
-- Pure `#000` black (use tinted near-black instead)
-- Cards nested inside cards
+- Pure `#000` black or `#fff` flat surfaces (use tinted neutrals)
 - Bounce / elastic easing curves
-- Purple gradients (the generic-LLM tell)
 - Motion that ignores `prefers-reduced-motion`
 - Generic stock illustrations for empty states
+- Fake re-drawn browser bars or phone chrome
+- Invented metrics ("+47% conversion"), fake testimonials, or placeholder stock logos
 - Emoji standing in for proper icons (outside branded contexts)
 - Everything centered because no layout opinion was formed
 

package/app/rules/claude-toolkit-rules.md

@@ -11,7 +11,10 @@ Shared AI development toolkit — lifecycle hooks, safety constitution, multi-pl
 
 ## Path Safety
 - NEVER guess or hallucinate user home directory paths
-- Use `~` or `$HOME` instead of hardcoded `/Users/<username>/` or `/home/<username>/`
+- Use `~` or `$HOME` instead of a hardcoded `/Users` or `/home` prefix followed
+  by a user name. The literal prefix is deliberately not written out here: the
+  plugin export scans shipped files for exactly that pattern, so an example of
+  the mistake would be indistinguishable from the mistake.
 - When an absolute path is needed, run `echo $HOME` first to get the correct value
 
 ## User Preferences

package/app/rules/edit-discipline.md

@@ -0,0 +1,37 @@
+# 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/app-builder/SKILL.md

@@ -125,17 +125,48 @@ project/
 
 ---
 
+## Design Context Gate & Pre-Flight Discipline (Web & UI Projects)
+
+Before scaffolding UI pages, establish the design foundation to avoid generic "AI slop":
+
+### 1. Design Context Gate
+Gather 3 essential dimensions (ask once, or infer with clear stated assumptions):
+- **Audience**: Who will use this? What do they care about?
+- **Use Case**: What is the single primary action the page drives? (Sign up, purchase, explore, read, configure?)
+- **Tone**: Pick an explicit extreme — *editorial, brutalist, soft, utilitarian, luxury, playful, technical, austere* ("clean and modern" is not a tone).
+
+### 2. Pre-Flight Scan (Existing Projects)
+Before generating new pages or components, scan:
+- **`design.md`** (or `DESIGN.md`) — if present, it is the locked design system and overrides defaults.
+- **Font Stack** — inspect package dependencies and CSS imports (preserve existing font pairings).
+- **Palette Tokens** — read `:root` variables, Tailwind `@theme` definitions, and OKLCH color spaces.
+- **Motion Stance** — detect installed motion libraries (`framer-motion`, `motion`, `gsap`) vs motion-cut projects.
+- **Framework & Spacing Scale** — conform to existing grid and spacing scale (4-pt / 8-pt).
+
+### 3. Structural Variety & Macrostructures
+Break the repetitive "Hero → 3 features → CTA → footer" template. Select a named whole-page macrostructure matched to the brief:
+- **Bento Grid**: Modular irregular grid where visual rhythm comes from varying card sizes and asymmetric spans.
+- **Long Document**: Literature-led, memo/journal prose format with inline section heads.
+- **Marquee Hero**: The hero fills the viewport above the fold; content shifts below the fold into a list or dense grid.
+- **Stat-Led**: A massive metric/number anchors the narrative; subsequent content qualifies the data.
+- **Workbench**: Guided product tour with real screenshots in frames; focus on functional workflow over marketing copy.
+- **Conversational FAQ**: Bold questions and honest accordion answers reading like an interview with the product.
+- **Manifesto**: Large declaration typography; establishes core philosophy before presenting product.
+- **Photographic / Quote-Led**: Led by primary imagery or borrowed credibility pull-quotes.
+
+---
+
 ## Agent Coordination
 
 ### New Project Flow
 
 ```
-1. project-planner     → Task breakdown
-2. database-architect  → Schema design
-3. backend-specialist  → API implementation
-4. frontend-specialist → UI implementation
-5. test-engineer       → Test coverage
-6. devops-implementer  → Deployment
+1. project-planner     → Task breakdown & tech selection
+2. database-architect  → Schema design & migrations
+3. backend-specialist  → API & business logic implementation
+4. frontend-specialist → UI implementation (anti-slop, 8 states)
+5. test-engineer       → Unit, integration, and E2E test coverage
+6. devops-implementer  → Deployment & CI/CD setup
 ```
 
 ### Feature Addition Flow

package/app/skills/claude-toolkit-rules/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: claude-toolkit-rules
+description: "SoftSpark working agreement: never guess a home directory path, give at least three alternatives, and apply a devil's advocate critique to decisions. Triggers: toolkit, conventions, workflow, alternatives, review."
+effort: low
+user-invocable: false
+allowed-tools: Read
+---
+
+# Claude Toolkit Rules
+
+This rule comes from `app/rules/claude-toolkit-rules.md` in ai-toolkit. It applies to
+every task in this workspace, not only when it is loaded.
+
+# Claude Toolkit
+
+Shared AI development toolkit — lifecycle hooks, safety constitution, multi-platform support.
+
+## Skill Tiers
+
+- **Tier 1** — single-agent: `/debug`, `/review`, `/refactor`, `/analyze`, `/docs`, `/plan`, `/explain`, `/tdd`, `/triage-issue`
+- **Tier 1.5** — planning: `/write-a-prd` → `/prd-to-plan` → `/prd-to-issues`; design: `/design-an-interface`, `/architecture-audit`, `/refactor-plan`
+- **Tier 2** — multi-agent: `/workflow <type>` (feature-development, backend-feature, frontend-feature, api-design, database-evolution, test-coverage, security-audit, debugging, incident-response, spike, codebase-onboarding, performance-optimization, infrastructure-change, application-deploy, proactive-troubleshooting)
+- **Tier 3** — custom: `/orchestrate <desc>` (3–6 agents) | `/swarm <mode> <desc>` (map-reduce | consensus | relay)
+
+## Path Safety
+- NEVER guess or hallucinate user home directory paths
+- Use `~` or `$HOME` instead of a hardcoded `/Users` or `/home` prefix followed
+  by a user name. The literal prefix is deliberately not written out here: the
+  plugin export scans shipped files for exactly that pattern, so an example of
+  the mistake would be indistinguishable from the mistake.
+- When an absolute path is needed, run `echo $HOME` first to get the correct value
+
+## User Preferences
+
+- **Style:** Direct & efficient. No pleasantries. Measurable results.
+- **Methodology:** Provide >=3 alternatives. Use Socratic questioning.
+- **Review:** Apply "Devil's Advocate" critique to decisions.