@agentic15.com/agentic15-claude-zen 3.0.4 → 3.2.1

package/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 Copyright 2024-2025 agentic15.com
 
+## [3.1.0] - 2025-12-26
+
+### Summary
+Minor release adding upgrade command for existing projects.
+
+### Added
+- **`npx agentic15 upgrade`** - New command to upgrade framework files in existing projects
+  - Updates .claude/hooks/, settings.json, schemas, and templates
+  - Preserves user code (Agent/), plans (.claude/plans/), and local settings
+  - Creates automatic backup (.claude.backup/) before upgrading
+  - Shows version information and detailed upgrade report
+
+### Changed
+- Updated command count in README from 5 to 6 commands
+
 ## [3.0.4] - 2025-12-25
 
 ### Summary

package/README.md

@@ -18,16 +18,27 @@ 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
+```
+
+**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: 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
+# Make your code changes with Claude...
 npx agentic15 commit                  # Test, commit, push, PR
 ```
 
+> **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.
+>
 > **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.
 >
@@ -41,11 +52,12 @@ npx agentic15 commit                  # Test, commit, push, PR
 
 ## What It Does
 
-**5 Commands:**
+**6 Commands:**
 - `npx agentic15 plan` - Generate and lock plans
 - `npx agentic15 task next` - Start next task
 - `npx agentic15 commit` - Test + commit + push + PR
 - `npx agentic15 status` - Check progress
+- `npx agentic15 upgrade` - Upgrade framework files
 - `npm test` - Run tests
 
 **Automates:**

package/bin/agentic15.js

@@ -6,6 +6,7 @@ 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();
 
@@ -47,4 +48,10 @@ program
   .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();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic15.com/agentic15-claude-zen",
-  "version": "3.0.4",
+  "version": "3.2.1",
   "description": "Structured AI-assisted development framework for Claude Code with enforced quality standards",
   "main": "src/index.js",
   "bin": {

package/src/cli/UpgradeCommand.js

@@ -0,0 +1,189 @@
+/**
+ * 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 { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, readFileSync, writeFileSync, unlinkSync, rmdirSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+/**
+ * UpgradeCommand - Updates framework files in existing projects
+ *
+ * Upgrades .claude/ framework files while preserving:
+ * - User code (Agent/src, Agent/tests)
+ * - Active plans (.claude/plans, .claude/ACTIVE-PLAN)
+ * - Local settings (.claude/settings.local.json)
+ */
+export class UpgradeCommand {
+  static execute() {
+    console.log('\n' + '═'.repeat(70));
+    console.log('🔄 Agentic15 Claude Zen - Framework Upgrade');
+    console.log('═'.repeat(70) + '\n');
+
+    // Verify we're in a project directory
+    if (!existsSync('.claude')) {
+      console.log('❌ Not in an Agentic15 project directory');
+      console.log('   Run this command from your project root (where .claude/ exists)\n');
+      process.exit(1);
+    }
+
+    // Get current and package versions
+    const currentVersion = this.getCurrentVersion();
+    const packageVersion = this.getPackageVersion();
+
+    console.log(`📦 Current framework version: ${currentVersion || 'unknown'}`);
+    console.log(`📦 Package version: ${packageVersion}\n`);
+
+    // Backup current .claude directory
+    console.log('📂 Creating backup...');
+    this.createBackup();
+
+    try {
+      // Update framework files
+      console.log('🔄 Updating framework files...\n');
+      this.updateFrameworkFiles();
+
+      // Update version file
+      this.updateVersionFile(packageVersion);
+
+      console.log('\n✅ Upgrade completed successfully!\n');
+      console.log('📋 What was updated:');
+      console.log('   - .claude/hooks/ (git hooks)');
+      console.log('   - .claude/settings.json (framework settings)');
+      console.log('   - .claude/PLAN-SCHEMA.json (plan structure)');
+      console.log('   - .claude/PROJECT-PLAN-TEMPLATE.json (plan template)');
+      console.log('   - .claude/POST-INSTALL.md (documentation)\n');
+      console.log('📋 What was preserved:');
+      console.log('   - .claude/plans/ (your project plans)');
+      console.log('   - .claude/ACTIVE-PLAN (current plan)');
+      console.log('   - .claude/settings.local.json (local settings)');
+      console.log('   - Agent/ (your source code)');
+      console.log('   - test-site/ (your test site)\n');
+      console.log('💾 Backup location: .claude.backup/\n');
+      console.log('═'.repeat(70) + '\n');
+    } catch (error) {
+      console.log('\n❌ Upgrade failed:', error.message);
+      console.log('   Your original files are backed up in .claude.backup/');
+      console.log('   To restore: rm -rf .claude && mv .claude.backup .claude\n');
+      process.exit(1);
+    }
+  }
+
+  static getCurrentVersion() {
+    const versionFile = join('.claude', '.framework-version');
+    if (existsSync(versionFile)) {
+      return readFileSync(versionFile, 'utf-8').trim();
+    }
+    return null;
+  }
+
+  static getPackageVersion() {
+    const packageJsonPath = join(__dirname, '..', '..', 'package.json');
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+    return packageJson.version;
+  }
+
+  static createBackup() {
+    const backupDir = '.claude.backup';
+
+    // Remove old backup if exists
+    if (existsSync(backupDir)) {
+      this.removeDirectory(backupDir);
+    }
+
+    // Copy entire .claude directory
+    this.copyDirectory('.claude', backupDir);
+    console.log('   ✓ Backup created at .claude.backup/\n');
+  }
+
+  static updateFrameworkFiles() {
+    const templatesDir = join(__dirname, '..', '..', 'templates', '.claude');
+
+    // Files to update (framework files only)
+    const filesToUpdate = [
+      'hooks/complete-task.js',
+      'hooks/enforce-plan-template.js',
+      'hooks/post-merge.js',
+      'hooks/session-start-context.js',
+      'hooks/start-task.js',
+      'hooks/validate-git-workflow.js',
+      'PLAN-SCHEMA.json',
+      'PROJECT-PLAN-TEMPLATE.json',
+      'POST-INSTALL.md',
+      'settings.json'
+    ];
+
+    // Ensure hooks directory exists
+    const hooksDir = join('.claude', 'hooks');
+    if (!existsSync(hooksDir)) {
+      mkdirSync(hooksDir, { recursive: true });
+    }
+
+    // Copy framework files
+    filesToUpdate.forEach(file => {
+      const sourcePath = join(templatesDir, file);
+      const destPath = join('.claude', file);
+
+      if (existsSync(sourcePath)) {
+        copyFileSync(sourcePath, destPath);
+        console.log(`   ✓ Updated ${file}`);
+      }
+    });
+  }
+
+  static updateVersionFile(version) {
+    const versionFile = join('.claude', '.framework-version');
+    writeFileSync(versionFile, version);
+  }
+
+  static copyDirectory(src, dest) {
+    if (!existsSync(dest)) {
+      mkdirSync(dest, { recursive: true });
+    }
+
+    const entries = readdirSync(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const srcPath = join(src, entry.name);
+      const destPath = join(dest, entry.name);
+
+      if (entry.isDirectory()) {
+        this.copyDirectory(srcPath, destPath);
+      } else {
+        copyFileSync(srcPath, destPath);
+      }
+    }
+  }
+
+  static removeDirectory(dir) {
+    if (existsSync(dir)) {
+      const entries = readdirSync(dir, { withFileTypes: true });
+
+      for (const entry of entries) {
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+          this.removeDirectory(fullPath);
+        } else {
+          unlinkSync(fullPath);
+        }
+      }
+
+      rmdirSync(dir);
+    }
+  }
+}

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

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

package/templates/.claude/settings.json

@@ -4,15 +4,11 @@
       "Read(**)",
       "Glob",
       "Grep",
-      "Bash(npm run *)",
-      "Bash(git status*)",
-      "Bash(git log*)",
-      "Bash(git diff*)",
-      "Bash(git branch*)",
-      "Bash(git checkout main)",
-      "Bash(git add *)",
-      "Bash(git commit*)",
-      "Bash(git push*)",
+      "Bash(npm run:*)",
+      "Bash(git status:*)",
+      "Bash(git log:*)",
+      "Bash(git diff:*)",
+      "Bash(git branch:*)",
       "Edit(./Agent/**)",
       "Write(./Agent/**)",
       "Edit(./scripts/**)",
@@ -42,29 +38,29 @@
       "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"
     ]
@@ -164,6 +160,15 @@
       }
     ],
     "PreToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node .claude/hooks/require-active-task.js"
+          }
+        ]
+      },
       {
         "matcher": "*",
         "hooks": [

package/templates/package.json

@@ -4,7 +4,7 @@
   "description": "Project with Claude Code structured development framework",
   "type": "commonjs",
   "scripts": {
-    "test": "jest"
+    "test": "jest --passWithNoTests"
   },
   "keywords": [
     "claude-code",