@kennethsolomon/shipkit 3.9.0 → 3.10.1

package/README.md

@@ -41,18 +41,23 @@ npm install -g @kennethsolomon/shipkit && shipkit
 /sk:setup-claude
 
 # 3. Start building
-/sk:brainstorm
+/sk:start
 ```
 
 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.
+
 ---
 
 ## Pick Your Flow
 
 | 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 |
@@ -204,12 +209,13 @@ Use these anytime — they're not part of any workflow.
 ## All Commands
 
 <details>
-<summary><strong>35 commands</strong> — click to expand</summary>
+<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 |
@@ -243,7 +249,9 @@ Use these anytime — they're not part of any workflow.
 | `/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` |

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.9.0",
+  "version": "3.10.1",
   "description": "A structured workflow toolkit for Claude Code.",
   "keywords": [
     "claude",

package/skills/.claude/settings.local.json

@@ -0,0 +1,37 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bash tests/verify-workflow.sh)",
+      "Bash(git add:*)",
+      "Bash(git commit:*)",
+      "Bash(node:*)",
+      "Bash(npm audit:*)",
+      "Bash(for f:*)",
+      "Bash(do echo:*)",
+      "Bash(bash -n \"$f\")",
+      "Bash(done)",
+      "Bash(tasks/security-findings.md:*)",
+      "Bash(git push:*)",
+      "Bash(git tag:*)",
+      "Bash(find /Users/kennethsolomon/Herd/shipit -type f -name *.md -path */node_modules/*commands/sk/*)",
+      "Bash(grep -r \"sk:\" /Users/kennethsolomon/Herd/shipit/commands/sk/*.md)",
+      "Bash(find /Users/kennethsolomon/Herd/shipit/.claude/docs -name *.md)",
+      "Bash(grep -v \"^Command$\")",
+      "Bash(find /Users/kennethsolomon/Herd/shipit -path */test* -o -path */__tests__/* -o -path */spec/*)",
+      "Bash(find /Users/kennethsolomon/Herd/shipit/commands/sk -type f -name *.md)",
+      "Bash(find /Users/kennethsolomon/Herd/shipit/skills -maxdepth 1 -type d -name sk:*)",
+      "Bash(python3 -m py_compile skills/sk:debug/lib/step_runner.py)",
+      "Bash(python3 -m py_compile skills/sk:debug/debug_conductor.py)",
+      "Bash(python3 -m py_compile skills/sk:setup-optimizer/lib/discover.py)",
+      "Bash(python3 -m py_compile skills/sk:debug/lib/findings_writer.py)",
+      "Bash(python3 -m py_compile skills/sk:debug/lib/lessons_writer.py)",
+      "Bash(python3 -m py_compile skills/sk:skill-creator/scripts/run_eval.py)",
+      "Bash(python3 -m py_compile skills/sk:skill-creator/scripts/run_loop.py)",
+      "Bash(python3 -m py_compile skills/sk:skill-creator/scripts/improve_description.py)",
+      "Bash(python3 -m py_compile skills/sk:skill-creator/scripts/generate_report.py)",
+      "Bash(python3 -m py_compile skills/sk:skill-creator/scripts/utils.py)",
+      "Bash(git:*)",
+      "Bash(npm publish:*)"
+    ]
+  }
+}

package/skills/sk:autopilot/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: sk:autopilot
+description: Hands-free workflow — runs all 21 steps with auto-skip, auto-advance, auto-commit. Stops only for direction approval, 3-strike failures, and PR push.
+user_invocable: true
+allowed_tools: Read, Write, Bash, Glob, Grep, Agent, Skill
+---
+
+# Autopilot Mode
+
+Hands-free workflow that executes all 21 steps of the ShipIt workflow with minimal interruptions. Same quality gates, same fix loops, same 100% coverage — just fewer stops.
+
+## When to Use
+
+- You know roughly what you want built and trust the workflow to handle details
+- You want to minimize context switches and manual step advancement
+- The task is well-defined enough for a single direction-approval checkpoint
+
+## When NOT to Use
+
+- Exploratory work where you want to steer each step
+- Tasks requiring frequent design decisions mid-implementation
+- When you want to review intermediate outputs before proceeding
+
+## Quality Guarantee
+
+Autopilot runs the EXACT same 21 steps as manual mode:
+- ALL quality gates enforced (lint, test, security, perf, review, e2e)
+- ALL fix-commit-rerun loops active
+- 100% test coverage required on new code
+- 0 security issues required
+- The ONLY difference: auto-advance between steps instead of stopping
+
+## Steps
+
+### 0. Reset Tracker
+
+Read `tasks/workflow-status.md`. If it has done/skipped steps from a different task, auto-reset all steps to `not yet`.
+
+### 1. Load Context (auto — no prompt)
+
+- Read `tasks/todo.md`
+- Read `tasks/lessons.md` (apply all active lessons as constraints)
+- Read `tasks/findings.md` (if exists)
+- Read `tasks/tech-debt.md` (if exists)
+
+### 2. Brainstorm + Direction Approval (STOP — requires user input)
+
+Run brainstorm internally:
+- Explore the codebase (3 parallel Explore agents)
+- Propose 2-3 approaches with trade-offs
+
+**Present ONE direction summary and ask:**
+> "Direction: [1-2 sentence summary of chosen approach]
+> Scope: [what will be built/changed]
+> Auto-skipping: [list of steps that will be auto-skipped and why]
+> Proceed? (y/n)"
+
+Wait for explicit `y` before continuing. This is the ONLY planning stop.
+
+### 3. Plan (auto-advance)
+
+Write the implementation plan to `tasks/todo.md`. Do NOT ask for plan approval — the direction approval in step 2 covers this.
+
+### 4. Branch (auto-advance)
+
+Create feature branch auto-named from the task. Do NOT ask for confirmation.
+
+### 5. Auto-Skip Detection
+
+Scan `tasks/todo.md` for frontend/backend/database keywords. For each optional step:
+- **Design (step 4)**: auto-skip if no frontend keywords
+- **Accessibility (step 5)**: auto-skip if no frontend keywords
+- **Migrate (step 8)**: auto-skip if no database keywords
+- **Performance (step 15)**: auto-skip if no frontend AND no database keywords
+
+Log each auto-skip: `Auto-skipped: [Step Name] ([reason])`
+
+### 6. Write Tests (auto-advance)
+
+Write failing tests based on the plan (TDD red phase). Auto-advance when done.
+
+### 7. Implement (auto-advance)
+
+Execute the plan — make failing tests pass. Use wave-based sub-agents for parallel work where possible.
+
+### 8. Commit (auto-commit)
+
+Auto-commit with conventional commit format. Do NOT ask for commit message approval.
+Format: `type(scope): description`
+
+### 9. Gates (auto-advance on clean pass)
+
+Run all quality gates. Use `/sk:gates` if available, otherwise run sequentially:
+1. Lint + dep audit
+2. Test (100% coverage)
+3. Security (0 issues)
+4. Performance (if not auto-skipped)
+5. Review + simplify
+6. E2E
+
+Each gate auto-fixes and re-runs internally. Auto-advance to next gate on clean pass.
+
+### 10. PR Push (STOP — requires user confirmation)
+
+**This is the second mandatory stop.** Present:
+> "All gates passed. Ready to create PR.
+> Title: [conventional format]
+> Changes: [file count] files, [line count] lines
+> Confirm push + PR? (y/n)"
+
+Wait for explicit confirmation — pushing is visible to others.
+
+### 11. Finalize (auto-advance)
+
+- Create PR
+- Sync features (`/sk:features`)
+- Ask about release (step 21 is never auto-skipped)
+
+## 3-Strike Protocol
+
+If any step fails 3 times:
+- **STOP immediately**
+- Report: what failed, what was tried, error details
+- Ask user for guidance before continuing
+- This overrides auto-advance — 3 strikes always stops
+
+## Stops Summary
+
+| Stop | When | Why |
+|------|------|-----|
+| Direction approval | After brainstorm (step 2) | User must approve the approach |
+| 3-strike failure | Any step fails 3x | Needs human judgment |
+| PR push | Before creating PR (step 10) | Visible to others — always confirm |
+
+Everything else auto-advances.
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+- If `model_overrides["sk:autopilot"]` 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/skills/sk:brainstorming/SKILL.md

@@ -34,7 +34,7 @@ You MUST create a task for each of these items and complete them in order:
    - Open questions (if any remain)
    Additionally, **append** an ADR entry to `docs/decisions.md` (see "Decisions Log" section below).
    (Optionally also write a full design doc to docs/plans/YYYY-MM-DD-<topic>-design.md)
-6. **Transition to implementation** — invoke writing-plans skill to create implementation plan
+6. **Transition to implementation** — invoke `/sk:write-plan` skill to create implementation plan
 
 ## Process Flow
 
@@ -46,7 +46,7 @@ digraph brainstorming {
     "Present design sections" [shape=box];
     "User approves design?" [shape=diamond];
     "Write design doc" [shape=box];
-    "Invoke writing-plans skill" [shape=doublecircle];
+    "Invoke `/sk:write-plan` skill" [shape=doublecircle];
 
     "Explore project context" -> "Ask clarifying questions";
     "Ask clarifying questions" -> "Propose 2-3 approaches";
@@ -54,11 +54,11 @@ digraph brainstorming {
     "Present design sections" -> "User approves design?";
     "User approves design?" -> "Present design sections" [label="no, revise"];
     "User approves design?" -> "Write design doc" [label="yes"];
-    "Write design doc" -> "Invoke writing-plans skill";
+    "Write design doc" -> "Invoke `/sk:write-plan` skill";
 }
 ```
 
-**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
+**The terminal state is invoking `/sk:write-plan`.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is `/sk:write-plan`.
 
 ## The Process
 
@@ -95,8 +95,8 @@ digraph brainstorming {
 - Commit the findings, decisions log entry, and any design document to git
 
 **Implementation:**
-- Invoke the writing-plans skill to create a detailed implementation plan
-- Do NOT invoke any other skill. writing-plans is the next step.
+- Invoke the `/sk:write-plan` skill to create a detailed implementation plan
+- Do NOT invoke any other skill. `/sk:write-plan` is the next step.
 
 ## Decisions Log
 

package/skills/sk:debug/debug_conductor.py

@@ -75,7 +75,6 @@ class DebugConductor:
             if not self._can_proceed(step):
                 print(f"\n⛔ BLOCKED: {self._gate_reason(step)}")
                 print("\nRun /debug again to continue from this step.")
-                self._save_progress()
                 return
 
             # Run step and update state
@@ -94,7 +93,6 @@ class DebugConductor:
                 proceed = input(f"\n✅ Step {step_num} complete. Continue to step {step_num + 1}? (y/n): ").strip().lower()
                 if proceed not in ['y', 'yes', '']:
                     print(f"Pausing after step {step_num}. Run /debug again to continue.")
-                    self._save_progress()
                     return
 
         print("\n" + "="*70)
@@ -161,12 +159,6 @@ class DebugConductor:
             return "No confirmed hypothesis yet—cannot propose fix."
         return "Precondition not met for this step."
 
-    def _save_progress(self):
-        """Save current state for resumption (optional)."""
-        # Could implement checkpoint system here
-        pass
-
-
 def main():
     """Entry point for /debug skill."""
     conductor = DebugConductor()

package/skills/sk:debug/lib/findings_writer.py

@@ -44,8 +44,8 @@ class FindingsWriter:
             self._append_entry(entry)
             print(f"\n✅ Findings written to {self.findings_path}")
             return True
-        except Exception as e:
-            print(f"\n❌ Error writing findings: {e}")
+        except OSError as e:
+            print(f"\n❌ Error writing findings to {self.findings_path}: {e}")
             return False
 
     def _ensure_file_exists(self):

package/skills/sk:debug/lib/lessons_writer.py

@@ -66,8 +66,8 @@ class LessonsWriter:
             self._append_lesson(entry)
             print(f"\n✅ New lesson added to {self.lessons_path}")
             return True
-        except Exception as e:
-            print(f"\n❌ Error writing lesson: {e}")
+        except OSError as e:
+            print(f"\n❌ Error writing lesson to {self.lessons_path}: {e}")
             return False
 
     def _ensure_file_exists(self):

package/skills/sk:debug/lib/step_runner.py

@@ -1,9 +1,11 @@
 """Execute individual debug steps (3-11)."""
 
+from __future__ import annotations
+
+import shlex
 import subprocess
-from typing import Dict
 from pathlib import Path
-import sys
+from typing import Dict
 
 
 class StepRunner:
@@ -42,8 +44,7 @@ class StepRunner:
             # Recent commits
             print("📋 Recent commits:")
             result = subprocess.run(
-                "git log --oneline -10",
-                shell=True,
+                ["git", "log", "--oneline", "-10"],
                 capture_output=True,
                 text=True
             )
@@ -52,8 +53,7 @@ class StepRunner:
             # Recent diffs
             print("\n📋 Recent file changes:")
             result = subprocess.run(
-                "git diff HEAD~3 --stat",
-                shell=True,
+                ["git", "diff", "HEAD~3", "--stat"],
                 capture_output=True,
                 text=True
             )
@@ -107,8 +107,7 @@ class StepRunner:
 
         try:
             result = subprocess.run(
-                command,
-                shell=True,
+                shlex.split(command),
                 capture_output=True,
                 text=True,
                 timeout=30
@@ -277,8 +276,7 @@ class StepRunner:
         if command:
             try:
                 result = subprocess.run(
-                    command,
-                    shell=True,
+                    shlex.split(command),
                     capture_output=True,
                     text=True,
                     timeout=30

package/skills/sk:lint/SKILL.md

@@ -171,8 +171,8 @@ Read `.shipkit/config.json` from the project root if it exists.
 
 | Profile | Model |
 |---------|-------|
-| `full-sail` | sonnet |
-| `quality` | sonnet |
+| `full-sail` | opus (inherit) |
+| `quality` | opus (inherit) |
 | `balanced` | haiku |
 | `budget` | haiku |
 

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

@@ -271,7 +271,16 @@ def _write_file_if_missing(dest: Path, content: str) -> Tuple[str, Path]:
     if dest.exists():
         return ("skipped", dest)
     dest.parent.mkdir(parents=True, exist_ok=True)
-    dest.write_text(content, encoding="utf-8")
+    # Atomic write: write to temp file then rename to avoid TOCTOU race
+    import tempfile
+    fd, tmp_path = tempfile.mkstemp(dir=dest.parent, suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        Path(tmp_path).replace(dest)
+    except BaseException:
+        Path(tmp_path).unlink(missing_ok=True)
+        raise
     return ("created", dest)
 
 
@@ -282,7 +291,7 @@ def _write_file_if_generated(dest: Path, content: str, template_path: Optional[P
         return ("created", dest)
     try:
         existing = dest.read_text(encoding="utf-8")
-    except Exception:
+    except (OSError, UnicodeDecodeError):
         return ("skipped", dest)
     if GENERATED_MARKER in existing:
         # Check if content is identical (fast path)
@@ -311,7 +320,7 @@ def _plan_file_if_generated(dest: Path, content: str) -> str:
         return "created"
     try:
         existing = dest.read_text(encoding="utf-8")
-    except Exception:
+    except (OSError, UnicodeDecodeError):
         return "skipped"
     if GENERATED_MARKER not in existing:
         return "skipped"

package/skills/sk:setup-claude/templates/.claude/agents/backend-dev.md

@@ -0,0 +1,63 @@
+---
+name: backend-dev
+model: sonnet
+description: Backend development agent — writes backend tests and implements API/services/models against the API contract.
+allowed_tools: Bash, Read, Edit, Write, Glob, Grep
+---
+
+# Backend Development Agent
+
+You are the Backend Agent in a team workflow. Your job is to write backend tests and implement backend code based on the plan and API contract.
+
+## Context
+
+You are working in an **isolated worktree** — a separate copy of the repository. Another agent (Frontend Agent) is working in parallel on frontend code. A QA Agent is writing E2E scenarios in the background.
+
+The **API contract** in `tasks/todo.md` is your shared interface with the Frontend Agent. Implement endpoints that match the contract exactly.
+
+## Behavior
+
+### 1. Read the Plan
+
+- Read `tasks/todo.md` — find the API contract section and all backend tasks
+- Read `tasks/lessons.md` — apply all active lessons
+- Identify: models, migrations, controllers, services, validation, routes
+
+### 2. Write Backend Tests (TDD Red Phase)
+
+Write failing tests for all backend behavior:
+- **Controller tests**: HTTP method, route, request validation, response shape
+- **Model tests**: Relationships, scopes, accessors, mutators
+- **Service tests**: Business logic, edge cases, error handling
+- **Validation tests**: All form request / input validation rules
+- Follow existing test conventions (read 1-2 existing test files first)
+
+### 3. Implement Backend Code (TDD Green Phase)
+
+Implement in dependency order:
+1. Migrations (if needed)
+2. Models + relationships
+3. Services / business logic
+4. Controllers + form requests
+5. Routes
+
+Make each test pass before moving to the next.
+
+### 4. Verify
+
+Run the backend test suite:
+- All new tests must pass
+- Existing tests must not break
+- Report: test count, pass/fail, coverage %
+
+### 5. Auto-Commit
+
+Commit with: `feat(backend): [description]`
+
+## Rules
+
+- ONLY touch backend files (models, controllers, services, migrations, routes, backend tests)
+- Do NOT touch frontend files (components, views, CSS, frontend tests)
+- Do NOT modify the API contract in `tasks/todo.md`
+- Follow the API contract exactly — request/response shapes must match
+- 3-strike protocol: if something fails 3 times, stop and report