@kennethsolomon/shipkit 3.17.0 → 3.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/README.md +293 -411
  2. package/commands/sk/finish-feature.md +14 -0
  3. package/commands/sk/help.md +13 -15
  4. package/package.json +1 -1
  5. package/skills/sk:autopilot/SKILL.md +25 -3
  6. package/skills/sk:gates/SKILL.md +2 -1
  7. package/skills/sk:setup-claude/templates/CLAUDE.md.template +7 -1
  8. package/skills/sk:setup-optimizer/SKILL.md +4 -4
  9. package/skills/sk:start/SKILL.md +2 -2
  10. package/skills/sk:team/SKILL.md +1 -1
package/README.md CHANGED
@@ -21,28 +21,15 @@ npm install -g @kennethsolomon/shipkit && shipkit
21
21
 
22
22
  ---
23
23
 
24
- ## What's New (v3.16.0 — March 2026)
25
-
26
- **Formal Agent Definitions, Path-Scoped Rules, and 2 new skills:**
27
-
28
- - **`.claude/agents/`** — 6 formal agent definitions (backend-dev, frontend-dev, qa-engineer, security-reviewer, code-reviewer, debugger) with `memory: project`, `isolation: worktree`, and `background: true` where appropriate. `/sk:setup-claude` deploys these to every new project.
29
- - **`.claude/rules/`** — 6 path-scoped rule files that auto-activate in Claude Code when you edit matching files: `laravel.md`, `react.md`, `vue.md`, `tests.md`, `api.md`, `migrations.md`. Stack-relevant rules are deployed by `/sk:setup-claude` automatically.
30
- - **`/sk:ci`** — Set up GitHub Actions or GitLab CI with Claude Code workflows: auto PR review, issue triage, nightly security audit, release automation. Supports enterprise setups (AWS Bedrock OIDC, Google Vertex AI Workload Identity).
31
- - **`/sk:plugin`** — Package your project-level customizations (skills, agents, hooks) into a distributable Claude Code plugin with a `.claude-plugin/plugin.json` manifest.
32
- - **Skill frontmatter upgrades** — model routing (`haiku` for lightweight skills, `sonnet` for analysis), `disable-model-invocation: true` on side-effect skills (commit, release, branch), `context: fork` on expensive standalone skills (seo-audit, accessibility, reverse-doc).
33
- - **Bug fix** — `allowed_tools` → `allowed-tools` (underscore typo silently ignored by Claude Code) fixed in 7 skills + all agent templates.
34
-
35
- ---
36
-
37
24
  ## What is ShipKit?
38
25
 
39
- ShipKit turns Claude Code into a disciplined development partner. Instead of "write some code," every feature goes through:
26
+ ShipKit turns Claude Code into a disciplined development partner. Instead of "write some code and hope," every task follows a structured path:
40
27
 
41
- **Plan** → **Build (TDD)** → **Quality Gates** → **Ship**
28
+ **Plan → Build (TDD) → Quality Gates → Ship**
42
29
 
43
30
  Each gate must pass before the next step. Lint fails? Fix it. Tests don't cover new code? Write them. Security issues? They block the PR. Quality is structural, not optional.
44
31
 
45
- ShipKit auto-detects your stack — linters, test runners, frameworks, package managers. No configuration needed.
32
+ ShipKit auto-detects your stack — linters, test runners, frameworks, ORMs. No configuration needed.
46
33
 
47
34
  ---
48
35
 
@@ -52,536 +39,433 @@ ShipKit auto-detects your stack — linters, test runners, frameworks, package m
52
39
  # 1. Install
53
40
  npm install -g @kennethsolomon/shipkit && shipkit
54
41
 
55
- # 2. Bootstrap your project (run once)
42
+ # 2. Bootstrap your project (run once per project)
56
43
  /sk:setup-claude
57
44
 
58
- # 3. Start building
59
- /sk:start
45
+ # 3. Start any task
46
+ /sk:start add user authentication
60
47
  ```
61
48
 
62
- That's it. `/sk:setup-claude` creates your project scaffolding: planning files, lifecycle hooks, path-scoped coding rules, and a persistent statusline — all auto-configured for your stack.
49
+ `/sk:setup-claude` creates everything your project needs: planning files, lifecycle hooks, 13 agent definitions, path-scoped rules, LSP config, and MCP servers.
63
50
 
64
- `/sk:start` is the recommended entry point — it classifies your task and routes you to the optimal flow automatically. You can also jump directly to `/sk:brainstorm`, `/sk:debug`, or any other flow entry point.
65
-
66
- ### Updating ShipKit
51
+ `/sk:start` is your single entry point — tell it what you want to do in plain English and it classifies the task, picks the right flow, and routes you automatically.
67
52
 
53
+ To update ShipKit later:
68
54
  ```bash
69
- # Update the package
70
- npm install -g @kennethsolomon/shipkit && shipkit
71
-
72
- # Then in each project, update CLAUDE.md + deploy new hooks:
73
- /sk:setup-optimizer
55
+ npm install -g @kennethsolomon/shipkit && shipkit # update globally
56
+ /sk:setup-optimizer # update each project
74
57
  ```
75
58
 
76
- `shipkit` re-installs all skills and commands globally. `/sk:setup-optimizer` updates each project's CLAUDE.md with new commands and deploys any missing hooks.
77
-
78
59
  ---
79
60
 
80
- ## Lifecycle Hooks
81
-
82
- `/sk:setup-claude` installs lifecycle hooks that automate common tasks. Core hooks are always installed; enhanced hooks are opt-in.
83
-
84
- **Core hooks (always installed):**
85
- | Hook | Event | What it does |
86
- |------|-------|-------------|
87
- | `session-start` | SessionStart | Loads branch, recent commits, tech debt, code health |
88
- | `session-stop` | Stop | Logs session accomplishments to `tasks/progress.md` |
89
- | `pre-compact` | PreCompact | Saves git state before context compression |
90
- | `validate-commit` | PreToolUse (git commit) | Validates conventional commit format, detects secrets |
91
- | `validate-push` | PreToolUse (git push) | Warns before pushing to protected branches |
92
- | `log-agent` | SubagentStart | Logs sub-agent invocations to `tasks/agent-audit.log` |
93
-
94
- **Enhanced hooks (opt-in via `/sk:setup-claude` or `/sk:setup-optimizer`):**
95
- | Hook | Event | What it does |
96
- |------|-------|-------------|
97
- | `config-protection` | PreToolUse (Edit/Write) | Blocks modifications to linter/formatter configs |
98
- | `post-edit-format` | PostToolUse (Edit) | Auto-formats with Biome/Prettier/Pint/gofmt after edits |
99
- | `console-log-warning` | Stop | Warns about `console.log`, `dd()`, `var_dump()` in modified files |
100
- | `suggest-compact` | PreToolUse (Edit/Write) | Suggests `/compact` after 50+ tool calls |
101
- | `cost-tracker` | Stop | Logs session metadata to `.claude/sessions/cost-log.jsonl` |
102
- | `safety-guard` | PreToolUse (Bash/Edit/Write) | Enforces `/sk:safety-guard` freeze/careful mode |
61
+ ## Which scenario are you in?
62
+
63
+ | I want to... | Start here | Flow |
64
+ |---|---|---|
65
+ | **Not sure — just describe my task** | `/sk:start <description>` | Auto-classified |
66
+ | **Build a new feature** | `/sk:start add <feature>` | Feature (8 phases + scope check, learn, retro) |
67
+ | **Build a full-stack feature (backend + frontend + mobile)** | `/sk:start --team add <feature>` | Feature with parallel agents |
68
+ | **Make a small change** (config, copy, dependency bump) | `/sk:start bump lodash` | Fast-track (5 steps) |
69
+ | **Fix a bug** | `/sk:start fix <description>` | Debug (7 steps) |
70
+ | **Fix a production emergency** | `/sk:start hotfix <description>` | Hotfix (6 steps) |
71
+ | **Requirement changed mid-way** | `/sk:change` | Re-enter at the right step |
72
+ | **Understand an unfamiliar codebase** | `/sk:reverse-doc architecture src/` | Generate architecture docs |
73
+ | **Set up CI/CD** | `/sk:ci` | GitHub Actions or GitLab CI |
74
+ | **Clean up messy code** | Use `refactor-specialist` agent | Behavior-preserving refactor |
75
+ | **Generate missing docs** | Use `tech-writer` agent | README, API, architecture docs |
103
76
 
104
77
  ---
105
78
 
106
- ## Formal Agent Definitions
107
-
108
- `/sk:setup-claude` deploys 13 agent definitions to `.claude/agents/` — specialized sub-agents with `memory`, `model`, `tools`, and `isolation` pre-configured. Invoke any agent by mentioning its name in Claude Code.
79
+ ## Scenario Tutorials
109
80
 
110
- **Implementation agents** — build things:
81
+ ### Scenario A — Building a New Feature
111
82
 
112
- | Agent | Memory | Isolation | When to use |
113
- |-------|--------|-----------|------------|
114
- | `backend-dev` | project | worktree | Parallel backend work in `/sk:team` — API, services, models |
115
- | `frontend-dev` | project | worktree | Parallel frontend work in `/sk:team` — components, pages, state |
116
- | `mobile-dev` | project | worktree | React Native / Expo / Flutter — mobile-specific patterns and store prep |
83
+ You want to add user authentication to your app.
117
84
 
118
- **Quality agents** — find and fix problems:
85
+ ```
86
+ /sk:start add email/password authentication with JWT
87
+ ```
119
88
 
120
- | Agent | Memory | Isolation | When to use |
121
- |-------|--------|-----------|------------|
122
- | `qa-engineer` | project | background | Write E2E scenarios while other agents implement |
123
- | `code-reviewer` | project | — | 7-dimension review after implementation (read-only) |
124
- | `security-reviewer` | user | — | OWASP audit before shipping sensitive changes (read-only) |
125
- | `performance-optimizer` | project | worktree | When `/sk:perf` finds Critical/High issues — finds AND fixes them |
89
+ ShipKit classifies this as a **full-stack feature** and confirms:
126
90
 
127
- **Design agents** — plan before building:
91
+ ```
92
+ Detected: Full-stack feature
93
+ Flow: feature (8 steps)
94
+ Mode: autopilot
95
+ Agents: team (backend + frontend + QA)
128
96
 
129
- | Agent | Memory | Isolation | When to use |
130
- |-------|--------|-----------|------------|
131
- | `architect` | project | — | Before `/sk:write-plan` on complex tasks — proposes options with trade-offs |
132
- | `database-architect` | project | — | Before `/sk:schema-migrate` — migration safety analysis and index recommendations |
97
+ Proceed? (y)
98
+ ```
133
99
 
134
- **Operations agents** — infrastructure and maintenance:
100
+ Type `y`. Here's what happens automatically:
135
101
 
136
- | Agent | Memory | Isolation | When to use |
137
- |-------|--------|-----------|------------|
138
- | `devops-engineer` | project | worktree | CI/CD pipelines, Docker, deployment config — use with `/sk:ci` |
139
- | `debugger` | project | — | Structured root-cause analysis — use with `/sk:debug` |
140
- | `refactor-specialist` | project | worktree | Behavior-preserving cleanups — tests must pass before AND after |
141
- | `tech-writer` | project | — | README, API docs, architecture docs from existing code |
102
+ **Step 1 — Brainstorm** (`/sk:brainstorming`)
103
+ Reads your `tasks/findings.md` and `tasks/lessons.md`. Asks clarifying questions one at a time: session vs token auth? remember me? email verification? Writes decisions to `tasks/findings.md`.
142
104
 
143
- `memory: project` — agent accumulates knowledge across sessions for that project. `isolation: worktree` — works in a separate git worktree, safe for risky changes. `background: true` — runs without blocking your conversation.
105
+ For complex architecture decisions, the `architect` agent kicks in before you write a plan:
106
+ > Reads your codebase → proposes 2-3 approaches with trade-offs → outputs: "Use Laravel Sanctum (already in composer.json) — not Passport"
144
107
 
145
- ---
108
+ **Step 2 — Design**
109
+ - `architect` agent produces API contracts: `POST /auth/login`, `POST /auth/register`, etc.
110
+ - `/sk:frontend-design` produces login/register page mockups.
111
+ - `database-architect` agent reviews the proposed schema: flags missing index on `users.email`, recommends nullable `email_verified_at`.
146
112
 
147
- ## Path-Scoped Rules
113
+ **Step 3 — Plan** (`/sk:write-plan`)
114
+ Writes `tasks/todo.md` with every checkbox: migrations, models, controllers, frontend pages, tests.
148
115
 
149
- `/sk:setup-claude` installs coding rule files in `.claude/rules/` that Claude Code auto-activates when you open or edit matching files — no manual context loading needed.
116
+ **Step 4 — Branch**
117
+ ```
118
+ git checkout -b feature/add-authentication
119
+ ```
150
120
 
151
- | Rule file | Activates when editing | What it enforces |
152
- |-----------|----------------------|-----------------|
153
- | `laravel.md` | `app/**/*.php`, `routes/**`, `config/**` | Laravel conventions, service containers, Eloquent patterns |
154
- | `react.md` | `**/*.tsx`, `**/*.jsx`, `src/**/*.ts` | Hooks rules, component patterns, TypeScript strictness |
155
- | `vue.md` | `**/*.vue`, `resources/js/**/*.ts` | Composition API only, `<script setup>`, Pinia patterns |
156
- | `tests.md` | `tests/**`, `**/*.test.*`, `**/*.spec.*` | TDD standards, assertion quality, test isolation |
157
- | `api.md` | `routes/api.php`, `app/Http/Controllers/**` | RESTful conventions, auth patterns, error response shapes |
158
- | `migrations.md` | `database/migrations/**`, `prisma/**` | Migration safety rules, reversibility, index naming |
121
+ **Step 5 — Implement** (`/sk:team`)
122
+ Three agents fire simultaneously:
159
123
 
160
- Stack-relevant rules are detected and deployed automatically during `/sk:setup-claude` and `/sk:setup-optimizer`.
124
+ ```
125
+ backend-dev (worktree) → writes AuthTest.php → implements migration, User model, AuthController
126
+ frontend-dev (worktree) → writes LoginPage.test.ts → implements LoginPage, useAuth composable
127
+ qa-engineer (background) → writes 14 Playwright E2E scenarios while others implement
128
+ ```
161
129
 
162
- ---
130
+ Backend and frontend work in isolated worktrees — zero conflicts. Results merge when both complete.
163
131
 
164
- ## Pick Your Flow
132
+ **Step 5.5 — Scope Check** (`/sk:scope-check`)
133
+ Compares everything that was implemented against `tasks/todo.md`. Flags anything that crept in beyond the plan — extra features, unrequested refactors, new files not in scope. Trims or defers the excess before committing.
165
134
 
166
- | I want to... | Run this | What happens |
167
- |--------------|----------|-------------|
168
- | **Not sure — let ShipKit decide** | `/sk:start` | Classifies your task, routes to optimal flow/mode/agents |
169
- | **Build a new feature** | `/sk:brainstorm` | Full workflow: plan → TDD → quality gates → PR |
170
- | **Build hands-free** | `/sk:autopilot` | All 8 steps, auto-skip, auto-advance, auto-commit |
171
- | **Full-stack feature (parallel)** | `/sk:team` | Parallel domain agents (backend + frontend + QA) |
172
- | **Make a small change** | `/sk:fast-track` | Skip planning, keep all quality gates |
173
- | **Fix a bug** | `/sk:debug` | Investigate → regression test → fix → gates → PR |
174
- | **Fix a production emergency** | `/sk:hotfix` | Skip TDD, but quality gates still enforced |
175
- | **Handle a requirement change** | `/sk:change` | Assess scope, re-enter workflow at the right step |
135
+ **Step 6 — Commit** (`/sk:smart-commit`)
136
+ Presents the diff. You approve. Commits.
176
137
 
177
- ---
138
+ **Step 7 — Gates** (`/sk:gates`)
139
+ Four batches run:
178
140
 
179
- ## Workflows
141
+ ```
142
+ Batch 1 (parallel):
143
+ security-reviewer → OWASP audit → flags: no rate limit on POST /login
144
+ performance-optimizer → scans for N+1 → clean
145
+ linter → pint auto-fixes formatting
180
146
 
181
- ### Feature Flow — full planning + TDD + all gates
147
+ Batch 2:
148
+ test runner → 97% coverage → adds missing test → 100%
182
149
 
183
- > Start with: `/sk:brainstorm`
150
+ Batch 3:
151
+ code-reviewer → 7-dimension review → flags: logout doesn't revoke all tokens
184
152
 
185
- | Step | Command | What it does | Phase |
186
- |------|---------|-------------|-------|
187
- | 1 | `/sk:brainstorm` | Explore requirements, propose approaches | Think |
188
- | 2 | `/sk:frontend-design` or `/sk:api-design` | *Optional* — UI mockup or API contracts (includes accessibility) | Think |
189
- | 3 | `/sk:write-plan` | Write decision-complete plan | Think |
190
- | 4 | `/sk:branch` | Create feature branch | Build |
191
- | 5 | `/sk:write-tests` + `/sk:execute-plan` | TDD: write failing tests, then implement | Build |
192
- | 6 | `/sk:smart-commit` | Conventional commit | Build |
193
- | 7 | `/sk:gates` | All 6 quality gates (parallel batches) | Verify |
194
- | 8 | `/sk:finish-feature` | Update task, changelog, PR, feature sync, release | Ship |
153
+ Batch 4:
154
+ E2E tester → runs 14 Playwright scenarios → 14/14 pass
155
+ ```
195
156
 
196
- ---
157
+ Each failure auto-fixes and re-runs. One squash commit per gate pass.
197
158
 
198
- ### Fast-Track Flow — skip planning, keep all gates
159
+ **Step 8 — Finalize** (`/sk:finish-feature`)
160
+ Changelog updated. PR created. Feature spec synced. Asks about release.
199
161
 
200
- > Start with: `/sk:fast-track`
162
+ **Step 8.5 — Learn** (`/sk:learn`)
163
+ Extracts reusable patterns from this session:
164
+ > "Rate limiting must be applied to all auth endpoints — security-reviewer flagged POST /login"
201
165
 
202
- | Step | Command | What it does | Phase |
203
- |------|---------|-------------|-------|
204
- | 1 | `/sk:branch` | Create feature branch | Build |
205
- | 2 | implement directly | No TDD — write code | Build |
206
- | 3 | `/sk:smart-commit` | Conventional commit | Build |
207
- | 4 | `/sk:gates` | All quality gates (parallel batches) | Verify |
208
- | 5 | `/sk:finish-feature` | Changelog + PR | Ship |
166
+ Saved to `~/.claude/skills/learned/` — available in future sessions across all projects.
209
167
 
210
- Guard rails: warns if diff > 300 lines or > 5 new files.
168
+ **Step 8.6 — Retro** (`/sk:retro`)
169
+ Brief post-ship retrospective — 3-5 bullets:
170
+ - What went well (gates caught rate-limit issue before PR)
171
+ - What slowed down (schema index discovery required re-migration)
172
+ - Next action (add rate-limit check to write-tests template)
211
173
 
212
174
  ---
213
175
 
214
- ### Bug Fix Flow — investigate first, then fix
215
-
216
- > Start with: `/sk:debug`
176
+ ### Scenario B — Fixing a Bug
217
177
 
218
- | Step | Command | What it does | Phase |
219
- |------|---------|-------------|-------|
220
- | 1 | `/sk:debug` | Reproduce, isolate, hypothesize, verify | Think |
221
- | 2 | `/sk:branch` | Create fix branch | Build |
222
- | 3 | `/sk:write-tests` | Regression test that reproduces the bug | Build |
223
- | 4 | implement the fix | Make regression test pass | Build |
224
- | 5 | `/sk:smart-commit` | Commit fix + test | Build |
225
- | 6 | `/sk:gates` | All quality gates (parallel batches) | Verify |
226
- | 7 | `/sk:finish-feature` | Changelog + PR | Ship |
178
+ Checkout total is wrong when a coupon and tax are both applied.
227
179
 
228
- ---
180
+ ```
181
+ /sk:start fix checkout total wrong when coupon and tax applied
182
+ ```
229
183
 
230
- ### Hotfix Flow — production emergency
184
+ ShipKit detects `fix` keyword → routes to **debug flow**.
231
185
 
232
- > Start with: `/sk:hotfix`
186
+ The `debugger` agent takes over:
187
+ 1. Reproduces: `POST /checkout` with `SAVE20` + CA tax → wrong total
188
+ 2. Isolates: `OrderCalculator::applyDiscount()` runs before `TaxService::calculate()`
189
+ 3. Hypothesis: discount should apply to subtotal, tax should compute on the discounted subtotal
190
+ 4. Verifies: writes a failing unit test proving expected vs actual
191
+ 5. Proposes minimal fix in `OrderCalculator.php:47`
233
192
 
234
- | Step | Command | What it does | Phase |
235
- |------|---------|-------------|-------|
236
- | 1 | `/sk:debug` | Root-cause analysis | Think |
237
- | 2 | `/sk:branch` | Create hotfix branch | Build |
238
- | 3 | implement directly | Fix the issue | Build |
239
- | 4 | `/sk:smart-commit` | Commit the fix | Build |
240
- | 5 | `/sk:gates` | All quality gates (parallel batches) | Verify |
241
- | 6 | `/sk:finish-feature` | Changelog + PR (marked as hotfix) | Ship |
193
+ You approve → fix applied → regression test committed → `/sk:gates` → PR.
242
194
 
243
- After merging: add regression test + lesson to `tasks/lessons.md`.
195
+ After merge, `/sk:learn` captures:
196
+ > "Calculation order matters in pricing pipeline — always test discount + tax combinations together"
244
197
 
245
198
  ---
246
199
 
247
- ### Requirement Change — mid-workflow pivot
200
+ ### Scenario C — Production Hotfix
248
201
 
249
- > Run: `/sk:change` — it classifies scope and re-enters at the right step
202
+ Login is broken in production (500 error). It's 2am.
250
203
 
251
- | Tier | What changed | Example | Re-entry point |
252
- |------|-------------|---------|----------------|
253
- | **Tier 1** | Behavior tweak (same scope) | "Delete all" → "Delete users only" | `/sk:write-tests` |
254
- | **Tier 2** | New requirements (new scope) | "Also add export to CSV" | `/sk:write-plan` |
255
- | **Tier 3** | Scope shift (rethink) | "Different approach entirely" | `/sk:brainstorm` |
256
-
257
- ---
204
+ ```
205
+ /sk:start hotfix login 500 error in production
206
+ ```
258
207
 
259
- ## Quality Gates (`/sk:gates`)
208
+ ShipKit detects `hotfix` + `production` → routes to **hotfix flow** (no TDD ceremony, gates still enforced).
260
209
 
261
- One command runs all 6 gates in parallel batches:
210
+ ```
211
+ /sk:debug → reads Sentry trace → undefined method 'getAuthToken' on User model
212
+ /sk:branch → hotfix/login-500-missing-auth-token
213
+ ```
262
214
 
263
- | Batch | Gates | Why this order |
264
- |-------|-------|---------------|
265
- | **1** (parallel) | lint + security + perf | Independent — run simultaneously |
266
- | **2** | tests | Needs lint fixes first |
267
- | **3** | code review | Needs deep understanding |
268
- | **4** | E2E Tests | Needs review fixes |
215
+ Fix applied directly — no brainstorm, no write-tests. Then:
269
216
 
270
- Each gate auto-fixes and re-runs until clean. Fixes are squashed into one commit per gate pass. If a gate fails 3 times, it stops and asks for help.
217
+ ```
218
+ /sk:gates → all gates pass
219
+ /sk:finish-feature → PR marked as hotfix
220
+ ```
271
221
 
272
- Pre-existing issues are logged to `tasks/tech-debt.md` — not fixed inline.
222
+ After merge: add regression test + lesson to `tasks/lessons.md`. Never skip this step.
273
223
 
274
224
  ---
275
225
 
276
- ## On-Demand Tools
277
-
278
- Use these anytime — they're not part of any workflow.
279
-
280
- ### Intelligence
281
-
282
- | Command | Usage | What it does |
283
- |---------|-------|-------------|
284
- | `/sk:learn` | `/sk:learn` | Extract reusable patterns from the session with confidence scoring (0.3-0.9) |
285
- | `/sk:learn` | `/sk:learn --list` | Show all learned patterns |
286
- | `/sk:context-budget` | `/sk:context-budget` | Audit token consumption across skills, agents, MCP tools, CLAUDE.md |
287
- | `/sk:context-budget` | `/sk:context-budget --verbose` | Per-file token breakdown |
288
- | `/sk:health` | `/sk:health` | Scorecard across 7 categories (0-70): tools, context, gates, memory, evals, security, cost |
289
- | `/sk:eval` | `/sk:eval define auth` | Define eval criteria before coding |
290
- | `/sk:eval` | `/sk:eval check auth` | Run evals during implementation |
291
- | `/sk:eval` | `/sk:eval report` | Summary of all eval results with pass@k metrics |
292
-
293
- ### Session Management
294
-
295
- | Command | Usage | What it does |
296
- |---------|-------|-------------|
297
- | `/sk:save-session` | `/sk:save-session` | Save branch, task, progress, open questions to `.claude/sessions/` |
298
- | `/sk:save-session` | `/sk:save-session --name "auth-flow"` | Save with a custom name |
299
- | `/sk:resume-session` | `/sk:resume-session` | List saved sessions and pick one to restore |
300
- | `/sk:resume-session` | `/sk:resume-session --latest` | Auto-pick most recent session |
301
- | `/sk:context` | `/sk:context` | Load all project context (automatic via hooks on session start) |
302
-
303
- ### Safety
226
+ ### Scenario D — Small Change
304
227
 
305
- | Command | Usage | What it does |
306
- |---------|-------|-------------|
307
- | `/sk:safety-guard` | `/sk:safety-guard careful` | Block destructive commands (rm -rf, force push, etc.) |
308
- | `/sk:safety-guard` | `/sk:safety-guard freeze --dir src/` | Lock edits to `src/` only |
309
- | `/sk:safety-guard` | `/sk:safety-guard guard --dir src/` | Both careful + freeze combined |
310
- | `/sk:safety-guard` | `/sk:safety-guard off` | Disable all guards |
311
- | `/sk:safety-guard` | `/sk:safety-guard status` | Show current mode + blocked action count |
228
+ Bump lodash to the latest version.
312
229
 
313
- ### Code Quality
230
+ ```
231
+ /sk:start bump lodash dependency to latest
232
+ ```
314
233
 
315
- | Command | When to use |
316
- |---------|------------|
317
- | `/sk:scope-check` | Mid-implementation — detect scope creep (On Track / Minor / Significant / Out of Control) |
318
- | `/sk:retro` | After shipping — analyze velocity, blockers, patterns, generate action items |
319
- | `/sk:seo-audit` | Web projects — SEO audit with source + dev server scanning |
234
+ ShipKit detects `bump` + `dependency` → routes to **fast-track flow** (5 steps, no planning ceremony).
320
235
 
321
- ### Documentation & Setup
236
+ ```
237
+ /sk:branch → fast-track/bump-lodash
238
+ update package.json
239
+ /sk:smart-commit
240
+ /sk:gates → same gates, no shortcuts on quality
241
+ /sk:finish-feature
242
+ ```
322
243
 
323
- | Command | When to use |
324
- |---------|------------|
325
- | `/sk:reverse-doc` | Inherited codebase — generate architecture/design docs from existing code |
326
- | `/sk:setup-optimizer` | Maintenance — diagnose, update workflow, deploy hooks, enrich CLAUDE.md |
327
- | `/sk:ci` | Team — set up GitHub Actions / GitLab CI with PR review, issue triage, nightly audits |
328
- | `/sk:plugin` | Distribution — package custom skills/agents/hooks as a shareable Claude Code plugin |
329
- | `/sk:mvp` | New idea — generate a complete MVP app from a single prompt |
330
- | `/sk:status` | Quick view of workflow and task status |
331
- | `/sk:dashboard` | Visual Kanban board across all git worktrees |
244
+ Guard rails: warns if the diff exceeds 300 lines (should be a full workflow at that point).
332
245
 
333
246
  ---
334
247
 
335
- ## Stack Support
336
-
337
- | Area | Supported |
338
- |------|-----------|
339
- | **Frameworks** | Laravel, Next.js, Nuxt, React, Vue, Node.js |
340
- | **Linters** | Pint, ESLint, PHPStan, Rector, Prettier, Biome |
341
- | **Test runners** | Pest, PHPUnit, Jest, Vitest, Playwright |
342
- | **Schema / ORM** | Prisma, Drizzle, Eloquent, SQLAlchemy, ActiveRecord |
343
- | **Release** | npm, Composer, iOS (App Store), Android (Play Store) |
344
-
345
- ---
248
+ ### Scenario E — Requirement Changed Mid-Way
346
249
 
347
- ## Code Navigation (LSP)
250
+ You're implementing a payment feature and the stakeholder adds "also support PayPal" after the plan is already written.
348
251
 
349
- ShipKit configures LSP (Language Server Protocol) automatically — giving Claude Code go-to-definition, find-references, hover, and diagnostics instead of plain text search.
252
+ ```
253
+ /sk:change
254
+ ```
350
255
 
351
- **`/sk:setup-claude`** and **`/sk:setup-optimizer`** both run an LSP Integration step that:
352
- - Sets `ENABLE_LSP_TOOL=1` in `~/.claude/settings.json`
353
- - Detects your stack and installs the appropriate language server
256
+ ShipKit classifies the scope change:
354
257
 
355
- | Stack | Language Server |
356
- |-------|----------------|
357
- | TypeScript / JavaScript | `typescript-language-server` |
358
- | PHP | `intelephense` |
359
- | Python | `pylsp` |
360
- | Go | `gopls` |
361
- | Rust | `rust-analyzer` |
362
- | Swift | `sourcekit-lsp` |
258
+ | Tier | What it means | Example |
259
+ |---|---|---|
260
+ | **Tier 1** | Behavior tweak, same scope | "Delete all" → "Delete users only" → re-enter at Write Tests |
261
+ | **Tier 2** | New requirements added | "Also add PayPal support" → re-enter at Write Plan |
262
+ | **Tier 3** | Scope shift, rethink needed | "Different approach entirely" → re-enter at Brainstorm |
363
263
 
364
- **Rule:** Prefer LSP over `rg`/Grep for code navigation. Use `rg` only when LSP is unavailable or for arbitrary text/pattern matching.
264
+ PayPal support = Tier 2. ShipKit revises the plan and re-enters at Step 3.
365
265
 
366
266
  ---
367
267
 
368
- ## MCP Servers & Plugins
369
-
370
- Both `/sk:setup-claude` and `/sk:setup-optimizer` offer to install three tools that enhance Claude Code's reasoning, knowledge, and session visibility. All are opt-in and idempotent.
268
+ ## The 13 Agents
371
269
 
372
- ### Sequential Thinking MCP
270
+ Agents are specialized sub-agents deployed to `.claude/agents/` by `/sk:setup-claude`. They are **explicitly invoked** by the workflow skills — not guessed. Each has its own memory, model, and isolation settings.
373
271
 
374
- **Why it exists:** Complex problems — architecture decisions, multi-step debugging, tasks with many constraints — benefit from structured reasoning. Without it, Claude works through hard problems in a single pass, which can miss steps or lose track of constraints.
272
+ ### Implementation Agents — build things
375
273
 
376
- **What it does:** Gives Claude a dedicated reasoning scratchpad. It thinks through steps sequentially before responding, without cluttering your conversation with the intermediate work.
274
+ | Agent | Invoked by | What it does |
275
+ |---|---|---|
276
+ | `backend-dev` | `sk:team` Step 2 | Writes backend tests (TDD red) then implements API, services, models in a worktree |
277
+ | `frontend-dev` | `sk:team` Step 2 | Writes frontend tests then implements components, pages, composables in a worktree |
278
+ | `mobile-dev` | `sk:team` Step 2 (mobile scope) | React Native / Expo / Flutter — mobile patterns, permissions, store prep |
377
279
 
378
- **Benefit:** More coherent, thorough responses on hard problems. Especially useful during `/sk:brainstorm`, `/sk:debug`, and `/sk:review`.
280
+ ### Quality Agents — find and fix problems
379
281
 
380
- **How it's installed:** Adds `@modelcontextprotocol/server-sequential-thinking` to `~/.mcp.json` (global, applies to all projects).
282
+ | Agent | Invoked by | What it does |
283
+ |---|---|---|
284
+ | `qa-engineer` | `sk:team` Step 2 | Writes E2E scenarios while others implement (background — doesn't block) |
285
+ | `code-reviewer` | `sk:gates` Batch 3 | 7-dimension review: correctness, security, performance, reliability, design, best practices, testing (read-only) |
286
+ | `security-reviewer` | `sk:gates` Batch 1, `sk:security-check` | OWASP audit — memory: user (remembers security patterns across all your projects) (read-only) |
287
+ | `performance-optimizer` | `sk:gates` Batch 1, `sk:perf` | Finds AND fixes Critical/High perf issues in a worktree |
381
288
 
382
- ### Context7
289
+ ### Design Agents — plan before building
383
290
 
384
- **Why it exists:** Claude's training has a knowledge cutoff. When you're working with libraries that release frequently — React, Next.js, Tailwind, shadcn/ui — Claude's suggestions can reference outdated APIs, deprecated methods, or patterns that no longer apply.
291
+ | Agent | Invoked by | What it does |
292
+ |---|---|---|
293
+ | `architect` | `sk:brainstorming` (complex tasks) | Proposes 2-3 architectural approaches with trade-offs before `/sk:write-plan` (read-only) |
294
+ | `database-architect` | `sk:schema-migrate` Phase 0 | Migration safety analysis, index recommendations, breaking change flags (read-only) |
385
295
 
386
- **What it does:** Fetches current, version-accurate documentation for libraries you're using and injects it into Claude's context at the moment it's needed.
296
+ ### Operations Agents — infrastructure and maintenance
387
297
 
388
- **Benefit:** Accurate code suggestions for the actual version you're running. No more `useEffect` patterns from React 17 when you're on React 19.
298
+ | Agent | Invoked by | What it does |
299
+ |---|---|---|
300
+ | `devops-engineer` | `sk:ci` | Generates CI/CD workflow files in a worktree — GitHub Actions, GitLab CI, Docker |
301
+ | `debugger` | `sk:debug` | Structured root-cause analysis: reproduce → isolate → hypothesize → verify → fix |
302
+ | `refactor-specialist` | On demand | Behavior-preserving cleanups — runs tests before AND after every change |
303
+ | `tech-writer` | `sk:reverse-doc` Phase 3 | README, API docs, architecture docs — reads code first, never invents behavior |
389
304
 
390
- **How it's installed:** Enables `context7@claude-plugins-official` in `~/.claude/settings.json`.
305
+ **Key rule:** Read-only agents (`security-reviewer`, `code-reviewer`, `architect`, `database-architect`) report findings — the main context or a write agent applies fixes. Write agents (`performance-optimizer`, `backend-dev`, `devops-engineer`, etc.) make changes directly in a worktree.
391
306
 
392
- ### ccstatusline
307
+ ---
393
308
 
394
- **Why it exists:** Knowing your context window %, active model, and current branch at a glance matters. Without it, you have to run `/sk:status` or guess when to `/compact`.
309
+ ## Quality Gates
395
310
 
396
- **What it does:** Adds a persistent statusline to the Claude Code CLI showing context window usage, active model, git branch, and current task.
311
+ `/sk:gates` runs all 6 gates in optimized parallel batches. One command replaces six.
397
312
 
398
- **Benefit:** Always-visible session state. Know when you're approaching context limits before it becomes a problem.
313
+ | Batch | Gates | Notes |
314
+ |---|---|---|
315
+ | **1** (parallel) | lint + `security-reviewer` + `performance-optimizer` | Independent — run simultaneously |
316
+ | **2** | tests (100% coverage on new code) | Needs lint fixes first |
317
+ | **3** | `code-reviewer` (7-dimension) | Needs test confirmation |
318
+ | **4** | E2E (Playwright or agent-browser) | Uses scenarios from `qa-engineer` |
399
319
 
400
- **How it's installed:** Runs `npx ccstatusline@latest` which writes the statusline config to `~/.claude/settings.json`.
320
+ 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.
401
321
 
402
322
  ---
403
323
 
404
- ## Highest ROI Workflow — Using Every Feature
405
-
406
- This is the recommended workflow that gets the most value from every ShipKit feature. It's not the fastest path — it's the most reliable path over the lifetime of a project.
407
-
408
- ### One-Time Project Setup (Do This Once)
409
-
410
- ```bash
411
- # 1. Install ShipKit globally
412
- npm install -g @kennethsolomon/shipkit && shipkit
413
-
414
- # 2. Bootstrap your project
415
- /sk:setup-claude
416
- ```
324
+ ## Lifecycle Hooks
417
325
 
418
- `/sk:setup-claude` deploys: CLAUDE.md, lifecycle hooks, 13 agent definitions, path-scoped rules, planning files, LSP config, MCP servers (Sequential Thinking, Context7), and ccstatusline.
326
+ Installed by `/sk:setup-claude`. Fire automatically on Claude Code events.
419
327
 
420
- ```bash
421
- # 3. Set up CI (once per repo)
422
- /sk:ci
423
- ```
328
+ **Always installed:**
424
329
 
425
- `/sk:ci` generates GitHub Actions workflows for auto PR review, issue triage, and nightly security audits. From this point on, every PR gets reviewed by Claude automatically.
330
+ | Hook | When | What it does |
331
+ |---|---|---|
332
+ | `session-start` | Session opens | Loads branch, recent commits, active task, tech debt |
333
+ | `session-stop` | Session closes | Logs accomplishments to `tasks/progress.md` |
334
+ | `pre-compact` | Before context compression | Saves git state |
335
+ | `validate-commit` | Before `git commit` | Validates conventional commit format, detects secrets |
336
+ | `validate-push` | Before `git push` | Warns before pushing to protected branches |
337
+ | `log-agent` | Sub-agent starts | Logs invocations to `tasks/agent-audit.log` |
426
338
 
427
- ### Session Start (Every Session)
339
+ **Opt-in:**
428
340
 
429
- The `session-start` hook fires automatically and loads: branch, recent commits, active task, tech debt, and code health. You see the session brief before you type anything.
341
+ | Hook | What it does |
342
+ |---|---|
343
+ | `post-edit-format` | Auto-formats with Biome/Prettier/Pint/gofmt after every edit |
344
+ | `config-protection` | Blocks edits to linter/formatter config files |
345
+ | `console-log-warning` | Warns about `console.log`, `dd()`, `var_dump()` in modified files |
346
+ | `cost-tracker` | Logs session metadata to `.claude/sessions/cost-log.jsonl` |
347
+ | `safety-guard` | Enforces `/sk:safety-guard` freeze/careful mode |
430
348
 
431
- If starting on an unfamiliar codebase:
432
- ```
433
- /sk:reverse-doc architecture src/
434
- ```
435
- `/sk:reverse-doc` reads your code and generates architecture documentation — maps layers, traces data flow, asks clarifying questions to distinguish intentional design from accidental implementation. Run it once when you join a codebase or after a long break.
349
+ ---
436
350
 
437
- ### Feature Development (The Core Loop)
351
+ ## Path-Scoped Rules
438
352
 
439
- **Step 1 — Before writing the plan, use the `architect` agent on complex tasks:**
440
- ```
441
- Use the architect agent: analyze the authentication system and propose an approach for adding OAuth
442
- ```
443
- The `architect` agent reads your findings, lessons, and existing code — then proposes 2-3 options with trade-offs. This prevents architectural mistakes before a single line is written.
353
+ Rule files in `.claude/rules/` auto-activate in Claude Code when you edit matching files — no manual context loading.
444
354
 
445
- **Step 2 — For database changes, use the `database-architect` agent first:**
446
- ```
447
- Use the database-architect agent: review the proposed users table changes
448
- ```
449
- Gets you a migration safety classification (Safe / Careful / Breaking), index recommendations, and a deployment plan before `/sk:schema-migrate` runs.
355
+ | Rule file | Activates when editing | Enforces |
356
+ |---|---|---|
357
+ | `laravel.md` | `app/**/*.php`, `routes/**`, `config/**` | Laravel conventions, Eloquent patterns |
358
+ | `react.md` | `**/*.tsx`, `**/*.jsx` | Hooks rules, component patterns, TypeScript strictness |
359
+ | `vue.md` | `**/*.vue`, `resources/js/**` | Composition API only, `<script setup>`, Pinia |
360
+ | `tests.md` | `tests/**`, `**/*.test.*`, `**/*.spec.*` | TDD standards, assertion quality, test isolation |
361
+ | `api.md` | `routes/api.php`, `app/Http/Controllers/**` | RESTful conventions, auth patterns, error shapes |
362
+ | `migrations.md` | `database/migrations/**`, `prisma/**` | Migration safety, reversibility, index naming |
450
363
 
451
- **Step 3 — Run the standard workflow:**
452
- ```
453
- /sk:start ← classifies task, routes to optimal flow
454
- /sk:brainstorm ← explore requirements, extract checklist
455
- /sk:write-plan ← decision-complete plan (auto-generates contracts.md for API tasks)
456
- /sk:branch ← feature branch auto-named from task
457
- /sk:write-tests ← TDD red: failing tests first
458
- /sk:execute-plan ← TDD green: implement to pass tests
459
- /sk:smart-commit ← conventional commit with approval
460
- /sk:gates ← all 6 quality gates in parallel batches
461
- /sk:finish-feature ← changelog + PR + arch log
462
- ```
364
+ ---
463
365
 
464
- **For full-stack features — run `/sk:team` instead of execute-plan:**
465
- ```
466
- /sk:team
467
- ```
468
- Spawns `backend-dev`, `frontend-dev`, and `qa-engineer` in parallel worktrees. Backend implements the API, frontend mocks and builds UI, QA writes E2E scenarios — simultaneously. Results merge after all complete.
366
+ ## MCP Servers
469
367
 
470
- ### During Gates — When Things Fail
368
+ Installed optionally by `/sk:setup-claude` and `/sk:setup-optimizer`.
471
369
 
472
- **Perf gate fails with Critical issues:**
473
- ```
474
- Use the performance-optimizer agent: fix the N+1 queries found in /sk:perf
475
- ```
476
- The `performance-optimizer` agent reads `tasks/perf-findings.md`, implements fixes, and runs tests to confirm no regression. Works in an isolated worktree.
370
+ | Server | What it does | Best for |
371
+ |---|---|---|
372
+ | **Sequential Thinking** | Structured reasoning scratchpad — Claude thinks through hard problems step-by-step without cluttering the conversation | `/sk:brainstorm`, `/sk:debug`, `/sk:review` |
373
+ | **Context7** | Fetches current, version-accurate docs for libraries you're using — no stale API suggestions | React 19, Next.js 15, Tailwind v4, shadcn/ui |
374
+ | **ccstatusline** | Persistent statusline: context window %, model, git branch, current task | Every session |
477
375
 
478
- **Security gate blocks with High findings:**
479
- ```
480
- Use the security-reviewer agent: audit the auth changes
481
- ```
482
- The `security-reviewer` agent runs a focused OWASP audit. Its memory is `user`-scoped — it remembers security patterns across ALL your projects.
376
+ ---
483
377
 
484
- **Review gate blocks:**
485
- ```
486
- Use the code-reviewer agent
487
- ```
488
- 7-dimension review: correctness, security, performance, reliability, design, best practices, testing. Tells you exactly what to fix.
378
+ ## On-Demand Tools
489
379
 
490
- ### After Shipping
380
+ Use these anytime outside of the main workflow.
491
381
 
492
- ```
493
- /sk:learn ← extract reusable patterns from the session (confidence-scored)
494
- /sk:retro ← velocity, blockers, patterns, 3-5 action items
495
- ```
382
+ ### Intelligence
496
383
 
497
- `/sk:learn` is the compounding step. Each session adds patterns that future sessions apply automatically. Over time, you stop repeating the same mistakes.
384
+ | Command | Usage | What it does |
385
+ |---|---|---|
386
+ | `/sk:learn` | `/sk:learn` | Extract reusable patterns from the session with confidence scoring (0.3–0.9) |
387
+ | `/sk:learn` | `/sk:learn --list` | Show all learned patterns |
388
+ | `/sk:eval` | `/sk:eval define auth` | Define eval criteria before coding |
389
+ | `/sk:eval` | `/sk:eval check auth` | Run evals during implementation |
390
+ | `/sk:health` | `/sk:health` | Scorecard across 7 categories (0–70) |
391
+ | `/sk:context-budget` | `/sk:context-budget` | Audit token consumption across skills, agents, CLAUDE.md |
498
392
 
499
- ### Maintenance Workflows
393
+ ### Session Management
500
394
 
501
- **Codebase cleanup:**
502
- ```
503
- Use the refactor-specialist agent: clean up the authentication module
504
- ```
505
- The `refactor-specialist` runs tests before starting, makes behavior-preserving changes one at a time, runs tests after each change, and commits with `refactor(scope): description`. If tests go red, it reverts and reports.
395
+ | Command | Usage | What it does |
396
+ |---|---|---|
397
+ | `/sk:save-session` | `/sk:save-session` | Save branch, task, progress to `.claude/sessions/` |
398
+ | `/sk:resume-session` | `/sk:resume-session --latest` | Restore most recent session |
399
+ | `/sk:context` | `/sk:context` | Load all project context (automatic via hooks) |
506
400
 
507
- **Documentation gaps:**
508
- ```
509
- Use the tech-writer agent: document the payment service API
510
- ```
511
- The `tech-writer` reads code first, never invents behavior, and produces README, API docs, or architecture docs in your project's existing style.
401
+ ### Safety
512
402
 
513
- **Mobile store submission:**
514
- ```
515
- Use the mobile-dev agent: prepare the iOS release
516
- /sk:release --ios
517
- ```
403
+ | Command | Usage | What it does |
404
+ |---|---|---|
405
+ | `/sk:safety-guard` | `careful` | Block destructive commands |
406
+ | `/sk:safety-guard` | `freeze --dir src/` | Lock edits to a directory |
407
+ | `/sk:safety-guard` | `off` | Disable all guards |
518
408
 
519
- **Infrastructure changes:**
520
- ```
521
- Use the devops-engineer agent: set up Docker for local development
522
- /sk:ci ← or update CI workflows
523
- ```
409
+ ### Code Quality
524
410
 
525
- ### Health Checks (Weekly/Monthly)
411
+ | Command | When to use |
412
+ |---|---|
413
+ | `/sk:scope-check` | Mid-implementation — detect scope creep |
414
+ | `/sk:retro` | After shipping — velocity, blockers, action items |
415
+ | `/sk:seo-audit` | Web projects — SEO audit against source + dev server |
526
416
 
527
- ```
528
- /sk:health ← scorecard across 7 categories (0-70)
529
- /sk:setup-optimizer ← update CLAUDE.md, deploy missing agents/rules/hooks
530
- ```
417
+ ### Setup & Docs
531
418
 
532
- `/sk:health` scores your project setup. `< 50` means you're leaving significant reliability on the table. `/sk:setup-optimizer` fixes the gaps.
419
+ | Command | When to use |
420
+ |---|---|
421
+ | `/sk:reverse-doc` | New to a codebase — generate architecture/design/API docs from existing code |
422
+ | `/sk:setup-optimizer` | Monthly — update CLAUDE.md, deploy missing agents, hooks, rules |
423
+ | `/sk:ci` | Once per repo — GitHub Actions or GitLab CI with PR review + nightly audits |
424
+ | `/sk:plugin` | Distribute — package custom skills/agents/hooks as a shareable Claude Code plugin |
425
+ | `/sk:mvp` | New idea — generate a complete MVP app from a single prompt |
426
+ | `/sk:website` | Client work — build a full multi-page marketing site from a brief or URL |
533
427
 
534
428
  ---
535
429
 
536
- ### Summary: Which Tool for Which Situation
537
-
538
- | Situation | What to reach for |
539
- |-----------|------------------|
540
- | Starting a feature | `/sk:start` → `/sk:brainstorm` |
541
- | Complex architecture decision | `architect` agent before `/sk:write-plan` |
542
- | Database schema change | `database-architect` agent before `/sk:schema-migrate` |
543
- | Full-stack feature | `/sk:team` (parallel agents) |
544
- | Performance issues | `performance-optimizer` agent |
545
- | Security review | `security-reviewer` agent |
546
- | Code review | `code-reviewer` agent |
547
- | Bug investigation | `/sk:debug` + `debugger` agent |
548
- | Codebase cleanup | `refactor-specialist` agent |
549
- | Missing docs | `tech-writer` agent + `/sk:reverse-doc` |
550
- | CI/CD setup | `/sk:ci` + `devops-engineer` agent |
551
- | Mobile feature | `mobile-dev` agent |
552
- | New to a codebase | `/sk:reverse-doc` first |
553
- | Session start | Hooks auto-run, or `/sk:context` |
554
- | After shipping | `/sk:learn` + `/sk:retro` |
555
- | Monthly maintenance | `/sk:health` + `/sk:setup-optimizer` |
430
+ ## Stack Support
431
+
432
+ | Area | Supported |
433
+ |---|---|
434
+ | **Frameworks** | Laravel, Next.js, Nuxt, React, Vue, Node.js |
435
+ | **Linters** | Pint, ESLint, PHPStan, Rector, Prettier, Biome |
436
+ | **Test runners** | Pest, PHPUnit, Jest, Vitest, Playwright |
437
+ | **Schema / ORM** | Prisma, Drizzle, Eloquent, SQLAlchemy, ActiveRecord |
438
+ | **Release** | npm, Composer, iOS (App Store), Android (Play Store) |
556
439
 
557
440
  ---
558
441
 
559
442
  ## All Commands
560
443
 
561
444
  <details>
562
- <summary><strong>54 commands</strong> — click to expand</summary>
445
+ <summary><strong>43 skills + 13 agents</strong> — click to expand</summary>
563
446
 
564
447
  | Command | Purpose |
565
- |---------|---------|
448
+ |---|---|
566
449
  | `/sk:accessibility` | WCAG 2.1 AA audit |
567
450
  | `/sk:api-design` | Design API contracts before implementation |
568
451
  | `/sk:autopilot` | Hands-free workflow — auto-skip, auto-advance, auto-commit |
569
- | `/sk:brainstorm` | Explore requirements and design; extracts requirements checklist |
452
+ | `/sk:brainstorm` | Explore requirements and design |
570
453
  | `/sk:branch` | Create feature branch from current task |
571
454
  | `/sk:change` | Handle mid-workflow requirement changes |
455
+ | `/sk:ci` | Set up GitHub Actions / GitLab CI |
572
456
  | `/sk:config` | View/edit project config |
573
- | `/sk:context` | Load project context (automatic via hooks) |
457
+ | `/sk:context` | Load project context |
574
458
  | `/sk:context-budget` | Audit context window token consumption |
575
- | `/sk:dashboard` | Live Kanban board — sk:dashboard across worktrees |
459
+ | `/sk:dashboard` | Live Kanban board across worktrees |
576
460
  | `/sk:debug` | Structured bug investigation |
577
- | `/sk:e2e` | E2E Tests — behavioral verification |
578
- | `/sk:eval` | Define, run, and report evals for agent reliability |
579
- | `/sk:execute-plan` | Execute plan checkboxes in batches with status checkpoints |
461
+ | `/sk:e2e` | E2E behavioral verification |
462
+ | `/sk:eval` | Define, run, and report evals |
463
+ | `/sk:execute-plan` | Execute plan checkboxes in batches |
580
464
  | `/sk:fast-track` | Small changes — skip planning, keep gates |
581
465
  | `/sk:features` | Sync feature specs with codebase |
582
466
  | `/sk:finish-feature` | Changelog + PR |
583
467
  | `/sk:frontend-design` | UI mockup + optional Pencil visual design |
584
- | `/sk:gates` | All quality gates in parallel batches with batch checkpoints |
468
+ | `/sk:gates` | All quality gates in parallel batches |
585
469
  | `/sk:health` | Harness self-audit scorecard |
586
470
  | `/sk:help` | Show all commands |
587
471
  | `/sk:hotfix` | Emergency fix workflow |
@@ -592,31 +476,30 @@ Use the devops-engineer agent: set up Docker for local development
592
476
  | `/sk:mvp` | Generate MVP app from a prompt |
593
477
  | `/sk:perf` | Performance audit |
594
478
  | `/sk:plan` | Create/refresh planning files |
479
+ | `/sk:plugin` | Package skills/agents/hooks as a plugin |
595
480
  | `/sk:release` | Version bump + tag (`--android` / `--ios` for store audit) |
596
481
  | `/sk:resume-session` | Resume a previously saved session |
597
482
  | `/sk:retro` | Post-ship retrospective |
598
483
  | `/sk:reverse-doc` | Generate docs from existing code |
599
- | `/sk:review` | 7-dimension code review with `<think>` reasoning and exhaustiveness |
484
+ | `/sk:review` | 7-dimension code review |
600
485
  | `/sk:safety-guard` | Protect against destructive ops |
601
486
  | `/sk:save-session` | Save session state for continuity |
602
487
  | `/sk:schema-migrate` | Database schema change analysis |
603
488
  | `/sk:scope-check` | Detect scope creep mid-implementation |
604
- | `/sk:security-check` | OWASP security audit with content isolation and CVSS scoring |
605
- | `/sk:ci` | Set up Claude Code GitHub Actions or GitLab CI — PR review, issue triage, nightly audits, release automation |
606
- | `/sk:plugin` | Package custom skills, agents, and hooks as a distributable Claude Code plugin |
489
+ | `/sk:security-check` | OWASP security audit with CVSS scoring |
607
490
  | `/sk:seo-audit` | SEO audit for web projects |
608
491
  | `/sk:set-profile` | Switch model routing profile |
609
- | `/sk:website` | Build a complete, client-deliverable multi-page marketing website from a brief or URL. Supports `--stack nuxt`, `--stack laravel`, `--deploy`, `--revise`. Full guide: `docs/guides/sk-website-guide.md` |
610
492
  | `/sk:setup-claude` | Bootstrap project scaffolding |
611
- | `/sk:setup-optimizer` | Diagnose + update workflow + deploy hooks + enrich CLAUDE.md |
493
+ | `/sk:setup-optimizer` | Update workflow, agents, hooks, CLAUDE.md |
612
494
  | `/sk:skill-creator` | Create or improve skills |
613
495
  | `/sk:smart-commit` | Conventional commit with approval |
614
- | `/sk:start` | Smart entry point — classifies task, routes to optimal flow |
496
+ | `/sk:start` | Smart entry point — classifies task, routes to flow |
615
497
  | `/sk:status` | Show workflow + task status |
616
498
  | `/sk:team` | Parallel domain agents for full-stack tasks |
617
499
  | `/sk:test` | Run all test suites |
618
500
  | `/sk:update-task` | Mark task done |
619
- | `/sk:write-plan` | Write plan to `tasks/todo.md`; auto-generates `tasks/contracts.md` for API tasks |
501
+ | `/sk:website` | Build a full multi-page marketing site |
502
+ | `/sk:write-plan` | Write plan to `tasks/todo.md` |
620
503
  | `/sk:write-tests` | TDD: write failing tests first |
621
504
 
622
505
  </details>
@@ -626,12 +509,11 @@ Use the devops-engineer agent: set up Docker for local development
626
509
  ## Learn More
627
510
 
628
511
  | Topic | Where |
629
- |-------|-------|
630
- | Detailed workflow steps (8-step flow) | [DOCUMENTATION.md](.claude/docs/DOCUMENTATION.md) |
512
+ |---|---|
513
+ | Detailed 8-step workflow | [DOCUMENTATION.md](.claude/docs/DOCUMENTATION.md) |
631
514
  | Feature specifications | [docs/FEATURES.md](docs/FEATURES.md) |
632
515
  | Model routing profiles & config | [DOCUMENTATION.md — Config](.claude/docs/DOCUMENTATION.md#config-reference) |
633
516
  | Infrastructure (hooks, agents, rules) | [DOCUMENTATION.md — Setup](.claude/docs/DOCUMENTATION.md#what-gets-created) |
634
- | Security & permissions | [DOCUMENTATION.md — Security](.claude/docs/DOCUMENTATION.md#security) |
635
517
 
636
518
  ---
637
519
 
package/commands/sk/finish-feature.md CHANGED
@@ -155,6 +155,20 @@ If unresolved Critical/High findings remain, warn the user before proceeding.
155
155
 
156
156
  e) Report the PR URL to the user.
157
157
 
158
+ 8. **Capture Patterns** (`/sk:learn`)
159
+
160
+ After the PR is created, run `/sk:learn` to extract reusable patterns from this session.
161
+ Present extracted patterns and ask: "Save patterns? (all / 1,3 / none)"
162
+
163
+ 9. **Retrospective** (`/sk:retro`)
164
+
165
+ Run `/sk:retro` to capture a brief post-ship retrospective:
166
+ - What went well
167
+ - What slowed things down
168
+ - Top action items for next time
169
+
170
+ Output is appended to `tasks/progress.md`.
171
+
158
172
  ## When Done
159
173
 
160
174
  > "Feature finalized and PR created! Run `/sk:release` when ready to tag and publish."
package/commands/sk/help.md CHANGED
@@ -21,21 +21,19 @@ Run these commands in order for a complete, quality-gated feature build.
21
21
 
22
22
  ## Feature Workflow
23
23
 
24
- | Command | Purpose |
25
- |---------|---------|
26
- | `/sk:brainstorm` | Explore requirements and design — **no code yet** |
27
- | `/sk:write-plan` | Write a decision-complete plan to `tasks/todo.md` |
28
- | `/sk:branch` | Create a feature branch from the current task |
29
- | `/sk:schema-migrate` | Analyze schema changes *(skip if no DB changes)* |
30
- | `/sk:write-tests` | TDD red: write failing tests first |
31
- | `/sk:execute-plan` | TDD green: implement until tests pass |
32
- | `/sk:smart-commit` | Conventional commit with approval |
33
- | `/sk:lint` | **GATE** — all linters must pass |
34
- | `/sk:test` | **GATE** — 100% coverage on new code |
35
- | `/sk:security-check` | **GATE** — 0 security issues |
36
- | `/sk:review` | **GATE** — blast-radius-aware self-review across 7 dimensions + cross-file impact |
37
- | `/sk:update-task` | Mark task done, log completion |
38
- | `/sk:finish-feature` | Changelog + PR creation |
24
+ | # | Command | Purpose |
25
+ |---|---------|---------|
26
+ | 1 | `/sk:brainstorm` | Explore requirements — **no code yet** |
27
+ | 2 | `/sk:frontend-design` or `/sk:api-design` | Design UI or API contracts *(auto-skip if no frontend/API keywords)* |
28
+ | 3 | `/sk:write-plan` | Write a decision-complete plan to `tasks/todo.md` |
29
+ | 4 | `/sk:branch` | Create a feature branch from the current task |
30
+ | 5 | `/sk:write-tests` + `/sk:execute-plan` | TDD red + green (includes `/sk:schema-migrate` if DB keywords detected) |
31
+ | 5.5 | `/sk:scope-check` | Trim scope creep — compare implementation to plan |
32
+ | 6 | `/sk:smart-commit` | Conventional commit with approval |
33
+ | 7 | `/sk:gates` | **All quality gates** — lint, test, security, perf, review, e2e *(hard gate)* |
34
+ | 8 | `/sk:finish-feature` | Changelog + PR creation |
35
+ | 8.5 | `/sk:learn` | Extract reusable patterns from this session |
36
+ | 8.6 | `/sk:retro` | Post-ship retrospective — velocity, blockers, next actions |
39
37
 
40
38
  ## Requirement Change Flow
41
39
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kennethsolomon/shipkit",
3
- "version": "3.17.0",
3
+ "version": "3.18.0",
4
4
  "description": "A structured workflow toolkit for Claude Code.",
5
5
  "keywords": [
6
6
  "claude",
package/skills/sk:autopilot/SKILL.md CHANGED
@@ -1,12 +1,12 @@
1
1
  ---
2
2
  name: sk:autopilot
3
- description: Hands-free workflow — runs all 8 steps with auto-skip, auto-advance, auto-commit. Stops only for direction approval, 3-strike failures, and PR push.
3
+ description: Hands-free workflow — runs all 8 phases (including scope check, learn, retro) with auto-skip, auto-advance, auto-commit. Stops only for direction approval, 3-strike failures, and PR push.
4
4
  allowed-tools: Read, Write, Bash, Glob, Grep, Agent, Skill
5
5
  ---
6
6
 
7
7
  # Autopilot Mode
8
8
 
9
- Hands-free workflow that executes all 8 steps of the ShipIt workflow with minimal interruptions. Same quality gates, same fix loops, same 100% coverage — just fewer stops.
9
+ Hands-free workflow that executes all 8 phases (including scope check, learn, and retro) of the ShipIt workflow with minimal interruptions. Same quality gates, same fix loops, same 100% coverage — just fewer stops.
10
10
 
11
11
  ## When to Use
12
12
 
@@ -22,7 +22,7 @@ Hands-free workflow that executes all 8 steps of the ShipIt workflow with minima
22
22
 
23
23
  ## Quality Guarantee
24
24
 
25
- Autopilot runs the EXACT same 8 steps as manual mode:
25
+ Autopilot runs the EXACT same workflow as manual mode (8 phases: explore, design, plan, branch, implement + scope check, commit, gates, ship + learn + retro):
26
26
  - ALL quality gates enforced (lint, test, security, perf, review, e2e)
27
27
  - ALL fix-rerun loops active
28
28
  - 100% test coverage required on new code
@@ -64,6 +64,13 @@ Create feature branch auto-named from the task. Do NOT ask for confirmation.
64
64
  - Run `/sk:execute-plan` (TDD green phase)
65
65
  - Auto-advance when done
66
66
 
67
+ ### 5.5. Scope Check (auto-advance)
68
+
69
+ Run `/sk:scope-check` to compare the implementation against `tasks/todo.md`.
70
+
71
+ - If scope creep detected: log findings, trim the excess, re-commit
72
+ - If on-scope: auto-advance silently
73
+
67
74
  ### 6. Commit (auto-commit)
68
75
 
69
76
  Auto-commit with conventional commit format. Do NOT ask for commit message approval.
@@ -96,6 +103,20 @@ After confirmation:
96
103
  - Sync features (`/sk:features`)
97
104
  - Ask about release (never auto-skipped)
98
105
 
106
+ ### 8.5. Learn (auto-advance)
107
+
108
+ Run `/sk:learn` to extract reusable patterns from this session.
109
+
110
+ - Patterns are saved to `~/.claude/skills/learned/` automatically
111
+ - Auto-advance after saving — no confirmation needed in autopilot
112
+
113
+ ### 8.6. Retro (auto-advance)
114
+
115
+ Run `/sk:retro` to capture velocity, blockers, and action items for this feature.
116
+
117
+ - Output is brief — 3-5 bullets covering what went well, what slowed down, and next actions
118
+ - Appended to `tasks/progress.md`
119
+
99
120
  ## 3-Strike Protocol
100
121
 
101
122
  If any step fails 3 times:
@@ -111,6 +132,7 @@ If any step fails 3 times:
111
132
  | Direction approval | After brainstorm (step 1) | User must approve the approach |
112
133
  | 3-strike failure | Any step fails 3x | Needs human judgment |
113
134
  | PR push | Before creating PR (step 8) | Visible to others — always confirm |
135
+ | Release | After step 8.6 | Never auto-skipped — always ask |
114
136
 
115
137
  Everything else auto-advances.
116
138
 
package/skills/sk:gates/SKILL.md CHANGED
@@ -10,7 +10,7 @@ Run all quality gates (lint, test, security, perf, review, e2e) in optimized bat
10
10
 
11
11
  ## When to Use
12
12
 
13
- Run `/sk:gates` after committing implementation code (step 11). This single command handles steps 12-17 of the workflow.
13
+ Run `/sk:gates` after `/sk:smart-commit` completes (step 6). This single command covers all quality gates (step 7 of the workflow).
14
14
 
15
15
  ## Execution Strategy
16
16
 
@@ -23,6 +23,7 @@ Launch 3 agents simultaneously:
23
23
  1. **Linter agent** — runs all formatters, analyzers, dep audits
24
24
  2. **`security-reviewer` agent** — OWASP audit on changed files (read-only; reports findings, does not fix)
25
25
  3. **`performance-optimizer` agent** — bundle, N+1, Core Web Vitals, memory (worktree isolation — finds AND fixes critical/high issues)
26
+ **Auto-skip:** If NO frontend keywords (component, view, page, CSS, UI, form, modal, button, react, vue, svelte, blade) AND NO database keywords (migration, schema, table, column, model, database, foreign key, index, seed) appear in `tasks/todo.md`, skip this agent and log: `Auto-skipped: Performance (no frontend or database keywords in plan)`.
26
27
 
27
28
  These 3 have no dependencies on each other. Run them in parallel using the Agent tool.
28
29
 
package/skills/sk:setup-claude/templates/CLAUDE.md.template CHANGED
@@ -51,9 +51,12 @@ Progress is tracked via git branch + `tasks/todo.md` checkboxes.
51
51
  | 3 | Plan | `/sk:write-plan` | required |
52
52
  | 4 | Branch | `/sk:branch` | required |
53
53
  | 5 | Write Tests + Implement | `/sk:write-tests` then `/sk:execute-plan` | required |
54
+ | 5.5 | Scope Check | `/sk:scope-check` | required |
54
55
  | 6 | Commit | `/sk:smart-commit` | required |
55
56
  | 7 | Gates | `/sk:gates` | required (hard gate) |
56
57
  | 8 | Finalize | `/sk:finish-feature` | required |
58
+ | 8.5 | Learn | `/sk:learn` | required |
59
+ | 8.6 | Retro | `/sk:retro` | required |
57
60
 
58
61
  ### Step Details
59
62
 
@@ -62,9 +65,12 @@ Progress is tracked via git branch + `tasks/todo.md` checkboxes.
62
65
  3. **Plan** — run `/sk:write-plan` to write a decision-complete plan into `tasks/todo.md`. No code in this step. After the plan is written, auto-skip detection runs for step 2 if not already done.
63
66
  4. **Branch** — run `/sk:branch` to create a feature branch auto-named from the current task.
64
67
  5. **Write Tests + Implement** — run `/sk:write-tests` (TDD red phase), then `/sk:execute-plan` (TDD green phase). Includes `/sk:schema-migrate` if database keywords detected in the plan. Log progress to `tasks/progress.md`.
68
+ 5.5. **Scope Check** — run `/sk:scope-check` to compare implementation against `tasks/todo.md`. Trim scope creep before committing.
65
69
  6. **Commit** — run `/sk:smart-commit` to commit tests + implementation.
66
70
  7. **Gates** — run `/sk:gates` to execute all quality gates in optimized parallel batches (lint, test, security, perf, review, e2e). This is a **hard gate** — blocks all forward progress until every check passes. Individual gate commands (`/sk:lint`, `/sk:test`, `/sk:security-check`, `/sk:perf`, `/sk:review`, `/sk:e2e`) are still available standalone.
67
71
  8. **Finalize** — run `/sk:finish-feature` for changelog, PR creation, `/sk:update-task`, `/sk:features` sync. Ask about `/sk:release` (never auto-skipped).
72
+ 8.5. **Learn** — run `/sk:learn` to extract reusable patterns from the session into `~/.claude/skills/learned/`.
73
+ 8.6. **Retro** — run `/sk:retro` for a brief post-ship retrospective (velocity, blockers, next actions).
68
74
 
69
75
  ### Workflow Rules
70
76
 
@@ -286,7 +292,7 @@ Create entries in: `[ARCH_CHANGELOG_DIR]`
286
292
  |---------|---------|
287
293
  | `/sk:accessibility` | WCAG 2.1 AA audit — runs after design, before implementation |
288
294
  | `/sk:api-design` | Design API contracts (endpoints, payloads, auth, errors) before implementation |
289
- | `/sk:autopilot` | Hands-free workflow — all 8 steps, auto-skip, auto-advance, auto-commit |
295
+ | `/sk:autopilot` | Hands-free workflow — all 8 phases (scope check, learn, retro included), auto-skip, auto-advance, auto-commit |
290
296
  | `/sk:brainstorm` | Explore requirements and design (includes search-first research) |
291
297
  | `/sk:branch` | Create feature branch auto-named from current task |
292
298
  | `/sk:change` | Handle mid-workflow requirement changes — re-enter at correct step |
package/skills/sk:setup-optimizer/SKILL.md CHANGED
@@ -44,7 +44,7 @@ Before making any changes, runs a diagnostic pass on the existing CLAUDE.md:
44
44
  - **Stale content** — detects outdated info (stale model/route counts, removed dependencies, old command names like `/laravel-lint` instead of `/sk:lint`)
45
45
  - **Inconsistencies** — compares documented vs actual project state (directories, scripts, workflows)
46
46
  - **Section completeness** — flags sections that exist but are empty or have only placeholder text
47
- - **Outdated workflow** — checks if the workflow matches the current 8-step flow with `/sk:gates` as single gate step
47
+ - **Outdated workflow** — checks if the workflow matches the current 11-step flow (1, 2, 3, 4, 5, 5.5, 6, 7, 8, 8.5, 8.6) with `/sk:gates` as single gate step
48
48
  - **Missing commands** — checks for `sk:start`, `sk:autopilot`, `sk:team`, `sk:learn`, `sk:context-budget`, `sk:health`, `sk:save-session`, `sk:resume-session`, `sk:safety-guard`, `sk:eval`, `sk:ci`, `sk:plugin` in the Commands table
49
49
  - **Missing agents** — checks if `.claude/agents/` exists and contains the 13 core agents: `backend-dev`, `frontend-dev`, `mobile-dev`, `qa-engineer`, `code-reviewer`, `security-reviewer`, `performance-optimizer`, `architect`, `database-architect`, `devops-engineer`, `debugger`, `refactor-specialist`, `tech-writer`
50
50
  - **Missing rules** — checks if `.claude/rules/` exists and contains the project-relevant rule files based on detected stack (laravel.md, react.md, vue.md, tests.md, api.md, migrations.md)
@@ -59,13 +59,13 @@ Reports findings before proceeding. If issues are found, they inform subsequent
59
59
 
60
60
  If the workflow section is outdated or missing, replace it with the latest version:
61
61
 
62
- **Current workflow (8 steps, TDD with `/sk:gates` as single gate step):**
62
+ **Current workflow (11 steps, TDD with `/sk:gates` as single gate step):**
63
63
  ```
64
- Explore → Design → Plan → Branch → Write Tests + Implement → Commit → Gates → Finalize
64
+ Explore → Design → Plan → Branch → Write Tests + Implement → Scope Check → Commit → Gates → Finalize + Learn + Retro
65
65
  ```
66
66
 
67
67
  **What gets updated:**
68
- - Workflow table (8 steps — `/sk:brainstorm`, `/sk:frontend-design` or `/sk:api-design`, `/sk:write-plan`, `/sk:branch`, `/sk:write-tests` + `/sk:execute-plan`, `/sk:smart-commit`, `/sk:gates`, `/sk:finish-feature`)
68
+ - Workflow table (11 steps — `/sk:brainstorm`, `/sk:frontend-design` or `/sk:api-design`, `/sk:write-plan`, `/sk:branch`, `/sk:write-tests` + `/sk:execute-plan`, `/sk:scope-check`, `/sk:smart-commit`, `/sk:gates`, `/sk:finish-feature`, `/sk:learn`, `/sk:retro`)
69
69
  - Step details (TDD red/green/verify descriptions)
70
70
  - Workflow rules (auto-advance, conditional summary, auto-skip, squash gate commits)
71
71
  - Bug fix flow section (7 steps)
package/skills/sk:start/SKILL.md CHANGED
@@ -32,7 +32,7 @@ Read the task description from arguments. Scan for signal keywords to determine
32
32
  | bug, fix, broken, error, regression, failing, crash, wrong | `debug` (7 steps) |
33
33
  | urgent, prod down, hotfix, emergency, critical, production, incident | `hotfix` (6 steps) |
34
34
  | config, bump, typo, copy, rename, dependency, upgrade, version, docs | `fast-track` (5 steps) |
35
- | *(default — no special signals)* | `feature` (8 steps) |
35
+ | *(default — no special signals)* | `feature` (8 phases + scope check, learn, retro) |
36
36
 
37
37
  **Scope detection:**
38
38
 
@@ -84,7 +84,7 @@ Present the classification and recommendation:
84
84
  ```
85
85
  Detected: [Full-stack feature / Backend bug fix / Frontend hotfix / Small config change / etc.]
86
86
  Recommended:
87
- Flow: [feature (8 steps) / debug (7 steps) / hotfix (6 steps) / fast-track (5 steps)]
87
+ Flow: [feature (8 phases) / debug (7 steps) / hotfix (6 steps) / fast-track (5 steps)]
88
88
  Mode: [autopilot / manual]
89
89
  Agents: [team (backend + frontend + QA) / solo]
90
90
 
package/skills/sk:team/SKILL.md CHANGED
@@ -106,7 +106,7 @@ If both agents used worktree isolation and made changes:
106
106
 
107
107
  ### 5. Collect QA Agent Results
108
108
 
109
- Collect the QA Agent's E2E scenarios. These will be used in the E2E gate (step 17).
109
+ Collect the QA Agent's E2E scenarios. These will be used in the E2E gate (step 7 / Batch 4).
110
110
 
111
111
  ### 6. Report Results
112
112