@agentic15.com/agentic15-claude-zen 3.2.0 → 3.3.0

package/README.md

@@ -18,22 +18,54 @@ npx @agentic15.com/agentic15-claude-zen my-project
 npx "@agentic15.com/agentic15-claude-zen" my-project
 ```
 
-**Step 2: Use CLI Inside Project**
+**Step 2: Navigate Into Project**
 ```bash
 cd my-project
-npx agentic15 auth                    # One-time GitHub setup
-npx agentic15 plan                    # Enter interactive mode
+```
+
+**Step 3: Launch Claude Code from Inside Project Directory**
+
+Start Claude Code CLI from inside the `my-project` directory. Claude Code MUST be running from inside your project directory to access the framework files.
+
+**Step 4: Configure Repository Settings (Recommended)**
+```bash
+# Prevent direct pushes to main - require PRs for all changes
+gh api repos/OWNER/REPO/branches/main/protection -X PUT \
+  -H "Accept: application/vnd.github+json" \
+  -f required_pull_request_reviews[required_approving_review_count]=0 \
+  -f enforce_admins=false \
+  -f allow_force_pushes=false \
+  -f allow_deletions=false
+
+# Auto-delete branches after PR merge
+gh api repos/OWNER/REPO -X PATCH \
+  -H "Accept: application/vnd.github+json" \
+  -f delete_branch_on_merge=true
+```
+Replace `OWNER/REPO` with your GitHub username and repository name.
+
+**Step 5: Use Framework Commands**
+```bash
+npx agentic15 auth                         # One-time GitHub setup
+npx agentic15 plan                         # Enter interactive mode
 # Type/paste your requirements, press Ctrl+D when done
-npx agentic15 task next               # Start first task
-npx agentic15 commit                  # Test, commit, push, PR
+# Open another terminal. Make sure that you in your project directory. Launch Claude
+# Ask Claude: "Read the requirements file and generate a task breakdown plan"
+npx agentic15 task next                    # Start first task
+# Ask Claude: "Implement this task"
+npx agentic15 commit                       # Test, commit, push, PR
 ```
 
-> **Note**: Project creation uses the full package name `@agentic15.com/agentic15-claude-zen`.
-> Once inside your project, use the short command `agentic15` for all workflows.
->
-> **Tip**: `npx agentic15 plan` without arguments enters interactive mode where you can
-> paste long requirements, URLs, and detailed specs. Press Ctrl+D (Mac/Linux) or
-> Ctrl+Z+Enter (Windows) to save.
+> **IMPORTANT**: Always launch Claude Code from inside your project directory, not from the parent directory. The framework relies on `.claude/` configuration files that must be accessible from the working directory.
+
+**Step 6: Clean Up Local Branches**
+```bash
+# If auto-delete is enabled, only clean up local branches
+git branch -d feature/task-001
+
+# For repositories without auto-delete, also delete remote
+git push origin --delete feature/task-001
+```
 
 **See [WORKFLOWS.md](WORKFLOWS.md) for complete workflows.**
 
@@ -45,8 +77,8 @@ npx agentic15 commit                  # Test, commit, push, PR
 - `npx agentic15 plan` - Generate and lock plans
 - `npx agentic15 task next` - Start next task
 - `npx agentic15 commit` - Test + commit + push + PR
+- `npx agentic15 visual-test <url>` - Capture screenshots & console errors
 - `npx agentic15 status` - Check progress
-- `npx agentic15 upgrade` - Upgrade framework files
 - `npm test` - Run tests
 
 **Automates:**

package/bin/agentic15.js

@@ -1,57 +1,65 @@
-#!/usr/bin/env node
-
-import { Command } from 'commander';
-import { AuthCommand } from '../src/cli/AuthCommand.js';
-import { TaskCommand } from '../src/cli/TaskCommand.js';
-import { CommitCommand } from '../src/cli/CommitCommand.js';
-import { StatusCommand } from '../src/cli/StatusCommand.js';
-import { PlanCommand } from '../src/cli/PlanCommand.js';
-import { UpgradeCommand } from '../src/cli/UpgradeCommand.js';
-
-const program = new Command();
-
-program
-  .name('agentic15')
-  .description('Agentic15 Claude Zen - Automated AI development workflow')
-  .version('2.0.0');
-
-// GitHub authentication setup
-program
-  .command('auth')
-  .description('GitHub authentication setup')
-  .action(() => AuthCommand.setup());
-
-// Task management
-program
-  .command('task')
-  .description('Task management')
-  .argument('<action>', 'Action: start, next, status')
-  .argument('[taskId]', 'Task ID (e.g., TASK-001) - required for "start"')
-  .action((action, taskId) => TaskCommand.handle(action, taskId));
-
-// Auto-commit workflow
-program
-  .command('commit')
-  .description('Run tests, commit, push, create PR')
-  .action(() => CommitCommand.execute());
-
-// Show status
-program
-  .command('status')
-  .description('Show current task status and progress')
-  .action(() => StatusCommand.show());
-
-// Plan management (single command for generate + lock)
-program
-  .command('plan')
-  .description('Generate and lock plan')
-  .argument('[description]', 'Project description (required for first run)')
-  .action((description) => PlanCommand.handle(description));
-
-// Upgrade framework
-program
-  .command('upgrade')
-  .description('Upgrade framework files to latest version')
-  .action(() => UpgradeCommand.execute());
-
-program.parse();
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { AuthCommand } from '../src/cli/AuthCommand.js';
+import { TaskCommand } from '../src/cli/TaskCommand.js';
+import { CommitCommand } from '../src/cli/CommitCommand.js';
+import { StatusCommand } from '../src/cli/StatusCommand.js';
+import { PlanCommand } from '../src/cli/PlanCommand.js';
+import { UpgradeCommand } from '../src/cli/UpgradeCommand.js';
+import { VisualTestCommand } from '../src/cli/VisualTestCommand.js';
+
+const program = new Command();
+
+program
+  .name('agentic15')
+  .description('Agentic15 Claude Zen - Automated AI development workflow')
+  .version('2.0.0');
+
+// GitHub authentication setup
+program
+  .command('auth')
+  .description('GitHub authentication setup')
+  .action(() => AuthCommand.setup());
+
+// Task management
+program
+  .command('task')
+  .description('Task management')
+  .argument('<action>', 'Action: start, next, status')
+  .argument('[taskId]', 'Task ID (e.g., TASK-001) - required for "start"')
+  .action((action, taskId) => TaskCommand.handle(action, taskId));
+
+// Auto-commit workflow
+program
+  .command('commit')
+  .description('Run tests, commit, push, create PR')
+  .action(() => CommitCommand.execute());
+
+// Show status
+program
+  .command('status')
+  .description('Show current task status and progress')
+  .action(() => StatusCommand.show());
+
+// Plan management (single command for generate + lock)
+program
+  .command('plan')
+  .description('Generate and lock plan')
+  .argument('[description]', 'Project description (required for first run)')
+  .action((description) => PlanCommand.handle(description));
+
+// Upgrade framework
+program
+  .command('upgrade')
+  .description('Upgrade framework files to latest version')
+  .action(() => UpgradeCommand.execute());
+
+// Visual testing - capture screenshots and console errors
+program
+  .command('visual-test')
+  .description('Capture screenshots and console errors for UI debugging')
+  .argument('<url>', 'URL to test (e.g., http://localhost:3000)')
+  .action((url) => VisualTestCommand.execute(url));
+
+program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic15.com/agentic15-claude-zen",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Structured AI-assisted development framework for Claude Code with enforced quality standards",
   "main": "src/index.js",
   "bin": {
@@ -11,7 +11,9 @@
   "scripts": {
     "test": "node test/integration.test.js",
     "test:e2e": "node test/e2e-verification.test.js",
-    "test:site": "node test/verify-test-site.js"
+    "test:site": "node test/verify-test-site.js",
+    "sync-readme": "node -e \"require('fs').copyFileSync('../../README.md', 'README.md')\"",
+    "prepublishOnly": "npm run sync-readme"
   },
   "keywords": [
     "agentic15",

package/src/cli/VisualTestCommand.js

@@ -0,0 +1,191 @@
+import { execSync } from 'child_process';
+import { existsSync, writeFileSync, mkdirSync, unlinkSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * VisualTestCommand - Capture screenshots and console errors for UI debugging
+ *
+ * Uses Claude Code's built-in screenshot capabilities (no API key needed)
+ * Helps report UI issues to Claude without manual back-and-forth
+ */
+export class VisualTestCommand {
+  static async execute(url) {
+    console.log('\n🎯 Visual Test - Capture screenshots and console errors\n');
+
+    if (!url) {
+      console.log('❌ URL required');
+      console.log('   Usage: npx agentic15 visual-test <url>\n');
+      console.log('   Example: npx agentic15 visual-test http://localhost:3000\n');
+      process.exit(1);
+    }
+
+    // Check if Playwright is installed
+    const hasPlaywright = this.checkPlaywright();
+
+    if (!hasPlaywright) {
+      console.log('⚠️  Playwright not installed');
+      console.log('   Install with: npx playwright install chromium\n');
+      process.exit(1);
+    }
+
+    console.log(`📸 Capturing screenshots and logs from: ${url}\n`);
+
+    try {
+      // Run Playwright visual test
+      this.runVisualTest(url);
+
+      console.log('\n✅ Visual test complete');
+      console.log('   Screenshots saved to: .claude/visual-test/\n');
+      console.log('💡 Next steps:');
+      console.log('   1. Review screenshots in .claude/visual-test/');
+      console.log('   2. Check console-errors.log for JavaScript errors');
+      console.log('   3. Ask Claude to analyze the visual test results\n');
+
+      process.exit(0);
+    } catch (error) {
+      console.log(`\n❌ Visual test failed: ${error.message}\n`);
+      process.exit(1);
+    }
+  }
+
+  static checkPlaywright() {
+    const projectRoot = process.cwd();
+    const packageJsonPath = join(projectRoot, 'package.json');
+
+    if (!existsSync(packageJsonPath)) {
+      return false;
+    }
+
+    try {
+      // Check if playwright is in devDependencies
+      execSync('npx playwright --version', { stdio: 'pipe' });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  static runVisualTest(url) {
+    const testScript = `
+const { chromium } = require('playwright');
+const { writeFileSync, mkdirSync } = require('fs');
+const { join } = require('path');
+
+(async () => {
+  const outputDir = join(process.cwd(), '.claude', 'visual-test');
+  mkdirSync(outputDir, { recursive: true });
+
+  const consoleErrors = [];
+  const consoleWarnings = [];
+
+  const browser = await chromium.launch({ headless: true });
+  const context = await browser.newContext({
+    viewport: { width: 1920, height: 1080 }
+  });
+  const page = await context.newPage();
+
+  // Capture console errors
+  page.on('console', msg => {
+    if (msg.type() === 'error') {
+      consoleErrors.push({
+        timestamp: new Date().toISOString(),
+        message: msg.text()
+      });
+    } else if (msg.type() === 'warning') {
+      consoleWarnings.push({
+        timestamp: new Date().toISOString(),
+        message: msg.text()
+      });
+    }
+  });
+
+  // Capture page errors
+  page.on('pageerror', error => {
+    consoleErrors.push({
+      timestamp: new Date().toISOString(),
+      message: error.message,
+      stack: error.stack
+    });
+  });
+
+  try {
+    // Navigate to URL
+    await page.goto('${url}', { waitUntil: 'networkidle', timeout: 30000 });
+
+    // Wait for page to stabilize
+    await page.waitForTimeout(2000);
+
+    // Capture full page screenshot
+    await page.screenshot({
+      path: join(outputDir, 'fullpage.png'),
+      fullPage: true
+    });
+
+    // Capture viewport screenshot
+    await page.screenshot({
+      path: join(outputDir, 'viewport.png'),
+      fullPage: false
+    });
+
+    // Save console errors
+    if (consoleErrors.length > 0) {
+      const errorLog = consoleErrors.map(e =>
+        \`[\${e.timestamp}] \${e.message}\${e.stack ? '\\n' + e.stack : ''}\`
+      ).join('\\n\\n');
+
+      writeFileSync(join(outputDir, 'console-errors.log'), errorLog);
+      console.log(\`❌ Found \${consoleErrors.length} console errors\`);
+    } else {
+      console.log('✅ No console errors detected');
+    }
+
+    // Save console warnings
+    if (consoleWarnings.length > 0) {
+      const warningLog = consoleWarnings.map(w =>
+        \`[\${w.timestamp}] \${w.message}\`
+      ).join('\\n\\n');
+
+      writeFileSync(join(outputDir, 'console-warnings.log'), warningLog);
+      console.log(\`⚠️  Found \${consoleWarnings.length} console warnings\`);
+    }
+
+    // Capture page HTML for debugging
+    const html = await page.content();
+    writeFileSync(join(outputDir, 'page.html'), html);
+
+  } catch (error) {
+    console.error('Error during visual test:', error.message);
+
+    // Try to capture screenshot even on error
+    try {
+      await page.screenshot({
+        path: join(outputDir, 'error-screenshot.png')
+      });
+    } catch {}
+
+    throw error;
+  } finally {
+    await browser.close();
+  }
+})();
+`;
+
+    // Write test script to temp file and execute
+    const tempScriptPath = join(process.cwd(), '.claude', 'temp-visual-test.js');
+
+    mkdirSync(join(process.cwd(), '.claude'), { recursive: true });
+    writeFileSync(tempScriptPath, testScript);
+
+    try {
+      execSync(`node "${tempScriptPath}"`, {
+        stdio: 'inherit',
+        cwd: process.cwd()
+      });
+    } finally {
+      // Clean up temp script
+      try {
+        unlinkSync(tempScriptPath);
+      } catch {}
+    }
+  }
+}

package/src/core/TemplateManager.js

@@ -1,160 +1,137 @@
-/**
- * Copyright 2024-2025 agentic15.com
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-import { mkdirSync, cpSync, readFileSync, writeFileSync, existsSync } from 'fs';
-import { join, dirname } from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-
-/**
- * TemplateManager - Manages template copying and customization
- *
- * Single Responsibility: Copy and customize project templates
- */
-export class TemplateManager {
-  constructor() {
-    // From src/core/, go up two levels to package root, then into templates
-    this.templatesDir = join(__dirname, '..', '..', 'templates');
-    this.distDir = join(__dirname, '.');
-  }
-
-  /**
-   * Copy all templates to target directory
-   *
-   * @param {string} projectName - Name of the project
-   * @param {string} targetDir - Target directory path
-   */
-  async copyTemplates(projectName, targetDir) {
-    console.log('📦 Creating project directory...');
-    mkdirSync(targetDir, { recursive: true });
-
-    console.log('📋 Copying framework templates...');
-
-    // Copy .claude directory structure
-    this.copyDirectory('.claude', targetDir);
-
-    // Copy and customize package.json
-    this.copyAndCustomize('package.json', targetDir, projectName);
-
-    // Copy and customize README.md
-    this.copyAndCustomize('README.md', targetDir, projectName);
-
-    // Copy .gitignore (npm may rename it)
-    this.copyGitignore(targetDir);
-
-    // Copy test-site
-    this.copyDirectory('test-site', targetDir);
-
-    // Copy Agent directory
-    this.copyDirectory('Agent', targetDir);
-
-    // Copy scripts directory
-    this.copyDirectory('scripts', targetDir);
-
-    // Copy Jest configuration files
-    this.copySingleFile('jest.config.js', targetDir);
-    this.copySingleFile('jest.setup.js', targetDir);
-    this.copySingleFile('.babelrc', targetDir);
-
-    // Copy __mocks__ directory
-    this.copyDirectory('__mocks__', targetDir);
-
-    console.log('✅ Framework structure created');
-    console.log('✅ Templates copied');
-    console.log('✅ Configuration files generated');
-  }
-
-  /**
-   * Extract bundled scripts and hooks to node_modules
-   *
-   * @param {string} targetDir - Target directory path
-   */
-  async extractBundledFiles(targetDir) {
-    const bundleDir = join(targetDir, 'node_modules', '.agentic15-claude-zen');
-    console.log('\n📦 Setting up bundled scripts and hooks...');
-    mkdirSync(bundleDir, { recursive: true });
-
-    // Copy bundled scripts
-    console.log('  ├─ scripts/');
-    const bundledScriptsDir = join(this.distDir, 'scripts');
-    cpSync(bundledScriptsDir, join(bundleDir, 'scripts'), { recursive: true });
-
-    // Copy bundled hooks
-    console.log('  └─ hooks/');
-    const bundledHooksDir = join(this.distDir, 'hooks');
-    cpSync(bundledHooksDir, join(bundleDir, 'hooks'), { recursive: true });
-
-    console.log('✅ Bundled files extracted');
-  }
-
-  /**
-   * Copy a directory from templates to target
-   *
-   * @param {string} dirName - Directory name
-   * @param {string} targetDir - Target directory path
-   */
-  copyDirectory(dirName, targetDir) {
-    console.log(`  ├─ ${dirName}/`);
-    cpSync(
-      join(this.templatesDir, dirName),
-      join(targetDir, dirName),
-      { recursive: true }
-    );
-  }
-
-  /**
-   * Copy a single file from templates to target
-   *
-   * @param {string} fileName - File name
-   * @param {string} targetDir - Target directory path
-   */
-  copySingleFile(fileName, targetDir) {
-    console.log(`  ├─ ${fileName}`);
-    cpSync(
-      join(this.templatesDir, fileName),
-      join(targetDir, fileName)
-    );
-  }
-
-  /**
-   * Copy and customize a file with project name replacement
-   *
-   * @param {string} fileName - File name
-   * @param {string} targetDir - Target directory path
-   * @param {string} projectName - Project name for replacement
-   */
-  copyAndCustomize(fileName, targetDir, projectName) {
-    console.log(`  ├─ ${fileName}`);
-    const template = readFileSync(join(this.templatesDir, fileName), 'utf8');
-    const customized = template.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
-    writeFileSync(join(targetDir, fileName), customized);
-  }
-
-  /**
-   * Copy .gitignore file (handles npm renaming issue)
-   *
-   * @param {string} targetDir - Target directory path
-   */
-  copyGitignore(targetDir) {
-    console.log('  ├─ .gitignore');
-    const gitignoreSource = existsSync(join(this.templatesDir, '.gitignore'))
-      ? join(this.templatesDir, '.gitignore')
-      : join(this.templatesDir, '.npmignore');
-    cpSync(gitignoreSource, join(targetDir, '.gitignore'));
-  }
-}
+/**
+ * Copyright 2024-2025 agentic15.com
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { mkdirSync, cpSync, readFileSync, writeFileSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * TemplateManager - Manages template copying and customization
+ *
+ * Single Responsibility: Copy and customize project templates
+ */
+export class TemplateManager {
+  constructor() {
+    // From src/core/, go up two levels to package root, then into templates
+    this.templatesDir = join(__dirname, '..', '..', 'templates');
+    this.distDir = join(__dirname, '.');
+  }
+
+  /**
+   * Copy all templates to target directory
+   *
+   * @param {string} projectName - Name of the project
+   * @param {string} targetDir - Target directory path
+   */
+  async copyTemplates(projectName, targetDir) {
+    console.log('📦 Creating project directory...');
+    mkdirSync(targetDir, { recursive: true });
+
+    console.log('📋 Copying framework templates...');
+
+    // Copy .claude directory structure
+    this.copyDirectory('.claude', targetDir);
+
+    // Copy and customize package.json
+    this.copyAndCustomize('package.json', targetDir, projectName);
+
+    // Copy and customize README.md
+    this.copyAndCustomize('README.md', targetDir, projectName);
+
+    // Copy .gitignore (npm may rename it)
+    this.copyGitignore(targetDir);
+
+    // Copy test-site
+    this.copyDirectory('test-site', targetDir);
+
+    // Copy Agent directory
+    this.copyDirectory('Agent', targetDir);
+
+    // Copy scripts directory
+    this.copyDirectory('scripts', targetDir);
+
+    // Copy Jest configuration files
+    this.copySingleFile('jest.config.js', targetDir);
+    this.copySingleFile('jest.setup.js', targetDir);
+    this.copySingleFile('.babelrc', targetDir);
+
+    // Copy __mocks__ directory
+    this.copyDirectory('__mocks__', targetDir);
+
+    console.log('✅ Framework structure created');
+    console.log('✅ Templates copied');
+    console.log('✅ Configuration files generated');
+  }
+
+  /**
+   * Copy a directory from templates to target
+   *
+   * @param {string} dirName - Directory name
+   * @param {string} targetDir - Target directory path
+   */
+  copyDirectory(dirName, targetDir) {
+    console.log(`  ├─ ${dirName}/`);
+    cpSync(
+      join(this.templatesDir, dirName),
+      join(targetDir, dirName),
+      { recursive: true }
+    );
+  }
+
+  /**
+   * Copy a single file from templates to target
+   *
+   * @param {string} fileName - File name
+   * @param {string} targetDir - Target directory path
+   */
+  copySingleFile(fileName, targetDir) {
+    console.log(`  ├─ ${fileName}`);
+    cpSync(
+      join(this.templatesDir, fileName),
+      join(targetDir, fileName)
+    );
+  }
+
+  /**
+   * Copy and customize a file with project name replacement
+   *
+   * @param {string} fileName - File name
+   * @param {string} targetDir - Target directory path
+   * @param {string} projectName - Project name for replacement
+   */
+  copyAndCustomize(fileName, targetDir, projectName) {
+    console.log(`  ├─ ${fileName}`);
+    const template = readFileSync(join(this.templatesDir, fileName), 'utf8');
+    const customized = template.replace(/\{\{PROJECT_NAME\}\}/g, projectName);
+    writeFileSync(join(targetDir, fileName), customized);
+  }
+
+  /**
+   * Copy .gitignore file (handles npm renaming issue)
+   *
+   * @param {string} targetDir - Target directory path
+   */
+  copyGitignore(targetDir) {
+    console.log('  ├─ .gitignore');
+    const gitignoreSource = existsSync(join(this.templatesDir, '.gitignore'))
+      ? join(this.templatesDir, '.gitignore')
+      : join(this.templatesDir, '.npmignore');
+    cpSync(gitignoreSource, join(targetDir, '.gitignore'));
+  }
+}

package/templates/.claude/hooks/require-active-task.js

@@ -1,89 +1,89 @@
-#!/usr/bin/env node
-
-/**
- * Require Active Task Hook
- *
- * BLOCKS all Edit/Write operations when no active task exists
- *
- * This is the enforcement mechanism that prevents workflow violations
- */
-
-const fs = require('fs');
-const path = require('path');
-
-// Read tool use from stdin
-let input = '';
-process.stdin.on('data', chunk => {
-  input += chunk;
-});
-
-process.stdin.on('end', () => {
-  try {
-    const toolUse = JSON.parse(input);
-
-    // Only check Edit and Write operations
-    if (toolUse.name !== 'Edit' && toolUse.name !== 'Write') {
-      // Allow all other tools
-      process.exit(0);
-      return;
-    }
-
-    // Check if active task exists
-    const activePlanFile = '.claude/ACTIVE-PLAN';
-
-    if (!fs.existsSync(activePlanFile)) {
-      console.error('\n' + '═'.repeat(70));
-      console.error('❌ BLOCKED: No active plan exists');
-      console.error('═'.repeat(70));
-      console.error('\nYou MUST have an active plan before making code changes.');
-      console.error('\nTo create a plan:');
-      console.error('  npx agentic15 plan "Your project requirements"');
-      console.error('\n' + '═'.repeat(70) + '\n');
-      process.exit(1);
-      return;
-    }
-
-    const activePlan = fs.readFileSync(activePlanFile, 'utf8').trim();
-    const planDir = path.join('.claude/plans', activePlan);
-    const trackerPath = path.join(planDir, 'TASK-TRACKER.json');
-
-    if (!fs.existsSync(trackerPath)) {
-      console.error('\n' + '═'.repeat(70));
-      console.error('❌ BLOCKED: Task tracker not found');
-      console.error('═'.repeat(70));
-      console.error('\nPlan exists but task tracker is missing.');
-      console.error('This indicates a corrupted plan state.');
-      console.error('\n' + '═'.repeat(70) + '\n');
-      process.exit(1);
-      return;
-    }
-
-    const tracker = JSON.parse(fs.readFileSync(trackerPath, 'utf8'));
-
-    if (!tracker.activeTask) {
-      console.error('\n' + '═'.repeat(70));
-      console.error('❌ BLOCKED: No active task');
-      console.error('═'.repeat(70));
-      console.error('\nYou MUST have an active task before making code changes.');
-      console.error('\nTo start a task:');
-      console.error('  npx agentic15 task next');
-      console.error('\nThis will:');
-      console.error('  1. Show you the next pending task');
-      console.error('  2. Create a feature branch');
-      console.error('  3. Create a GitHub issue');
-      console.error('  4. Mark the task as active');
-      console.error('\nThen you can make your changes.');
-      console.error('\n' + '═'.repeat(70) + '\n');
-      process.exit(1);
-      return;
-    }
-
-    // Active task exists - allow the operation
-    process.exit(0);
-
-  } catch (error) {
-    // If we can't parse or check, fail safe and allow
-    // (don't want to block legitimate work due to hook errors)
-    process.exit(0);
-  }
-});
+#!/usr/bin/env node
+
+/**
+ * Require Active Task Hook
+ *
+ * BLOCKS all Edit/Write operations when no active task exists
+ *
+ * This is the enforcement mechanism that prevents workflow violations
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Read tool use from stdin
+let input = '';
+process.stdin.on('data', chunk => {
+  input += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const toolUse = JSON.parse(input);
+
+    // Only check Edit and Write operations
+    if (toolUse.name !== 'Edit' && toolUse.name !== 'Write') {
+      // Allow all other tools
+      process.exit(0);
+      return;
+    }
+
+    // Check if active task exists
+    const activePlanFile = '.claude/ACTIVE-PLAN';
+
+    if (!fs.existsSync(activePlanFile)) {
+      console.error('\n' + '═'.repeat(70));
+      console.error('❌ BLOCKED: No active plan exists');
+      console.error('═'.repeat(70));
+      console.error('\nYou MUST have an active plan before making code changes.');
+      console.error('\nTo create a plan:');
+      console.error('  npx agentic15 plan "Your project requirements"');
+      console.error('\n' + '═'.repeat(70) + '\n');
+      process.exit(1);
+      return;
+    }
+
+    const activePlan = fs.readFileSync(activePlanFile, 'utf8').trim();
+    const planDir = path.join('.claude/plans', activePlan);
+    const trackerPath = path.join(planDir, 'TASK-TRACKER.json');
+
+    if (!fs.existsSync(trackerPath)) {
+      console.error('\n' + '═'.repeat(70));
+      console.error('❌ BLOCKED: Task tracker not found');
+      console.error('═'.repeat(70));
+      console.error('\nPlan exists but task tracker is missing.');
+      console.error('This indicates a corrupted plan state.');
+      console.error('\n' + '═'.repeat(70) + '\n');
+      process.exit(1);
+      return;
+    }
+
+    const tracker = JSON.parse(fs.readFileSync(trackerPath, 'utf8'));
+
+    if (!tracker.activeTask) {
+      console.error('\n' + '═'.repeat(70));
+      console.error('❌ BLOCKED: No active task');
+      console.error('═'.repeat(70));
+      console.error('\nYou MUST have an active task before making code changes.');
+      console.error('\nTo start a task:');
+      console.error('  npx agentic15 task next');
+      console.error('\nThis will:');
+      console.error('  1. Show you the next pending task');
+      console.error('  2. Create a feature branch');
+      console.error('  3. Create a GitHub issue');
+      console.error('  4. Mark the task as active');
+      console.error('\nThen you can make your changes.');
+      console.error('\n' + '═'.repeat(70) + '\n');
+      process.exit(1);
+      return;
+    }
+
+    // Active task exists - allow the operation
+    process.exit(0);
+
+  } catch (error) {
+    // If we can't parse or check, fail safe and allow
+    // (don't want to block legitimate work due to hook errors)
+    process.exit(0);
+  }
+});

package/templates/.claude/settings.json

@@ -4,11 +4,11 @@
       "Read(**)",
       "Glob",
       "Grep",
-      "Bash(npm run *)",
-      "Bash(git status*)",
-      "Bash(git log*)",
-      "Bash(git diff*)",
-      "Bash(git branch*)",
+      "Bash(npm run:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git branch:*)",
       "Edit(./Agent/**)",
       "Write(./Agent/**)",
       "Edit(./scripts/**)",
@@ -34,33 +34,32 @@
       "Edit(./.claude/settings.json)",
       "Edit(./.claude/hooks/**)",
       "Write(./.claude/hooks/**)",
-      "Edit(./.claude/CLAUDE.md)",
       "Edit(./.claude/TASK-TRACKER.json)",
       "Read(./.claude/POST-INSTALL.md)",
       "Read(./docs/**)",
-      "Bash(agentic15 *)",
-      "Bash(git *)",
-      "Bash(gh *)",
+      "Bash(agentic15:*)",
+      "Bash(git:*)",
+      "Bash(gh:*)",
       "Bash(npm run task:*)",
       "Bash(npm run plan:*)",
-      "Bash(curl*)",
-      "Bash(wget*)",
-      "Bash(rm -rf*)",
-      "Bash(sudo*)",
-      "Bash(npm install*)",
-      "Bash(npm publish*)",
-      "Bash(git push --force*)",
-      "Bash(git merge*)",
-      "Bash(psql*)",
-      "Bash(mysql*)",
-      "Bash(sqlite3*)",
-      "Bash(mongosh*)",
-      "Bash(redis-cli*)",
+      "Bash(curl:*)",
+      "Bash(wget:*)",
+      "Bash(rm -rf:*)",
+      "Bash(sudo:*)",
+      "Bash(npm install:*)",
+      "Bash(npm publish:*)",
+      "Bash(git push --force:*)",
+      "Bash(git merge:*)",
+      "Bash(psql:*)",
+      "Bash(mysql:*)",
+      "Bash(sqlite3:*)",
+      "Bash(mongosh:*)",
+      "Bash(redis-cli:*)",
       "Bash(node ./scripts/**)",
       "Bash(node ./Agent/db/**)",
       "Bash(bash ./scripts/**)",
       "Bash(sh ./scripts/**)",
-      "Bash(git checkout -b *)",
+      "Bash(git checkout -b:*)",
       "WebFetch",
       "WebSearch"
     ]
@@ -150,11 +149,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/session-start-context.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/detect-pending-reviews.js"
+            "command": "node .claude/hooks/session-start-context.js"
           }
         ]
       }
@@ -174,19 +169,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/enforce-hard-requirements.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/prevent-read-bypass.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/enforce-structured-development.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/enforce-plan-template.js"
+            "command": "node .claude/hooks/enforce-plan-template.js"
           }
         ]
       },
@@ -195,87 +178,18 @@
         "hooks": [
           {
             "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-git-workflow.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-task-completion.js"
+            "command": "node .claude/hooks/validate-git-workflow.js"
           }
         ]
       }
     ],
     "PostToolUse": [
       {
-        "matcher": "Edit|Write",
+        "matcher": "Bash(git:*)",
         "hooks": [
           {
             "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/enforce-structured-development.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/auto-format.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-ui-syntax.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-ui-runtime.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-ui-visual-native.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-component-contract.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-test-quality.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-ui-integration.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-integration-site.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-database-changes.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-migration-impact.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-visual-regression.js"
-          }
-        ]
-      },
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-test-results.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/validate-e2e-coverage.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/enforce-test-pyramid.js"
-          },
-          {
-            "type": "command",
-            "command": "node node_modules/.agentic15-claude-zen/hooks/enforce-migration-workflow.js"
+            "command": "node .claude/hooks/post-merge.js"
           }
         ]
       }

package/templates/package.json

@@ -1,31 +1,31 @@
-{
-  "name": "{{PROJECT_NAME}}",
-  "version": "1.0.0",
-  "description": "Project with Claude Code structured development framework",
-  "type": "commonjs",
-  "scripts": {
-    "test": "jest --passWithNoTests"
-  },
-  "keywords": [
-    "claude-code",
-    "structured-development",
-    "task-tracking"
-  ],
-  "license": "MIT",
-  "dependencies": {
-    "@agentic15.com/agentic15-claude-zen": "^2.0.0"
-  },
-  "devDependencies": {
-    "jest": "^30.2.0",
-    "@testing-library/react": "^16.1.0",
-    "@testing-library/jest-dom": "^6.6.3",
-    "@testing-library/user-event": "^14.5.2",
-    "@babel/preset-env": "^7.26.0",
-    "@babel/preset-react": "^7.26.3",
-    "babel-jest": "^30.0.0",
-    "jest-environment-jsdom": "^30.0.0",
-    "prop-types": "^15.8.1",
-    "identity-obj-proxy": "^3.0.0",
-    "@playwright/test": "^1.41.0"
-  }
-}
+{
+  "name": "{{PROJECT_NAME}}",
+  "version": "1.0.0",
+  "description": "Project with Claude Code structured development framework",
+  "type": "commonjs",
+  "scripts": {
+    "test": "jest --passWithNoTests"
+  },
+  "keywords": [
+    "claude-code",
+    "structured-development",
+    "task-tracking"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@agentic15.com/agentic15-claude-zen": "^2.0.0"
+  },
+  "devDependencies": {
+    "jest": "^30.2.0",
+    "@testing-library/react": "^16.1.0",
+    "@testing-library/jest-dom": "^6.6.3",
+    "@testing-library/user-event": "^14.5.2",
+    "@babel/preset-env": "^7.26.0",
+    "@babel/preset-react": "^7.26.3",
+    "babel-jest": "^30.0.0",
+    "jest-environment-jsdom": "^30.0.0",
+    "prop-types": "^15.8.1",
+    "identity-obj-proxy": "^3.0.0",
+    "@playwright/test": "^1.41.0"
+  }
+}