@howlil/ez-agents 2.0.0

package/bin/update.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+
+/**
+ * EZ Agents Update — Check and install updates
+ *
+ * Usage:
+ *   ez-agents-update              # Check for updates
+ *   ez-agents-update --check      # Check only
+ *   ez-agents-update --force      # Force reinstall
+ *   ez-agents-update --changelog  # Show changelog
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const PACKAGE_NAME = 'ez-agents';
+const REPO_URL = 'https://github.com/howlil/ez-agents.git';
+
+// Colors for output
+const colors = {
+  reset: '\x1b[0m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  red: '\x1b[31m',
+  bold: '\x1b[1m'
+};
+
+function log(message, color = 'reset') {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+/**
+ * Get current installed version
+ */
+function getCurrentVersion() {
+  try {
+    const pkg = require('./package.json');
+    return pkg.version;
+  } catch {
+    return 'unknown';
+  }
+}
+
+/**
+ * Get latest version from npm
+ */
+function getLatestVersion() {
+  try {
+    const output = execSync(`npm view ${PACKAGE_NAME} version`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'ignore']
+    });
+    return output.trim();
+  } catch {
+    // Fallback: check GitHub repo
+    try {
+      const output = execSync(`npm view git+${REPO_URL} version`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'ignore']
+      });
+      return output.trim();
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * Check if update is available
+ */
+function checkUpdate() {
+  const current = getCurrentVersion();
+  const latest = getLatestVersion();
+  
+  log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'blue');
+  log(' EZ Agents Update Check', 'bold');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n', 'blue');
+  
+  log(`Current version: ${colors.bold}v${current}${colors.reset}`);
+  
+  if (!latest) {
+    log('Unable to check for updates (no network or repo unavailable)', 'yellow');
+    return;
+  }
+  
+  log(`Latest version:  ${colors.bold}v${latest}${colors.reset}\n`);
+  
+  if (current === latest) {
+    log('✓ You are on the latest version!\n', 'green');
+    return false;
+  }
+  
+  log(`⚡ Update available: v${current} → v${latest}\n`, 'yellow');
+  log('To update, run:\n', 'blue');
+  log(`  npm install -g ${PACKAGE_NAME}@latest\n`, 'green');
+  log('Or force reinstall:\n', 'blue');
+  log(`  ez-agents-update --force\n`, 'green');
+  
+  return true;
+}
+
+/**
+ * Install update
+ */
+function installUpdate(force = false) {
+  log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'blue');
+  log(' EZ Agents Update', 'bold');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n', 'blue');
+  
+  const current = getCurrentVersion();
+  const latest = getLatestVersion();
+  
+  if (!latest) {
+    log('Unable to check for updates', 'red');
+    process.exit(1);
+  }
+  
+  if (current === latest && !force) {
+    log('Already on latest version', 'green');
+    return;
+  }
+  
+  log(`Updating: v${current} → v${latest}...\n`, 'blue');
+  
+  try {
+    execSync(`npm install -g ${PACKAGE_NAME}@latest`, {
+      stdio: 'inherit'
+    });
+    
+    log('\n✓ Update complete!\n', 'green');
+    log('Restart your terminal or run:\n', 'blue');
+    log(`  ez-agents --version\n`, 'green');
+  } catch (err) {
+    log('\n✗ Update failed\n', 'red');
+    log('Try manual install:\n', 'yellow');
+    log(`  npm install -g ${PACKAGE_NAME}@latest\n`, 'blue');
+    process.exit(1);
+  }
+}
+
+/**
+ * Show changelog
+ */
+function showChangelog() {
+  log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━', 'blue');
+  log(' EZ Agents Changelog', 'bold');
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n', 'blue');
+  
+  try {
+    const fs = require('fs');
+    const changelogPath = path.join(__dirname, 'CHANGELOG.md');
+    
+    if (fs.existsSync(changelogPath)) {
+      const content = fs.readFileSync(changelogPath, 'utf-8');
+      // Show first 50 lines
+      const lines = content.split('\n').slice(0, 50);
+      log(lines.join('\n'));
+    } else {
+      log('CHANGELOG.md not found', 'yellow');
+      log(`\nView online: ${REPO_URL}/blob/main/CHANGELOG.md\n`, 'blue');
+    }
+  } catch (err) {
+    log('Unable to read changelog', 'red');
+  }
+}
+
+/**
+ * Show help
+ */
+function showHelp() {
+  log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ Agents Update — Check and Install Updates
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Usage:
+  ez-agents-update [options]
+
+Options:
+  --check      Check for updates (don't install)
+  --force      Force reinstall even if up-to-date
+  --changelog  Show changelog
+  --help       Show this help message
+
+Examples:
+  ez-agents-update              # Check and prompt to update
+  ez-agents-update --check      # Check only
+  ez-agents-update --force      # Force reinstall
+  ez-agents-update --changelog  # View changelog
+
+Manual Update:
+  npm install -g ez-agents@latest
+`);
+}
+
+// Main
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  showHelp();
+} else if (args.includes('--changelog')) {
+  showChangelog();
+} else if (args.includes('--check')) {
+  checkUpdate();
+} else if (args.includes('--force')) {
+  installUpdate(true);
+} else {
+  const hasUpdate = checkUpdate();
+  if (hasUpdate) {
+    // Auto-prompt (simple version)
+    log('Run "ez-agents-update --force" to update now\n');
+  }
+}

package/commands/ez/add-phase.md

@@ -0,0 +1,43 @@
+---
+name: ez:add-phase
+description: Add phase to end of current milestone in roadmap
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+Routes to the add-phase workflow which handles:
+- Phase number calculation (next sequential integer)
+- Directory creation with slug generation
+- Roadmap structure updates
+- STATE.md roadmap evolution tracking
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/add-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (phase description)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
+<process>
+**Follow the add-phase workflow** from `@~/.claude/ez-agents/workflows/add-phase.md`.
+
+The workflow handles all logic including:
+1. Argument parsing and validation
+2. Roadmap existence checking
+3. Current milestone identification
+4. Next phase number calculation (ignoring decimals)
+5. Slug generation from description
+6. Phase directory creation
+7. Roadmap entry insertion
+8. STATE.md updates
+</process>

package/commands/ez/add-tests.md

@@ -0,0 +1,41 @@
+---
+name: ez:add-tests
+description: Generate tests for a completed phase based on UAT criteria and implementation
+argument-hint: "<phase> [additional instructions]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+argument-instructions: |
+  Parse the argument as a phase number (integer, decimal, or letter-suffix), plus optional free-text instructions.
+  Example: /ez:add-tests 12
+  Example: /ez:add-tests 12 focus on edge cases in the pricing module
+---
+<objective>
+Generate unit and E2E tests for a completed phase, using its SUMMARY.md, CONTEXT.md, and VERIFICATION.md as specifications.
+
+Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
+
+Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/add-tests.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+Execute the add-tests workflow from @~/.claude/ez-agents/workflows/add-tests.md end-to-end.
+Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
+</process>

package/commands/ez/add-todo.md

@@ -0,0 +1,47 @@
+---
+name: ez:add-todo
+description: Capture idea or task as todo from current conversation context
+argument-hint: [optional description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Capture an idea, task, or issue that surfaces during an EZ Agents session as a structured todo for later work.
+
+Routes to the add-todo workflow which handles:
+- Directory structure creation
+- Content extraction from arguments or conversation
+- Area inference from file paths
+- Duplicate detection and resolution
+- Todo file creation with frontmatter
+- STATE.md updates
+- Git commits
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/add-todo.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional todo description)
+
+State is resolved in-workflow via `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the add-todo workflow** from `@~/.claude/ez-agents/workflows/add-todo.md`.
+
+The workflow handles all logic including:
+1. Directory ensuring
+2. Existing area checking
+3. Content extraction (arguments or conversation)
+4. Area inference
+5. Duplicate checking
+6. File creation with slug generation
+7. STATE.md updates
+8. Git commits
+</process>

package/commands/ez/audit-milestone.md

@@ -0,0 +1,36 @@
+---
+name: ez:audit-milestone
+description: Audit milestone completion against original intent before archiving
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - Write
+---
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/audit-milestone.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional — defaults to current milestone)
+
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
+
+**Completed Work:**
+Glob: .planning/phases/*/*-SUMMARY.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>
+
+<process>
+Execute the audit-milestone workflow from @~/.claude/ez-agents/workflows/audit-milestone.md end-to-end.
+Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+</process>

package/commands/ez/autonomous.md

@@ -0,0 +1,41 @@
+---
+name: ez:autonomous
+description: Run all remaining phases autonomously — discuss→plan→execute per phase
+argument-hint: "[--from N]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+---
+<objective>
+Execute all remaining milestone phases autonomously. For each phase: discuss → plan → execute. Pauses only for user decisions (grey area acceptance, blockers, validation requests).
+
+Uses ROADMAP.md phase discovery and Skill() flat invocations for each phase command. After all phases complete: milestone audit → complete → cleanup.
+
+**Creates/Updates:**
+- `.planning/STATE.md` — updated after each phase
+- `.planning/ROADMAP.md` — progress updated after each phase
+- Phase artifacts — CONTEXT.md, PLANs, SUMMARYs per phase
+
+**After:** Milestone is complete and cleaned up.
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/autonomous.md
+@~/.claude/ez-agents/references/ui-brand.md
+</execution_context>
+
+<context>
+Optional flag: `--from N` — start from phase N instead of the first incomplete phase.
+
+Project context, phase list, and state are resolved inside the workflow using init commands (`ez-tools.cjs init milestone-op`, `ez-tools.cjs roadmap analyze`). No upfront context loading needed.
+</context>
+
+<process>
+Execute the autonomous workflow from @~/.claude/ez-agents/workflows/autonomous.md end-to-end.
+Preserve all workflow gates (phase discovery, per-phase execution, blocker handling, progress display).
+</process>

package/commands/ez/check-todos.md

@@ -0,0 +1,45 @@
+---
+name: ez:check-todos
+description: List pending todos and select one to work on
+argument-hint: [area filter]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+
+Routes to the check-todos workflow which handles:
+- Todo counting and listing with area filtering
+- Interactive selection with full context loading
+- Roadmap correlation checking
+- Action routing (work now, add to phase, brainstorm, create phase)
+- STATE.md updates and git commits
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/check-todos.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional area filter)
+
+Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the check-todos workflow** from `@~/.claude/ez-agents/workflows/check-todos.md`.
+
+The workflow handles all logic including:
+1. Todo existence checking
+2. Area filtering
+3. Interactive listing and selection
+4. Full context loading with file summaries
+5. Roadmap correlation checking
+6. Action offering and execution
+7. STATE.md updates
+8. Git commits
+</process>

package/commands/ez/cleanup.md

@@ -0,0 +1,18 @@
+---
+name: ez:cleanup
+description: Archive accumulated phase directories from completed milestones
+---
+<objective>
+Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
+
+Use when `.planning/phases/` has accumulated directories from past milestones.
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/cleanup.md
+</execution_context>
+
+<process>
+Follow the cleanup workflow at @~/.claude/ez-agents/workflows/cleanup.md.
+Identify completed milestones, show a dry-run summary, and archive on confirmation.
+</process>

package/commands/ez/complete-milestone.md

@@ -0,0 +1,136 @@
+---
+type: prompt
+name: ez:complete-milestone
+description: Archive completed milestone and prepare for next version
+argument-hint: <version>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
+
+Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
+Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
+</objective>
+
+<execution_context>
+**Load these files NOW (before proceeding):**
+
+- @~/.claude/ez-agents/workflows/complete-milestone.md (main workflow)
+- @~/.claude/ez-agents/templates/milestone-archive.md (archive template)
+  </execution_context>
+
+<context>
+**Project files:**
+- `.planning/ROADMAP.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/STATE.md`
+- `.planning/PROJECT.md`
+
+**User input:**
+
+- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+  </context>
+
+<process>
+
+**Follow complete-milestone.md workflow:**
+
+0. **Check for audit:**
+
+   - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
+   - If missing or stale: recommend `/ez:audit-milestone` first
+   - If audit status is `gaps_found`: recommend `/ez:plan-milestone-gaps` first
+   - If audit status is `passed`: proceed to step 1
+
+   ```markdown
+   ## Pre-flight Check
+
+   {If no v{{version}}-MILESTONE-AUDIT.md:}
+   ⚠ No milestone audit found. Run `/ez:audit-milestone` first to verify
+   requirements coverage, cross-phase integration, and E2E flows.
+
+   {If audit has gaps:}
+   ⚠ Milestone audit found gaps. Run `/ez:plan-milestone-gaps` to create
+   phases that close the gaps, or proceed anyway to accept as tech debt.
+
+   {If audit passed:}
+   ✓ Milestone audit passed. Proceeding with completion.
+   ```
+
+1. **Verify readiness:**
+
+   - Check all phases in milestone have completed plans (SUMMARY.md exists)
+   - Present milestone scope and stats
+   - Wait for confirmation
+
+2. **Gather stats:**
+
+   - Count phases, plans, tasks
+   - Calculate git range, file changes, LOC
+   - Extract timeline from git log
+   - Present summary, confirm
+
+3. **Extract accomplishments:**
+
+   - Read all phase SUMMARY.md files in milestone range
+   - Extract 4-6 key accomplishments
+   - Present for approval
+
+4. **Archive milestone:**
+
+   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
+   - Extract full phase details from ROADMAP.md
+   - Fill milestone-archive.md template
+   - Update ROADMAP.md to one-line summary with link
+
+5. **Archive requirements:**
+
+   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+   - Mark all v1 requirements as complete (checkboxes checked)
+   - Note requirement outcomes (validated, adjusted, dropped)
+   - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
+
+6. **Update PROJECT.md:**
+
+   - Add "Current State" section with shipped version
+   - Add "Next Milestone Goals" section
+   - Archive previous content in `<details>` (if v1.1+)
+
+7. **Commit and tag:**
+
+   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
+   - Commit: `chore: archive v{{version}} milestone`
+   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
+   - Ask about pushing tag
+
+8. **Offer next steps:**
+   - `/ez:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
+
+</process>
+
+<success_criteria>
+
+- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
+- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
+- ROADMAP.md collapsed to one-line entry
+- PROJECT.md updated with current state
+- Git tag v{{version}} created
+- Commit successful
+- User knows next steps (including need for fresh requirements)
+  </success_criteria>
+
+<critical_rules>
+
+- **Load workflow first:** Read complete-milestone.md before executing
+- **Verify completion:** All phases must have SUMMARY.md files
+- **User confirmation:** Wait for approval at verification gates
+- **Archive before deleting:** Always create archive files before updating/deleting originals
+- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
+- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
+- **Fresh requirements:** Next milestone starts with `/ez:new-milestone` which includes requirements definition
+  </critical_rules>