@kennethsolomon/shipkit 1.0.0

package/skills/sk:setup-claude/templates/tasks-lessons.md.template

@@ -0,0 +1,3 @@
+<!-- Deprecated template path. -->
+<!-- Source of truth: templates/tasks/lessons.md.template -->
+

package/skills/sk:setup-claude/templates/tasks-progress.md.template

@@ -0,0 +1,3 @@
+<!-- Deprecated template path. -->
+<!-- Source of truth: templates/tasks/progress.md.template -->
+

package/skills/sk:setup-claude/templates/tasks-todo.md.template

@@ -0,0 +1,3 @@
+<!-- Deprecated template path. -->
+<!-- Source of truth: templates/tasks/todo.md.template -->
+

package/skills/sk:setup-claude/tests/test_apply_setup_claude.py

@@ -0,0 +1,193 @@
+import contextlib
+import importlib.util
+import io
+import json
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+
+def _load_apply_module():
+    skill_root = Path(__file__).resolve().parents[1]
+    script_path = skill_root / "scripts" / "apply_setup_claude.py"
+    spec = importlib.util.spec_from_file_location("apply_setup_claude", script_path)
+    assert spec and spec.loader
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+    return module
+
+
+class TestApplySetupClaude(unittest.TestCase):
+    def test_print_detection_exits_without_writes(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "package.json").write_text(
+                json.dumps(
+                    {
+                        "name": "demo",
+                        "description": "Demo repo",
+                        "scripts": {"dev": "next dev", "test": "vitest"},
+                        "dependencies": {"next": "1.0.0", "react": "1.0.0"},
+                        "devDependencies": {"vitest": "1.0.0"},
+                    }
+                ),
+                encoding="utf-8",
+            )
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                rc = mod.main(["apply_setup_claude.py", str(repo_root), "--print-detection"])
+            self.assertEqual(rc, 0)
+            data = json.loads(buf.getvalue().strip())
+            self.assertEqual(data["project_name"], "demo")
+            self.assertEqual(data["framework"], "Next.js (App Router)")
+
+            self.assertFalse((repo_root / "tasks").exists())
+            self.assertFalse((repo_root / ".claude").exists())
+
+    def test_dry_run_does_not_write_files_or_dirs(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "package.json").write_text(json.dumps({"name": "demo"}), encoding="utf-8")
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                rc = mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=False,
+                    dry_run=True,
+                    detection=mod.detect(repo_root),
+                )
+            self.assertEqual(rc, 0)
+
+            self.assertFalse((repo_root / "tasks").exists())
+            self.assertFalse((repo_root / ".claude").exists())
+
+    def test_marker_guarded_updates(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "package.json").write_text(
+                json.dumps({"name": "demo", "scripts": {"dev": "node dev"}}),
+                encoding="utf-8",
+            )
+            detection = mod.detect(repo_root)
+
+            # Create an agent-modified file (no marker): should NOT be overwritten.
+            no_marker_path = repo_root / ".claude" / "commands" / "status.md"
+            no_marker_path.parent.mkdir(parents=True, exist_ok=True)
+            no_marker_path.write_text("# custom status\n", encoding="utf-8")
+
+            # Create a generated file with marker but wrong content: should be updated.
+            marker_path = repo_root / ".claude" / "commands" / "plan.md"
+            marker_path.write_text(f"{mod.GENERATED_MARKER}\n# old\n", encoding="utf-8")
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                rc = mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=True,
+                    dry_run=False,
+                    detection=detection,
+                )
+            self.assertEqual(rc, 0)
+
+            self.assertEqual(no_marker_path.read_text(encoding="utf-8"), "# custom status\n")
+
+            tpl = (skill_root / "templates" / "commands" / "plan.md.template").read_text(encoding="utf-8")
+            expected = mod.render_template(tpl, detection)
+            self.assertEqual(marker_path.read_text(encoding="utf-8"), expected)
+
+    def test_workflow_status_created_on_fresh_setup(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "package.json").write_text(json.dumps({"name": "demo"}), encoding="utf-8")
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                rc = mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=False,
+                    dry_run=False,
+                    detection=mod.detect(repo_root),
+                )
+            self.assertEqual(rc, 0)
+
+            wf_path = repo_root / "tasks" / "workflow-status.md"
+            self.assertTrue(wf_path.exists())
+            content = wf_path.read_text(encoding="utf-8")
+            self.assertIn(">> next <<", content)
+            self.assertIn("/brainstorm", content)
+            self.assertIn("/finish-feature", content)
+            self.assertIn("/release", content)
+            # All 14 steps present
+            self.assertIn("| 14 |", content)
+
+    def test_workflow_status_not_overwritten_on_rerun(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "package.json").write_text(json.dumps({"name": "demo"}), encoding="utf-8")
+
+            # First run creates the file
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                mod.apply(repo_root, skill_root, update_generated=False, dry_run=False, detection=mod.detect(repo_root))
+
+            # Simulate user progress by modifying the file
+            wf_path = repo_root / "tasks" / "workflow-status.md"
+            custom_content = wf_path.read_text(encoding="utf-8").replace(">> next <<", "done")
+            wf_path.write_text(custom_content, encoding="utf-8")
+
+            # Second run should NOT overwrite
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                mod.apply(repo_root, skill_root, update_generated=False, dry_run=False, detection=mod.detect(repo_root))
+
+            self.assertEqual(wf_path.read_text(encoding="utf-8"), custom_content)
+
+    def test_existing_custom_claude_md_writes_sidecar(self):
+        mod = _load_apply_module()
+        skill_root = Path(__file__).resolve().parents[1]
+
+        with tempfile.TemporaryDirectory() as td:
+            repo_root = Path(td)
+            (repo_root / "package.json").write_text(json.dumps({"name": "demo"}), encoding="utf-8")
+            (repo_root / "CLAUDE.md").write_text("# Custom\n", encoding="utf-8")
+
+            buf = io.StringIO()
+            with contextlib.redirect_stdout(buf):
+                rc = mod.apply(
+                    repo_root,
+                    skill_root,
+                    update_generated=False,
+                    dry_run=False,
+                    detection=mod.detect(repo_root),
+                )
+            self.assertEqual(rc, 0)
+
+            self.assertEqual((repo_root / "CLAUDE.md").read_text(encoding="utf-8"), "# Custom\n")
+            self.assertTrue((repo_root / "CLAUDE.setup-claude.md").exists())
+            self.assertIn("Notes:", buf.getvalue())
+
+
+if __name__ == "__main__":
+    unittest.main()

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

@@ -0,0 +1,184 @@
+---
+name: sk:setup-optimizer
+description: "Diagnose, update workflow, enrich, and maintain CLAUDE.md. The single command to keep any CLAUDE.md current."
+triggers:
+  - optimize claude
+  - optimize setup
+  - enrich claude
+  - maintain claude
+  - doctor claude
+  - check claude
+  - diagnose claude
+  - refresh claude
+  - update claude
+  - re-setup
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+---
+
+## Overview
+
+The single command to keep your CLAUDE.md current. Diagnoses problems, updates the workflow to the latest version, scans your codebase, and enriches with project context — all while preserving your customizations.
+
+### What It Does
+
+1. **Diagnoses** — finds missing sections, stale info, inconsistencies, and gaps
+2. **Updates workflow** — refreshes the workflow section to the latest template version
+3. **Discovers** — scans project structure, docs, and workflows
+4. **Enriches** — merges discoveries into CLAUDE.md while preserving your edits
+
+## Usage
+
+```bash
+/sk:setup-optimizer
+```
+
+### Step 0: Diagnose
+
+Before making any changes, runs a diagnostic pass on the existing CLAUDE.md:
+
+- **Missing sections** — checks for essential sections (Workflow, Sub-Agent Patterns, Project Memory, Lessons Capture, Testing, Commands, etc.)
+- **Stale content** — detects outdated info (stale model/route counts, removed dependencies, old command names like `/laravel-lint` instead of `/sk:lint`)
+- **Inconsistencies** — compares documented vs actual project state (directories, scripts, workflows)
+- **Section completeness** — flags sections that exist but are empty or have only placeholder text
+- **Outdated workflow** — checks if the workflow matches the current 24-step TDD flow with hard gates
+
+Reports findings before proceeding. If issues are found, they inform subsequent steps.
+
+### Step 1: Update Workflow
+
+If the workflow section is outdated or missing, replace it with the latest version:
+
+**Current workflow (24 steps, TDD with hard gates):**
+```
+Read → Explore → Design → Accessibility → Plan → Branch → Migrate → Write Tests → Implement → Lint → Verify Tests → Security → Performance → Review → Finish
+```
+
+**What gets updated:**
+- Workflow table (24 steps with correct commands: `/sk:write-tests`, `/sk:lint`, `/sk:test`, `/sk:accessibility`, `/sk:perf`)
+- Step details (TDD red/green/verify descriptions)
+- Tracker rules (hard gates at 12, 14, 16, 20; optional steps 4, 5, 7, 18, 24)
+- Step completion summary rule (NON-NEGOTIABLE)
+- Bug fix flow section
+- Sub-Agent Patterns section (if missing)
+- Project Memory section (if missing)
+- Lessons Capture section (if missing)
+- Testing TDD section (if missing)
+- 3-Strike Protocol (if missing)
+
+**What gets preserved:**
+- Everything marked with `<!-- LOCK -->` is never touched
+- Project-specific content below the workflow (conventions, models, routes, architecture)
+- Stack section, Build & Run section
+- Any section with `<!-- EDITED -->` marker
+
+**How it works:**
+1. Read the latest workflow template from `~/.claude/skills/sk:setup-claude/templates/CLAUDE.md.template`
+2. Compare with the current CLAUDE.md workflow section
+3. If different, replace the workflow section (between `## Workflow` and the next `##` that isn't a workflow subsection)
+4. Insert missing sections (Sub-Agent Patterns, Project Memory, etc.) in their correct positions
+5. Preserve all `<!-- LOCK -->` and project-specific sections
+
+### Step 2: Scan & Enrich
+
+After workflow update, proceeds with codebase discovery and enrichment:
+
+1. Scans project for directories, docs, and workflows
+2. Reads your existing CLAUDE.md
+3. Intelligently merges discoveries with your content (prioritizing diagnosed gaps)
+4. Preserves any user customizations
+5. Updates CLAUDE.md with comprehensive context
+
+## What Gets Discovered
+
+### Directories
+Auto-documents: src/, tests/, docs/, public/, scripts/, config/, migrations/, and more (intelligently excludes node_modules/, vendor/, etc.)
+
+### Documentation
+Finds and links: README.md, CONTRIBUTING.md, CHANGELOG.md, docs/*.md, .github/CONTRIBUTING.md, and more
+
+### Workflows
+Detects: Makefile targets, npm/yarn scripts, GitHub Actions workflows
+
+## Smart Features
+
+### 1. User Customization Preservation
+
+**Dual Detection:**
+- Compares content to detect user edits
+- Looks for `<!-- EDITED -->` markers
+- Automatically preserves customized sections
+
+**Auto-Locking:**
+- `Important Context` section - auto-locked if has content
+- `Known Issues` section - auto-locked
+- Any section with `<!-- LOCK -->` comment - permanently locked
+
+**Result:** Run multiple times during development without losing work!
+
+### 2. Intelligent Merging
+
+When updating CLAUDE.md:
+- ✅ Keeps user customizations intact
+- ✅ Updates auto-generated discovery sections
+- ✅ Adds newly discovered items
+- ✅ Reports what was preserved
+
+### 3. Flexible Line Count
+
+- **Target:** Stay under 200 lines when possible
+- **Philosophy:** Comprehensive context > artificial line limit
+- **Strategy:** Link to docs instead of inlining if extensive
+
+## Maintenance Workflow
+
+### During Development
+
+```bash
+# After adding new test directory
+mkdir tests
+
+# Run optimizer to discover it
+/optimize-claude
+
+# CLAUDE.md now documents tests/ automatically!
+```
+
+### When Customizing
+
+```bash
+# Edit Important Context with custom notes
+vim CLAUDE.md
+
+# The edit is automatically preserved on next run
+/optimize-claude
+
+# ✅ Your notes stay intact!
+```
+
+## Configuration
+
+### Smart Defaults (Auto-Locked)
+- **Important Context** - Your project decisions
+- **Known Issues** - Problems/limitations
+- Any section with `<!-- LOCK -->` comment
+
+### Explicit Locking
+
+```markdown
+## My Custom Section
+<!-- LOCK -->
+This content will never be regenerated.
+```
+
+## When to Use
+
+✅ **Use `/optimize-claude` when:**
+- You've added new directories to your project
+- You've created documentation files
+- You want to refresh project context
+- Monthly maintenance of CLAUDE.md
+
+✅ **Safe to run multiple times during development** - Your customizations are always preserved!

package/skills/sk:setup-optimizer/lib/__init__.py

@@ -0,0 +1,24 @@
+"""Claude setup tools library."""
+
+from .detect import ProjectConfig, detect_project
+from .sidecar import (
+    has_marker,
+    is_custom_file,
+    get_target_file,
+    add_marker,
+    format_output,
+    count_lines,
+    extract_sections,
+)
+
+__all__ = [
+    "ProjectConfig",
+    "detect_project",
+    "has_marker",
+    "is_custom_file",
+    "get_target_file",
+    "add_marker",
+    "format_output",
+    "count_lines",
+    "extract_sections",
+]

package/skills/sk:setup-optimizer/lib/detect.py

@@ -0,0 +1,205 @@
+"""Auto-detection logic for project configuration."""
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+@dataclass
+class ProjectConfig:
+    """Detected project configuration."""
+
+    language: str = "Unknown"
+    framework: str = "None"
+    database: str = "None"
+    ui: str = "None"
+    testing: str = "None"
+    description: str = ""
+    dev_command: str = ""
+    build_command: str = ""
+    test_command: str = ""
+    lint_command: str = ""
+    project_name: str = ""
+    project_dir: str = ""
+
+
+def detect_project(root_path: Path) -> ProjectConfig:
+    """Auto-detect project configuration from files.
+
+    Args:
+        root_path: Root directory of the project
+
+    Returns:
+        ProjectConfig with detected values
+    """
+    config = ProjectConfig()
+    config.project_dir = root_path.name
+    config.project_name = root_path.name
+
+    # Check package.json (Node.js)
+    package_json = root_path / "package.json"
+    if package_json.exists():
+        return _detect_nodejs(root_path, config)
+
+    # Check pyproject.toml or setup.py (Python)
+    if (root_path / "pyproject.toml").exists() or (root_path / "setup.py").exists():
+        return _detect_python(root_path, config)
+
+    # Check go.mod (Go)
+    if (root_path / "go.mod").exists():
+        return _detect_go(root_path, config)
+
+    # Check Cargo.toml (Rust)
+    if (root_path / "Cargo.toml").exists():
+        return _detect_rust(root_path, config)
+
+    # Default: Generic project
+    config.language = "JavaScript/TypeScript"
+    config.dev_command = "npm run dev"
+    config.build_command = "npm run build"
+    config.test_command = "npm test"
+    config.lint_command = "npm run lint"
+
+    return config
+
+
+def _detect_nodejs(root_path: Path, config: ProjectConfig) -> ProjectConfig:
+    """Detect Node.js/JavaScript project details."""
+    config.language = "JavaScript/TypeScript"
+
+    try:
+        with open(root_path / "package.json") as f:
+            pkg = json.load(f)
+
+        # Extract project info
+        config.project_name = pkg.get("name", config.project_name)
+        config.description = pkg.get("description", "")
+
+        # Detect framework
+        deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+
+        if "react" in deps or "next" in deps:
+            config.framework = "React" if "react" in deps else "Next.js"
+            config.ui = "React"
+        elif "vue" in deps or "nuxt" in deps:
+            config.framework = "Vue" if "vue" in deps else "Nuxt"
+            config.ui = "Vue"
+        elif "angular" in deps:
+            config.framework = "Angular"
+            config.ui = "Angular"
+        elif "svelte" in deps:
+            config.framework = "Svelte"
+            config.ui = "Svelte"
+
+        # Detect UI framework
+        if "tailwindcss" in deps:
+            config.ui = "Tailwind CSS"
+        elif "styled-components" in deps:
+            config.ui = "styled-components"
+        elif "sass" in deps or "node-sass" in deps:
+            config.ui = "Sass"
+
+        # Detect database
+        if "prisma" in deps:
+            config.database = "Prisma"
+        elif "drizzle-orm" in deps:
+            config.database = "Drizzle"
+        elif "mongoose" in deps:
+            config.database = "MongoDB (Mongoose)"
+        elif "sequelize" in deps:
+            config.database = "PostgreSQL (Sequelize)"
+        elif "typeorm" in deps:
+            config.database = "TypeORM"
+
+        # Detect testing
+        if "vitest" in deps:
+            config.testing = "Vitest"
+        elif "jest" in deps:
+            config.testing = "Jest"
+        elif "mocha" in deps:
+            config.testing = "Mocha"
+
+        # Extract commands from package.json scripts
+        scripts = pkg.get("scripts", {})
+        config.dev_command = f"npm run {_find_script(scripts, ['dev', 'start'])}" if _find_script(scripts, ['dev', 'start']) else "npm run dev"
+        config.build_command = f"npm run {_find_script(scripts, ['build'])}" if _find_script(scripts, ['build']) else "npm run build"
+        config.test_command = f"npm test"
+        config.lint_command = f"npm run {_find_script(scripts, ['lint'])}" if _find_script(scripts, ['lint']) else "npm run lint"
+
+    except Exception as e:
+        print(f"Warning: Could not fully parse package.json: {e}")
+
+    return config
+
+
+def _detect_python(root_path: Path, config: ProjectConfig) -> ProjectConfig:
+    """Detect Python project details."""
+    config.language = "Python"
+
+    # Try pyproject.toml first
+    pyproject = root_path / "pyproject.toml"
+    if pyproject.exists():
+        try:
+            content = pyproject.read_text()
+
+            # Simple detection without external dependency
+            if "django" in content:
+                config.framework = "Django"
+            elif "fastapi" in content:
+                config.framework = "FastAPI"
+            elif "flask" in content:
+                config.framework = "Flask"
+            elif "starlette" in content:
+                config.framework = "Starlette"
+
+            if "sqlalchemy" in content or "alembic" in content:
+                config.database = "SQLAlchemy"
+            elif "django" in content:
+                config.database = "Django ORM"
+
+            if "pytest" in content:
+                config.testing = "pytest"
+        except Exception as e:
+            print(f"Warning: Could not parse pyproject.toml: {e}")
+
+    # Default Python commands
+    config.dev_command = "python -m uvicorn main:app --reload"
+    config.build_command = "pip install -e ."
+    config.test_command = "pytest"
+    config.lint_command = "pylint ."
+    config.description = "Python project"
+
+    return config
+
+
+def _detect_go(root_path: Path, config: ProjectConfig) -> ProjectConfig:
+    """Detect Go project details."""
+    config.language = "Go"
+    config.dev_command = "go run ."
+    config.build_command = "go build -o bin/app ."
+    config.test_command = "go test ./..."
+    config.lint_command = "golangci-lint run"
+    config.description = "Go project"
+
+    return config
+
+
+def _detect_rust(root_path: Path, config: ProjectConfig) -> ProjectConfig:
+    """Detect Rust project details."""
+    config.language = "Rust"
+    config.dev_command = "cargo run"
+    config.build_command = "cargo build --release"
+    config.test_command = "cargo test"
+    config.lint_command = "cargo clippy"
+    config.description = "Rust project"
+
+    return config
+
+
+def _find_script(scripts: dict, candidates: list) -> Optional[str]:
+    """Find first matching script from candidates."""
+    for candidate in candidates:
+        if candidate in scripts:
+            return candidate
+    return None