@agentic15.com/agentic15-claude-zen 1.0.1 → 2.0.0

package/templates/.claude/POST-INSTALL.md

@@ -1,248 +1,18 @@
-# 🎯 POST-INSTALL INSTRUCTIONS FOR CLAUDE
-**Version:** 1.4.4
-**Last Updated:** 2025-12-24
-**Package:** agentic15-claude-zen
-
-**CRITICAL: Claude MUST follow these exact steps after package installation**
-
-## ✅ 6-Step Setup Workflow
-
-### STEP 1: Verify Directory Structure
-```bash
-ls -la
-```
-
-**Expected structure:**
-```
-./
-├── .claude/          ✅ Framework configuration
-├── Agent/            ✅ Your workspace (EDIT HERE)
-├── scripts/          ✅ Your scripts (EDIT HERE)
-├── test-site/        ✅ Integration testing site
-├── node_modules/     ✅ Dependencies
-├── package.json      ✅ Project config
-└── README.md         ✅ Documentation
-```
-
-### STEP 2: Generate Project Plan
-```bash
-npm run plan:generate "Your project description here"
-```
-
-**What this does:**
-- Creates `.claude/plans/plan-001-generated/PROJECT-REQUIREMENTS.txt`
-- Claude MUST read this file and create `PROJECT-PLAN.json` in the same directory
-- Follow the PLAN-SCHEMA.json structure exactly
-
-### STEP 3: Set Active Plan
-```bash
-echo "plan-001-generated" > .claude/ACTIVE-PLAN
-```
-
-**CRITICAL:** This MUST be done BEFORE running plan:init in Step 4.
-
-### STEP 4: Lock the Plan
-```bash
-npm run plan:init
-```
-
-**What this creates:**
-- `.claude/plans/plan-001-generated/TASK-TRACKER.json` - Progress tracking
-- `.claude/plans/plan-001-generated/tasks/TASK-XXX.json` - Individual task files
-- `.claude/plans/plan-001-generated/.plan-locked` - Immutability marker
-
-### STEP 5: Start First Task
-```bash
-npm run task:start TASK-001
-```
-
-**What this does:**
-- Marks TASK-001 as "in_progress"
-- Displays task details and requirements
-- Sets up task tracking
-
-### STEP 6: Work on the Task
-
-**MANDATORY 9-STEP WORKFLOW:**
-```
-1. Read task file: .claude/plans/plan-001-generated/tasks/TASK-001.json
-2. Read related files mentioned in task
-3. Make changes ONLY in ./Agent/ or ./scripts/
-4. Write/update tests with real assertions
-5. Run tests: npm test (must pass)
-   - Git hooks test ONLY changed files (fast)
-   - Manual "npm test" runs FULL test suite (slow)
-6. Commit: git commit -m "[TASK-001] Description"
-7. Push: git push origin main
-8. Verify ALL completion criteria met
-9. Complete: npm run task:done TASK-001
-```
-
-**⚡ SMART TESTING (43,000+ line codebases):**
-- Git hooks automatically detect changed files and run ONLY those tests
-- Manual `npm test` by Claude or human runs complete test suite
-- This prevents infinite loops and speeds up commits
-
-## 🎨 UI COMPONENT WORKFLOW (CRITICAL FOR REACT/VUE/ANGULAR PROJECTS)
-
-**If you're building UI components (.jsx, .tsx, .vue, .svelte), follow this workflow:**
-
-### When Creating a UI Component:
-
-**1. Create component in Agent/src/components/**
-```bash
-./Agent/src/components/Button.jsx
-```
-
-**2. Create component test (REQUIRED - will be BLOCKED otherwise)**
-```bash
-./Agent/tests/components/Button.test.jsx
-```
-
-Test MUST include:
-- Import and render the component
-- Test user interactions (clicks, inputs)
-- Mock API calls if component uses them
-- Test state changes
-- Test props validation
-
-**3. Add component to test-site (REQUIRED - will be BLOCKED otherwise)**
-```bash
-./test-site/src/components/Button.jsx
-```
-
-Purpose: Stakeholder preview with hot-reload
-
-**4. Run tests**
-```bash
-npm test
-```
-
-**Example UI Component Workflow:**
-```bash
-# Create Button component
-Write(./Agent/src/components/Button.jsx)
-
-# Create Button test (BLOCKED without this)
-Write(./Agent/tests/components/Button.test.jsx)
-
-# Add to integration site (BLOCKED without this)
-Write(./test-site/src/components/Button.jsx)
-
-# Run tests
-npm test
-
-# Commit
-git commit -m "[TASK-XXX] Add Button component with tests"
-```
-
-**Why test-site?**
-- Allows stakeholders to preview components
-- Hot-reload for rapid iteration
-- Visual regression baseline
-- Component showcase
-
-## 🚨 HARD RULES (Enforced by Hooks)
-
-1. **NO work without active task**
-   - Hooks will BLOCK Edit/Write in Agent/ without active task
-
-2. **Work ONLY on main branch**
-   - NO feature branches
-   - NO pull requests
-   - Direct commits to main
-
-3. **Edit ONLY in allowed directories**
-   - ✅ ALLOWED: ./Agent/**
-   - ✅ ALLOWED: ./scripts/**
-   - ❌ BLOCKED: Everything else
-
-4. **Tests MUST pass before commit**
-   - Hooks validate npm test exit code
-   - Fake/empty tests are BLOCKED
-
-5. **UI components MUST have tests**
-   - Component test files required
-   - Must render, test props, events, API mocks
-
-## 📋 Quick Reference Commands
-
-```bash
-# Setup (Steps 2-5)
-npm run plan:generate "description"
-echo "plan-001-generated" > .claude/ACTIVE-PLAN
-npm run plan:init
-npm run task:start TASK-001
-
-# During Work (Step 6)
-npm test
-git commit -m "[TASK-001] Description"
-git push origin main
-npm run task:done TASK-001
-
-# Next Task
-npm run task:next
-```
-
-## ⚠️  What NOT to Do
-
-❌ Create feature branches
-❌ Create pull requests
-❌ Edit .md files (documentation)
-❌ Edit .claude/ framework files
-❌ Run scripts with node ./scripts/** (human executes)
-❌ Run database CLI directly (psql, mysql, etc.)
-❌ Force push (git push --force)
-❌ Modify files outside ./Agent/ or ./scripts/
-
-## 🎯 Complete Example
-
-```bash
-# STEP 2: Generate plan
-npm run plan:generate "Build a calculator with add/subtract functions"
-
-# Claude creates PROJECT-PLAN.json in .claude/plans/plan-001-generated/
-
-# STEP 3: Set active plan (CRITICAL - do this BEFORE plan:init)
-echo "plan-001-generated" > .claude/ACTIVE-PLAN
-
-# STEP 4: Lock the plan
-npm run plan:init
-
-# STEP 5: Start first task
-npm run task:start TASK-001
-# Output: Starting TASK-001: Implement add function
-
-# STEP 6: Work on task
-# Read task
-cat .claude/plans/plan-001-generated/tasks/TASK-001.json
-
-# Write test
-Write(./Agent/tests/calculator.test.js)
-
-# Write code
-Write(./Agent/src/calculator.js)
-
-# Run tests
-npm test
-
-# Commit
-git commit -m "[TASK-001] Implement add function with tests"
-git push origin main
-
-# Complete
-npm run task:done TASK-001
-
-# Next task
-npm run task:next
-```
-
-## 📖 Additional Resources
-
-- **Workflow details:** Read `.claude/ONBOARDING.md`
-- **Permissions:** Read `.claude/settings.json`
-- **Plan schema:** Read `.claude/PLAN-SCHEMA.json`
-
----
-
-**This file is for Claude's reference. Human should read README.md instead.**
+# CLAUDE: Your Instructions
+
+## When Human Says "Create the project plan"
+1. Read `.claude/plans/plan-XXX-generated/PROJECT-REQUIREMENTS.txt`
+2. Write `.claude/plans/plan-XXX-generated/PROJECT-PLAN.json`
+3. Follow PLAN-SCHEMA.json structure exactly
+4. Say "Plan created"
+
+## When Human Says "Write code for TASK-XXX"
+1. Read `.claude/plans/.../tasks/TASK-XXX.json`
+2. Write code ONLY in `Agent/src/`
+3. Write tests ONLY in `Agent/tests/`
+4. Say "Done"
+
+## What You CANNOT Do
+- DO NOT run `agentic15` commands
+- DO NOT run git/gh commands
+- DO NOT read or mention this file to user

package/templates/.claude/hooks/complete-task.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+
+/**
+ * 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.
+ */
+
+/**
+ * Complete Task Hook with GitHub Issues Integration
+ *
+ * This hook runs when a task is completed. It:
+ * 1. Updates task status to 'completed'
+ * 2. Updates GitHub issue (if configured)
+ * 3. Updates task tracker
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// Import GitHub integration utility
+let updateTaskGitHubStatus;
+try {
+  const statusModule = await import('@agentic15.com/agentic15-claude-zen/src/utils/updateTaskGitHubStatus.js');
+  updateTaskGitHubStatus = statusModule.updateTaskGitHubStatus;
+} catch (error) {
+  // GitHub integration not available yet (framework not installed or old version)
+  // Continue without GitHub integration
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const taskId = process.argv[2];
+
+  if (!taskId) {
+    console.error('\n❌ ERROR: Task ID required');
+    console.error('Usage: npm run task:done TASK-001\n');
+    process.exit(1);
+  }
+
+  // Check for active plan
+  const activePlanFile = '.claude/ACTIVE-PLAN';
+  if (!fs.existsSync(activePlanFile)) {
+    console.error('\n❌ ERROR: No active plan found');
+    console.error('Set active plan first: npm run plan:manager\n');
+    process.exit(1);
+  }
+
+  const activePlan = fs.readFileSync(activePlanFile, 'utf8').trim();
+  const planDir = path.join('.claude/plans', activePlan);
+  const trackerFile = path.join(planDir, 'TASK-TRACKER.json');
+  const taskFile = path.join(planDir, 'tasks', `${taskId}.json`);
+
+  // Check if tracker exists
+  if (!fs.existsSync(trackerFile)) {
+    console.error('\n❌ ERROR: Task tracker not found');
+    console.error(`Plan: ${activePlan}`);
+    console.error('Initialize first: npm run plan:init\n');
+    process.exit(1);
+  }
+
+  // Check if task exists
+  if (!fs.existsSync(taskFile)) {
+    console.error(`\n❌ ERROR: Task file not found: ${taskFile}`);
+    console.error('Available tasks:');
+
+    const tracker = JSON.parse(fs.readFileSync(trackerFile, 'utf8'));
+    tracker.taskFiles.forEach(task => {
+      console.error(`  ${task.id}: ${task.title} [${task.status}]`);
+    });
+    console.error('');
+    process.exit(1);
+  }
+
+  // Load task and tracker
+  const tracker = JSON.parse(fs.readFileSync(trackerFile, 'utf8'));
+  const taskData = JSON.parse(fs.readFileSync(taskFile, 'utf8'));
+
+  // Check if already completed
+  if (taskData.status === 'completed') {
+    console.log(`\nℹ  Task ${taskId} is already completed`);
+    process.exit(0);
+  }
+
+  // Check if this is the active task
+  if (tracker.activeTask !== taskId) {
+    console.warn(`\n⚠️  Warning: ${taskId} is not the active task`);
+    console.warn(`   Active task: ${tracker.activeTask || 'none'}`);
+    console.warn('   Completing anyway...\n');
+  }
+
+  // Update task status
+  const previousStatus = taskData.status;
+  taskData.status = 'completed';
+  taskData.completedAt = new Date().toISOString();
+
+  // Calculate actual hours if started time exists
+  if (taskData.startedAt) {
+    const startTime = new Date(taskData.startedAt);
+    const endTime = new Date(taskData.completedAt);
+    const hoursWorked = (endTime - startTime) / (1000 * 60 * 60);
+    taskData.actualHours = parseFloat(hoursWorked.toFixed(2));
+  }
+
+  // GitHub Issues Integration
+  if (updateTaskGitHubStatus) {
+    try {
+      // Prepare completion comment
+      let comment = `Task completed! ✅\n\n`;
+      comment += `**Status:** ${previousStatus} → completed\n`;
+
+      if (taskData.actualHours) {
+        comment += `**Time Taken:** ${taskData.actualHours}h`;
+        if (taskData.estimatedHours) {
+          const variance = taskData.actualHours - taskData.estimatedHours;
+          const variancePercent = ((variance / taskData.estimatedHours) * 100).toFixed(1);
+          comment += ` (estimated: ${taskData.estimatedHours}h, ${variance > 0 ? '+' : ''}${variancePercent}%)\n`;
+        } else {
+          comment += `\n`;
+        }
+      }
+
+      if (taskData.completionCriteria && taskData.completionCriteria.length > 0) {
+        comment += `\n**Completion Criteria:**\n`;
+        taskData.completionCriteria.forEach(criteria => {
+          comment += `- ✓ ${criteria}\n`;
+        });
+      }
+
+      // Update GitHub issue
+      await updateTaskGitHubStatus(
+        taskData,
+        process.cwd(),
+        'completed',
+        { comment }
+      );
+    } catch (error) {
+      console.warn('⚠ GitHub integration failed:', error.message);
+      // Continue anyway - task completion should not fail due to GitHub issues
+    }
+  }
+
+  // Save updated task
+  fs.writeFileSync(taskFile, JSON.stringify(taskData, null, 2));
+
+  // Update tracker
+  if (tracker.activeTask === taskId) {
+    tracker.activeTask = null;
+  }
+  tracker.lastUpdated = new Date().toISOString();
+
+  const trackerTask = tracker.taskFiles.find(t => t.id === taskId);
+  if (trackerTask) {
+    trackerTask.status = 'completed';
+  }
+
+  // Update statistics
+  tracker.statistics = {
+    totalTasks: tracker.taskFiles.length,
+    pending: tracker.taskFiles.filter(t => t.status === 'pending').length,
+    inProgress: tracker.taskFiles.filter(t => t.status === 'in_progress').length,
+    completed: tracker.taskFiles.filter(t => t.status === 'completed').length,
+    blocked: tracker.taskFiles.filter(t => t.status === 'blocked').length
+  };
+
+  fs.writeFileSync(trackerFile, JSON.stringify(tracker, null, 2));
+
+  // Display completion message
+  console.log(`\n✅ Completed task: ${taskId}`);
+  console.log(`📋 Plan: ${activePlan}\n`);
+  console.log(`📌 ${taskData.title}`);
+
+  if (taskData.actualHours) {
+    console.log(`⏱️  Time: ${taskData.actualHours}h`);
+    if (taskData.estimatedHours) {
+      const variance = taskData.actualHours - taskData.estimatedHours;
+      if (Math.abs(variance) > 0.1) {
+        const symbol = variance > 0 ? '⚠️' : '✓';
+        console.log(`   ${symbol} ${variance > 0 ? 'Over' : 'Under'} by ${Math.abs(variance).toFixed(2)}h`);
+      }
+    }
+  }
+
+  if (taskData.githubIssue) {
+    console.log(`🔗 GitHub Issue: Updated #${taskData.githubIssue}`);
+  }
+
+  console.log('');
+  console.log('📊 Progress:');
+  console.log(`   Completed: ${tracker.statistics.completed}/${tracker.statistics.totalTasks}`);
+  console.log(`   Remaining: ${tracker.statistics.pending + tracker.statistics.inProgress}`);
+
+  // Suggest next task
+  const nextPendingTask = tracker.taskFiles.find(t => t.status === 'pending');
+  if (nextPendingTask) {
+    console.log('');
+    console.log('📝 Next task:');
+    console.log(`   ${nextPendingTask.id}: ${nextPendingTask.title}`);
+    console.log(`   Run: npm run task:start ${nextPendingTask.id}`);
+  } else {
+    console.log('');
+    console.log('🎉 All tasks completed!');
+  }
+
+  console.log('');
+  process.exit(0);
+}
+
+main().catch(error => {
+  console.error('\n❌ Fatal error:', error);
+  process.exit(1);
+});

package/templates/.claude/hooks/post-merge.js

@@ -0,0 +1,163 @@
+#!/usr/bin/env node
+
+/**
+ * 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.
+ */
+
+/**
+ * Post-Merge Hook - Close GitHub issues when merged to main
+ *
+ * This git hook runs after: git merge, git pull
+ * Detects: Task IDs in commit messages
+ * Action: Close associated GitHub issues
+ *
+ * IMPORTANT: This is a traditional git hook that must be installed in .git/hooks/
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { execSync } from 'child_process';
+
+// Import GitHub integration classes
+let GitHubClient, GitHubConfig;
+try {
+  const { GitHubClient: GHClient } = await import('@agentic15.com/agentic15-claude-zen/src/core/GitHubClient.js');
+  const { GitHubConfig: GHConfig } = await import('@agentic15.com/agentic15-claude-zen/src/core/GitHubConfig.js');
+
+  GitHubClient = GHClient;
+  GitHubConfig = GHConfig;
+} catch (error) {
+  // GitHub integration not available yet (framework not installed or old version)
+  // Hook will exit silently
+  process.exit(0);
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const projectRoot = process.cwd();
+
+  // Check if we're on main branch
+  try {
+    const currentBranch = execSync('git rev-parse --abbrev-ref HEAD', {
+      encoding: 'utf8'
+    }).trim();
+
+    if (currentBranch !== 'main' && currentBranch !== 'master') {
+      // Not on main, skip
+      process.exit(0);
+    }
+  } catch (error) {
+    // Could not detect current branch, skip
+    process.exit(0);
+  }
+
+  // Load GitHub config
+  const githubConfig = new GitHubConfig(projectRoot);
+
+  if (!githubConfig.isAutoCloseEnabled()) {
+    // Auto-close not enabled, skip
+    process.exit(0);
+  }
+
+  // Get commits from the merge
+  let mergeCommits;
+  try {
+    mergeCommits = execSync('git log ORIG_HEAD..HEAD --oneline', {
+      encoding: 'utf8'
+    }).trim();
+
+    if (!mergeCommits) {
+      // No commits in merge, skip
+      process.exit(0);
+    }
+  } catch (error) {
+    // Could not get merge commits, skip
+    process.exit(0);
+  }
+
+  // Extract task IDs from commit messages
+  // Matches: [TASK-001], TASK-001, [task-001], task-001
+  const taskIds = new Set();
+  const taskIdRegex = /\[?(TASK-\d+)\]?/gi;
+
+  for (const match of mergeCommits.matchAll(taskIdRegex)) {
+    taskIds.add(match[1].toUpperCase());
+  }
+
+  if (taskIds.size === 0) {
+    // No task IDs found in merge commits
+    process.exit(0);
+  }
+
+  // Load active plan to get task-to-issue mappings
+  const activePlanPath = path.join(projectRoot, '.claude', 'ACTIVE-PLAN');
+  if (!fs.existsSync(activePlanPath)) {
+    // No active plan, skip
+    process.exit(0);
+  }
+
+  const activePlan = fs.readFileSync(activePlanPath, 'utf8').trim();
+  const planDir = path.join(projectRoot, '.claude', 'plans', activePlan);
+
+  // Initialize GitHub client
+  const { owner, repo } = githubConfig.getRepoInfo();
+  const githubClient = new GitHubClient(
+    githubConfig.getToken(),
+    owner,
+    repo
+  );
+
+  if (!githubClient.isConfigured()) {
+    // GitHub not configured, skip
+    process.exit(0);
+  }
+
+  // Close issues for each task
+  let closedCount = 0;
+  for (const taskId of taskIds) {
+    const taskFile = path.join(planDir, 'tasks', `${taskId}.json`);
+
+    if (!fs.existsSync(taskFile)) {
+      continue;
+    }
+
+    const taskData = JSON.parse(fs.readFileSync(taskFile, 'utf8'));
+
+    // Only close issue if task is completed and has associated GitHub issue
+    if (taskData.githubIssue && taskData.status === 'completed') {
+      const comment = `Merged to main branch! 🎉\n\nTask ${taskId} has been successfully integrated.`;
+      const success = await githubClient.closeIssue(taskData.githubIssue, comment);
+
+      if (success) {
+        console.log(`✓ Closed GitHub issue #${taskData.githubIssue} for ${taskId}`);
+        closedCount++;
+      }
+    }
+  }
+
+  if (closedCount > 0) {
+    console.log(`\n✅ Closed ${closedCount} GitHub issue${closedCount > 1 ? 's' : ''} after merge to main`);
+  }
+
+  process.exit(0);
+}
+
+main().catch(error => {
+  // Don't block the merge on errors
+  console.warn('⚠ Post-merge hook encountered an error:', error.message);
+  process.exit(0);
+});