@kennethsolomon/shipkit 3.6.0 → 3.8.0

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:review/SKILL.md

@@ -33,7 +33,7 @@ Use `git diff main..HEAD --name-only` to identify the changed files, then run si
 
 If simplify makes any changes:
 1. Verify the changes are correct
-2. Commit them with `/sk:smart-commit` before continuing the review
+2. Auto-commit them with message `fix(review): simplify pre-pass` before continuing the review. Do not ask the user.
 3. Note in the review report: "Simplify pre-pass: X files updated"
 
 If simplify makes no changes, proceed directly to step 1.
@@ -436,20 +436,28 @@ Format findings with severity levels and review dimensions:
 - Include a brief "What Looks Good" section (2-3 items) — acknowledge strong patterns so they're reinforced. This isn't cheerleading — it's calibrating signal.
 - If you genuinely find nothing wrong after all 7 dimensions, say so — but that's rare
 
-### 11. Next Steps
+### 11. Fix and Re-run
 
-After presenting the review:
+After presenting the review report, fix **all** findings regardless of severity (Critical, Warning, and Nitpick). Do not ask the user whether to fix nitpicks — fix everything.
 
-If there are **Critical** or **Warning** items:
-> "Review found issues that should be addressed. Fix them with `/sk:debug`, commit with `/sk:smart-commit`, then re-run `/sk:review` to verify."
+**For each finding:**
+- If the issue is in a file **within** the current branch diff (`git diff $BASE..HEAD --name-only`): fix it inline, include in the auto-commit
+- If the issue is in a file **outside** the current branch diff (pre-existing issue found via blast-radius): log it to `tasks/tech-debt.md` — do NOT fix it inline:
+  ```
+  ### [YYYY-MM-DD] Found during: sk:review
+  File: path/to/file.ext:line
+  Issue: description of the problem
+  Severity: critical | high | medium | low
+  ```
 
-If there are only **Nitpick** items (no Critical/Warning):
-> "Review complete — no critical issues found, but there are some nitpicks. Would you like to fix them now, or proceed to `/sk:finish-feature`?"
+After all in-scope fixes are applied: auto-commit with `fix(review): address review findings`. Do not ask the user. Re-run `/sk:review` from scratch.
 
-If the user wants to fix nitpicks, loop back to `/sk:debug` + `/sk:smart-commit` → `/sk:review`.
+Loop until the review is completely clean (0 findings across all severities for in-scope code).
 
-If the review is **completely clean**:
-> "Review complete — no issues found. Run `/sk:finish-feature` to finalize the branch and create a PR."
+When clean:
+> "Review complete — 0 findings. Run `/sk:finish-feature` to finalize the branch and create a PR."
+
+**Note:** Gates own their commits — the fix-commit-rerun loop is fully internal. No manual commit step needed after this gate.
 
 ### Fix & Retest Protocol
 
@@ -460,7 +468,7 @@ When applying a fix from this review, classify it before committing:
 **b. Logic change** (fix incorrect condition, add missing null check, change data flow, refactor algorithm, fix async bug) → trigger protocol:
 1. Update or add failing unit tests for the corrected behavior
 2. Re-run `/sk:test` — must pass at 100% coverage
-3. Commit (tests + fix together in one commit)
+3. Auto-commit tests + fix together with `fix(review): [description]`.
 4. Re-run `/sk:review` from scratch
 
 **Why:** Review catches logic bugs. Fixing a logic bug without updating tests leaves the test suite asserting on the old (wrong) behavior.

package/skills/sk:schema-migrate/SKILL.md

@@ -24,6 +24,28 @@ guidance. Auto-detects the ORM from project files — no configuration needed.
 
 ---
 
+## Phase 0: Auto-Detect Migration Changes
+
+Before doing anything else, check whether the current branch has any migration-related changes:
+
+```bash
+git diff main..HEAD --name-only
+```
+
+Scan the output for migration-related files:
+- Files under `migrations/`, `database/migrations/`, `prisma/migrations/`, `alembic/versions/`, `db/migrate/`
+- Schema definition files: `prisma/schema.prisma`, `drizzle.config.ts`, `drizzle.config.js`, `alembic.ini`
+- Any `*.sql` files in migration-related directories
+
+**If NO migration-related files are found in the diff:**
+> auto-skip: No migration changes detected in this branch — skipping `/sk:schema-migrate`.
+
+Exit cleanly. Do not ask the user. Do not proceed to Phase 1.
+
+**If migration-related files ARE found:** proceed to Phase 1 (ORM Detection) below.
+
+---
+
 ## Phase 1: ORM Detection
 
 ### Step 1 — Read in Parallel

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/`:

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

@@ -7,12 +7,18 @@ import hashlib
 import json
 import os
 import re
+import shutil
+import stat
 import sys
 from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Dict, Iterable, List, Optional, Tuple
 
 
+CACHE_MAX_AGE_DAYS = 7
+
+
 GENERATED_MARKER = "<!-- Generated by /setup-claude -->"
 TEMPLATE_HASH_MARKER = "<!-- Template Hash: "
 TEMPLATE_HASH_END = " -->"
@@ -59,6 +65,46 @@ def _any_dep_prefix(pkg: dict, prefix: str) -> bool:
     return any(k.startswith(prefix) for k in deps.keys())
 
 
+def _cache_path(repo_root: Path) -> Path:
+    return repo_root / ".shipkit" / "config.json"
+
+
+def _read_cached_detection(repo_root: Path) -> Optional[Detection]:
+    """Return cached Detection if cache exists and is less than CACHE_MAX_AGE_DAYS old."""
+    cache = _cache_path(repo_root)
+    data = _read_json(cache)
+    if data is None:
+        return None
+    detected_at = data.get("detected_at")
+    if not detected_at:
+        return None
+    try:
+        ts = datetime.fromisoformat(detected_at)
+        age = datetime.now(timezone.utc) - ts
+        if age.days >= CACHE_MAX_AGE_DAYS:
+            return None
+    except (ValueError, TypeError):
+        return None
+    det = data.get("detection")
+    if not det:
+        return None
+    try:
+        return Detection(**det)
+    except (TypeError, KeyError):
+        return None
+
+
+def _write_cached_detection(repo_root: Path, detection: Detection) -> None:
+    """Persist detection results to .shipkit/config.json with a detected_at timestamp."""
+    cache = _cache_path(repo_root)
+    cache.parent.mkdir(parents=True, exist_ok=True)
+    payload = {
+        "detected_at": datetime.now(timezone.utc).isoformat(),
+        "detection": asdict(detection),
+    }
+    cache.write_text(json.dumps(payload, indent=2, sort_keys=True), encoding="utf-8")
+
+
 def detect(repo_root: Path) -> Detection:
     package_json = _read_json(repo_root / "package.json") or {}
     scripts = (package_json.get("scripts") or {}) if isinstance(package_json, dict) else {}
@@ -272,6 +318,103 @@ def _plan_file_if_generated(dest: Path, content: str) -> str:
     return "skipped" if existing == content else "updated"
 
 
+def _collect_results(
+    results,
+    repo_root: Path,
+    created: List[str],
+    updated: List[str],
+    skipped: List[str],
+) -> None:
+    """Categorize deployment results into created/updated/skipped lists."""
+    for action, p in results:
+        rel = str(p.relative_to(repo_root))
+        if action == "created":
+            created.append(rel)
+        elif action == "updated":
+            updated.append(rel)
+        else:
+            skipped.append(rel)
+
+
+def _make_executable(path: Path) -> None:
+    """Add owner-execute permission to a file."""
+    st = path.stat()
+    path.chmod(st.st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+
+def _deploy_directory(
+    src_dir: Path,
+    dest_dir: Path,
+    *,
+    dry_run: bool,
+    executable: bool = False,
+    filter_fn=None,
+) -> List[tuple]:
+    """Copy files from src_dir to dest_dir. Returns list of (action, relative_path)."""
+    results: List[tuple] = []
+    if not src_dir.exists():
+        return results
+    for src_file in sorted(src_dir.iterdir()):
+        if not src_file.is_file():
+            continue
+        if filter_fn and not filter_fn(src_file.name):
+            continue
+        dest_file = dest_dir / src_file.name
+        if dest_file.exists():
+            results.append(("skipped", dest_file))
+        elif dry_run:
+            results.append(("created", dest_file))
+        else:
+            dest_dir.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(src_file, dest_file)
+            if executable:
+                _make_executable(dest_file)
+            results.append(("created", dest_file))
+    return results
+
+
+def _deploy_rendered_file(
+    template_path: Path,
+    dest: Path,
+    detection: Detection,
+    *,
+    dry_run: bool,
+    executable: bool = False,
+) -> tuple:
+    """Render a template and write to dest. Returns (action, path)."""
+    if not template_path.exists():
+        return ("skipped", dest)
+    template_text = template_path.read_text(encoding="utf-8")
+    rendered = render_template(template_text, detection)
+    if dest.exists():
+        return ("skipped", dest)
+    if dry_run:
+        return ("created", dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    dest.write_text(rendered, encoding="utf-8")
+    if executable:
+        _make_executable(dest)
+    return ("created", dest)
+
+
+def _rules_filter(detection: Detection):
+    """Return a filter function that selects rules relevant to the detected stack."""
+    always = {"tests.md.template", "frontend.md.template", "api.md.template"}
+
+    def _filter(filename: str) -> bool:
+        if filename in always:
+            return True
+        if filename == "laravel.md.template" and "Laravel" in detection.framework:
+            return True
+        if filename == "react.md.template" and (
+            "React" in detection.framework or detection.framework == "Next.js (App Router)"
+        ):
+            return True
+        return False
+
+    return _filter
+
+
 def apply(
     repo_root: Path,
     skill_root: Path,
@@ -370,12 +513,54 @@ def apply(
         else:
             action, p = ("skipped", dest_path)
 
-        if action == "created":
-            created.append(str(p.relative_to(repo_root)))
-        elif action == "updated":
-            updated.append(str(p.relative_to(repo_root)))
+        _collect_results([(action, p)], repo_root, created, updated, skipped)
+
+    # --- Deploy hooks ---
+    hooks_src = skill_root / "templates" / "hooks"
+    hooks_dest = repo_root / ".claude" / "hooks"
+    _collect_results(
+        _deploy_directory(hooks_src, hooks_dest, dry_run=dry_run, executable=True),
+        repo_root, created, updated, skipped,
+    )
+
+    # --- Deploy agents ---
+    agents_src = skill_root / "templates" / ".claude" / "agents"
+    agents_dest = repo_root / ".claude" / "agents"
+    _collect_results(
+        _deploy_directory(agents_src, agents_dest, dry_run=dry_run),
+        repo_root, created, updated, skipped,
+    )
+
+    # --- Deploy rules (stack-filtered) ---
+    rules_src = skill_root / "templates" / ".claude" / "rules"
+    rules_dest = repo_root / ".claude" / "rules"
+    _collect_results(
+        _deploy_directory(rules_src, rules_dest, dry_run=dry_run, filter_fn=_rules_filter(detection)),
+        repo_root, created, updated, skipped,
+    )
+
+    # --- Deploy settings.json ---
+    settings_template = skill_root / "templates" / ".claude" / "settings.json.template"
+    settings_dest = repo_root / ".claude" / "settings.json"
+    _collect_results(
+        [_deploy_rendered_file(settings_template, settings_dest, detection, dry_run=dry_run)],
+        repo_root, created, updated, skipped,
+    )
+
+    # --- Deploy statusline.sh ---
+    statusline_src = skill_root / "templates" / ".claude" / "statusline.sh"
+    statusline_dest = repo_root / ".claude" / "statusline.sh"
+    if statusline_src.exists():
+        if statusline_dest.exists():
+            action_sl = "skipped"
+        elif dry_run:
+            action_sl = "created"
         else:
-            skipped.append(str(p.relative_to(repo_root)))
+            statusline_dest.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(statusline_src, statusline_dest)
+            _make_executable(statusline_dest)
+            action_sl = "created"
+        _collect_results([(action_sl, statusline_dest)], repo_root, created, updated, skipped)
 
     if dry_run:
         print("setup-claude dry-run complete (no files written)")
@@ -415,6 +600,11 @@ def main(argv: List[str]) -> int:
         action="store_true",
         help="Print detected values as JSON and exit unless combined with --dry-run.",
     )
+    parser.add_argument(
+        "--force-detect",
+        action="store_true",
+        help="Bypass cached detection and re-run stack detection from scratch.",
+    )
     args = parser.parse_args(argv[1:])
 
     repo_root = Path(args.repo_root).resolve()
@@ -424,7 +614,17 @@ def main(argv: List[str]) -> int:
         print(f"Repo root not found: {repo_root}", file=sys.stderr)
         return 2
 
-    detection = detect(repo_root)
+    # Use cached detection unless --force-detect is set
+    detection = None
+    if not args.force_detect:
+        detection = _read_cached_detection(repo_root)
+        if detection:
+            print("Using cached detection (< 7 days old). Pass --force-detect to re-run.")
+    if detection is None:
+        detection = detect(repo_root)
+        if not args.dry_run:
+            _write_cached_detection(repo_root, detection)
+
     if args.print_detection:
         print(json.dumps(asdict(detection), indent=2, sort_keys=True))
         if not args.dry_run:

package/skills/sk:setup-claude/templates/.claude/agents/e2e-tester.md

@@ -0,0 +1,46 @@
+---
+name: e2e-tester
+model: sonnet
+description: Run E2E behavioral verification using Playwright CLI or agent-browser. Fix failures and auto-commit.
+allowed_tools: Bash, Read, Edit, Write, Glob, Grep
+---
+
+# E2E Tester Agent
+
+You are a specialized E2E testing agent. Your job is to verify the complete implementation works end-to-end from a user's perspective.
+
+## Behavior
+
+1. **Detect E2E framework**:
+   - If `playwright.config.ts` exists -> use Playwright CLI
+   - If `cypress.config.ts` exists -> use Cypress
+   - If `tests/verify-workflow.sh` exists -> use bash test suite
+   - Otherwise -> report no E2E framework detected
+
+2. **Run E2E tests**:
+   - Playwright: `npx playwright test --reporter=list`
+   - Cypress: `npx cypress run`
+   - Bash: `bash tests/verify-workflow.sh`
+
+3. **If tests fail**:
+   - Analyze failure output and screenshots (if Playwright)
+   - Determine if failure is in test or implementation
+   - Fix the root cause
+   - Stage: `git add <files>`
+   - auto-commit: `fix(e2e): resolve failing E2E scenarios`
+   - Re-run from scratch
+   - Loop until all pass
+
+4. **Pre-existing failures** (tests that were already failing before this branch):
+   - Log to `tasks/tech-debt.md`:
+     ```
+     ### [YYYY-MM-DD] Found during: sk:e2e
+     File: path/to/test.ext
+     Issue: Pre-existing E2E failure — [description]
+     Severity: medium
+     ```
+
+5. **Report** when passing:
+   ```
+   E2E: [N] scenarios passed, 0 failed (attempt [M])
+   ```