codingbuddy-rules 5.4.0 → 5.5.0

package/.ai-rules/adapters/claude-code.md

@@ -6,6 +6,52 @@ This guide explains how to use the common AI rules (`.ai-rules/`) in Claude Code
 
 Claude Code uses the `.claude/` directory for project-specific custom instructions, referencing the common rules from `.ai-rules/`.
 
+## Collective Intelligence with `activate` + Claude Native Teams
+
+### The `activate` Tool (Recommended Entry Point)
+
+The `activate` MCP tool is the **one-shot entry point** for collective intelligence workflows in Claude Code. It replaces the multi-step `parse_mode` + `dispatch_agents` ceremony with a single call.
+
+```
+activate({ prompt: "design auth feature", mode: "PLAN" })
+```
+
+**Returns:**
+- `mode` — resolved workflow mode
+- `rules` — loaded rules for the mode
+- `primaryAgent` — agent name + full system prompt
+- `specialists` — recommended specialists with full prompts
+- `discussion` — format guide for approve/concern/reject consensus
+- `nativeIntegration` — guidance for Teams, Memory, orchestration
+
+### Running a Specialist Council via Claude Native Teams
+
+When `activate` returns specialists, use Claude native Teams for real-time debate:
+
+```
+1. activate({ prompt }) → get specialists
+2. TeamCreate({ team_name: "plan-council" })
+3. For each specialist: Agent({ team_name, name: specialist.name, prompt: specialist.prompt })
+4. Specialists analyze independently → cross-review → consensus
+5. Collect findings → summarize to user
+```
+
+### Claude Code Native Feature Mapping
+
+Use Claude Code native features instead of legacy codingbuddy tools:
+
+| Need | Use This | Instead of |
+|------|----------|------------|
+| Workflow entry | `activate` | `parse_mode` + `dispatch_agents` |
+| Cross-session context | Claude Code Memory | `update_context` / `create_briefing` / `resume_session` |
+| Specialist execution | Claude native Teams | subagent dispatch |
+| Task exploration | `/dream` | `analyze_task` |
+| Planning approval | `EnterPlanMode` | planning stage routing |
+| Repeated execution | `/loop` | AUTO mode repetition |
+| Clarification | `AskUserQuestion` | clarification gate |
+
+> **Note**: `parse_mode` remains available for non-Claude Code hosts (Cursor, Codex, etc.).
+
 ## 🆕 Code Conventions Support
 
 CodingBuddy now automatically enforces project code conventions from config files:
@@ -325,9 +371,13 @@ AI assistants should display the `activation_message.formatted` field at the sta
 
 CodingBuddy supports parallel execution of multiple specialist agents for comprehensive analysis.
 
-### When to Use Parallel Execution
+### Recommended: Claude Native Teams (Primary Strategy)
+
+In Claude Code environments, use **Claude native Teams** as the primary execution strategy for specialist councils. The `activate` tool returns specialist prompts ready for Teams execution. See the "Collective Intelligence with `activate`" section above for the full workflow.
+
+### Legacy: SubAgent / TaskMaestro Strategies
 
-Parallel execution is recommended when `parse_mode` returns a `parallelAgentsRecommendation` field:
+For non-Claude Code hosts or when Teams is not available, parallel execution is recommended when `parse_mode` returns a `parallelAgentsRecommendation` field:
 
 | Mode | Default Specialists | Use Case |
 |------|---------------------|----------|

package/bin/cli.js

@@ -16,13 +16,16 @@ Usage:
   codingbuddy <command> [options]
 
 Commands:
-  init          Initialize .ai-rules in the current project
-  validate      Validate .ai-rules structure (agents JSON, rules markdown)
-  list-agents   List available specialist agents
+  init              Initialize .ai-rules in the current project
+  init --team       Detect AI tools and generate adapter configs for all
+  validate          Validate .ai-rules structure (agents JSON, rules markdown)
+  list-agents       List available specialist agents
 
 Options:
-  --help, -h    Show this help message
-  --version, -v Show version
+  --help, -h        Show this help message
+  --version, -v     Show version
+  --dry-run         Preview changes without writing (init --team)
+  --force           Overwrite without backup (init --team)
 `.trim(),
   );
 }
@@ -130,12 +133,23 @@ function validate() {
   console.log('\nAll validations passed');
 }
 
-function init() {
-  const { run } = require('../lib/init');
-  run().catch(err => {
-    console.error('Error:', err.message);
-    process.exit(1);
-  });
+function init(flags) {
+  if (flags.team) {
+    const { runTeam } = require('../lib/init/team');
+    runTeam(process.cwd(), {
+      dryRun: flags.dryRun,
+      force: flags.force,
+    }).catch(err => {
+      console.error('Error:', err.message);
+      process.exit(1);
+    });
+  } else {
+    const { run } = require('../lib/init');
+    run().catch(err => {
+      console.error('Error:', err.message);
+      process.exit(1);
+    });
+  }
 }
 
 // --- Main ---
@@ -153,9 +167,15 @@ if (command === '--version' || command === '-v') {
   process.exit(0);
 }
 
+const flags = {
+  team: args.includes('--team'),
+  dryRun: args.includes('--dry-run'),
+  force: args.includes('--force'),
+};
+
 switch (command) {
   case 'init':
-    init();
+    init(flags);
     break;
   case 'validate':
     validate();

package/lib/init/detect-tools.js

@@ -0,0 +1,40 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Supported AI coding tool definitions.
+ * Each entry maps a tool name to its config directory and indicator file.
+ */
+const AI_TOOLS = [
+  { name: 'cursor', configDir: '.cursor', indicator: 'rules' },
+  { name: 'claude-code', configDir: '.claude', indicator: 'settings.json' },
+  { name: 'codex', configDir: '.codex', indicator: 'instructions.md' },
+  { name: 'antigravity', configDir: '.antigravity', indicator: 'instructions.md' },
+  { name: 'amazon-q', configDir: '.q', indicator: 'settings.json' },
+  { name: 'kiro', configDir: '.kiro', indicator: 'settings.json' },
+];
+
+/**
+ * Detect installed AI coding tools by scanning for their config directories.
+ * @param {string} cwd - Directory to scan
+ * @returns {Array<{ name: string, configDir: string, indicator: string, exists: boolean, hasConfig: boolean }>}
+ */
+function detectTools(cwd) {
+  return AI_TOOLS.map(tool => {
+    const dirPath = path.join(cwd, tool.configDir);
+    const exists = fs.existsSync(dirPath);
+    const hasConfig =
+      exists && fs.existsSync(path.join(dirPath, tool.indicator));
+    return {
+      name: tool.name,
+      configDir: tool.configDir,
+      indicator: tool.indicator,
+      exists,
+      hasConfig,
+    };
+  });
+}
+
+module.exports = { detectTools, AI_TOOLS };

package/lib/init/generate-adapter.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+/**
+ * Maps tool names to their adapter template file and output target path.
+ */
+const ADAPTER_MAP = {
+  cursor: { adapter: 'cursor.md', target: '.cursor/rules/codingbuddy.mdc' },
+  'claude-code': { adapter: 'claude-code.md', target: '.claude/CLAUDE.md' },
+  codex: { adapter: 'codex.md', target: '.codex/instructions.md' },
+  antigravity: { adapter: 'antigravity.md', target: '.antigravity/instructions.md' },
+  'amazon-q': { adapter: 'q.md', target: '.q/rules/codingbuddy.md' },
+  kiro: { adapter: 'kiro.md', target: '.kiro/rules/codingbuddy.md' },
+};
+
+/**
+ * Generate adapter-specific configs for detected AI tools from shared .ai-rules.
+ * @param {string} cwd - Project root directory
+ * @param {Array<{ name: string }>} detectedTools - Tools to generate configs for
+ * @param {{ dryRun?: boolean, force?: boolean }} [options]
+ * @returns {{ generated: Array, backedUp: Array, skipped: Array }}
+ */
+function generateAdapterConfigs(cwd, detectedTools, options) {
+  const { dryRun = false, force = false } = options || {};
+  const result = { generated: [], backedUp: [], skipped: [] };
+  const adaptersDir = path.join(cwd, '.ai-rules', 'adapters');
+
+  for (const tool of detectedTools) {
+    if (!Object.hasOwn(ADAPTER_MAP, tool.name)) {
+      result.skipped.push({ tool: tool.name, reason: 'no adapter mapping' });
+      continue;
+    }
+
+    const mapping = ADAPTER_MAP[tool.name];
+    const adapterPath = path.join(adaptersDir, mapping.adapter);
+    if (!fs.existsSync(adapterPath)) {
+      result.skipped.push({ tool: tool.name, reason: 'adapter template not found' });
+      continue;
+    }
+
+    const targetPath = path.join(cwd, mapping.target);
+
+    if (dryRun) {
+      result.generated.push({ tool: tool.name, path: mapping.target, action: 'would-create' });
+      continue;
+    }
+
+    // Read adapter template (only when not dry-run)
+    const content = fs.readFileSync(adapterPath, 'utf-8');
+
+    // Backup existing config unless --force; skip symlinks for safety
+    if (fs.existsSync(targetPath) && !force) {
+      const stat = fs.lstatSync(targetPath);
+      if (!stat.isSymbolicLink()) {
+        const backupDir = path.join(cwd, '.codingbuddy-backup');
+        fs.mkdirSync(backupDir, { recursive: true });
+        const timestamp = Date.now();
+        const backupName = path.basename(mapping.target) + '.' + timestamp + '.bak';
+        const backupPath = path.join(backupDir, tool.name + '-' + backupName);
+        fs.copyFileSync(targetPath, backupPath);
+        result.backedUp.push({ tool: tool.name, from: mapping.target, to: backupPath });
+      }
+    }
+
+    // Write adapter config
+    fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+    fs.writeFileSync(targetPath, content, 'utf-8');
+    result.generated.push({ tool: tool.name, path: mapping.target, action: 'created' });
+  }
+
+  return result;
+}
+
+module.exports = { generateAdapterConfigs, ADAPTER_MAP };

package/lib/init/team.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const { detectTools } = require('./detect-tools');
+const { generateAdapterConfigs } = require('./generate-adapter');
+
+/**
+ * Run the team bootstrap flow: detect AI tools + generate adapter configs.
+ * @param {string} [cwd=process.cwd()]
+ * @param {{ dryRun?: boolean, force?: boolean }} [options]
+ * @returns {Promise<{ detected: number, generated: number, backedUp: number, skipped: number }>}
+ */
+async function runTeam(cwd, options) {
+  const targetDir = cwd || process.cwd();
+  const { dryRun = false, force = false } = options || {};
+
+  console.log('\n  codingbuddy init --team\n');
+
+  // Step 1: Detect AI tools
+  console.log('  Scanning for AI coding tools...');
+  const tools = detectTools(targetDir);
+  const detected = tools.filter(t => t.exists);
+  const notDetected = tools.filter(t => !t.exists);
+
+  if (detected.length > 0) {
+    console.log(`  Found ${detected.length} tool(s):`);
+    for (const tool of detected) {
+      const status = tool.hasConfig
+        ? '\u26a0 has existing config \u2014 will overwrite (backup auto-created)'
+        : '(no config)';
+      console.log(`    \u2713 ${tool.name} ${status}`);
+    }
+  }
+
+  if (notDetected.length > 0) {
+    console.log(`  Not found: ${notDetected.map(t => t.name).join(', ')}`);
+  }
+
+  // Step 2: Generate adapter configs
+  if (detected.length === 0) {
+    console.log('\n  No AI tools detected. Nothing to configure.\n');
+    return { detected: 0, generated: 0, backedUp: 0, skipped: 0 };
+  }
+
+  if (dryRun) {
+    console.log('\n  Dry run \u2014 previewing changes:');
+  } else {
+    console.log('\n  Generating adapter configs...');
+  }
+
+  const result = generateAdapterConfigs(targetDir, detected, { dryRun, force });
+
+  for (const item of result.generated) {
+    const verb = dryRun ? 'would create' : 'created';
+    console.log(`    ${verb}: ${item.path}`);
+  }
+
+  for (const item of result.backedUp) {
+    console.log(`    backed up: ${item.from}`);
+  }
+
+  for (const item of result.skipped) {
+    console.log(`    skipped: ${item.tool} (${item.reason})`);
+  }
+
+  const verb = dryRun ? 'would be generated' : 'generated';
+  console.log(`\n  Done! ${result.generated.length} config(s) ${verb}.\n`);
+
+  return {
+    detected: detected.length,
+    generated: result.generated.length,
+    backedUp: result.backedUp.length,
+    skipped: result.skipped.length,
+  };
+}
+
+module.exports = { runTeam };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codingbuddy-rules",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "AI coding rules for consistent practices across AI assistants",
   "main": "index.js",
   "types": "index.d.ts",