@howlil/ez-agents 3.4.1 → 3.5.0

package/ez-agents/workflows/release.md

@@ -0,0 +1,253 @@
+<purpose>
+Orchestrate tier-aware production releases. Validates state, runs security gates, evaluates tier checklist, creates release branch, generates changelog, bumps version, writes rollback plan, and tags the release.
+</purpose>
+
+<process>
+
+<auto_invoke>
+Check for --no-auto in ARGUMENTS. If present, skip this section and proceed to step 1.
+
+```bash
+SMART_ORCH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get smart_orchestration.enabled 2>/dev/null || echo "true")
+```
+If `SMART_ORCH` is `"false"`: skip, proceed to step 1.
+
+**Tier-based pre-flight:**
+Parse the tier argument from ARGUMENTS (mvp / medium / enterprise).
+
+- **mvp**: No pre-flight auto-invocations. Proceed directly to step 1.
+- **medium**: Check if a VERIFICATION.md from verify-work already exists for the current phase. If not:
+  → Display: `[auto] Running verify-work before medium release...`
+  → Invoke: Skill(ez:verify-work)
+  → Continue to step 1.
+- **enterprise**: Run in sequence:
+  → Display: `[auto] Running verify-work...`
+  → Invoke: Skill(ez:verify-work)
+  → Display: `[auto] Running audit-milestone...`
+  → Invoke: Skill(ez:audit-milestone)
+  → Display: `[auto] Running arch-review...`
+  → Invoke: Skill(ez:arch-review)
+  → Continue to step 1.
+
+All auto-invocations are prefixed with `[auto]` in output. Override with `--no-auto` to skip all pre-invocations.
+</auto_invoke>
+
+## 1. Initialize
+
+Parse $ARGUMENTS:
+- Command: `release` or `preflight`
+- Tier: `mvp`, `medium`, or `enterprise`
+- Version: semver string (e.g., `1.0.0`)
+
+**If missing tier or version (for release command):**
+```
+Usage: /ez:release <tier> <version>
+       /ez:release preflight <tier>
+
+Examples:
+  /ez:release mvp v1.0.0
+  /ez:release medium v1.5.0
+  /ez:release enterprise v2.0.0
+  /ez:release preflight medium
+```
+Exit.
+
+**Normalize version:** Strip leading `v` if present (e.g., `v1.0.0` → `1.0.0`).
+
+**Load tier config:**
+```bash
+TIER_CONFIG=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" tier-config "${TARGET_TIER}" 2>/dev/null)
+```
+
+Display banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► RELEASE v{version} — {TIER} TIER
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 2. Validate Semver
+
+```bash
+echo "${VERSION}" | grep -E "^[0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.]+)?$"
+```
+
+**If invalid:** Error — "Version must be semver (X.Y.Z). Got: {version}"
+
+## 3. Check Current State
+
+```bash
+# Uncommitted changes
+git status --short
+
+# Current branch
+git branch --show-current
+
+# Current version
+CURRENT=$(node -e "console.log(require('./package.json').version)" 2>/dev/null || echo "0.0.0")
+```
+
+**If uncommitted changes:** Error — "Commit or stash all changes before releasing"
+
+## 4. Run Security Gates
+
+```bash
+echo "Running security gates..."
+
+# Gate 1: No secrets in tracked files
+SECRET_HITS=$(git grep -i -E "(api[_-]?key|password|secret)['\"]?\s*[=:]\s*['\"]?[a-zA-Z0-9+/]{20,}" HEAD 2>/dev/null | \
+  grep -v "example\|placeholder\|your-key\|process\.env\|env\.\|config\.\|getenv" | wc -l)
+
+# Gate 2: npm audit
+npm audit --audit-level=critical 2>/dev/null
+AUDIT_EXIT=$?
+
+# Gate 3: Production TODOs
+PROD_TODOS=$(grep -rn "TODO\|FIXME\|HACK" src/ --include="*.ts" --include="*.js" --include="*.py" 2>/dev/null | \
+  grep -v "test\|spec\|__test__\|\.test\." | wc -l)
+
+# Gate 4: .env in .gitignore
+grep -q "^\.env" .gitignore 2>/dev/null && ENV_SAFE=true || ENV_SAFE=false
+```
+
+Security gate results:
+```
+Security Gates:
+  ✓/✗ No secrets in committed files ({SECRET_HITS} found)
+  ✓/✗ npm audit clean (exit {AUDIT_EXIT})
+  ✓/✗ No production TODOs ({PROD_TODOS} found)
+  ✓/✗ .env in .gitignore
+```
+
+**Hard stop:** If SECRET_HITS > 0 → "BLOCKED: Secrets found in committed files. Remove before releasing."
+**Hard stop:** If AUDIT_EXIT is non-zero → "BLOCKED: Critical vulnerabilities found. Run npm audit fix."
+
+## 5. Run Tier Checklist
+
+Load checklist template from `~/.claude/ez-agents/templates/release-checklist.md`.
+
+Run automated checks for the target tier:
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" release check-tier "${TARGET_TIER}"
+```
+
+Display checklist results with pass/fail/skip for each item.
+
+**If `preflight` command:** Display checklist results and exit here.
+
+## 6. Check Coverage (if test coverage available)
+
+```bash
+# Try to find coverage report
+COVERAGE=$(cat coverage/coverage-summary.json 2>/dev/null | jq '.total.lines.pct // 0')
+```
+
+Coverage thresholds by tier:
+- mvp: 60%
+- medium: 80%
+- enterprise: 95%
+
+**If below threshold:** Warning (not hard blocker — tests may not be configured).
+
+## 7. Spawn Release Agent
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+◆ Spawning release agent...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Release agent prompt:
+
+```markdown
+<objective>
+Create a {TARGET_TIER} tier release v{VERSION}.
+</objective>
+
+<release_config>
+Tier: {TARGET_TIER}
+Version: {VERSION}
+Current version: {CURRENT_VERSION}
+</release_config>
+
+<files_to_read>
+- package.json (current version and scripts)
+- CHANGELOG.md (if exists — append new entry)
+- .planning/config.json (release tier config)
+- ~/.claude/ez-agents/templates/release-checklist.md (checklist template)
+- ~/.claude/ez-agents/templates/rollback-plan.md (rollback template)
+</files_to_read>
+
+<security_gate_results>
+{security gate results from step 4}
+</security_gate_results>
+
+<checklist_results>
+{checklist results from step 5}
+</checklist_results>
+
+<tasks>
+1. Create release branch (per tier: trunk | github-flow | gitflow)
+2. Generate changelog from git log since last tag
+3. Bump version in package.json to {VERSION}
+4. Create rollback plan in .planning/releases/v{VERSION}-ROLLBACK-PLAN.md
+5. Commit release artifacts
+6. Tag v{VERSION}
+7. Report production readiness score
+</tasks>
+```
+
+```
+Task(
+  prompt=release_prompt,
+  subagent_type="ez-release-agent",
+  model="{planner_model from init}"
+)
+```
+
+## 8. Handle Agent Return
+
+**`## RELEASE COMPLETE`:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► RELEASE v{version} READY ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{agent summary}
+
+### To Ship
+git push origin {branch} && git push origin v{version}
+
+### Rollback Plan
+.planning/releases/v{version}-ROLLBACK-PLAN.md
+```
+
+**If blocked:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► RELEASE BLOCKED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{blocker details}
+
+Fix the above issues then re-run: /ez:release {tier} v{version}
+```
+
+</process>
+
+<success_criteria>
+- [ ] Tier and version validated
+- [ ] Uncommitted changes check passed
+- [ ] All security gates run (fail on hard blockers)
+- [ ] Tier checklist evaluated
+- [ ] Coverage checked against tier threshold
+- [ ] ez-release-agent spawned with full context
+- [ ] Release branch created per tier strategy
+- [ ] Changelog updated
+- [ ] Version bumped in package.json
+- [ ] Rollback plan written
+- [ ] Tag created
+- [ ] User sees push instructions and production readiness score
+</success_criteria>

package/ez-agents/workflows/remove-phase.md

@@ -1,155 +1,155 @@
-<purpose>
-Remove an unstarted future phase from the project roadmap, delete its directory, renumber all subsequent phases to maintain a clean linear sequence, and commit the change. The git commit serves as the historical record of removal.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<process>
-
-<step name="parse_arguments">
-Parse the command arguments:
-- Argument is the phase number to remove (integer or decimal)
-- Example: `/ez:remove-phase 17` → phase = 17
-- Example: `/ez:remove-phase 16.1` → phase = 16.1
-
-If no argument provided:
-
-```
-ERROR: Phase number required
-Usage: /ez:remove-phase <phase-number>
-Example: /ez:remove-phase 17
-```
-
-Exit.
-</step>
-
-<step name="init_context">
-Load phase operation context:
-
-```bash
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init phase-op "${target}")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Extract: `phase_found`, `phase_dir`, `phase_number`, `commit_docs`, `roadmap_exists`.
-
-Also read STATE.md and ROADMAP.md content for parsing current position.
-</step>
-
-<step name="validate_future_phase">
-Verify the phase is a future phase (not started):
-
-1. Compare target phase to current phase from STATE.md
-2. Target must be > current phase number
-
-If target <= current phase:
-
-```
-ERROR: Cannot remove Phase {target}
-
-Only future phases can be removed:
-- Current phase: {current}
-- Phase {target} is current or completed
-
-To abandon current work, use /ez:pause-work instead.
-```
-
-Exit.
-</step>
-
-<step name="confirm_removal">
-Present removal summary and confirm:
-
-```
-Removing Phase {target}: {Name}
-
-This will:
-- Delete: .planning/phases/{target}-{slug}/
-- Renumber all subsequent phases
-- Update: ROADMAP.md, STATE.md
-
-Proceed? (y/n)
-```
-
-Wait for confirmation.
-</step>
-
-<step name="execute_removal">
-**Delegate the entire removal operation to ez-tools:**
-
-```bash
-RESULT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" phase remove "${target}")
-```
-
-If the phase has executed plans (SUMMARY.md files), ez-tools will error. Use `--force` only if the user confirms:
-
-```bash
-RESULT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" phase remove "${target}" --force)
-```
-
-The CLI handles:
-- Deleting the phase directory
-- Renumbering all subsequent directories (in reverse order to avoid conflicts)
-- Renaming all files inside renumbered directories (PLAN.md, SUMMARY.md, etc.)
-- Updating ROADMAP.md (removing section, renumbering all phase references, updating dependencies)
-- Updating STATE.md (decrementing phase count)
-
-Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `renamed_files`, `roadmap_updated`, `state_updated`.
-</step>
-
-<step name="commit">
-Stage and commit the removal:
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
-```
-
-The commit message preserves the historical record of what was removed.
-</step>
-
-<step name="completion">
-Present completion summary:
-
-```
-Phase {target} ({original-name}) removed.
-
-Changes:
-- Deleted: .planning/phases/{target}-{slug}/
-- Renumbered: {N} directories and {M} files
-- Updated: ROADMAP.md, STATE.md
-- Committed: chore: remove phase {target} ({original-name})
-
----
-
-## What's Next
-
-Would you like to:
-- `/ez:progress` — see updated roadmap status
-- Continue with current phase
-- Review roadmap
-
----
-```
-</step>
-
-</process>
-
-<anti_patterns>
-
-- Don't remove completed phases (have SUMMARY.md files) without --force
-- Don't remove current or past phases
-- Don't manually renumber — use `ez-tools phase remove` which handles all renumbering
-- Don't add "removed phase" notes to STATE.md — git commit is the record
-- Don't modify completed phase directories
-</anti_patterns>
-
-<success_criteria>
-Phase removal is complete when:
-
-- [ ] Target phase validated as future/unstarted
-- [ ] `ez-tools phase remove` executed successfully
-- [ ] Changes committed with descriptive message
-- [ ] User informed of changes
-</success_criteria>
+<purpose>
+Remove an unstarted future phase from the project roadmap, delete its directory, renumber all subsequent phases to maintain a clean linear sequence, and commit the change. The git commit serves as the historical record of removal.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- Argument is the phase number to remove (integer or decimal)
+- Example: `/ez:remove-phase 17` → phase = 17
+- Example: `/ez:remove-phase 16.1` → phase = 16.1
+
+If no argument provided:
+
+```
+ERROR: Phase number required
+Usage: /ez:remove-phase <phase-number>
+Example: /ez:remove-phase 17
+```
+
+Exit.
+</step>
+
+<step name="init_context">
+Load phase operation context:
+
+```bash
+INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init phase-op "${target}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Extract: `phase_found`, `phase_dir`, `phase_number`, `commit_docs`, `roadmap_exists`.
+
+Also read STATE.md and ROADMAP.md content for parsing current position.
+</step>
+
+<step name="validate_future_phase">
+Verify the phase is a future phase (not started):
+
+1. Compare target phase to current phase from STATE.md
+2. Target must be > current phase number
+
+If target <= current phase:
+
+```
+ERROR: Cannot remove Phase {target}
+
+Only future phases can be removed:
+- Current phase: {current}
+- Phase {target} is current or completed
+
+To abandon current work, use /ez:pause-work instead.
+```
+
+Exit.
+</step>
+
+<step name="confirm_removal">
+Present removal summary and confirm:
+
+```
+Removing Phase {target}: {Name}
+
+This will:
+- Delete: .planning/phases/{target}-{slug}/
+- Renumber all subsequent phases
+- Update: ROADMAP.md, STATE.md
+
+Proceed? (y/n)
+```
+
+Wait for confirmation.
+</step>
+
+<step name="execute_removal">
+**Delegate the entire removal operation to ez-tools:**
+
+```bash
+RESULT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" phase remove "${target}")
+```
+
+If the phase has executed plans (SUMMARY.md files), ez-tools will error. Use `--force` only if the user confirms:
+
+```bash
+RESULT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" phase remove "${target}" --force)
+```
+
+The CLI handles:
+- Deleting the phase directory
+- Renumbering all subsequent directories (in reverse order to avoid conflicts)
+- Renaming all files inside renumbered directories (PLAN.md, SUMMARY.md, etc.)
+- Updating ROADMAP.md (removing section, renumbering all phase references, updating dependencies)
+- Updating STATE.md (decrementing phase count)
+
+Extract from result: `removed`, `directory_deleted`, `renamed_directories`, `renamed_files`, `roadmap_updated`, `state_updated`.
+</step>
+
+<step name="commit">
+Stage and commit the removal:
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "chore: remove phase {target} ({original-phase-name})" --files .planning/
+```
+
+The commit message preserves the historical record of what was removed.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {target} ({original-name}) removed.
+
+Changes:
+- Deleted: .planning/phases/{target}-{slug}/
+- Renumbered: {N} directories and {M} files
+- Updated: ROADMAP.md, STATE.md
+- Committed: chore: remove phase {target} ({original-name})
+
+---
+
+## What's Next
+
+Would you like to:
+- `/ez:progress` — see updated roadmap status
+- Continue with current phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't remove completed phases (have SUMMARY.md files) without --force
+- Don't remove current or past phases
+- Don't manually renumber — use `ez-tools phase remove` which handles all renumbering
+- Don't add "removed phase" notes to STATE.md — git commit is the record
+- Don't modify completed phase directories
+</anti_patterns>
+
+<success_criteria>
+Phase removal is complete when:
+
+- [ ] Target phase validated as future/unstarted
+- [ ] `ez-tools phase remove` executed successfully
+- [ ] Changes committed with descriptive message
+- [ ] User informed of changes
+</success_criteria>