@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/workflows/help.md

@@ -9,22 +9,29 @@ Display the complete EZ Agents command reference. Output ONLY the reference cont
 
 ## Quick Start
 
-1. `/ez:new-project` - Initialize project (includes research, requirements, roadmap)
-2. `/ez:plan-phase 1` - Create detailed plan for first phase
-3. `/ez:execute-phase 1` - Execute the phase
+### Lean Agile Flow (Recommended)
+1. `/ez:new-project` - Initialize project (requirements + roadmap)
+2. `/ez:run-phase 1` - Run all phases iteratively with pause points
+3. `/ez:audit-milestone` - Verify all requirements met
+4. `/ez:complete-milestone` - Archive and tag release
+
+### Manual Control Flow
+1. `/ez:new-project` - Initialize project
+2. `/ez:discuss-phase 1` - Optional: clarify approach
+3. `/ez:plan-phase 1` - Create task breakdown
+4. `/ez:execute-phase 1` - Build the plan
+5. `/ez:verify-work 1` - Test it works
 
-## Staying Updated
-
-EZ Agents evolves fast. Update periodically:
+## Core Workflow
 
-```bash
-npx ez-agents@latest
+```
+/ez:new-project → /ez:run-phase → /ez:audit-milestone → /ez:complete-milestone
 ```
 
-## Core Workflow
+Or with manual control:
 
 ```
-/ez:new-project → /ez:plan-phase → /ez:execute-phase → repeat
+/ez:new-project → /ez:discuss-phase → /ez:plan-phase → /ez:execute-phase → /ez:verify-work → repeat
 ```
 
 ### Project Initialization
@@ -58,6 +65,31 @@ Map an existing codebase for brownfield projects.
 
 Usage: `/ez:map-codebase`
 
+### Iterative Execution (NEW!)
+
+**`/ez:run-phase [start-phase]`**
+**NEW!** Run all phases iteratively with pause points for approval.
+
+Execute all phases from a starting point: discuss → plan → execute → verify, with user approval between each step. Auto-advances to next phase after completion.
+
+- **Pause points** (unless `--yolo`):
+  - After discuss: "Continue to plan?"
+  - After plan: "Continue to execute?"
+  - After execute: "Continue to verify?"
+  - After verify: "Continue to next phase?"
+- **Auto-tracks progress** in STATE.md and ROADMAP.md
+- **Resume support**: Stop anytime, resume with `/ez:run-phase [N]`
+
+**Flags:**
+- `--no-discuss` — Skip discuss-phase for all phases
+- `--no-verify` — Skip verify-work for all phases
+- `--yolo` — No pause points, fully autonomous (use at own risk)
+
+Usage: `/ez:run-phase` (start from first incomplete phase)
+Usage: `/ez:run-phase 1` (start from phase 1)
+Usage: `/ez:run-phase 2 --no-discuss` (skip discussion)
+Usage: `/ez:run-phase 1 --yolo` (fully autonomous)
+
 ### Phase Planning
 
 **`/ez:discuss-phase <number>`**
@@ -72,25 +104,6 @@ Usage: `/ez:discuss-phase 2`
 Usage: `/ez:discuss-phase 2 --batch`
 Usage: `/ez:discuss-phase 2 --batch=3`
 
-**`/ez:research-phase <number>`**
-Comprehensive ecosystem research for niche/complex domains.
-
-- Discovers standard stack, architecture patterns, pitfalls
-- Creates RESEARCH.md with "how experts build this" knowledge
-- Use for 3D, games, audio, shaders, ML, and other specialized domains
-- Goes beyond "which library" to ecosystem knowledge
-
-Usage: `/ez:research-phase 3`
-
-**`/ez:list-phase-assumptions <number>`**
-See what Claude is planning to do before it starts.
-
-- Shows Claude's intended approach for a phase
-- Lets you course-correct if Claude misunderstood your vision
-- No files created - conversational output only
-
-Usage: `/ez:list-phase-assumptions 3`
-
 **`/ez:plan-phase <number>`**
 Create detailed execution plan for a specific phase.
 
@@ -131,38 +144,6 @@ Use when you know exactly what to do and the task is small enough to not need re
 Usage: `/ez:quick`
 Result: Creates `.planning/quick/NNN-slug/PLAN.md`, `.planning/quick/NNN-slug/SUMMARY.md`
 
-### Roadmap Management
-
-**`/ez:add-phase <description>`**
-Add new phase to end of current milestone.
-
-- Appends to ROADMAP.md
-- Uses next sequential number
-- Updates phase directory structure
-
-Usage: `/ez:add-phase "Add admin dashboard"`
-
-**`/ez:insert-phase <after> <description>`**
-Insert urgent work as decimal phase between existing phases.
-
-- Creates intermediate phase (e.g., 7.1 between 7 and 8)
-- Useful for discovered work that must happen mid-milestone
-- Maintains phase ordering
-
-Usage: `/ez:insert-phase 7 "Fix critical auth bug"`
-Result: Creates Phase 7.1
-
-**`/ez:remove-phase <number>`**
-Remove a future phase and renumber subsequent phases.
-
-- Deletes phase directory and all references
-- Renumbers all subsequent phases to close the gap
-- Only works on future (unstarted) phases
-- Git commit preserves historical record
-
-Usage: `/ez:remove-phase 17`
-Result: Phase 17 deleted, phases 18-20 become 17-19
-
 ### Milestone Management
 
 **`/ez:new-milestone <name>`**
@@ -212,15 +193,6 @@ Resume work from previous session with full context restoration.
 
 Usage: `/ez:resume-work`
 
-**`/ez:pause-work`**
-Create context handoff when pausing work mid-phase.
-
-- Creates .continue-here file with current state
-- Updates STATE.md session continuity section
-- Captures in-progress work context
-
-Usage: `/ez:pause-work`
-
 ### Debugging
 
 **`/ez:debug [issue description]`**
@@ -235,32 +207,6 @@ Systematic debugging with persistent state across context resets.
 Usage: `/ez:debug "login button doesn't work"`
 Usage: `/ez:debug` (resume active session)
 
-### Todo Management
-
-**`/ez:add-todo [description]`**
-Capture idea or task as todo from current conversation.
-
-- Extracts context from conversation (or uses provided description)
-- Creates structured todo file in `.planning/todos/pending/`
-- Infers area from file paths for grouping
-- Checks for duplicates before creating
-- Updates STATE.md todo count
-
-Usage: `/ez:add-todo` (infers from conversation)
-Usage: `/ez:add-todo Add auth token refresh`
-
-**`/ez:check-todos [area]`**
-List pending todos and select one to work on.
-
-- Lists all pending todos with title, area, age
-- Optional area filter (e.g., `/ez:check-todos api`)
-- Loads full context for selected todo
-- Routes to appropriate action (work now, add to phase, brainstorm)
-- Moves todo to done/ when work begins
-
-Usage: `/ez:check-todos`
-Usage: `/ez:check-todos api`
-
 ### User Acceptance Testing
 
 **`/ez:verify-work [phase]`**
@@ -285,16 +231,6 @@ Audit milestone completion against original intent.
 
 Usage: `/ez:audit-milestone`
 
-**`/ez:plan-milestone-gaps`**
-Create phases to close gaps identified by audit.
-
-- Reads MILESTONE-AUDIT.md and groups gaps into phases
-- Prioritizes by requirement priority (must/should/nice)
-- Adds gap closure phases to ROADMAP.md
-- Ready for `/ez:plan-phase` on new phases
-
-Usage: `/ez:plan-milestone-gaps`
-
 ### Configuration
 
 **`/ez:settings`**
@@ -306,27 +242,8 @@ Configure workflow toggles and model profile interactively.
 
 Usage: `/ez:settings`
 
-**`/ez:set-profile <profile>`**
-Quick switch model profile for EZ agents.
-
-- `quality` — Opus everywhere except verification
-- `balanced` — Opus for planning, Sonnet for execution (default)
-- `budget` — Sonnet for writing, Haiku for research/verification
-
-Usage: `/ez:set-profile budget`
-
 ### Utility Commands
 
-**`/ez:cleanup`**
-Archive accumulated phase directories from completed milestones.
-
-- Identifies phases from completed milestones still in `.planning/phases/`
-- Shows dry-run summary before moving anything
-- Moves phase dirs to `.planning/milestones/v{X.Y}-phases/`
-- Use after multiple milestones to reduce `.planning/phases/` clutter
-
-Usage: `/ez:cleanup`
-
 **`/ez:help`**
 Show this command reference.
 
@@ -341,14 +258,6 @@ Update EZ Agents to latest version with changelog preview.
 
 Usage: `/ez:update`
 
-**`/ez:join-discord`**
-Join the EZ Agents Discord community.
-
-- Get help, share what you're building, stay updated
-- Connect with other EZ Agents users
-
-Usage: `/ez:join-discord`
-
 ## Files & Structure
 
 ```
@@ -483,6 +392,50 @@ Example config:
 /ez:debug                                    # Resume from where you left off
 ```
 
+## Global Flags
+
+Flags below apply to all core commands (`execute-phase`, `plan-phase`, `release`, `progress`):
+
+| Flag | Effect |
+|---|---|
+| `--no-auto` | Disable all auto-invocations. Expert mode. |
+| `--verbose` | Show detail for every auto-invocation step. |
+| `--skip-discussion` | Skip discuss-phase only (more granular than --no-auto). |
+
+## Smart Orchestration
+
+Core commands automatically invoke helper commands based on context:
+
+- `/ez:execute-phase N` → auto: health check (pre), verify-work (post)
+- `/ez:plan-phase N` → auto: discuss-phase if phase touches a sensitive area (auth, DB, payment, etc.)
+- `/ez:release tier ver` → auto: verify-work (medium+), audit-milestone + arch-review (enterprise)
+- `/ez:progress` → auto: health check (silent on pass)
+
+All auto-invocations appear with `[auto]` prefix in output.
+
+Disable globally: set `"smart_orchestration": { "enabled": false }` in `.planning/config.json`.
+Disable per-command: append `--no-auto` flag.
+
+## Flags
+
+### --skip-discussion
+Skips the DISCUSSION.md pre-flight check and proceeds directly to execution.
+
+Usage: ez execute-phase <phase> --skip-discussion
+
+⚠️ Warning: Pre-flight discussion skipped via --skip-discussion
+
+### Migration Guide (v2.x → v3.0)
+If upgrading from v2.x:
+- `agent_discussion` is now enabled by default (was disabled)
+- Use `--skip-discussion` to preserve v2.x behavior during transition
+- Set `"agent_discussion": { "enabled": false }` in config.json to permanently disable
+
+### Migration Note (v3.x → Smart Orchestration)
+If upgrading from v3.x without smart orchestration and the new behavior is not desired, two options:
+1. Add `--no-auto` to frequently used commands
+2. Set `"smart_orchestration": { "enabled": false }` in `.planning/config.json`
+
 ## Getting Help
 
 - Read `.planning/PROJECT.md` for project vision

package/ez-agents/workflows/hotfix.md

@@ -0,0 +1,291 @@
+<purpose>
+Manage hotfix branches: create from main, complete by merging atomically to main (and develop for GitFlow), tag the release, and sync without polluting in-progress work.
+</purpose>
+
+<process>
+
+## 1. Parse Arguments
+
+Extract from $ARGUMENTS:
+- Subcommand: `start` or `complete`
+- Name: slug for the hotfix (e.g., `critical-bug`, `gmail-login-fix`)
+- Version (for `complete` only): semver string
+
+**If missing subcommand:**
+```
+Usage:
+  /ez:hotfix start <name>
+  /ez:hotfix complete <name> <version>
+```
+Exit.
+
+## 2. Handle "start" Subcommand
+
+### 2a. Load current state
+
+```bash
+# Current branch
+CURRENT_BRANCH=$(git branch --show-current)
+
+# Current version
+CURRENT_VERSION=$(node -e "console.log(require('./package.json').version)" 2>/dev/null || echo "0.0.0")
+
+# Load tier from config
+TIER=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get release.tier 2>/dev/null || echo "mvp")
+
+# Last tag
+LAST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "none")
+```
+
+### 2b. Check for uncommitted changes
+
+```bash
+git status --short
+```
+
+**If uncommitted changes:** Error — "Stash or commit current work before creating a hotfix"
+
+### 2c. Create hotfix branch
+
+```bash
+# Get hotfix branch name
+HOTFIX_BRANCH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" hotfix-branch-name "${NAME}")
+# Returns: hotfix/{name-slug}
+
+# Branch from main (or last release tag if available)
+SOURCE=$(git rev-parse --verify "${LAST_TAG}" 2>/dev/null && echo "${LAST_TAG}" || echo "main")
+
+git checkout "${SOURCE}"
+git checkout -b "${HOTFIX_BRANCH}"
+```
+
+### 2d. Report to user
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► HOTFIX STARTED: {HOTFIX_BRANCH}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Branch:   {HOTFIX_BRANCH}
+From:     {SOURCE} ({CURRENT_VERSION})
+Tier:     {TIER}
+
+Make your fix, commit it, then complete:
+/ez:hotfix complete {NAME} {NEXT_PATCH_VERSION}
+
+Example:
+  Current: {CURRENT_VERSION}
+  Next:    {NEXT_PATCH_SUGGESTION}
+```
+
+Suggest next patch version: increment patch number (1.2.3 → 1.2.4).
+
+**STOP here for `start` subcommand.**
+
+---
+
+## 3. Handle "complete" Subcommand
+
+### 3a. Validate state
+
+```bash
+# Confirm on hotfix branch
+CURRENT_BRANCH=$(git branch --show-current)
+EXPECTED_BRANCH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" hotfix-branch-name "${NAME}")
+
+if [ "$CURRENT_BRANCH" != "$EXPECTED_BRANCH" ]; then
+  echo "ERROR: Not on hotfix branch. Expected: ${EXPECTED_BRANCH}, got: ${CURRENT_BRANCH}"
+  exit 1
+fi
+
+# Check for uncommitted changes
+git status --short
+```
+
+**If uncommitted changes:** Error — "Commit your fix before completing the hotfix"
+
+### 3b. Validate version is semver
+
+```bash
+echo "${VERSION}" | grep -E "^[0-9]+\.[0-9]+\.[0-9]+$"
+```
+
+**If invalid:** Error — "Version must be semver (X.Y.Z)"
+
+### 3c. Run security gates
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" release security-gates
+```
+
+**If secrets found:** Error — "Remove secrets before completing hotfix"
+**If critical vulns:** Warning (not hard block for hotfix — speed matters)
+
+### 3d. Run tests
+
+```bash
+npm test 2>/dev/null || yarn test 2>/dev/null || echo "WARNING: No test command found"
+```
+
+**If tests fail:** Warning — "Tests failing. Hotfix will be tagged but verify before pushing."
+
+### 3e. Load tier and git strategy
+
+```bash
+TIER=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get release.tier 2>/dev/null || echo "mvp")
+```
+
+Determine sync target:
+- MVP/Medium: No sync needed (just main)
+- Enterprise: Also sync to develop
+
+### 3f. Generate changelog entry
+
+```bash
+LAST_TAG=$(git describe --tags --abbrev=0 main 2>/dev/null || echo "")
+if [ -n "$LAST_TAG" ]; then
+  COMMITS=$(git log ${LAST_TAG}..HEAD --oneline --no-merges)
+fi
+```
+
+Format entry for CHANGELOG.md:
+```markdown
+## [{VERSION}] — {date} (hotfix)
+
+### Bug Fixes
+- {fix commit message(s)}
+```
+
+### 3g. Merge to main
+
+```bash
+git checkout main
+git merge --no-ff "${HOTFIX_BRANCH}" -m "hotfix(release): merge ${HOTFIX_BRANCH} for v${VERSION}"
+```
+
+**If merge conflict:**
+```
+MERGE CONFLICT during hotfix merge.
+Resolve conflicts in: {conflicting files}
+Then run: git commit && /ez:hotfix complete {NAME} {VERSION}
+```
+STOP.
+
+### 3h. Bump version and update changelog
+
+```bash
+# Bump version in package.json
+node -e "
+  const pkg = JSON.parse(require('fs').readFileSync('package.json'));
+  pkg.version = '${VERSION}';
+  require('fs').writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+"
+
+# Update CHANGELOG.md (prepend entry)
+```
+
+### 3i. Create rollback plan
+
+Write to `.planning/releases/v${VERSION}-ROLLBACK-PLAN.md` using rollback-plan template.
+
+### 3j. Commit and tag
+
+```bash
+git add CHANGELOG.md package.json .planning/releases/
+git commit -m "chore(hotfix): v${VERSION} — ${NAME}
+
+Hotfix: ${NAME}
+Previous: v${PREVIOUS_VERSION}"
+
+git tag -a "v${VERSION}" -m "Hotfix v${VERSION}: ${NAME}"
+```
+
+### 3k. Sync to develop (Enterprise tier only)
+
+```bash
+if [ "$TIER" = "enterprise" ]; then
+  # Check if develop exists
+  git rev-parse --verify develop 2>/dev/null
+  if [ $? -eq 0 ]; then
+    git checkout develop
+  fi
+fi
+```
+
+### Enterprise: Sync hotfix ke develop
+
+1. Cek apakah sync akan conflict:
+   ```
+   git merge-base --is-ancestor v{version} develop
+   ```
+
+2. Jika tidak conflict → `git merge v{version} --no-ff -m "chore: sync hotfix v{version} to develop"`
+
+3. **Jika CONFLICT terdeteksi:**
+   - Jangan auto-merge. Beri instruksi eksplisit:
+   ```
+   ⚠️ MERGE CONFLICT: Hotfix sync ke develop memerlukan manual resolution.
+
+   Langkah:
+   a. git checkout develop
+   b. git merge v{version}
+   c. Resolve conflicts di file yang di-list git
+   d. git add . && git merge --continue
+   e. git push origin develop
+
+   PENTING: Hotfix SUDAH di production (main + tag).
+   Develop conflict tidak memblokir hotfix — selesaikan setelah production stabil.
+   ```
+
+### 3l. Clean up hotfix branch (optional)
+
+```bash
+git branch -d "${HOTFIX_BRANCH}"
+```
+
+### 3m. Report completion
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► HOTFIX COMPLETE: v{VERSION} ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Hotfix:   {NAME}
+Version:  v{VERSION}
+Tag:      v{VERSION}
+Changelog: Updated
+Rollback:  .planning/releases/v{VERSION}-ROLLBACK-PLAN.md
+
+{If enterprise:}
+Synced to develop: ✓
+
+### To Ship
+git push origin main && git push origin v{VERSION}
+
+{If enterprise:}
+git push origin develop
+```
+
+</process>
+
+<success_criteria>
+
+### start
+- [ ] Uncommitted changes check passed
+- [ ] Hotfix branch created from main (or last tag)
+- [ ] User sees branch name and complete instructions
+
+### complete
+- [ ] On correct hotfix branch
+- [ ] Security gates run
+- [ ] Tests run (warn if fail, don't block)
+- [ ] Changelog entry generated
+- [ ] Merged to main with no-ff
+- [ ] Version bumped in package.json
+- [ ] Rollback plan created
+- [ ] Release tagged
+- [ ] Develop synced (enterprise tier only)
+- [ ] Hotfix branch cleaned up
+- [ ] User sees push instructions
+
+</success_criteria>