@agentic15.com/agentic15-claude-zen 4.2.3 → 5.0.2

package/README.md

@@ -17,127 +17,23 @@ Agentic15 Claude Zen is a structured development framework designed to work seam
 
 ## Quick Start
 
-### 1. Create Project
-
-**Bash/Mac/Linux:**
-```bash
-npx @agentic15.com/agentic15-claude-zen my-project
-cd my-project
-```
-
-**PowerShell (Windows):**
-```powershell
-npx "@agentic15.com/agentic15-claude-zen" my-project
-cd my-project
-```
-
-### 2. Initialize Git and Link to GitHub
-
-```bash
-# Initialize git repository
-git init
-git branch -M main
-git add .
-git commit -m "Initial commit"
-
-# Create GitHub repository and link it
-gh repo create OWNER/REPO --public
-git remote add origin https://github.com/OWNER/REPO.git
-git push -u origin main
-```
-
-> **Note:** Replace `OWNER/REPO` with your GitHub username and repository name (e.g., `myusername/my-project`).
-
-> **Required:** This step is mandatory. The framework needs a GitHub remote to create issues and pull requests.
-
-### 3. Configure Repository Settings (Optional)
-
-**Bash/Mac/Linux:**
-```bash
-# Prevent direct pushes to main - require PRs for all changes
-cat > /tmp/protection.json << 'EOF'
-{
-  "required_pull_request_reviews": {
-    "required_approving_review_count": 0
-  },
-  "enforce_admins": false,
-  "allow_force_pushes": false,
-  "allow_deletions": false,
-  "required_status_checks": null,
-  "restrictions": null
-}
-EOF
-
-gh api repos/OWNER/REPO/branches/main/protection -X PUT \
-  -H "Accept: application/vnd.github+json" \
-  --input /tmp/protection.json
-
-# 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
-```
-
-**PowerShell (Windows):**
-```powershell
-# Prevent direct pushes to main - require PRs for all changes
-$body = @"
-{
-  "required_pull_request_reviews": {
-    "required_approving_review_count": 0
-  },
-  "enforce_admins": false,
-  "allow_force_pushes": false,
-  "allow_deletions": false,
-  "required_status_checks": null,
-  "restrictions": null
-}
-"@
-
-echo $body | gh api repos/OWNER/REPO/branches/main/protection -X PUT -H "Accept: application/vnd.github+json" --input -
-
-# 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
-```
-
-### 4. Start Using the Framework
-
-```bash
-# Configure GitHub authentication (one-time setup)
-npx agentic15 auth
-
-# Create a project plan
-npx agentic15 plan "Build a todo app with add, remove, and list features"
-
-# Start the first task
-npx agentic15 task next
-```
-
-### 5. Development Workflow
-
-**In Claude Code Terminal:**
-1. Ask Claude: "Implement the active task"
-2. Claude writes code in `Agent/` directory
-
-**In Your Terminal:**
-```bash
-# When task is complete
-npx agentic15 commit
-# This will: stage changes, commit, push, and create PR
-```
-
-**On GitHub:**
-1. Review and merge the PR
-
-**Back in Your Terminal:**
-```bash
-# Sync with main branch after PR merge
-npx agentic15 sync
-# This will: switch to main, pull changes, delete feature branch
-
-# Continue to next task
-npx agentic15 task next
-```
+| Step | Action | Commands |
+|------|--------|----------|
+| **1. Create Project** | **Bash/Mac/Linux:**<br>`npx @agentic15.com/agentic15-claude-zen my-project`<br>`cd my-project`<br><br>**PowerShell (Windows):**<br>`npx "@agentic15.com/agentic15-claude-zen" my-project`<br>`cd my-project` | Creates new project with framework structure |
+| **2. Initialize Git** | `git init`<br>`git branch -M main`<br>`git add .`<br>`git commit -m "Initial commit"`<br><br>`gh repo create OWNER/REPO --public`<br>`git remote add origin https://github.com/OWNER/REPO.git`<br>`git push -u origin main`<br><br>**Note:** Replace `OWNER/REPO` with your GitHub username/repo | Links project to GitHub (required for PRs) |
+| **3. Configure Auth** | `npx agentic15 auth` | One-time GitHub authentication setup |
+| **4. Create Plan** | **In Terminal:**<br>`npx agentic15 plan "Build a todo app with add, remove, and list features"`<br><br>**In Claude Code (launch from project directory):**<br>Ask: "Create the project plan from the requirements file"<br><br>**Back in Terminal:**<br>`npx agentic15 plan`<br>`git add .`<br>`git commit -m "Add initial project plan"`<br>`git push`<br><br>**Important:** Commit plan to main BEFORE enabling branch protection | Generates and locks project plan |
+| **5. Enable Branch Protection** | **Bash/Mac/Linux:**<br>```cat > /tmp/protection.json << 'EOF'```<br>```{```<br>```  "required_pull_request_reviews": {```<br>```    "required_approving_review_count": 0```<br>```  },```<br>```  "enforce_admins": false,```<br>```  "allow_force_pushes": false,```<br>```  "allow_deletions": false,```<br>```  "required_status_checks": null,```<br>```  "restrictions": null```<br>```}```<br>```EOF```<br><br>```gh api repos/OWNER/REPO/branches/main/protection -X PUT \```<br>```  -H "Accept: application/vnd.github+json" \```<br>```  --input /tmp/protection.json```<br><br>```gh api repos/OWNER/REPO -X PATCH \```<br>```  -H "Accept: application/vnd.github+json" \```<br>```  -f delete_branch_on_merge=true```<br><br>**PowerShell (Windows):**<br>```$body = @"```<br>```{```<br>```  "required_pull_request_reviews": {```<br>```    "required_approving_review_count": 0```<br>```  },```<br>```  "enforce_admins": false,```<br>```  "allow_force_pushes": false,```<br>```  "allow_deletions": false,```<br>```  "required_status_checks": null,```<br>```  "restrictions": null```<br>```}```<br>```"@```<br><br>```echo $body \| gh api repos/OWNER/REPO/branches/main/protection -X PUT -H "Accept: application/vnd.github+json" --input -```<br><br>```gh api repos/OWNER/REPO -X PATCH -H "Accept: application/vnd.github+json" -f delete_branch_on_merge=true``` | Enforces PR-only workflow for all future changes |
+| **6. Start First Task** | `npx agentic15 task next` | Creates feature branch for first task |
+
+### Daily Development Workflow
+
+| Location | Step | Action |
+|----------|------|--------|
+| **Claude Code** | 1. Implement | Ask: "Implement the active task"<br>Claude writes code in `Agent/` directory |
+| **Your Terminal** | 2. Commit & PR | `npx agentic15 commit`<br>Stages changes, commits, pushes, creates PR |
+| **GitHub** | 3. Review | Review and merge the PR |
+| **Your Terminal** | 4. Sync & Next | `npx agentic15 sync`<br>Syncs with main, deletes feature branch<br><br>`npx agentic15 task next`<br>Starts next task |
 
 ---
 
@@ -154,7 +50,6 @@ npx agentic15 task next
 | `npx agentic15 commit` | Commit, push, and create PR |
 | `npx agentic15 sync` | Sync with main branch after PR merge |
 | `npx agentic15 visual-test <url>` | Capture UI screenshots and console errors |
-| `npx agentic15 upgrade` | Update framework files |
 | `npx agentic15 auth` | Configure GitHub authentication |
 
 ### Workflow Automation
@@ -178,11 +73,22 @@ plan → task → code → commit → PR → merge → sync → next task
 
 ```
 my-project/
-├── .claude/                    # Framework configuration
-│   ├── hooks/                  # Claude Code hooks
-│   ├── plans/                  # Project plans and tasks
-│   ├── settings.json           # Framework settings
-│   └── settings.local.json     # Local overrides (gitignored)
+├── node_modules/
+│   └── @agentic15.com/agentic15-claude-zen/
+│       └── framework/          # Framework files (hooks, schemas, templates)
+│           ├── hooks/          # Claude Code hooks
+│           ├── settings.json   # Framework settings
+│           ├── PLAN-SCHEMA.json
+│           ├── PROJECT-PLAN-TEMPLATE.json
+│           └── POST-INSTALL.md
+├── .claude/                    # User-generated content only
+│   ├── ACTIVE-PLAN             # Current active plan
+│   ├── plans/                  # Your project plans and tasks
+│   │   └── {planId}/
+│   │       ├── TASK-TRACKER.json
+│   │       └── tasks/
+│   ├── settings.json           # References framework in node_modules
+│   └── settings.local.json     # Local overrides (optional, gitignored)
 ├── Agent/                      # Your code workspace
 │   ├── src/                    # Source code
 │   └── tests/                  # Tests (optional)
@@ -190,34 +96,70 @@ my-project/
 └── package.json                # Project dependencies
 ```
 
+### Framework Upgrades
+
+Framework files live in `node_modules` and are automatically updated when you upgrade the package:
+
+```bash
+# Upgrade to latest version
+npm install @agentic15.com/agentic15-claude-zen@latest
+
+# Or to a specific version
+npm install @agentic15.com/agentic15-claude-zen@5.0.0
+```
+
+**What gets updated:**
+- ✅ Framework hooks in `node_modules`
+- ✅ Settings schema and templates
+- ✅ CLI commands
+
+**What stays unchanged:**
+- ✅ Your code in `Agent/`
+- ✅ Your plans and tasks in `.claude/plans/`
+- ✅ Your local settings in `.claude/settings.local.json`
+
 ---
 
 ## GitHub Integration
 
-### Optional Configuration
+### Authentication
+
+The framework uses **GitHub CLI (`gh`)** for authentication - no personal access tokens needed!
+
+**Setup:**
+```bash
+npx agentic15 auth
+```
+
+This command will:
+1. Check if `gh` CLI is installed
+2. Run `gh auth login` if not already authenticated
+3. Auto-detect your repository owner/repo from git remote
+4. Save configuration to `.claude/settings.local.json`
 
-Create `.claude/settings.local.json`:
+### Manual Configuration (Optional)
+
+If you need to override the auto-detected values, create or edit `.claude/settings.local.json`:
 ```json
 {
   "github": {
-    "token": "ghp_xxxxxxxxxxxxx",
+    "enabled": true,
+    "autoCreate": true,
+    "autoUpdate": true,
+    "autoClose": true,
     "owner": "your-username",
     "repo": "your-repo"
   }
 }
 ```
 
-Or use environment variables:
-```bash
-export GITHUB_TOKEN="ghp_xxxxxxxxxxxxx"
-export GITHUB_OWNER="your-username"
-export GITHUB_REPO="your-repo"
-```
+**Note:** Authentication is handled by `gh` CLI - no token field needed.
 
 ### Features
 - **Auto-create issues:** When starting tasks
 - **Auto-update issues:** When creating PRs
 - **Auto-close issues:** When merging to main (optional)
+- **Secure authentication:** Uses `gh` CLI credentials
 
 ---
 

package/bin/agentic15.js

@@ -6,7 +6,6 @@ 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';
 import { SyncCommand } from '../src/cli/SyncCommand.js';
 
@@ -50,12 +49,6 @@ 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());
-
 // Visual testing - capture screenshots and console errors
 program
   .command('visual-test')