@kennethsolomon/shipkit 3.7.0 → 3.8.0

package/README.md

@@ -177,6 +177,7 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/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
 
@@ -189,6 +190,7 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/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
 
@@ -206,6 +208,8 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/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
 
@@ -216,6 +220,7 @@ Requirement changes → /sk:change → re-enter at correct step
 | `/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
 

package/package.json

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

package/skills/sk:fast-track/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: sk:fast-track
+description: Abbreviated workflow for small, clear changes — skip planning ceremony, keep all quality gates
+user_invocable: true
+allowed_tools: Read, Write, Bash, Glob, Grep, Agent, Skill
+---
+
+# Fast-Track Flow
+
+Abbreviated workflow for small, well-understood changes. Skips brainstorm, design, plan, and write-tests phases but still enforces all quality gates.
+
+## When to Use
+
+- Config changes, dependency bumps, copy/wording changes
+- Small refactors with obvious scope
+- Adding a missing test for existing code
+- Fixing a typo or updating documentation
+- Any change where the "what" is already clear and doesn't need design exploration
+
+## When NOT to Use
+
+- New features (use full workflow)
+- Changes affecting multiple systems (use full workflow)
+- Anything requiring design decisions (use `/sk:brainstorm` first)
+- Bug fixes (use `/sk:debug` flow)
+
+## Guard Rails
+
+Before proceeding, check the scope of planned changes:
+
+1. **Diff size check**: After implementation, run `git diff --stat HEAD`. If the diff exceeds **300 lines** changed:
+   > "This change is [N] lines — larger than the 300-line fast-track threshold. Consider the full workflow for better test coverage. Continue anyway? (y/n)"
+
+2. **New file count**: If more than **5 new files** are created:
+   > "You've created [N] new files. Consider running `/sk:write-tests` first. Continue anyway? (y/n)"
+
+3. **Migration check**: If any migration files are detected in changes, warn:
+   > "Migration files detected. Consider running `/sk:schema-migrate` for analysis."
+
+## Steps
+
+### 1. Context (quick)
+- Read `tasks/todo.md` — pick the task or accept user's description
+- Read `tasks/lessons.md` — apply active lessons as constraints
+
+### 2. Branch
+- Run `/sk:branch` to create a feature branch
+
+### 3. Implement
+- Write the code directly — no brainstorm, design, plan, or TDD phases
+- Focus on the minimal change needed
+
+### 4. Commit
+- Run `/sk:smart-commit` to stage and commit with conventional commit message
+
+### 5. Gates
+- Run `/sk:gates` — all quality gates in optimized parallel batches
+- This is the same gate process as the full workflow — no shortcuts on quality
+- Lint, test, security, perf, review, E2E all run
+
+### 6. Finalize
+- Run `/sk:finish-feature` for changelog + PR
+
+## Workflow Status
+
+Fast-track updates `tasks/workflow-status.md` with abbreviated steps:
+- Steps 1-2 (read): done
+- Steps 3-6 (explore, design, accessibility, plan): skipped (fast-track)
+- Steps 7-11 (branch, implement, commit): done
+- Steps 12-17 (gates): handled by `/sk:gates`
+- Steps 18-21 (update, finalize, sync, release): done as applicable
+
+## Model Routing
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |

package/skills/sk:gates/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: sk:gates
+description: Run all quality gates in optimized parallel batches — one command instead of six
+user_invocable: true
+allowed_tools: Agent, Read, Write, Bash, Glob, Grep
+---
+
+# Gates Orchestrator
+
+Run all quality gates (lint, test, security, perf, review, e2e) in optimized batches. Replaces manually invoking 6 separate commands.
+
+## When to Use
+
+Run `/sk:gates` after committing implementation code (step 11). This single command handles steps 12-17 of the workflow.
+
+## Execution Strategy
+
+Gates are organized into 4 batches for maximum parallelism while respecting dependencies:
+
+### Batch 1 — Parallel Agents (lint + security + perf)
+
+Launch 3 agents simultaneously:
+
+1. **Linter agent** — runs all formatters, analyzers, dep audits
+2. **Security auditor agent** — OWASP audit on changed files
+3. **Performance auditor agent** — bundle, N+1, Core Web Vitals, memory
+
+These 3 have no dependencies on each other. Run them in parallel using the Agent tool.
+
+Wait for all 3 to complete. Collect results.
+
+### Batch 2 — Test Agent (sequential, needs lint fixes)
+
+After Batch 1 completes (lint may have auto-formatted code):
+
+4. **Test runner agent** — runs all test suites, ensures 100% coverage on new code
+
+### Batch 3 — Review (main context, needs test confirmation)
+
+After Batch 2 completes:
+
+5. **Review** — runs `/sk:review` in the main context (NOT as an agent) because review needs deep code understanding and access to the full conversation history
+
+### Batch 4 — E2E Agent (needs review fixes)
+
+After Batch 3 completes:
+
+6. **E2E tester agent** — runs full E2E verification
+
+## Gate Results
+
+After all 4 batches complete, output a summary:
+
+```
+=== Gate Results ===
+Lint:     clean (attempt N)
+Security: 0 findings (attempt N)
+Perf:     0 critical/high (attempt N)
+Tests:    X passed, 0 failed (attempt N)
+Review:   0 issues (attempt N)
+E2E:      Y scenarios passed (attempt N)
+
+All gates passed. Run /sk:update-task
+```
+
+## Failure Handling
+
+- Each agent handles its own fix → auto-commit → re-run loop internally
+- If any agent fails after 3 attempts → stop all gates and report to user
+- Do NOT proceed to the next batch if the current batch has unresolved failures
+- Update `tasks/workflow-status.md` for each gate as it completes:
+  - Steps 12-17 marked `done` with attempt count in Notes
+
+## 3-Strike Protocol
+
+If any single gate fails 3 times:
+1. Stop the entire gates process
+2. Log the failure to `tasks/progress.md`
+3. Report to user with details of what failed and what was tried
+4. Do NOT mark the step as done
+
+## Model Routing
+
+The orchestrator itself runs in the main context. Agents use their own model routing:
+- Linter: haiku (mechanical)
+- Test runner: sonnet
+- Security auditor: sonnet
+- Perf auditor: sonnet
+- E2E tester: sonnet
+- Review: main context model (opus or sonnet depending on profile)
+
+| Profile | Orchestrator Model |
+|---------|-------------------|
+| `full-sail` | opus (inherit) |
+| `quality` | opus (inherit) |
+| `balanced` | sonnet |
+| `budget` | sonnet |

package/skills/sk:retro/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: sk:retro
+description: Post-ship retrospective analyzing velocity, blockers, and patterns to generate actionable improvements
+user_invocable: true
+allowed_tools: Read, Glob, Grep, Bash, Write
+---
+
+# Retrospective
+
+Analyze completed work after shipping a feature to generate actionable insights for the next iteration.
+
+## When to Use
+
+Run `/sk:retro` after `/sk:finish-feature` or `/sk:release` to reflect on what went well, what didn't, and what to improve. Best run while context is fresh.
+
+## Steps
+
+### 1. Gather Data
+
+Read these files to build the retrospective:
+
+| File | What to Extract |
+|------|----------------|
+| `tasks/todo.md` | Planned tasks — count total, completed, dropped |
+| `tasks/progress.md` | Work log — errors, resolutions, session timestamps |
+| `tasks/workflow-status.md` | Step-by-step status — attempt counts, skip reasons |
+| `tasks/findings.md` | Design decisions — were they validated? |
+| `tasks/lessons.md` | New lessons added during this task |
+| `tasks/tech-debt.md` | Tech debt logged during gates |
+
+### 2. Analyze Git History
+
+```bash
+# Commits on this branch
+git log main..HEAD --oneline --format="%h %s"
+
+# Time span
+git log main..HEAD --format="%ai" | tail -1  # first commit
+git log main..HEAD --format="%ai" | head -1  # last commit
+
+# Files changed
+git diff main..HEAD --stat
+
+# Commit count
+git rev-list main..HEAD --count
+```
+
+### 3. Calculate Metrics
+
+| Metric | How |
+|--------|-----|
+| **Completion rate** | Completed tasks / Planned tasks * 100 |
+| **Velocity** | Commits per day, files changed per day |
+| **Gate performance** | Extract attempt counts from workflow-status.md Notes (e.g., "clean on attempt 3") |
+| **Blocker count** | Count "FAIL", "error", "blocked", "3-Strike" entries in tasks/progress.md |
+| **Rework rate** | Count fix commits (fix(lint):, fix(test):, etc.) vs feature commits |
+
+### 4. Identify Patterns
+
+- **Recurring blocker**: Same type of issue across multiple gates?
+- **Estimation accuracy**: Did planned scope match actual scope? (cross-ref with `/sk:scope-check` if available)
+- **Gate friction**: Which gates required the most fix cycles?
+- **Previous retro follow-up**: Read previous `tasks/retro-*.md` files — were action items addressed?
+
+### 5. Generate Action Items
+
+Produce 3-5 concrete, actionable improvements:
+- Each action item must have: **what** to do, **why** it matters, **when** to apply it
+- Prioritize systemic fixes over one-off patches
+- Flag recurring unaddressed items from previous retros as process concerns
+
+### 6. Write Report
+
+Save to `tasks/retro-YYYY-MM-DD.md`:
+
+```markdown
+# Retrospective — [date] — [task name]
+
+## Metrics
+| Metric | Value |
+|--------|-------|
+| Planned tasks | N |
+| Completed | X / N (Y%) |
+| Commits | Z |
+| Time span | A days |
+| Files changed | B (+C/-D) |
+| Gate attempts | lint: 1, test: 2, security: 1, ... |
+| Blockers | K |
+| Rework rate | R% |
+
+## What Went Well
+- [data-backed observation]
+
+## What Didn't Go Well
+- [data-backed observation, with blocker/error references]
+
+## Patterns
+- [recurring theme from this or previous retros]
+
+## Action Items
+1. **[What]** — [Why] — Apply during: [When]
+2. ...
+
+## Previous Action Item Follow-Up
+- [Action from last retro] — [Addressed / Still open]
+```
+
+### 7. Summary
+
+Output to user:
+```
+Retrospective saved to tasks/retro-YYYY-MM-DD.md
+Completion: X/N tasks (Y%)  |  Velocity: Z commits/day  |  Blockers: K
+Top action: [most important action item]
+```
+
+## Model Routing
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | sonnet |
+| `balanced` | sonnet |
+| `budget` | haiku |

package/skills/sk:reverse-doc/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: sk:reverse-doc
+description: Generate architecture and design documentation from existing code by analyzing patterns and asking clarifying questions
+user_invocable: true
+allowed_tools: Read, Glob, Grep, Write, Agent
+---
+
+# Reverse Document
+
+Generate documentation from existing code — work backwards from implementation to create missing design or architecture docs.
+
+## When to Use
+
+- Onboarding to an existing codebase that lacks documentation
+- Formalizing a prototype into a documented design
+- Capturing the "why" behind existing code before refactoring
+- Creating architecture docs for a codebase you inherited
+
+## Arguments
+
+```
+/sk:reverse-doc <type> <path>
+```
+
+| Type | Output | Location |
+|------|--------|----------|
+| `architecture` | Architecture Decision Record | `docs/architecture/` |
+| `design` | Design document (GDD-style) | `docs/design/` |
+| `api` | API specification | `docs/api/` |
+
+If no type specified, infer from the path:
+- `src/core/`, `src/lib/`, `app/Services/` → architecture
+- `src/components/`, `resources/views/` → design
+- `routes/`, `app/Http/Controllers/` → api
+
+## Steps
+
+### Phase 1: Analyze
+
+Launch Explore agents to analyze the target path:
+
+1. **Structure agent**: Map the file tree, identify entry points, trace dependency chains
+2. **Patterns agent**: Identify design patterns, abstractions, conventions used
+3. **Data flow agent**: Trace data through the system — inputs, transformations, outputs
+
+Synthesize findings into:
+- **What it does** (mechanics, behavior)
+- **How it's built** (patterns, architecture, dependencies)
+- **What's unclear** (inconsistencies, undocumented decisions)
+
+### Phase 2: Clarify
+
+Ask the user 3-5 clarifying questions to distinguish intentional design from accidental implementation:
+
+- "Is [pattern X] intentional, or would you change it in a refactor?"
+- "What was the motivation for [architectural decision Y]?"
+- "Are [components A and B] coupled by design, or is that tech debt?"
+
+**Critical principle: Never assume intent. Always ask before documenting "why."**
+
+The distinction between "what the code does" and "what the developer intended" is the entire value of this skill. Do not skip this phase.
+
+### Phase 3: Draft
+
+Based on analysis + user answers, generate the document:
+
+**Architecture docs include:**
+- System overview and purpose
+- Component diagram (text-based)
+- Data flow description
+- Key design decisions with rationale (from user answers)
+- Dependencies and interfaces
+- Trade-offs and known limitations
+
+**Design docs include:**
+- Feature overview and user-facing behavior
+- Component breakdown
+- State management approach
+- Interaction patterns
+- Edge cases and error handling
+
+**API docs include:**
+- Endpoint inventory
+- Request/response schemas
+- Authentication requirements
+- Error codes and formats
+- Rate limits and constraints
+
+### Phase 4: Approve
+
+Present the draft to the user:
+- Show key sections
+- Highlight areas marked as "inferred" (not confirmed by user)
+- Ask for corrections or additions
+
+**Do not write the file until the user approves.**
+
+### Phase 5: Write
+
+Save the approved document to the appropriate location.
+
+Flag follow-up work:
+- Related areas that also need documentation
+- Inconsistencies discovered during analysis
+- Suggested refactoring based on documented architecture
+
+**Do not auto-execute follow-up work.** Present it as a list for the user to decide.
+
+## Model Routing
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | opus (inherit) |
+| `balanced` | sonnet |
+| `budget` | sonnet |

package/skills/sk:scope-check/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: sk:scope-check
+description: Compare current implementation against the plan to detect scope creep
+user_invocable: true
+allowed_tools: Read, Glob, Grep, Bash
+---
+
+# Scope Check
+
+Compare the current implementation against `tasks/todo.md` to detect scope creep and unplanned additions.
+
+## When to Use
+
+Run `/sk:scope-check` mid-implementation (during or after step 10) to verify you're building what was planned — no more, no less. Useful when implementation feels like it's growing beyond the original plan.
+
+## Steps
+
+### 1. Read the Plan
+
+- Read `tasks/todo.md` — extract all planned tasks (checkboxes)
+- Count total planned tasks, completed tasks, and remaining tasks
+- List planned files/areas from task descriptions
+
+### 2. Analyze Actual Changes
+
+- Run `git diff main..HEAD --stat` to get files changed, insertions, deletions
+- Run `git diff main..HEAD --name-only` to list all changed files
+- Count new files created vs. files modified
+- Identify files changed that are NOT mentioned in any todo.md task
+
+### 3. Compare Planned vs. Actual
+
+For each changed file, trace it back to a planned task:
+- **Planned**: File change is directly described in a todo.md checkbox
+- **Supporting**: File change is a reasonable dependency of a planned task (e.g., updating imports after moving a function)
+- **Unplanned**: File change has no clear connection to any planned task — this is scope creep
+
+### 4. Calculate Scope Bloat
+
+```
+Planned tasks:    N checkboxes in todo.md
+Actual changes:   M files changed
+Unplanned items:  U files with no matching task
+Scope bloat:      (U / M) * 100 = X%
+```
+
+### 5. Classify
+
+| Classification | Bloat % | Recommendation |
+|---------------|---------|----------------|
+| **On Track** | 0-10% | Proceeding as planned. Minor supporting changes are normal. |
+| **Minor Creep** | 10-25% | Some unplanned additions detected. Review if they're necessary. |
+| **Significant Creep** | 25-50% | Scope has grown substantially. Consider splitting into separate tasks. |
+| **Out of Control** | >50% | More unplanned work than planned. Stop and reassess with `/sk:change`. |
+
+### 6. Output Report
+
+```markdown
+## Scope Check Report — [date]
+
+**Plan**: [N] tasks in tasks/todo.md
+**Completed**: [X] / [N] tasks
+**Files changed**: [M] files (+[insertions] / -[deletions])
+**Unplanned changes**: [U] files
+
+### Classification: [On Track | Minor Creep | Significant Creep | Out of Control] ([X]%)
+
+### Planned Changes
+- [file] — task: [matching checkbox text]
+- ...
+
+### Supporting Changes
+- [file] — supports: [which planned task]
+- ...
+
+### Unplanned Changes
+- [file] — no matching task found
+- ...
+
+### Recommendation
+[Actionable advice based on classification]
+```
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | opus (inherit) |
+| `quality` | sonnet |
+| `balanced` | haiku |
+| `budget` | haiku |

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

@@ -305,6 +305,59 @@ Additionally report:
 - Tools installed vs already present
 - Config files created vs skipped
 
+### Hooks (in `.claude/hooks/`)
+
+Deployed from `templates/hooks/` to `.claude/hooks/` (made executable):
+
+- `session-start.sh` — runs on SessionStart, loads context
+- `session-stop.sh` — runs on Stop, persists session state
+- `pre-compact.sh` — runs on PreCompact, saves context before compaction
+- `validate-commit.sh` — PreToolUse hook for `git commit*`, validates commit messages
+- `validate-push.sh` — PreToolUse hook for `git push*`, confirms before pushing
+- `log-agent.sh` — SubagentStart hook, logs sub-agent launches
+
+### Agent Definitions (in `.claude/agents/`)
+
+Deployed from `templates/.claude/agents/` (create-if-missing):
+
+- `e2e-tester.md` — E2E testing agent definition
+- `linter.md` — Linting agent definition
+- `perf-auditor.md` — Performance auditing agent
+- `security-auditor.md` — Security auditing agent
+- `test-runner.md` — Test execution agent
+
+### Path-Scoped Rules (in `.claude/rules/`)
+
+Deployed from `templates/.claude/rules/` based on detected stack:
+
+| Rule file | Deployed when |
+|-----------|---------------|
+| `tests.md.template` | Always |
+| `frontend.md.template` | Always |
+| `api.md.template` | Always |
+| `laravel.md.template` | Laravel detected in framework |
+| `react.md.template` | React or Next.js detected in framework |
+
+### Settings Generation (`.claude/settings.json`)
+
+Rendered from `templates/.claude/settings.json.template`. Contains:
+- Statusline configuration (points to `.claude/statusline.sh`)
+- Permission allow/deny lists for safe Bash commands
+- Hook wiring for all 6 hooks above
+
+### Statusline Generation (`.claude/statusline.sh`)
+
+Copied from `templates/.claude/statusline.sh` (made executable). Displays:
+- Context window usage percentage
+- Current model
+- Current workflow step (from `tasks/workflow-status.md`)
+- Git branch
+- Current task name
+
+### Cached Detection
+
+Detection results are cached to `.shipkit/config.json` with a `detected_at` timestamp. On subsequent runs, if the cache is less than 7 days old, cached values are used instead of re-scanning. Pass `--force-detect` to bypass the cache and re-run detection from scratch.
+
 ## Templates (Source of Truth)
 
 All output files are rendered from templates in `templates/`: