@itz4blitz/agentful 1.8.0 → 1.8.1

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/worktree-service.js

@@ -0,0 +1,514 @@
+#!/usr/bin/env node
+
+/**
+ * Git Worktree Service
+ *
+ * Core service for managing git worktrees in agentful.
+ * Provides worktree creation, tracking, and cleanup functions.
+ *
+ * Environment Variables:
+ *   AGENTFUL_WORKTREE_MODE - auto|block|off (default: auto)
+ *   AGENTFUL_WORKTREE_LOCATION - 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)
+ *
+ * Usage:
+ *   node worktree-service.js create <purpose> <branch>
+ *   node worktree-service.js list
+ *   node worktree-service.js cleanup
+ *   node worktree-service.js prune
+ *   node worktree-service.js status
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// Configuration from environment
+const CONFIG = {
+  mode: process.env.AGENTFUL_WORKTREE_MODE || 'auto',
+  location: process.env.AGENTFUL_WORKTREE_LOCATION || '../',
+  autoCleanup: process.env.AGENTFUL_WORKTREE_AUTO_CLEANUP !== 'false',
+  retentionDays: parseInt(process.env.AGENTFUL_WORKTREE_RETENTION_DAYS || '7', 10),
+  maxActive: parseInt(process.env.AGENTFUL_WORKTREE_MAX_ACTIVE || '5', 10),
+};
+
+// Paths
+const REPO_ROOT = findRepoRoot();
+const WORKTREES_DIR = path.join(REPO_ROOT, '.git', 'worktrees');
+const TRACKING_FILE = path.join(REPO_ROOT, '.agentful', 'worktrees.json');
+
+/**
+ * Find git repository root
+ */
+function findRepoRoot() {
+  try {
+    return execSync('git rev-parse --show-toplevel', {
+      encoding: 'utf8',
+      cwd: process.cwd(),
+    }).trim();
+  } catch (error) {
+    console.error('❌ Not in a git repository');
+    process.exit(1);
+  }
+}
+
+/**
+ * Get current git branch
+ */
+function getCurrentBranch() {
+  try {
+    return execSync('git rev-parse --abbrev-ref HEAD', {
+      encoding: 'utf8',
+      cwd: process.cwd(),
+    }).trim();
+  } catch (error) {
+    return 'unknown';
+  }
+}
+
+/**
+ * Get current working directory relative to repo root
+ */
+function getCurrentWorktree() {
+  const cwd = process.cwd();
+  const gitCommonDir = execSync('git rev-parse --git-common-dir', {
+    encoding: 'utf8',
+    cwd,
+  }).trim();
+
+  // If .git is a file, we're in a worktree
+  const gitFile = path.join(cwd, '.git');
+  const isWorktree = fs.existsSync(gitFile) && fs.statSync(gitFile).isFile();
+
+  if (isWorktree) {
+    // Read the worktree path from .git file
+    const gitDir = fs.readFileSync(gitFile, 'utf8').trim();
+    const worktreePath = gitDir.replace('gitdir: ', '').replace('/.git', '');
+    return path.basename(worktreePath);
+  }
+
+  return null;
+}
+
+/**
+ * Sanitize branch name for use in worktree name
+ */
+function sanitizeBranchName(branch) {
+  return branch
+    .replace(/\//g, '-')      // Replace / with -
+    .replace(/[^a-zA-Z0-9-]/g, '')  // Remove special chars
+    .replace(/-+/g, '-')      // Collapse multiple dashes
+    .replace(/^-|-$/g, '');  // Trim leading/trailing dashes
+}
+
+/**
+ * Validate worktree name for security
+ */
+function validateWorktreeName(name) {
+  // Prevent path traversal
+  const resolvedPath = path.resolve(REPO_ROOT, CONFIG.location, name);
+  if (!resolvedPath.startsWith(REPO_ROOT)) {
+    throw new Error('Invalid worktree name: path traversal detected');
+  }
+
+  // Check for valid characters
+  if (!/^[a-zA-Z0-9-]+$/.test(name)) {
+    throw new Error('Invalid worktree name: contains invalid characters');
+  }
+
+  return true;
+}
+
+/**
+ * Get tracked worktrees from .agentful/worktrees.json
+ */
+function getTrackedWorktrees() {
+  try {
+    if (fs.existsSync(TRACKING_FILE)) {
+      const content = fs.readFileSync(TRACKING_FILE, 'utf8');
+      return JSON.parse(content);
+    }
+  } catch (error) {
+    // Invalid tracking file, start fresh
+    console.warn(`⚠️  Corrupted tracking file, starting fresh: ${TRACKING_FILE}`);
+  }
+
+  return { active: [] };
+}
+
+/**
+ * Save tracked worktrees to .agentful/worktrees.json
+ */
+function saveTrackedWorktrees(data) {
+  const dir = path.dirname(TRACKING_FILE);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  fs.writeFileSync(
+    TRACKING_FILE,
+    JSON.stringify(data, null, 2),
+    'utf8'
+  );
+}
+
+/**
+ * Get list of all git worktrees
+ */
+function getGitWorktrees() {
+  try {
+    const output = execSync('git worktree list', {
+      encoding: 'utf8',
+      cwd: REPO_ROOT,
+    });
+
+    return output.trim().split('\n').map(line => {
+      const [worktreePath, commit, branch] = line.split(/\s+/);
+      return {
+        path: worktreePath,
+        commit,
+        branch: branch.replace(/[\[\]]/g, ''), // Remove [ ] brackets
+      };
+    });
+  } catch (error) {
+    return [];
+  }
+}
+
+/**
+ * Check if a branch is already checked out
+ */
+function isBranchCheckedOut(branch) {
+  const worktrees = getGitWorktrees();
+  return worktrees.some(w => w.branch === branch);
+}
+
+/**
+ * Create a unique branch name if original is already checked out
+ */
+function getUniqueBranch(originalBranch, timestamp) {
+  if (!isBranchCheckedOut(originalBranch)) {
+    return originalBranch;
+  }
+
+  // Create unique branch with timestamp
+  const uniqueName = `${originalBranch}-agentful-${timestamp}`;
+  console.log(`⚠️  Branch "${originalBranch}" already checked out`);
+  console.log(`   Creating unique branch: ${uniqueName}`);
+  return uniqueName;
+}
+
+/**
+ * Check disk space
+ */
+function checkDiskSpace(requiredBytes) {
+  try {
+    const stats = fs.statSync(REPO_ROOT);
+    // Note: This is a basic check. For production, use df or similar
+    return true;
+  } catch (error) {
+    console.warn('⚠️  Could not check disk space');
+    return true;
+  }
+}
+
+/**
+ * Create a new worktree
+ */
+function createWorktree(purpose, branch = null) {
+  const timestamp = Date.now();
+  const currentBranch = branch || getCurrentBranch();
+  const sanitizedBranch = sanitizeBranchName(currentBranch);
+
+  // Generate worktree name
+  const worktreeName = `agentful-${purpose}-${sanitizedBranch}-${timestamp}`;
+
+  // Validate
+  validateWorktreeName(worktreeName);
+
+  // Get unique branch if needed
+  const targetBranch = getUniqueBranch(currentBranch, timestamp);
+
+  // Check max active worktrees
+  const tracked = getTrackedWorktrees();
+  if (tracked.active.length >= CONFIG.maxActive) {
+    console.warn(`⚠️  Maximum active worktrees reached (${CONFIG.maxActive})`);
+    console.warn('   Run cleanup first: node worktree-service.js cleanup');
+  }
+
+  // Create worktree
+  const worktreePath = path.join(REPO_ROOT, CONFIG.location, worktreeName);
+
+  try {
+    console.log(`🌳 Creating worktree: ${worktreeName}`);
+    console.log(`   Branch: ${targetBranch}`);
+    console.log(`   Path: ${worktreePath}`);
+
+    execSync(
+      `git worktree add "${worktreePath}" -b "${targetBranch}"`,
+      { cwd: REPO_ROOT, stdio: 'inherit' }
+    );
+
+    // Initialize submodules if present
+    const submodulePath = path.join(worktreePath, '.gitmodules');
+    if (fs.existsSync(submodulePath)) {
+      console.log('   📦 Initializing submodules...');
+      execSync('git submodule update --init --recursive', {
+        cwd: worktreePath,
+        stdio: 'inherit',
+      });
+    }
+
+    // Track the worktree
+    const worktreeData = {
+      name: worktreeName,
+      path: worktreePath,
+      branch: targetBranch,
+      purpose,
+      created_at: new Date().toISOString(),
+      last_activity: new Date().toISOString(),
+    };
+
+    tracked.active.push(worktreeData);
+    saveTrackedWorktrees(tracked);
+
+    console.log(`✅ Worktree created successfully`);
+    console.log(`   Export AGENTFUL_WORKTREE_DIR="${worktreePath}"`);
+
+    // Output worktree path for easy capture
+    console.log(`WORKTREE_PATH=${worktreePath}`);
+
+    return worktreeData;
+  } catch (error) {
+    console.error(`❌ Failed to create worktree: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * List all tracked worktrees
+ */
+function listWorktrees() {
+  const tracked = getTrackedWorktrees();
+  const gitWorktrees = getGitWorktrees();
+
+  console.log('\n📋 Active Worktrees:\n');
+
+  if (tracked.active.length === 0) {
+    console.log('   No active worktrees\n');
+    return;
+  }
+
+  tracked.active.forEach(w => {
+    const gitWt = gitWorktrees.find(gw => gw.path === w.path);
+    const exists = !!gitWt;
+    const ageMs = Date.now() - new Date(w.created_at).getTime();
+    const ageMins = Math.floor(ageMs / 60000);
+
+    let status = exists ? '🟢 Active' : '🔴 Orphaned';
+    if (ageMins > 60) status = '🟡 Stale';
+
+    console.log(`┌─────────────────────────────────────────────────────────────┐`);
+    console.log(`│ ${w.name}`);
+    console.log(`│ ├─ Branch: ${w.branch}`);
+    console.log(`│ ├─ Purpose: ${w.purpose}`);
+    console.log(`│ ├─ Path: ${w.path}`);
+    console.log(`│ ├─ Status: ${status} (${ageMins} min ago)`);
+    console.log(`│ └─ Created: ${w.created_at}`);
+    console.log(`└─────────────────────────────────────────────────────────────┘`);
+  });
+
+  console.log('');
+}
+
+/**
+ * Get status of current session
+ */
+function getStatus() {
+  const currentWorktree = getCurrentWorktree();
+  const tracked = getTrackedWorktrees();
+
+  if (currentWorktree) {
+    const wt = tracked.active.find(w => w.name === currentWorktree);
+    if (wt) {
+      console.log(`\n🌳 Current worktree: ${wt.name}`);
+      console.log(`   Branch: ${wt.branch}`);
+      console.log(`   Purpose: ${wt.purpose}`);
+      console.log(`   Path: ${wt.path}\n`);
+    } else {
+      console.log(`\n⚠️  In untracked worktree: ${currentWorktree}`);
+      console.log(`   Worktree exists but not tracked by agentful\n`);
+    }
+  } else {
+    console.log('\n📍 Working in root repository');
+    console.log('   No active worktree for this session\n');
+  }
+
+  console.log(`Mode: ${CONFIG.mode}`);
+  console.log(`Location: ${CONFIG.location}`);
+  console.log(`Auto-cleanup: ${CONFIG.autoCleanup ? 'enabled' : 'disabled'}`);
+  console.log(`Max active: ${CONFIG.maxActive}\n`);
+}
+
+/**
+ * Cleanup stale worktrees
+ */
+function cleanupWorktrees() {
+  const tracked = getTrackedWorktrees();
+  const now = Date.now();
+  const retentionMs = CONFIG.retentionDays * 24 * 60 * 60 * 1000;
+  let cleanedCount = 0;
+
+  console.log(`\n🧹 Cleaning up worktrees older than ${CONFIG.retentionDays} days...\n`);
+
+  const active = tracked.active.filter(w => {
+    const age = now - new Date(w.created_at).getTime();
+    const isStale = age > retentionMs;
+
+    if (isStale) {
+      console.log(`🗑️  Removing stale: ${w.name}`);
+      try {
+        execSync(`git worktree remove "${w.path}"`, {
+          cwd: REPO_ROOT,
+          stdio: 'inherit',
+        });
+        cleanedCount++;
+      } catch (error) {
+        console.warn(`   ⚠️  Failed to remove: ${error.message}`);
+      }
+    }
+
+    return !isStale; // Keep only non-stale
+  });
+
+  // Save updated tracking
+  saveTrackedWorktrees({ active });
+
+  // Also run git prune to clean metadata
+  console.log('\n🧹 Pruning git worktree metadata...');
+  try {
+    execSync('git worktree prune', { cwd: REPO_ROOT, stdio: 'inherit' });
+  } catch (error) {
+    console.warn(`   ⚠️  Prune warning: ${error.message}`);
+  }
+
+  console.log(`\n✅ Cleanup complete. Removed ${cleanedCount} worktree(s).\n`);
+}
+
+/**
+ * Prune git worktree metadata
+ */
+function pruneWorktrees() {
+  console.log('\n🧹 Pruning git worktree metadata...\n');
+  try {
+    execSync('git worktree prune', { cwd: REPO_ROOT, stdio: 'inherit' });
+    console.log('✅ Prune complete\n');
+  } catch (error) {
+    console.error(`❌ Prune failed: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Remove a specific worktree
+ */
+function removeWorktree(worktreeName) {
+  const tracked = getTrackedWorktrees();
+  const worktree = tracked.active.find(w => w.name === worktreeName);
+
+  if (!worktree) {
+    console.error(`❌ Worktree not found: ${worktreeName}`);
+    process.exit(1);
+  }
+
+  try {
+    console.log(`🗑️  Removing worktree: ${worktreeName}`);
+    execSync(`git worktree remove "${worktree.path}"`, {
+      cwd: REPO_ROOT,
+      stdio: 'inherit',
+    });
+
+    // Remove from tracking
+    const active = tracked.active.filter(w => w.name !== worktreeName);
+    saveTrackedWorktrees({ active });
+
+    console.log('✅ Worktree removed\n');
+  } catch (error) {
+    console.error(`❌ Failed to remove worktree: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+/**
+ * Detect if running in CI environment
+ */
+function isCIEnvironment() {
+  return process.env.CI === 'true' ||
+         process.env.GITHUB_ACTIONS === 'true' ||
+         process.env.GITLAB_CI === 'true' ||
+         process.env.CIRCLECI === 'true';
+}
+
+// CLI interface
+const command = process.argv[2];
+const args = process.argv.slice(3);
+
+// Auto-disable worktree mode in CI
+if (isCIEnvironment()) {
+  console.log('🤖 CI environment detected. Worktree mode auto-disabled.\n');
+  process.exit(0);
+}
+
+switch (command) {
+  case 'create':
+    if (args.length < 1) {
+      console.error('Usage: worktree-service.js create <purpose> [branch]');
+      console.error('Example: worktree-service.js create feature feature/auth');
+      process.exit(1);
+    }
+    createWorktree(args[0], args[1]);
+    break;
+
+  case 'list':
+    listWorktrees();
+    break;
+
+  case 'status':
+    getStatus();
+    break;
+
+  case 'cleanup':
+    cleanupWorktrees();
+    break;
+
+  case 'prune':
+    pruneWorktrees();
+    break;
+
+  case 'remove':
+    if (args.length < 1) {
+      console.error('Usage: worktree-service.js remove <worktree-name>');
+      process.exit(1);
+    }
+    removeWorktree(args[0]);
+    break;
+
+  default:
+    console.log('Git Worktree Service for agentful\n');
+    console.log('Usage: node worktree-service.js <command> [args]\n');
+    console.log('Commands:');
+    console.log('  create <purpose> [branch]  Create a new worktree');
+    console.log('  list                        List all tracked worktrees');
+    console.log('  status                      Show current worktree status');
+    console.log('  cleanup                     Remove stale worktrees');
+    console.log('  prune                       Prune git worktree metadata');
+    console.log('  remove <name>              Remove specific worktree\n');
+    console.log(`Environment: AGENTFUL_WORKTREE_MODE=${CONFIG.mode}`);
+    process.exit(0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "1.8.0",
+  "version": "1.8.1",
   "description": "Pre-configured AI toolkit with self-hosted execution - works with any LLM, any tech stack, any platform.",
   "type": "module",
   "bin": {
@@ -79,6 +79,7 @@
     "@vitest/coverage-v8": "^1.2.0",
     "eslint": "^9.39.2",
     "semantic-release": "^25.0.2",
+    "vite-plugin-pagefind": "^1.0.7",
     "vitest": "^1.2.0",
     "vocs": "^1.4.1"
   },

package/template/.claude/agents/backend.md

@@ -48,6 +48,25 @@ You are the **Backend Agent**. You implement server-side code using clean archit
 
 **Reference skills for tech-specific guidance:**
 - Look in `.claude/skills/` for framework-specific patterns
+
+## Step 1.5: Worktree Check
+
+Before implementing, verify your working environment:
+
+```bash
+# Check if AGENTFUL_WORKTREE_DIR is set
+if exists("$AGENTFUL_WORKTREE_DIR"):
+    worktree_path = "$AGENTFUL_WORKTREE_DIR"
+    echo "✅ Implementing backend in worktree: $worktree_path"
+else:
+    echo "📍 Implementing backend in root repository"
+    echo "⚠️  Changes will affect main branch directly"
+```
+
+**Report worktree status**: In your final report, always include:
+- Worktree path (if applicable)
+- Branch being worked on
+- Any commits created
 - Skills contain project-specific conventions, not generic framework docs
 
 **Sample existing code to understand conventions:**

package/template/.claude/agents/frontend.md

@@ -53,6 +53,25 @@ You are the **Frontend Agent**. You implement user interfaces and client-side co
 
 **Reference skills for tech-specific guidance:**
 - Look in `.claude/skills/` for framework-specific patterns
+
+## Step 1.5: Worktree Check
+
+Before implementing, verify your working environment:
+
+```bash
+# Check if AGENTFUL_WORKTREE_DIR is set
+if exists("$AGENTFUL_WORKTREE_DIR"):
+    worktree_path = "$AGENTFUL_WORKTREE_DIR"
+    echo "✅ Implementing frontend in worktree: $worktree_path"
+else:
+    echo "📍 Implementing frontend in root repository"
+    echo "⚠️  Changes will affect main branch directly"
+```
+
+**Report worktree status**: In your final report, always include:
+- Worktree path (if applicable)
+- Branch being worked on
+- Any commits created
 - Skills contain project-specific conventions (styling, state management, forms)
 
 **Sample existing code to understand conventions:**

package/template/.claude/agents/orchestrator.md

@@ -456,6 +456,188 @@ else:
 }
 ```
 
+## Worktree Management
+
+Git worktrees provide isolated environments for parallel agent development. Each task can work in its own worktree without polluting the main repository.
+
+### Why Worktrees?
+
+- **Isolation**: Changes are isolated until merged
+- **Parallel Development**: Multiple agents can work simultaneously
+- **Safety**: Experimental changes don't affect main branch
+- **Clean History**: Each worktree has its own git history
+
+### Worktree Modes
+
+Controlled via `AGENTFUL_WORKTREE_MODE` environment variable:
+
+| Mode | Behavior | When to Use |
+|-------|-----------|--------------|
+| `auto` | Create worktrees automatically | Default, recommended |
+| `block` | Require existing worktree | Strict environments |
+| `off` | Allow direct edits | Legacy, manual control |
+
+### Before Delegation: Worktree Setup
+
+Before delegating to any specialist agent:
+
+```bash
+# Check worktree mode
+if AGENTFUL_WORKTREE_MODE != "off":
+    # Check if we need a worktree
+    current_worktree = get_current_worktree()
+
+    if not current_worktree:
+        # Determine purpose from task type
+        purpose = determine_worktree_purpose(task_type)
+
+        # Create worktree via worktree-service
+        worktree = execute("node bin/hooks/worktree-service.js create " + purpose)
+
+        # Set environment for delegated agents
+        # They inherit AGENTFUL_WORKTREE_DIR
+        current_worktree = worktree
+
+    # Track in state.json
+    state.current_worktree = {
+        name: worktree.name,
+        path: worktree.path,
+        branch: worktree.branch,
+        purpose: worktree.purpose,
+        created_at: worktree.created_at
+    }
+```
+
+### Worktree Naming Convention
+
+Worktrees are automatically named:
+
+```
+agentful-<purpose>-<branch-slug>-<timestamp>
+```
+
+Examples:
+- `agentful-feature-auth-1739297120` - Feature development
+- `agentful-fix-coverage-1739297150` - Fixer adding coverage
+- `agentful-review-1739297180` - Reviewer validating
+- `agentful-hotfix-login-bug-1739297210` - Hotfix work
+
+### State Schema Extension
+
+Track worktrees in `.agentful/state.json`:
+
+```json
+{
+  "current_task": "feature/auth",
+  "current_phase": "implementation",
+  "current_worktree": {
+    "name": "agentful-feature-auth-1739297120",
+    "path": "/Users/dev/project/.git/worktrees/agentful-feature-auth-1739297120",
+    "branch": "feature/auth",
+    "purpose": "feature",
+    "created_at": "2025-02-11T15:30:00Z"
+  },
+  "worktrees": {
+    "active": [
+      {
+        "name": "agentful-feature-auth-1739297120",
+        "branch": "feature/auth",
+        "purpose": "feature",
+        "agent": "orchestrator",
+        "created_at": "2025-02-11T15:30:00Z",
+        "last_activity": "2025-02-11T16:45:00Z"
+      }
+    ]
+  }
+}
+```
+
+### After Task Completion: Worktree Cleanup
+
+When a feature passes all quality gates:
+
+```bash
+if task_completed and AGENTFUL_WORKTREE_AUTO_CLEANUP != "false":
+    # Commit changes in worktree
+    git -C $WORKTREE_PATH add .
+    git -C $WORKTREE_PATH commit -m "feat: complete ${feature_name}"
+
+    # Ask user what to do next
+    response = AskUserQuestion(
+        "Feature complete! What would you like to do?",
+        options: [
+            "Create PR",
+            "Merge to main",
+            "Keep worktree for review",
+            "Clean up worktree"
+        ]
+    )
+
+    if response == "Create PR" or response == "Merge to main":
+        # Push and create PR/merge
+        git -C $WORKTREE_PATH push
+        # ... PR creation logic ...
+
+    # Remove worktree
+    execute("node bin/hooks/worktree-service.js remove " + worktree.name)
+
+    # Update state.json
+    state.current_worktree = null
+```
+
+### Handling Interruptions
+
+If user interrupts during worktree operation:
+
+```bash
+on SIGINT:
+    if active_worktree:
+        # Mark for review instead of deleting
+        state.interrupted_worktree = {
+            name: active_worktree.name,
+            path: active_worktree.path,
+            interrupted_at: new Date().toISOString()
+        }
+
+        console.log("Worktree preserved: " + active_worktree.name)
+        console.log("Run /agentful-worktree --resume to continue")
+        console.log("Run /agentful-worktree --cleanup to remove")
+```
+
+### Worktree Service API
+
+The `worktree-service.js` provides these operations:
+
+```bash
+node bin/hooks/worktree-service.js create <purpose> [branch]  # Create worktree
+node bin/hooks/worktree-service.js list                    # List all worktrees
+node bin/hooks/worktree-service.js status                  # Show current status
+node bin/hooks/worktree-service.js cleanup                # Remove stale worktrees
+node bin/hooks/worktree-service.js prune                 # Run git prune
+node bin/hooks/worktree-service.js remove <name>         # Remove specific worktree
+```
+
+### Environment Variables
+
+| Variable | Default | Description |
+|-----------|----------|-------------|
+| `AGENTFUL_WORKTREE_MODE` | `auto` | Worktree enforcement mode |
+| `AGENTFUL_WORKTREE_DIR` | (auto-set) | Current worktree path |
+| `AGENTFUL_WORKTREE_LOCATION` | `../` | Where to create worktrees |
+| `AGENTFUL_WORKTREE_AUTO_CLEANUP` | `true` | Auto-remove after completion |
+| `AGENTFUL_WORKTREE_RETENTION_DAYS` | `7` | Days before stale cleanup |
+| `AGENTFUL_WORKTREE_MAX_ACTIVE` | `5` | Maximum active worktrees |
+
+### CI/CD Detection
+
+Worktree mode auto-disables in CI environments:
+
+```bash
+if process.env.CI == "true" or process.env.GITHUB_ACTIONS == "true":
+    # Skip worktree creation
+    # CI already provides isolated environments
+```
+
 ## Delegation Pattern
 
 **NEVER implement yourself.** Always use Task tool.

package/template/.claude/agents/reviewer.md

@@ -38,6 +38,24 @@ Fall back to manual Grep if none available
 
 **Reference the validation skill** (`.claude/skills/validation/SKILL.md`) for comprehensive validation strategies.
 
+## Step 1.5: Worktree Check
+
+Before running checks, verify your working environment:
+
+```bash
+# Check if AGENTFUL_WORKTREE_DIR is set
+if exists("$AGENTFUL_WORKTREE_DIR"):
+    worktree_path = "$AGENTFUL_WORKTREE_DIR"
+    echo "✅ Reviewing in worktree: $worktree_path"
+else:
+    echo "📍 Reviewing in root repository"
+    echo "⚠️  Validation reports will be saved to main .agentful/"
+```
+
+**Report worktree status**: In your validation report, always include:
+- Worktree path (if applicable)
+- Branch being validated
+
 ## Your Scope
 
 - **Type Checking** - Run type checker (tsc, mypy, etc.)

package/template/.claude/commands/agentful-worktree.md

@@ -0,0 +1,106 @@
+---
+name: agentful-worktree
+description: Manage git worktrees for parallel agent development. List, create, and cleanup worktrees.
+---
+
+# /agentful-worktree
+
+Manage git worktrees for parallel agentful development.
+
+## Usage
+
+```bash
+/agentful-worktree                    # List all active worktrees
+/agentful-worktree --status           # Show current session worktree
+/agentful-worktree --create feature/x  # Create new worktree for branch
+/agentful-worktree --cleanup          # Remove stale worktrees
+/agentful-worktree --prune           # Run git worktree prune
+/agentful-worktree --remove <name>    # Remove specific worktree
+```
+
+## Environment Variables
+
+| Variable | Default | Description |
+|-----------|----------|-------------|
+| `AGENTFUL_WORKTREE_MODE` | `auto` | `auto` (create), `block` (require), `off` (disabled) |
+| `AGENTFUL_WORKTREE_LOCATION` | `../` | Where to create worktrees (relative to repo) |
+| `AGENTFUL_WORKTREE_AUTO_CLEANUP` | `true` | Auto-remove worktrees after task completion |
+| `AGENTFUL_WORKTREE_RETENTION_DAYS` | `7` | Days before worktrees are marked stale |
+| `AGENTFUL_WORKTREE_MAX_ACTIVE` | `5` | Maximum active worktrees before cleanup forced |
+
+## Examples
+
+### List Worktrees
+
+```
+/agentful-worktree
+```
+
+Output:
+```
+📋 Active Worktrees:
+
+┌─────────────────────────────────────────────────────────────┐
+│ agentful-feature-auth-1739297120                │
+│ ├─ Branch: feature/auth                             │
+│ ├─ Purpose: feature                                │
+│ ├─ Path: ../agentful-feature-auth-1739297120       │
+│ ├─ Status: 🟢 Active (15 min ago)                │
+│ └─ Created: 2025-02-11T15:30:00.000Z            │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Show Current Status
+
+```
+/agentful-worktree --status
+```
+
+### Create Worktree
+
+```
+/agentful-worktree --create feature/dashboard
+```
+
+Creates a worktree named `agentful-feature-dashboard-<timestamp>` on the `feature/dashboard` branch.
+
+### Cleanup Stale Worktrees
+
+```
+/agentful-worktree --cleanup
+```
+
+Removes worktrees older than `AGENTFUL_WORKTREE_RETENTION_DAYS` (default: 7 days).
+
+## Worktree Naming Convention
+
+Worktrees are automatically named using this pattern:
+
+```
+agentful-<purpose>-<branch-slug>-<timestamp>
+```
+
+Examples:
+- `agentful-feature-auth-1739297120` - Feature development
+- `agentful-fix-coverage-1739297150` - Fixer adding coverage
+- `agentful-review-1739297180` - Reviewer validating
+- `agentful-hotfix-login-bug-1739297210` - Hotfix work
+
+## When to Use Worktrees
+
+**Use worktrees when**:
+- Working on multiple features simultaneously
+- Running quality gates while developing other features
+- Reviewing PRs without interrupting active work
+- Testing experimental approaches safely
+
+**Don't need worktrees when**:
+- Quick fixes in a single feature branch
+- Documentation-only changes
+- Set `AGENTFUL_WORKTREE_MODE=off` to disable
+
+## See Also
+
+- [Git Worktrees Concept](/concepts/git-worktrees) - Deep dive on worktree usage
+- [/agentful-start](/commands/agentful-start) - Main development loop
+- [/agentful-status](/commands/agentful-status) - Check completion progress

package/template/.claude/settings.json

@@ -1,7 +1,8 @@
 {
   "includeCoAuthoredBy": false,
   "env": {
-    "ENABLE_TOOL_SEARCH": "true"
+    "ENABLE_TOOL_SEARCH": "true",
+    "AGENTFUL_WORKTREE_MODE": "auto"
   },
   "hooks": {
     "SessionStart": [
@@ -23,6 +24,17 @@
       }
     ],
     "PreToolUse": [
+      {
+        "tools": ["Write", "Edit"],
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node bin/hooks/ensure-worktree.js",
+            "timeout": 10,
+            "description": "Ensure agents work in git worktrees (disable with AGENTFUL_WORKTREE_MODE=off)"
+          }
+        ]
+      },
       {
         "tools": ["Write", "Edit"],
         "hooks": [

package/template/CLAUDE.md

@@ -199,6 +199,33 @@ The `reviewer` agent runs these checks automatically. The `fixer` agent resolves
 - Estimated remaining work
 → If no progress for 2+ minutes, the task may be stuck. Check `.agentful/state.json` for circuit breaker status.
 
+### Git Worktree Mode
+
+agentful supports automatic git worktree management for safer parallel development.
+
+**Modes**:
+| Mode | Behavior |
+|-------|-----------|
+| `auto` | Create worktrees automatically when agents make changes (recommended) |
+| `block` | Require agents to work in existing worktrees |
+| `off` | Allow direct edits to root repository (legacy) |
+
+**Enable via environment**:
+```bash
+export AGENTFUL_WORKTREE_MODE=auto
+```
+
+**Or in `.claude/settings.json`**:
+```json
+{
+  "env": {
+    "AGENTFUL_WORKTREE_MODE": "auto"
+  }
+}
+```
+
+**More configuration**: See [/agentful-worktree](/commands/agentful-worktree) command and [Git Worktrees concept](/concepts/git-worktrees) for full details.
+
 ## Getting Help
 
 **Documentation**: See `.claude/commands/` for detailed command documentation

package/version.json

@@ -1,3 +1,3 @@
 {
-  "version": "1.7.0"
+  "version": "1.8.0"
 }