@kennethsolomon/shipkit 3.17.1 → 3.18.0

package/README.md

@@ -63,7 +63,7 @@ npm install -g @kennethsolomon/shipkit && shipkit  # update globally
 | I want to... | Start here | Flow |
 |---|---|---|
 | **Not sure — just describe my task** | `/sk:start <description>` | Auto-classified |
-| **Build a new feature** | `/sk:start add <feature>` | Feature (8 steps) |
+| **Build a new feature** | `/sk:start add <feature>` | Feature (8 phases + scope check, learn, retro) |
 | **Build a full-stack feature (backend + frontend + mobile)** | `/sk:start --team add <feature>` | Feature with parallel agents |
 | **Make a small change** (config, copy, dependency bump) | `/sk:start bump lodash` | Fast-track (5 steps) |
 | **Fix a bug** | `/sk:start fix <description>` | Debug (7 steps) |
@@ -129,6 +129,9 @@ qa-engineer  (background) → writes 14 Playwright E2E scenarios while others im
 
 Backend and frontend work in isolated worktrees — zero conflicts. Results merge when both complete.
 
+**Step 5.5 — Scope Check** (`/sk:scope-check`)
+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.
+
 **Step 6 — Commit** (`/sk:smart-commit`)
 Presents the diff. You approve. Commits.
 
@@ -156,6 +159,18 @@ Each failure auto-fixes and re-runs. One squash commit per gate pass.
 **Step 8 — Finalize** (`/sk:finish-feature`)
 Changelog updated. PR created. Feature spec synced. Asks about release.
 
+**Step 8.5 — Learn** (`/sk:learn`)
+Extracts reusable patterns from this session:
+> "Rate limiting must be applied to all auth endpoints — security-reviewer flagged POST /login"
+
+Saved to `~/.claude/skills/learned/` — available in future sessions across all projects.
+
+**Step 8.6 — Retro** (`/sk:retro`)
+Brief post-ship retrospective — 3-5 bullets:
+- What went well (gates caught rate-limit issue before PR)
+- What slowed down (schema index discovery required re-migration)
+- Next action (add rate-limit check to write-tests template)
+
 ---
 
 ### Scenario B — Fixing a Bug

package/commands/sk/finish-feature.md

@@ -155,6 +155,20 @@ If unresolved Critical/High findings remain, warn the user before proceeding.
 
    e) Report the PR URL to the user.
 
+8. **Capture Patterns** (`/sk:learn`)
+
+   After the PR is created, run `/sk:learn` to extract reusable patterns from this session.
+   Present extracted patterns and ask: "Save patterns? (all / 1,3 / none)"
+
+9. **Retrospective** (`/sk:retro`)
+
+   Run `/sk:retro` to capture a brief post-ship retrospective:
+   - What went well
+   - What slowed things down
+   - Top action items for next time
+
+   Output is appended to `tasks/progress.md`.
+
 ## When Done
 
 > "Feature finalized and PR created! Run `/sk:release` when ready to tag and publish."

package/commands/sk/help.md

@@ -21,21 +21,19 @@ Run these commands in order for a complete, quality-gated feature build.
 
 ## Feature Workflow
 
-| Command | Purpose |
-|---------|---------|
-| `/sk:brainstorm` | Explore requirements and design — **no code yet** |
-| `/sk:write-plan` | Write a decision-complete plan to `tasks/todo.md` |
-| `/sk:branch` | Create a feature branch from the current task |
-| `/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:smart-commit` | Conventional commit with approval |
-| `/sk:lint` | **GATE** — all linters must pass |
-| `/sk:test` | **GATE** — 100% coverage on new code |
-| `/sk:security-check` | **GATE** — 0 security issues |
-| `/sk:review` | **GATE** — blast-radius-aware self-review across 7 dimensions + cross-file impact |
-| `/sk:update-task` | Mark task done, log completion |
-| `/sk:finish-feature` | Changelog + PR creation |
+| # | Command | Purpose |
+|---|---------|---------|
+| 1 | `/sk:brainstorm` | Explore requirements — **no code yet** |
+| 2 | `/sk:frontend-design` or `/sk:api-design` | Design UI or API contracts *(auto-skip if no frontend/API keywords)* |
+| 3 | `/sk:write-plan` | Write a decision-complete plan to `tasks/todo.md` |
+| 4 | `/sk:branch` | Create a feature branch from the current task |
+| 5 | `/sk:write-tests` + `/sk:execute-plan` | TDD red + green (includes `/sk:schema-migrate` if DB keywords detected) |
+| 5.5 | `/sk:scope-check` | Trim scope creep — compare implementation to plan |
+| 6 | `/sk:smart-commit` | Conventional commit with approval |
+| 7 | `/sk:gates` | **All quality gates** — lint, test, security, perf, review, e2e *(hard gate)* |
+| 8 | `/sk:finish-feature` | Changelog + PR creation |
+| 8.5 | `/sk:learn` | Extract reusable patterns from this session |
+| 8.6 | `/sk:retro` | Post-ship retrospective — velocity, blockers, next actions |
 
 ## Requirement Change Flow
 

package/package.json

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

package/skills/sk:autopilot/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: sk:autopilot
-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.
+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.
 allowed-tools: Read, Write, Bash, Glob, Grep, Agent, Skill
 ---
 
 # Autopilot Mode
 
-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.
+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.
 
 ## When to Use
 
@@ -22,7 +22,7 @@ Hands-free workflow that executes all 8 steps of the ShipIt workflow with minima
 
 ## Quality Guarantee
 
-Autopilot runs the EXACT same 8 steps as manual mode:
+Autopilot runs the EXACT same workflow as manual mode (8 phases: explore, design, plan, branch, implement + scope check, commit, gates, ship + learn + retro):
 - ALL quality gates enforced (lint, test, security, perf, review, e2e)
 - ALL fix-rerun loops active
 - 100% test coverage required on new code
@@ -64,6 +64,13 @@ Create feature branch auto-named from the task. Do NOT ask for confirmation.
 - Run `/sk:execute-plan` (TDD green phase)
 - Auto-advance when done
 
+### 5.5. Scope Check (auto-advance)
+
+Run `/sk:scope-check` to compare the implementation against `tasks/todo.md`.
+
+- If scope creep detected: log findings, trim the excess, re-commit
+- If on-scope: auto-advance silently
+
 ### 6. Commit (auto-commit)
 
 Auto-commit with conventional commit format. Do NOT ask for commit message approval.
@@ -96,6 +103,20 @@ After confirmation:
 - Sync features (`/sk:features`)
 - Ask about release (never auto-skipped)
 
+### 8.5. Learn (auto-advance)
+
+Run `/sk:learn` to extract reusable patterns from this session.
+
+- Patterns are saved to `~/.claude/skills/learned/` automatically
+- Auto-advance after saving — no confirmation needed in autopilot
+
+### 8.6. Retro (auto-advance)
+
+Run `/sk:retro` to capture velocity, blockers, and action items for this feature.
+
+- Output is brief — 3-5 bullets covering what went well, what slowed down, and next actions
+- Appended to `tasks/progress.md`
+
 ## 3-Strike Protocol
 
 If any step fails 3 times:
@@ -111,6 +132,7 @@ If any step fails 3 times:
 | Direction approval | After brainstorm (step 1) | User must approve the approach |
 | 3-strike failure | Any step fails 3x | Needs human judgment |
 | PR push | Before creating PR (step 8) | Visible to others — always confirm |
+| Release | After step 8.6 | Never auto-skipped — always ask |
 
 Everything else auto-advances.
 

package/skills/sk:gates/SKILL.md

@@ -10,7 +10,7 @@ Run all quality gates (lint, test, security, perf, review, e2e) in optimized bat
 
 ## When to Use
 
-Run `/sk:gates` after committing implementation code (step 11). This single command handles steps 12-17 of the workflow.
+Run `/sk:gates` after `/sk:smart-commit` completes (step 6). This single command covers all quality gates (step 7 of the workflow).
 
 ## Execution Strategy
 
@@ -23,6 +23,7 @@ Launch 3 agents simultaneously:
 1. **Linter agent** — runs all formatters, analyzers, dep audits
 2. **`security-reviewer` agent** — OWASP audit on changed files (read-only; reports findings, does not fix)
 3. **`performance-optimizer` agent** — bundle, N+1, Core Web Vitals, memory (worktree isolation — finds AND fixes critical/high issues)
+   **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)`.
 
 These 3 have no dependencies on each other. Run them in parallel using the Agent tool.
 

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

@@ -51,9 +51,12 @@ Progress is tracked via git branch + `tasks/todo.md` checkboxes.
 | 3 | Plan | `/sk:write-plan` | required |
 | 4 | Branch | `/sk:branch` | required |
 | 5 | Write Tests + Implement | `/sk:write-tests` then `/sk:execute-plan` | required |
+| 5.5 | Scope Check | `/sk:scope-check` | required |
 | 6 | Commit | `/sk:smart-commit` | required |
 | 7 | Gates | `/sk:gates` | required (hard gate) |
 | 8 | Finalize | `/sk:finish-feature` | required |
+| 8.5 | Learn | `/sk:learn` | required |
+| 8.6 | Retro | `/sk:retro` | required |
 
 ### Step Details
 
@@ -62,9 +65,12 @@ Progress is tracked via git branch + `tasks/todo.md` checkboxes.
 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.
 4.  **Branch** — run `/sk:branch` to create a feature branch auto-named from the current task.
 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`.
+5.5. **Scope Check** — run `/sk:scope-check` to compare implementation against `tasks/todo.md`. Trim scope creep before committing.
 6.  **Commit** — run `/sk:smart-commit` to commit tests + implementation.
 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.
 8.  **Finalize** — run `/sk:finish-feature` for changelog, PR creation, `/sk:update-task`, `/sk:features` sync. Ask about `/sk:release` (never auto-skipped).
+8.5. **Learn** — run `/sk:learn` to extract reusable patterns from the session into `~/.claude/skills/learned/`.
+8.6. **Retro** — run `/sk:retro` for a brief post-ship retrospective (velocity, blockers, next actions).
 
 ### Workflow Rules
 
@@ -286,7 +292,7 @@ Create entries in: `[ARCH_CHANGELOG_DIR]`
 |---------|---------|
 | `/sk:accessibility` | WCAG 2.1 AA audit — runs after design, before implementation |
 | `/sk:api-design` | Design API contracts (endpoints, payloads, auth, errors) before implementation |
-| `/sk:autopilot` | Hands-free workflow — all 8 steps, auto-skip, auto-advance, auto-commit |
+| `/sk:autopilot` | Hands-free workflow — all 8 phases (scope check, learn, retro included), auto-skip, auto-advance, auto-commit |
 | `/sk:brainstorm` | Explore requirements and design (includes search-first research) |
 | `/sk:branch` | Create feature branch auto-named from current task |
 | `/sk:change` | Handle mid-workflow requirement changes — re-enter at correct step |

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

@@ -44,7 +44,7 @@ Before making any changes, runs a diagnostic pass on the existing CLAUDE.md:
 - **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
-- **Outdated workflow** — checks if the workflow matches the current 8-step flow with `/sk:gates` as single gate step
+- **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
 - **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
 - **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`
 - **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
 
 If the workflow section is outdated or missing, replace it with the latest version:
 
-**Current workflow (8 steps, TDD with `/sk:gates` as single gate step):**
+**Current workflow (11 steps, TDD with `/sk:gates` as single gate step):**
 ```
-Explore → Design → Plan → Branch → Write Tests + Implement → Commit → Gates → Finalize
+Explore → Design → Plan → Branch → Write Tests + Implement → Scope Check → Commit → Gates → Finalize + Learn + Retro
 ```
 
 **What gets updated:**
-- 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`)
+- 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`)
 - Step details (TDD red/green/verify descriptions)
 - Workflow rules (auto-advance, conditional summary, auto-skip, squash gate commits)
 - Bug fix flow section (7 steps)

package/skills/sk:start/SKILL.md

@@ -32,7 +32,7 @@ Read the task description from arguments. Scan for signal keywords to determine
 | bug, fix, broken, error, regression, failing, crash, wrong | `debug` (7 steps) |
 | urgent, prod down, hotfix, emergency, critical, production, incident | `hotfix` (6 steps) |
 | config, bump, typo, copy, rename, dependency, upgrade, version, docs | `fast-track` (5 steps) |
-| *(default — no special signals)* | `feature` (8 steps) |
+| *(default — no special signals)* | `feature` (8 phases + scope check, learn, retro) |
 
 **Scope detection:**
 
@@ -84,7 +84,7 @@ Present the classification and recommendation:
 ```
 Detected: [Full-stack feature / Backend bug fix / Frontend hotfix / Small config change / etc.]
 Recommended:
-  Flow:   [feature (8 steps) / debug (7 steps) / hotfix (6 steps) / fast-track (5 steps)]
+  Flow:   [feature (8 phases) / debug (7 steps) / hotfix (6 steps) / fast-track (5 steps)]
   Mode:   [autopilot / manual]
   Agents: [team (backend + frontend + QA) / solo]
 

package/skills/sk:team/SKILL.md

@@ -106,7 +106,7 @@ If both agents used worktree isolation and made changes:
 
 ### 5. Collect QA Agent Results
 
-Collect the QA Agent's E2E scenarios. These will be used in the E2E gate (step 17).
+Collect the QA Agent's E2E scenarios. These will be used in the E2E gate (step 7 / Batch 4).
 
 ### 6. Report Results