@howlil/ez-agents 3.4.2 → 4.0.0

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

@@ -40,6 +40,28 @@ mkdir -p ".planning/phases/${padded_phase}-${phase_slug}"
 
 **Existing artifacts from init:** `has_research`, `has_plans`, `plan_count`.
 
+<auto_invoke>
+Check for --no-auto in ARGUMENTS. If not present:
+
+```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"` or `--no-auto` is in ARGUMENTS: skip, proceed to step 3.
+
+**Conditional discuss-phase for sensitive areas:**
+Read phase name and objective from the phase arguments and roadmap. Check if they contain any of these sensitive keywords (case-insensitive):
+`auth`, `login`, `jwt`, `oauth`, `database`, `migration`, `schema`, `payment`, `billing`, `security`
+
+If YES and no CONTEXT.md exists in the phase directory and `--skip-discussion` is NOT in ARGUMENTS:
+  → Display: `[auto] Sensitive area detected — running pre-flight discussion...`
+  → Invoke: Skill(ez:discuss-phase, args: phase_number + " --auto")
+  → Continue to step 3.
+
+If NO match OR CONTEXT.md already exists OR `--skip-discussion` present: skip silently, proceed to step 3.
+
+**Detection rule:** Only trigger if phase name or goal in ROADMAP.md contains one of the explicit keywords above. False-negative is safer than false-positive — when uncertain, skip.
+</auto_invoke>
+
 ## 3. Validate Phase
 
 ```bash
@@ -259,46 +281,6 @@ test -f "${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md" && echo "VALIDATION_CREATED
 
 **If not found:** Warn and continue — plans may fail Dimension 8.
 
-## 5.6. UI Design Contract Gate
-
-> Skip if `workflow.ui_phase` is explicitly `false` AND `workflow.ui_safety_gate` is explicitly `false` in `.planning/config.json`. If keys are absent, treat as enabled.
-
-```bash
-UI_PHASE_CFG=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
-UI_GATE_CFG=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get workflow.ui_safety_gate 2>/dev/null || echo "true")
-```
-
-**If both are `false`:** Skip to step 6.
-
-Check if phase has frontend indicators:
-
-```bash
-PHASE_SECTION=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase "${PHASE}" 2>/dev/null)
-echo "$PHASE_SECTION" | grep -iE "UI|interface|frontend|component|layout|page|screen|view|form|dashboard|widget" > /dev/null 2>&1
-HAS_UI=$?
-```
-
-**If `HAS_UI` is 0 (frontend indicators found):**
-
-Check for existing UI-SPEC:
-```bash
-UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-```
-
-**If UI-SPEC.md found:** Set `UI_SPEC_PATH=$UI_SPEC_FILE`. Display: `Using UI design contract: ${UI_SPEC_PATH}`
-
-**If UI-SPEC.md missing AND `UI_GATE_CFG` is `true`:**
-
-Use AskUserQuestion:
-- header: "UI Design Contract"
-- question: "Phase {N} has frontend indicators but no UI-SPEC.md. Generate a design contract before planning?"
-- options:
-  - "Generate UI-SPEC first" → Display: "Run `/ez:ui-phase {N}` then re-run `/ez:plan-phase {N}`". Exit workflow.
-  - "Continue without UI-SPEC" → Continue to step 6.
-  - "Not a frontend phase" → Continue to step 6.
-
-**If `HAS_UI` is 1 (no frontend indicators):** Skip silently to step 6.
-
 ## 6. Check Existing Plans
 
 ```bash

package/ez-agents/workflows/progress.md

@@ -8,6 +8,19 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 <process>
 
+<auto_invoke>
+Check for --no-auto in ARGUMENTS. If not present, also check:
+```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 not `"false"` and `--no-auto` is not in ARGUMENTS:
+```bash
+HEALTH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" health --json 2>/dev/null)
+```
+- If FAIL: display a warning in the output report but do NOT stop (progress continues)
+- If PASS: silent (do not show to user)
+</auto_invoke>
+
 <step name="init_context">
 **Load progress context (paths only):**
 
@@ -219,16 +232,10 @@ Check if `{phase_num}-CONTEXT.md` exists in phase directory.
 
 **Phase {N}: {Name}** — {Goal from ROADMAP.md}
 
-`/ez:discuss-phase {phase}` — gather context and clarify approach
+`/ez:discuss-phase {phase}`
 
 <sub>`/clear` first → fresh context window</sub>
 
----
-
-**Also available:**
-- `/ez:plan-phase {phase}` — skip discussion, plan directly
-- `/ez:list-phase-assumptions {phase}` — see Claude's assumptions
-
 ---
 ```
 
@@ -249,12 +256,6 @@ UAT.md exists with gaps (diagnosed issues). User needs to plan fixes.
 
 <sub>`/clear` first → fresh context window</sub>
 
----
-
-**Also available:**
-- `/ez:execute-phase {phase}` — execute phase plans
-- `/ez:verify-work {phase}` — run more UAT testing
-
 ---
 ```
 
@@ -292,16 +293,10 @@ Read ROADMAP.md to get the next phase's name and goal.
 
 **Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
 
-`/ez:discuss-phase {Z+1}` — gather context and clarify approach
+`/ez:discuss-phase {Z+1}`
 
 <sub>`/clear` first → fresh context window</sub>
 
----
-
-**Also available:**
-- `/ez:plan-phase {Z+1}` — skip discussion, plan directly
-- `/ez:verify-work {Z}` — user acceptance test before continuing
-
 ---
 ```
 
@@ -324,11 +319,6 @@ All {N} phases finished!
 
 <sub>`/clear` first → fresh context window</sub>
 
----
-
-**Also available:**
-- `/ez:verify-work` — user acceptance test before completing milestone
-
 ---
 ```
 

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/resume-session.md

@@ -0,0 +1,215 @@
+# Workflow: resume-session
+
+**Purpose:** Resume work from a previous session with full context restoration
+
+**Related Commands:** `/ez:resume`
+
+---
+
+## Workflow Steps
+
+### 1. Load and Validate Session
+
+```
+SessionManager mgr = new SessionManager();
+Session session = sessionId ? mgr.loadSession(sessionId) : mgr.getLastSession();
+
+if (!session) {
+  output("No previous sessions found. Start a new session with your work.");
+  exit;
+}
+
+logger.info('Resuming session', { sessionId: session.metadata.session_id });
+```
+
+### 2. Compare with Current State
+
+```
+Load current STATE.md
+Extract current phase, plan, incomplete tasks from STATE.md
+
+sessionPhase = session.state.current_phase
+sessionPlan = session.state.current_plan
+statePhase = STATE.md.current_phase
+statePlan = STATE.md.current_plan
+
+needsReconciliation = (sessionPhase !== statePhase) || (sessionPlan !== statePlan)
+```
+
+### 3. If Reconciliation Needed
+
+**Display Warning:**
+```
+⚠️ Session state differs from current project state
+
+Session shows:
+- Phase: {session.state.current_phase}
+- Plan: {session.state.current_plan}
+
+Current STATE.md shows:
+- Phase: {state.current_phase}
+- Plan: {state.current_plan}
+```
+
+**Offer Options:**
+```
+How would you like to reconcile?
+
+1. Use session state (overwrite STATE.md)
+2. Use current state (ignore session state)
+3. Manual review (show both, let user decide)
+```
+
+**Handle Choice:**
+- "1": Update STATE.md with session.state values
+- "2": Keep STATE.md unchanged, use session context only
+- "3": Show side-by-side comparison, let user edit
+
+### 4. Load Context
+
+```
+// Load recent transcript for context
+transcript = session.context.transcript
+if (Array.isArray(transcript)) {
+  recentMessages = transcript.slice(-20) // Last 20 messages
+}
+
+// Load tasks
+completedTasks = session.context.tasks.filter(t => t.status === 'completed')
+incompleteTasks = session.state.incomplete_tasks
+
+// Load decisions
+decisions = session.context.decisions
+
+// Load file changes
+fileChanges = session.context.file_changes
+```
+
+### 5. Update STATE.md
+
+```
+ez-tools state record-session \
+  --stopped-at "{session.state.last_action}" \
+  --resume-file "{session.metadata.session_id}"
+
+// Update phase/plan if using session state
+if (useSessionState) {
+  ez-tools state update "Current Phase" "{session.metadata.phase}"
+  ez-tools state update "Current Plan" "{session.metadata.plan}"
+}
+```
+
+### 6. Prepare for Continuation
+
+```
+// Identify incomplete work
+incompleteTasks = session.state.incomplete_tasks || []
+
+// Identify next action
+nextAction = session.state.next_recommended_action
+
+// Load relevant files
+if (session.metadata.phase && session.metadata.plan) {
+  planFile = `.planning/phases/${session.metadata.phase}/.../${session.metadata.plan}-PLAN.md`
+  summaryFile = `.planning/phases/${session.metadata.phase}/.../${session.metadata.plan}-PLAN-SUMMARY.md`
+  
+  if (fileExists(planFile)) {
+    loadFile(planFile)
+  }
+}
+
+// Load incomplete task files
+for (task of incompleteTasks) {
+  if (task.file) {
+    loadFile(task.file)
+  }
+}
+```
+
+### 7. Output Resumption Confirmation
+
+```
+╔══════════════════════════════════════════════════════════════╗
+║  SESSION RESUMED                                              ║
+╠══════════════════════════════════════════════════════════════╣
+║  Session: {session.metadata.session_id}                       ║
+║  Phase: {session.metadata.phase}                              ║
+║  Plan: {session.metadata.plan}                                ║
+║  Next action: {session.state.next_recommended_action}         ║
+╚══════════════════════════════════════════════════════════════╝
+
+Context loaded:
+- {incompleteTasks.length} incomplete tasks
+- {decisions.length} decisions recorded
+- {fileChanges.length} file changes
+
+Ready to continue. What would you like to do?
+
+1. Continue with recommended action
+2. Review incomplete tasks
+3. View session transcript
+4. Something else
+```
+
+---
+
+## Error Handling
+
+### Session Not Found
+```
+if (!session) {
+  output(`Session not found: ${sessionId}`);
+  output("Use /ez:list-sessions to see available sessions.");
+  exit;
+}
+```
+
+### Corrupted Session File
+```
+try {
+  session = JSON.parse(content);
+} catch (err) {
+  logger.error('Corrupted session file', { sessionId, error: err.message });
+  output(`Error: Session file is corrupted: ${sessionId}`);
+  output("Consider deleting the file or contacting support.");
+  exit;
+}
+```
+
+### Broken Chain Links
+```
+if (session.metadata.session_chain) {
+  for (chainId of session.metadata.session_chain) {
+    if (!mgr.loadSession(chainId)) {
+      warnings.push(`Missing linked session: ${chainId}`);
+    }
+  }
+  
+  if (warnings.length > 0) {
+    output("⚠️ Session chain has broken links:");
+    for (warning of warnings) {
+      output(`  - ${warning}`);
+    }
+  }
+}
+```
+
+---
+
+## State Transitions
+
+**Before:** Session ended, STATE.md shows stopped state
+
+**After:** Session resumed, STATE.md updated with:
+- `Last session`: Current timestamp
+- `Resume file`: Session ID
+- `Stopped at`: Last action from session
+
+---
+
+## Related Files
+
+- `ez-agents/bin/lib/session-manager.cjs` - Session loading
+- `ez-agents/bin/lib/session-chain.cjs` - Chain navigation
+- `ez-agents/bin/lib/state.cjs` - STATE.md updates
+- `.planning/sessions/` - Session storage directory