claude-base-setup 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # claude-base-setup
 
-A reusable `.claude` configuration for Claude Code projects with smart context injection, rules, and agents.
+A reusable `.claude` configuration for Claude Code projects with smart context injection, rules, agents, and slash commands.
 
 ## Installation
 
@@ -10,18 +10,36 @@ npx claude-base-setup
 
 This creates a `.claude/` directory in your project with:
 
+- **CLAUDE.md** - Project context (auto-loaded by Claude)
 - **hooks/** - Smart context injection on every prompt
 - **rules/** - Behavioral guidelines injected into context
 - **agents/** - Task workers (pre-code-check, package-checker, etc.)
-- **skills/** - Custom slash commands (empty by default)
-- **settings.local.json** - Hook configuration
+- **commands/** - Slash commands (/review, /test, /commit)
+- **settings.json** - Hook configuration
 
-## Usage
-
-### Re-initialize (overwrite existing)
+## CLI Options
 
 ```bash
+# Initialize (interactive - prompts for API key)
+npx claude-base-setup
+
+# Initialize without API key prompt (CI/automation)
+npx claude-base-setup --skip-api-key
+
+# Overwrite existing .claude directory
 npx claude-base-setup --force
+
+# Remove .claude directory
+npx claude-base-setup --remove
+
+# Update specific components (preserves settings.json and CLAUDE.md)
+npx claude-base-setup --update-hooks
+npx claude-base-setup --update-agents
+npx claude-base-setup --update-rules
+npx claude-base-setup --update-commands
+
+# Show help
+npx claude-base-setup --help
 ```
 
 ### What it does
@@ -39,9 +57,11 @@ npx claude-base-setup --force
 | announce-actions | always | Announce actions, track agent usage |
 | rule-format | "rule" keywords | How to create rules |
 | subagent-format | "agent" keywords | How to create agents |
+| command-format | "command" keywords | How to create slash commands |
 
-## Included Agents
+## Included Agents (23 specialized agents)
 
+### Core Agents
 | Agent | Purpose |
 |-------|---------|
 | pre-code-check | Search for existing code before creating new |
@@ -49,6 +69,60 @@ npx claude-base-setup --force
 | context-loader | Scan codebase and generate CONTEXT.md |
 | structure-validator | Validate project structure after file ops |
 
+### Planning & Requirements
+| Agent | Purpose |
+|-------|---------|
+| intent-clarifier | Clarifies requirements before coding starts |
+| assumption-challenger | Reviews plans and lists hidden assumptions |
+| breaking-change-predictor | Predicts what might break from changes |
+
+### Code Quality
+| Agent | Purpose |
+|-------|---------|
+| legacy-archaeologist | Explains why old code exists and its history |
+| dependency-detective | Investigates packages before adding them |
+| test-gap-finder | Finds untested code paths and logic gaps |
+| refactor-scope-limiter | Defines minimum safe scope for refactoring |
+
+### Workflow
+| Agent | Purpose |
+|-------|---------|
+| pr-narrator | Writes PR descriptions from commits/diffs |
+| migration-planner | Plans safe database/API migrations |
+| incident-replayer | Traces errors through code to explain them |
+
+### Session Management
+| Agent | Purpose |
+|-------|---------|
+| context-curator | Summarizes conversation and suggests compaction |
+| decision-logger | Records architectural decisions as ADRs |
+| session-handoff | Prepares summary for continuing later |
+| scope-creep-detector | Monitors if work is drifting from task |
+
+### Domain-Specific
+| Agent | Purpose |
+|-------|---------|
+| api-contract-guardian | Ensures API changes don't break consumers |
+| accessibility-auditor | Checks UI code for a11y issues |
+| performance-profiler | Finds obvious performance issues |
+| error-boundary-designer | Suggests where to add error handling |
+
+### Thinking Partners
+| Agent | Purpose |
+|-------|---------|
+| rubber-duck | Helps think through problems via questions |
+| devils-advocate | Argues against solutions to stress-test them |
+| 10x-simplifier | Challenges code to be radically simpler |
+| future-you | Reviews code as if maintaining it 6 months later |
+
+## Included Commands
+
+| Command | Purpose |
+|---------|---------|
+| /review | Review current changes for issues |
+| /test | Run tests and fix failures |
+| /commit | Stage and commit changes |
+
 ## Customization
 
 After installation, modify files in `.claude/` to fit your project:
@@ -56,7 +130,8 @@ After installation, modify files in `.claude/` to fit your project:
 - Add project-specific rules in `rules/`
 - Customize keyword triggers in `hooks/triggers.json`
 - Add custom agents in `agents/`
-- Update `settings.local.json` for permissions
+- Add custom slash commands in `commands/`
+- Update `settings.json` for permissions
 
 ## License
 

package/bin/cli.js

@@ -2,9 +2,24 @@
 
 const fs = require('fs');
 const path = require('path');
+const readline = require('readline');
 
 const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
 const TARGET_DIR = path.join(process.cwd(), '.claude');
+const ENV_FILE = path.join(process.cwd(), '.env');
+const args = process.argv.slice(2);
+
+// Parse flags
+const hasFlag = (...flags) => flags.some((f) => args.includes(f));
+const skipApiKey = hasFlag('--skip-api-key', '--no-api-key', '-s');
+const forceMode = hasFlag('--force', '-f');
+const removeMode = hasFlag('--remove', '--uninstall', '-r');
+const helpMode = hasFlag('--help', '-h');
+const updateHooks = hasFlag('--update-hooks');
+const updateAgents = hasFlag('--update-agents');
+const updateRules = hasFlag('--update-rules');
+const updateCommands = hasFlag('--update-commands');
+const updateMode = updateHooks || updateAgents || updateRules || updateCommands;
 
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -23,6 +38,23 @@ function copyDir(src, dest) {
   }
 }
 
+function copySubdir(subdir) {
+  const src = path.join(TEMPLATES_DIR, subdir);
+  const dest = path.join(TARGET_DIR, subdir);
+
+  if (!fs.existsSync(src)) {
+    console.error(`❌ Source directory not found: ${subdir}`);
+    return false;
+  }
+
+  if (fs.existsSync(dest)) {
+    fs.rmSync(dest, { recursive: true });
+  }
+
+  copyDir(src, dest);
+  return true;
+}
+
 function makeExecutable(dir) {
   const hooksDir = path.join(dir, 'hooks');
   if (fs.existsSync(hooksDir)) {
@@ -36,12 +68,72 @@ function makeExecutable(dir) {
   }
 }
 
-function init() {
+function prompt(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+const DEFAULT_MODEL = 'claude-3-5-haiku-latest';
+
+function saveEnvVar(name, value) {
+  let envContent = '';
+
+  if (fs.existsSync(ENV_FILE)) {
+    envContent = fs.readFileSync(ENV_FILE, 'utf8');
+    const regex = new RegExp(`^${name}=.*$`, 'gm');
+    if (regex.test(envContent)) {
+      envContent = envContent.replace(regex, `${name}=${value}`);
+    } else {
+      envContent += `${envContent.endsWith('\n') ? '' : '\n'}${name}=${value}\n`;
+    }
+  } else {
+    envContent = `${name}=${value}\n`;
+  }
+
+  fs.writeFileSync(ENV_FILE, envContent);
+}
+
+function saveApiKey(apiKey) {
+  saveEnvVar('ANTHROPIC_API_KEY', apiKey);
+}
+
+function saveModel(model) {
+  saveEnvVar('ANTHROPIC_MODEL', model);
+}
+
+function updateSettingsForLLM(useLLM) {
+  const settingsPath = path.join(TARGET_DIR, 'settings.json');
+  if (!fs.existsSync(settingsPath)) return;
+
+  let settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+
+  const hookScript = useLLM
+    ? '.claude/hooks/smart-inject-llm.sh'
+    : '.claude/hooks/smart-inject-rules.sh';
+
+  if (settings.hooks?.UserPromptSubmit?.[0]?.hooks?.[0]) {
+    settings.hooks.UserPromptSubmit[0].hooks[0].command = hookScript;
+  }
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+}
+
+async function init() {
   console.log('🔧 Initializing Claude Code base setup...\n');
 
-  if (fs.existsSync(TARGET_DIR)) {
+  if (fs.existsSync(TARGET_DIR) && !forceMode) {
     console.log('⚠️  .claude directory already exists.');
-    console.log('   Use --force to overwrite.\n');
+    console.log('   Use --force to overwrite, or use selective updates:');
+    console.log('   --update-hooks, --update-agents, --update-rules, --update-commands\n');
     process.exit(1);
   }
 
@@ -50,6 +142,11 @@ function init() {
     process.exit(1);
   }
 
+  if (forceMode && fs.existsSync(TARGET_DIR)) {
+    fs.rmSync(TARGET_DIR, { recursive: true });
+    console.log('🗑️  Removed existing .claude directory.\n');
+  }
+
   copyDir(TEMPLATES_DIR, TARGET_DIR);
   makeExecutable(TARGET_DIR);
 
@@ -57,16 +154,81 @@ function init() {
   console.log('   📁 hooks/     - Smart context injection');
   console.log('   📁 rules/     - Behavioral guidelines');
   console.log('   📁 agents/    - Task workers');
-  console.log('   📁 skills/    - Custom commands (empty)');
-  console.log('   📄 settings.local.json\n');
+  console.log('   📁 commands/  - Slash commands (/review, /test, /commit)');
+  console.log('   📄 settings.json');
+  console.log('   📄 CLAUDE.md\n');
+
+  // Handle API key
+  if (skipApiKey) {
+    console.log('⏭️  Skipped API key prompt (--skip-api-key).');
+    console.log('   Using keyword-based injection.\n');
+    updateSettingsForLLM(false);
+  } else {
+    console.log('🔑 Smart injection uses Claude Haiku for semantic rule matching.');
+    console.log('   This requires an Anthropic API key.\n');
+
+    const apiKey = await prompt(
+      '   Enter your ANTHROPIC_API_KEY (or press Enter to skip): '
+    );
+
+    if (apiKey) {
+      saveApiKey(apiKey);
+      saveModel(DEFAULT_MODEL);
+      updateSettingsForLLM(true);
+      console.log('\n   ✅ API key saved to .env');
+      console.log(`   ✅ Model set to ${DEFAULT_MODEL}`);
+      console.log('   ✅ Enabled LLM-powered smart injection');
+      console.log('   💡 Add .env to your .gitignore if not already there.');
+      console.log('   💡 Change ANTHROPIC_MODEL in .env to use a different model.\n');
+    } else {
+      console.log('\n   ⏭️  Skipped. Using keyword-based injection.');
+      console.log(
+        '   💡 Set ANTHROPIC_API_KEY env var later to enable LLM-powered injection.\n'
+      );
+      updateSettingsForLLM(false);
+    }
+  }
+
   console.log('🚀 Ready! Claude Code will now use these rules and agents.\n');
 }
 
-function forceInit() {
-  if (fs.existsSync(TARGET_DIR)) {
-    fs.rmSync(TARGET_DIR, { recursive: true });
+async function update() {
+  if (!fs.existsSync(TARGET_DIR)) {
+    console.error('❌ .claude directory not found. Run without flags to initialize first.');
+    process.exit(1);
+  }
+
+  console.log('🔄 Updating selected components...\n');
+
+  const updates = [];
+
+  if (updateHooks) {
+    if (copySubdir('hooks')) {
+      makeExecutable(TARGET_DIR);
+      updates.push('hooks');
+    }
+  }
+  if (updateAgents && copySubdir('agents')) updates.push('agents');
+  if (updateRules && copySubdir('rules')) updates.push('rules');
+  if (updateCommands && copySubdir('commands')) updates.push('commands');
+
+  if (updates.length > 0) {
+    console.log(`✅ Updated: ${updates.join(', ')}\n`);
+    console.log('💡 Your settings.json and CLAUDE.md were preserved.\n');
+  } else {
+    console.log('⚠️  No components updated.\n');
   }
-  init();
+}
+
+function remove() {
+  if (!fs.existsSync(TARGET_DIR)) {
+    console.log('ℹ️  .claude directory does not exist. Nothing to remove.\n');
+    return;
+  }
+
+  fs.rmSync(TARGET_DIR, { recursive: true });
+  console.log('✅ Removed .claude directory.\n');
+  console.log('💡 Note: .env file (if created) was not removed.\n');
 }
 
 function showHelp() {
@@ -74,26 +236,44 @@ function showHelp() {
 claude-base-setup - Initialize .claude configuration for Claude Code
 
 Usage:
-  npx claude-base-setup         Initialize .claude in current directory
-  npx claude-base-setup --force Overwrite existing .claude directory
-  npx claude-base-setup --help  Show this help message
+  npx claude-base-setup              Initialize .claude in current directory
+  npx claude-base-setup --force      Overwrite existing .claude directory
+  npx claude-base-setup --remove     Remove .claude directory
+  npx claude-base-setup --skip-api-key  Skip API key prompt (CI/automation)
+
+Selective updates (preserves settings.json and CLAUDE.md):
+  npx claude-base-setup --update-hooks     Update only hooks/
+  npx claude-base-setup --update-agents    Update only agents/
+  npx claude-base-setup --update-rules     Update only rules/
+  npx claude-base-setup --update-commands  Update only commands/
+
+Options:
+  -h, --help          Show this help message
+  -f, --force         Overwrite existing .claude directory
+  -r, --remove        Remove .claude directory (alias: --uninstall)
+  -s, --skip-api-key  Skip API key prompt (alias: --no-api-key)
 
 What's included:
   • hooks/     Smart context injection on every prompt
   • rules/     Behavioral guidelines (code standards, etc.)
   • agents/    Task workers (pre-code-check, package-checker, etc.)
-  • skills/    Custom slash commands (empty by default)
+  • commands/  Slash commands (/review, /test, /commit)
+  • CLAUDE.md  Project context (auto-loaded by Claude)
 
 Learn more: https://github.com/fr0mpy/claude-base-setup
 `);
 }
 
-const args = process.argv.slice(2);
-
-if (args.includes('--help') || args.includes('-h')) {
-  showHelp();
-} else if (args.includes('--force') || args.includes('-f')) {
-  forceInit();
-} else {
-  init();
+async function main() {
+  if (helpMode) {
+    showHelp();
+  } else if (removeMode) {
+    remove();
+  } else if (updateMode) {
+    await update();
+  } else {
+    await init();
+  }
 }
+
+main();

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "claude-base-setup",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A reusable .claude configuration for Claude Code projects with smart context injection, rules, and agents",
   "main": "index.js",
   "bin": {
     "claude-base-setup": "./bin/cli.js"
   },
   "scripts": {
-    "test": "echo \"No tests yet\" && exit 0"
+    "test": "node test/cli.test.js"
   },
   "keywords": [
     "claude",
@@ -20,7 +20,7 @@
     "agents",
     "hooks"
   ],
-  "author": "",
+  "author": "fr0mpy",
   "license": "MIT",
   "repository": {
     "type": "git",

package/templates/CLAUDE.md

@@ -0,0 +1,20 @@
+# Project Context
+
+This project uses dynamic context management via `.claude/CONTEXT.md`.
+
+## Quick Reference
+
+Run `context-loader` agent if context is stale or missing.
+
+See `.claude/CONTEXT.md` for:
+- Project structure and file tree
+- Detected stack and dependencies
+- Key directories and their purposes
+- TODOs and stub functions
+
+## Configuration
+
+- **Rules**: `.claude/rules/` - Behavioral guidelines (auto-injected)
+- **Agents**: `.claude/agents/` - Task specialists
+- **Commands**: `.claude/commands/` - Slash command workflows
+- **Hooks**: `.claude/hooks/` - Automation scripts

package/templates/agents/10x-simplifier.md

@@ -0,0 +1,64 @@
+---
+name: 10x-simplifier
+description: Challenges code to be radically simpler. Use when code feels complex or over-engineered.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+You are a simplification expert that finds the essence of solutions.
+
+## Your Task
+
+Given code or a design:
+
+1. **Identify complexity** - What makes this complicated?
+2. **Question necessity** - Does each part need to exist?
+3. **Find the essence** - What's the core problem being solved?
+4. **Propose radical simplification** - How would this look 10x simpler?
+5. **Challenge abstractions** - Are these earning their complexity?
+
+## Simplification Lenses
+
+- **Delete it** - Can we just not do this?
+- **Inline it** - Do we need this abstraction?
+- **Hardcode it** - Is this configurability used?
+- **Combine it** - Are these separate things really one thing?
+- **Defer it** - Do we need this now?
+
+## Output Format
+
+```
+✨ 10x simplification: [target]
+
+Current complexity:
+- Lines of code: [count]
+- Abstractions: [count]
+- Dependencies: [count]
+- Cognitive load: [low/medium/high]
+
+Complexity sources:
+1. [source] - Reason: [why it exists]
+2. [source] - Reason: [why it exists]
+
+Questions to challenge:
+- "Do we actually need [X]?"
+- "What if we just [simpler approach]?"
+- "Is [abstraction] earning its complexity?"
+
+10x simpler version:
+
+[Describe or sketch the radically simpler approach]
+
+What we'd lose: [tradeoffs]
+What we'd gain: [benefits]
+
+Concrete suggestion:
+[Specific simplification to try first]
+```
+
+## Rules
+
+- "The best code is no code"
+- Abstractions should be earned, not anticipated
+- Simple and working beats complex and flexible
+- Ask "what would a junior dev understand?"

package/templates/agents/accessibility-auditor.md

@@ -0,0 +1,62 @@
+---
+name: accessibility-auditor
+description: Checks UI code for accessibility issues. Use before shipping UI components or after design changes.
+tools: Read, Grep, Glob
+model: haiku
+---
+
+You are an accessibility checker that catches a11y issues early.
+
+## Your Task
+
+Review UI code for:
+
+1. **Semantic HTML** - Proper element usage
+2. **ARIA attributes** - Labels, roles, states
+3. **Keyboard navigation** - Focus management, tab order
+4. **Color/contrast** - Not relying on color alone
+5. **Screen reader** - Meaningful content order
+
+## Common Issues to Check
+
+- Images without alt text
+- Buttons/links without accessible names
+- Form inputs without labels
+- Missing focus indicators
+- Non-semantic div/span overuse
+- Color-only state indication
+- Missing skip links
+- Inaccessible modals/dialogs
+
+## Output Format
+
+```
+♿ Accessibility audit: [file/component]
+
+Issues found:
+
+🔴 Critical (blocks users):
+- [line]: [issue] - Fix: [solution]
+
+🟡 Serious (major barriers):
+- [line]: [issue] - Fix: [solution]
+
+🟢 Minor (best practice):
+- [line]: [issue] - Fix: [solution]
+
+Checklist:
+- [ ] All images have alt text
+- [ ] All interactive elements are keyboard accessible
+- [ ] All form inputs have labels
+- [ ] Focus order is logical
+- [ ] Color is not the only indicator
+
+WCAG level: [A/AA/AAA estimate]
+```
+
+## Rules
+
+- Prioritize issues that block users entirely
+- Provide specific fix suggestions
+- Note when manual testing is needed
+- Don't flag decorative images needing alt=""

package/templates/agents/api-contract-guardian.md

@@ -0,0 +1,67 @@
+---
+name: api-contract-guardian
+description: Ensures API changes don't break consumers. Use before modifying endpoints, response shapes, or public interfaces.
+tools: Read, Grep, Glob
+model: sonnet
+---
+
+You are an API contract enforcer that prevents breaking changes.
+
+## Your Task
+
+Before API modifications:
+
+1. **Document current contract** - What do consumers expect?
+2. **Analyze proposed changes** - What would change?
+3. **Find all consumers** - Who uses this API?
+4. **Assess compatibility** - Is this breaking?
+5. **Suggest versioning** - How to change safely?
+
+## Contract Elements
+
+- Request method and path
+- Required/optional parameters
+- Request body shape
+- Response status codes
+- Response body shape
+- Error formats
+- Headers expected/returned
+
+## Output Format
+
+```
+🔒 API contract analysis: [endpoint/interface]
+
+Current contract:
+- Method: [GET/POST/etc]
+- Path: [path with params]
+- Request: [shape summary]
+- Response: [shape summary]
+
+Proposed changes:
+- [change 1]
+- [change 2]
+
+Consumers found: [count]
+- [consumer 1] - Uses: [which fields]
+- [consumer 2] - Uses: [which fields]
+
+Breaking change assessment:
+🔴 Breaking: [list]
+🟡 Potentially breaking: [list]
+🟢 Safe: [list]
+
+Recommendation:
+[version bump / additive change / deprecation path]
+
+Safe migration:
+1. [step 1]
+2. [step 2]
+```
+
+## Rules
+
+- Removing or renaming fields is always breaking
+- Adding optional fields is usually safe
+- Changing types is always breaking
+- Document the deprecation path