claudenv 1.0.2 → 1.2.0

package/README.md

@@ -27,15 +27,18 @@ Claude AI will:
 2. Detect your tech stack, frameworks, and tooling
 3. Ask you about the project (description, deployment, conventions)
 4. Generate all documentation files
-5. Install slash commands for ongoing maintenance
+5. Search the [MCP Registry](https://registry.modelcontextprotocol.io) and configure MCP servers
+6. Install slash commands for ongoing maintenance
 
-**Step 3.** You now have three commands available in Claude Code:
+You now have five commands available in Claude Code:
 
 | Command | What it does |
 |---------|-------------|
 | `/init-docs` | Regenerate documentation from scratch |
 | `/update-docs` | Scan for changes and propose updates |
 | `/validate-docs` | Check that documentation is complete and correct |
+| `/setup-mcp` | Recommend and configure MCP servers |
+| `/improve` | Analyze and make one improvement |
 
 ## What Gets Generated
 
@@ -43,6 +46,7 @@ Claude AI will:
 your-project/
 ├── CLAUDE.md                              # Project overview, commands, architecture
 ├── _state.md                              # Session memory (decisions, focus, issues)
+├── .mcp.json                              # MCP server configuration
 └── .claude/
     ├── rules/
     │   ├── code-style.md                  # Coding conventions (scoped by file paths)
@@ -52,7 +56,9 @@ your-project/
     ├── commands/
     │   ├── init-docs.md                   # /init-docs
     │   ├── update-docs.md                 # /update-docs
-    │   └── validate-docs.md              # /validate-docs
+    │   ├── validate-docs.md              # /validate-docs
+    │   ├── setup-mcp.md                  # /setup-mcp
+    │   └── improve.md                    # /improve
     ├── skills/
     │   └── doc-generator/                 # Auto-triggers when docs need updating
     └── agents/
@@ -68,6 +74,145 @@ your-project/
 | `.claude/rules/workflow.md` | Best practices: plan mode, `/compact`, subagents, git discipline |
 | `.claude/rules/code-style.md` | Language and framework-specific coding conventions |
 | `.claude/rules/testing.md` | Test framework patterns and commands |
+| `.mcp.json` | MCP server configuration with `${ENV_VAR}` placeholders |
+
+## MCP Server Recommendations
+
+`/claudenv` automatically recommends MCP servers based on your tech stack. You can also run `/setup-mcp` independently at any time.
+
+**How it works:**
+
+1. Claude analyzes your project's dependencies, databases, cloud services, and tools
+2. Searches the [official MCP Registry](https://registry.modelcontextprotocol.io) for matching servers
+3. Verifies trust via npm download counts (filters out servers with <100 monthly downloads)
+4. Presents recommendations grouped as **Essential** / **Recommended** / **Optional**
+5. Generates `.mcp.json` with selected servers
+
+**Example output** (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"],
+      "env": {}
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres@latest", "${POSTGRES_CONNECTION_STRING}"],
+      "env": {}
+    }
+  }
+}
+```
+
+Secrets use `${ENV_VAR}` placeholders — configure them with:
+
+```bash
+claude config set env.POSTGRES_CONNECTION_STRING "postgresql://..."
+```
+
+`.mcp.json` is safe to commit — it never contains actual secrets.
+
+Run `/setup-mcp --force` to auto-select Essential + Recommended servers without prompting.
+
+## Iterative Improvement Loop
+
+`claudenv loop` spawns Claude Code in headless mode to analyze and improve your project iteratively. Each run creates a git safety tag so you can always rollback.
+
+**How it works:**
+
+1. **Planning** (iteration 0) — Claude analyzes the project and generates `.claude/improvement-plan.md` with prioritized hypotheses
+2. **Execution** (iterations 1-N) — each iteration picks the top unfinished item from the plan, implements it, runs tests, and commits
+3. **Convergence** — the loop stops when the plan is complete, max iterations are reached, or the loop detects it's stuck
+
+**Usage:**
+
+```bash
+claudenv loop                              # Interactive, pauses between iterations
+claudenv loop --trust                      # Full trust, no pauses, no permission prompts
+claudenv loop --trust -n 5                 # 5 iterations in full trust
+claudenv loop --goal "add test coverage"   # Focused improvement
+claudenv loop --trust --model opus -n 3    # Use Opus, 3 iterations
+claudenv loop --budget 1.00 -n 10          # Budget cap per iteration
+claudenv loop --rollback                   # Undo all loop changes
+```
+
+| Flag | Description |
+|------|-------------|
+| `-n, --iterations <n>` | Max iterations (default: unlimited) |
+| `--trust` | Full trust mode — no pauses, skip permission prompts |
+| `--goal <text>` | Focus area for improvements |
+| `--profile <name>` | Autonomy profile: safe, moderate, full, ci |
+| `--no-pause` | Don't pause between iterations |
+| `--max-turns <n>` | Max agentic turns per iteration (default: 30) |
+| `--model <model>` | Model to use (default: sonnet) |
+| `--budget <usd>` | Budget cap per iteration in USD |
+| `-d, --dir <path>` | Target project directory |
+| `--allow-dirty` | Allow running with uncommitted changes |
+| `--rollback` | Undo all changes from the most recent loop |
+| `--unsafe` | Remove default tool restrictions |
+
+**Git safety:** Before the first iteration, a `claudenv-loop-<timestamp>` git tag is created. Each iteration commits separately. Use `claudenv loop --rollback` to reset everything, or cherry-pick individual commits.
+
+**Single iteration:** Use `/improve` inside Claude Code for a one-shot improvement without the full loop.
+
+## Autonomous Agent Mode
+
+`claudenv autonomy` configures Claude Code for autonomous operation with predefined security profiles. Inspired by [trailofbits/claude-code-config](https://github.com/trailofbits/claude-code-config).
+
+**Usage:**
+
+```bash
+claudenv autonomy                          # Interactive profile selection
+claudenv autonomy --profile moderate       # Non-interactive, writes files directly
+claudenv autonomy --profile moderate -y    # Same — -y only needed for profile selection
+claudenv autonomy --profile ci --dry-run   # Preview generated files
+claudenv autonomy --profile full           # Full autonomy — requires typing "full" to confirm
+claudenv autonomy --profile full --yes     # Full autonomy, skip confirmation
+```
+
+### Profiles
+
+| Profile | Description | Permissions | Credentials |
+|---------|-------------|-------------|-------------|
+| `safe` | Read-only + limited bash | Allow-list only | Blocked |
+| `moderate` | Full dev with deny-list | Allow + deny lists | Blocked |
+| `full` | Unrestricted + audit logging | `--dangerously-skip-permissions` | Warn-only |
+| `ci` | Headless CI/CD (50 turns, $5 budget) | `--dangerously-skip-permissions` | Warn-only |
+
+All profiles hard-block `rm -rf`, force push to main/master, and `sudo`.
+
+### Generated files
+
+```
+.claude/
+├── settings.json               # Permissions + hooks config
+├── hooks/
+│   ├── pre-tool-use.sh         # PreToolUse guard (blocks dangerous ops)
+│   └── audit-log.sh            # PostToolUse audit → audit-log.jsonl
+└── aliases.sh                  # Shell aliases: claude-safe, claude-yolo, claude-ci, claude-local
+```
+
+CI profile also generates `.github/workflows/claude-ci.yml`.
+
+### Loop integration
+
+Use `--profile` with `claudenv loop` to apply profile settings:
+
+```bash
+claudenv loop --profile moderate --goal "add types"   # Uses profile's deny-list
+claudenv loop --profile ci -n 5                       # CI defaults: 50 turns, $5 budget
+```
+
+| Flag | Description |
+|------|-------------|
+| `-p, --profile <name>` | Profile: safe, moderate, full, ci |
+| `-d, --dir <path>` | Project directory (default: `.`) |
+| `--overwrite` | Overwrite existing files |
+| `-y, --yes` | Skip prompts |
+| `--dry-run` | Preview without writing |
 
 ## Tech Stack Detection
 
@@ -83,14 +228,21 @@ Claude AI reads your actual code, but the following are auto-detected for contex
 ## CLI Reference
 
 ```
-claudenv                Install /claudenv into ~/.claude/ (default)
-claudenv install        Same as above (explicit)
-claudenv install -f     Reinstall, overwriting existing files
-claudenv uninstall      Remove /claudenv from ~/.claude/
-claudenv init [dir]     Legacy: static analysis + terminal prompts (no AI)
-claudenv init -y        Legacy: skip prompts, auto-detect everything
-claudenv generate       Templates only, no scaffold
-claudenv validate       Check documentation completeness
+claudenv                  Install /claudenv into ~/.claude/ (default)
+claudenv install          Same as above (explicit)
+claudenv install -f       Reinstall, overwriting existing files
+claudenv uninstall        Remove /claudenv from ~/.claude/
+claudenv init [dir]       Legacy: static analysis + terminal prompts (no AI)
+claudenv init -y          Legacy: skip prompts, auto-detect everything
+claudenv generate         Templates only, no scaffold
+claudenv validate         Check documentation completeness
+claudenv loop             Iterative improvement loop (spawns Claude)
+claudenv loop --trust     Full trust mode, no pauses
+claudenv loop --profile moderate  Use autonomy profile in loop
+claudenv loop --rollback  Undo all loop changes
+claudenv autonomy         Configure autonomous agent mode (interactive)
+claudenv autonomy -p moderate     Apply moderate profile
+claudenv autonomy -p ci --dry-run Preview CI config without writing
 ```
 
 ## Alternative: Run Without Installing

package/bin/cli.js

@@ -2,7 +2,7 @@
 
 import { Command } from 'commander';
 import { resolve, join } from 'node:path';
-import { readFile } from 'node:fs/promises';
+import { readFile, chmod } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
 import { detectTechStack } from '../src/detector.js';
@@ -10,6 +10,9 @@ import { generateDocs, writeDocs, installScaffold } from '../src/generator.js';
 import { validateClaudeMd, validateStructure, crossReferenceCheck } from '../src/validator.js';
 import { runExistingProjectFlow, runColdStartFlow, buildDefaultConfig } from '../src/prompts.js';
 import { installGlobal, uninstallGlobal } from '../src/installer.js';
+import { runLoop, rollback, checkClaudeCli } from '../src/loop.js';
+import { generateAutonomyConfig, printSecuritySummary, getFullModeWarning } from '../src/autonomy.js';
+import { getProfile, listProfiles } from '../src/profiles.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkgJson = JSON.parse(await readFile(join(__dirname, '..', 'package.json'), 'utf-8'));
@@ -113,6 +116,92 @@ program
     }
   });
 
+// --- loop ---
+program
+  .command('loop')
+  .description('Iterative improvement loop — spawn Claude to analyze and improve the project')
+  .option('-n, --iterations <n>', 'Max iterations (default: unlimited)', parseInt)
+  .option('--trust', 'Full trust mode — no pauses, no permission prompts')
+  .option('--goal <text>', 'Focus area for improvements')
+  .option('--pause', 'Pause between iterations (default: on unless --trust)')
+  .option('--no-pause', 'Do not pause between iterations')
+  .option('--max-turns <n>', 'Max agentic turns per iteration (default: 30)', parseInt)
+  .option('--model <model>', 'Model to use (default: sonnet)')
+  .option('--budget <usd>', 'Budget cap per iteration in USD', parseFloat)
+  .option('-d, --dir <path>', 'Target project directory')
+  .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('--profile <name>', 'Autonomy profile: safe, moderate, full, ci')
+  .action(async (opts) => {
+    // --- Rollback mode ---
+    if (opts.rollback) {
+      await rollback({ cwd: opts.dir ? resolve(opts.dir) : process.cwd() });
+      return;
+    }
+
+    // --- Pre-flight: check Claude CLI ---
+    const cli = checkClaudeCli();
+    if (!cli.installed) {
+      console.error('\n  Error: Claude CLI not found.');
+      console.error('  Install it from https://docs.anthropic.com/en/docs/claude-code\n');
+      process.exit(1);
+    }
+    console.log(`\n  claudenv loop v${pkgJson.version}`);
+    console.log(`  Claude CLI: ${cli.version}`);
+
+    // --- Load profile if specified ---
+    let profileDefaults = {};
+    if (opts.profile) {
+      const profile = getProfile(opts.profile);
+      profileDefaults = {
+        trust: profile.skipPermissions,
+        disallowedTools: profile.disallowedTools,
+        maxTurns: profile.maxTurns,
+        budget: profile.maxBudget,
+      };
+      console.log(`  Profile: ${profile.name} — ${profile.description}`);
+    }
+
+    // --- Config summary ---
+    const cwd = opts.dir ? resolve(opts.dir) : process.cwd();
+    const trust = opts.trust || profileDefaults.trust || false;
+    const pause = opts.pause !== undefined ? opts.pause : !trust;
+
+    console.log(`  Directory: ${cwd}`);
+    console.log(`  Mode: ${trust ? 'full trust (--dangerously-skip-permissions)' : 'interactive'}`);
+    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}`);
+    if (opts.budget || profileDefaults.budget) console.log(`  Budget: $${opts.budget || profileDefaults.budget}/iteration`);
+    if (opts.maxTurns || profileDefaults.maxTurns) console.log(`  Max turns: ${opts.maxTurns || profileDefaults.maxTurns}`);
+
+    await runLoop({
+      iterations: opts.iterations,
+      trust,
+      goal: opts.goal,
+      pause,
+      maxTurns: opts.maxTurns || profileDefaults.maxTurns || 30,
+      model: opts.model,
+      budget: opts.budget || profileDefaults.budget,
+      cwd,
+      allowDirty: opts.allowDirty || false,
+      unsafe: opts.unsafe || false,
+      disallowedTools: profileDefaults.disallowedTools,
+    });
+  });
+
+// --- autonomy ---
+program
+  .command('autonomy')
+  .description('Configure autonomous agent mode with safety guardrails')
+  .option('-p, --profile <name>', 'Profile: safe, moderate, full, ci')
+  .option('-d, --dir <path>', 'Project directory', '.')
+  .option('--overwrite', 'Overwrite existing files')
+  .option('-y, --yes', 'Skip prompts')
+  .option('--dry-run', 'Preview without writing')
+  .action(runAutonomy);
+
 // =============================================
 // Install / Uninstall
 // =============================================
@@ -263,4 +352,81 @@ function printValidation(label, result) {
   }
 }
 
+// =============================================
+// Autonomy
+// =============================================
+async function runAutonomy(opts) {
+  const { select, input } = await import('@inquirer/prompts');
+  const projectDir = resolve(opts.dir);
+
+  console.log(`\n  claudenv autonomy v${pkgJson.version}\n`);
+
+  // --- Profile selection ---
+  let profileName = opts.profile;
+  if (!profileName && !opts.yes) {
+    const profiles = listProfiles();
+    profileName = await select({
+      message: 'Select autonomy profile:',
+      choices: profiles.map((p) => ({
+        name: `${p.name} — ${p.description}`,
+        value: p.name,
+      })),
+    });
+  } else if (!profileName) {
+    profileName = 'moderate';
+  }
+
+  // --- Full mode confirmation ---
+  if (profileName === 'full') {
+    console.log(getFullModeWarning());
+    if (!opts.yes) {
+      const confirm = await input({ message: 'Type "full" to confirm:' });
+      if (confirm.trim() !== 'full') {
+        console.log('  Cancelled.\n');
+        return;
+      }
+    } else {
+      console.log('  --yes flag set, proceeding without confirmation.\n');
+    }
+  }
+
+  // --- Generate files ---
+  const { files, profile } = await generateAutonomyConfig(profileName, projectDir);
+
+  printSecuritySummary(profile);
+
+  if (opts.dryRun) {
+    console.log('  Dry run — files that would be generated:\n');
+    for (const f of files) {
+      console.log(`  ── ${f.path} ──`);
+      console.log(f.content);
+    }
+    return;
+  }
+
+  // --- Write files ---
+  const { written, skipped } = await writeDocs(projectDir, files, {
+    overwrite: opts.overwrite || false,
+  });
+
+  // Make hook scripts executable
+  for (const f of files) {
+    if (f.path.endsWith('.sh')) {
+      try {
+        await chmod(join(projectDir, f.path), 0o755);
+      } catch { /* ignore */ }
+    }
+  }
+
+  printFileResults(written, skipped);
+
+  console.log(`
+  Next steps:
+    1. Review .claude/settings.json
+    2. Source aliases: source .claude/aliases.sh
+    3. ${profile.skipPermissions ? 'Run: claude --dangerously-skip-permissions' : 'Run: claude'}
+    4. git add .claude/ && git commit -m "Add autonomy config (${profileName})"
+`);
+}
+
 program.parse();

package/package.json

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

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

@@ -0,0 +1,60 @@
+---
+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/.claude/commands/setup-mcp.md

@@ -0,0 +1,115 @@
+---
+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/doc-generator/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.

package/scaffold/.claude/commands/update-docs.md

@@ -34,6 +34,7 @@ Compare the current state against the existing documentation:
 - **New directories** not covered in Architecture section
 - **Stale references** to files or directories that no longer exist
 - **Missing conventions** based on new config files (e.g., new linter added)
+- **Missing or outdated `.mcp.json`** — if `.mcp.json` doesn't exist, or if new technologies have been added that could benefit from MCP servers, suggest running `/setup-mcp`
 
 ## Step 4: Propose Updates
 

package/scaffold/.claude/skills/doc-generator/SKILL.md

@@ -12,6 +12,7 @@ allowed-tools: Read, Write, Glob, Grep, Bash(find:*), Bash(cat:*), Bash(node:*)
 - New files detected that change the tech stack (new framework, test runner, etc.)
 - After major refactoring that changes directory structure
 - When CLAUDE.md references files or directories that no longer exist
+- When `.mcp.json` is missing and the project has significant external dependencies
 
 ## Process
 
@@ -28,6 +29,7 @@ If CLAUDE.md already exists, read it and identify:
 
 ### 3. Generate or Update
 - For new documentation: generate CLAUDE.md, _state.md, .claude/rules/code-style.md, .claude/rules/testing.md, .claude/rules/workflow.md
+- For MCP configuration: suggest running `/setup-mcp` to search the MCP Registry and generate `.mcp.json`
 - For updates: propose specific changes and wait for user approval
 - Always present generated content for review before writing
 - NEVER create .md files beyond the ones listed above unless the user explicitly asks
@@ -54,3 +56,4 @@ Generated CLAUDE.md should follow this structure:
 Additionally generate:
 - `_state.md` — project state tracking (decisions, focus, known issues)
 - `.claude/rules/workflow.md` — Claude Code workflow best practices
+- `.mcp.json` — MCP server configuration (via `/setup-mcp`)