@kennethsolomon/shipkit 3.0.1 → 3.0.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenneth Solomon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,13 @@
+<div align="center">
+
 # SHIPKIT
 
-A structured, quality-gated workflow system for Claude Code.
+**A structured, quality-gated workflow system for Claude Code.**
+
+Stop winging it. Ship features with TDD, auto-detecting linters, security audits,<br>
+and AI-powered code review — all wired into a single repeatable workflow.
 
-Ship features with TDD, auto-detecting linters, security audits, and AI-powered code review — all wired into a single repeatable workflow.
+**Every gate must pass. Quality isn't optional — it's structural.**
 
 [![npm](https://img.shields.io/npm/v/@kennethsolomon%2Fshipkit)](https://www.npmjs.com/package/@kennethsolomon/shipkit)
 [![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
@@ -14,78 +19,54 @@ npm install -g @kennethsolomon/shipkit && shipkit
 
 Works on Mac, Linux, and Windows.
 
-```
-~ $ shipkit
-
-           ⚑
-           |
-          /|\
-         / | \
-        /  |  \
-       /   |   \
-      / ☠  |  ☠ \
-     /     |     \
-    /______|______\
-  ▄████████████████▄
-  █  ◉          ◉  █
-   ▀██████████████▀
-     ≋  ≋  ≋  ≋  ≋
-
-  ShipKit v3.0.1
-  A structured workflow toolkit for Claude Code.
-  by Kenneth Solomon
-
-  ✓ Installed commands/sk (15 commands)
-  ✓ Installed skills (19 skills)
-
-  Done! Run /sk:help to get started.
-
-~ $
-```
+</div>
 
----
+<div align="center">
 
-> "Stop winging it. Ship with a system."
+![ShipKit terminal demo](assets/shipkit-terminal.png)
+
+</div>
 
 ---
 
-## How It Works
+<div align="center">
+
+*"Ran `/sk:review` on what I thought was done. It found 3 things I would have caught in production. Now it's in every merge."*
 
-ShipKit installs a set of slash commands and skills into your Claude Code config (`~/.claude/`). Each command is a focused instruction set that Claude follows — no magic, just structured prompts that enforce quality gates.
+*"Every other Claude workflow I tried was either too rigid or too vague. ShipKit is the first one that actually ships."*
 
-The workflow is linear: **Explore → Design → Plan → Branch → Test → Implement → Lint → Verify → Security → Review → Ship.**
+*"The gates feel annoying until the day they catch something real. Now I don't merge without them."*
 
-Every gate must pass before the next step. If lint fails, you fix it. If tests don't cover new code, you write them. Security issues block the PR. This isn't optional — it's the whole point.
+</div>
 
 ---
 
-## Installation
+## Quick Start
 
 ```bash
+# 1. Install ShipKit globally
 npm install -g @kennethsolomon/shipkit && shipkit
-```
 
-Or clone and install locally (symlinks — changes reflect immediately):
+# 2. Bootstrap your project (run inside your project directory)
+/sk:setup-claude
 
-```bash
-git clone https://github.com/kennethsolomon/shipkit.git
-cd shipkit
-./install.sh
+# 3. Start your first feature
+/sk:brainstorm
 ```
 
-### Update
+`/sk:setup-claude` creates `tasks/todo.md`, `tasks/lessons.md`, and a project-specific `CLAUDE.md` with the full workflow baked in. Run it once per project.
 
-```bash
-npm install -g @kennethsolomon/shipkit && shipkit
-```
+---
 
-Re-running always installs the latest version.
+## How It Works
 
-### Uninstall
+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.
 
-```bash
-shipkit --uninstall
-```
+The workflow is linear: **Brainstorm → Plan → Branch → Test → Implement → Lint → Security → Review → Ship.**
+
+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.
+
+**Requirements change mid-workflow?** Run `/sk:change`. It assesses the scope and tells you exactly where to re-enter — no guessing, no skipping steps.
 
 ---
 
@@ -164,6 +145,22 @@ Debug → Branch → Fix → Smoke Test → Lint ✓ → Test ✓ → Security
 
 After merging: add a regression test and a lesson to `tasks/lessons.md`.
 
+### Requirement Change Flow
+
+Requirements change mid-workflow all the time. Run `/sk:change` whenever something shifts — it classifies the scope and routes you back to the right step automatically.
+
+```
+Requirement changes → /sk:change → re-enter at correct step
+```
+
+| Tier | What changed | Re-entry point |
+|------|-------------|----------------|
+| **Tier 1** — Behavior Tweak | Logic changes, scope stays the same *(e.g. delete all → delete users only)* | `/sk:write-tests` |
+| **Tier 2** — New Requirements | New scope, new constraints, new acceptance criteria | `/sk:write-plan` |
+| **Tier 3** — Scope Shift | Fundamental rethinking of approach or architecture | `/sk:brainstorm` |
+
+`/sk:change` logs the change to `tasks/todo.md` and `tasks/progress.md`, marks invalidated tasks, and tells you exactly what to carry forward.
+
 ---
 
 ## Commands
@@ -189,6 +186,7 @@ After merging: add a regression test and a lesson to `tasks/lessons.md`.
 | `/sk:schema-migrate` | Analyze pending schema changes (Prisma, Drizzle, Eloquent, SQLAlchemy, ActiveRecord) |
 | `/sk:write-tests` | TDD: write failing tests before implementation |
 | `/sk:execute-plan` | Implement the plan in small batches |
+| `/sk:change` | Handle a mid-workflow requirement change — assess scope and re-enter at the right step |
 | `/sk:debug` | Structured bug investigation: reproduce → isolate → fix |
 | `/sk:hotfix` | Emergency fix workflow — skips design and TDD |
 
@@ -238,8 +236,14 @@ After merging: add a regression test and a lesson to `tasks/lessons.md`.
 
 ## Model Routing Profiles
 
-ShipKit routes each skill to the right model automatically based on your project profile.
-Set it once with `/sk:set-profile <name>` — config is saved to `.shipkit/config.json`.
+ShipKit routes each skill to the right model automatically. Set it once per project:
+
+```bash
+/sk:set-profile balanced   # default
+/sk:set-profile quality    # most projects
+/sk:set-profile full-sail  # high-stakes / client work
+/sk:set-profile budget     # side projects / exploration
+```
 
 | Profile | Philosophy | Best for |
 |---------|-----------|---------|
@@ -252,13 +256,14 @@ Set it once with `/sk:set-profile <name>` — config is saved to `.shipkit/confi
 |-------------|-----------|---------|----------|--------|
 | brainstorm, write-plan, debug, execute-plan, review | opus | opus | sonnet | sonnet |
 | write-tests, frontend-design, api-design, security-check | opus | sonnet | sonnet | sonnet |
+| change | opus | sonnet | sonnet | sonnet |
 | perf, schema-migrate, accessibility | opus | sonnet | sonnet | haiku |
 | lint, test | sonnet | sonnet | haiku | haiku |
 | smart-commit, branch, update-task | haiku | haiku | haiku | haiku |
 
-`opus` = inherit (uses your current session model).
+`opus` = inherit (uses your current session model). Config lives in `.shipkit/config.json` — per project, gitignored by default.
 
-### Other config settings
+### Config Reference
 
 ```json
 {
@@ -296,26 +301,41 @@ ShipKit auto-detects your stack — no configuration needed.
 
 ---
 
-## Project Setup
+## Security
 
-To wire ShipKit into a new project:
+ShipKit instructs Claude to audit your code — but Claude also has access to your filesystem. Protect sensitive files by adding a deny list to `.claude/settings.json` in your project:
 
-```
-/sk:setup-claude
+```json
+{
+  "permissions": {
+    "deny": [
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(**/*.pem)",
+      "Read(**/*.key)",
+      "Read(**/*.p12)",
+      "Read(**/credentials*)"
+    ]
+  }
+}
 ```
 
-This creates `tasks/todo.md`, `tasks/lessons.md`, and a project-specific `CLAUDE.md` with the full workflow baked in.
+This prevents Claude from reading secrets even if a prompt tries to access them. Pair this with your `.gitignore` — never commit `.env` files.
+
+If you discover a security issue in ShipKit itself, please open a [GitHub issue](https://github.com/kennethsolomon/shipkit/issues) or email directly rather than posting publicly.
 
 ---
 
-## Why ShipKit
+## License
 
-Claude Code is powerful but context degrades as the window fills. Unstructured sessions lead to skipped tests, no lint, missing security review, and PRs that broke things in ways nobody caught.
+MIT — see [LICENSE](LICENSE) for details.
 
-ShipKit fixes that with a repeatable system: every feature goes through the same gates in the same order. Quality isn't optional — it's structural.
+Built by [Kenneth Solomon](https://github.com/kennethsolomon).
 
 ---
 
-## License
+<div align="center">
+
+**Claude Code is powerful. ShipKit makes it reliable.**
 
-MIT — by [Kenneth Solomon](https://github.com/kennethsolomon)
+</div>

package/bin/shipkit.js

@@ -32,7 +32,8 @@ ${cyan}   ▀██████████████▀${reset}
 ${cyan}     ≋  ≋  ≋  ≋  ≋${reset}
 
   ${bold}ShipKit${reset} ${dim}v${pkg.version}${reset}
-  A structured workflow toolkit for Claude Code.
+  Quality-gated workflow toolkit for Claude Code.
+  TDD · Lint · Security · Review · Ship.
   by Kenneth Solomon
 
 `;

package/commands/sk/change.md

@@ -0,0 +1,135 @@
+---
+description: "Handle a mid-workflow requirement change — assess scope and re-enter at the right step."
+---
+
+# /sk:change
+
+Handle a requirement change that was discovered mid-workflow. Assesses the scope of the change and routes you back to the correct step — no over-restarting, no skipping.
+
+## Hard Rules
+
+- **DO NOT modify code or tests until this command completes.** The re-entry point must be determined first.
+- **DO NOT guess the scope.** Ask explicitly if unclear.
+- **Always update `tasks/todo.md` and `tasks/progress.md`** to record what changed and why before routing forward.
+
+## Steps
+
+### 1. Understand the Change
+
+Ask the user:
+- What changed? (describe the old behavior and the new behavior)
+- What triggered this change? (review finding, stakeholder feedback, edge case discovered, etc.)
+- Is this change isolated to one area, or does it affect multiple parts of the system?
+
+Do not proceed until you have clear answers.
+
+### 2. Assess the Scope
+
+Based on the answers, classify the change into one of three tiers:
+
+---
+
+**Tier 1 — Behavior Tweak**
+
+The logic changes but the scope and plan stay the same. Examples:
+- Delete all tables → delete only users table
+- Return 404 → return 403 on unauthorized access
+- Sort ascending → sort descending
+
+Re-entry point: **`/sk:write-tests`**
+
+Action: Update or replace the affected tests to reflect the new behavior. The existing plan is still valid — only the test assertions and implementation need to change.
+
+---
+
+**Tier 2 — New Requirements**
+
+New scope, new constraints, or new acceptance criteria that the current plan doesn't cover. Examples:
+- Simple delete → soft-delete with audit log
+- Basic auth → role-based permissions
+- Single endpoint → paginated + filterable endpoint
+
+Re-entry point: **`/sk:write-plan`**
+
+Action: Update `tasks/todo.md` with revised tasks. The brainstorm findings are still valid but the plan needs new steps. After plan approval, proceed to `/sk:write-tests`.
+
+---
+
+**Tier 3 — Scope Shift**
+
+Fundamental rethinking of the approach, user flow, or architecture. Examples:
+- Rethinking the entire delete flow and who can trigger it
+- Changing the data model the feature is built on
+- New understanding of the problem that invalidates prior decisions
+
+Re-entry point: **`/sk:brainstorm`**
+
+Action: The existing findings and plan may be partially or fully invalid. Start fresh from brainstorm, record new decisions in `tasks/findings.md`, then proceed through write-plan → write-tests → execute-plan.
+
+---
+
+### 3. Confirm the Tier
+
+Present your classification to the user:
+
+```
+Change detected: <1-line summary of what changed>
+Scope tier: Tier <1|2|3> — <Behavior Tweak|New Requirements|Scope Shift>
+Re-entry point: /sk:<command>
+
+Reason: <1-2 sentences explaining why this tier was chosen>
+
+Proceed? (yes / no / different tier)
+```
+
+Wait for explicit confirmation before logging or routing.
+
+### 4. Log the Change
+
+Once confirmed, update the planning files:
+
+**`tasks/todo.md`** — Add a `## Change Log` section at the top (or append to existing):
+```
+## Change Log
+- [<date>] <summary of change> — re-entered at /sk:<command>
+```
+
+Mark any tasks that are now invalidated with `~~strikethrough~~` and a note: `(invalidated by requirement change — see change log)`.
+
+**`tasks/progress.md`** — Append:
+```
+## Requirement Change — <date>
+- What changed: <description>
+- Trigger: <what caused the change>
+- Scope tier: <1|2|3>
+- Re-entry point: /sk:<command>
+- Invalidated tasks: <list or "none">
+```
+
+### 5. Route Forward
+
+Tell the user exactly where to go next:
+
+> "Change logged. Re-enter the workflow at `/sk:<command>`.
+> Carry forward: <what's still valid — plan steps, findings, etc.>
+> Discard: <what's no longer valid>"
+
+**Do not proceed to the next step yourself.** The user must explicitly invoke it.
+
+---
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:change"]` is set, use that model — it takes precedence.
+- Otherwise use the `profile` field. Default: `balanced`.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | opus (inherit) |
+| `balanced` | sonnet |
+| `budget` | sonnet |
+
+> `opus` = inherit. When spawning sub-agents via the Agent tool, pass `model: "<resolved-model>"`.

package/commands/sk/execute-plan.md

@@ -52,6 +52,12 @@ Execute the plan in `tasks/todo.md` in small batches with clear checkpoints.
 - Do not repeat the same failing action; change approach.
 - After 3 failed attempts, stop and ask the user with details.
 
+## Requirement Changes Mid-Execution
+
+If the user indicates that requirements have changed during execution, **stop immediately** — do not continue implementing the old behavior.
+
+Run `/sk:change` to assess the scope and re-enter at the correct step.
+
 ## On User Correction
 
 If the user corrects your approach during execution, immediately append to

package/commands/sk/help.md

@@ -19,6 +19,7 @@ Run these commands in order for a complete, quality-gated feature build.
 | `/sk:schema-migrate` | Analyze schema changes *(skip if no DB changes)* |
 | `/sk:write-tests` | TDD red: write failing tests first |
 | `/sk:execute-plan` | TDD green: implement until tests pass |
+| `/sk:change` | Requirements changed? Re-enter at the right step |
 | `/sk:smart-commit` | Conventional commit with approval |
 | `/sk:lint` | **GATE** — all linters must pass |
 | `/sk:test` | **GATE** — 100% coverage on new code |
@@ -27,6 +28,16 @@ Run these commands in order for a complete, quality-gated feature build.
 | `/sk:update-task` | Mark task done, log completion |
 | `/sk:finish-feature` | Changelog + PR creation |
 
+## Requirement Change Flow
+
+Requirements change mid-workflow? Run `/sk:change` — it classifies the scope and routes you back to the right step.
+
+| Tier | Scope | Re-entry |
+|------|-------|---------|
+| Tier 1 | Behavior tweak *(logic changes, plan stays)* | `/sk:write-tests` |
+| Tier 2 | New requirements *(new scope or constraints)* | `/sk:write-plan` |
+| Tier 3 | Scope shift *(rethinking the approach)* | `/sk:brainstorm` |
+
 ## Bug Fix Workflow
 
 | Command | Purpose |
@@ -47,6 +58,7 @@ Run these commands in order for a complete, quality-gated feature build.
 | `/sk:api-design` | Design REST/GraphQL contracts before implementation |
 | `/sk:brainstorm` | Explore requirements, no code |
 | `/sk:branch` | Create branch from current task |
+| `/sk:change` | Handle mid-workflow requirement change — re-enter at the right step |
 | `/sk:debug` | Structured bug investigation |
 | `/sk:execute-plan` | Implement plan in batches |
 | `/sk:features` | Sync docs/sk:features/ specs with codebase |
@@ -91,6 +103,7 @@ ShipKit routes each skill to the right model automatically. Set once per project
 |-------------|-----------|---------|----------|--------|
 | brainstorm, write-plan, debug, execute-plan, review | opus | opus | sonnet | sonnet |
 | write-tests, frontend-design, api-design, security-check | opus | sonnet | sonnet | sonnet |
+| change | opus | sonnet | sonnet | sonnet |
 | perf, schema-migrate, accessibility | opus | sonnet | sonnet | haiku |
 | lint, test | sonnet | sonnet | haiku | haiku |
 | smart-commit, branch, update-task | haiku | haiku | haiku | haiku |
@@ -100,4 +113,4 @@ Config lives in `.shipkit/config.json` — per project, gitignored by default.
 
 ---
 
-**ShipKit** by Kenneth Solomon · `npx @kennethsolomon/shipkit` to install/update
+**ShipKit** by Kenneth Solomon · `npm install -g @kennethsolomon/shipkit` to install/update

package/package.json

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

package/skills/sk:setup-claude/templates/CLAUDE.md.template

@@ -117,6 +117,8 @@ Progress is tracked in `tasks/workflow-status.md`. This file persists across con
 
 6. **Never skip steps without confirmation.** Steps cannot run out of order. Hard gate steps (12, 14, 16, 20) can NEVER be skipped. Optional gate step (18) requires explicit confirmation to skip.
 
+7. **Requirements change mid-workflow?** Stop the current step and run `/change` immediately. It will classify the scope (behavior tweak / new requirements / scope shift) and tell you exactly where to re-enter the workflow. Never continue implementing stale requirements.
+
 7. **Never auto-advance.** When one step completes, stop and tell the user which step is next. Do not proceed automatically.
 
 8. **Never write code during design or plan phases.** Steps 1-6 are reading/exploring/planning/design only — no code, no file edits (except `tasks/` files).

package/skills/sk:write-tests/SKILL.md

@@ -9,6 +9,8 @@ description: "TDD: Auto-detect BE + FE testing stacks, write failing tests befor
 
 Auto-detect the project's backend AND frontend testing frameworks, read the plan from `tasks/todo.md`, and write comprehensive failing tests BEFORE implementation. Tests define the expected behavior — implementation makes them pass.
 
+> **Requirements changed mid-workflow?** Run `/sk:change` first. It will classify the scope and tell you whether to update tests (Tier 1), revise the plan (Tier 2), or re-brainstorm (Tier 3). Never update tests based on a changed requirement without going through `/sk:change` first.
+
 ## Allowed Tools
 
 Bash, Read, Write, Edit, Glob, Grep