claudenv 1.2.0 → 1.2.1

package/bin/cli.js

@@ -132,6 +132,7 @@ program
   .option('--allow-dirty', 'Allow running with uncommitted git changes')
   .option('--rollback', 'Undo all changes from the most recent loop run')
   .option('--unsafe', 'Remove default tool restrictions (allows rm -rf)')
+  .option('--worktree', 'Run each iteration in an isolated git worktree')
   .option('--profile <name>', 'Autonomy profile: safe, moderate, full, ci')
   .action(async (opts) => {
     // --- Rollback mode ---
@@ -170,6 +171,7 @@ program
 
     console.log(`  Directory: ${cwd}`);
     console.log(`  Mode: ${trust ? 'full trust (--dangerously-skip-permissions)' : 'interactive'}`);
+    if (opts.worktree) console.log(`  Worktree: enabled (each iteration in isolated worktree)`);
     if (opts.iterations) console.log(`  Max iterations: ${opts.iterations}`);
     if (opts.goal) console.log(`  Goal: ${opts.goal}`);
     if (opts.model) console.log(`  Model: ${opts.model}`);
@@ -187,6 +189,7 @@ program
       cwd,
       allowDirty: opts.allowDirty || false,
       unsafe: opts.unsafe || false,
+      worktree: opts.worktree || false,
       disallowedTools: profileDefaults.disallowedTools,
     });
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudenv",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "One command to integrate Claude Code into any project — installs /claudenv command for AI-powered documentation generation",
   "type": "module",
   "bin": {

package/scaffold/.claude/agents/hypothesis-tester.md

@@ -0,0 +1,22 @@
+---
+name: hypothesis-tester
+description: Tests implementation hypotheses in isolation. Use when exploring risky refactors, alternative approaches, or when the current approach might need rollback.
+tools: Read, Write, Edit, Glob, Grep, Bash
+model: sonnet
+---
+
+You are testing an implementation hypothesis in an isolated git worktree.
+
+## Your workflow
+1. Read the parent branch context (goal, constraints, current state)
+2. Implement the hypothesis
+3. Run tests to validate
+4. If tests pass — commit with descriptive message, report SUCCESS
+5. If tests fail — report FAILURE with analysis of why, do NOT commit broken code
+
+## Output format
+Report exactly one of:
+- `HYPOTHESIS_SUCCESS: <summary of what worked and why>`
+- `HYPOTHESIS_FAILURE: <summary of what failed and why>`
+
+The parent agent will decide whether to merge your worktree branch.

package/scaffold/.claude/agents/rollback-analyzer.md

@@ -0,0 +1,22 @@
+---
+name: rollback-analyzer
+description: Analyzes past hypothesis branches to understand what was tried and why it failed. Use before retrying a failed approach.
+tools: Read, Glob, Grep, Bash
+model: haiku
+---
+
+You analyze past hypothesis branches to help the parent agent avoid repeating mistakes.
+
+## Your workflow
+1. List branches: `git branch -l "claudenv/*"`
+2. For each relevant branch, show: `git log --oneline <parent>..claudenv/<name>`
+3. Read key changed files: `git diff <parent>...claudenv/<name> --stat`
+4. Summarize: what was tried, what failed, what can be learned
+
+## Output format
+For each hypothesis branch:
+- **Branch:** claudenv/<name>
+- **Goal:** <extracted from commit messages>
+- **Changes:** <file summary>
+- **Result:** SUCCESS/FAILURE
+- **Lesson:** <what to do differently>

package/src/index.js

@@ -7,3 +7,4 @@ export { runLoop, spawnClaude, checkClaudeCli } from './loop.js';
 export { AUTONOMY_PROFILES, getProfile, listProfiles, CREDENTIAL_PATHS } from './profiles.js';
 export { generateSettingsJson, generatePreToolUseHook, generateAuditLogHook, generateAliases, generateCIWorkflow } from './hooks-gen.js';
 export { generateAutonomyConfig, printSecuritySummary, getFullModeWarning } from './autonomy.js';
+export { createWorktree, removeWorktree, mergeWorktree, listHypotheses } from './worktree.js';

package/src/loop.js

@@ -2,6 +2,7 @@ import { execSync, spawn } from 'node:child_process';
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { select } from '@inquirer/prompts';
+import { createWorktree, removeWorktree, mergeWorktree, getCurrentBranch } from './worktree.js';
 
 // =============================================
 // Pre-flight: check Claude CLI
@@ -114,9 +115,42 @@ export function spawnClaude(prompt, options = {}) {
  * Build the planning prompt (iteration 0).
  */
 function buildPlanningPrompt(goal) {
-  const goalLine = goal ? `\nFocus area: ${goal}` : '';
+  if (goal) {
+    return `You are an expert software engineer. Your task: ${goal}
+
+## Instructions
+
+1. Analyze the current project state — read key files to understand what exists (README.md, CLAUDE.md, package.json, and important source files).
+2. Create an action plan in \`.claude/improvement-plan.md\` with the following format:
+
+\`\`\`markdown
+# Improvement Plan
+
+Generated by claudenv loop. Goal: ${goal}.
+
+## Pending
+
+### 1. [Title of step]
+- **Impact**: High/Medium/Low — [why]
+- **Difficulty**: High/Medium/Low
+- **Files**: [files to create or modify]
+
+### 2. [Title of step]
+- **Impact**: High/Medium/Low — [why]
+- **Difficulty**: High/Medium/Low
+- **Files**: [files to create or modify]
+
+## Completed
+\`\`\`
+
+3. Break the goal into concrete, sequential steps — each step should be implementable in a single iteration.
+4. The plan must directly serve the stated goal — do NOT add unrelated improvements.
+5. Include 5-10 actionable items.
+6. Do NOT implement anything yet — only create the plan.
+7. Commit the plan: \`git add .claude/improvement-plan.md && git commit -m "Add action plan for: ${goal}"\``;
+  }
+
   return `You are an expert software engineer analyzing this project to create an improvement plan.
-${goalLine}
 
 ## Instructions
 
@@ -134,7 +168,7 @@ ${goalLine}
 \`\`\`markdown
 # Improvement Plan
 
-Generated by claudenv loop. Goal: ${goal || 'General improvement'}.
+Generated by claudenv loop. Goal: General improvement.
 
 ## Pending
 
@@ -163,15 +197,21 @@ Generated by claudenv loop. Goal: ${goal || 'General improvement'}.
 function buildExecutionPrompt(iteration, maxIterations, goal) {
   const maxLine = maxIterations ? ` (iteration ${iteration} of ${maxIterations})` : ` (iteration ${iteration})`;
   const goalLine = goal ? `\nGoal: ${goal}` : '';
-  return `You are an expert software engineer making improvements to this project.${maxLine}
+  const goalRules = goal
+    ? `
+- Implement REAL changes — write code, create files, build features
+- Do NOT limit yourself to documentation or analysis — the goal requires working software`
+    : '';
+  return `You are an expert software engineer working on this project.${maxLine}
 ${goalLine}
 
 ## Instructions
 
 1. Read \`.claude/improvement-plan.md\`
 2. Pick the top unfinished item from the "## Pending" section
-3. Implement it:
+3. Implement it fully:
    - Write the code changes
+   - Create new files as needed
    - Add or update tests if applicable
    - Run tests to verify nothing is broken
 4. Update \`.claude/improvement-plan.md\`:
@@ -182,7 +222,7 @@ ${goalLine}
 6. Report what you did in a brief summary
 
 ## Important rules
-
+${goalRules}
 - Do NOT delete files unless the deletion IS the improvement itself
 - Do NOT make changes beyond the single item you picked
 - If the "## Pending" section is empty or all items are done, output exactly: NO_MORE_IMPROVEMENTS
@@ -329,6 +369,12 @@ function printFinalSummary(log) {
     const lastSession = log.iterations[log.iterations.length - 1].sessionId;
     if (lastSession) console.log(`  Session ID: ${lastSession} (use --resume in Claude Code)`);
   }
+  if (log.hypotheses && log.hypotheses.length > 0) {
+    console.log('\n  Hypothesis branches:');
+    for (const h of log.hypotheses) {
+      console.log(`    ${h.status === 'merged' ? '+' : h.status === 'failed' ? '!' : '~'} ${h.branch} [${h.status}] (iteration ${h.iteration})`);
+    }
+  }
   console.log(`\n  To undo all changes: claudenv loop --rollback`);
   console.log('  ═══════════════════════════════════\n');
 }
@@ -350,6 +396,7 @@ function printFinalSummary(log) {
  * @param {number} [options.budget] - Budget cap per iteration
  * @param {string} [options.cwd] - Working directory
  * @param {boolean} [options.allowDirty] - Allow dirty git state
+ * @param {boolean} [options.worktree] - Run each iteration in an isolated git worktree
  */
 export async function runLoop(options = {}) {
   const cwd = options.cwd || process.cwd();
@@ -391,6 +438,7 @@ export async function runLoop(options = {}) {
     completedAt: null,
     stopReason: null,
     totalIterations: 0,
+    hypotheses: [],
   };
 
   // --- Shared spawn options ---
@@ -484,22 +532,103 @@ export async function runLoop(options = {}) {
         // 'goal' and 'continue' both continue
       }
 
-      console.log(`\n  Starting iteration ${i}${maxIterations < Infinity ? ` of ${maxIterations}` : ''}...\n`);
+      const worktreeMode = options.worktree || false;
+      console.log(`\n  Starting iteration ${i}${maxIterations < Infinity ? ` of ${maxIterations}` : ''}${worktreeMode ? ' (worktree)' : ''}...\n`);
 
       const startedAt = new Date().toISOString();
       const execPrompt = buildExecutionPrompt(i, maxIterations < Infinity ? maxIterations : null, options.goal);
 
+      // --- Worktree mode: run iteration in isolated worktree ---
+      let iterCwd = cwd;
+      let worktreeInfo = null;
+      if (worktreeMode) {
+        try {
+          worktreeInfo = await createWorktree(cwd, null, { goal: options.goal });
+          iterCwd = worktreeInfo.path;
+          console.log(`  Worktree: ${worktreeInfo.branch} → ${worktreeInfo.path}`);
+        } catch (err) {
+          console.error(`\n  Failed to create worktree: ${err.message}`);
+          log.stopReason = 'error';
+          break;
+        }
+      }
+
       let iterResult;
       try {
-        iterResult = await spawnClaude(execPrompt, { ...spawnOpts, sessionId });
+        iterResult = await spawnClaude(execPrompt, { ...spawnOpts, cwd: iterCwd, sessionId });
       } catch (err) {
         console.error(`\n  Iteration ${i} failed: ${err.message}`);
+        // In worktree mode, clean up the worktree on failure
+        if (worktreeInfo) {
+          try {
+            removeWorktree(cwd, worktreeInfo.name);
+          } catch { /* ignore cleanup errors */ }
+          log.hypotheses.push({
+            name: worktreeInfo.name,
+            branch: worktreeInfo.branch,
+            status: 'failed',
+            iteration: i,
+          });
+        }
         log.stopReason = 'error';
         break;
       }
 
       sessionId = iterResult.sessionId || sessionId;
 
+      // --- Worktree mode: merge or discard ---
+      if (worktreeMode && worktreeInfo) {
+        const isSuccess = !detectConvergence(iterResult.result);
+        const hasCommits = (() => {
+          try {
+            const diff = execSync(`git log ${getCurrentBranch(cwd)}..${worktreeInfo.branch} --oneline`, {
+              cwd,
+              encoding: 'utf-8',
+            }).trim();
+            return diff !== '';
+          } catch {
+            return false;
+          }
+        })();
+
+        if (hasCommits && isSuccess) {
+          try {
+            mergeWorktree(cwd, worktreeInfo.name);
+            console.log(`  Worktree merged: ${worktreeInfo.branch}`);
+            log.hypotheses.push({
+              name: worktreeInfo.name,
+              branch: worktreeInfo.branch,
+              status: 'merged',
+              iteration: i,
+            });
+          } catch (err) {
+            console.error(`  Merge failed: ${err.message}`);
+            log.hypotheses.push({
+              name: worktreeInfo.name,
+              branch: worktreeInfo.branch,
+              status: 'conflict',
+              iteration: i,
+            });
+          }
+        } else {
+          // No commits or convergence — discard worktree, keep branch
+          try {
+            removeWorktree(cwd, worktreeInfo.name);
+          } catch { /* ignore */ }
+          log.hypotheses.push({
+            name: worktreeInfo.name,
+            branch: worktreeInfo.branch,
+            status: hasCommits ? 'discarded' : 'empty',
+            iteration: i,
+          });
+          if (!hasCommits) {
+            console.log(`  Worktree discarded (no changes): ${worktreeInfo.branch}`);
+          } else {
+            console.log(`  Worktree discarded (converged): ${worktreeInfo.branch}`);
+          }
+        }
+      }
+
       const iteration = {
         number: i,
         startedAt,
@@ -610,8 +739,23 @@ export async function rollback(options = {}) {
     }
   }
 
+  // Clean up worktrees if any (keep branches for reference)
+  if (log && log.hypotheses && log.hypotheses.length > 0) {
+    console.log('  Cleaning up worktrees...');
+    for (const h of log.hypotheses) {
+      try {
+        removeWorktree(cwd, h.name);
+      } catch { /* worktree may already be removed */ }
+    }
+  }
+
   execSync(`git reset --hard ${tag}`, { cwd, stdio: 'inherit' });
   execSync(`git tag -d ${tag}`, { cwd, stdio: 'inherit' });
 
-  console.log('\n  Rollback complete. All loop changes have been undone.\n');
+  console.log('\n  Rollback complete. All loop changes have been undone.');
+  if (log && log.hypotheses && log.hypotheses.length > 0) {
+    console.log('  Hypothesis branches preserved — use `git branch -l "claudenv/*"` to list them.\n');
+  } else {
+    console.log();
+  }
 }

package/src/worktree.js

@@ -0,0 +1,189 @@
+import { execSync } from 'node:child_process';
+import { readFile, writeFile, access } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// =============================================
+// Constants
+// =============================================
+
+const WORKTREE_DIR = '.worktrees';
+const BRANCH_PREFIX = 'claudenv';
+
+// =============================================
+// Path helpers
+// =============================================
+
+/**
+ * Get the worktree directory path for a given name.
+ * @param {string} cwd - Working directory
+ * @param {string} name - Worktree name
+ * @returns {string} Absolute path to .worktrees/<name>
+ */
+export function getWorktreePath(cwd, name) {
+  return join(cwd, WORKTREE_DIR, name);
+}
+
+/**
+ * Get the branch name for a worktree.
+ * @param {string} name - Worktree name
+ * @returns {string} Branch name claudenv/<name>
+ */
+export function getBranchName(name) {
+  return `${BRANCH_PREFIX}/${name}`;
+}
+
+/**
+ * Generate an auto-name based on current timestamp.
+ * @returns {string} hypothesis-YYYY-MM-DD-HHMM
+ */
+export function generateWorktreeName() {
+  const now = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `hypothesis-${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}`;
+}
+
+/**
+ * Get the current branch name.
+ * @param {string} cwd - Working directory
+ * @returns {string} Current branch name
+ */
+export function getCurrentBranch(cwd) {
+  return execSync('git rev-parse --abbrev-ref HEAD', { cwd, encoding: 'utf-8' }).trim();
+}
+
+// =============================================
+// Gitignore management
+// =============================================
+
+/**
+ * Ensure .worktrees/ is in .gitignore. Idempotent.
+ * @param {string} cwd - Working directory
+ */
+export async function ensureGitignore(cwd) {
+  const gitignorePath = join(cwd, '.gitignore');
+  const entry = `${WORKTREE_DIR}/`;
+
+  let content = '';
+  try {
+    content = await readFile(gitignorePath, 'utf-8');
+  } catch {
+    // .gitignore doesn't exist yet
+  }
+
+  // Check if already present (exact line match)
+  const lines = content.split('\n');
+  if (lines.some((line) => line.trim() === entry)) {
+    return;
+  }
+
+  // Append entry
+  const separator = content && !content.endsWith('\n') ? '\n' : '';
+  await writeFile(gitignorePath, content + separator + entry + '\n');
+}
+
+// =============================================
+// Worktree operations
+// =============================================
+
+/**
+ * Create a new git worktree with a dedicated branch.
+ *
+ * @param {string} cwd - Working directory (main repo)
+ * @param {string} [name] - Worktree name (auto-generated if omitted)
+ * @param {object} [options]
+ * @param {string} [options.goal] - Goal description (used in branch commit message)
+ * @returns {{ name: string, path: string, branch: string }}
+ */
+export async function createWorktree(cwd, name, options = {}) {
+  if (!name) {
+    name = generateWorktreeName();
+  }
+
+  const worktreePath = getWorktreePath(cwd, name);
+  const branch = getBranchName(name);
+
+  // Ensure .worktrees/ is gitignored
+  await ensureGitignore(cwd);
+
+  // Create worktree with new branch
+  execSync(`git worktree add -b "${branch}" "${worktreePath}"`, {
+    cwd,
+    stdio: 'pipe',
+  });
+
+  return { name, path: worktreePath, branch };
+}
+
+/**
+ * Remove a worktree but keep the branch for reference.
+ *
+ * @param {string} cwd - Working directory (main repo)
+ * @param {string} name - Worktree name
+ */
+export function removeWorktree(cwd, name) {
+  const worktreePath = getWorktreePath(cwd, name);
+
+  execSync(`git worktree remove "${worktreePath}" --force`, {
+    cwd,
+    stdio: 'pipe',
+  });
+}
+
+/**
+ * Merge a worktree branch back into the current branch with --no-ff.
+ *
+ * @param {string} cwd - Working directory (main repo)
+ * @param {string} name - Worktree name
+ * @param {object} [options]
+ * @param {string} [options.message] - Custom merge commit message
+ * @returns {{ merged: boolean, branch: string }}
+ * @throws {Error} On merge conflict
+ */
+export function mergeWorktree(cwd, name, options = {}) {
+  const branch = getBranchName(name);
+  const message = options.message || `Merge hypothesis: ${name}`;
+
+  // Remove worktree first (must be done before merge)
+  removeWorktree(cwd, name);
+
+  try {
+    execSync(`git merge --no-ff "${branch}" -m "${message}"`, {
+      cwd,
+      stdio: 'pipe',
+    });
+  } catch (err) {
+    // Abort the merge on conflict
+    try {
+      execSync('git merge --abort', { cwd, stdio: 'pipe' });
+    } catch {
+      // merge --abort may fail if there's nothing to abort
+    }
+    throw new Error(`Merge conflict when merging ${branch}. Branch preserved for manual resolution.`);
+  }
+
+  return { merged: true, branch };
+}
+
+/**
+ * List all hypothesis branches (claudenv/*).
+ *
+ * @param {string} cwd - Working directory
+ * @returns {string[]} Branch names
+ */
+export function listHypotheses(cwd) {
+  try {
+    const output = execSync(`git branch -l "${BRANCH_PREFIX}/*"`, {
+      cwd,
+      encoding: 'utf-8',
+    }).trim();
+
+    if (!output) return [];
+
+    return output
+      .split('\n')
+      .map((line) => line.trim().replace(/^[*+]\s*/, ''))
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/templates/rules-workflow.ejs

@@ -28,6 +28,13 @@ paths:
 - Update `_state.md` when making significant architectural decisions
 - Review `_state.md` at the start of each session to restore context
 
+## Worktree Safety
+- For risky changes or alternative approaches, spawn `hypothesis-tester` subagent — it runs in an isolated git worktree
+- If a hypothesis fails, the worktree is discarded without affecting the main branch
+- Before retrying a failed approach, spawn `rollback-analyzer` to review past hypothesis branches
+- Past hypotheses are preserved as `claudenv/*` branches for reference
+- Use `git branch -l "claudenv/*"` to see all hypothesis branches
+
 ## Commits and Git
 - NEVER commit unless the user explicitly asks
 - NEVER push to remote without explicit permission

package/scaffold/global/.claude/commands/improve.md

@@ -1,60 +0,0 @@
----
-description: Analyze this project and make one high-impact improvement — fix bugs, add tests, improve code quality
-allowed-tools: Read, Write, Glob, Grep, Bash
-argument-hint: [area-to-improve]
----
-
-# /improve — Single Improvement Iteration
-
-You are an expert software engineer. Your job is to analyze this project and make one high-impact improvement.
-
-## Step 1: Read Context
-
-Read these files if they exist:
-- `CLAUDE.md` — project overview and conventions
-- `_state.md` — session memory
-- `.claude/improvement-plan.md` — existing improvement plan (if any)
-
-## Step 2: Choose What to Improve
-
-**If `.claude/improvement-plan.md` exists:**
-- Read the plan and pick the top unfinished item from the "## Pending" section
-- If `$ARGUMENTS` is provided, use it as a focus area instead of the plan
-
-**If no plan exists:**
-- Analyze the project: read manifest files, scan source code, check test coverage
-- If `$ARGUMENTS` is provided, focus on that area
-- Identify the single highest-impact improvement you can make
-
-## Step 3: Implement the Change
-
-- Write the code changes
-- Add or update tests if applicable
-- Follow existing code style and conventions
-
-## Step 4: Verify
-
-- Run tests (if a test command is available)
-- Run linter (if configured)
-- Fix any issues found
-
-## Step 5: Update Plan
-
-If `.claude/improvement-plan.md` exists:
-- Move the completed item from "## Pending" to "## Completed"
-- Add the commit hash and notes about what was done
-- If you discovered new issues, add them to "## Pending"
-
-## Step 6: Commit and Report
-
-- Commit all changes with a descriptive message
-- Report:
-  - What you changed and why
-  - What tests were added/updated
-  - What's next (remaining plan items or suggested improvements)
-
-## Important Rules
-
-- Do NOT delete files unless the deletion IS the improvement
-- Make exactly ONE improvement per invocation
-- If there's nothing left to improve, output: NO_MORE_IMPROVEMENTS

package/scaffold/global/.claude/commands/setup-mcp.md

@@ -1,115 +0,0 @@
----
-description: Recommend and configure MCP servers based on project analysis
-allowed-tools: Read, Write, Glob, Grep, Bash(curl:*), Bash(find:*), Bash(cat:*)
-disable-model-invocation: true
-argument-hint: [--force]
----
-
-# MCP Server Setup
-
-You are configuring MCP servers for this project. Analyze the tech stack, search the official MCP Registry, verify trust signals, and generate `.mcp.json`.
-
-## Step 1: Analyze the Project
-
-Understand what this project uses:
-
-**Read existing documentation:**
-- Read CLAUDE.md if it exists — it contains the tech stack summary
-- Read _state.md if it exists
-
-**Check for existing MCP config:**
-- Read `.mcp.json` if it exists — you will merge new entries, not overwrite
-
-**Scan manifest files:**
-!`find . -maxdepth 3 \( -name "package.json" -o -name "pyproject.toml" -o -name "go.mod" -o -name "Cargo.toml" -o -name "Gemfile" -o -name "composer.json" -o -name "requirements.txt" \) -not -path "*/node_modules/*" -not -path "*/.venv/*" -not -path "*/vendor/*" 2>/dev/null | head -20`
-
-**Scan framework and tooling configs:**
-!`find . -maxdepth 2 \( -name "tsconfig*.json" -o -name "next.config.*" -o -name "vite.config.*" -o -name "docker-compose.*" -o -name "Dockerfile" -o -name ".env*" -o -name "prisma" -o -name "drizzle.config.*" \) -not -path "*/node_modules/*" 2>/dev/null | head -20`
-
-Read the manifest files you found. Identify:
-- Programming languages and frameworks
-- Databases (PostgreSQL, MongoDB, Redis, etc.)
-- Cloud services (AWS, GCP, Azure)
-- External APIs (Stripe, Sentry, etc.)
-- Dev tools (Docker, GitHub Actions, etc.)
-
-## Step 2: Search the MCP Registry
-
-Read the MCP server reference for search and evaluation guidance:
-@~/.claude/skills/claudenv/templates/mcp-servers.md
-
-For each major technology in the project, search the official MCP Registry API:
-```bash
-curl -s 'https://registry.modelcontextprotocol.io/v0.1/servers?search=<tech>&version=latest&limit=10'
-```
-
-For each candidate server with an npm package, verify trust by checking monthly downloads:
-```bash
-curl -s 'https://api.npmjs.org/downloads/point/last-month/<npm-package>'
-```
-
-Optionally check GitHub stars for additional trust signal:
-```bash
-curl -s 'https://api.github.com/repos/<owner>/<repo>'
-```
-
-**Filtering rules:**
-- Remove servers with <100 monthly npm downloads
-- Rank by: npm downloads (primary) + GitHub stars (secondary) + description relevance
-- When multiple servers exist for the same technology, pick the one with the highest downloads
-
-## Step 3: Present Recommendations
-
-Group your recommendations into three tiers:
-
-**Essential** — servers that directly support the project's core technologies (e.g., PostgreSQL server for a project using PostgreSQL)
-
-**Recommended** — servers that enhance the development workflow (e.g., Context7 for library docs, GitHub for repo management)
-
-**Optional** — servers that could be useful but aren't critical (e.g., Fetch for web content, Docker if Docker is used occasionally)
-
-For each recommendation, explain:
-- **What it does** and why it's relevant to THIS project
-- **Monthly npm downloads** (trust signal)
-- **Environment variables required** and whether they need secrets
-
-Ask the user which servers to configure.
-
-If `$ARGUMENTS` includes `--force`, auto-select all Essential and Recommended servers.
-
-## Step 4: Generate .mcp.json
-
-Build the `.mcp.json` file with the selected servers following the format in the MCP server reference.
-
-**If `.mcp.json` already exists:**
-- Read it and parse the existing `mcpServers` entries
-- Merge new servers into the existing config — do NOT remove or overwrite existing entries
-- If a server key already exists, skip it (preserve the user's existing config)
-
-**Key rules:**
-- Use `${ENV_VAR}` placeholders for ALL secret environment variables — NEVER literal values
-- Non-secret env vars can use literal values when appropriate
-- Use `npx -y <package>@latest` for stdio/npm servers
-- Use the `type` and `url` from remotes for HTTP/SSE servers
-
-Write the `.mcp.json` file.
-
-## Step 5: Update CLAUDE.md
-
-If CLAUDE.md exists, add or update an `## MCP Servers` section listing the configured servers and what they do. Keep it concise — one line per server.
-
-If CLAUDE.md doesn't exist, skip this step and suggest running `/claudenv` first.
-
-## Step 6: Environment Variables
-
-List all required environment variables and how to configure them:
-
-```
-To configure secrets, run:
-  claude config set env.VAR_NAME "your-value"
-
-Required environment variables:
-  VAR_NAME — Description of what this is and where to get it
-```
-
-Remind the user that `.mcp.json` is safe to commit — it only contains placeholders, not actual secrets.