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

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);
+});

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

@@ -0,0 +1,233 @@
+#!/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.
+ */
+
+/**
+ * Start Task Hook with GitHub Issues Integration
+ *
+ * This hook runs when a task is started. It:
+ * 1. Updates task status to 'in_progress'
+ * 2. Creates a GitHub issue (if configured)
+ * 3. Updates task tracker
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+// Import GitHub integration classes
+// These classes are bundled with the framework
+let GitHubClient, GitHubConfig, TaskIssueMapper;
+try {
+  // Try to import from node_modules (after framework is installed)
+  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');
+  const { TaskIssueMapper: GHMapper } = await import('@agentic15.com/agentic15-claude-zen/src/core/TaskIssueMapper.js');
+
+  GitHubClient = GHClient;
+  GitHubConfig = GHConfig;
+  TaskIssueMapper = GHMapper;
+} 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:start 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.error(`\n❌ ERROR: Task ${taskId} is already completed`);
+    console.error('Cannot restart a completed task\n');
+    process.exit(1);
+  }
+
+  // Pause any currently active task
+  if (tracker.activeTask && tracker.activeTask !== taskId) {
+    const activeTaskFile = path.join(planDir, 'tasks', `${tracker.activeTask}.json`);
+    if (fs.existsSync(activeTaskFile)) {
+      const activeTask = JSON.parse(fs.readFileSync(activeTaskFile, 'utf8'));
+      console.log(`\n⚠️  Pausing task ${activeTask.id}: ${activeTask.title}`);
+      activeTask.status = 'pending';
+      fs.writeFileSync(activeTaskFile, JSON.stringify(activeTask, null, 2));
+
+      // Update in tracker
+      const trackerTask = tracker.taskFiles.find(t => t.id === tracker.activeTask);
+      if (trackerTask) {
+        trackerTask.status = 'pending';
+      }
+    }
+  }
+
+  // Update task status
+  taskData.status = 'in_progress';
+  taskData.startedAt = new Date().toISOString();
+
+  // GitHub Issues Integration
+  if (GitHubConfig && GitHubClient && TaskIssueMapper) {
+    try {
+      const githubConfig = new GitHubConfig(process.cwd());
+
+      if (githubConfig.isAutoCreateEnabled()) {
+        const { owner, repo } = githubConfig.getRepoInfo();
+        const githubClient = new GitHubClient(
+          githubConfig.getToken(),
+          owner,
+          repo
+        );
+
+        // Only create issue if not already created
+        if (!taskData.githubIssue) {
+          const title = TaskIssueMapper.taskToIssueTitle(taskData);
+          const body = TaskIssueMapper.taskToIssueBody(taskData);
+          const labels = TaskIssueMapper.taskStatusToLabels(taskData.status, taskData.phase);
+
+          const issueNumber = await githubClient.createIssue(title, body, labels);
+
+          if (issueNumber) {
+            taskData.githubIssue = issueNumber;
+            console.log(`✓ Created GitHub issue #${issueNumber}`);
+          }
+        } else {
+          console.log(`ℹ  Task already linked to GitHub issue #${taskData.githubIssue}`);
+        }
+      }
+    } catch (error) {
+      console.warn('⚠ GitHub integration failed:', error.message);
+      // Continue anyway - task creation should not fail due to GitHub issues
+    }
+  }
+
+  // Save updated task
+  fs.writeFileSync(taskFile, JSON.stringify(taskData, null, 2));
+
+  // Update tracker
+  tracker.activeTask = taskId;
+  tracker.lastUpdated = new Date().toISOString();
+
+  const trackerTask = tracker.taskFiles.find(t => t.id === taskId);
+  if (trackerTask) {
+    trackerTask.status = 'in_progress';
+  }
+
+  // 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 task info
+  console.log(`\n✅ Started task: ${taskId}`);
+  console.log(`📋 Plan: ${activePlan}\n`);
+  console.log(`📌 ${taskData.title}`);
+
+  if (taskData.description) {
+    console.log(`📝 ${taskData.description}`);
+  }
+
+  console.log('');
+
+  if (taskData.phase) {
+    console.log(`🔧 Phase: ${taskData.phase}`);
+  }
+
+  if (taskData.githubIssue) {
+    const { owner, repo } = new GitHubConfig(process.cwd()).getRepoInfo();
+    const issueUrl = `https://github.com/${owner}/${repo}/issues/${taskData.githubIssue}`;
+    console.log(`🔗 GitHub Issue: ${issueUrl}`);
+  }
+
+  if (taskData.completionCriteria && taskData.completionCriteria.length > 0) {
+    console.log('\n✓ Completion criteria:');
+    taskData.completionCriteria.forEach((criteria, index) => {
+      console.log(`  ${index + 1}. ${criteria}`);
+    });
+  }
+
+  if (taskData.testCases && taskData.testCases.length > 0) {
+    console.log('\n🧪 Test cases:');
+    taskData.testCases.forEach((test, index) => {
+      console.log(`  ${index + 1}. ${test}`);
+    });
+  }
+
+  console.log(`\n📂 Task file: ${taskFile}`);
+  console.log('\n📝 WORKFLOW:');
+  console.log(' 1. Make your changes on main branch');
+  console.log(' 2. Commit frequently with task reference:');
+  console.log(`     git commit -m "[${taskId}] Description of changes"`);
+  console.log(' 3. When finished:');
+  console.log(`     npm run task:done ${taskId}`);
+
+  process.exit(0);
+}
+
+main().catch(error => {
+  console.error('\n❌ Fatal error:', error);
+  process.exit(1);
+});