@kennethsolomon/shipkit 3.15.1 → 3.16.0

package/README.md

@@ -21,6 +21,19 @@ npm install -g @kennethsolomon/shipkit && shipkit
 
 ---
 
+## What's New (v3.16.0 — March 2026)
+
+**Formal Agent Definitions, Path-Scoped Rules, and 2 new skills:**
+
+- **`.claude/agents/`** — 6 formal agent definitions (backend-dev, frontend-dev, qa-engineer, security-reviewer, code-reviewer, debugger) with `memory: project`, `isolation: worktree`, and `background: true` where appropriate. `/sk:setup-claude` deploys these to every new project.
+- **`.claude/rules/`** — 6 path-scoped rule files that auto-activate in Claude Code when you edit matching files: `laravel.md`, `react.md`, `vue.md`, `tests.md`, `api.md`, `migrations.md`. Stack-relevant rules are deployed by `/sk:setup-claude` automatically.
+- **`/sk:ci`** — Set up GitHub Actions or GitLab CI with Claude Code workflows: auto PR review, issue triage, nightly security audit, release automation. Supports enterprise setups (AWS Bedrock OIDC, Google Vertex AI Workload Identity).
+- **`/sk:plugin`** — Package your project-level customizations (skills, agents, hooks) into a distributable Claude Code plugin with a `.claude-plugin/plugin.json` manifest.
+- **Skill frontmatter upgrades** — model routing (`haiku` for lightweight skills, `sonnet` for analysis), `disable-model-invocation: true` on side-effect skills (commit, release, branch), `context: fork` on expensive standalone skills (seo-audit, accessibility, reverse-doc).
+- **Bug fix** — `allowed_tools` → `allowed-tools` (underscore typo silently ignored by Claude Code) fixed in 7 skills + all agent templates.
+
+---
+
 ## What is ShipKit?
 
 ShipKit turns Claude Code into a disciplined development partner. Instead of "write some code," every feature goes through:
@@ -90,6 +103,64 @@ npm install -g @kennethsolomon/shipkit && shipkit
 
 ---
 
+## Formal Agent Definitions
+
+`/sk:setup-claude` deploys 13 agent definitions to `.claude/agents/` — specialized sub-agents with `memory`, `model`, `tools`, and `isolation` pre-configured. Invoke any agent by mentioning its name in Claude Code.
+
+**Implementation agents** — build things:
+
+| Agent | Memory | Isolation | When to use |
+|-------|--------|-----------|------------|
+| `backend-dev` | project | worktree | Parallel backend work in `/sk:team` — API, services, models |
+| `frontend-dev` | project | worktree | Parallel frontend work in `/sk:team` — components, pages, state |
+| `mobile-dev` | project | worktree | React Native / Expo / Flutter — mobile-specific patterns and store prep |
+
+**Quality agents** — find and fix problems:
+
+| Agent | Memory | Isolation | When to use |
+|-------|--------|-----------|------------|
+| `qa-engineer` | project | background | Write E2E scenarios while other agents implement |
+| `code-reviewer` | project | — | 7-dimension review after implementation (read-only) |
+| `security-reviewer` | user | — | OWASP audit before shipping sensitive changes (read-only) |
+| `performance-optimizer` | project | worktree | When `/sk:perf` finds Critical/High issues — finds AND fixes them |
+
+**Design agents** — plan before building:
+
+| Agent | Memory | Isolation | When to use |
+|-------|--------|-----------|------------|
+| `architect` | project | — | Before `/sk:write-plan` on complex tasks — proposes options with trade-offs |
+| `database-architect` | project | — | Before `/sk:schema-migrate` — migration safety analysis and index recommendations |
+
+**Operations agents** — infrastructure and maintenance:
+
+| Agent | Memory | Isolation | When to use |
+|-------|--------|-----------|------------|
+| `devops-engineer` | project | worktree | CI/CD pipelines, Docker, deployment config — use with `/sk:ci` |
+| `debugger` | project | — | Structured root-cause analysis — use with `/sk:debug` |
+| `refactor-specialist` | project | worktree | Behavior-preserving cleanups — tests must pass before AND after |
+| `tech-writer` | project | — | README, API docs, architecture docs from existing code |
+
+`memory: project` — agent accumulates knowledge across sessions for that project. `isolation: worktree` — works in a separate git worktree, safe for risky changes. `background: true` — runs without blocking your conversation.
+
+---
+
+## Path-Scoped Rules
+
+`/sk:setup-claude` installs coding rule files in `.claude/rules/` that Claude Code auto-activates when you open or edit matching files — no manual context loading needed.
+
+| Rule file | Activates when editing | What it enforces |
+|-----------|----------------------|-----------------|
+| `laravel.md` | `app/**/*.php`, `routes/**`, `config/**` | Laravel conventions, service containers, Eloquent patterns |
+| `react.md` | `**/*.tsx`, `**/*.jsx`, `src/**/*.ts` | Hooks rules, component patterns, TypeScript strictness |
+| `vue.md` | `**/*.vue`, `resources/js/**/*.ts` | Composition API only, `<script setup>`, Pinia patterns |
+| `tests.md` | `tests/**`, `**/*.test.*`, `**/*.spec.*` | TDD standards, assertion quality, test isolation |
+| `api.md` | `routes/api.php`, `app/Http/Controllers/**` | RESTful conventions, auth patterns, error response shapes |
+| `migrations.md` | `database/migrations/**`, `prisma/**` | Migration safety rules, reversibility, index naming |
+
+Stack-relevant rules are detected and deployed automatically during `/sk:setup-claude` and `/sk:setup-optimizer`.
+
+---
+
 ## Pick Your Flow
 
 | I want to... | Run this | What happens |
@@ -253,6 +324,8 @@ Use these anytime — they're not part of any workflow.
 |---------|------------|
 | `/sk:reverse-doc` | Inherited codebase — generate architecture/design docs from existing code |
 | `/sk:setup-optimizer` | Maintenance — diagnose, update workflow, deploy hooks, enrich CLAUDE.md |
+| `/sk:ci` | Team — set up GitHub Actions / GitLab CI with PR review, issue triage, nightly audits |
+| `/sk:plugin` | Distribution — package custom skills/agents/hooks as a shareable Claude Code plugin |
 | `/sk:mvp` | New idea — generate a complete MVP app from a single prompt |
 | `/sk:status` | Quick view of workflow and task status |
 | `/sk:dashboard` | Visual Kanban board across all git worktrees |
@@ -328,10 +401,165 @@ Both `/sk:setup-claude` and `/sk:setup-optimizer` offer to install three tools t
 
 ---
 
+## Highest ROI Workflow — Using Every Feature
+
+This is the recommended workflow that gets the most value from every ShipKit feature. It's not the fastest path — it's the most reliable path over the lifetime of a project.
+
+### One-Time Project Setup (Do This Once)
+
+```bash
+# 1. Install ShipKit globally
+npm install -g @kennethsolomon/shipkit && shipkit
+
+# 2. Bootstrap your project
+/sk:setup-claude
+```
+
+`/sk:setup-claude` deploys: CLAUDE.md, lifecycle hooks, 13 agent definitions, path-scoped rules, planning files, LSP config, MCP servers (Sequential Thinking, Context7), and ccstatusline.
+
+```bash
+# 3. Set up CI (once per repo)
+/sk:ci
+```
+
+`/sk:ci` generates GitHub Actions workflows for auto PR review, issue triage, and nightly security audits. From this point on, every PR gets reviewed by Claude automatically.
+
+### Session Start (Every Session)
+
+The `session-start` hook fires automatically and loads: branch, recent commits, active task, tech debt, and code health. You see the session brief before you type anything.
+
+If starting on an unfamiliar codebase:
+```
+/sk:reverse-doc architecture src/
+```
+`/sk:reverse-doc` reads your code and generates architecture documentation — maps layers, traces data flow, asks clarifying questions to distinguish intentional design from accidental implementation. Run it once when you join a codebase or after a long break.
+
+### Feature Development (The Core Loop)
+
+**Step 1 — Before writing the plan, use the `architect` agent on complex tasks:**
+```
+Use the architect agent: analyze the authentication system and propose an approach for adding OAuth
+```
+The `architect` agent reads your findings, lessons, and existing code — then proposes 2-3 options with trade-offs. This prevents architectural mistakes before a single line is written.
+
+**Step 2 — For database changes, use the `database-architect` agent first:**
+```
+Use the database-architect agent: review the proposed users table changes
+```
+Gets you a migration safety classification (Safe / Careful / Breaking), index recommendations, and a deployment plan before `/sk:schema-migrate` runs.
+
+**Step 3 — Run the standard workflow:**
+```
+/sk:start               ← classifies task, routes to optimal flow
+/sk:brainstorm          ← explore requirements, extract checklist
+/sk:write-plan          ← decision-complete plan (auto-generates contracts.md for API tasks)
+/sk:branch              ← feature branch auto-named from task
+/sk:write-tests         ← TDD red: failing tests first
+/sk:execute-plan        ← TDD green: implement to pass tests
+/sk:smart-commit        ← conventional commit with approval
+/sk:gates               ← all 6 quality gates in parallel batches
+/sk:finish-feature      ← changelog + PR + arch log
+```
+
+**For full-stack features — run `/sk:team` instead of execute-plan:**
+```
+/sk:team
+```
+Spawns `backend-dev`, `frontend-dev`, and `qa-engineer` in parallel worktrees. Backend implements the API, frontend mocks and builds UI, QA writes E2E scenarios — simultaneously. Results merge after all complete.
+
+### During Gates — When Things Fail
+
+**Perf gate fails with Critical issues:**
+```
+Use the performance-optimizer agent: fix the N+1 queries found in /sk:perf
+```
+The `performance-optimizer` agent reads `tasks/perf-findings.md`, implements fixes, and runs tests to confirm no regression. Works in an isolated worktree.
+
+**Security gate blocks with High findings:**
+```
+Use the security-reviewer agent: audit the auth changes
+```
+The `security-reviewer` agent runs a focused OWASP audit. Its memory is `user`-scoped — it remembers security patterns across ALL your projects.
+
+**Review gate blocks:**
+```
+Use the code-reviewer agent
+```
+7-dimension review: correctness, security, performance, reliability, design, best practices, testing. Tells you exactly what to fix.
+
+### After Shipping
+
+```
+/sk:learn               ← extract reusable patterns from the session (confidence-scored)
+/sk:retro               ← velocity, blockers, patterns, 3-5 action items
+```
+
+`/sk:learn` is the compounding step. Each session adds patterns that future sessions apply automatically. Over time, you stop repeating the same mistakes.
+
+### Maintenance Workflows
+
+**Codebase cleanup:**
+```
+Use the refactor-specialist agent: clean up the authentication module
+```
+The `refactor-specialist` runs tests before starting, makes behavior-preserving changes one at a time, runs tests after each change, and commits with `refactor(scope): description`. If tests go red, it reverts and reports.
+
+**Documentation gaps:**
+```
+Use the tech-writer agent: document the payment service API
+```
+The `tech-writer` reads code first, never invents behavior, and produces README, API docs, or architecture docs in your project's existing style.
+
+**Mobile store submission:**
+```
+Use the mobile-dev agent: prepare the iOS release
+/sk:release --ios
+```
+
+**Infrastructure changes:**
+```
+Use the devops-engineer agent: set up Docker for local development
+/sk:ci                  ← or update CI workflows
+```
+
+### Health Checks (Weekly/Monthly)
+
+```
+/sk:health              ← scorecard across 7 categories (0-70)
+/sk:setup-optimizer     ← update CLAUDE.md, deploy missing agents/rules/hooks
+```
+
+`/sk:health` scores your project setup. `< 50` means you're leaving significant reliability on the table. `/sk:setup-optimizer` fixes the gaps.
+
+---
+
+### Summary: Which Tool for Which Situation
+
+| Situation | What to reach for |
+|-----------|------------------|
+| Starting a feature | `/sk:start` → `/sk:brainstorm` |
+| Complex architecture decision | `architect` agent before `/sk:write-plan` |
+| Database schema change | `database-architect` agent before `/sk:schema-migrate` |
+| Full-stack feature | `/sk:team` (parallel agents) |
+| Performance issues | `performance-optimizer` agent |
+| Security review | `security-reviewer` agent |
+| Code review | `code-reviewer` agent |
+| Bug investigation | `/sk:debug` + `debugger` agent |
+| Codebase cleanup | `refactor-specialist` agent |
+| Missing docs | `tech-writer` agent + `/sk:reverse-doc` |
+| CI/CD setup | `/sk:ci` + `devops-engineer` agent |
+| Mobile feature | `mobile-dev` agent |
+| New to a codebase | `/sk:reverse-doc` first |
+| Session start | Hooks auto-run, or `/sk:context` |
+| After shipping | `/sk:learn` + `/sk:retro` |
+| Monthly maintenance | `/sk:health` + `/sk:setup-optimizer` |
+
+---
+
 ## All Commands
 
 <details>
-<summary><strong>52 commands</strong> — click to expand</summary>
+<summary><strong>54 commands</strong> — click to expand</summary>
 
 | Command | Purpose |
 |---------|---------|
@@ -374,6 +602,8 @@ Both `/sk:setup-claude` and `/sk:setup-optimizer` offer to install three tools t
 | `/sk:schema-migrate` | Database schema change analysis |
 | `/sk:scope-check` | Detect scope creep mid-implementation |
 | `/sk:security-check` | OWASP security audit with content isolation and CVSS scoring |
+| `/sk:ci` | Set up Claude Code GitHub Actions or GitLab CI — PR review, issue triage, nightly audits, release automation |
+| `/sk:plugin` | Package custom skills, agents, and hooks as a distributable Claude Code plugin |
 | `/sk:seo-audit` | SEO audit for web projects |
 | `/sk:set-profile` | Switch model routing profile |
 | `/sk:website` | Build a complete, client-deliverable multi-page marketing website from a brief or URL. Supports `--stack nuxt`, `--stack laravel`, `--deploy`, `--revise`. Full guide: `docs/guides/sk-website-guide.md` |

package/bin/shipkit.js

@@ -105,17 +105,37 @@ function install() {
   // Install commands/sk/
   const commandsSrc  = path.join(pkgDir, 'commands', 'sk');
   const commandsDest = path.join(claudeDir, 'commands', 'sk');
+  const skillsSrc    = path.join(pkgDir, 'skills');
 
   if (fs.existsSync(commandsSrc)) {
-    copyDir(commandsSrc, commandsDest);
-    const count = countFiles(commandsSrc, '.md');
-    console.log(`  ${green}✓${reset} Installed commands/sk ${dim}(${count} commands)${reset}`);
+    fs.mkdirSync(commandsDest, { recursive: true });
+    let cmdCount = 0;
+    let skipped  = 0;
+    for (const entry of fs.readdirSync(commandsSrc, { withFileTypes: true })) {
+      const srcPath  = path.join(commandsSrc, entry.name);
+      const destPath = path.join(commandsDest, entry.name);
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath);
+      } else if (entry.name.endsWith('.md')) {
+        // Skip command file if a corresponding skill directory already exists
+        const skillName = 'sk:' + entry.name.replace(/\.md$/, '');
+        if (fs.existsSync(path.join(skillsSrc, skillName))) {
+          skipped++;
+          continue;
+        }
+        fs.copyFileSync(srcPath, destPath);
+        cmdCount++;
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+      }
+    }
+    const skipNote = skipped ? ` ${dim}(${skipped} skipped — covered by skills)${reset}` : '';
+    console.log(`  ${green}✓${reset} Installed commands/sk ${dim}(${cmdCount} commands)${reset}${skipNote}`);
   } else {
     console.log(`  ${yellow}!${reset} commands/sk not found — skipping`);
   }
 
   // Install skills/sk:*/
-  const skillsSrc  = path.join(pkgDir, 'skills');
   const skillsDest = path.join(claudeDir, 'skills');
   let skillCount = 0;
 

package/commands/sk/branch.md

@@ -1,5 +1,6 @@
 ---
 description: "Create a feature branch from the current task in tasks/todo.md."
+disable-model-invocation: true
 ---
 
 # /sk:branch

package/commands/sk/finish-feature.md

@@ -1,5 +1,6 @@
 ---
 description: "Finalize a feature/bug-fix: changelog, arch log, verification, and PR creation."
+disable-model-invocation: true
 ---
 
 # /sk:finish-feature

package/commands/sk/hotfix.md

@@ -1,5 +1,6 @@
 ---
 description: "Emergency fix workflow for production issues. Skips brainstorm, design, and TDD setup. Goes straight to: investigate → branch → fix → gates → ship."
+disable-model-invocation: true
 ---
 
 # /sk:hotfix

package/commands/sk/security-check.md

@@ -1,8 +1,9 @@
 ---
 description: "Audit changed code for security best practices, production-grade quality, and industry gold standards."
+disable-model-invocation: true
 ---
 
-<!-- Generated by /sk:setup-claude -->
+<!-- Thin wrapper — skill lives at skills/sk:security-check/SKILL.md -->
 
 # /sk:security-check
 

package/package.json

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

package/skills/sk:accessibility/SKILL.md

@@ -2,6 +2,9 @@
 name: sk:accessibility
 description: WCAG 2.1 AA accessibility audit. Use after /sk:frontend-design or on existing frontend code to catch accessibility issues before implementation or before shipping. Reports findings — does NOT fix code.
 license: Complete terms in LICENSE.txt
+model: haiku
+context: fork
+agent: general-purpose
 ---
 
 ## Purpose

package/skills/sk:autopilot/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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.
-allowed_tools: Read, Write, Bash, Glob, Grep, Agent, Skill
+allowed-tools: Read, Write, Bash, Glob, Grep, Agent, Skill
 ---
 
 # Autopilot Mode