@kennethsolomon/shipkit 3.0.6 → 3.1.0

package/README.md

@@ -62,7 +62,7 @@ npm install -g @kennethsolomon/shipkit && shipkit
 
 ShipKit installs slash commands and skills into `~/.claude/`. Each command is a focused instruction set that Claude follows — no magic, just structured prompts that enforce quality gates.
 
-The workflow is linear: **Brainstorm → Plan → Branch → Test → Implement → Lint → Security → Review → Ship.**
+The workflow is linear: **Read → Explore → Design → Accessibility → Plan → Branch → Migrate → Write Tests → Implement → Lint → Verify Tests → Security → Performance → Review → E2E Tests → Finish → Sync Features**
 
 Every gate must pass before the next step. If lint fails, fix it. If tests don't cover new code, write them. Security issues block the PR. This isn't optional — it's the whole point.
 
@@ -76,7 +76,7 @@ Every gate must pass before the next step. If lint fails, fix it. If tests don't
 
 ```
 Brainstorm → Plan → Branch → [Schema] → Write Tests → Implement → Commit
-  → Lint ✓ → Test ✓ → Security ✓ → Review ✓ → Update Task → Finish
+  → Lint ✓ → Test ✓ → Security ✓ → Review ✓ → E2E ✓ → Update Task → Finish → Sync Features
 ```
 
 | # | Command | Purpose |
@@ -84,26 +84,32 @@ Brainstorm → Plan → Branch → [Schema] → Write Tests → Implement → Co
 | 1 | read `tasks/todo.md` | Pick the next task |
 | 2 | read `tasks/lessons.md` | Review past corrections |
 | 3 | `/sk:brainstorm` | Clarify requirements — no code |
-| 4 | `/sk:frontend-design` | UI design spec *(skip if backend-only)* |
-| 5 | `/sk:api-design` | API contracts *(skip if no new endpoints)* |
-| 6 | `/sk:accessibility` | WCAG 2.1 AA audit on design *(skip if no frontend)* |
-| 7 | `/sk:write-plan` | Write plan to `tasks/todo.md` |
-| 8 | `/sk:branch` | Create branch from current task |
-| 9 | `/sk:schema-migrate` | Schema change analysis *(skip if no DB changes)* |
-| 10 | `/sk:write-tests` | TDD red: write failing tests first |
-| 11 | `/sk:execute-plan` | TDD green: make tests pass |
-| 12 | `/sk:smart-commit` | Conventional commit |
-| 13 | **`/sk:lint`** | **GATE** — all linters must pass |
-| 14 | `/sk:smart-commit` | Auto-skip if already clean |
-| 15 | **`/sk:test`** | **GATE** — 100% coverage on new code |
-| 16 | `/sk:smart-commit` | Auto-skip if already clean |
-| 17 | **`/sk:security-check`** | **GATE** — 0 issues |
-| 18 | `/sk:smart-commit` | Auto-skip if already clean |
-| 19 | **`/sk:review`** | **GATE** — 0 issues including nitpicks |
-| 20 | `/sk:smart-commit` | Auto-skip if already clean |
-| 21 | `/sk:update-task` | Mark done, log completion |
-| 22 | `/sk:finish-feature` | Changelog + PR |
-| 23 | `/sk:release` | Version bump + tag *(optional)* |
+| 4 | `/sk:frontend-design` or `/sk:api-design` | Design spec *(skip if not needed)*. Frontend: add `--pencil` for Pencil visual mockup. API: REST/GraphQL contracts. |
+| 5 | `/sk:accessibility` | WCAG 2.1 AA audit on design *(skip if no frontend)* |
+| 6 | `/sk:write-plan` | Write plan to `tasks/todo.md` |
+| 7 | `/sk:branch` | Create branch from current task |
+| 8 | `/sk:schema-migrate` | Schema change analysis *(skip if no DB changes)* |
+| 9 | `/sk:write-tests` | TDD red: write failing tests first |
+| 10 | `/sk:execute-plan` | TDD green: make tests pass |
+| 11 | `/sk:smart-commit` | Conventional commit |
+| 12 | **`/sk:lint`** | **GATE** — Lint + Dep Audit — all linters must pass |
+| 13 | `/sk:smart-commit` | Auto-skip if already clean |
+| 14 | **`/sk:test`** | **GATE** — 100% coverage on new code |
+| 15 | `/sk:smart-commit` | Auto-skip if already clean |
+| 16 | **`/sk:security-check`** | **GATE** — 0 issues |
+| 17 | `/sk:smart-commit` | Auto-skip if already clean |
+| 18 | **`/sk:perf`** | **GATE** *(optional)* — critical/high findings = 0 |
+| 19 | `/sk:smart-commit` | Auto-skip if already clean |
+| 20 | **`/sk:review`** | **GATE** — Review + Simplify — 0 issues including nitpicks |
+| 21 | `/sk:smart-commit` | Auto-skip if already clean |
+| 22 | **`/sk:e2e`** | **GATE** — E2E Tests — all end-to-end tests must pass |
+| 23 | `/sk:smart-commit` | Auto-skip if already clean |
+| 24 | `/sk:update-task` | Mark done, log completion |
+| 25 | `/sk:finish-feature` | Changelog + PR |
+| 26 | `/sk:features` | Sync Features — update docs/features/ specs *(required)* |
+| 27 | `/sk:release` | Version bump + tag *(optional)* |
+
+> **Fix & Retest Protocol:** All code-producing gates (Lint, Test, Security, Performance, Review, E2E) apply the Fix & Retest Protocol: logic changes require updating unit tests before committing the fix. Fix immediately, then re-run — never ask the user to re-run.
 
 ### Bug Fix Flow
 
@@ -118,8 +124,8 @@ Debug → Plan → Branch → Write Tests → Implement → Lint ✓ → Test
 | 3 | `/sk:branch` | Create branch |
 | 4 | `/sk:write-tests` | Reproduce the bug in a test |
 | 5 | `/sk:execute-plan` | Fix — make the test pass |
-| 6–9 | lint → test → security → review | Quality gates |
-| 10 | `/sk:finish-feature` | Changelog + PR |
+| 6–10 | `/sk:lint` → `/sk:test` → `/sk:security-check` → `/sk:review` → `/sk:e2e` | Quality gates |
+| 11 | `/sk:finish-feature` | Changelog + PR |
 
 ### Hotfix Flow
 
@@ -170,7 +176,7 @@ Requirement changes → /sk:change → re-enter at correct step
 | Command | Description |
 |---------|-------------|
 | `/sk:brainstorm` | Explore requirements and design before writing any code |
-| `/sk:frontend-design` | Create UI design specs and mockups |
+| `/sk:frontend-design` | Create UI design specs and mockups. After the design summary, it asks if you want a Pencil visual mockup. Use `--pencil` flag to jump directly to the Pencil phase *(requires Pencil app + MCP)* |
 | `/sk:api-design` | Design REST or GraphQL API contracts |
 | `/sk:accessibility` | WCAG 2.1 AA audit on design or existing frontend |
 | `/sk:write-plan` | Write a decision-complete plan to `tasks/todo.md` |

package/commands/sk/help.md

@@ -72,7 +72,7 @@ Requirements change mid-workflow? Run `/sk:change` — it classifies the scope a
 | `/sk:execute-plan` | Implement plan in batches |
 | `/sk:features` | Sync docs/sk:features/ specs with codebase |
 | `/sk:finish-feature` | Changelog + PR creation |
-| `/sk:frontend-design` | UI mockup + design spec before implementation |
+| `/sk:frontend-design` | UI mockup + design spec before implementation. Add `--pencil` to also generate a Pencil visual mockup (requires Pencil app + MCP) |
 | `/sk:hotfix` | Emergency fix workflow (skips design/TDD) |
 | `/sk:laravel-init` | Configure existing Laravel project |
 | `/sk:laravel-new` | Scaffold new Laravel project |

package/commands/sk/security-check.md

@@ -171,6 +171,20 @@ If there are Critical or High findings:
 
 **Do not auto-fix.** The user decides what to address.
 
+### Fix & Retest Protocol
+
+When applying a fix, classify it before committing:
+
+**a. Config/hardening change** (adding security header, fixing CORS config, adding rate limit, sanitizing output without changing logic) → commit and re-run `/sk:security-check`. No test update needed.
+
+**b. Logic change** (new input validation branch, modified query parameterization, changed auth check, refactored data handling) → trigger protocol:
+1. Update or add failing unit tests for the new secure behavior
+2. Re-run `/sk:test` — must pass at 100% coverage
+3. Commit (tests + fix together in one commit)
+4. Re-run `/sk:security-check` from scratch
+
+**Why:** Security fixes often change logic (e.g., adding parameterized queries, sanitizing inputs). Tests must cover the new secure behavior, not just the old vulnerable path.
+
 ---
 
 ## Model Routing

package/package.json

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

package/skills/sk:e2e/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: sk:e2e
+description: "Run E2E behavioral verification using agent-browser as the final quality gate before finalize. Tests the complete, reviewed, secure implementation from a user's perspective."
+---
+
+# /sk:e2e
+
+E2E behavioral verification — the final quality gate before `/sk:finish-feature`. Runs after Review to verify the complete, reviewed, secure implementation works end-to-end from a user's perspective.
+
+**Hard gate:** all scenarios must pass. Zero failures allowed.
+
+## Allowed Tools
+
+Bash, Read, Glob, Grep
+
+## Steps
+
+### 1. Read Context
+
+Read these files to understand what to test:
+- `tasks/todo.md` — planned features and acceptance criteria
+- `tasks/findings.md` — design decisions and expected behaviors
+- `tasks/progress.md` — implementation notes
+
+### 2. Check agent-browser is Available
+
+```bash
+agent-browser --version
+```
+
+If not found, instruct the user:
+```
+agent-browser is required. Install it:
+  npm install -g agent-browser
+  agent-browser install   # downloads Chrome (~100MB)
+Then re-run /sk:e2e.
+```
+Stop if not available.
+
+### 3. Detect Local Server
+
+Determine what URL to test against:
+- Check for a dev server command in `package.json` scripts (`dev`, `start`)
+- Check for `artisan serve` in Laravel projects (`php artisan serve`)
+- Check for `vite` or `next dev`
+- If a server is already running (check common ports: 3000, 5173, 8000, 8080), use it
+- If no server is running, start one in the background and note the URL
+
+### 4. Locate E2E Test Files
+
+Find E2E test scenarios written during the Write Tests step:
+```bash
+find . -name "*.e2e.*" -o -name "*.spec.*" | grep -v node_modules
+ls tests/e2e/ 2>/dev/null
+```
+
+If no E2E test files exist, derive scenarios from `tasks/todo.md` acceptance criteria and `tasks/findings.md`.
+
+### 5. Run E2E Scenarios
+
+For each scenario, use agent-browser following this core pattern:
+
+```bash
+# Navigate to the page
+agent-browser open <url>
+
+# Get interactive elements (token-efficient ref-based snapshot)
+agent-browser snapshot -i
+
+# Interact using @refs (never CSS selectors)
+agent-browser click @e1
+agent-browser fill @e2 "input value"
+agent-browser press Enter
+
+# Use semantic locators when @refs aren't stable
+agent-browser find role button
+agent-browser find text "Expected Text"
+agent-browser find label "Email"
+
+# Assert expected state
+agent-browser snapshot   # check content
+agent-browser find text "Success Message"
+```
+
+**Ref-based interaction is required.** Never use CSS selectors (`#id`, `.class`) — use semantic locators (`find role`, `find text`, `find label`, `find placeholder`) for stability.
+
+For each scenario, record:
+- Scenario name
+- Steps executed
+- Result: PASS or FAIL
+- On FAIL: what was expected vs. what was found (include snapshot excerpt)
+
+### 6. Report Results
+
+```
+E2E Results:
+  PASS  [scenario name]
+  PASS  [scenario name]
+  FAIL  [scenario name] — expected "X" but found "Y"
+
+Total: X passed, Y failed
+```
+
+If all pass → proceed to Fix & Retest Protocol section (no action needed).
+If any fail → apply Fix & Retest Protocol.
+
+## Fix & Retest Protocol
+
+When this gate requires a fix, classify it before committing:
+
+**a. Style/config/wording change** (CSS tweak, copy change, selector fix) → commit and re-run `/sk:e2e` (no unit test update needed)
+
+**b. Logic change** (new branch, modified condition, new data path, query change, new function, API change) → trigger protocol:
+1. Update or add failing unit tests for the new behavior
+2. Re-run `/sk:test` — must pass at 100% coverage
+3. Commit (tests + fix together in one commit)
+4. Re-run `/sk:e2e` from scratch
+
+**Exception:** Formatter auto-fixes are never logic changes — bypass protocol automatically.
+
+**This gate cannot be skipped.** All scenarios must pass before proceeding to `/sk:update-task`.
+
+## Next Steps
+
+If all scenarios pass:
+> "E2E gate clean. Run `/sk:update-task` to mark the task done."
+
+If failures remain after fixes:
+> "Re-running /sk:e2e — [N] scenarios still failing."
+
+---
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:e2e"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |
+
+> `opus` = inherit (uses the current session model). When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

package/skills/sk:frontend-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sk:frontend-design
-description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Produces design direction, mockups, and visual specifications — NOT code.
+description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Produces design direction, mockups, and visual specifications — NOT code. Use --pencil flag to also generate a Pencil visual mockup (requires Pencil app + MCP).
 license: Complete terms in LICENSE.txt
 ---
 
@@ -95,15 +95,21 @@ End every `/sk:frontend-design` session with a structured summary:
 [Specific Tailwind classes, CSS patterns, or gotchas for /sk:execute-plan]
 ```
 
-After presenting the design summary, ask the user:
+After presenting the design summary, you **MUST** stop and ask — do not continue or summarize further:
 
-**"Would you like me to create a Pencil visual mockup? (y/n)"**
+> **"Would you like me to create a Pencil visual mockup? (Requires Pencil app open + Pencil MCP connected) (y/n)"**
+
+Wait for the user's response before doing anything else.
+
+You can also trigger the Pencil phase directly by running `/sk:frontend-design --pencil`.
 
 ---
 
 ## Pencil Visual Mockup Phase
 
-Only run this phase if the user answers **y** or **yes**.
+Only run this phase if:
+- The user answers **y** or **yes** to the prompt above, OR
+- The user invoked the skill with `--pencil`
 
 ### Step 1 — Find or create the .pen file
 

package/skills/sk:lint/SKILL.md

@@ -66,15 +66,38 @@ Agent 2: "Run vendor/bin/rector --dry-run. Report all suggested changes with fil
 Agent 3: "Run npx eslint . Report all errors with file:line."
 ```
 
-### 5. Fix and Re-run
+### 5. Run Dependency Audit
 
-If any analyzer reports errors:
+Run dependency vulnerability checks for detected stacks:
+
+| Stack | Command | Block on |
+|-------|---------|----------|
+| PHP (composer.json) | `composer audit` | any severity with fix available (`composer audit` has no severity filter) |
+| Node (package.json) | `npm audit --audit-level=high` | high or critical |
+| Node (yarn.lock) | `yarn audit --level high` | high or critical |
+| Node (pnpm-lock.yaml) | `pnpm audit --audit-level high` | high or critical |
+| Python (pyproject.toml / requirements.txt) | `pip-audit` | high or critical |
+
+For each detected package manager, run the audit command and capture output.
+
+**Block (fail this gate):**
+- PHP: any vulnerability that has a fix available (`composer audit` exits non-zero for all severities — no filtering option exists)
+- Node/Python: critical or high severity vulnerabilities that have a fix available
+
+**Warn (pass with note):** medium/low severity for Node/Python, or any severity with no available fix — note in report but do not block.
+
+Skip stacks not present in the project.
+
+### 6. Fix and Re-run
+
+If any analyzer reports errors or the dep audit blocks:
 1. Fix all reported issues
 2. Re-run formatters (fixes may need formatting)
 3. Re-launch all analyzers in parallel
-4. Loop until every tool exits clean
+4. Re-run dep audit if any dependency was fixed
+5. Loop until every tool exits clean
 
-### 6. Report Results
+### 7. Report Results
 
 Print one line per tool:
 
@@ -90,12 +113,34 @@ ESLint:        X errors fixed / clean
 ruff check:    X issues fixed / clean
 golangci-lint: X issues fixed / clean
 cargo clippy:  X warnings fixed / clean
+composer audit: clean / X vulns blocked
+npm audit:     clean / X vulns blocked
 ```
 
 Only include lines for detected tools. All must show "clean" before this skill passes.
 
 ---
 
+## Fix & Retest Protocol
+
+When this gate requires a fix, classify it before committing:
+
+**a. Formatter auto-fix** (Pint, Prettier, gofmt, cargo fmt changed whitespace/style) → commit and re-run `/sk:lint`. Never a logic change — bypass protocol.
+
+**b. Analyzer fix** (PHPStan type error, Rector suggestion, ESLint error, ruff violation) → classify each fix:
+  - Type annotation, import order, unused var, style rule → **style fix** → commit and re-run
+  - New guard clause, changed condition, extracted function, modified data flow → **logic change** → trigger protocol:
+    1. Update or add failing unit tests for the new behavior
+    2. Re-run `/sk:test` — must pass at 100% coverage
+    3. Commit (tests + fix together in one commit)
+    4. Re-run `/sk:lint` from scratch
+
+**c. Dependency vulnerability fix** (composer audit / npm audit finding) → classify:
+  - Version bump with no API change → **style fix** → commit and re-run
+  - Version bump with API/behavior change → **logic change** → trigger protocol
+
+---
+
 ## Model Routing
 
 Read `.shipkit/config.json` from the project root if it exists.

package/skills/sk:perf/SKILL.md

@@ -171,6 +171,27 @@ If there are no critical or high findings:
 
 ---
 
+## Fix & Retest Protocol
+
+When applying a performance fix, classify it before committing:
+
+**a. Config/infrastructure change** (adding cache headers, enabling compression, changing CDN config, adjusting connection pool size) → commit and re-run `/sk:perf`. No test update needed.
+
+**b. Logic change** (fixing N+1 query by changing data-fetching logic, refactoring algorithm, modifying data structure, changing pagination logic) → trigger protocol:
+1. Update or add failing unit tests for the new optimized behavior
+2. Re-run `/sk:test` — must pass at 100% coverage
+3. Commit (tests + fix together in one commit)
+4. Re-run `/sk:perf` to verify the fix resolved the finding
+
+**Common logic-change performance fixes:**
+- N+1 fix: changes how related data is fetched → update tests that assert on query count or data shape
+- Algorithm change: O(n²) → O(n log n) → update tests that assert on output correctness
+- Pagination: adding LIMIT/offset → update tests that assert on result set size
+
+**Why:** Performance fixes often change how data is fetched or processed. Tests must verify the optimized path produces correct results.
+
+---
+
 ## Model Routing
 
 Read `.shipkit/config.json` from the project root if it exists.

package/skills/sk:review/SKILL.md

@@ -15,14 +15,31 @@ This is a **report-only** step. If Critical or Warning issues are found, the use
 
 ## Allowed Tools
 
-Bash, Read, Glob, Grep
+Bash, Read, Glob, Grep, Skill
 
-**Intentionally NO Write or Edit** — this skill is report-only. If issues are found, the user decides what to fix.
+**Step 0 only:** the `simplify` skill is invoked via the Skill tool, which carries its own Write/Edit permissions. All other steps are read-only — no direct Write or Edit calls. If issues are found in the main review, the user decides what to fix.
 
 ## Steps
 
 You MUST complete these steps in order:
 
+### 0. Run Simplify First
+
+Before reviewing, invoke the built-in `simplify` skill on the changed files to catch reuse, quality, and efficiency issues automatically:
+
+> "Review the changed files on this branch for reuse, quality, and efficiency. Fix any issues found."
+
+Use `git diff main..HEAD --name-only` to identify the changed files, then run simplify on them.
+
+If simplify makes any changes:
+1. Verify the changes are correct
+2. Commit them with `/sk:smart-commit` before continuing the review
+3. Note in the review report: "Simplify pre-pass: X files updated"
+
+If simplify makes no changes, proceed directly to step 1.
+
+**Note:** Simplify runs automatically as part of `/sk:review` — users do not need to run it separately.
+
 ### 1. Read Project Context
 
 ```
@@ -327,6 +344,20 @@ If the user wants to fix nitpicks, loop back to `/sk:debug` + `/sk:smart-commit`
 If the review is **completely clean**:
 > "Review complete — no issues found. Run `/sk:finish-feature` to finalize the branch and create a PR."
 
+### Fix & Retest Protocol
+
+When applying a fix from this review, classify it before committing:
+
+**a. Style/naming/comment change** (rename variable, add doc comment, reorder imports, extract constant) → commit and re-run `/sk:review`. No test update needed.
+
+**b. Logic change** (fix incorrect condition, add missing null check, change data flow, refactor algorithm, fix async bug) → trigger protocol:
+1. Update or add failing unit tests for the corrected behavior
+2. Re-run `/sk:test` — must pass at 100% coverage
+3. Commit (tests + fix together in one commit)
+4. Re-run `/sk:review` from scratch
+
+**Why:** Review catches logic bugs. Fixing a logic bug without updating tests leaves the test suite asserting on the old (wrong) behavior.
+
 ---
 
 ## Model Routing

package/skills/sk:setup-claude/SKILL.md

@@ -36,7 +36,6 @@ After bootstrapping a project, the recommended workflow becomes:
 - `plan.md` — creates/refreshes planning files and starts planning
 - `status.md` — prints a compact progress summary
 - `finish-feature.md` — branch finalization checklist (stack-aware)
-- `features.md` — sync `docs/sk:features/` specs with current codebase; creates the spec system from scratch if it doesn't exist
 - `security-check.md` — audit changed files (or full project with `--all`) for security best practices, OWASP Top 10, and production-grade quality
 
 ### Project Docs (in `.claude/docs/`)