@itz4blitz/agentful 1.8.1 → 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/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();
+  }
+})();

package/bin/hooks/package-metadata-guard.js

@@ -0,0 +1,118 @@
+#!/usr/bin/env node
+
+/**
+ * Package Metadata Guard Hook
+ *
+ * Protects package.json metadata from accidental ownership corruption.
+ *
+ * Catches:
+ * - repository.type being changed away from "git"
+ * - repository.url being changed to github.com/itz4blitz/* in repos owned by someone else
+ *
+ * Run: PostToolUse (Write|Edit)
+ * Action: Exit non-zero so the agent corrects the change immediately.
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+const AGENTFUL_OWNER = 'itz4blitz';
+
+function getOriginOwner() {
+  try {
+    const remote = execSync('git config --get remote.origin.url', {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim();
+
+    if (!remote) return null;
+
+    const httpsMatch = remote.match(/github\.com[:/]+([^/]+)\/[^/]+(?:\.git)?$/i);
+    if (httpsMatch?.[1]) {
+      return httpsMatch[1].toLowerCase();
+    }
+
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function resolveFilePath(filePath) {
+  if (!filePath) return null;
+  return path.isAbsolute(filePath) ? filePath : path.join(process.cwd(), filePath);
+}
+
+function isPackageJsonTarget(filePath) {
+  if (!filePath) return false;
+  const normalized = filePath.replace(/\\/g, '/');
+  return path.basename(normalized) === 'package.json' && !normalized.includes('/node_modules/');
+}
+
+function inspectPackageMetadata(packageJsonPath, originOwner) {
+  const issues = [];
+
+  let pkg;
+  try {
+    pkg = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  } catch {
+    return issues;
+  }
+
+  if (!pkg.repository || typeof pkg.repository !== 'object') {
+    return issues;
+  }
+
+  const repoType = pkg.repository.type;
+  if (typeof repoType === 'string' && repoType.trim().toLowerCase() !== 'git') {
+    issues.push(`repository.type is "${repoType}" (expected "git")`);
+  }
+
+  const repoUrl = pkg.repository.url;
+  if (typeof repoUrl === 'string') {
+    const ownerInUrl = repoUrl.match(/github\.com[:/]+([^/]+)\//i)?.[1]?.toLowerCase();
+    if (ownerInUrl === AGENTFUL_OWNER && originOwner && originOwner !== AGENTFUL_OWNER) {
+      issues.push(`repository.url points to "${AGENTFUL_OWNER}" but git remote owner is "${originOwner}"`);
+    }
+  }
+
+  return issues;
+}
+
+function main() {
+  const filePath = process.env.FILE || '';
+  const toolName = process.env.TOOL_NAME || '';
+
+  if (toolName !== 'Write' && toolName !== 'Edit') {
+    process.exit(0);
+  }
+
+  if (!isPackageJsonTarget(filePath)) {
+    process.exit(0);
+  }
+
+  const absolutePath = resolveFilePath(filePath);
+  if (!absolutePath || !fs.existsSync(absolutePath)) {
+    process.exit(0);
+  }
+
+  const originOwner = getOriginOwner();
+  const issues = inspectPackageMetadata(absolutePath, originOwner);
+
+  if (issues.length === 0) {
+    process.exit(0);
+  }
+
+  console.error('\n❌ BLOCKED: Suspicious package.json metadata change\n');
+  console.error(`File: ${filePath}`);
+  for (const issue of issues) {
+    console.error(`- ${issue}`);
+  }
+  console.error('\nExpected behavior: preserve project ownership metadata and keep repository.type as "git".');
+  console.error('Action: restore the package.json metadata to match the current project repository.\n');
+
+  process.exit(1);
+}
+
+main();

package/bin/hooks/session-start.js

@@ -29,15 +29,42 @@ try {
 
 /**
  * Detect if TeammateTool (parallel execution) is enabled
+ * Supports Windows, macOS, and Linux
  */
 function detectParallelExecution() {
+  // Check environment variable first (user can set AGENTFUL_PARALLEL=true)
+  if (process.env.AGENTFUL_PARALLEL === 'true') {
+    return { enabled: true, method: 'env_var' };
+  }
+
   try {
-    // Find Claude Code binary
-    const npmRoot = execSync('npm root -g', { encoding: 'utf8' }).trim();
-    const cliPath = path.join(npmRoot, '@anthropic-ai', 'claude-code', 'cli.js');
+    // Find Claude Code binary - try multiple paths for Windows/Unix
+    let cliPath = null;
+    const possiblePaths = [
+      // Unix npm global
+      '/usr/local/lib/node_modules/@anthropic-ai/claude-code/cli.js',
+      // Homebrew on macOS
+      '/opt/homebrew/lib/node_modules/@anthropic-ai/claude-code/cli.js',
+    ];
+
+    // npm root -g can throw on Windows if npm isn't in PATH
+    try {
+      const npmRoot = execSync('npm root -g', { encoding: 'utf8' }).trim();
+      possiblePaths.unshift(path.join(npmRoot, '@anthropic-ai', 'claude-code', 'cli.js'));
+    } catch {
+      // npm not available - continue with static paths
+    }
+
+    for (const p of possiblePaths) {
+      if (fs.existsSync(p)) {
+        cliPath = p;
+        break;
+      }
+    }
 
-    if (!fs.existsSync(cliPath)) {
-      return { enabled: false, reason: 'Claude Code binary not found' };
+    if (!cliPath) {
+      // Assume enabled if we can't find CLI (newer versions have it by default)
+      return { enabled: true, method: 'assumed' };
     }
 
     // Check for TeammateTool pattern

package/lib/presets.js

@@ -19,7 +19,7 @@ export const presets = {
     description: 'Complete agentful installation (recommended)',
     agents: ['orchestrator', 'architect', 'backend', 'frontend', 'tester', 'reviewer', 'fixer', 'product-analyzer'],
     skills: ['product-tracking', 'validation', 'testing', 'conversation', 'product-planning', 'deployment', 'research'],
-    hooks: ['session-start', 'health-check', 'block-random-docs', 'block-file-creation', 'product-spec-watcher', 'architect-drift-detector', 'analyze-trigger'],
+    hooks: ['session-start', 'health-check', 'mcp-health-check', 'block-random-docs', 'block-file-creation', 'product-spec-watcher', 'architect-drift-detector', 'analyze-trigger', 'package-metadata-guard'],
     gates: ['types', 'tests', 'coverage', 'lint', 'security', 'dead-code']
   },
 
@@ -47,6 +47,16 @@ export const hookConfigurations = {
     }
   },
 
+  'mcp-health-check': {
+    event: 'SessionStart',
+    config: {
+      type: 'command',
+      command: 'node bin/hooks/mcp-health-check.js',
+      timeout: 3,
+      description: 'Verify agentful MCP server is configured'
+    }
+  },
+
   'block-random-docs': {
     event: 'PreToolUse',
     matcher: 'Write',
@@ -151,6 +161,17 @@ export const hookConfigurations = {
       timeout: 3,
       description: 'Watch for product spec changes and auto-trigger generation'
     }
+  },
+
+  'package-metadata-guard': {
+    event: 'PostToolUse',
+    matcher: 'Write|Edit',
+    config: {
+      type: 'command',
+      command: 'node bin/hooks/package-metadata-guard.js',
+      timeout: 3,
+      description: 'Protect package.json ownership metadata from accidental corruption'
+    }
   }
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@itz4blitz/agentful",
-  "version": "1.8.1",
+  "version": "1.8.2",
   "description": "Pre-configured AI toolkit with self-hosted execution - works with any LLM, any tech stack, any platform.",
   "type": "module",
   "bin": {
@@ -16,16 +16,14 @@
     "lint": "eslint .",
     "release": "semantic-release",
     "release:dry-run": "semantic-release --dry-run",
-    "docs:dev": "vocs dev",
+    "docs:dev": "vocs dev --host 127.0.0.1 --port 8080",
     "docs:build": "vocs build",
     "docs:preview": "vocs preview",
-    "build:all": "npm run build:cli && npm run build:studio && npm run build:mcp",
-    "build:cli": "cd packages/cli && npm run build",
-    "build:studio": "cd packages/studio && npm run build",
+    "build:all": "npm run build:mcp",
     "build:mcp": "cd packages/mcp-server && npm run build",
-    "dev:studio": "cd packages/studio && npm run dev",
-    "watch:studio": "cd packages/studio && npm run watch",
-    "install:all": "npm install && cd packages/cli && npm install && cd ../studio && npm install && cd ../mcp-server && npm install && cd ../shared && npm install"
+    "test:mcp": "cd packages/mcp-server && npm run test",
+    "dev:mcp": "cd packages/mcp-server && npm run dev",
+    "install:all": "npm install && cd packages/mcp-server && npm install"
   },
   "exports": {
     ".": {

package/template/.claude/settings.json

@@ -25,7 +25,7 @@
     ],
     "PreToolUse": [
       {
-        "tools": ["Write", "Edit"],
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -36,7 +36,7 @@
         ]
       },
       {
-        "tools": ["Write", "Edit"],
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -47,7 +47,7 @@
         ]
       },
       {
-        "tools": ["Write"],
+        "matcher": "Write",
         "hooks": [
           {
             "type": "command",
@@ -60,7 +60,7 @@
     ],
     "PostToolUse": [
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -71,7 +71,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -82,7 +82,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -93,7 +93,18 @@
         ]
       },
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node bin/hooks/package-metadata-guard.js",
+            "timeout": 3,
+            "description": "Protect package.json ownership metadata from accidental corruption"
+          }
+        ]
+      },
+      {
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -102,7 +113,7 @@
         ]
       },
       {
-        "matcher": "Write|Edit",
+        "matcher": "Write|Edit|NotebookEdit",
         "hooks": [
           {
             "type": "command",
@@ -132,4 +143,4 @@
       "Bash(mkfs:*)"
     ]
   }
-}
+}

package/template/CLAUDE.md

@@ -20,7 +20,7 @@ npx @itz4blitz/agentful init --agents=orchestrator,backend --skills=validation
 npx @itz4blitz/agentful presets
 ```
 
-**[agentful.app/configure](https://agentful.app/configure)** - Interactive web configurator for shareable configurations
+Use `npx @itz4blitz/agentful presets` to see local installation options.
 
 ## Quick Start
 
@@ -78,6 +78,15 @@ Without MCP: agents start from scratch every session. With MCP: agents compound
 
 See [Hooks System](#hooks-system) below for manual setup or other editors.
 
+## Metadata Safety (Critical)
+
+When editing `package.json` (or other repo metadata files), preserve project ownership:
+
+- Never change `repository.url`, `homepage`, `bugs.url`, `name` scope, or `author` to agentful maintainer values unless the project explicitly asks.
+- Keep `repository.type` as `"git"` when a `repository` object exists.
+- Do not infer repo owner from agentful package names/docs (`@itz4blitz/agentful`); derive owner from the current repository remote instead.
+- Prefer structured JSON edits (JSON path / `jq` / `npm pkg`) instead of broad text replace on `"type"` or `"url"`.
+
 ## Commands
 
 | Command | Description | When to Use |
@@ -286,7 +295,6 @@ Agentful uses Claude Code hooks for automation, protection, and intelligent cont
   - ✅ `.claude/skills/*/SKILL.md` - Skill documentation
   - ✅ `.claude/product/**/*.md` - Product specifications
   - ✅ `template/**/*.md` - Template files
-  - ✅ `examples/**/*.md` - Example documentation
 - **Allowed if parent directory exists**:
   - 📁 `docs/*.md`, `docs/pages/*.mdx` - Requires `docs/` directory
   - 📁 `documentation/*.md` - Requires `documentation/` directory

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

@@ -16,7 +16,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

package/version.json

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