@howlil/ez-agents 3.4.2 → 3.5.0

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

@@ -12,6 +12,34 @@ Read STATE.md before any operation to load project context.
 
 <process>
 
+<auto_invoke>
+Run BEFORE the initialize step. Check flags from ARGUMENTS:
+
+**Flag handling:**
+- If ARGUMENTS contains `--no-auto`: skip all auto_invoke blocks, proceed directly to initialize.
+- If ARGUMENTS contains `--verbose`: display detail for every auto_invoke step.
+
+**Pre-flight health check (always, unless --no-auto):**
+```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 all auto_invoke, proceed to initialize.
+
+```bash
+HEALTH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" health --json 2>/dev/null)
+```
+- If output shows status FAIL: display error, STOP execution.
+- If PASS: display `[auto] ✅ health check passed` only when `--verbose` flag is present; otherwise silent.
+
+**Conditional discuss-phase:**
+Read tier from `.planning/config.json` (`release.tier`). If tier is `medium` or `enterprise` AND no CONTEXT.md exists in the phase directory AND `--skip-discussion` is not in ARGUMENTS:
+  → Display: `[auto] Running pre-flight discussion...`
+  → Invoke: Skill(ez:discuss-phase, args: phase_number + " --auto")
+  → Continue to initialize.
+
+If conditions are not met: skip silently.
+</auto_invoke>
+
 <step name="initialize" priority="first">
 Load all context in one call:
 
@@ -447,6 +475,23 @@ Read and follow `~/.claude/ez-agents/workflows/transition.md`, passing through t
 ```
 </step>
 
+<auto_invoke_post>
+Run AFTER all waves complete. Skip if --no-auto is in ARGUMENTS or `smart_orchestration.enabled` is false.
+
+**Post-execution verify-work:**
+Display: `[auto] Running verification...`
+Invoke: Skill(ez:verify-work, args: phase_number)
+- If PASS: display `[auto] ✅ Verification passed`
+- If FAIL: display `⚠️ Verification warnings (non-blocking)` — show details, do NOT block
+
+**Scope creep detection:**
+Check if there is scope creep from DISCUSSION.md (if it exists):
+```bash
+grep -i "scope creep\|out of scope\|BLOCKER" .planning/phases/${PHASE_DIR}/DISCUSSION.md 2>/dev/null
+```
+If any match found: display `[auto] Scope creep detected — creating todos...` → Invoke: Skill(ez:add-todo)
+</auto_invoke_post>
+
 </process>
 
 <context_efficiency>

package/ez-agents/workflows/export-session.md

@@ -0,0 +1,255 @@
+# Workflow: export-session
+
+**Purpose:** Export session data for model handoff or archival
+
+**Related Commands:** `/ez:export-session`
+
+---
+
+## Workflow Steps
+
+### 1. Parameters
+
+```
+session_id: string (default: 'last')
+format: 'markdown' | 'json' (default: 'markdown')
+output_path: string (default: auto-generated)
+```
+
+### 2. Resolve Session
+
+```
+SessionManager mgr = new SessionManager();
+
+if (session_id === 'last') {
+  session = mgr.getLastSession();
+  if (!session) {
+    throw error("No sessions found");
+  }
+  session_id = session.metadata.session_id;
+} else {
+  session = mgr.loadSession(session_id);
+  if (!session) {
+    throw error(`Session not found: ${session_id}`);
+  }
+}
+
+logger.info('Exporting session', { session_id });
+```
+
+### 3. Validate Format
+
+```
+if (!['markdown', 'json'].includes(format)) {
+  throw error("Format must be 'markdown' or 'json'");
+}
+```
+
+### 4. Generate Output Path
+
+```
+if (!output_path) {
+  ext = format === 'markdown' ? 'md' : 'json';
+  output_path = `.planning/sessions/export-${session_id}.${ext}`;
+}
+```
+
+### 5. Export
+
+```
+SessionExport exporter = new SessionExport(mgr);
+
+try {
+  result = exporter.exportToFile(session_id, format, output_path);
+} catch (SessionExportError err) {
+  logger.error('Export failed', { session_id, format, error: err.message });
+  throw error(`Export failed: ${err.message}`);
+}
+```
+
+### 6. Verify Output
+
+```
+if (!fs.existsSync(output_path)) {
+  throw error("Export verification failed: File not created");
+}
+
+const stats = fs.statSync(output_path);
+if (stats.size === 0) {
+  throw error("Export verification failed: File is empty");
+}
+
+logger.info('Export verified', { path: output_path, size: stats.size });
+```
+
+### 7. Log Success
+
+```
+logger.info('Session exported', { 
+  session_id, 
+  format, 
+  output_path,
+  size: stats.size 
+});
+```
+
+### 8. Return Result
+
+```
+return {
+  success: true,
+  path: output_path,
+  format: format,
+  size: stats.size
+};
+```
+
+---
+
+## Output Format Examples
+
+### Markdown Export
+```markdown
+# Session Export: session-20260319-143052
+
+**Exported:** 2026-03-19T15:45:00.000Z
+**Model:** qwen
+**Phase:** 18
+**Plan:** 18
+**Duration:** 1h 15m
+
+---
+
+## Session Summary
+
+**Objective:** Implement session memory and model continuity
+
+**Completed:**
+- Task 1: Create session error classes
+- Task 2: Create session manager
+
+**Incomplete:**
+- Task 3: Create session export module
+
+---
+
+## Key Decisions
+
+1. **Use timestamp-based session IDs**
+   - Rationale: Easy to sort and identify
+   - Status: Implemented
+
+---
+
+## File Changes
+
+| File | Action | Reason |
+|------|--------|--------|
+| ez-agents/bin/lib/session-errors.cjs | created | Error classes |
+| ez-agents/bin/lib/session-manager.cjs | created | Core module |
+
+---
+
+## Open Questions
+
+None
+
+---
+
+## Blockers/Concerns
+
+None
+
+---
+
+## Recommended Next Actions
+
+- Complete session export module implementation
+
+---
+
+## Session Chain
+
+- Previous: session-20260319-120000
+- Current: session-20260319-143052
+- Next: none
+```
+
+### JSON Export
+```json
+{
+  "export_version": "1.0",
+  "exported_at": "2026-03-19T15:45:00.000Z",
+  "export_format": "json",
+  "session": {
+    "metadata": {
+      "session_id": "session-20260319-143052",
+      "session_version": "1.0",
+      "started_at": "2026-03-19T14:30:52.000Z",
+      "ended_at": "2026-03-19T15:45:00.000Z",
+      "model": "qwen",
+      "phase": 18,
+      "plan": 18,
+      "status": "completed",
+      "session_chain": ["session-20260319-120000"],
+      "token_usage": {
+        "input": 50000,
+        "output": 30000,
+        "total": 80000
+      }
+    },
+    "context": {
+      "transcript": "...",
+      "tasks": [],
+      "decisions": [],
+      "file_changes": [],
+      "open_questions": [],
+      "blockers": []
+    },
+    "state": {
+      "current_phase": 18,
+      "current_plan": 18,
+      "incomplete_tasks": [],
+      "last_action": "Task 2 complete",
+      "next_recommended_action": "Continue with Task 3"
+    }
+  }
+}
+```
+
+---
+
+## Error Handling
+
+### Session Not Found
+```
+if (!session) {
+  throw error(`Session not found: ${session_id}`);
+}
+```
+
+### Invalid Format
+```
+if (!['markdown', 'json'].includes(format)) {
+  throw error(`Unsupported export format: ${format}`);
+}
+```
+
+### Write Failure
+```
+try {
+  safePlanningWriteSync(output_path, content);
+} catch (err) {
+  logger.error('Write failed', { path: output_path, error: err.message });
+  throw error(`Failed to write export file: ${err.message}`);
+}
+```
+
+---
+
+## Related Files
+
+- `ez-agents/bin/lib/session-manager.cjs` - Session loading
+- `ez-agents/bin/lib/session-export.cjs` - Export logic
+- `ez-agents/bin/lib/planning-write.cjs` - Safe file writes
+- `.planning/sessions/` - Output directory

package/ez-agents/workflows/gather-requirements.md

@@ -0,0 +1,206 @@
+<purpose>
+Orchestrate BDD requirements gathering for a phase. Spawns ez-requirements-agent to interview user, produce .feature files, validate INVEST, and create acceptance criteria documents.
+</purpose>
+
+<process>
+
+## 1. Initialize
+
+```bash
+INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init plan-phase "${PHASE}" 2>/dev/null || echo '{}')
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`, `context_path`, `requirements_path`, `state_path`, `roadmap_path`.
+
+**If `.planning/` missing:** Error — run `/ez:new-project` first.
+
+## 2. Parse Arguments
+
+Extract from $ARGUMENTS:
+- Phase number (integer or decimal like `3.1`)
+- `--auto` flag — skip interactive interview, derive from context
+
+**If no phase number:** Detect next unplanned phase from roadmap.
+
+## 3. Check Phase Exists
+
+```bash
+PHASE_INFO=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase "${PHASE}")
+```
+
+**If not found:** Error — phase does not exist in ROADMAP.md.
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► GATHERING REQUIREMENTS — Phase {X}: {Name}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## 4. Check Existing .feature Files
+
+```bash
+ls specs/features/ 2>/dev/null
+find specs/features/ -name "*.feature" 2>/dev/null | wc -l
+```
+
+**If .feature files exist for this phase:**
+
+Check `.planning/phases/{phase_dir}/{phase_num}-ACCEPTANCE-CRITERIA.md`.
+
+If exists, ask:
+1. "Regenerate — replace existing requirements" → Clear old files, re-gather
+2. "Extend — add more scenarios" → Append mode
+3. "View existing" → Display ACCEPTANCE-CRITERIA.md and exit
+
+**If no .feature files:** Proceed to step 5.
+
+## 5. Spawn ez-requirements-agent
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+◆ Spawning requirements agent...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Requirements prompt:
+
+```markdown
+<objective>
+Gather BDD requirements for Phase {phase_number}: {phase_name}.
+Mode: {interactive | auto}
+</objective>
+
+<files_to_read>
+- {state_path} (Project State)
+- {roadmap_path} (Roadmap — phase goal and requirements)
+- {requirements_path} (Existing requirements)
+- {context_path} (USER DECISIONS from /ez:discuss-phase, if exists)
+</files_to_read>
+
+<phase_info>
+Phase: {phase_number}
+Name: {phase_name}
+Goal: {goal from ROADMAP}
+Phase directory: {phase_dir}
+Padded phase: {padded_phase}
+</phase_info>
+
+<mode>
+{If --auto:}
+AUTO MODE: Do NOT ask the user questions. Derive all requirements from:
+1. ROADMAP.md phase goal and description
+2. CONTEXT.md locked decisions (if exists)
+3. Existing REQUIREMENTS.md entries for this phase
+
+{If interactive:}
+INTERACTIVE MODE: Conduct a focused interview with the user.
+- Group questions into batches of 3-4 at a time
+- Confirm understanding after each batch before proceeding
+- Focus on observable behavior, not implementation
+</mode>
+
+<project_instructions>
+Read ./CLAUDE.md if exists — follow project-specific guidelines.
+Check .claude/skills/ or .agents/skills/ — apply skill rules to requirements scope.
+</project_instructions>
+```
+
+```
+Task(
+  prompt=requirements_prompt,
+  subagent_type="ez-requirements-agent",
+  model="{planner_model from init}"
+)
+```
+
+## 6. Handle Agent Return
+
+**`## REQUIREMENTS GATHERED`:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► REQUIREMENTS COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{agent summary}
+```
+
+Continue to step 7.
+
+**`## REQUIREMENTS BLOCKED`:**
+
+Display blocker details. Offer:
+1. "Provide more context about the phase goal"
+2. "Use --auto mode to derive from existing context"
+3. "Skip requirements for this phase"
+
+## 7. Validate BDD Output
+
+```bash
+# Check .feature files were created
+FEATURE_COUNT=$(find specs/features/ -name "*.feature" 2>/dev/null | wc -l)
+
+# Validate structure
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" bdd validate specs/features/ 2>/dev/null || true
+
+# Check ACCEPTANCE-CRITERIA.md exists
+ls .planning/phases/${PHASE_DIR}/*-ACCEPTANCE-CRITERIA.md 2>/dev/null
+```
+
+Report findings:
+```
+Validation:
+  ✓ {N} .feature file(s) created
+  ✓ INVEST: {score}/6 dimensions pass
+  ✓ MoSCoW: {must} must / {should} should / {could} could / {wont} wont
+  ✓ ACCEPTANCE-CRITERIA.md created
+```
+
+If INVEST score < 5, warn: "User stories may need refinement before planning — run `/ez:gather-requirements {phase}` again."
+
+## 8. Present Final Status
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► PHASE {X} REQUIREMENTS ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Phase {X}: {Name}**
+Feature files: {N}
+Scenarios: {M} total ({must} @must / {should} @should / {could} @could)
+INVEST: {score}/6
+
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Plan Phase {X}** — create implementation plans cross-checked against BDD specs
+
+/ez:plan-phase {X}
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- cat specs/features/{domain}/*.feature — review scenarios
+- cat .planning/phases/{phase-dir}/{phase}-ACCEPTANCE-CRITERIA.md — review acceptance criteria
+- /ez:discuss-phase {X} — capture design decisions first (if not done)
+```
+
+</process>
+
+<success_criteria>
+- [ ] Phase validated against roadmap
+- [ ] Existing .feature files checked
+- [ ] ez-requirements-agent spawned with correct mode and file paths
+- [ ] .feature files created in specs/features/
+- [ ] Every scenario has MoSCoW + tier tags
+- [ ] INVEST validation run
+- [ ] ACCEPTANCE-CRITERIA.md exists in phase directory
+- [ ] REQUIREMENTS-BDD.md updated
+- [ ] User sees summary with scenario counts and next steps
+</success_criteria>

package/ez-agents/workflows/help.md

@@ -221,6 +221,54 @@ Create context handoff when pausing work mid-phase.
 
 Usage: `/ez:pause-work`
 
+**`/ez:resume`**
+Resume from last session or navigate session chain (Phase 18+).
+
+- Loads most recent session from `.planning/sessions/`
+- Shows formatted summary with model, phase, plan, duration
+- Displays incomplete items, decisions, file changes
+- Offers options: Continue, Show transcript, Export, Navigate chain, Start fresh
+- Supports navigation: `--previous`, `--next`, `--chain`
+
+Usage: `/ez:resume`
+Usage: `/ez:resume session-20260319-143052`
+Usage: `/ez:resume --previous`
+
+**`/ez:export-session`**
+Export session for model handoff or archival.
+
+- Exports last session by default (or specified session)
+- Supports markdown (human-readable) and JSON formats
+- Includes: summary, tasks, decisions, file changes, open questions, blockers
+- Output to `.planning/sessions/export-{session_id}.{ext}`
+
+Usage: `/ez:export-session`
+Usage: `/ez:export-session session-20260319-143052 --format json`
+Usage: `/ez:export-session --output /path/to/file.md`
+
+**`/ez:import-session`**
+Import session from exported file.
+
+- Validates session structure and chain integrity
+- Supports model-specific adapters (claude, qwen, openai, kimi)
+- Creates new session with imported context
+- Offers to resume imported session
+
+Usage: `/ez:import-session /path/to/session.json`
+Usage: `/ez:import-session session.json --source-model claude`
+
+**`/ez:list-sessions`**
+List all sessions with metadata and disk usage.
+
+- Shows: session_id, started_at, ended_at, model, phase, plan, status
+- Sorted by date (newest first)
+- Displays disk usage summary
+- Supports `--limit N` and `--json` flags
+
+Usage: `/ez:list-sessions`
+Usage: `/ez:list-sessions --limit 10`
+Usage: `/ez:list-sessions --json`
+
 ### Debugging
 
 **`/ez:debug [issue description]`**
@@ -483,6 +531,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