@agentic15.com/agentic15-claude-zen 1.0.0

package/templates/.claude/PLAN-SCHEMA.json

@@ -0,0 +1,240 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Project Plan Schema",
+  "description": "Hierarchical project plan with SDLC state machine",
+  "type": "object",
+  "required": ["version", "project"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "2.0",
+      "description": "Schema version"
+    },
+    "project": {
+      "type": "object",
+      "required": ["id", "name", "description", "status", "subprojects"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^PROJ-[0-9]{3}$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["planning", "active", "on-hold", "completed", "cancelled"]
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "createdBy": {
+          "type": "string"
+        },
+        "locked": {
+          "type": "boolean"
+        },
+        "lockedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "subprojects": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/subproject"
+          }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "subproject": {
+      "type": "object",
+      "required": ["id", "name", "description", "status", "milestones"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^SUB-[0-9]{3}$"
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "active", "on-hold", "completed", "cancelled"]
+        },
+        "dependencies": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^SUB-[0-9]{3}$"
+          }
+        },
+        "milestones": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/milestone"
+          }
+        }
+      }
+    },
+    "milestone": {
+      "type": "object",
+      "required": ["id", "name", "description", "status", "tasks"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^MILE-[0-9]{3}$"
+        },
+        "name": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "active", "completed"]
+        },
+        "dueDate": {
+          "type": "string",
+          "format": "date"
+        },
+        "dependencies": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^MILE-[0-9]{3}$"
+          }
+        },
+        "tasks": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/task"
+          }
+        }
+      }
+    },
+    "task": {
+      "type": "object",
+      "required": ["id", "title", "status", "phase"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^TASK-[0-9]{3}$"
+        },
+        "title": {
+          "type": "string"
+        },
+        "description": {
+          "type": "string"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["pending", "in_progress", "blocked", "review", "testing", "completed", "cancelled"]
+        },
+        "phase": {
+          "type": "string",
+          "enum": ["requirements", "design", "implementation", "testing", "deployment", "maintenance"],
+          "description": "SDLC phase"
+        },
+        "dependencies": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^TASK-[0-9]{3}$"
+          }
+        },
+        "assignee": {
+          "type": "string"
+        },
+        "estimatedHours": {
+          "type": "number",
+          "minimum": 0
+        },
+        "actualHours": {
+          "type": "number",
+          "minimum": 0
+        },
+        "completionCriteria": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "testCases": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "artifacts": {
+          "type": "object",
+          "properties": {
+            "design": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "code": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "tests": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "documentation": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "startedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "completedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "blockedReason": {
+          "type": "string"
+        },
+        "notes": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "timestamp": {
+                "type": "string",
+                "format": "date-time"
+              },
+              "author": {
+                "type": "string"
+              },
+              "content": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,248 @@
+# 🎯 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.**