@howlil/ez-agents 3.5.0 → 4.0.0

package/ez-agents/workflows/arch-review.md

@@ -1,54 +0,0 @@
-<purpose>
-Run a Tech Lead architecture review on phase plans. Reads phase PLAN.md files and checks for pattern drift, technical debt, security issues, and design conflicts.
-</purpose>
-
-<process>
-
-## 1. Initialize
-
-Parse $ARGUMENTS for phase number.
-
-```bash
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init plan-phase "$PHASE")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Extract: `phase_dir`, `phase_number`, `phase_name`, `planner_model`.
-
-## 2. Validate
-
-Check phase directory and plans exist. If no PLAN.md found: error "No plans found for phase {N}. Run /ez:plan-phase first."
-
-## 3. Spawn Tech Lead Review
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► ARCH REVIEW — Phase {N}: {Name}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-```
-Task(
-  prompt="Review architecture of Phase {phase_number}: {phase_name}.
-  Read all PLAN.md files in {phase_dir}.
-  Check: pattern consistency, technical debt, security, cross-phase conflicts, dependencies.
-  Report: BLOCKERS (must fix), WARNINGS (should fix), ADVISORY (consider).
-  Output: ## Tech Lead Review: Phase {N} — {status}",
-  subagent_type="ez-tech-lead-agent",
-  model="{planner_model}"
-)
-```
-
-## 4. Present Results
-
-Display agent output directly. If BLOCKER found: highlight "Fix before /ez:execute-phase". If APPROVE: confirm safe to execute.
-
-</process>
-
-<success_criteria>
-- [ ] Phase validated
-- [ ] Tech lead agent spawned
-- [ ] Findings presented with severity
-- [ ] Clear go/no-go for execution
-</success_criteria>

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

@@ -1,255 +0,0 @@
-# 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

@@ -1,206 +0,0 @@
-<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>