claude-launchpad 0.5.0 → 0.5.2

package/README.md

@@ -5,19 +5,16 @@
 [![GitHub stars](https://img.shields.io/github/stars/mboss37/claude-launchpad?style=flat-square)](https://github.com/mboss37/claude-launchpad)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://github.com/mboss37/claude-launchpad/blob/master/LICENSE)
 
-**Everything you need to launch a project with Claude Code — and keep it healthy.**
+**Score your Claude Code setup. Fix what's broken. Prove it works.**
 
-A launchpad isn't just where you start. It's where you prepare, run checks, and make sure everything is ready before you go. Claude Launchpad does exactly that for your Claude Code setup:
-
-- **Launch new projects** with production-ready Claude Code config from day one
-- **Check existing projects** — score your config, find issues, auto-fix them
-- **Prove it works** — run Claude against test scenarios and see if your rules are actually followed
+CLAUDE.md is advisory — Claude follows your rules ~80% of the time. Hooks are deterministic — 100% compliance. But most developers have zero hooks and too many instructions. This tool gives you a number, fixes the gaps, and lets you prove Claude actually follows your config.
 
 ```bash
-npm i -g claude-launchpad
-cd your-project
+npx claude-launchpad
 ```
 
+That's it. Run it in any project with Claude Code. You'll see a score out of 100 and a list of exactly what's wrong. Run `--fix` to auto-repair.
+
 ## Two Paths, One Tool
 
 ### Starting a new project?
@@ -26,9 +23,9 @@ cd your-project
 claude-launchpad init
 ```
 
-Detects your stack, generates `CLAUDE.md` with your commands, conventions, and memory management instructions, creates `TASKS.md` for sprint tracking and session continuity, sets up hooks for auto-formatting, `.env` protection, and context re-injection after compaction, and adds a `.claudeignore` so Claude doesn't waste time reading `node_modules`.
+Detects your stack, generates `CLAUDE.md` with your commands and conventions, creates `TASKS.md` for tracking work across sessions, sets up hooks that auto-format code and block dangerous operations, and adds a `.claudeignore` so Claude skips `node_modules` and build artifacts.
 
-Then run `enhance` to have Claude read your codebase and fill in the architecture, conventions, and guardrails with real, project-specific content — not boilerplate.
+Then run `enhance` to have Claude read your actual codebase and fill in the architecture and guardrails — not boilerplate, real project-specific content. Requires Claude Code CLI.
 
 ### Already have a project?
 
@@ -40,35 +37,24 @@ Scans your Claude Code config, gives you a score out of 100, and tells you exact
 
 ## All Commands
 
-| Command | What it does |
-|---|---|
-| `claude-launchpad init` | Launch a new project: detects stack, generates config, security rules, hooks, permissions |
-| `claude-launchpad` | Check your config: score it 0-100, list issues |
-| `claude-launchpad doctor --fix` | Auto-fix issues: adds hooks, rules, missing sections, .claudeignore |
-| `claude-launchpad doctor --watch` | Live score that updates when you save config files |
-| `claude-launchpad enhance` | Claude reads your code and completes CLAUDE.md with real content |
-| `claude-launchpad eval --suite security` | Run Claude against test scenarios, prove your config works |
+| Command | What it does | Runs |
+|---|---|---|
+| `claude-launchpad init` | Detect stack, generate config, hooks, permissions | Locally |
+| `claude-launchpad` | Score your config 0-100, list issues | Locally |
+| `claude-launchpad doctor --fix` | Auto-fix issues: hooks, rules, sections, .claudeignore | Locally |
+| `claude-launchpad doctor --watch` | Live score that updates when you save config files | Locally |
+| `claude-launchpad enhance` | Claude reads your code and completes CLAUDE.md | Via Claude CLI |
+| `claude-launchpad eval` | Run Claude against test scenarios, prove config works | Via Claude CLI |
 
 ## Quick Start
 
 ```bash
-# Install
-npm i -g claude-launchpad
-
-# Go to any project with Claude Code
 cd your-project
-
-# See your score
-claude-launchpad
-
-# Fix everything it found
-claude-launchpad doctor --fix
-
-# See your new score
-claude-launchpad
+npx claude-launchpad            # see your score
+npx claude-launchpad doctor --fix   # fix everything
 ```
 
-That takes you from ~42% to ~93% with zero manual work.
+A typical unconfigured project scores ~42%. After `--fix`, it jumps to ~86%. Run `init` on a fresh project and you start at ~93%.
 
 ## The Doctor
 
@@ -105,6 +91,7 @@ Output looks like this:
 | Flag | What it does |
 |---|---|
 | `--fix` | Auto-fixes issues: adds hooks, CLAUDE.md sections, rules, .claudeignore |
+| `--fix --dry-run` | Preview what --fix would change without applying |
 | `--watch` | Re-runs every second, updates when you save a config file |
 | `--json` | Pure JSON output, no colors, no banner — for scripts and CI |
 | `--min-score <n>` | Exit code 1 if score is below threshold — use in CI to block bad configs |
@@ -182,7 +169,7 @@ Results are saved to `.claude/eval/` as structured markdown — you can feed the
 |---|---|---|
 | `security` | 6 | SQL injection, .env protection, secret exposure, input validation, credential read, sandbox escape |
 | `conventions` | 5 | Error handling, immutability, file size, naming, no hardcoded values |
-| `workflow` | 2 | Git conventions, session continuity |
+| `workflow` | 4 | Git conventions, session continuity, memory persistence, deferred tracking |
 
 **All eval flags:**
 
@@ -217,14 +204,6 @@ jobs:
 
 Score below threshold = exit code 1 = PR blocked.
 
-## Plugin (pending marketplace review)
-
-```bash
-claude plugin install claude-launchpad
-```
-
-Then use `/launchpad:doctor`, `/launchpad:init`, `/launchpad:enhance`, `/launchpad:eval` inside Claude Code. The plugin nudges you to re-check your score when you edit config files.
-
 ## How It Works
 
 **Doctor** reads your files and runs static analysis. No API calls. No network. No cost.
@@ -237,12 +216,7 @@ Then use `/launchpad:doctor`, `/launchpad:init`, `/launchpad:enhance`, `/launchp
 
 ## Why This Exists
 
-- **CLAUDE.md is advisory.** ~80% compliance. Claude might ignore your rules.
-- **Hooks are deterministic.** 100% compliance. But most people have zero hooks.
-- **Instruction budget is real.** Past ~150, compliance drops. Most people don't know they're over.
-- **Nobody measures.** You can't improve what you can't measure.
-
-This tool gives you a number. Fix the issues, re-run, watch the number go up.
+Nobody measures their Claude Code config quality. You write CLAUDE.md, hope Claude follows it, and never verify. This tool gives you a number. Fix the issues, re-run, watch it go up.
 
 ## Glossary
 
@@ -254,6 +228,7 @@ New to Claude Code? Here's what the terms mean:
 | **Hooks** | Shell commands that run automatically when Claude does something. For example: auto-format a file after Claude edits it, or block Claude from reading your `.env` file. They live in `.claude/settings.json`. |
 | **Instruction budget** | CLAUDE.md has a soft limit of ~150 actionable lines. Past that, Claude starts ignoring rules at the bottom. Doctor counts your lines and warns you. |
 | **Rules** | Extra markdown files in `.claude/rules/` that Claude reads alongside CLAUDE.md. Use them to offload detailed conventions so CLAUDE.md stays under budget. |
+| **Compaction** | When a Claude Code conversation gets too long, it compresses older messages to free up space. This can lose context — a PostCompact hook re-injects critical files (like TASKS.md) after compaction. |
 | **MCP Servers** | External tools Claude can connect to (databases, APIs, docs). Configured in `.claude/settings.json`. Most projects don't need them. |
 | **.claudeignore** | Like `.gitignore` but for Claude. Tells Claude which files to skip (node_modules, dist, lockfiles) so it doesn't waste time reading noise. |
 

package/dist/cli.js

@@ -404,6 +404,13 @@ function generateSettings(detected) {
   if (formatHook) {
     postToolUse.push(formatHook);
   }
+  const sessionStart = [{
+    matcher: "startup|resume",
+    hooks: [{
+      type: "command",
+      command: "cat TASKS.md 2>/dev/null; exit 0"
+    }]
+  }];
   const postCompact = [{
     matcher: "",
     hooks: [{
@@ -412,6 +419,7 @@ function generateSettings(detected) {
     }]
   }];
   const hooks = {};
+  hooks.SessionStart = sessionStart;
   if (preToolUse.length > 0) hooks.PreToolUse = preToolUse;
   if (postToolUse.length > 0) hooks.PostToolUse = postToolUse;
   hooks.PostCompact = postCompact;
@@ -810,7 +818,8 @@ async function readHooks(claudeDir) {
               event,
               type: h.type ?? "command",
               matcher,
-              command: h.command
+              command: h.command,
+              timeout: h.timeout
             });
           }
         } else {
@@ -818,7 +827,8 @@ async function readHooks(claudeDir) {
             event,
             type: g.type ?? "command",
             matcher,
-            command: g.command
+            command: g.command,
+            timeout: g.timeout
           });
         }
       }
@@ -981,6 +991,44 @@ async function analyzeSettings(config) {
       fix: "Add PreToolUse hooks for security or remove allowedTools to use interactive prompting"
     });
   }
+  if (config.settings.includeCoAuthoredBy !== void 0) {
+    issues.push({
+      analyzer: "Settings",
+      severity: "low",
+      message: 'Deprecated includeCoAuthoredBy \u2014 use attribution: { commit: "", pr: "" } instead',
+      fix: "Replace includeCoAuthoredBy with the attribution object in settings.json"
+    });
+  }
+  if (!config.settings.claudeMdExcludes) {
+    issues.push({
+      analyzer: "Settings",
+      severity: "info",
+      message: "No claudeMdExcludes configured \u2014 consider adding this if you have a monorepo"
+    });
+  }
+  const broadMatchers = ["Bash", "Write", "Edit", "Read"];
+  const hooksWithoutTimeout = config.hooks.filter(
+    (h) => !h.timeout && broadMatchers.some((m) => h.matcher?.includes(m))
+  );
+  if (hooksWithoutTimeout.length > 0) {
+    issues.push({
+      analyzer: "Settings",
+      severity: "low",
+      message: `${hooksWithoutTimeout.length} hook(s) on broad matchers without timeout \u2014 defaults to 60s per invocation`,
+      fix: "Add timeout (in seconds) to hooks on Bash, Write, Edit, or Read matchers"
+    });
+  }
+  if (config.settings.autoMemoryEnabled === false) {
+    const hasMemorySection = config.claudeMdContent?.includes("## Memory") ?? false;
+    if (!hasMemorySection) {
+      issues.push({
+        analyzer: "Settings",
+        severity: "medium",
+        message: "Auto-memory is disabled with no manual memory strategy in CLAUDE.md",
+        fix: "Re-enable autoMemoryEnabled or add a ## Memory section to CLAUDE.md"
+      });
+    }
+  }
   const actionableCount = issues.filter((i) => i.severity !== "info").length;
   const score = Math.max(0, 100 - actionableCount * 20);
   return { name: "Settings", issues, score };
@@ -1040,7 +1088,16 @@ async function analyzeHooks(config) {
       fix: "Add a PostCompact hook that re-injects TASKS.md after compaction"
     });
   }
-  const score = Math.max(0, 100 - issues.length * 20);
+  const hasSessionStart = hooks.some((h) => h.event === "SessionStart");
+  if (!hasSessionStart) {
+    issues.push({
+      analyzer: "Hooks",
+      severity: "low",
+      message: "No SessionStart hook \u2014 session starts without project context loaded",
+      fix: "Add a SessionStart hook that injects TASKS.md at startup"
+    });
+  }
+  const score = Math.max(0, 100 - issues.length * 15);
   return { name: "Hooks", issues, score };
 }
 
@@ -1373,7 +1430,8 @@ var FIX_TABLE = [
   { analyzer: "Permissions", match: "Credential files not blocked", fix: (root) => addCredentialDenyRules(root) },
   { analyzer: "Permissions", match: "Bypass permissions mode", fix: (root) => addBypassDisable(root) },
   { analyzer: "Permissions", match: "Sandbox not enabled", fix: (root) => addSandboxSettings(root) },
-  { analyzer: "Permissions", match: ".env is protected by hooks but not in .claudeignore", fix: (root) => addEnvToClaudeignore(root) }
+  { analyzer: "Permissions", match: ".env is protected by hooks but not in .claudeignore", fix: (root) => addEnvToClaudeignore(root) },
+  { analyzer: "Settings", match: "Deprecated includeCoAuthoredBy", fix: (root) => migrateAttribution(root) }
 ];
 async function tryFix(issue, root, detected) {
   const entry = FIX_TABLE.find(
@@ -1475,6 +1533,15 @@ async function addPostCompactHook(root) {
   log.success("Added PostCompact hook (re-injects TASKS.md after compaction)");
   return true;
 }
+async function migrateAttribution(root) {
+  const settings = await readSettingsJson(root);
+  if (settings.includeCoAuthoredBy === void 0) return false;
+  const { includeCoAuthoredBy: _, ...rest } = settings;
+  const updated = { ...rest, attribution: { commit: "", pr: "" } };
+  await writeSettingsJson(root, updated);
+  log.success("Migrated includeCoAuthoredBy \u2192 attribution object");
+  return true;
+}
 async function addCredentialDenyRules(root) {
   const settings = await readSettingsJson(root);
   const permissions = settings.permissions ?? {};
@@ -1660,7 +1727,7 @@ async function runAndDisplay(projectRoot) {
 
 // src/commands/doctor/index.ts
 function createDoctorCommand() {
-  return new Command2("doctor").description("Diagnose your Claude Code configuration and report issues").option("-p, --path <path>", "Project root path", process.cwd()).option("--json", "Output as JSON").option("--min-score <n>", "Exit non-zero if overall score is below this threshold (for CI)").option("--fix", "Auto-apply deterministic fixes for detected issues").option("--watch", "Watch for config changes and re-run automatically").action(async (opts) => {
+  return new Command2("doctor").description("Diagnose your Claude Code configuration and report issues").option("-p, --path <path>", "Project root path", process.cwd()).option("--json", "Output as JSON").option("--min-score <n>", "Exit non-zero if overall score is below this threshold (for CI)").option("--fix", "Auto-apply deterministic fixes for detected issues").option("--dry-run", "Preview what --fix would change without applying").option("--watch", "Watch for config changes and re-run automatically").action(async (opts) => {
     if (opts.watch) {
       await watchConfig(opts.path);
       return;
@@ -1697,13 +1764,36 @@ function createDoctorCommand() {
       const allIssues = results.flatMap((r) => r.issues);
       const fixable = allIssues.filter((i) => i.severity !== "info");
       if (fixable.length > 0) {
+        if (opts.dryRun) {
+          log.blank();
+          log.step("Dry run \u2014 would apply these fixes:");
+          log.blank();
+          for (const issue of fixable) {
+            log.info(`  Would fix: ${issue.message}`);
+          }
+          log.blank();
+          log.success(`${fixable.length} fix(es) available. Run --fix without --dry-run to apply.`);
+          return;
+        }
         log.blank();
         log.step("Applying fixes...");
         log.blank();
         const { fixed, skipped } = await applyFixes(fixable, opts.path);
         log.blank();
         if (fixed > 0) {
-          log.success(`Applied ${fixed} fix(es). Run \`claude-launchpad doctor\` again to see your new score.`);
+          log.success(`Applied ${fixed} fix(es). Re-scanning...`);
+          log.blank();
+          const updatedConfig = await parseClaudeConfig(opts.path);
+          const updatedResults = await Promise.all([
+            analyzeBudget(updatedConfig),
+            analyzeQuality(updatedConfig),
+            analyzeSettings(updatedConfig),
+            analyzeHooks(updatedConfig),
+            analyzeRules(updatedConfig),
+            analyzePermissions(updatedConfig),
+            analyzeMcp(updatedConfig)
+          ]);
+          renderDoctorReport(updatedResults);
         }
         if (skipped > 0) {
           log.info(`${skipped} issue(s) require manual intervention.`);
@@ -2346,9 +2436,15 @@ Also review .claude/settings.json hooks:
 - Read the existing hooks in .claude/settings.json
 - If you see project-specific patterns that deserve hooks (e.g., protected directories, test file patterns, migration files), suggest adding them
 - If no PostCompact hook exists, suggest adding one that re-injects TASKS.md after context compaction (critical for session continuity)
+- If no SessionStart hook exists, suggest adding one that injects TASKS.md at session startup
 - DO NOT overwrite existing hooks \u2014 only add new ones that are specific to this project
 - Print hook suggestions at the end with the exact JSON to add, don't modify settings.json directly
 
+Also check for advanced configuration opportunities:
+- If the project has both app code and tests, suggest creating path-scoped .claude/rules/ files with paths: frontmatter (e.g., test conventions only load when editing test files)
+- If the project uses external APIs (Stripe, GitHub, AWS SDKs, etc.), suggest sandbox.network.allowedDomains to restrict outbound traffic
+- If you detect a monorepo (Turborepo, Lerna, pnpm workspaces, multiple package.json), suggest claudeMdExcludes in settings.json
+
 Rules:
 - Don't remove existing content \u2014 only add or improve
 - Be specific to THIS project, not generic advice