@kennethsolomon/shipkit 3.10.2 → 3.11.0

package/skills/sk:health/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: sk:health
+description: "Run harness self-audit and produce a health scorecard."
+---
+
+# /sk:health — Harness Self-Audit Scorecard
+
+Deterministic scoring of your ShipKit setup across 7 categories. Produces a reproducible scorecard that identifies gaps and recommends improvements.
+
+## Usage
+
+```
+/sk:health              # full scorecard
+/sk:health --category <name>  # single category deep-dive
+```
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | haiku |
+| `quality` | haiku |
+| `balanced` | haiku |
+| `budget` | haiku |
+
+> File checks + arithmetic — haiku is sufficient.
+
+## Scoring Categories
+
+Each category scores 0-10. Maximum total: 70.
+
+### 1. Tool Coverage (0-10)
+
+Check for presence and completeness of:
+
+| Check | Points |
+|-------|--------|
+| `.claude/hooks/` exists with 6+ hooks | +2 |
+| `.claude/agents/` exists with 4+ agents | +2 |
+| `.claude/rules/` exists with 1+ rules | +1 |
+| `commands/sk/` or `.claude/commands/sk/` has 10+ commands | +2 |
+| MCP servers configured | +1 |
+| Statusline configured in settings.json | +1 |
+| Permissions deny list has 3+ entries | +1 |
+
+### 2. Context Efficiency (0-10)
+
+| Check | Points |
+|-------|--------|
+| CLAUDE.md exists and is <250 lines | +2 (>250: +1, >400: 0) |
+| No duplicate instructions across CLAUDE.md and skills | +2 |
+| MCP tools total <40 | +2 (40-60: +1, >60: 0) |
+| Skills total <60 | +2 (>60: +1, >80: 0) |
+| Agent descriptions all <200 lines | +2 |
+
+### 3. Quality Gates (0-10)
+
+| Check | Points |
+|-------|--------|
+| Lint configured (package.json scripts or Makefile) | +2 |
+| Test runner configured | +2 |
+| Security check available (npm audit, composer audit, etc.) | +2 |
+| E2E test config exists (playwright.config, cypress.config) | +2 |
+| Code review skill available | +2 |
+
+### 4. Memory Persistence (0-10)
+
+| Check | Points |
+|-------|--------|
+| `tasks/findings.md` exists and has content | +2 |
+| `tasks/lessons.md` exists and has content | +2 |
+| `tasks/progress.md` exists | +1 |
+| `tasks/tech-debt.md` exists | +1 |
+| `tasks/cross-platform.md` exists | +1 |
+| Session hooks active (session-start.sh, session-stop.sh) | +2 |
+| `.claude/sessions/` directory exists | +1 |
+
+### 5. Eval Coverage (0-10)
+
+| Check | Points |
+|-------|--------|
+| Test directory exists (`tests/`, `test/`, `spec/`, `__tests__/`) | +2 |
+| Test assertions exist (grep for assert/expect/test/it/describe) | +2 |
+| Coverage config exists (jest.config coverage, phpunit coverage) | +2 |
+| `.claude/evals/` directory exists with eval definitions | +2 |
+| CI/CD runs tests (`.github/workflows/` with test step) | +2 |
+
+### 6. Security Guardrails (0-10)
+
+| Check | Points |
+|-------|--------|
+| validate-commit hook exists | +2 |
+| validate-push hook exists | +2 |
+| config-protection hook exists | +2 |
+| Deny rules in settings.json (3+ patterns) | +2 |
+| safety-guard hook exists | +2 |
+
+### 7. Cost Efficiency (0-10)
+
+| Check | Points |
+|-------|--------|
+| Model routing configured (`.shipkit/config.json` exists) | +3 |
+| Compact suggestions active (suggest-compact hook) | +2 |
+| Cost tracker active (cost-tracker hook) | +2 |
+| Context budget recently audited (`/sk:context-budget` run) | +3 |
+
+## Output Format
+
+```
+=== ShipKit Health Scorecard ===
+
+  Tool Coverage:        8/10  ||||||||..
+  Context Efficiency:   7/10  |||||||...
+  Quality Gates:       10/10  ||||||||||
+  Memory Persistence:   6/10  ||||||....
+  Eval Coverage:        4/10  ||||......
+  Security Guardrails:  8/10  ||||||||..
+  Cost Efficiency:      5/10  |||||.....
+  ─────────────────────────────────
+  Total:               48/70  (69%)
+
+  Rating: GOOD
+
+Findings:
+  [MISSING] No .claude/evals/ directory — no formal eval definitions
+  [MISSING] No CI/CD test step detected
+  [MISSING] Context budget never audited
+  [WEAK]    Only 4 hooks installed (recommended: 8+)
+
+Top 3 Actions:
+  1. Run /sk:eval define to create eval definitions (+4 points)
+  2. Add CI/CD test workflow (+2 points)
+  3. Run /sk:context-budget to audit token usage (+3 points)
+```
+
+### Rating Scale
+
+| Score | Rating |
+|-------|--------|
+| 60-70 | EXCELLENT |
+| 45-59 | GOOD |
+| 30-44 | FAIR |
+| 15-29 | NEEDS WORK |
+| 0-14 | CRITICAL |

package/skills/sk:learn/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: sk:learn
+description: "Extract reusable patterns from the current session into learned instincts."
+---
+
+# /sk:learn — Extract Reusable Patterns
+
+Analyzes the current session for extractable patterns and saves them as learned instincts. Patterns evolve from tentative observations into strong conventions over time.
+
+## Usage
+
+```
+/sk:learn                  # analyze current session
+/sk:learn --list           # show all learned patterns
+/sk:learn --promote <id>   # promote project pattern to global
+/sk:learn --export         # export patterns as shareable file
+```
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | haiku |
+| `quality` | haiku |
+| `balanced` | haiku |
+| `budget` | haiku |
+
+> Pattern detection is lightweight keyword matching — haiku is sufficient.
+
+## How It Works
+
+### Phase 1: Session Analysis
+
+Scan the current conversation for extractable patterns:
+
+1. **Error resolutions** — problems encountered and how they were solved
+2. **Debugging techniques** — investigation steps that led to root causes
+3. **Workarounds** — non-obvious solutions to framework/tool limitations
+4. **Project conventions** — naming patterns, file organization, code style decisions
+5. **Tool usage patterns** — effective tool combinations and sequences
+
+Filter out trivial items:
+- Typo fixes, syntax errors, simple formatting
+- One-off configuration changes
+- Standard framework usage (documented in official docs)
+
+### Phase 2: Pattern Extraction
+
+For each candidate pattern, extract:
+
+```markdown
+---
+name: [descriptive-slug]
+type: [error-resolution | debugging | workaround | convention | tool-usage]
+confidence: [0.3 | 0.5 | 0.7 | 0.9]
+scope: [project | global]
+created: [YYYY-MM-DD]
+seen_count: 1
+---
+
+## Problem
+[What triggered this pattern]
+
+## Solution
+[What resolved it — specific steps]
+
+## Example
+[Concrete code or command example]
+
+## When to Apply
+[Conditions that indicate this pattern is relevant]
+```
+
+### Phase 3: Confidence Scoring
+
+| Score | Label | Meaning |
+|-------|-------|---------|
+| 0.3 | tentative | Seen once, might be coincidence |
+| 0.5 | emerging | Seen in similar contexts, likely a real pattern |
+| 0.7 | strong | Proven effective multiple times |
+| 0.9 | near-certain | Battle-tested, consistently reliable |
+
+New patterns start at 0.3. Confidence increases when:
+- Same pattern seen again in a different session (+0.2)
+- User explicitly confirms the pattern (+0.2)
+- Pattern seen in a different project (+0.1, also promotes to global)
+
+### Phase 4: Storage
+
+- **Project patterns**: `~/.claude/skills/learned/[project-name]/[pattern-name].md`
+- **Global patterns**: `~/.claude/skills/learned/global/[pattern-name].md`
+
+### Phase 5: User Confirmation
+
+Present extracted patterns and ask for confirmation before saving:
+
+```
+Extracted 3 patterns from this session:
+
+1. [error-resolution] "laravel-queue-retry-after" (0.3 tentative)
+   Problem: Queue jobs silently failing after Redis timeout
+   Solution: Set retry_after in queue config > job timeout
+
+2. [convention] "api-resource-wrapping" (0.3 tentative)
+   Problem: Inconsistent API response format
+   Solution: Always wrap in ApiResource with data key
+
+3. [tool-usage] "parallel-explore-before-implement" (0.3 tentative)
+   Problem: Missing context leads to wrong implementation
+   Solution: Launch 3 Explore agents before writing code
+
+Save patterns? (all / 1,3 / none)
+```
+
+## Promotion: Project to Global
+
+A pattern is auto-promoted to global when:
+- Same pattern (by name or content similarity) appears in 2+ projects
+- Confidence >= 0.7 in both projects
+- User hasn't marked it as project-specific
+
+Manual promotion: `/sk:learn --promote <pattern-id>`
+
+## Export / Import
+
+Export all patterns for sharing:
+```
+/sk:learn --export > my-patterns.json
+```
+
+Import from a colleague:
+```
+/sk:learn --import colleague-patterns.json
+```
+
+Imported patterns start at 0.3 confidence regardless of source confidence.

package/skills/sk:resume-session/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: sk:resume-session
+description: "Resume a previously saved session with full context restoration."
+---
+
+# /sk:resume-session — Restore Session Context
+
+Lists available saved sessions and restores the selected one, injecting the saved context into the current conversation.
+
+## Usage
+
+```
+/sk:resume-session             # list sessions, pick one
+/sk:resume-session --latest    # auto-pick most recent session
+/sk:resume-session --name "auth-flow"  # resume specific named session
+```
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | haiku |
+| `quality` | haiku |
+| `balanced` | haiku |
+| `budget` | haiku |
+
+> Deserialization is lightweight — haiku is sufficient.
+
+## How It Works
+
+### Step 1: List Available Sessions
+
+Read `.claude/sessions/` and display:
+
+```
+Available sessions:
+
+  1. [2026-03-25] feat/auth-flow — "auth-flow" (3 hours ago)
+     Task: Implement OAuth2 login with Google
+     Step: 5 (Write Tests + Implement)
+
+  2. [2026-03-24] feat/api-redesign — "api-v2" (1 day ago)
+     Task: Redesign REST API to v2 spec
+     Step: 7 (Gates)
+
+  3. [2026-03-23] fix/queue-timeout — auto-save (2 days ago)
+     Task: Fix Redis queue timeout in production
+     Step: 4 (Branch)
+
+Select session (1-3) or 'q' to cancel:
+```
+
+### Step 2: Load Session
+
+Read the selected session file and inject context:
+
+1. **Verify branch** — check if the session's branch still exists
+   - If yes: suggest `git checkout [branch]` if not already on it
+   - If no: warn that the branch was deleted, proceed with context anyway
+2. **Load task state** — read `tasks/todo.md` and cross-reference with saved state
+3. **Load progress** — read `tasks/progress.md` for the full history
+4. **Restore context** — output the session's findings, open questions, and next steps
+
+### Step 3: Report
+
+```
+Resumed session from 2026-03-25 on branch feat/auth-flow
+
+  Task: Implement OAuth2 login with Google
+  Step: 5 (Write Tests + Implement)
+  Commits since save: 2
+
+  Open Questions:
+    - Should we support refresh token rotation?
+    - Which scopes are required for profile access?
+
+  Next Steps:
+    - Write integration test for token exchange
+    - Implement callback controller
+```
+
+### Step 4: Continue
+
+The workflow continues from wherever it left off. The session file provides enough context to avoid re-reading the entire codebase.
+
+## Session Cleanup
+
+Sessions older than 30 days are candidates for cleanup. Run manually:
+```bash
+find .claude/sessions/ -name "*.md" -mtime +30 -delete
+```
+
+Future: add `--cleanup` flag to auto-remove old sessions.

package/skills/sk:safety-guard/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: sk:safety-guard
+description: "Protect against destructive operations with careful, freeze, and guard modes."
+---
+
+# /sk:safety-guard — Destructive Operation Protection
+
+Three modes of protection that prevent accidental destructive operations and constrain file edits to specific directories.
+
+## Usage
+
+```
+/sk:safety-guard careful              # intercept destructive commands
+/sk:safety-guard freeze --dir src/    # lock edits to src/ only
+/sk:safety-guard guard --dir src/     # both careful + freeze
+/sk:safety-guard off                  # disable all guards
+/sk:safety-guard status               # show current mode
+```
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | haiku |
+| `quality` | haiku |
+| `balanced` | haiku |
+| `budget` | haiku |
+
+> Config read/write — haiku is sufficient.
+
+## Modes
+
+### Careful Mode
+
+Intercepts destructive commands before execution:
+
+| Command Pattern | Risk |
+|----------------|------|
+| `rm -rf`, `rm -fr` | File deletion |
+| `git push --force`, `git push -f` | History rewrite |
+| `git reset --hard` | Uncommitted changes lost |
+| `git clean -f` | Untracked files deleted |
+| `DROP TABLE`, `DROP DATABASE` | Data loss |
+| `chmod 777`, `chmod -R 777` | Security vulnerability |
+| `--no-verify` | Hook bypass |
+
+When a destructive command is detected:
+```
+BLOCKED by safety-guard (careful mode): destructive command detected.
+  Command: rm -rf /tmp/build
+  Pattern: rm -rf
+  Disable: /sk:safety-guard off
+```
+
+### Freeze Mode
+
+Locks file edits (Edit/Write tools) to a specific directory tree:
+
+```
+/sk:safety-guard freeze --dir src/api/
+```
+
+After activation:
+- Edit/Write to `src/api/**` → allowed
+- Edit/Write to `src/models/**` → **BLOCKED**
+- Edit/Write to `tests/**` → **BLOCKED**
+- Bash commands → not restricted (use careful mode for that)
+
+When a write outside the frozen directory is detected:
+```
+BLOCKED by safety-guard (freeze mode): write outside frozen directory.
+  File: tests/api/auth.test.ts
+  Allowed: src/api/
+  Disable: /sk:safety-guard off
+```
+
+### Guard Mode
+
+Combines careful + freeze. Both protections active simultaneously.
+
+### Off
+
+Disables all guards. Removes `.claude/safety-guard.json`.
+
+## Implementation
+
+### Configuration File
+
+Safety guard state is stored in `.claude/safety-guard.json`:
+
+```json
+{
+  "mode": "guard",
+  "freeze_dir": "src/api/",
+  "activated_at": "2026-03-25T10:30:00Z",
+  "activated_by": "user"
+}
+```
+
+### Hook Integration
+
+The `safety-guard.sh` hook (deployed to `.claude/hooks/`) reads this config file on every PreToolUse event for Bash/Edit/Write tools. If no config file exists, the hook exits immediately (no overhead).
+
+## Steps
+
+When invoked:
+
+1. Parse the mode argument (`careful` | `freeze` | `guard` | `off` | `status`)
+2. For freeze/guard: require `--dir` argument
+3. Write config to `.claude/safety-guard.json`
+4. Confirm activation:
+   ```
+   Safety guard activated: guard mode
+   Freeze directory: src/api/
+   Destructive commands: blocked
+   Disable: /sk:safety-guard off
+   ```
+
+For `status`:
+```
+Safety guard: guard mode (active since 2026-03-25 10:30)
+  Freeze directory: src/api/
+  Blocked actions: 3 (2 destructive commands, 1 out-of-scope write)
+  Log: .claude/safety-guard.log
+```
+
+## Best Practices
+
+- Use **freeze mode** during `/sk:autopilot` to prevent scope creep in file edits
+- Use **careful mode** as a default for new team members
+- Use **guard mode** for production hotfixes — maximum protection
+- Always disable after the focused task is complete

package/skills/sk:save-session/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: sk:save-session
+description: "Save current session state for cross-session continuity."
+---
+
+# /sk:save-session — Persist Session State
+
+Saves the current session state to `.claude/sessions/` so you can resume work in a future conversation. Essential for EPIC-scope tasks that span multiple sessions.
+
+## Usage
+
+```
+/sk:save-session                    # save with auto-generated name
+/sk:save-session --name "auth-flow" # save with custom name
+```
+
+## Model Routing
+
+Read `.shipkit/config.json` from the project root if it exists.
+
+| Profile | Model |
+|---------|-------|
+| `full-sail` | haiku |
+| `quality` | haiku |
+| `balanced` | haiku |
+| `budget` | haiku |
+
+> Serialization is lightweight — haiku is sufficient.
+
+## What Gets Saved
+
+The session file captures:
+
+```markdown
+---
+saved: [YYYY-MM-DDTHH:MM:SSZ]
+branch: [current git branch]
+task: [current task title from tasks/todo.md]
+step: [current workflow step number]
+---
+
+## Active Task
+[Current task description from tasks/todo.md — first unchecked item]
+
+## Branch State
+- Branch: [name]
+- Commits since main: [count]
+- Uncommitted changes: [list of modified files]
+
+## Progress Summary
+[Last 10 lines from tasks/progress.md]
+
+## Key Findings This Session
+[Any entries added to tasks/findings.md during this session]
+
+## Open Questions
+[Questions that were raised but not resolved]
+
+## Next Steps
+[What should be done when resuming — derived from todo.md + progress]
+
+## Context Notes
+[Any important context that would be lost on session end]
+```
+
+## Storage
+
+- **Path**: `.claude/sessions/[YYYY-MM-DD]-[branch]-[name].md`
+- **Example**: `.claude/sessions/2026-03-25-feat-auth-flow-auth-flow.md`
+- **Gitignore**: Add `.claude/sessions/` to `.gitignore` (session state is personal, not shared)
+
+## Steps
+
+1. Read current git state (branch, uncommitted changes, recent commits)
+2. Read `tasks/todo.md` — extract current task and step
+3. Read `tasks/progress.md` — extract recent entries
+4. Read `tasks/findings.md` — extract entries from today
+5. Ask user: "Any open questions or context to preserve?" (optional)
+6. Write session file to `.claude/sessions/`
+7. Confirm save with file path
+
+## Auto-Save via Hook
+
+The `session-stop.sh` hook automatically saves a minimal session snapshot on every session end. The `/sk:save-session` command creates a richer, more detailed snapshot with user input.

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

@@ -102,6 +102,28 @@ Never overwrite `tasks/lessons.md` — always append.
 - `.claude/docs/changelog-guide.md`
 - `.claude/docs/arch-changelog-guide.md`
 
+## Phase 0: Reconnaissance (first setup only)
+
+On **first-time setup** (no existing `CLAUDE.md` or `tasks/findings.md`), run a reconnaissance pass before stack detection:
+
+1. **Directory scan** — list top 2 levels of the project tree (excluding node_modules, vendor, .git, dist, build)
+2. **Entry point detection** — find main.*, index.*, app.*, server.*, manage.py, artisan, Makefile
+3. **Architecture classification**:
+   - Monorepo: multiple package.json/go.mod files, `packages/` or `apps/` directory
+   - Monolith: single manifest, `src/` or `app/` directory
+   - Microservices: `services/` directory with separate manifests
+4. **Data flow trace** — from entry point, identify: request handling → validation → business logic → data persistence
+5. **Output** — append architecture summary to `tasks/findings.md`:
+   ```
+   ## Reconnaissance (auto-generated by /sk:setup-claude)
+   - Architecture: [monolith/monorepo/microservices]
+   - Entry points: [list]
+   - Key directories: [list with purposes]
+   - Data flow: [request → ... → response]
+   ```
+
+Skip this phase on re-runs (when `tasks/findings.md` already contains "Reconnaissance").
+
 ## Generation Inputs
 
 This skill detects:
@@ -309,7 +331,7 @@ Additionally report:
 
 ### Hooks (in `.claude/hooks/`)
 
-Deployed from `templates/hooks/` to `.claude/hooks/` (made executable):
+**Core hooks** — always 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
@@ -318,6 +340,21 @@ Deployed from `templates/hooks/` to `.claude/hooks/` (made executable):
 - `validate-push.sh` — PreToolUse hook for `git push*`, confirms before pushing
 - `log-agent.sh` — SubagentStart hook, logs sub-agent launches
 
+**Enhanced hooks** — deployed only when user opts in. After deploying core hooks, prompt:
+
+> "Install enhanced hooks? These add config protection, auto-formatting, debug statement warnings, compact suggestions, and cost tracking. [y/n]"
+
+If yes, deploy these additional hooks:
+
+- `config-protection.sh` — PreToolUse hook for Edit/Write, blocks linter/formatter config modifications
+- `post-edit-format.sh` — PostToolUse hook for Edit, auto-formats with project's formatter
+- `console-log-warning.sh` — Stop hook, warns about debug statements in modified files
+- `cost-tracker.sh` — Stop hook (async), logs session metadata to `.claude/sessions/cost-log.jsonl`
+- `suggest-compact.sh` — PreToolUse hook, suggests `/compact` after 50+ tool calls
+- `safety-guard.sh` — PreToolUse hook for Bash/Edit/Write, reads `.claude/safety-guard.json` for protection rules
+
+If no, skip enhanced hooks — core hooks are always installed.
+
 ### Agent Definitions (in `.claude/agents/`)
 
 Deployed from `templates/.claude/agents/` (create-if-missing):
@@ -345,7 +382,7 @@ Deployed from `templates/.claude/rules/` based on detected stack:
 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
+- Hook wiring for all hooks (core 6 + enhanced 6 if opted in)
 
 ### Statusline Generation (`.claude/statusline.sh`)