@itz4blitz/agentful 1.8.0 → 1.8.2

package/README.md

@@ -70,9 +70,6 @@ npx @itz4blitz/agentful init --preset=minimal
 
 # Custom: Choose components
 npx @itz4blitz/agentful init --agents=orchestrator,backend --skills=validation
-
-# Web configurator
-https://agentful.app/configure
 ```
 
 ## Commands

package/bin/cli.js

@@ -20,6 +20,7 @@
 
 import fs from 'fs';
 import path from 'path';
+import { spawnSync } from 'child_process';
 import { fileURLToPath } from 'url';
 import { initProject, isInitialized } from '../lib/init.js';
 import {
@@ -82,11 +83,11 @@ function showHelp() {
   console.log('');
   console.log('INIT OPTIONS (optional):');
   console.log(`  ${colors.yellow}--preset=minimal${colors.reset}       Minimal setup (orchestrator + backend only)`);
-  console.log(`  ${colors.yellow}--config=<url|id>${colors.reset}       Use a shareable configuration`);
   console.log(`  ${colors.yellow}--agents=<list>${colors.reset}         Custom agents (comma-separated)`);
   console.log(`  ${colors.yellow}--skills=<list>${colors.reset}         Custom skills (comma-separated)`);
   console.log(`  ${colors.yellow}--hooks=<list>${colors.reset}          Custom hooks (comma-separated)`);
   console.log(`  ${colors.yellow}--gates=<list>${colors.reset}          Custom quality gates (comma-separated)`);
+  console.log(`  ${colors.yellow}--skip-mcp${colors.reset}              Skip automatic MCP server setup`);
   console.log('');
   console.log('EXAMPLES:');
   console.log(`  ${colors.dim}# Install agentful (all components - recommended)${colors.reset}`);
@@ -183,50 +184,78 @@ function checkGitignore() {
   }
 }
 
-/**
- * Fetch configuration from shareable URL or ID
- * @param {string} configParam - URL or ID
- * @returns {Promise<Object|null>}
- */
-async function fetchShareableConfig(configParam) {
-  try {
-    // Determine if it's a full URL or just an ID
-    let apiUrl;
-    if (configParam.startsWith('http://') || configParam.startsWith('https://')) {
-      // Extract ID from URL
-      const match = configParam.match(/\/c\/([a-f0-9]{8})$/i);
-      if (!match) {
-        throw new Error('Invalid config URL format. Expected: https://agentful.app/c/{id}');
-      }
-      const id = match[1];
-      apiUrl = `https://agentful.app/api/get-config/${id}`;
-    } else if (/^[a-f0-9]{8}$/i.test(configParam)) {
-      // It's just the ID
-      apiUrl = `https://agentful.app/api/get-config/${configParam}`;
-    } else {
-      throw new Error('Invalid config parameter. Provide either a full URL or an 8-character ID.');
-    }
+const MCP_SERVER_NAME = 'agentful';
+const MCP_SERVER_PACKAGE = '@itz4blitz/agentful-mcp-server';
+const MCP_SETUP_COMMAND = `claude mcp add ${MCP_SERVER_NAME} -- npx -y ${MCP_SERVER_PACKAGE}`;
 
-    log(colors.dim, `Fetching configuration from ${apiUrl}...`);
+function parseMcpInstallState() {
+  const result = spawnSync('claude', ['mcp', 'list'], {
+    encoding: 'utf8'
+  });
 
-    const response = await fetch(apiUrl);
+  if (result.error) {
+    return {
+      ok: false,
+      reason: result.error.code === 'ENOENT' ? 'claude-not-found' : result.error.message
+    };
+  }
 
-    if (!response.ok) {
-      if (response.status === 404) {
-        throw new Error('Configuration not found. The config may have expired or the ID is invalid.');
-      }
-      if (response.status === 410) {
-        throw new Error('Configuration has expired (1 year TTL).');
-      }
-      throw new Error(`Failed to fetch config: HTTP ${response.status}`);
-    }
+  if (result.status !== 0) {
+    return {
+      ok: false,
+      reason: (result.stderr || result.stdout || '').trim() || 'claude mcp list failed'
+    };
+  }
 
-    const data = await response.json();
-    return data.config;
-  } catch (error) {
-    log(colors.red, `Error fetching shareable config: ${error.message}`);
-    return null;
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+  const installed = new RegExp(`^\\s*${MCP_SERVER_NAME}(\\s|$)`, 'm').test(output);
+
+  return {
+    ok: true,
+    installed
+  };
+}
+
+function ensureAgentfulMcpInstalled() {
+  const state = parseMcpInstallState();
+  if (!state.ok) {
+    return {
+      status: 'unavailable',
+      reason: state.reason
+    };
   }
+
+  if (state.installed) {
+    return { status: 'already-installed' };
+  }
+
+  const addResult = spawnSync('claude', ['mcp', 'add', MCP_SERVER_NAME, '--', 'npx', '-y', MCP_SERVER_PACKAGE], {
+    encoding: 'utf8'
+  });
+
+  if (addResult.error) {
+    return {
+      status: 'failed',
+      reason: addResult.error.message
+    };
+  }
+
+  if (addResult.status !== 0) {
+    return {
+      status: 'failed',
+      reason: (addResult.stderr || addResult.stdout || '').trim() || 'claude mcp add failed'
+    };
+  }
+
+  const verify = parseMcpInstallState();
+  if (!verify.ok || !verify.installed) {
+    return {
+      status: 'failed',
+      reason: !verify.ok ? verify.reason : 'MCP server not visible after install'
+    };
+  }
+
+  return { status: 'installed' };
 }
 
 async function init(args) {
@@ -241,77 +270,72 @@ async function init(args) {
   // Build configuration from preset and/or flags
   let config = null;
 
-  // Check for shareable config first
   if (flags.config) {
-    config = await fetchShareableConfig(flags.config);
-    if (!config) {
-      log(colors.red, 'Failed to load shareable configuration.');
-      process.exit(1);
-    }
-    log(colors.green, 'Loaded shareable configuration successfully!');
-    console.log('');
-  } else {
-    // Default to "default" preset if no flags provided
-    let presetConfig = null;
-    const hasCustomFlags = flags.agents || flags.skills || flags.hooks || flags.gates;
-
-    if (flags.preset) {
-      // User explicitly specified a preset
-      presetConfig = getPreset(flags.preset);
-      if (!presetConfig) {
-        log(colors.red, `Unknown preset: ${flags.preset}`);
-        console.log('');
-        log(colors.dim, 'Available presets:');
-        listPresets().forEach(p => log(colors.dim, `  - ${p.name}`));
-        console.log('');
-        log(colors.dim, 'Run: agentful presets');
-        process.exit(1);
-      }
-      log(colors.dim, `Using preset: ${flags.preset}`);
-    } else if (!hasCustomFlags) {
-      // No preset and no custom flags = use default preset
-      presetConfig = getPreset('default');
-      log(colors.dim, 'Installing agentful (all components)');
-    }
-
-    // Parse individual flags
-    const flagConfig = {
-      agents: flags.agents ? parseArrayFlag(flags.agents) : null,
-      skills: flags.skills ? parseArrayFlag(flags.skills) : null,
-      hooks: flags.hooks ? parseArrayFlag(flags.hooks) : null,
-      gates: flags.gates ? parseArrayFlag(flags.gates) : null
-    };
+    log(colors.red, '--config is no longer supported.');
+    log(colors.dim, 'Use local CLI flags instead: --preset, --agents, --skills, --hooks, --gates');
+    process.exit(1);
+  }
 
-    // Merge preset with flags (flags override preset)
-    if (presetConfig) {
-      config = mergePresetWithFlags(presetConfig, flagConfig);
-    } else {
-      // Custom configuration with no preset
-      config = {
-        agents: flagConfig.agents || ['orchestrator'],
-        skills: flagConfig.skills || [],
-        hooks: flagConfig.hooks || [],
-        gates: flagConfig.gates || []
-      };
-    }
+  // Default to "default" preset if no flags provided
+  let presetConfig = null;
+  const hasCustomFlags = flags.agents || flags.skills || flags.hooks || flags.gates;
 
-    // Validate configuration
-    const validation = validateConfiguration(config);
-    if (!validation.valid) {
-      log(colors.yellow, 'Configuration warnings:');
-      validation.errors.forEach(err => log(colors.yellow, `  - ${err}`));
+  if (flags.preset) {
+    // User explicitly specified a preset
+    presetConfig = getPreset(flags.preset);
+    if (!presetConfig) {
+      log(colors.red, `Unknown preset: ${flags.preset}`);
+      console.log('');
+      log(colors.dim, 'Available presets:');
+      listPresets().forEach(p => log(colors.dim, `  - ${p.name}`));
       console.log('');
+      log(colors.dim, 'Run: agentful presets');
+      process.exit(1);
     }
+    log(colors.dim, `Using preset: ${flags.preset}`);
+  } else if (!hasCustomFlags) {
+    // No preset and no custom flags = use default preset
+    presetConfig = getPreset('default');
+    log(colors.dim, 'Installing agentful (all components)');
+  }
 
-    // Show what will be installed
-    log(colors.dim, 'Configuration:');
-    log(colors.dim, `  Agents: ${config.agents.join(', ')}`);
-    log(colors.dim, `  Skills: ${config.skills.join(', ') || 'none'}`);
-    log(colors.dim, `  Hooks: ${config.hooks.join(', ') || 'none'}`);
-    log(colors.dim, `  Gates: ${config.gates.join(', ') || 'none'}`);
+  // Parse individual flags
+  const flagConfig = {
+    agents: flags.agents ? parseArrayFlag(flags.agents) : null,
+    skills: flags.skills ? parseArrayFlag(flags.skills) : null,
+    hooks: flags.hooks ? parseArrayFlag(flags.hooks) : null,
+    gates: flags.gates ? parseArrayFlag(flags.gates) : null
+  };
+
+  // Merge preset with flags (flags override preset)
+  if (presetConfig) {
+    config = mergePresetWithFlags(presetConfig, flagConfig);
+  } else {
+    // Custom configuration with no preset
+    config = {
+      agents: flagConfig.agents || ['orchestrator'],
+      skills: flagConfig.skills || [],
+      hooks: flagConfig.hooks || [],
+      gates: flagConfig.gates || []
+    };
+  }
+
+  // Validate configuration
+  const validation = validateConfiguration(config);
+  if (!validation.valid) {
+    log(colors.yellow, 'Configuration warnings:');
+    validation.errors.forEach(err => log(colors.yellow, `  - ${err}`));
     console.log('');
   }
 
+  // Show what will be installed
+  log(colors.dim, 'Configuration:');
+  log(colors.dim, `  Agents: ${config.agents.join(', ')}`);
+  log(colors.dim, `  Skills: ${config.skills.join(', ') || 'none'}`);
+  log(colors.dim, `  Hooks: ${config.hooks.join(', ') || 'none'}`);
+  log(colors.dim, `  Gates: ${config.gates.join(', ') || 'none'}`);
+  console.log('');
+
   // Check if already initialized
   if (await isInitialized(targetDir)) {
     log(colors.yellow, 'agentful is already initialized in this directory!');
@@ -391,6 +415,28 @@ async function init(args) {
   // Update .gitignore
   checkGitignore();
 
+  // Configure Agentful MCP server by default (non-fatal)
+  const skipMcpSetup = Boolean(flags['skip-mcp']);
+  const mcpSetupResult = skipMcpSetup ? { status: 'skipped' } : ensureAgentfulMcpInstalled();
+
+  if (skipMcpSetup) {
+    log(colors.dim, 'Skipped MCP setup (--skip-mcp)');
+    console.log('');
+  } else if (mcpSetupResult.status === 'installed') {
+    log(colors.green, '✓ Agentful MCP server configured');
+    console.log('');
+  } else if (mcpSetupResult.status === 'already-installed') {
+    log(colors.green, '✓ Agentful MCP server already configured');
+    console.log('');
+  } else {
+    log(colors.yellow, '⚠ Could not auto-configure Agentful MCP server');
+    if (mcpSetupResult.reason) {
+      log(colors.dim, `  Reason: ${mcpSetupResult.reason}`);
+    }
+    log(colors.dim, `  Run manually: ${MCP_SETUP_COMMAND}`);
+    console.log('');
+  }
+
   // Show next steps
   console.log('');
   log(colors.bright, 'Next Steps:');
@@ -411,13 +457,23 @@ async function init(args) {
   }
   log(colors.dim, 'Optional: Edit CLAUDE.md and .claude/product/index.md first to customize.');
   console.log('');
-  log(colors.bright, 'Recommended: Enable Pattern Learning');
-  console.log('');
-  log(colors.dim, '  Agents get smarter when they can store and reuse patterns.');
-  log(colors.dim, '  Run this once to enable:');
-  console.log('');
-  log(colors.cyan, '    claude mcp add agentful -- npx -y @itz4blitz/agentful-mcp-server');
-  console.log('');
+  if (skipMcpSetup) {
+    log(colors.bright, 'Pattern Learning (Skipped)');
+    console.log('');
+    log(colors.dim, '  You skipped automatic MCP setup with --skip-mcp.');
+    log(colors.dim, '  Enable it later with:');
+    console.log('');
+    log(colors.cyan, `    ${MCP_SETUP_COMMAND}`);
+    console.log('');
+  } else if (mcpSetupResult.status !== 'installed' && mcpSetupResult.status !== 'already-installed') {
+    log(colors.bright, 'Pattern Learning (Manual Step Required)');
+    console.log('');
+    log(colors.dim, '  Agents get smarter when they can store and reuse patterns.');
+    log(colors.dim, '  Run this once to enable:');
+    console.log('');
+    log(colors.cyan, `    ${MCP_SETUP_COMMAND}`);
+    console.log('');
+  }
 }
 
 function showStatus() {

package/bin/hooks/architect-drift-detector.js

@@ -239,4 +239,6 @@ function markForReanalysis(arch, reasons) {
 
 // Run detection
 const driftDetected = detectArchitectDrift();
-process.exit(driftDetected ? 1 : 0);
+// Always exit 0 - drift is informational, not an error
+// Non-zero exit codes are interpreted as hook errors by Claude Code
+process.exit(0);

package/bin/hooks/block-random-docs.js

@@ -12,7 +12,6 @@
  * - .claude/skills/*\/SKILL.md (skill documentation)
  * - .claude/product/**\/*.md (product specifications)
  * - template/**\/*.md (template files)
- * - examples/**\/*.md (example documentation)
  *
  * Blocked:
  * - Random *.md files in project root
@@ -42,7 +41,6 @@ const ALLOWED_PATTERNS = [
   /^\.claude\/skills\/[^\/]+\/SKILL\.md$/,     // Skill docs
   /^\.claude\/product\/.*\.md$/,               // Product specs
   /^template\/.*\.md$/,                        // Template files
-  /^examples\/.*\.md$/,                        // Examples
   /^\.agentful\/.*\.md$/                       // Internal agentful state docs (rare)
 ];
 

package/bin/hooks/ensure-worktree.js

@@ -0,0 +1,234 @@
+#!/usr/bin/env node
+
+/**
+ * Ensure Worktree Hook
+ *
+ * PreToolUse hook that enforces git worktree usage for file modifications.
+ *
+ * Modes:
+ *   off   - Allow all edits (backward compatible)
+ *   block  - Require existing worktree, reject if not in one
+ *   auto   - Create worktree automatically if not in one
+ *
+ * Environment Variables:
+ *   AGENTFUL_WORKTREE_MODE - off|block|auto (default: auto)
+ *   AGENTFUL_WORKTREE_DIR - Where to create worktrees (default: ../)
+ *   AGENTFUL_WORKTREE_AUTO_CLEANUP - Auto-remove after completion (default: true)
+ *   AGENTFUL_WORKTREE_RETENTION_DAYS - Days before cleanup (default: 7)
+ *   AGENTFUL_WORKTREE_MAX_ACTIVE - Max active worktrees (default: 5)
+ *
+ * To disable this hook:
+ *   Temporary: export AGENTFUL_WORKTREE_MODE=off
+ *   Permanent: Remove from .claude/settings.json PreToolUse hooks
+ *   Customize: Edit bin/hooks/ensure-worktree.js
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+
+// Get configuration
+const MODE = process.env.AGENTFUL_WORKTREE_MODE || 'auto';
+const WORKTREE_DIR = process.env.AGENTFUL_WORKTREE_DIR || '../';
+const AUTO_CLEANUP = process.env.AGENTFUL_WORKTREE_AUTO_CLEANUP !== 'false';
+const RETENTION_DAYS = parseInt(process.env.AGENTFUL_WORKTREE_RETENTION_DAYS || '7', 10);
+const MAX_ACTIVE = parseInt(process.env.AGENTFUL_WORKTREE_MAX_ACTIVE || '5', 10);
+const AGENT_TYPE = process.env.AGENTFUL_AGENT_TYPE || 'general';
+const TASK_TYPE = process.env.AGENTFUL_TASK_TYPE || 'general';
+
+/**
+ * Detect if currently in a git worktree
+ */
+function isInWorktree() {
+  try {
+    const cwd = process.cwd();
+    const gitFile = path.join(cwd, '.git');
+
+    // If .git is a file (not a directory), we're in a worktree
+    if (existsSync(gitFile) && statSync(gitFile).isFile()) {
+      return true;
+    }
+  } catch (error) {
+    return false;
+  }
+}
+
+/**
+ * Determine worktree purpose from agent/task context
+ */
+function determinePurpose() {
+  // Agent-based purposes
+  const agentPurposes = {
+    'fixer': 'fix',
+    'reviewer': 'review',
+    'tester': 'test',
+    'backend': 'backend',
+    'frontend': 'frontend',
+    'architect': 'architect',
+    'orchestrator': 'orchestrator',
+  };
+
+  // Task-based purposes
+  const taskPurposes = {
+    'feature': 'feature',
+    'hotfix': 'hotfix',
+    'bugfix': 'bugfix',
+    'experiment': 'experiment',
+  };
+
+  // Determine purpose based on agent type, then task type
+  if (agentPurposes[AGENT_TYPE]) {
+    return agentPurposes[AGENT_TYPE];
+  }
+
+  if (taskPurposes[TASK_TYPE]) {
+    return taskPurposes[TASK_TYPE];
+  }
+
+  // Default to general
+  return 'general';
+}
+
+/**
+ * Show block message with helpful error
+ */
+function showBlockMessage() {
+  const branch = getCurrentBranch();
+
+  console.error(`
+:::error
+═════════════════════════════════════════════════
+  🚫 Blocked: Direct Repository Edits
+═════════════════════════════════════════════════
+
+You are attempting to edit files in the root repository, but AGENTFUL_WORKTREE_MODE
+is set to "block" which requires working in a git worktree.
+
+Current branch: ${branch}
+Current directory: ${process.cwd()}
+
+To proceed, choose one option:
+
+1. 🌳 Create a worktree (recommended):
+   git worktree add ../my-worktree -b ${branch}
+   cd ../my-worktree
+
+2. ⚙️  Change mode to auto (creates worktrees automatically):
+   export AGENTFUL_WORKTREE_MODE=auto
+
+3. 🚫 Disable worktree protection (not recommended):
+   export AGENTFUL_WORKTREE_MODE=off
+
+For more information, see: /agentful-worktree or docs/pages/concepts/git-worktrees.mdx
+:::`);
+
+  process.exit(1);
+}
+
+/**
+ * Create worktree automatically
+ */
+function createWorktree() {
+  const repoRoot = findRepoRoot();
+  if (!repoRoot) {
+    console.error(':::error Not in a git repository:::');
+    process.exit(1);
+  }
+
+  const purpose = determinePurpose();
+  const branch = getCurrentBranch();
+  const timestamp = Date.now();
+
+  // Generate worktree name
+  const worktreeName = `agentful-${purpose}-${sanitizeBranchName(branch)}-${timestamp}`;
+
+  // Create worktree
+  const worktreePath = path.join(repoRoot, WORKTREE_DIR, worktreeName);
+
+  console.log(`🌳 Creating worktree: ${worktreeName}`);
+  console.log(`   Branch: ${branch}`);
+  console.log(`   Path: ${worktreePath}`);
+
+  try {
+    execSync(
+      `git worktree add "${worktreePath}" -b "${branch}"`,
+      { cwd: repoRoot, stdio: 'inherit' }
+    );
+  } catch (error) {
+    console.error(`:::error Failed to create worktree: ${error.message}:::`);
+    process.exit(1);
+  }
+
+  // Track in state.json (would happen in orchestrator, but this is standalone)
+  try {
+    const stateFile = path.join(repoRoot, '.agentful', 'state.json');
+    if (existsSync(stateFile)) {
+      const state = JSON.parse(readFileSync(stateFile, 'utf8'));
+      state.current_worktree = {
+        name: worktreeName,
+        path: worktreePath,
+        branch: branch,
+        purpose: purpose,
+        created_at: new Date().toISOString(),
+      };
+      writeFileSync(stateFile, JSON.stringify(state, null, 2));
+    }
+  } catch (error) {
+    // State file might not exist yet, that's okay
+  }
+
+  // Export for caller to capture
+  console.log(`export AGENTFUL_WORKTREE_DIR="${worktreePath}"`);
+
+  process.exit(0);
+}
+
+/**
+ * Main execution
+ */
+(() => {
+  // Get tool and file from environment
+  const tool = process.env.TOOL || '';
+  const file = process.env.FILE || '';
+
+  // Only check Write and Edit tools
+  if (tool !== 'Write' && tool !== 'Edit') {
+    process.exit(0);
+  }
+
+  // Auto-disable in CI environments
+  if (isCIEnvironment()) {
+    process.exit(0);
+  }
+
+  // Check if already in worktree (explicitly set or detected)
+  if (WORKTREE_DIR) {
+    // In worktree - allow operation
+    process.exit(0);
+  }
+
+  // Not in worktree - handle based on mode
+  switch (MODE) {
+    case 'off':
+      // Allow all edits silently
+      process.exit(0);
+      break;
+
+    case 'block':
+      // Require existing worktree
+      showBlockMessage();
+      break;
+
+    case 'auto':
+      // Create worktree automatically
+      createWorktree();
+      break;
+
+    default:
+      console.error(`:::warning Invalid AGENTFUL_WORKTREE_MODE: ${MODE}:::`);
+      console.error(`:::warning Valid options: off, block, auto:::`);
+      process.exit(1);
+  }
+})();

package/bin/hooks/mcp-health-check.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * MCP Health Check Hook
+ *
+ * Verifies the "agentful" MCP server is configured in Claude Code.
+ * Non-blocking: warns only, never exits with failure.
+ */
+
+import { spawnSync } from 'child_process';
+
+const MCP_NAME = 'agentful';
+const SETUP_COMMAND = 'claude mcp add agentful -- npx -y @itz4blitz/agentful-mcp-server';
+
+function runClaudeMcpList() {
+  return spawnSync('claude', ['mcp', 'list'], {
+    encoding: 'utf8'
+  });
+}
+
+function hasAgentfulMcp(text) {
+  return new RegExp(`^\\s*${MCP_NAME}(\\s|$)`, 'm').test(text);
+}
+
+function printMissingMcpWarning() {
+  console.log('⚠️  Agentful MCP server is not configured.');
+  console.log(`   Run: ${SETUP_COMMAND}`);
+}
+
+(() => {
+  const result = runClaudeMcpList();
+
+  if (result.error) {
+    if (result.error.code === 'ENOENT') {
+      console.log('⚠️  Claude CLI not found; MCP setup check skipped.');
+      return;
+    }
+
+    if (process.env.VERBOSE) {
+      console.log(`⚠️  MCP setup check failed: ${result.error.message}`);
+    }
+    return;
+  }
+
+  if (result.status !== 0) {
+    if (process.env.VERBOSE) {
+      const reason = (result.stderr || result.stdout || '').trim();
+      console.log(`⚠️  MCP setup check failed${reason ? `: ${reason}` : ''}`);
+    }
+    return;
+  }
+
+  const output = `${result.stdout || ''}\n${result.stderr || ''}`;
+  if (!hasAgentfulMcp(output)) {
+    printMissingMcpWarning();
+  }
+})();