@delegance/claude-autopilot 5.0.0-alpha.1 → 5.0.0-alpha.2

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [5.0.0-alpha.2] — 2026-04-24
+
+### Added
+- **v4 compatibility assertion matrix** at `tests/v4-compat/` — 20 pinned invocations covering version/help, subcommand routing for all v4 names, deterministic reads (doctor, costs, baseline, explain), flag parsing (`--base`, `--format`, `--fail-on`), deprecation-notice behavior, and the new grouped verbs. Uses marker/regex assertions, not full stdout snapshots — still catches routing and parsing regressions, which is the intent. Full normalized-stdout snapshots for deterministic commands are a follow-up item. Regression of any test blocks future alpha promotion.
+- **Superpowers peer-dep detection** — `doctor` now reports a warn-level check for `superpowers:writing-plans`, `superpowers:using-git-worktrees`, `superpowers:subagent-driven-development`. Missing skills produce an actionable remediation hint (`claude plugin install superpowers`). Treated as warn not fail because review-only users don't need it; pipeline phases will hard-fail at their own entry point.
+- **Grouped CLI verbs (phase 1: additive aliases)** — `claude-autopilot review <verb>` accepts `{run, scan, ci, fix, baseline, explain, watch, report}`. `claude-autopilot advanced <verb>` accepts `{lsp, mcp, worker, autoregress, test-gen, hook, detector, ignore}`. Both are additive aliases — flat forms (`claude-autopilot run`) continue to work unchanged. Broader restructuring (pipeline verbs `migrate`/`validate` top-level, `pr {create,comment,desc}`) is a later-alpha item.
+- **`peerDependencies.superpowers`** (optional) declared in `package.json`.
+- `src/cli/preflight.ts`: `findMissingSuperpowersSkills()` exported with recursive search across `~/.claude/plugins/**` and project-local `.claude/plugins/**`.
+
+### Fixed
+- **`--help` / `-h` routed to `run`** (latent v4 bug). v4's dispatcher defaulted the subcommand to `run` when `args[0]` started with `--`, so `guardrail --help` silently executed a review instead of printing help. v5.0.0-alpha.2 intercepts `--help`/`-h` before subcommand defaulting and routes to the help handler. Surfaced by the new v4 compat matrix.
+- **`--help` output missing 8 v4 subcommands** — `setup`, `preflight`, `hook`, `baseline`, `triage`, `pr-desc`, `council`, `mcp` were listed in the `SUBCOMMANDS` array but not in `printUsage()`. Help now lists all 20+.
+
+### Changed
+- README install instructions now pin `@alpha` explicitly for the v5 alpha cycle. The npm `latest` tag still points at a pre-rename 2.5.0 release; without pinning, bare installs silently regress to old code. When 5.0.0 GA ships, `latest` advances and the `@alpha` pin becomes optional.
+- Migration guide updated with the `@alpha` pinning note for `npm install`, GitHub Actions, and Dockerfile examples.
+
+### Still deferred to alpha.3
+- Tombstone `@delegance/guardrail@5.0.0` with thin CLI wrapper and strict argv/stdio passthrough.
+- CI bin-parity smoke tests (`npx guardrail`, `npx @delegance/guardrail`, global install, GitHub Actions).
+- Codemod script `claude-autopilot migrate-v4 [--write]`.
+- Compiled JS entrypoint (drops `tsx` runtime dep).
+
 ## [5.0.0-alpha.1] — 2026-04-24
 
 **Package renamed: `@delegance/guardrail` → `@delegance/claude-autopilot`.**

package/README.md

@@ -39,11 +39,11 @@ The architectural differences that matter most in practice:
 ## 30-second quickstart
 
 ```bash
-# Install
-npm install -g @delegance/claude-autopilot
+# Install (alpha channel — use @alpha through the v5 alpha cycle)
+npm install -g @delegance/claude-autopilot@alpha
 
 # One-shot setup — detects stack, writes config, installs skills, sets hooks
-npx claude-autopilot init
+npx claude-autopilot@alpha init
 
 # Ship a feature end-to-end
 claude-autopilot brainstorm "add rate limiting to the public API"
@@ -98,13 +98,18 @@ claude-autopilot fix --verify                    # LLM patch + test gate + rever
 ## Install & requirements
 
 ```bash
-npm install -g @delegance/claude-autopilot
+# v5 alpha — current release channel
+npm install -g @delegance/claude-autopilot@alpha
+
+# When 5.0.0 GA ships, the `latest` tag will advance and you can drop the @alpha:
+# npm install -g @delegance/claude-autopilot
 ```
 
 - Node 22+
 - `gh` CLI (for PR phases)
 - One of: `ANTHROPIC_API_KEY` (recommended), `OPENAI_API_KEY`, `GEMINI_API_KEY`, or `GROQ_API_KEY`
 - Claude Code CLI (for skill-based phases — pipeline falls back to direct CLI invocations without it, but loses interactive checkpoints)
+- `superpowers` Claude Code plugin (required for pipeline phases — `claude-autopilot doctor` will remediation-hint if missing)
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@delegance/claude-autopilot",
-  "version": "5.0.0-alpha.1",
+  "version": "5.0.0-alpha.2",
   "type": "module",
   "description": "Autonomous development pipeline for Claude Code: brainstorm → spec → plan → implement → migrate → validate → PR → review → merge. Multi-model, local-first, every phase a skill you can intervene in.",
   "keywords": [
@@ -64,5 +64,13 @@
     "@types/js-yaml": "^4",
     "@types/node": "^25",
     "typescript": "^6"
+  },
+  "peerDependencies": {
+    "superpowers": "*"
+  },
+  "peerDependenciesMeta": {
+    "superpowers": {
+      "optional": true
+    }
   }
 }

package/src/cli/index.ts

@@ -40,6 +40,81 @@ if (args[0] === '--version' || args[0] === '-v') {
   process.exit(0);
 }
 
+// Help flag — route to help handler explicitly before subcommand defaulting.
+// Without this, `--help` falls through the "args[0].startsWith('--')" check below
+// and defaults to `run`, which is surprising and a v4 regression we preserve no longer.
+if (args[0] === '--help' || args[0] === '-h') {
+  args.unshift('help');
+  args.splice(1, 1); // remove the original --help/-h token
+}
+
+// Verb grouping (new in alpha.2): `claude-autopilot review <verb>` and
+// `claude-autopilot advanced <verb>` are dispatcher prefixes that route to the
+// same flat handlers. Legacy flat invocation (`claude-autopilot run`) is unchanged
+// — the grouped form is purely additive.
+//
+// Scope gates enforce that only the documented verb sets work under each prefix,
+// so `claude-autopilot review doctor` is rejected with a clear error instead of
+// silently routing to the doctor handler (which would confuse the mental model).
+const REVIEW_VERBS = new Set(['run', 'scan', 'ci', 'fix', 'baseline', 'explain', 'watch', 'report']);
+// `detector` is a library used by setup/run, not a CLI subcommand — leave it out.
+const ADVANCED_VERBS = new Set(['lsp', 'mcp', 'worker', 'autoregress', 'test-gen', 'hook', 'ignore']);
+if (args[0] === 'review') {
+  const sub = args[1];
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.log(`
+Usage: claude-autopilot review <verb> [options]
+
+Review-phase verbs:
+  run          Review git-changed files (default)
+  scan         Review any path — no git required
+  ci           Opinionated CI entrypoint (post comments + SARIF)
+  fix          Auto-fix cached findings using the configured LLM
+  baseline     Manage the committed findings baseline
+  explain      Deep-dive explanation + remediation for a specific finding
+  watch        Watch for file changes and re-run on each save
+  report       Render cached findings as a markdown report
+
+These are aliases for the flat subcommands — \`claude-autopilot run\` and
+\`claude-autopilot review run\` are equivalent.
+`);
+    process.exit(0);
+  }
+  if (!REVIEW_VERBS.has(sub)) {
+    console.error(`\x1b[31m[claude-autopilot] "${sub}" is not a review-phase verb.\x1b[0m`);
+    console.error(`\x1b[2m  Valid: ${[...REVIEW_VERBS].join(', ')}\x1b[0m`);
+    console.error(`\x1b[2m  Did you mean: claude-autopilot ${sub} ...?\x1b[0m`);
+    process.exit(1);
+  }
+  args.shift(); // drop 'review', leave the flat subcommand at args[0]
+}
+if (args[0] === 'advanced') {
+  const sub = args[1];
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.log(`
+Usage: claude-autopilot advanced <verb> [options]
+
+Advanced / niche verbs (hidden from top-level --help to keep it readable):
+  lsp          Language server — publishes findings as LSP diagnostics
+  mcp          MCP server for Claude / ChatGPT integration
+  worker       Persistent review daemon (start|stop|status)
+  autoregress  Snapshot regression tests
+  test-gen     Generate test cases for uncovered exports
+  hook         Install / remove the pre-push git hook
+  ignore       Edit the findings ignore list
+
+These are aliases for the flat subcommands; they still work without the 'advanced' prefix.
+`);
+    process.exit(0);
+  }
+  if (!ADVANCED_VERBS.has(sub)) {
+    console.error(`\x1b[31m[claude-autopilot] "${sub}" is not an advanced verb.\x1b[0m`);
+    console.error(`\x1b[2m  Valid: ${[...ADVANCED_VERBS].join(', ')}\x1b[0m`);
+    process.exit(1);
+  }
+  args.shift(); // drop 'advanced'
+}
+
 const SUBCOMMANDS = ['init', 'run', 'scan', 'report', 'explain', 'ignore', 'ci', 'pr', 'fix', 'costs', 'watch', 'hook', 'autoregress', 'baseline', 'triage', 'lsp', 'worker', 'mcp', 'test-gen', 'pr-desc', 'doctor', 'preflight', 'setup', 'council', 'help', '--help', '-h'] as const;
 const VALUE_FLAGS = ['base', 'config', 'files', 'format', 'output', 'debounce', 'ask', 'focus', 'fail-on', 'note', 'reason', 'expires', 'profile', 'severity', 'prompt', 'context-file'];
 
@@ -108,7 +183,15 @@ Commands:
   costs        Show per-run cost summary
   ci           Opinionated CI entrypoint (post comments + SARIF)
   init         Scaffold guardrail.config.yaml from a preset
+  setup        Auto-detect stack, write config, install pre-push hook
   doctor       Check prerequisites (alias: preflight)
+  preflight    Check prerequisites (alias: doctor)
+  hook         Install / remove the pre-push git hook
+  baseline     Manage the committed findings baseline (create|update|show|delete)
+  triage       Mark individual findings as accepted/dismissed
+  pr-desc      Generate a PR title / summary / test plan from the current diff
+  council      Multi-model review — dispatch the diff to N models and synthesize consensus
+  mcp          MCP server for Claude / ChatGPT integration
   autoregress  Snapshot regression tests (run|diff|update|generate)
   lsp          Language server — publishes findings as LSP diagnostics (stdin/stdout)
   worker       Persistent review daemon for multi-terminal parallel usage (start|stop|status)

package/src/cli/preflight.ts

@@ -22,6 +22,87 @@ export interface DoctorResult {
   warnings: number;
 }
 
+/**
+ * Checks that the superpowers plugin skills required by the pipeline are resolvable
+ * from the usual Claude Code plugin paths. Returns skill names that weren't found.
+ */
+const REQUIRED_SUPERPOWERS_SKILLS = [
+  'writing-plans',
+  'using-git-worktrees',
+  'subagent-driven-development',
+] as const;
+
+function skillRoots(): string[] {
+  const home = process.env.HOME || process.env.USERPROFILE || '';
+  const cwd = process.cwd();
+  const roots: string[] = [];
+  // Project-local plugin install
+  roots.push(path.join(cwd, '.claude', 'plugins'));
+  // User-global plugin install
+  if (home) roots.push(path.join(home, '.claude', 'plugins'));
+  return roots.filter(p => fs.existsSync(p));
+}
+
+export function findMissingSuperpowersSkills(): string[] {
+  // Traverse each root once, collect all discovered skill names, then diff against
+  // the required set. Previous implementation did N × roots separate recursive walks.
+  const discovered = new Set<string>();
+  const MAX_DIRS_PER_ROOT = 2000; // safety cap to prevent pathological plugin trees
+
+  for (const root of skillRoots()) {
+    collectSkills(root, discovered, { visited: { n: 0 }, max: MAX_DIRS_PER_ROOT });
+  }
+
+  return REQUIRED_SUPERPOWERS_SKILLS.filter(s => !discovered.has(s));
+}
+
+// Walks up to 8 levels deep, capped at `max` directories total. When it finds a
+// `skills/` directory, records every `<skill-name>/SKILL.md` and `<skill-name>.md`
+// entry directly into the Set. Never revisits by name (Claude Code plugin caches
+// can contain many parallel copies — we only care whether a skill exists *somewhere*).
+function collectSkills(
+  dir: string,
+  out: Set<string>,
+  ctx: { visited: { n: number }; max: number },
+  depth = 0,
+): void {
+  if (depth > 8) return;
+  if (ctx.visited.n >= ctx.max) return;
+  ctx.visited.n++;
+
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  // If this dir has a skills/ child, record every skill inside it
+  for (const entry of entries) {
+    if (entry.isDirectory() && entry.name === 'skills') {
+      const skillsDir = path.join(dir, 'skills');
+      try {
+        for (const skill of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+          if (skill.isDirectory() && fs.existsSync(path.join(skillsDir, skill.name, 'SKILL.md'))) {
+            out.add(skill.name);
+          } else if (skill.isFile() && skill.name.endsWith('.md') && skill.name !== 'README.md') {
+            out.add(skill.name.slice(0, -3)); // strip .md
+          }
+        }
+      } catch { /* ignore */ }
+    }
+  }
+
+  // Recurse into non-skills dirs (bounded depth + visit cap prevent pathological scans)
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (entry.name.startsWith('.')) continue;
+    if (entry.name === 'node_modules') continue;
+    if (entry.name === 'skills') continue; // already handled above
+    collectSkills(path.join(dir, entry.name), out, ctx, depth + 1);
+  }
+}
+
 export async function runDoctor(): Promise<DoctorResult> {
   const checks: Check[] = [];
 
@@ -106,6 +187,19 @@ export async function runDoctor(): Promise<DoctorResult> {
       : undefined,
   });
 
+  // 9. Superpowers plugin — required for pipeline phases, optional for review-only use
+  const missingSkills = findMissingSuperpowersSkills();
+  const allSkillsFound = missingSkills.length === 0;
+  checks.push({
+    name: `Superpowers plugin${allSkillsFound ? '' : ` (missing: ${missingSkills.join(', ')})`}`,
+    // Treat as warn, not fail — users who only run `claude-autopilot run` (review phase)
+    // don't need superpowers. Pipeline invocations (`autopilot` skill) will hard-fail at
+    // their own entry point.
+    result: allSkillsFound ? 'pass' : 'warn',
+    message: !allSkillsFound
+      ? 'Install: `claude plugin install superpowers` (required for pipeline phases — brainstorm/plan/implement)'
+      : undefined,
+  });
 
   // Print results
   console.log('\n\x1b[1m[doctor] Guardrail prerequisite check\x1b[0m\n');