@kennethsolomon/shipkit 3.8.0 → 3.9.0

package/README.md

@@ -4,10 +4,8 @@
 
 **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.
-
-**Every gate must pass. Quality isn't optional — it's structural.**
+Ship features with TDD, security audits, and AI-powered code review —<br>
+all wired into a single repeatable workflow.
 
 [![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)
@@ -17,339 +15,260 @@ and AI-powered code review — all wired into a single repeatable workflow.
 npm install -g @kennethsolomon/shipkit && shipkit
 ```
 
-Works on Mac, Linux, and Windows.
-
-</div>
-
-<div align="center">
-
-![ShipKit terminal demo](assets/shipkit-terminal.png)
-
 </div>
 
 ---
 
-<div align="center">
+## What is ShipKit?
 
-*"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 turns Claude Code into a disciplined development partner. Instead of "write some code," every feature goes through:
 
-*"Every other Claude workflow I tried was either too rigid or too vague. ShipKit is the first one that actually ships."*
+**Plan** → **Build (TDD)** → **Quality Gates** → **Ship**
 
-*"The gates feel annoying until the day they catch something real. Now I don't merge without them."*
+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.
 
-</div>
+ShipKit auto-detects your stack — linters, test runners, frameworks, package managers. No configuration needed.
 
 ---
 
 ## Quick Start
 
 ```bash
-# 1. Install ShipKit globally
+# 1. Install
 npm install -g @kennethsolomon/shipkit && shipkit
 
-# 2. Bootstrap your project (run inside your project directory)
+# 2. Bootstrap your project (run once)
 /sk:setup-claude
 
-# 3. Start your first feature
+# 3. Start building
 /sk:brainstorm
 ```
 
-`/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.
+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.
 
 ---
 
-## How It Works
-
-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.
+## Pick Your Flow
 
-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**
+| I want to... | Run this | What happens |
+|--------------|----------|-------------|
+| **Build a new feature** | `/sk:brainstorm` | Full workflow: plan → TDD → 6 quality gates → PR |
+| **Make a small change** | `/sk:fast-track` | Skip planning, keep all quality gates |
+| **Fix a bug** | `/sk:debug` | Investigate → regression test → fix → gates → PR |
+| **Fix a production emergency** | `/sk:hotfix` | Skip TDD, but quality gates still enforced |
+| **Handle a requirement change** | `/sk:change` | Assess scope, re-enter workflow at the right step |
 
-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.
+## Workflows
+
+### Feature Flow — full planning + TDD + all gates
+
+> Start with: `/sk:brainstorm`
+
+| Step | Command | What it does | Phase |
+|------|---------|-------------|-------|
+| 1 | `/sk:brainstorm` | Explore requirements, propose approaches | Think |
+| 2 | `/sk:frontend-design` | *Optional* — UI mockup (`--pencil` for visual) | Think |
+| 3 | `/sk:api-design` | *Optional* — API contracts | Think |
+| 4 | `/sk:accessibility` | *Optional* — WCAG 2.1 AA audit on design | Think |
+| 5 | `/sk:write-plan` | Write decision-complete plan | Think |
+| 6 | `/sk:branch` | Create feature branch | Build |
+| 7 | `/sk:schema-migrate` | *Optional* — auto-skips if no migrations | Build |
+| 8 | `/sk:write-tests` | TDD red — write failing tests | Build |
+| 9 | `/sk:execute-plan` | TDD green — make tests pass | Build |
+| 10 | `/sk:smart-commit` | Conventional commit | Build |
+| 11 | `/sk:gates` | All 6 quality gates (parallel) | Verify |
+| 12 | `/sk:update-task` | Mark done | Ship |
+| 13 | `/sk:finish-feature` | Changelog + PR | Ship |
+| 14 | `/sk:features` | Sync feature specs | Ship |
+| 15 | `/sk:release` | *Optional* — version bump + tag | Ship |
 
 ---
 
-## Workflow
+### Fast-Track Flow — skip planning, keep all gates
 
-### Feature Flow
+> Start with: `/sk:fast-track`
 
-```
-Brainstorm → Plan → Branch → [Schema] → Write Tests → Implement → Commit
-  → Lint ✓ → Test ✓ → Security ✓ → Review ✓ → E2E ✓ → Update Task → Finish → Sync Features
-```
+| Step | Command | What it does | Phase |
+|------|---------|-------------|-------|
+| ~~1~~ | ~~/sk:brainstorm~~ | **Skipped** | — |
+| ~~2~~ | ~~/sk:write-plan~~ | **Skipped** | — |
+| ~~3~~ | ~~/sk:write-tests~~ | **Skipped** | — |
+| 4 | `/sk:branch` | Create feature branch | Build |
+| 5 | implement directly | No TDD — write code | Build |
+| 6 | `/sk:smart-commit` | Conventional commit | Build |
+| 7 | `/sk:gates` | All 6 quality gates (parallel) | Verify |
+| 8 | `/sk:finish-feature` | Changelog + PR | Ship |
 
-| # | Command | Purpose |
-|---|---------|---------|
-| 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` 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:test`** | **GATE** — 100% coverage on new code |
-| 14 | **`/sk:security-check`** | **GATE** — 0 issues |
-| 15 | **`/sk:perf`** | **GATE** *(optional)* — critical/high findings = 0 |
-| 16 | **`/sk:review`** | **GATE** — Review + Simplify + Blast Radius — 0 issues including nitpicks |
-| 17 | **`/sk:e2e`** | **GATE** — E2E Tests — prefers Playwright CLI when config detected, falls back to agent-browser; all scenarios must pass |
-| 18 | `/sk:update-task` | Mark done, log completion |
-| 19 | `/sk:finish-feature` | Changelog + PR |
-| 20 | `/sk:features` | Sync Features — update docs/features/ specs *(required)* |
-| 21 | `/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
+Guard rails: warns if diff > 300 lines or > 5 new files.
 
-```
-Debug → Plan → Branch → Write Tests → Implement → Lint ✓ → Test ✓ → Security ✓ → Review ✓ → Finish
-```
+---
 
-| # | Command | Purpose |
-|---|---------|---------|
-| 1 | `/sk:debug` | Root-cause analysis |
-| 2 | `/sk:write-plan` | Fix plan |
-| 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–10 | `/sk:lint` → `/sk:test` → `/sk:security-check` → `/sk:review` → `/sk:e2e` | Quality gates |
-| 11 | `/sk:finish-feature` | Changelog + PR |
+### Bug Fix Flow — investigate first, then fix
 
-### Hotfix Flow
+> Start with: `/sk:debug`
 
-For production issues that need to ship immediately. Skips brainstorm, design, and TDD. **Quality gates are non-negotiable even in a hotfix.**
+| Step | Command | What it does | Phase |
+|------|---------|-------------|-------|
+| ~~1~~ | ~~/sk:brainstorm~~ | **Skipped** | — |
+| ~~2~~ | ~~/sk:write-plan~~ | **Skipped** | — |
+| 3 | `/sk:debug` | Reproduce, isolate, hypothesize, verify | Think |
+| 4 | `/sk:branch` | Create fix branch | Build |
+| 5 | `/sk:write-tests` | Regression test that reproduces the bug | Build |
+| 6 | implement the fix | Make regression test pass | Build |
+| 7 | `/sk:smart-commit` | Commit fix + test | Build |
+| 8 | `/sk:gates` | All 6 quality gates (parallel) | Verify |
+| 9 | `/sk:finish-feature` | Changelog + PR | Ship |
 
-```
-Debug → Branch → Fix → Smoke Test → Lint ✓ → Test ✓ → Security ✓ → Review ✓ → Finish
-```
+---
 
-| # | Command | Purpose |
-|---|---------|---------|
-| 1 | `/sk:debug` | Root-cause analysis — understand before touching code |
-| 2 | `/sk:branch` | Auto-named from the bug description |
-| 3 | implement directly | No write-tests phase — go straight to the fix |
-| 4 | run existing tests | Existing tests MUST still pass |
-| 5 | `/sk:smart-commit` | Commit the fix |
-| 6 | **`/sk:lint`** | **GATE** |
-| 7 | **`/sk:test`** | **GATE** |
-| 8 | **`/sk:security-check`** | **GATE** |
-| 9 | **`/sk:review`** | **GATE** |
-| 10 | `/sk:update-task` | Mark done |
-| 11 | `/sk:finish-feature` | Changelog + PR — mark as hotfix |
+### Hotfix Flow — production emergency
 
-After merging: add a regression test and a lesson to `tasks/lessons.md`.
+> Start with: `/sk:hotfix`
 
-### Requirement Change Flow
+| Step | Command | What it does | Phase |
+|------|---------|-------------|-------|
+| ~~1~~ | ~~/sk:brainstorm~~ | **Skipped** | — |
+| ~~2~~ | ~~/sk:write-plan~~ | **Skipped** | — |
+| ~~3~~ | ~~/sk:write-tests~~ | **Skipped** | — |
+| 4 | `/sk:debug` | Root-cause analysis | Think |
+| 5 | `/sk:branch` | Create hotfix branch | Build |
+| 6 | implement directly | Fix the issue | Build |
+| 7 | run existing tests | Must still pass | Build |
+| 8 | `/sk:smart-commit` | Commit the fix | Build |
+| 9 | `/sk:gates` | All 6 quality gates (parallel) | Verify |
+| 10 | `/sk:finish-feature` | Changelog + PR (marked as hotfix) | Ship |
 
-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.
+After merging: add regression test + lesson to `tasks/lessons.md`.
 
-```
-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` |
+### Requirement Change — mid-workflow pivot
 
-`/sk:change` logs the change to `tasks/todo.md` and `tasks/progress.md`, marks invalidated tasks, and tells you exactly what to carry forward.
+> Run: `/sk:change` — it classifies scope and re-enters at the right step
+
+| Tier | What changed | Example | Re-entry point |
+|------|-------------|---------|----------------|
+| **Tier 1** | Behavior tweak (same scope) | "Delete all" → "Delete users only" | `/sk:write-tests` |
+| **Tier 2** | New requirements (new scope) | "Also add export to CSV" | `/sk:write-plan` |
+| **Tier 3** | Scope shift (rethink) | "Different approach entirely" | `/sk:brainstorm` |
 
 ---
 
-## Commands
-
-### Planning & Design
-
-| Command | Description |
-|---------|-------------|
-| `/sk:brainstorm` | Explore requirements and design before writing any code |
-| `/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` |
-| `/sk:plan` | Create or refresh task planning files |
-| `/sk:setup-claude` | Bootstrap project scaffolding (CLAUDE.md + tasks/) |
-| `/sk:setup-optimizer` | Enrich CLAUDE.md by scanning the codebase |
-| `/sk:reverse-doc` | Generate architecture/design docs from existing code |
-
-### Development
-
-| Command | Description |
-|---------|-------------|
-| `/sk:branch` | Create a feature branch from the current task |
-| `/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 |
-| `/sk:fast-track` | Abbreviated workflow for small changes — skip planning, keep all gates |
-
-### Prototyping
-
-| Command | Description |
-|---------|-------------|
-| `/sk:mvp` | Generate a complete MVP from a single idea prompt — landing page with waitlist + working app with fake data. Supports Next.js, Nuxt, Laravel, React+Vite. Optional Pencil MCP design phase and Playwright MCP visual validation. |
-
-### Quality Gates
-
-| Command | Description |
-|---------|-------------|
-| `/sk:lint` | Auto-detect and run all linters (Pint, ESLint, PHPStan, Prettier…) |
-| `/sk:test` | Auto-detect and run all test suites, verify 100% coverage on new code |
-| `/sk:security-check` | OWASP security audit across changed code |
-| `/sk:perf` | Performance audit: bundle size, N+1 queries, Core Web Vitals |
-| `/sk:seo-audit` | SEO audit — dual-mode (source templates + dev server), ask-before-fix, checklist output to `tasks/seo-findings.md` |
-| `/sk:review` | Blast-radius-aware self-review across 7 dimensions + cross-file impact analysis |
-| `/sk:gates` | Run all quality gates in optimized parallel batches |
-| `/sk:scope-check` | Compare implementation against plan, detect scope creep |
-
-### Shipping
-
-| Command | Description |
-|---------|-------------|
-| `/sk:smart-commit` | Generate conventional commit messages with approval |
-| `/sk:update-task` | Mark current task done, log completion |
-| `/sk:finish-feature` | Write changelog entry + create PR |
-| `/sk:release` | Version bump + CHANGELOG + git tag + push |
-| `/sk:features` | Sync docs/features/ specs with the codebase |
-| `/sk:retro` | Post-ship retrospective: velocity, blockers, action items |
-
-### Laravel
-
-| Command | Description |
-|---------|-------------|
-| `/sk:laravel-new` | Scaffold a fresh Laravel app with production-ready conventions |
-| `/sk:laravel-init` | Configure an existing Laravel project |
-
-### Configuration
-
-| Command | Description |
-|---------|-------------|
-| `/sk:config` | View and edit project config (`.shipkit/config.json`) |
-| `/sk:set-profile` | Switch model routing profile for this project |
-
-### Meta
-
-| Command | Description |
-|---------|-------------|
-| `/sk:help` | Show all commands and workflow overview |
-| `/sk:status` | Show workflow and task status at a glance |
-| `/sk:dashboard` | Read-only workflow Kanban board — localhost server, multi-worktree |
-| `/sk:context` | Load all context files + output session brief for fast session start |
-| `/sk:skill-creator` | Create or improve ShipKit skills |
+## Quality Gates (`/sk:gates`)
 
----
+One command runs all 6 gates in parallel batches:
 
-## Model Routing Profiles
+| Batch | Gates | Why this order |
+|-------|-------|---------------|
+| **1** (parallel) | lint + security + perf | Independent — run simultaneously |
+| **2** | tests | Needs lint fixes first |
+| **3** | code review | Needs deep understanding |
+| **4** | E2E Tests | Needs review fixes |
 
-ShipKit routes each skill to the right model automatically. Set it once per project:
+Each gate auto-fixes, auto-commits, and re-runs until clean. If a gate fails 3 times, it stops and asks for help.
 
-```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
-```
+Pre-existing issues are logged to `tasks/tech-debt.md` — not fixed inline.
 
-| Profile | Philosophy | Best for |
-|---------|-----------|---------|
-| `full-sail` | Opus on everything that matters | High-stakes work, client projects |
-| `quality` | Opus for planning + review, Sonnet for implementation | Most professional projects |
-| `balanced` | Sonnet across the board *(default)* | Day-to-day development |
-| `budget` | Haiku where possible, Sonnet for gates | Side projects, prototyping |
-
-| Skill group | full-sail | quality | balanced | budget |
-|-------------|-----------|---------|----------|--------|
-| 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). Config lives in `.shipkit/config.json` — per project, gitignored by default.
-
-### Config Reference
-
-```json
-{
-  "profile": "balanced",
-  "auto_commit": true,
-  "skip_gates": [],
-  "coverage_threshold": 100,
-  "branch_pattern": "feature/{slug}",
-  "model_overrides": { "sk:review": "opus" }
-}
-```
+---
+
+## On-Demand Tools
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `profile` | `balanced` | Model routing profile |
-| `auto_commit` | `true` | Auto-commit after each gate passes |
-| `skip_gates` | `[]` | Gates to skip — e.g. `["perf","accessibility"]` for backend-only projects |
-| `coverage_threshold` | `100` | Minimum test coverage % on new code |
-| `branch_pattern` | `feature/{slug}` | Branch naming convention |
-| `model_overrides` | `{}` | Per-skill model overrides that take precedence over profile |
+Use these anytime — they're not part of any workflow.
+
+| Command | When to use |
+|---------|------------|
+| `/sk:scope-check` | Mid-implementation — detect scope creep (On Track / Minor / Significant / Out of Control) |
+| `/sk:retro` | After shipping — analyze velocity, blockers, patterns, generate action items |
+| `/sk:reverse-doc` | Inherited codebase — generate architecture/design docs from existing code |
+| `/sk:status` | Quick view of workflow and task status |
+| `/sk:dashboard` | Visual Kanban board across all git worktrees |
+| `/sk:mvp` | Generate a complete MVP app from a single idea prompt |
+| `/sk:seo-audit` | SEO audit for web projects |
 
 ---
 
 ## Stack Support
 
-ShipKit auto-detects your stack — no configuration needed.
-
 | Area | Supported |
 |------|-----------|
-| **Linters** | Pint, ESLint, PHPStan, Rector, Prettier, Biome, Stylelint |
-| **Test runners** | Pest, PHPUnit, Jest, Vitest, Playwright |
-| **Schema / ORM** | Prisma, Drizzle, Eloquent, SQLAlchemy + Alembic, ActiveRecord |
 | **Frameworks** | Laravel, Next.js, Nuxt, React, Vue, Node.js |
+| **Linters** | Pint, ESLint, PHPStan, Rector, Prettier, Biome |
+| **Test runners** | Pest, PHPUnit, Jest, Vitest, Playwright |
+| **Schema / ORM** | Prisma, Drizzle, Eloquent, SQLAlchemy, ActiveRecord |
 | **Release** | npm, Composer, iOS (App Store), Android (Play Store) |
 
 ---
 
-## Security
-
-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:
-
-```json
-{
-  "permissions": {
-    "deny": [
-      "Read(.env)",
-      "Read(.env.*)",
-      "Read(**/*.pem)",
-      "Read(**/*.key)",
-      "Read(**/*.p12)",
-      "Read(**/credentials*)"
-    ]
-  }
-}
-```
-
-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.
+## All Commands
+
+<details>
+<summary><strong>35 commands</strong> — click to expand</summary>
+
+| Command | Purpose |
+|---------|---------|
+| `/sk:accessibility` | WCAG 2.1 AA audit |
+| `/sk:api-design` | Design API contracts before implementation |
+| `/sk:brainstorm` | Explore requirements and design |
+| `/sk:branch` | Create feature branch from current task |
+| `/sk:change` | Handle mid-workflow requirement changes |
+| `/sk:config` | View/edit project config |
+| `/sk:context` | Load project context (automatic via hooks) |
+| `/sk:dashboard` | Live Kanban board — sk:dashboard across worktrees |
+| `/sk:debug` | Structured bug investigation |
+| `/sk:e2e` | E2E Tests — behavioral verification |
+| `/sk:execute-plan` | Execute plan checkboxes in batches |
+| `/sk:fast-track` | Small changes — skip planning, keep gates |
+| `/sk:features` | Sync feature specs with codebase |
+| `/sk:finish-feature` | Changelog + PR |
+| `/sk:frontend-design` | UI mockup + optional Pencil visual design |
+| `/sk:gates` | All quality gates in parallel batches |
+| `/sk:help` | Show all commands |
+| `/sk:hotfix` | Emergency fix workflow |
+| `/sk:laravel-init` | Configure existing Laravel project |
+| `/sk:laravel-new` | Scaffold fresh Laravel app |
+| `/sk:lint` | Auto-detect and run all linters |
+| `/sk:mvp` | Generate MVP app from a prompt |
+| `/sk:perf` | Performance audit |
+| `/sk:plan` | Create/refresh planning files |
+| `/sk:release` | Version bump + tag (`--android` / `--ios` for store audit) |
+| `/sk:retro` | Post-ship retrospective |
+| `/sk:reverse-doc` | Generate docs from existing code |
+| `/sk:review` | 7-dimension code review |
+| `/sk:schema-migrate` | Database schema change analysis |
+| `/sk:scope-check` | Detect scope creep mid-implementation |
+| `/sk:security-check` | OWASP security audit |
+| `/sk:seo-audit` | sk:seo-audit for web projects |
+| `/sk:set-profile` | Switch model routing profile |
+| `/sk:setup-claude` | Bootstrap project scaffolding |
+| `/sk:smart-commit` | Conventional commit with approval |
+| `/sk:status` | Show workflow + task status |
+| `/sk:test` | Run all test suites |
+| `/sk:update-task` | Mark task done |
+| `/sk:write-plan` | Write plan to `tasks/todo.md` |
+| `/sk:write-tests` | TDD: write failing tests first |
+
+</details>
 
 ---
 
-## License
+## Learn More
 
-MIT — see [LICENSE](LICENSE) for details.
-
-Built by [Kenneth Solomon](https://github.com/kennethsolomon).
+| Topic | Where |
+|-------|-------|
+| Detailed workflow steps (21-step table) | [DOCUMENTATION.md](.claude/docs/DOCUMENTATION.md) |
+| Feature specifications | [docs/FEATURES.md](docs/FEATURES.md) |
+| Model routing profiles & config | [DOCUMENTATION.md — Config](.claude/docs/DOCUMENTATION.md#config-reference) |
+| Infrastructure (hooks, agents, rules) | [DOCUMENTATION.md — Setup](.claude/docs/DOCUMENTATION.md#what-gets-created) |
+| Security & permissions | [DOCUMENTATION.md — Security](.claude/docs/DOCUMENTATION.md#security) |
 
 ---
 
 <div align="center">
 
+MIT License — Built by [Kenneth Solomon](https://github.com/kennethsolomon)
+
 **Claude Code is powerful. ShipKit makes it reliable.**
 
 </div>

package/package.json

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

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

@@ -27,6 +27,7 @@ After bootstrapping a project, the recommended workflow becomes:
 - `tasks/progress.md` — chronological work log + test results
 - `tasks/lessons.md` — durable “don’t repeat mistakes” log (**never overwrite**)
 - `tasks/security-findings.md` — security audit results from `/sk:security-check` (**never overwrite**)
+- `tasks/cross-platform.md` — changes that need replication in companion codebase (web <-> mobile) (**never overwrite**)
 
 ### Project Commands (in `.claude/commands/`)
 - `brainstorm.md` — invokes the global `brainstorming` skill
@@ -88,6 +89,7 @@ Never overwrite `tasks/lessons.md` — always append.
 - `tasks/progress.md`
 - `tasks/lessons.md`
 - `tasks/security-findings.md`
+- `tasks/cross-platform.md`
 - `CHANGELOG.md`
 - custom `CLAUDE.md` (anything not marked `<!-- Generated by /sk:setup-claude -->`)
 

package/skills/sk:setup-claude/scripts/apply_setup_claude.py

@@ -443,6 +443,7 @@ def apply(
     add("templates/tasks/lessons.md.template", "tasks/lessons.md", "missing")
     add("templates/tasks/security-findings.md.template", "tasks/security-findings.md", "missing")
     add("templates/tasks/workflow-status.md.template", "tasks/workflow-status.md", "missing")
+    add("templates/tasks/cross-platform.md.template", "tasks/cross-platform.md", "missing")
 
     # commands (update if generated)
     add("templates/commands/brainstorm.md.template", ".claude/commands/brainstorm.md", "generated")

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

@@ -272,6 +272,21 @@ Use `run_in_background: true` for tasks that don't block your next step:
 ```
 <!-- END:sub-agent-patterns -->
 
+## Cross-Platform Tracking
+
+This project may have a companion codebase (web <-> mobile). During implementation, **log every change that affects the other platform** to `tasks/cross-platform.md`.
+
+**When to log:**
+- API contract changes (new/modified endpoints, payload shapes, auth)
+- Data model changes (new fields, type changes, validation rules)
+- Business logic that must behave identically on both platforms
+- UI/UX flows that should have parity
+- Platform-specific deviations (intentional differences)
+
+**How to log:** Append a new section using the template in `tasks/cross-platform.md`. Include enough context that a developer in the other codebase can implement without guessing.
+
+**When to review:** At the start of every task, check `tasks/cross-platform.md` for pending items targeting this codebase.
+
 ## Project Memory
 
 Read these files at the start of every task:
@@ -279,12 +294,14 @@ Read these files at the start of every task:
 - `tasks/lessons.md` — past mistakes and how to avoid them
 - `tasks/todo.md` — current plan
 - `tasks/tech-debt.md` — known shortcuts, deferred work, and areas to revisit
+- `tasks/cross-platform.md` — pending changes from the other codebase
 
 Write to these files continuously:
 - `tasks/progress.md` — every attempt, error, and resolution
 - `tasks/findings.md` — anything important discovered mid-task
+- `tasks/cross-platform.md` — any change that impacts the other platform
 
-**Never overwrite** `tasks/lessons.md` or `tasks/security-findings.md`.
+**Never overwrite** `tasks/lessons.md`, `tasks/security-findings.md`, or `tasks/cross-platform.md`.
 
 ## Lessons Capture
 

package/skills/sk:setup-claude/templates/tasks/cross-platform.md.template

@@ -0,0 +1,31 @@
+# Cross-Platform Changes
+
+Track changes that need to be replicated in the other codebase (web <-> mobile).
+
+<!--
+  Format: One section per feature/task.
+  Each entry should have enough context for a developer (or Claude session)
+  in the other codebase to implement without guessing.
+-->
+
+<!-- TEMPLATE — copy this block for each new feature:
+
+## [Feature Name] (YYYY-MM-DD)
+Source: [web|mobile] — the codebase where this was implemented first
+
+### API Changes
+- [ ] Description of endpoint/payload/auth changes
+
+### Data Model Changes
+- [ ] New fields, renamed fields, type changes, validation rules
+
+### Behavior Changes
+- [ ] Business logic that must match across platforms
+
+### UI/UX Parity
+- [ ] Screens, flows, or interactions that should match
+
+### Platform-Specific Notes
+- [ ] Anything that differs intentionally between web and mobile
+
+-->

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

@@ -39,7 +39,7 @@ The single command to keep your CLAUDE.md current. Diagnoses problems, updates t
 
 Before making any changes, runs a diagnostic pass on the existing CLAUDE.md:
 
-- **Missing sections** — checks for essential sections (Workflow, Sub-Agent Patterns, Project Memory, Lessons Capture, Testing, Commands, etc.)
+- **Missing sections** — checks for essential sections (Workflow, Sub-Agent Patterns, Cross-Platform Tracking, Project Memory, Lessons Capture, Testing, Commands, etc.)
 - **Stale content** — detects outdated info (stale model/route counts, removed dependencies, old command names like `/laravel-lint` instead of `/sk:lint`)
 - **Inconsistencies** — compares documented vs actual project state (directories, scripts, workflows)
 - **Section completeness** — flags sections that exist but are empty or have only placeholder text
@@ -63,6 +63,7 @@ Read → Explore → Design → Accessibility → Plan → Branch → Migrate
 - Step completion summary rule (NON-NEGOTIABLE)
 - Bug fix flow section
 - Sub-Agent Patterns section (if missing)
+- Cross-Platform Tracking section (if missing)
 - Project Memory section (if missing)
 - Lessons Capture section (if missing)
 - Testing TDD section (if missing)