@agentic15.com/agentic15-claude-zen 1.0.0

package/templates/.claude/PROJECT-PLAN-TEMPLATE.json

@@ -0,0 +1,223 @@
+{
+  "version": "2.0",
+  "project": {
+    "id": "PROJ-001",
+    "name": "E-commerce Platform",
+    "description": "Full-featured online store with payment processing",
+    "status": "planning",
+    "createdAt": "2025-12-18T00:00:00.000Z",
+    "createdBy": "human",
+    "locked": false,
+    "subprojects": [
+      {
+        "id": "SUB-001",
+        "name": "User Management System",
+        "description": "Authentication, authorization, and user profiles",
+        "status": "pending",
+        "dependencies": [],
+        "milestones": [
+          {
+            "id": "MILE-001",
+            "name": "Core Authentication",
+            "description": "Basic login/logout functionality",
+            "status": "pending",
+            "dependencies": [],
+            "tasks": [
+              {
+                "id": "TASK-001",
+                "title": "Design user database schema",
+                "description": "Create ERD for users, roles, sessions",
+                "status": "pending",
+                "phase": "design",
+                "dependencies": [],
+                "estimatedHours": 4,
+                "completionCriteria": [
+                  "ERD diagram completed",
+                  "Schema reviewed by team",
+                  "Migration scripts ready"
+                ],
+                "artifacts": {
+                  "design": ["./Agent/db/schema/users.sql"],
+                  "code": [],
+                  "tests": [],
+                  "documentation": ["./docs/database-design.md"]
+                }
+              },
+              {
+                "id": "TASK-002",
+                "title": "Implement user registration API",
+                "description": "POST /api/auth/register endpoint",
+                "status": "pending",
+                "phase": "implementation",
+                "dependencies": ["TASK-001"],
+                "estimatedHours": 6,
+                "completionCriteria": [
+                  "Email validation implemented",
+                  "Password hashing with bcrypt",
+                  "Duplicate email check",
+                  "Returns JWT token"
+                ],
+                "testCases": [
+                  "Valid registration succeeds",
+                  "Invalid email rejected",
+                  "Weak password rejected",
+                  "Duplicate email rejected"
+                ],
+                "artifacts": {
+                  "design": [],
+                  "code": [
+                    "./Agent/src/controllers/authController.js",
+                    "./Agent/src/services/userService.js"
+                  ],
+                  "tests": ["./Agent/tests/auth.test.js"],
+                  "documentation": []
+                }
+              },
+              {
+                "id": "TASK-003",
+                "title": "Write unit tests for registration",
+                "description": "Test all registration edge cases",
+                "status": "pending",
+                "phase": "testing",
+                "dependencies": ["TASK-002"],
+                "estimatedHours": 3,
+                "completionCriteria": [
+                  "100% code coverage for registration",
+                  "All edge cases tested",
+                  "Integration tests pass"
+                ],
+                "artifacts": {
+                  "code": [],
+                  "tests": [
+                    "./Agent/tests/auth.test.js",
+                    "./Agent/tests/integration/register.test.js"
+                  ]
+                }
+              }
+            ]
+          },
+          {
+            "id": "MILE-002",
+            "name": "User Profile Management",
+            "description": "Profile viewing and editing",
+            "status": "pending",
+            "dependencies": ["MILE-001"],
+            "tasks": [
+              {
+                "id": "TASK-004",
+                "title": "Create profile update API",
+                "description": "PATCH /api/users/:id endpoint",
+                "status": "pending",
+                "phase": "implementation",
+                "dependencies": ["TASK-003"],
+                "estimatedHours": 5,
+                "completionCriteria": [
+                  "Can update name, email, avatar",
+                  "Email uniqueness validated",
+                  "Authorization checked"
+                ],
+                "artifacts": {
+                  "code": ["./Agent/src/controllers/userController.js"],
+                  "tests": ["./Agent/tests/userProfile.test.js"]
+                }
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "id": "SUB-002",
+        "name": "Product Catalog System",
+        "description": "Product listings, search, and categories",
+        "status": "pending",
+        "dependencies": [],
+        "milestones": [
+          {
+            "id": "MILE-003",
+            "name": "Basic Product CRUD",
+            "description": "Create, read, update, delete products",
+            "status": "pending",
+            "dependencies": [],
+            "tasks": [
+              {
+                "id": "TASK-005",
+                "title": "Design product database schema",
+                "description": "Tables for products, categories, images",
+                "status": "pending",
+                "phase": "design",
+                "dependencies": [],
+                "estimatedHours": 3,
+                "completionCriteria": [
+                  "Schema supports multiple categories",
+                  "Image URLs stored properly",
+                  "Price and inventory tracked"
+                ],
+                "artifacts": {
+                  "design": ["./Agent/db/schema/products.sql"]
+                }
+              },
+              {
+                "id": "TASK-006",
+                "title": "Implement product listing API",
+                "description": "GET /api/products with pagination",
+                "status": "pending",
+                "phase": "implementation",
+                "dependencies": ["TASK-005"],
+                "estimatedHours": 4,
+                "completionCriteria": [
+                  "Pagination works (limit/offset)",
+                  "Filtering by category",
+                  "Sorting by price, name, date"
+                ],
+                "artifacts": {
+                  "code": ["./Agent/src/controllers/productController.js"],
+                  "tests": ["./Agent/tests/products.test.js"]
+                }
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "id": "SUB-003",
+        "name": "Shopping Cart & Checkout",
+        "description": "Cart management and order processing",
+        "status": "pending",
+        "dependencies": ["SUB-001", "SUB-002"],
+        "milestones": [
+          {
+            "id": "MILE-004",
+            "name": "Shopping Cart",
+            "description": "Add/remove/update cart items",
+            "status": "pending",
+            "dependencies": ["MILE-001", "MILE-003"],
+            "tasks": [
+              {
+                "id": "TASK-007",
+                "title": "Implement cart management",
+                "description": "Session-based cart for guests, DB for users",
+                "status": "pending",
+                "phase": "implementation",
+                "dependencies": ["TASK-002", "TASK-006"],
+                "estimatedHours": 8,
+                "completionCriteria": [
+                  "Add items to cart",
+                  "Update quantities",
+                  "Calculate totals",
+                  "Persist cart for logged-in users"
+                ],
+                "artifacts": {
+                  "code": [
+                    "./Agent/src/services/cartService.js",
+                    "./Agent/src/controllers/cartController.js"
+                  ],
+                  "tests": ["./Agent/tests/cart.test.js"]
+                }
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/.claude/hooks/enforce-plan-template.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * Enforce Plan Template Hook
+ *
+ * CRITICAL: Blocks custom plan formats - ONLY allow official template
+ *
+ * When Claude writes PROJECT-PLAN.json, this hook validates:
+ * 1. Plan follows PLAN-SCHEMA.json structure
+ * 2. Has required fields: planId, projectName, structure, tasks
+ * 3. Tasks have proper format: id, title, description, phase, dependencies
+ * 4. No custom formats allowed
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Read the tool input
+const input = process.argv[2] || '{}';
+const toolData = JSON.parse(input);
+
+const filePath = toolData.tool_input?.file_path;
+const content = toolData.tool_input?.content;
+const tool = toolData.tool;
+
+// Only check when writing PROJECT-PLAN.json
+if (tool === 'Write' && filePath && filePath.includes('PROJECT-PLAN.json')) {
+
+  let plan;
+  try {
+    plan = JSON.parse(content);
+  } catch (error) {
+    console.error('\n❌ BLOCKED: PROJECT-PLAN.json must be valid JSON');
+    console.error(`   Parse error: ${error.message}\n`);
+    process.exit(2);
+  }
+
+  const errors = [];
+
+  // Required top-level fields
+  const requiredFields = ['planId', 'projectName', 'description', 'structure', 'tasks'];
+  for (const field of requiredFields) {
+    if (!plan[field]) {
+      errors.push(`Missing required field: ${field}`);
+    }
+  }
+
+  // Validate structure field
+  if (plan.structure && typeof plan.structure !== 'string') {
+    errors.push('Field "structure" must be "flat" or "hierarchical"');
+  }
+
+  // Validate tasks array
+  if (plan.tasks && !Array.isArray(plan.tasks)) {
+    errors.push('Field "tasks" must be an array');
+  }
+
+  // Validate each task
+  if (Array.isArray(plan.tasks)) {
+    const taskRequiredFields = ['id', 'title', 'description', 'phase', 'dependencies', 'estimatedHours'];
+
+    plan.tasks.forEach((task, index) => {
+      for (const field of taskRequiredFields) {
+        if (task[field] === undefined) {
+          errors.push(`Task ${task.id || index}: Missing required field "${field}"`);
+        }
+      }
+
+      // Validate task ID format
+      if (task.id && !task.id.match(/^TASK-\d{3}$/)) {
+        errors.push(`Task ${task.id || index}: Invalid ID format. Must be TASK-XXX (e.g., TASK-001)`);
+      }
+
+      // Validate dependencies is array
+      if (task.dependencies && !Array.isArray(task.dependencies)) {
+        errors.push(`Task ${task.id || index}: dependencies must be an array`);
+      }
+
+      // Validate phase
+      const validPhases = ['design', 'implementation', 'testing', 'deployment'];
+      if (task.phase && !validPhases.includes(task.phase)) {
+        errors.push(`Task ${task.id || index}: Invalid phase "${task.phase}". Must be one of: ${validPhases.join(', ')}`);
+      }
+    });
+  }
+
+  // If errors found, block
+  if (errors.length > 0) {
+    console.error('\n❌ BLOCKED: PROJECT-PLAN.json does NOT follow template');
+    console.error('\n   Validation errors:');
+    errors.forEach(err => console.error(`   • ${err}`));
+    console.error('\n   ✅ Use the official template:');
+    console.error('   1. Read .claude/PLAN-SCHEMA.json for structure');
+    console.error('   2. Read .claude/PROJECT-PLAN-TEMPLATE.json for format');
+    console.error('   3. Follow the exact structure');
+    console.error('\n   Required fields:');
+    console.error('   - planId, projectName, description, structure, tasks');
+    console.error('   - Each task: id (TASK-XXX), title, description, phase, dependencies, estimatedHours\n');
+    process.exit(2);
+  }
+
+  // Validation passed
+  console.log('✅ PROJECT-PLAN.json follows official template');
+}
+
+process.exit(0);

package/templates/.claude/hooks/session-start-context.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+/**
+ * Session Start Context Display Hook
+ *
+ * CRITICAL: Shows Claude the current context at session start
+ * - Active plan name and location
+ * - Active task ID and description
+ * - Project structure
+ * - Workflow reminder
+ *
+ * This hook FORCES Claude to acknowledge the agentic15-claude-zen workflow
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function log(message, color = 'reset') {
+  const colors = {
+    reset: '\x1b[0m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    red: '\x1b[31m',
+    bold: '\x1b[1m'
+  };
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+// Check if active plan exists
+const activePlanFile = '.claude/ACTIVE-PLAN';
+let activePlan = null;
+let planDir = null;
+let tracker = null;
+let activeTask = null;
+
+if (fs.existsSync(activePlanFile)) {
+  activePlan = fs.readFileSync(activePlanFile, 'utf8').trim();
+  planDir = path.join('.claude/plans', activePlan);
+
+  const trackerPath = path.join(planDir, 'TASK-TRACKER.json');
+  if (fs.existsSync(trackerPath)) {
+    tracker = JSON.parse(fs.readFileSync(trackerPath, 'utf8'));
+  }
+}
+
+console.log('\n' + '═'.repeat(70));
+log('🎯 GL-LIFE-CLAUDE-ZEN WORKFLOW - SESSION START', 'bold');
+console.log('═'.repeat(70) + '\n');
+
+// Display active context
+if (activePlan && tracker) {
+  log('✅ ACTIVE PROJECT CONTEXT:', 'green');
+  log(`   Project: ${tracker.projectName}`, 'cyan');
+  log(`   Plan: ${activePlan}`, 'cyan');
+  log(`   Location: .claude/plans/${activePlan}/`, 'cyan');
+
+  if (tracker.activeTask) {
+    const taskFile = path.join(planDir, 'tasks', `${tracker.activeTask}.json`);
+    if (fs.existsSync(taskFile)) {
+      const task = JSON.parse(fs.readFileSync(taskFile, 'utf8'));
+      log(`\n   Active Task: ${tracker.activeTask}`, 'yellow');
+      log(`   Title: ${task.title}`, 'yellow');
+      log(`   Status: ${task.status}`, 'yellow');
+      log(`   Description: ${task.description}`, 'yellow');
+    }
+  } else {
+    log('\n   ⚠️  No active task - start one:', 'yellow');
+    log('   npm run task:next', 'yellow');
+  }
+
+  // Show progress
+  const stats = tracker.statistics;
+  log(`\n   Progress: ${stats.completed}/${stats.totalTasks} tasks complete`, 'cyan');
+  log(`   In Progress: ${stats.inProgress}`, 'cyan');
+  log(`   Pending: ${stats.pending}`, 'cyan');
+
+} else {
+  log('❌ NO ACTIVE PROJECT PLAN', 'red');
+  log('\n   You MUST work within the agentic15-claude-zen framework.', 'yellow');
+  log('   Create a plan first:', 'yellow');
+  log('   1. npm run plan:generate "Your requirements"', 'yellow');
+  log('   2. Create PROJECT-PLAN.json from requirements', 'yellow');
+  log('   3. npm run plan:init', 'yellow');
+  log('   4. npm run task:next\n', 'yellow');
+}
+
+console.log('─'.repeat(70));
+log('📖 MANDATORY WORKFLOW RULES:', 'bold');
+console.log('─'.repeat(70));
+log('   1. NO work without active plan + task', 'cyan');
+log('   2. Work ONLY on main branch (no feature branches)', 'cyan');
+log('   3. Edit ONLY ./Agent/** and ./scripts/** directories', 'cyan');
+log('   4. Follow 9-step task completion checklist', 'cyan');
+log('   5. Follow TDD: write tests first, then code', 'cyan');
+log('   6. Commit with task ID: [TASK-XXX] Description', 'cyan');
+log('   7. Push regularly: git push origin main', 'cyan');
+
+console.log('\n' + '─'.repeat(70));
+log('📂 DIRECTORY STRUCTURE:', 'bold');
+console.log('─'.repeat(70));
+log('   ./Agent/                    # Your workspace (EDIT HERE)', 'green');
+log('   ./scripts/                  # Your scripts (EDIT HERE)', 'green');
+log('   ./.claude/                  # Framework files (READ ONLY)', 'yellow');
+log('   ./node_modules/.agentic15-claude-zen/  # Bundled scripts & hooks', 'yellow');
+
+console.log('\n' + '─'.repeat(70));
+log('📋 AVAILABLE COMMANDS:', 'bold');
+console.log('─'.repeat(70));
+log('   npm run plan:generate <desc>   # Generate plan (non-interactive)', 'cyan');
+log('   npm run plan:init               # Lock plan', 'cyan');
+log('   npm run task:next               # Start next task', 'cyan');
+log('   npm run task:status             # View progress', 'cyan');
+log('   npm run task:done TASK-XXX      # Complete task', 'cyan');
+
+console.log('\n' + '─'.repeat(70));
+log('⚠️  ENFORCEMENT ACTIVE:', 'bold');
+console.log('─'.repeat(70));
+log('   • Hooks BLOCK operations that violate rules', 'red');
+log('   • Permission system DENIES dangerous commands', 'red');
+log('   • All work requires active task (enforced)', 'red');
+log('   • Tests must pass before commit (enforced)', 'red');
+log('   • Direct main branch workflow (enforced)', 'red');
+
+console.log('\n' + '═'.repeat(70));
+log('📖 Read .claude/ONBOARDING.md for complete workflow details', 'bold');
+console.log('═'.repeat(70) + '\n');
+
+process.exit(0);

package/templates/.claude/hooks/validate-git-workflow.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+
+// Read the tool input from stdin
+const input = process.argv[2] || '{}';
+let toolData;
+try {
+  toolData = JSON.parse(input);
+} catch (error) {
+  // Invalid JSON, exit gracefully
+  process.exit(0);
+}
+
+const command = toolData.tool_input?.command || '';
+
+// Only validate git commands
+if (!command.includes('git')) {
+  process.exit(0);
+}
+
+// Get current branch
+let currentBranch;
+try {
+  currentBranch = execSync('git rev-parse --abbrev-ref HEAD', { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
+} catch (error) {
+  // Not in a git repo or git command failed
+  process.exit(0);
+}
+
+// RULE 1: BLOCK branch creation (direct main workflow only)
+if (command.includes('git checkout -b') || command.includes('git branch ') && !command.includes('git branch --show-current')) {
+  console.error('\n❌ BLOCKED: Branch creation is NOT allowed');
+  console.error('   agentic15-claude-zen uses DIRECT MAIN WORKFLOW');
+  console.error('   All work happens on main branch');
+  console.error('   Command blocked: ' + command);
+  console.error('\n   ✅ Correct workflow:');
+  console.error('   git checkout main');
+  console.error('   # work on main');
+  console.error('   git commit -m "[TASK-XXX] Description"');
+  console.error('   git push origin main\n');
+  process.exit(2);
+}
+
+// RULE 2: BLOCK merges (no branching = no merging)
+if (command.includes('git merge')) {
+  console.error('\n❌ BLOCKED: Git merge is NOT allowed');
+  console.error('   agentic15-claude-zen uses DIRECT MAIN WORKFLOW');
+  console.error('   No branching = no merging needed');
+  console.error('   All work happens on main branch');
+  console.error('\n   ✅ Correct workflow:');
+  console.error('   Work directly on main');
+  console.error('   Commit and push regularly\n');
+  process.exit(2);
+}
+
+// RULE 3: BLOCK commits to non-main branches
+if (currentBranch !== 'main' && command.includes('git commit')) {
+  console.error('\n❌ BLOCKED: Commits only allowed on main branch');
+  console.error('   Current branch: ' + currentBranch);
+  console.error('   agentic15-claude-zen requires direct main workflow');
+  console.error('\n   ✅ Switch to main:');
+  console.error('   git checkout main\n');
+  process.exit(2);
+}
+
+// RULE 4: BLOCK force push
+if (command.includes('git push --force') || command.includes('git push -f')) {
+  console.error('\n❌ BLOCKED: Force push is NOT allowed');
+  console.error('   Never rewrite published history\n');
+  process.exit(2);
+}
+
+process.exit(0);