@kennethsolomon/shipkit 3.19.0 → 3.20.0

package/README.md

@@ -315,7 +315,7 @@ Agents are specialized sub-agents deployed to `.claude/agents/` by `/sk:setup-cl
 | **1** (parallel) | lint + `security-reviewer` + `performance-optimizer` | Independent — run simultaneously |
 | **2** | tests (100% coverage on new code) | Needs lint fixes first |
 | **3** | `code-reviewer` (7-dimension) | Needs test confirmation |
-| **4** | E2E (Playwright or agent-browser) | Uses scenarios from `qa-engineer` |
+| **4** | E2E Tests (Playwright or agent-browser) | Uses scenarios from `qa-engineer` |
 
 Each gate auto-fixes and re-runs until clean. One squash commit per gate pass. If a gate fails 3 times it stops and asks for help. Pre-existing issues are logged to `tasks/tech-debt.md` — never fixed inline.
 
@@ -370,7 +370,7 @@ Installed optionally by `/sk:setup-claude` and `/sk:setup-optimizer`.
 | Server | What it does | Best for |
 |---|---|---|
 | **Sequential Thinking** | Structured reasoning scratchpad — Claude thinks through hard problems step-by-step without cluttering the conversation | `/sk:brainstorm`, `/sk:debug`, `/sk:review` |
-| **Context7** | Fetches current, version-accurate docs for libraries you're using — no stale API suggestions | React 19, Next.js 15, Tailwind v4, shadcn/ui |
+| **context7** | Fetches current, version-accurate docs for libraries you're using — no stale API suggestions | React 19, Next.js 15, Tailwind v4, shadcn/ui |
 | **ccstatusline** | Persistent statusline: context window %, model, git branch, current task | Every session |
 
 ---
@@ -431,12 +431,34 @@ Use these anytime outside of the main workflow.
 
 | Area | Supported |
 |---|---|
-| **Frameworks** | Laravel, Next.js, Nuxt, React, Vue, Node.js |
+| **Frameworks** | Laravel, Next.js, Nuxt, React, Vue, Node.js, Go, Rust, Python, Rails |
 | **Linters** | Pint, ESLint, PHPStan, Rector, Prettier, Biome |
 | **Test runners** | Pest, PHPUnit, Jest, Vitest, Playwright |
 | **Schema / ORM** | Prisma, Drizzle, Eloquent, SQLAlchemy, ActiveRecord |
 | **Release** | npm, Composer, iOS (App Store), Android (Play Store) |
 
+### Stack-Aware Skill Filtering
+
+When you run `/sk:setup-claude`, ShipKit auto-detects your project's stack and installs only the skills, agents, and rules relevant to that stack at the project level (`.claude/skills/`, `.claude/agents/`, `.claude/rules/`).
+
+For example, a **Next.js** project gets web skills (frontend-design, accessibility, seo-audit) but not Laravel skills. A **mobile** project skips Playwright E2E and SEO audits.
+
+Detection is automatic — no config needed. To override:
+
+```json
+// .shipkit/config.json
+{
+  "skills": {
+    "extra": ["sk:schema-migrate"],   // force-add skills
+    "disabled": ["sk:website"]        // force-remove skills
+  }
+}
+```
+
+Run `/sk:setup-optimizer` to re-detect and sync when your stack changes (e.g., adding a database ORM later). ShipKit also suggests activating relevant skills when it detects code changes in disabled skill domains.
+
+See [skill-profiles.md](skills/sk:setup-claude/references/skill-profiles.md) for the full mapping of skills/agents/rules per stack.
+
 ---
 
 ## All Commands

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kennethsolomon/shipkit",
-  "version": "3.19.0",
+  "version": "3.20.0",
   "description": "A structured workflow toolkit for Claude Code.",
   "keywords": [
     "claude",

package/skills/sk:brainstorming/SKILL.md

@@ -6,132 +6,35 @@ allowed-tools: Read, Write, Glob, Grep, Bash, Agent
 
 # Brainstorming Ideas Into Designs
 
-## Overview
-
-Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
-
-Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
-
 <HARD-GATE>
-Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
+Do NOT invoke any implementation skill, write any code, or scaffold until the user approves the design. Every project — no matter how simple — goes through this process. The design can be short, but it MUST be presented and approved.
 </HARD-GATE>
 
-## Anti-Pattern: "This Is Too Simple To Need A Design"
-
-Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
-
-## Checklist
-
-You MUST create a task for each of these items and complete them in order:
-
-1. **Explore project context** — read `tasks/findings.md` and `tasks/lessons.md` if they exist, then check files, docs, recent commits
-2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
-3. **Propose 2-3 approaches** — with trade-offs and your recommendation
-4. **Present design** — in sections scaled to their complexity, get user approval after each section
-5. **Write findings** — Save the agreed-upon direction to `tasks/findings.md`:
-   - Problem statement
-   - Key decisions made
-   - Chosen approach + rationale
-   - Open questions (if any remain)
-   Additionally, **append** an ADR entry to `docs/decisions.md` (see "Decisions Log" section below).
-   (Optionally also write a full design doc to docs/plans/YYYY-MM-DD-<topic>-design.md)
-6. **Transition to implementation** — invoke `/sk:write-plan` skill to create implementation plan
-
-## Process Flow
-
-```dot
-digraph brainstorming {
-    "Explore project context" [shape=box];
-    "Ask clarifying questions" [shape=box];
-    "Propose 2-3 approaches" [shape=box];
-    "Present design sections" [shape=box];
-    "User approves design?" [shape=diamond];
-    "Write design doc" [shape=box];
-    "Invoke `/sk:write-plan` skill" [shape=doublecircle];
-
-    "Explore project context" -> "Ask clarifying questions";
-    "Ask clarifying questions" -> "Propose 2-3 approaches";
-    "Propose 2-3 approaches" -> "Present design sections";
-    "Present design sections" -> "User approves design?";
-    "User approves design?" -> "Present design sections" [label="no, revise"];
-    "User approves design?" -> "Write design doc" [label="yes"];
-    "Write design doc" -> "Invoke `/sk:write-plan` skill";
-}
-```
-
-**The terminal state is invoking `/sk:write-plan`.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is `/sk:write-plan`.
-
-## The Process
-
-**Understanding the idea:**
-- If `tasks/findings.md` exists and has content, read it in full. Summarize the prior
-  decisions to the user and ask: extend, revise, or start fresh? Do not re-explore
-  what is already decided unless the user asks.
-- If `tasks/lessons.md` exists, read it in full. Apply every active lesson as a design
-  constraint throughout the brainstorm — particularly prevention rules when proposing approaches.
-- Check out the current project state first (files, docs, recent commits)
-- Ask questions one at a time to refine the idea
-- Prefer multiple choice questions when possible, but open-ended is fine too
-- Only one question per message - if a topic needs more exploration, break it into multiple questions
-- Focus on understanding: purpose, constraints, success criteria
-
-**Architecture Assessment (before proposing approaches — complex tasks only):**
-
-After exploring the project context, check if this task is architecturally complex:
-- Does it span multiple systems, services, or bounded contexts?
-- Does it require decisions about data modeling, API contracts, or system boundaries?
-- Does it involve 3+ major components being added or changed?
-- Does it touch auth, billing, or other sensitive infrastructure?
-
-If YES to any of the above, invoke the **`architect` agent** before proposing approaches:
-> Task: "Read tasks/findings.md, tasks/lessons.md, tasks/tech-debt.md, and explore the relevant code areas. Propose 2-3 architecturally sound approaches for [task description] with explicit trade-offs. Read-only — no code."
+## Steps
 
-Incorporate the architect's recommendations into step 3 (propose approaches). If the task is simple and narrow, skip this step.
+1. **Explore context** — read `tasks/findings.md` and `tasks/lessons.md` if they exist. Summarize prior decisions; ask extend/revise/fresh? Do not re-explore what is already decided. Apply every active lesson as a design constraint. Check files, docs, recent commits.
+2. **Ask clarifying questions** — one per message, prefer multiple choice. Focus on purpose, constraints, success criteria.
+3. **Architecture assessment** (complex tasks only) — if task spans multiple systems, requires data modeling/API contracts, 3+ components, or touches auth/billing: invoke the `architect` agent with: "Read tasks/findings.md, tasks/lessons.md, tasks/tech-debt.md, explore relevant code. Propose 2-3 architecturally sound approaches for [task] with trade-offs. Read-only." Incorporate into step 5.
+4. **Search-First Research** — before proposing approaches:
 
-**Search-First Research (before proposing approaches):**
-Before proposing custom solutions, check if the problem is already solved:
-1. **Grep codebase** — does similar functionality already exist in this repo?
-2. **Check package registries** — is there a well-maintained package for this? (npm, PyPI, Packagist, crates.io)
-3. **Check existing skills** — does a ShipKit skill or MCP server already handle this?
+   | Check | Action | Decision |
+   |-------|--------|----------|
+   | Grep codebase | Similar functionality exists? | **Adopt** (90%+) · **Extend** (60-90%) · **Build** (<60%) |
+   | Package registries | Well-maintained package? | Include as approach option |
+   | Existing skills/MCPs | ShipKit skill handles this? | Include as approach option |
 
-Decision matrix:
-- **Adopt** — existing solution covers 90%+ of requirements → use it directly
-- **Extend** — existing solution covers 60-90% → extend or wrap it
-- **Build custom** — nothing suitable exists → build from scratch (informed by what was found)
-
-If a suitable package or existing solution is found, include it as one of the approaches.
-
-**Exploring approaches:**
-- Propose 2-3 different approaches with trade-offs
-- Present options conversationally with your recommendation and reasoning
-- Lead with your recommended option and explain why
-
-**Presenting the design:**
-- Once you believe you understand what you're building, present the design
-- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
-- Ask after each section whether it looks right so far
-- Cover: architecture, components, data flow, error handling, testing
-- Be ready to go back and clarify if something doesn't make sense
-
-## After the Design
-
-**Documentation:**
-- Write the findings to `tasks/findings.md` (required — captures problem, decisions, approach, rationale)
-- Append an ADR entry to `docs/decisions.md` (required — see "Decisions Log" section below)
-- Optionally: Create a full design doc at `docs/plans/YYYY-MM-DD-<topic>-design.md` for complex projects
-- Commit the findings, decisions log entry, and any design document to git
-
-**Implementation:**
-- Invoke the `/sk:write-plan` skill to create a detailed implementation plan
-- Do NOT invoke any other skill. `/sk:write-plan` is the next step.
+5. **Propose 2-3 approaches** — with trade-offs; lead with recommendation and reasoning.
+6. **Present design** — scale each section to complexity. Ask after each section. Cover: architecture, components, data flow, error handling, testing.
+7. **Write findings** — save to `tasks/findings.md` (problem statement, decisions, approach + rationale, open questions). Append ADR to `docs/decisions.md` (see below). Optionally: `docs/plans/YYYY-MM-DD-<topic>-design.md`. Commit all.
+8. **Transition** — invoke `/sk:write-plan`. Do NOT invoke any other skill.
 
 ## Decisions Log
 
-After writing findings to `tasks/findings.md`, also **append** an Architecture Decision Record (ADR) entry to `docs/decisions.md`. This file is **cumulative and append-only** — never overwrite or remove existing entries.
+After writing findings, **append** an ADR entry to `docs/decisions.md`. This file is **cumulative and append-only** — never overwrite or remove existing entries.
 
 ### If `docs/decisions.md` does not exist
 
-Create it with this header before the first entry:
+Create it with this header first:
 
 ```markdown
 # Architecture Decision Records
@@ -141,8 +44,6 @@ A cumulative log of key design decisions made across features. Append-only — n
 
 ### ADR Entry Format
 
-Append this template for each brainstorm decision:
-
 ```markdown
 ## [YYYY-MM-DD] [Feature/Task Name]
 
@@ -155,19 +56,9 @@ Append this template for each brainstorm decision:
 
 ### Rules
 
-- **Append-only** — never edit or delete existing entries in `docs/decisions.md`
+- **Append-only** — never edit or delete existing entries
 - **One entry per brainstorm** — each completed brainstorm adds exactly one ADR entry
-- **Use absolute dates** — always `YYYY-MM-DD`, never relative dates
-- Entries accumulate across features — this is a project-level historical record
-
-## Key Principles
-
-- **One question at a time** - Don't overwhelm with multiple questions
-- **Multiple choice preferred** - Easier to answer than open-ended when possible
-- **YAGNI ruthlessly** - Remove unnecessary features from all designs
-- **Explore alternatives** - Always propose 2-3 approaches before settling
-- **Incremental validation** - Present design, get approval before moving on
-- **Be flexible** - Go back and clarify when something doesn't make sense
+- **Absolute dates only** — always `YYYY-MM-DD`
 
 ---
 

package/skills/sk:debug/SKILL.md

@@ -5,22 +5,18 @@ description: "Structured bug investigation: reproduce, isolate, hypothesize, ver
 
 # Structured Debugging Workflow
 
-## Overview
-
-Systematic bug investigation that follows a disciplined process: reproduce, isolate, hypothesize, verify, fix. Every finding is logged to prevent repeated work and build project knowledge.
-
 <HARD-GATE>
 Do NOT jump to fixing code before you understand the bug. No code changes until a hypothesis is CONFIRMED through systematic investigation. Random fixes waste time and mask root causes.
 </HARD-GATE>
 
-## Anti-Patterns — Do NOT Do These
+## Anti-Patterns
 
-- **Changing code before understanding** — Read and analyze first
-- **Trying random fixes** — "Maybe if I change this..." is not debugging
-- **Ignoring stack traces** — They tell you exactly where to look
-- **Fixing symptoms, not causes** — A try/catch around a crash is not a fix
-- **Skipping reproduction** — If you can't reproduce it, you can't verify the fix
-- **Debugging in production** — Reproduce locally first
+- Changing code before understanding — read and analyze first
+- Trying random fixes — "maybe if I change this..." is not debugging
+- Ignoring stack traces — they tell you exactly where to look
+- Fixing symptoms, not causes — a try/catch around a crash is not a fix
+- Skipping reproduction — if you can't reproduce it, you can't verify the fix
+- Debugging in production — reproduce locally first
 
 ## Allowed Tools
 
@@ -49,36 +45,32 @@ If `debugger` agent hits a 3-strike failure, fall back to manual steps below.
 
 ## Steps
 
-You MUST complete these steps in order:
+Complete these steps in order:
 
 ### 1. Gather Information
 
 Parse what the user tells you:
 
-- **Error message**: Extract the exact error text
-- **Stack trace**: Identify the file, line, and call chain
-- **Expected vs actual behavior**: What should happen vs what does happen
-- **Trigger conditions**: When does it happen? Always, sometimes, under specific conditions?
-- **Recent changes**: Did it work before? What changed?
+- **Error message** — exact error text
+- **Stack trace** — file, line, and call chain
+- **Expected vs actual** — what should happen vs what does happen
+- **Trigger conditions** — always, sometimes, under specific conditions?
+- **Recent changes** — did it work before? what changed?
 
-If the user provides insufficient information, ask specific questions — don't guess.
+If insufficient information, ask specific questions — don't guess.
 
 ### 2. Read Project Context
 
-Check for existing knowledge:
-
 ```
-CLAUDE.md                  — Project conventions, known issues
-tasks/findings.md          — Previous debugging sessions, known bugs
-tasks/lessons.md           — Patterns that caused issues before
-tasks/progress.md          — Recent work log and error log
+CLAUDE.md               — project conventions, known issues
+tasks/findings.md       — previous debugging sessions, known bugs
+tasks/lessons.md        — patterns that caused issues before
+tasks/progress.md       — recent work log and error log
 ```
 
-**If `tasks/lessons.md` exists, read it in full.** For each active lesson, apply its prevention rule to your investigation — treat lessons as standing constraints, not just history. For example: if a lesson says "always check env vars before checking application code", do that first.
+**If `tasks/lessons.md` exists, read it in full.** For each active lesson, apply its prevention rule — treat lessons as standing constraints, not just history.
 
-**If `tasks/progress.md` exists**, scan the Error Log for failures near the bug's reported time — they often share a root cause with the current bug.
-
-Check if this bug (or something similar) has been investigated before.
+**If `tasks/progress.md` exists**, scan the Error Log for failures near the bug's reported time — they often share a root cause.
 
 ### 3. Check Recent Changes
 
@@ -91,55 +83,19 @@ Correlate the bug timeline with recent changes. Did the bug start after a specif
 
 ### 4. Reproduce the Bug
 
-**Determine the bug surface first:**
-
-#### A. Server / CLI / Non-Browser Bug
-
-Run the specific command, test, or action that triggers the bug. Capture the full output.
-
-```bash
-# Run the failing test/command
-[specific command that triggers the bug]
-```
+**A. Server / CLI / Non-Browser Bug** — run the specific command, test, or action that triggers the bug. Capture the full output.
 
-#### B. Browser / UI Bug
+**B. Browser / UI Bug** — use the Playwright MCP plugin:
 
-If the bug is visual, involves JavaScript errors, or requires a browser to reproduce, use the Playwright MCP plugin instead of Bash:
+1. Navigate: `mcp__plugin_playwright_playwright__browser_navigate({ url: "http://localhost:[PORT]/[path]" })`
+2. JS errors: `mcp__plugin_playwright_playwright__browser_console_messages({ level: "error" })`
+3. Network failures: `mcp__plugin_playwright_playwright__browser_network_requests({ includeStatic: false })`
+4. Screenshot: `mcp__plugin_playwright_playwright__browser_take_screenshot({ type: "png" })`
+5. DOM snapshot: `mcp__plugin_playwright_playwright__browser_snapshot()`
 
-1. **Navigate to the page**:
-   ```
-   mcp__plugin_playwright_playwright__browser_navigate({ url: "http://localhost:[PORT]/[path]" })
-   ```
+Use console errors and network failures as primary evidence in Step 6.
 
-2. **Capture JS errors** (most useful for runtime exceptions):
-   ```
-   mcp__plugin_playwright_playwright__browser_console_messages({ level: "error" })
-   ```
-
-3. **Inspect failed network requests** (useful for API/fetch failures):
-   ```
-   mcp__plugin_playwright_playwright__browser_network_requests({ includeStatic: false })
-   ```
-
-4. **Screenshot the visual state** to document what the bug looks like:
-   ```
-   mcp__plugin_playwright_playwright__browser_take_screenshot({ type: "png" })
-   ```
-
-5. **Capture accessibility snapshot** for structural/DOM-level inspection:
-   ```
-   mcp__plugin_playwright_playwright__browser_snapshot()
-   ```
-
-Use the console errors and network failures as primary evidence in Step 6 (Hypotheses).
-
----
-
-If you cannot reproduce (either path):
-- Check environment differences
-- Check for race conditions or timing issues
-- Ask the user for exact reproduction steps
-- Do NOT proceed to fixing without reproduction
+If you cannot reproduce (either path): check environment differences, check for race conditions, ask for exact reproduction steps. Do NOT proceed to fixing without reproduction.
 
 ### 5. Isolate the Problem
 
@@ -147,20 +103,12 @@ Read the relevant code, tracing the execution path:
 
 1. Start at the error location (from stack trace)
 2. Trace backward through the call chain
-3. Identify the inputs and state at each step
+3. Identify inputs and state at each step
 4. Find where actual behavior diverges from expected
 
-Use targeted searches:
-
-```bash
-# Find related code
-grep -r "functionName" src/
-grep -r "ERROR_CODE" .
-```
-
 ### 6. Form Hypotheses
 
-Generate 2-3 ranked hypotheses based on your investigation:
+Generate 2-3 ranked hypotheses and log to `tasks/findings.md`:
 
 ```markdown
 ## Hypotheses
@@ -178,28 +126,21 @@ Generate 2-3 ranked hypotheses based on your investigation:
 - Test: how to confirm or reject
 ```
 
-Log these to `tasks/findings.md` under a dated heading.
-
 ### 7. Test Hypotheses Systematically
 
-For each hypothesis, starting with the most likely:
+For each hypothesis (most likely first):
 
 1. Design a specific diagnostic step (not a fix)
 2. Execute it and observe the result
-3. Update the hypothesis status: **CONFIRMED** / **REJECTED** / **PARTIAL**
+3. Update status: **CONFIRMED** / **REJECTED** / **PARTIAL**
 
-Diagnostic steps might include:
-- Adding a temporary log statement to check a value
-- Running with different inputs
-- Checking database state
-- Inspecting environment variables
-- Running a minimal reproduction
+Diagnostic steps: add a temporary log statement, run with different inputs, check database state, inspect environment variables, run a minimal reproduction.
 
 **Do NOT change production code during this phase.** Diagnostic changes only.
 
 ### 8. Update Findings
 
-Update `tasks/findings.md` with results:
+Update `tasks/findings.md`:
 
 ```markdown
 ### [Date] Bug: [brief description]
@@ -212,24 +153,12 @@ Update `tasks/findings.md` with results:
 
 ### 9. Propose Minimal Fix
 
-Once a hypothesis is confirmed, propose the smallest possible fix:
+Once a hypothesis is confirmed, propose the smallest possible fix — change as few lines as possible, don't refactor surrounding code, don't add "while I'm here" improvements. Explain why the fix addresses the root cause.
 
-- Change as few lines as possible
-- Don't refactor surrounding code
-- Don't add "while I'm here" improvements
-- Explain why this fix addresses the root cause
-
-Present the fix and **wait for user approval** before applying.
+**Wait for user approval before applying.**
 
 ### 10. Verify Fix + Regression Check
 
-After the fix is applied:
-
-1. Re-run the original reproduction steps — bug should be gone
-2. Run the full test suite — no new failures
-3. If there was a related test, confirm it passes
-4. If there was no test, suggest writing one (reference `/sk:write-tests`)
-
 ```bash
 # Verify the specific fix
 [reproduction command]
@@ -238,12 +167,16 @@ After the fix is applied:
 [test suite command]
 ```
 
+1. Re-run the original reproduction steps — bug should be gone
+2. Run the full test suite — no new failures
+3. If there was a related test, confirm it passes
+4. If there was no test, suggest writing one (reference `/sk:write-tests`)
+
 ### 11. Document
 
-**Root cause in `tasks/findings.md`:**
-Update the entry from step 8 with the final resolution.
+**`tasks/findings.md`** — update the entry from step 8 with the final resolution.
 
-**Lesson in `tasks/lessons.md`** (only if the pattern could recur):
+**`tasks/lessons.md`** (only if the pattern could recur):
 
 ```markdown
 ### [Date] Lesson: [brief title]