@kennethsolomon/shipkit 1.0.0

package/commands/sk/execute-plan.md

@@ -0,0 +1,85 @@
+---
+description: "Execute tasks/todo.md checkboxes in small batches; log to tasks/progress.md."
+---
+
+<!-- Generated by /sk:setup-claude -->
+
+# /sk:execute-plan
+
+Execute the plan in `tasks/todo.md` in small batches with clear checkpoints.
+
+## Before You Start
+
+1. If `tasks/lessons.md` exists, read it in full. Treat every active lesson as a
+   standing constraint for this entire session. Apply each prevention rule before
+   executing the first batch.
+
+2. If `tasks/progress.md` exists and has Error Log entries, read the last 20 lines.
+   Do NOT repeat any action already recorded as a failed attempt — change approach.
+
+## Steps
+
+1. Read `tasks/todo.md` and identify the next unchecked items (up to ~6).
+2. **Analyze dependencies and build waves.** For each unchecked item, determine
+   which other items it depends on. Group independent items into **waves**:
+   - Tasks within a wave have no dependency on each other — they run in parallel.
+   - A wave only starts after the previous wave completes.
+   - Example: Task A and B are independent → Wave 1. Task C depends on A → Wave 2.
+3. **Execute each wave:**
+   - For waves with a single task, execute it directly.
+   - For waves with multiple tasks, dispatch each task to a **sub-agent** (Agent tool)
+     with fresh context. Each sub-agent receives:
+     - The specific task(s) to implement
+     - The full plan from `tasks/todo.md` for orientation
+     - Relevant file paths / codebase context needed for that task
+     - NOT the current conversation history (fresh context prevents context rot)
+   - Each task (whether direct or sub-agent):
+     - Make the smallest change that satisfies the step
+     - Run the verification specified (or add it if missing)
+     - Log what was done in `tasks/progress.md` (files touched + commands run + results)
+     - If something important was learned, append it to `tasks/findings.md`
+4. After all waves in the batch complete, report:
+   - what changed
+   - verification results
+   - what's next
+   - After all items in this batch pass verification, the code is ready to stage.
+     Run `/sk:smart-commit` after any passed batch, or accumulate and commit at plan completion.
+     Never combine more than one logical unit of work in a single commit.
+5. Stop and wait for user feedback before continuing.
+
+## Failure handling
+- Log every failure (error + attempt # + fix) in `tasks/progress.md`.
+- Do not repeat the same failing action; change approach.
+- After 3 failed attempts, stop and ask the user with details.
+
+## On User Correction
+
+If the user corrects your approach during execution, immediately append to
+`tasks/lessons.md`:
+
+```
+### [YYYY-MM-DD] [Brief title]
+**Bug:** What you did wrong
+**Root cause:** Why the approach was wrong
+**Prevention:** What to do instead next time
+```
+
+Then continue with the corrected approach.
+
+---
+
+## Model Routing
+
+Read `.shipkit/sk:config.json` from the project root if it exists.
+
+- If `model_overrides["sk:execute-plan"]` 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/features.md

@@ -0,0 +1,238 @@
+---
+name: features
+description: "Sync docs/sk:features/ specs with the current codebase. Auto-detects changed areas and updates only affected specs. Creates the spec system from scratch if it doesn't exist."
+---
+
+<!-- Generated by /sk:setup-claude -->
+
+# /sk:features
+
+Keep feature specifications in `docs/sk:features/` in sync with the actual codebase.
+Works with **any project** — framework-agnostic, auto-discovers source structure.
+
+## What This Does
+
+Maintains `docs/sk:features/` as a platform-agnostic feature specification system —
+the single source of truth shared between web, mobile, and any other platform
+that uses the same backend. Each spec covers: DB schema, business logic, API
+contract, permissions, edge cases, error states, web/mobile UI behavior, and
+platform divergences.
+
+---
+
+## Steps
+
+### Step 1: Detect Project State
+
+Check what exists:
+
+```bash
+ls docs/sk:features/ 2>/dev/null && echo "EXISTS" || echo "MISSING"
+ls docs/FEATURES.md 2>/dev/null && echo "INDEX_EXISTS" || echo "INDEX_MISSING"
+```
+
+**If `docs/sk:features/` does not exist:**
+Ask the user: "No feature specification system found. Create one from scratch?"
+- Yes → jump to **[Create From Scratch](#create-from-scratch)** below
+- No → stop
+
+**If `docs/sk:features/` exists:**
+Continue to Step 2.
+
+---
+
+### Step 2: Determine Update Scope
+
+Present three options:
+
+> **What would you like to update?**
+> **A. Auto-detect** *(recommended)* — scan recent git changes, update only affected specs
+> **B. Select features** — pick which specs to update from the list
+> **C. Refresh all** — update every spec from current source code
+
+Wait for the user's choice.
+
+---
+
+### Step 3A: Auto-detect Changed Features
+
+```bash
+git log --since="7 days ago" --name-only --pretty=format: | grep -v '^$' | sort -u
+```
+
+Map changed file paths to feature specs using these rules:
+
+1. **Read `docs/FEATURES.md`** to get the list of all spec files and their names.
+2. For each changed file, determine which spec it belongs to:
+   - Match by **feature name similarity**: if the spec is `expenses.md`, look for changed files containing `expense` in their path.
+   - Match by **directory**: if the spec is `budgets.md`, match files under any `budgets/` or `budget/` directory.
+   - Match by **schema files**: if any migration file, `schema.sql`, `schema.prisma`, `database.ts`, or similar schema file changed → mark ALL specs as potentially affected (schema changes ripple everywhere).
+3. Deduplicate the affected spec list.
+4. Report which specs will be updated and ask for confirmation.
+
+---
+
+### Step 3B: User Selects Features
+
+List all `.md` files in `docs/sk:features/` (excluding `_template.md`).
+Let the user pick which ones to update.
+
+---
+
+### Step 3C: Refresh All
+
+Set update list = all `.md` files in `docs/sk:features/` (excluding `_template.md`).
+
+---
+
+### Step 4: Update Each Affected Spec
+
+For each spec file to update, follow this sequence:
+
+#### 4a. Read the existing spec
+Understand its current content and section structure.
+
+#### 4b. Discover relevant source files
+
+Use a three-step lookup — no hardcoded paths:
+
+1. **Name-based search**: the feature name from the spec filename (e.g., `expenses.md` → feature name `expenses`). Search the repo:
+   ```bash
+   # Find files whose name contains the feature keyword
+   find . -type f \( -name "*expense*" -o -name "*expenses*" \) \
+     ! -path "*/node_modules/*" ! -path "*/.git/*" ! -path "*/docs/*" \
+     2>/dev/null | head -30
+   ```
+   Adjust the keyword to match the feature name.
+
+2. **Related Docs in spec**: read the `## Related Docs` section of the existing spec — it lists previously referenced files. Read those files too.
+
+3. **DB schema hint**: read the `## Database Schema` section — it names tables. Search migrations and schema files for those table names.
+
+#### 4c. Read the source files
+Read all discovered source files to understand the current implementation.
+
+#### 4d. Identify what changed
+Compare the current source code against what the spec describes:
+- New or removed DB columns / tables / constraints
+- Changed business logic rules or state transitions
+- New/changed API payloads or query patterns
+- Updated permission keys or tier requirements
+- New edge cases, error codes, or recovery paths
+
+#### 4e. Update only changed sections
+Rewrite only the sections that are out of date. **Preserve all unchanged sections verbatim.**
+Update the `> Status` block if the implementation status on either platform changed.
+
+---
+
+### Step 5: Handle New Features
+
+If source code has a clear new feature (new hook, new route group, new major component) with no corresponding spec:
+
+1. Create `docs/sk:features/<feature-name>.md` using `docs/sk:features/_template.md` as base.
+   If `_template.md` doesn't exist, use this 11-section structure:
+   ```
+   Status → Overview → Database Schema → Business Logic → API Contract
+   → Permissions & Access Control → Edge Cases → Error States
+   → UI/UX Behavior (### Web + ### Mobile) → Platform Notes → Related Docs
+   ```
+2. Fill all 11 sections from current source code.
+3. Add the new spec to `docs/FEATURES.md` under the appropriate section.
+
+---
+
+### Step 6: Update Master Index
+
+Review `docs/FEATURES.md`:
+- Add links for any new specs
+- Update status columns (Web / Mobile) if implementation status changed
+- Update any tier/feature tables if permissions changed
+
+---
+
+### Step 7: Report and Commit
+
+Show a summary:
+- ✅ **Updated**: `spec-name.md` — what changed (1 sentence each)
+- ➕ **Added**: any new spec files
+- ⏭️ **Skipped**: specs with no detected changes
+
+Ask: **"Commit the updated specs?"**
+- Yes → stage only files under `docs/` and commit:
+  `docs(features): update feature specs to reflect current implementation`
+- No → leave changes unstaged for the user to review
+
+---
+
+## Create From Scratch
+
+When `docs/sk:features/` doesn't exist, discover and document all features:
+
+### Discovery Phase
+
+1. **Detect source structure** — find where feature logic lives:
+   ```bash
+   # Look for hooks, services, controllers, models, routes
+   ls src/ lib/ app/ 2>/dev/null
+   find . -maxdepth 4 -type f \
+     \( -name "use-*.ts" -o -name "use-*.js" \
+        -o -name "*.service.ts" -o -name "*.controller.ts" \
+        -o -name "*.model.ts" -o -name "*.router.ts" \) \
+     ! -path "*/node_modules/*" ! -path "*/.git/*" 2>/dev/null | head -50
+   ```
+
+2. **Detect schema files** — migrations, ORM schemas:
+   ```bash
+   find . -maxdepth 5 \
+     \( -name "schema.sql" -o -name "*.schema.prisma" \
+        -o -name "database.ts" -o -name "*.migration.*" \) \
+     ! -path "*/node_modules/*" ! -path "*/.git/*" 2>/dev/null
+   ls supabase/migrations/ 2>/dev/null | tail -10
+   ls prisma/ 2>/dev/null
+   ```
+
+3. **Identify feature domains** from the discovered files — group related files into named features.
+
+4. **Report discovered features** and ask the user to confirm/adjust the list before creating anything.
+
+### Creation Phase
+
+For each confirmed feature:
+1. Read all relevant source files.
+2. Create `docs/sk:features/<feature-name>.md` with all 11 sections — based entirely on source code.
+
+Also create:
+- `docs/FEATURES.md` — master index with:
+  - How-to-use section (web path + mobile path via `../project-name/docs/`)
+  - Feature table grouped by domain
+  - Tier/subscription overview (if the project has tiers)
+- `docs/sk:features/_template.md` — 11-section template for future specs
+
+Commit: `docs: add feature specification system`
+
+---
+
+## Quality Rules (Always Apply)
+
+- **Source-verified only** — every claim must be findable in source code; never invent behavior
+- **No placeholders** — no `// TODO`, no `false // will be computed`, no assumed values
+- **Surgical updates** — only rewrite what changed; preserve unchanged sections verbatim
+- **Numeric JSX coercion** — when documenting frontend behavior, note `!!value` (not `value &&`) for numerics to avoid rendering `0` as text in React/React Native
+- **Local date, not UTC** — for any time-bounded query (current month, today, etc.), document that implementations must use local `new Date()`, not `toISOString()` which returns UTC and causes off-by-one for users in non-UTC timezones
+- **All 11 sections required** — mark "N/A" only if genuinely not applicable
+
+## Source Discovery Heuristics (Reference)
+
+When locating source files for a feature named `<name>`:
+
+| What to look for | Search pattern |
+|---|---|
+| Hooks / composables | `use-<name>.*`, `use<Name>.*` |
+| Components | directories or files matching `<name>/`, `*<name>*` |
+| API routes / controllers | `<name>.route.*`, `<name>.controller.*`, `api/<name>/` |
+| Services / repositories | `<name>.service.*`, `<name>.repo.*` |
+| DB schema | `migrations/` containing table name, `schema.prisma`, `database.ts` |
+| Tests | `<name>.test.*`, `<name>.spec.*` |
+
+These are starting points — read broadly and verify before updating any section.

package/commands/sk/finish-feature.md

@@ -0,0 +1,154 @@
+<!-- Generated by /sk:setup-claude -->
+<!-- Template Hash: 7deba6efd53c -->
+
+# Finish Feature Command
+
+Finalize a feature/bug-fix branch: changelog, arch log, security gate, verification, and PR creation.
+
+This is the **last step before `/sk:release`**. It auto-commits documentation changes (changelog, arch log) so you don't need to loop back to `/sk:smart-commit` for docs-only work.
+
+## Before You Start
+
+If `tasks/lessons.md` exists, read it in full. For each active lesson, scan the
+final diff (`git diff main..HEAD`) for the **Bug** pattern described in that lesson
+before marking the feature done. This is the last gate before merge — catch recurring
+mistakes here rather than in review.
+
+If `tasks/security-findings.md` exists, read it. Check that any Critical or High
+severity findings from the most recent `/sk:security-check` audit have been addressed.
+If unresolved Critical/High findings remain, warn the user before proceeding.
+
+## Steps
+
+1. **Check Git Branch**
+   - Verify you are not on `main`
+   - Create a branch if needed: `feature/<desc>`, `fix/<desc>`, or `chore/<desc>`
+
+2. **Show Branch Summary**
+   - `git status --short`
+   - `git log main..HEAD --oneline`
+
+3. **Verify `CHANGELOG.md` Updated**
+   - Ensure an entry exists under `[Unreleased]`
+   - Follow `.claude/docs/changelog-guide.md`
+   - If CHANGELOG.md needs updating, make the edit and auto-commit:
+     ```bash
+     git add CHANGELOG.md
+     git commit -m "docs: update CHANGELOG.md for unreleased changes"
+     ```
+
+4. **Check for Architectural Changes**
+
+   The auto-detector scans for architecture-relevant changes:
+   - Schema/database changes (migrations, models, databases)
+   - API/route structure changes (endpoints, controllers)
+   - Component/module organization changes
+   - Configuration changes affecting architecture
+   - New subsystems or major refactors
+   - Dependency changes
+
+   Run to see what would be detected:
+   ```bash
+   python3 $HOME/.claude/skills/sk:setup-claude/scripts/detect_arch_changes.py --dry-run
+   ```
+
+   If architectural changes detected:
+   a) **Auto-generate the draft:**
+      ```bash
+      python3 $HOME/.claude/skills/sk:setup-claude/scripts/detect_arch_changes.py
+      ```
+      This creates a markdown draft in `.claude/docs/architectural_change_log/`
+
+   b) **Review and edit the draft:**
+      - Open the generated file
+      - Fill in [TODO] sections:
+        - Detailed Changes: What specifically changed?
+        - Before & After: Show the comparison
+        - Affected Components: What parts of system are impacted?
+        - Migration/Compatibility: Any breaking changes?
+      - Verify the auto-filled sections (Summary, Type, What Changed, Impact)
+
+   c) **Auto-commit the arch log** (no need to go back to `/sk:smart-commit`):
+      ```bash
+      git add .claude/docs/architectural_change_log/
+      git commit -m "docs: add architectural changelog entry"
+      ```
+
+   If no architectural changes detected: skip to step 5.
+
+5. **Verification** (with Test Checklist for Reviewers)
+
+   Tests should have been created during `/sk:execute-plan`. Verify:
+
+   a) **Automated Tests**
+      - Execute: `npm test`
+      - Verify all tests pass with no failures
+      - Check test coverage (target: >80% for new code in `Unknown` projects)
+      - No skipped tests (`test.skip`, `it.skip`, `@skip`, etc.)
+      - Run other CI checks: lint (`npm run lint` or equivalent), build (`npm run build` or equivalent)
+
+   b) **Manual Testing - Unknown / Unknown**
+      - For frontend (Unknown): Render the component/page in browser, verify state updates work correctly, test all user interactions (clicks, form inputs, navigation), verify conditional rendering, check edge cases and error states
+      - For backend/API (Unknown): Test HTTP status codes and responses, verify request/response bodies match spec, test error cases and input validation, check database transactions/state, verify authentication/authorization if applicable
+      - For CLI/desktop (Unknown): Test command-line arguments and flags, verify output format and readability, test error messages and help text, check file I/O operations
+      - Using Unknown framework: Verify test structure matches project conventions, assertions are clear and specific, setup/teardown is properly handled
+
+   c) **Regression Testing**
+      - Test related existing functionality to ensure no breakage
+      - For Unknown projects: check related components/endpoints/commands work correctly
+      - Verify no new console errors, warnings, or debug statements
+      - Confirm existing tests still pass
+
+   d) **Code Quality Checks**
+      - No hardcoded test data, credentials, or environment-specific values in production code
+      - Proper error handling and validation
+      - No debugging code (`console.log`, `debugger`, `pdb`, `print` statements, etc.)
+      - Comments explain *why*, not *what*
+      - Follows Unknown conventions and style guide (see `CLAUDE.md`)
+
+6. **Security Gate**
+   - If `/sk:security-check` has not been run on this branch, recommend: "Run `/sk:security-check` before creating a PR."
+   - If `tasks/security-findings.md` has unresolved Critical or High findings, list them and ask the user to confirm they've been addressed.
+
+7. **Create Pull Request**
+
+   a) **Check remote status:**
+   ```bash
+   git remote -v
+   git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo "no upstream"
+   ```
+
+   b) **Push branch if needed:**
+   ```bash
+   git push -u origin HEAD
+   ```
+
+   c) **Generate PR title and body:**
+      - Title: Short, imperative, under 70 characters
+      - Body: Summary of changes, review findings (if any from `/sk:review`), test status
+
+   d) **Create PR:**
+   ```bash
+   gh pr create --title "title here" --body "$(cat <<'EOF'
+   ## Summary
+   - bullet points of key changes
+
+   ## Review Notes
+   - Any findings from /sk:review (or "Clean review — no issues found")
+
+   ## Security
+   - Security check status (passed / N findings addressed)
+
+   ## Test Plan
+   - How to verify the changes
+
+   Generated with [Claude Code](https://claude.com/claude-code)
+   EOF
+   )"
+   ```
+
+   e) Report the PR URL to the user.
+
+## When Done
+
+> "Feature finalized and PR created! Run `/sk:release` when ready to tag and publish."

package/commands/sk/help.md

@@ -0,0 +1,103 @@
+---
+description: "Show all ShipKit commands and workflow overview."
+---
+
+# /sk:help — ShipKit
+
+A structured workflow toolkit for Claude Code.
+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** — self-review across 7 dimensions |
+| `/sk:update-task` | Mark task done, log completion |
+| `/sk:finish-feature` | Changelog + PR creation |
+
+## Bug Fix Workflow
+
+| Command | Purpose |
+|---------|---------|
+| `/sk:debug` | Root-cause analysis |
+| `/sk:write-plan` | Fix plan |
+| `/sk:branch` | Feature branch |
+| `/sk:write-tests` | Reproduce the bug in a test |
+| `/sk:execute-plan` | Fix the bug |
+| `/sk:lint` → `/sk:test` → `/sk:security-check` → `/sk:review` | Quality gates |
+| `/sk:finish-feature` | Changelog + PR |
+
+## All Commands
+
+| Command | Description |
+|---------|-------------|
+| `/sk:accessibility` | WCAG 2.1 AA audit on frontend code |
+| `/sk:api-design` | Design REST/GraphQL contracts before implementation |
+| `/sk:brainstorm` | Explore requirements, no code |
+| `/sk:branch` | Create branch from current task |
+| `/sk:debug` | Structured bug investigation |
+| `/sk:execute-plan` | Implement plan in batches |
+| `/sk:features` | Sync docs/sk:features/ specs with codebase |
+| `/sk:finish-feature` | Changelog + PR creation |
+| `/sk:frontend-design` | UI mockup + design spec before implementation |
+| `/sk:hotfix` | Emergency fix workflow (skips design/TDD) |
+| `/sk:laravel-init` | Configure existing Laravel project |
+| `/sk:laravel-new` | Scaffold new Laravel project |
+| `/sk:lint` | Auto-detect and run all linters |
+| `/sk:perf` | Performance audit |
+| `/sk:plan` | Create/refresh task planning files |
+| `/sk:release` | Version bump + changelog + tag |
+| `/sk:review` | Self-review of branch changes |
+| `/sk:schema-migrate` | Multi-ORM schema change analysis |
+| `/sk:security-check` | OWASP security audit |
+| `/sk:setup-claude` | Bootstrap project scaffolding |
+| `/sk:setup-optimizer` | Enrich CLAUDE.md by scanning codebase |
+| `/sk:skill-creator` | Create or improve skills |
+| `/sk:smart-commit` | Conventional commit with approval |
+| `/sk:status` | Show workflow and task status |
+| `/sk:test` | Auto-detect and verify all tests pass |
+| `/sk:update-task` | Mark task done, log completion |
+| `/sk:write-plan` | Write plan to `tasks/todo.md` |
+| `/sk:write-tests` | TDD: write failing tests first |
+| `/sk:config` | View and edit project config |
+| `/sk:set-profile` | Switch model routing profile |
+
+---
+
+## Model Routing Profiles
+
+ShipKit routes each skill to the right model automatically. Set once per project:
+
+```
+/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
+```
+
+| 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 |
+| 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/sk:config.json` — per project, gitignored by default.
+
+---
+
+**ShipKit** by Kenneth Solomon · `npx @kennethsolomon/shipkit` to install/update

package/commands/sk/hotfix.md

@@ -0,0 +1,61 @@
+---
+description: "Emergency fix workflow for production issues. Skips brainstorm, design, and TDD setup. Goes straight to: investigate → branch → fix → gates → ship."
+---
+
+# /sk:hotfix
+
+Emergency workflow for production issues that need to ship fast. Skips brainstorm, design, and write-tests phases. Quality gates still apply — they cannot be skipped.
+
+## When to Use
+
+- A bug is causing production impact RIGHT NOW
+- There is no time for full TDD workflow
+- The fix is small and well-understood
+
+**If the bug is complex or the fix is unclear, use the full Bug Fix Flow (`/sk:debug`) instead.**
+
+## Before You Start
+
+1. Read `tasks/lessons.md` — apply any relevant lessons immediately
+2. Read `tasks/todo.md` — note the bug being fixed for tracking
+
+## Hotfix Flow
+
+| # | Step | Command | Notes |
+|---|------|---------|-------|
+| 1 | Investigate | `/sk:debug` | Root-cause analysis only — understand before touching code |
+| 2 | Branch | `/sk:branch` | Auto-named from the bug description |
+| 3 | Fix | implement directly | No write-tests phase — go straight to the fix |
+| 4 | Smoke Test | run existing tests | Existing tests MUST still pass — no new failures allowed |
+| 5 | Commit | `/sk:smart-commit` | Commit the fix |
+| 6 | **Lint** | `/sk:lint` | **GATE** — all lint tools must pass |
+| 7 | Commit | `/sk:smart-commit` | Skip if lint was clean |
+| 8 | **Verify Tests** | `/sk:test` | **GATE** — all existing tests must pass |
+| 9 | Commit | `/sk:smart-commit` | Skip if tests passed first try |
+| 10 | **Security** | `/sk:security-check` | **GATE** — 0 issues across all severities |
+| 11 | Commit | `/sk:smart-commit` | Skip if security was clean |
+| 12 | **Review** | `/sk:review` | **GATE** — 0 issues including nitpicks |
+| 13 | Commit | `/sk:smart-commit` | Skip if review was clean |
+| 14 | Update | `/sk:update-task` | Mark done, log completion |
+| 15 | Finalize | `/sk:finish-feature` | Changelog + PR — mark PR as hotfix |
+
+## Quality Gates Are Non-Negotiable
+
+Even in a hotfix, **gates 6, 8, 10, and 12 cannot be skipped.** Fix issues immediately and re-run. A broken hotfix is worse than no hotfix.
+
+## After Merging
+
+Consider creating a follow-up task to:
+- Write a regression test for the bug that was just fixed
+- Add a lesson to `tasks/lessons.md` if this bug reveals a recurring pattern
+- Review whether the root cause points to a broader systemic issue
+
+## Step Summary Format
+
+After each step, output:
+
+```
+--- Hotfix Step [#] [Name]: [done/skipped] ---
+Summary: [what was done]
+Next step: [#] [Name] — run `[command]`
+```

package/commands/sk/plan.md

@@ -0,0 +1,30 @@
+---
+description: "Create/refresh tasks planning files and start planning."
+---
+
+<!-- Generated by /sk:setup-claude -->
+
+# /sk:plan
+
+Initialize planning files in `tasks/` (create-if-missing) and start Phase 1 planning.
+
+## Before You Start
+
+If `tasks/lessons.md` exists, read it in full. Apply every active lesson as a
+constraint when filling `tasks/todo.md` — lessons represent decisions already made
+about what not to do on this project.
+
+## Steps
+
+1. Ensure `tasks/` exists.
+2. If missing, create:
+   - `tasks/todo.md`
+   - `tasks/findings.md`
+   - `tasks/progress.md`
+3. Read `tasks/todo.md` and ask the user:
+   - What’s the goal?
+   - What are the constraints?
+   - What does “done” look like?
+4. Fill `tasks/todo.md` (Goal + Plan + Verification + Acceptance Criteria).
+5. Continue with `/sk:write-plan` if you need a more detailed plan.
+