@kennethsolomon/shipkit 1.0.0

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

@@ -0,0 +1,365 @@
+---
+name: sk:setup-claude
+description: "Bootstrap/repair Claude Code project scaffolding (.claude docs/commands + tasks planning files) with an enforced workflow cadence."
+---
+
+# /sk:setup-claude
+
+Bootstrap or repair Claude Code infrastructure on any project in a safe, idempotent way.
+
+## Workflow Contract (What This Enables)
+
+After bootstrapping a project, the recommended workflow becomes:
+
+1. `/sk:setup-claude` — ensure scaffolding exists
+2. `/sk:brainstorm` — clarify design (no coding yet)
+3. `/sk:write-plan` — write a decision-complete plan into `tasks/todo.md`
+4. `/sk:execute-plan` — implement in small batches while logging progress
+5. `/sk:security-check` — audit changed files for vulnerabilities and production quality
+6. `/sk:review` — self-review (report-only). Loop `/sk:debug` + `/sk:smart-commit` until clean
+7. `/sk:finish-feature` — finalize branch (changelog, arch log auto-committed, security gate, create PR)
+
+## What Gets Bootstrapped In The Target Repo
+
+### Planning / Memory Files (in `tasks/`)
+- `tasks/todo.md` — plan + checkboxes + results
+- `tasks/findings.md` — discoveries + decisions
+- `tasks/progress.md` — chronological work log + test results
+- `tasks/lessons.md` — durable “don’t repeat mistakes” log (**never overwrite**)
+- `tasks/security-findings.md` — security audit results from `/sk:security-check` (**never overwrite**)
+
+### Project Commands (in `.claude/commands/`)
+- `brainstorm.md` — invokes the global `brainstorming` skill
+- `re-setup.md` — re-runs the setup script for this repo (refresh generated files)
+- `write-plan.md` — forces a decision-complete plan (writes to `tasks/todo.md`)
+- `execute-plan.md` — executes the plan in batches; logs to `tasks/progress.md`
+- `plan.md` — creates/refreshes planning files and starts planning
+- `status.md` — prints a compact progress summary
+- `finish-feature.md` — branch finalization checklist (stack-aware)
+- `features.md` — sync `docs/sk:features/` specs with current codebase; creates the spec system from scratch if it doesn't exist
+- `security-check.md` — audit changed files (or full project with `--all`) for security best practices, OWASP Top 10, and production-grade quality
+
+### Project Docs (in `.claude/docs/`)
+- `changelog-guide.md`
+- `arch-changelog-guide.md`
+
+### Optional Root Files
+- `CLAUDE.md`
+- `CHANGELOG.md` (create if missing; **never overwrite**)
+
+## Critical Behavior Rules
+
+### Read-before-decide
+Before major decisions or after many tool calls, re-read `tasks/todo.md` to refresh the goal and constraints.
+
+### Log errors with attempts (3-strike protocol)
+When anything fails, log it immediately (error + attempt # + resolution). If the same approach fails twice, change approach. After 3 failures, stop and ask the user with what you tried.
+
+### Always write findings/progress to disk
+If you discover anything important (stack details, key paths, constraints, failures), write it into `tasks/findings.md` or `tasks/progress.md` before moving on.
+
+### Lessons Capture (lessons.md)
+
+`tasks/lessons.md` is a permanent log of corrections. Two triggers:
+
+**Explicit** — user says any of these phrases:
+- `lesson:` / `remember:` / `don't do this again:` / `add to lessons`
+→ Immediately append to `tasks/lessons.md` without asking.
+
+**Implicit** — detect correction language in user messages:
+- Keywords: "no", "don't", "instead", "wrong", "not like that", "stop doing"
+→ Ask: *"Should I add this to lessons.md?"* → append on confirmation only.
+
+Entry format:
+```markdown
+### [YYYY-MM-DD] [Brief title]
+**Mistake:** What went wrong (symptom)
+**Root cause:** Why it happened
+**Prevention:** What to do differently next time
+```
+
+Never remove lessons unless the user explicitly asks to remove a specific one.
+Never overwrite `tasks/lessons.md` — always append.
+
+## Idempotency Rules (Non-Negotiable)
+
+**Never overwrite:**
+- `tasks/todo.md`
+- `tasks/findings.md`
+- `tasks/progress.md`
+- `tasks/lessons.md`
+- `tasks/security-findings.md`
+- `CHANGELOG.md`
+- custom `CLAUDE.md` (anything not marked `<!-- Generated by /sk:setup-claude -->`)
+
+**Create-if-missing only:**
+- planning files above
+- `.claude/commands/*` (unless clearly generated by this skill; see “Signature” below)
+- `CLAUDE.md` (skip if present unless wrong-project artifacts are detected)
+
+**Safe to overwrite only if unmodified / matches template signature:**
+- `.claude/docs/changelog-guide.md`
+- `.claude/docs/arch-changelog-guide.md`
+
+## Generation Inputs
+
+This skill detects:
+- language/framework (from `package.json`, `composer.json`, `go.mod`, `Cargo.toml`, etc.)
+- DB/ORM (Drizzle/Prisma/Supabase/Eloquent/SQLAlchemy…)
+- scripts for build/dev/sk:lint/sk:test (from `package.json` where applicable)
+- key directories (common conventions + observed folders)
+
+## Laravel Detection (Additional Path)
+
+When `composer.json` contains `laravel/framework`, run these additional steps **after** the generic bootstrap. All steps are additive and idempotent — they never replace existing generic behavior.
+
+### Stack Detection
+
+Read `composer.json` and `package.json` (if present) to classify the stack:
+
+| Signal | Stack |
+|--------|-------|
+| `inertiajs/inertia-laravel` + `react` in package.json | Inertia + React |
+| `inertiajs/inertia-laravel` + `vue` in package.json | Inertia + Vue |
+| `livewire/livewire` in composer.json | Livewire |
+| Neither of the above | API-only |
+
+Write detected stack to `tasks/findings.md` (append, never overwrite):
+```
+## Stack Detection (auto-generated by /sk:setup-claude)
+- Framework: Laravel [version from composer.json]
+- Stack: [detected stack]
+- PHP: [version from composer.json]
+- Testing: Pest
+- Tools: PHPStan level 9, Rector, Pint
+```
+
+### Tool Installation
+
+Check `composer.json` devDependencies. Install only what's missing — never downgrade:
+
+```bash
+# PHPStan + Larastan (if missing)
+composer require --dev nunomaduro/larastan
+
+# Rector (if missing)
+composer require --dev rector/rector
+
+# Pint (if missing, usually pre-installed)
+composer require --dev laravel/pint
+
+# Pest (if missing)
+composer require --dev pestphp/pest pestphp/pest-plugin-laravel
+./vendor/bin/pest --init
+```
+
+### Config Publishing (create-if-missing only)
+
+**`phpstan.neon`:**
+```neon
+includes:
+    - vendor/nunomaduro/larastan/extension.neon
+
+parameters:
+    level: 9
+    paths:
+        - app
+        - tests
+    checkMissingIterableValueType: false
+```
+
+**`rector.php`:**
+```php
+<?php
+
+declare(strict_types=1);
+
+use Rector\Config\RectorConfig;
+
+return RectorConfig::configure()
+    ->withPaths([__DIR__.'/app', __DIR__.'/tests'])
+    ->withPhpSets(php84: true)
+    ->withPreparedSets(
+        deadCode: true,
+        codeQuality: true,
+        typeDeclarations: true,
+        privatization: true,
+    );
+```
+
+**`pint.json`:**
+```json
+{
+    "preset": "laravel",
+    "rules": {
+        "declare_strict_types": true,
+        "final_class": true,
+        "fully_qualified_strict_types": true
+    }
+}
+```
+
+### Strict Model Configuration
+
+Add to `AppServiceProvider::boot()` if not already present:
+
+```php
+use Illuminate\Database\Eloquent\Model;
+
+Model::shouldBeStrict(! app()->isProduction());
+Model::unguard();
+```
+
+### Sub-Agent Patterns Section
+
+The generated `CLAUDE.md` MUST include this section (place after Workflow, before Commands):
+
+```markdown
+## Sub-Agent Patterns
+<!-- BEGIN:sub-agent-patterns -->
+
+Use Claude Code sub-agents to parallelize independent work and speed up development.
+
+### Codebase Exploration (before implementation)
+
+Before implementing a feature, launch parallel Explore agents to understand the affected areas:
+
+```
+Use Agent tool with subagent_type="Explore" — launch all in a single message:
+  - Agent 1: Explore related models, migrations, and relationships
+  - Agent 2: Explore existing routes, controllers, and middleware
+  - Agent 3: Explore test patterns and existing test coverage for the area
+```
+
+### Parallel Quality Checks (/sk:lint)
+
+After Pint formats files, run PHPStan and Rector in parallel (both are read-only):
+
+```
+1. Pint (sequential — modifies files)
+2. Then in parallel:
+   - Agent 1: PHPStan analyse
+   - Agent 2: Rector --dry-run
+```
+
+### Code Review Parallelization
+
+For `/sk:review` and `/sk:security-check`, split into parallel agents for faster feedback:
+
+```
+Launch in a single message:
+  - Agent 1: Security review — OWASP, injection, auth bypass
+  - Agent 2: Performance review — N+1 queries, missing indexes, cache misses
+  - Agent 3: Test coverage gaps — untested paths, missing edge cases
+```
+
+### Worktree Isolation for Risky Changes
+
+For refactors or experimental approaches, use `isolation: "worktree"` to try the change on an isolated copy:
+
+```
+Agent tool with isolation: "worktree":
+  - Try the refactor in isolation
+  - If it works, apply the same changes to the main worktree
+  - If it fails, the worktree is discarded — no cleanup needed
+```
+
+### Background Agents for Long-Running Tasks
+
+Use `run_in_background: true` for tasks that don't block your next step:
+
+```
+- Background agent: Run full test suite while you continue implementing
+- Background agent: PHPStan analysis while you fix Rector suggestions
+- You'll be notified when they complete
+```
+<!-- END:sub-agent-patterns -->
+```
+
+### Section Completeness Check (Required on Every Run)
+
+When a generated CLAUDE.md exists (has `<!-- Generated by /sk:setup-claude -->` marker), perform a section completeness check before reporting "no changes needed":
+
+1. Search for `<!-- BEGIN:sub-agent-patterns -->`. If not found, insert the full Sub-Agent Patterns section after the Workflow section and before `## Commands`.
+2. For any future managed sections with BEGIN/END markers, repeat: search for marker, insert if missing, replace content between markers if found.
+
+This check runs every time — even if tools are installed and tasks files exist. Never short-circuit before verifying section completeness.
+
+### Laravel Idempotency (extends global rules)
+
+**Never overwrite** (in addition to global list):
+- `phpstan.neon`, `rector.php`, `pint.json` if already present
+
+**Generated CLAUDE.md (has `<!-- Generated by /sk:setup-claude -->` marker):**
+- Safe to edit with section-level updates using `<!-- BEGIN:section-name -->` / `<!-- END:section-name -->` markers
+- Full regeneration only when explicitly requested by the user
+
+**User-owned CLAUDE.md (no marker):**
+- NEVER edit directly
+- Create `CLAUDE-sub-agents.md` in the project root with the sub-agent patterns content
+- Inform the user: "Created `CLAUDE-sub-agents.md` — copy the sections you want into your `CLAUDE.md`"
+
+### Laravel Output Report (appended to generic report)
+
+Additionally report:
+- Detected stack
+- Tools installed vs already present
+- Config files created vs skipped
+
+## Templates (Source of Truth)
+
+All output files are rendered from templates in `templates/`:
+- `templates/commands/*.template` → `.claude/commands/*.md`
+- `templates/tasks/*.template` → `tasks/*.md`
+- `templates/.claude/docs/*.template` → `.claude/docs/*.md`
+- `templates/CLAUDE.md.template` → `CLAUDE.md`
+- `templates/CHANGELOG.md.template` → `CHANGELOG.md` (create-if-missing)
+
+## Quick Start (Deterministic Apply)
+
+If you want `/sk:setup-claude` to **actually write files** (not just describe what to do), run:
+
+```bash
+python3 "$HOME/.claude/skills/sk:setup-claude/scripts/apply_setup_claude.py" "$(pwd)"
+```
+
+Preview what would change (no writes):
+
+```bash
+python3 "$HOME/.claude/skills/sk:setup-claude/scripts/apply_setup_claude.py" "$(pwd)" --dry-run
+```
+
+Print detected values (JSON):
+
+```bash
+python3 "$HOME/.claude/skills/sk:setup-claude/scripts/apply_setup_claude.py" "$(pwd)" --print-detection
+```
+
+Optional: update previously generated files (only ones containing the marker):
+
+```bash
+python3 "$HOME/.claude/skills/sk:setup-claude/scripts/apply_setup_claude.py" "$(pwd)" --update-generated
+```
+
+This will:
+- create missing planning files in `tasks/`
+- create/update generated `.claude/commands/*`
+- create `CLAUDE.md` (generated) and `CHANGELOG.md` (missing-only)
+
+## Signature for Safe Updates
+
+Files generated by this skill should include a marker comment:
+`<!-- Generated by /sk:setup-claude -->`
+
+Only auto-update a file if:
+- it contains the marker, and
+- the user hasn’t obviously customized it (major edits / removed sections), otherwise **skip** and report.
+
+If a repo already has a custom `CLAUDE.md` without the marker, `/sk:setup-claude` will write a sidecar draft `CLAUDE.setup-claude.md` instead (marker-guarded) so you can copy/paste sections without losing existing project guidance.
+
+## Output Report
+
+After bootstrapping, report:
+- ✅ Created
+- 🔄 Updated
+- ⏭️ Skipped (and why)

package/skills/sk:setup-claude/references/detection.md

@@ -0,0 +1,6 @@
+# Detection Reference (Deprecated)
+
+This file exists for backwards compatibility.
+
+Source of truth: `../SKILL.md` (Detection section) and template rendering logic.
+

package/skills/sk:setup-claude/references/templates.md

@@ -0,0 +1,11 @@
+# Templates Reference (Deprecated)
+
+This file exists for backwards compatibility.
+
+Source of truth: `../templates/`.
+
+Key locations:
+- Commands: `../templates/commands/`
+- Planning files: `../templates/tasks/`
+- Project docs: `../templates/.claude/docs/`
+