@kennethsolomon/shipkit 3.8.0 → 3.10.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,268 @@ 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
-/sk:brainstorm
+# 3. Start building
+/sk:start
 ```
 
-`/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.
 
----
+`/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.
 
-## 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 |
+|--------------|----------|-------------|
+| **Not sure — let ShipKit decide** | `/sk:start` | Classifies your task, routes to optimal flow/mode/agents |
+| **Build a new feature** | `/sk:brainstorm` | Full workflow: plan → TDD → 6 quality gates → PR |
+| **Build hands-free** | `/sk:autopilot` | All 21 steps, auto-skip, auto-advance, auto-commit |
+| **Full-stack feature (parallel)** | `/sk:team` | Parallel domain agents (backend + frontend + QA) |
+| **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>38 commands</strong> — click to expand</summary>
+
+| Command | Purpose |
+|---------|---------|
+| `/sk:accessibility` | WCAG 2.1 AA audit |
+| `/sk:api-design` | Design API contracts before implementation |
+| `/sk:autopilot` | Hands-free workflow — auto-skip, auto-advance, auto-commit |
+| `/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:start` | Smart entry point — classifies task, routes to optimal flow |
+| `/sk:status` | Show workflow + task status |
+| `/sk:team` | Parallel domain agents for full-stack tasks |
+| `/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/commands/sk/autopilot.md

@@ -0,0 +1,22 @@
+---
+description: "Hands-free workflow — all 21 steps, auto-skip, auto-advance, auto-commit. Stops only for direction approval and PR push."
+---
+
+# /sk:autopilot
+
+Run the full ShipIt workflow in hands-free mode.
+
+Usage: `/sk:autopilot <task description>`
+
+Executes all 21 workflow steps with:
+- **Auto-skip** — optional steps skipped when clearly not needed
+- **Auto-advance** — no manual step transitions
+- **Auto-commit** — conventional format, no approval prompt
+- **Same quality gates** — all gates enforced, same fix loops
+
+Stops only for:
+1. Direction approval (after brainstorm)
+2. 3-strike failures
+3. PR push confirmation
+
+See `skills/sk:autopilot/SKILL.md` for full details.

package/commands/sk/set-profile.md

@@ -28,6 +28,8 @@ Valid profiles: `full-sail` · `quality` · `balanced` · `budget`
 | perf, schema-migrate, accessibility | opus | sonnet | sonnet | haiku |
 | lint, test | sonnet | sonnet | haiku | haiku |
 | smart-commit, branch, update-task | haiku | haiku | haiku | haiku |
+| autopilot, team | opus | opus | sonnet | sonnet |
+| start | haiku | haiku | haiku | haiku |
 
 Note: `opus` = inherit (uses the current session model). Switch to Opus 4.5 in your session to get the full benefit.
 
@@ -66,6 +68,8 @@ Model assignments for this project:
   perf, schema-migrate, accessibility → <model>
   lint, test → <model>
   smart-commit, branch, update-task → haiku
+  autopilot, team → <model>
+  start → haiku
 
 Run /sk:config to see all settings or make further changes.
 ```

package/commands/sk/start.md

@@ -0,0 +1,30 @@
+---
+description: "Smart entry point — classifies your task and routes to the optimal flow, mode, and agent strategy."
+---
+
+# /sk:start
+
+Smart entry point for all ShipIt work. Classifies your task and recommends the best workflow configuration.
+
+Usage: `/sk:start <task description>`
+
+Examples:
+```
+/sk:start add user profile page with avatar upload
+/sk:start fix login redirect loop
+/sk:start urgent: payments failing in production
+/sk:start bump lodash to latest version
+```
+
+**What it does:**
+1. **Classifies** — detects if it's a feature, bug, hotfix, or small change
+2. **Detects scope** — full-stack, frontend-only, or backend-only
+3. **Recommends** — optimal flow + mode (autopilot/manual) + agents (team/solo)
+4. **Routes** — enters the chosen workflow after your confirmation
+
+**Override flags:**
+- `--manual` — force step-by-step mode
+- `--team` / `--no-team` — force team or solo agents
+- `--debug` / `--hotfix` / `--fast-track` — force a specific flow
+
+See `skills/sk:start/SKILL.md` for full details.

package/commands/sk/team.md

@@ -0,0 +1,23 @@
+---
+description: "Parallel domain agents — spawns Backend, Frontend, and QA agents for full-stack implementation."
+---
+
+# /sk:team
+
+Split implementation across parallel domain agents.
+
+Usage: `/sk:team`
+
+Spawns 3 specialized agents in parallel:
+- **Backend Agent** (worktree) — backend tests + implementation
+- **Frontend Agent** (worktree) — frontend tests + implementation
+- **QA Agent** (background) — E2E test scenarios
+
+**Prerequisite:** Plan must contain an explicit API contract section.
+
+Falls back to single-agent mode if:
+- No API contract in plan
+- Backend-only or frontend-only task
+- Worktree creation fails
+
+See `skills/sk:team/SKILL.md` for full details.

package/package.json

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