@howlil/ez-agents 3.5.0 → 4.0.0

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

@@ -1,290 +0,0 @@
-<purpose>
-Generate a UI design contract (UI-SPEC.md) for frontend phases. Orchestrates ez-ui-researcher and ez-ui-checker with a revision loop. Inserts between discuss-phase and plan-phase in the lifecycle.
-
-UI-SPEC.md locks spacing, typography, color, copywriting, and design system decisions before the planner creates tasks. This prevents design debt caused by ad-hoc styling decisions during execution.
-</purpose>
-
-<required_reading>
-@~/.claude/ez-agents/references/ui-brand.md
-</required_reading>
-
-<process>
-
-## 1. Initialize
-
-```bash
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init plan-phase "$PHASE")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_context`, `has_research`, `commit_docs`.
-
-**File paths:** `state_path`, `roadmap_path`, `requirements_path`, `context_path`, `research_path`.
-
-Resolve UI agent models:
-
-```bash
-UI_RESEARCHER_MODEL=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" resolve-model ez-ui-researcher --raw)
-UI_CHECKER_MODEL=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" resolve-model ez-ui-checker --raw)
-```
-
-Check config:
-
-```bash
-UI_ENABLED=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-get workflow.ui_phase 2>/dev/null || echo "true")
-```
-
-**If `UI_ENABLED` is `false`:**
-```
-UI phase is disabled in config. Enable via /ez:settings.
-```
-Exit workflow.
-
-**If `planning_exists` is false:** Error — run `/ez:new-project` first.
-
-## 2. Parse and Validate Phase
-
-Extract phase number from $ARGUMENTS. If not provided, detect next unplanned phase.
-
-```bash
-PHASE_INFO=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase "${PHASE}")
-```
-
-**If `found` is false:** Error with available phases.
-
-## 3. Check Prerequisites
-
-**If `has_context` is false:**
-```
-No CONTEXT.md found for Phase {N}.
-Recommended: run /ez:discuss-phase {N} first to capture design preferences.
-Continuing without user decisions — UI researcher will ask all questions.
-```
-Continue (non-blocking).
-
-**If `has_research` is false:**
-```
-No RESEARCH.md found for Phase {N}.
-Note: stack decisions (component library, styling approach) will be asked during UI research.
-```
-Continue (non-blocking).
-
-## 4. Check Existing UI-SPEC
-
-```bash
-UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-```
-
-**If exists:** Use AskUserQuestion:
-- header: "Existing UI-SPEC"
-- question: "UI-SPEC.md already exists for Phase {N}. What would you like to do?"
-- options:
-  - "Update — re-run researcher with existing as baseline"
-  - "View — display current UI-SPEC and exit"
-  - "Skip — keep current UI-SPEC, proceed to verification"
-
-If "View": display file contents, exit.
-If "Skip": proceed to step 7 (checker).
-If "Update": continue to step 5.
-
-## 5. Spawn ez-ui-researcher
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► UI DESIGN CONTRACT — PHASE {N}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning UI researcher...
-```
-
-Build prompt:
-
-```markdown
-Read ~/.claude/agents/ez-ui-researcher.md for instructions.
-
-<objective>
-Create UI design contract for Phase {phase_number}: {phase_name}
-Answer: "What visual and interaction contracts does this phase need?"
-</objective>
-
-<files_to_read>
-- {state_path} (Project State)
-- {roadmap_path} (Roadmap)
-- {requirements_path} (Requirements)
-- {context_path} (USER DECISIONS from /ez:discuss-phase)
-- {research_path} (Technical Research — stack decisions)
-</files_to_read>
-
-<output>
-Write to: {phase_dir}/{padded_phase}-UI-SPEC.md
-Template: ~/.claude/ez-agents/templates/UI-SPEC.md
-</output>
-
-<config>
-commit_docs: {commit_docs}
-phase_dir: {phase_dir}
-padded_phase: {padded_phase}
-</config>
-```
-
-Omit null file paths from `<files_to_read>`.
-
-```
-Task(
-  prompt=ui_research_prompt,
-  subagent_type="ez-ui-researcher",
-  model="{UI_RESEARCHER_MODEL}",
-  description="UI Design Contract Phase {N}"
-)
-```
-
-## 6. Handle Researcher Return
-
-**If `## UI-SPEC COMPLETE`:**
-Display confirmation. Continue to step 7.
-
-**If `## UI-SPEC BLOCKED`:**
-Display blocker details and options. Exit workflow.
-
-## 7. Spawn ez-ui-checker
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► VERIFYING UI-SPEC
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ Spawning UI checker...
-```
-
-Build prompt:
-
-```markdown
-Read ~/.claude/agents/ez-ui-checker.md for instructions.
-
-<objective>
-Validate UI design contract for Phase {phase_number}: {phase_name}
-Check all 6 dimensions. Return APPROVED or BLOCKED.
-</objective>
-
-<files_to_read>
-- {phase_dir}/{padded_phase}-UI-SPEC.md (UI Design Contract — PRIMARY INPUT)
-- {context_path} (USER DECISIONS — check compliance)
-- {research_path} (Technical Research — check stack alignment)
-</files_to_read>
-
-<config>
-ui_safety_gate: {ui_safety_gate config value}
-</config>
-```
-
-```
-Task(
-  prompt=ui_checker_prompt,
-  subagent_type="ez-ui-checker",
-  model="{UI_CHECKER_MODEL}",
-  description="Verify UI-SPEC Phase {N}"
-)
-```
-
-## 8. Handle Checker Return
-
-**If `## UI-SPEC VERIFIED`:**
-Display dimension results. Proceed to step 10.
-
-**If `## ISSUES FOUND`:**
-Display blocking issues. Proceed to step 9.
-
-## 9. Revision Loop (Max 2 Iterations)
-
-Track `revision_count` (starts at 0).
-
-**If `revision_count` < 2:**
-- Increment `revision_count`
-- Re-spawn ez-ui-researcher with revision context:
-
-```markdown
-<revision>
-The UI checker found issues with the current UI-SPEC.md.
-
-### Issues to Fix
-{paste blocking issues from checker return}
-
-Read the existing UI-SPEC.md, fix ONLY the listed issues, re-write the file.
-Do NOT re-ask the user questions that are already answered.
-</revision>
-```
-
-- After researcher returns → re-spawn checker (step 7)
-
-**If `revision_count` >= 2:**
-```
-Max revision iterations reached. Remaining issues:
-
-{list remaining issues}
-
-Options:
-1. Force approve — proceed with current UI-SPEC (FLAGs become accepted)
-2. Edit manually — open UI-SPEC.md in editor, re-run /ez:ui-phase
-3. Abandon — exit without approving
-```
-
-Use AskUserQuestion for the choice.
-
-## 10. Present Final Status
-
-Display:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► UI-SPEC READY ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {N}: {Name}** — UI design contract approved
-
-Dimensions: 6/6 passed
-{If any FLAGs: "Recommendations: {N} (non-blocking)"}
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next Up
-
-**Plan Phase {N}** — planner will use UI-SPEC.md as design context
-
-`/ez:plan-phase {N}`
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-```
-
-## 11. Commit (if configured)
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs(${padded_phase}): UI design contract" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md"
-```
-
-## 12. Update State
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" state record-session \
-  --stopped-at "Phase ${PHASE} UI-SPEC approved" \
-  --resume-file "${PHASE_DIR}/${PADDED_PHASE}-UI-SPEC.md"
-```
-
-</process>
-
-<success_criteria>
-- [ ] Config checked (exit if ui_phase disabled)
-- [ ] Phase validated against roadmap
-- [ ] Prerequisites checked (CONTEXT.md, RESEARCH.md — non-blocking warnings)
-- [ ] Existing UI-SPEC handled (update/view/skip)
-- [ ] ez-ui-researcher spawned with correct context and file paths
-- [ ] UI-SPEC.md created in correct location
-- [ ] ez-ui-checker spawned with UI-SPEC.md
-- [ ] All 6 dimensions evaluated
-- [ ] Revision loop if BLOCKED (max 2 iterations)
-- [ ] Final status displayed with next steps
-- [ ] UI-SPEC.md committed (if commit_docs enabled)
-- [ ] State updated
-</success_criteria>

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

@@ -1,157 +0,0 @@
-<purpose>
-Retroactive 6-pillar visual audit of implemented frontend code. Standalone command that works on any project — ez-managed or not. Produces scored UI-REVIEW.md with actionable findings.
-</purpose>
-
-<required_reading>
-@~/.claude/ez-agents/references/ui-brand.md
-</required_reading>
-
-<process>
-
-## 0. Initialize
-
-```bash
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init phase-op "${PHASE_ARG}")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `commit_docs`.
-
-```bash
-UI_AUDITOR_MODEL=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" resolve-model ez-ui-auditor --raw)
-```
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► UI AUDIT — PHASE {N}: {name}
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## 1. Detect Input State
-
-```bash
-SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
-UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
-UI_REVIEW_FILE=$(ls "${PHASE_DIR}"/*-UI-REVIEW.md 2>/dev/null | head -1)
-```
-
-**If `SUMMARY_FILES` empty:** Exit — "Phase {N} not executed. Run /ez:execute-phase {N} first."
-
-**If `UI_REVIEW_FILE` non-empty:** Use AskUserQuestion:
-- header: "Existing UI Review"
-- question: "UI-REVIEW.md already exists for Phase {N}."
-- options:
-  - "Re-audit — run fresh audit"
-  - "View — display current review and exit"
-
-If "View": display file, exit.
-If "Re-audit": continue.
-
-## 2. Gather Context Paths
-
-Build file list for auditor:
-- All SUMMARY.md files in phase dir
-- All PLAN.md files in phase dir
-- UI-SPEC.md (if exists — audit baseline)
-- CONTEXT.md (if exists — locked decisions)
-
-## 3. Spawn ez-ui-auditor
-
-```
-◆ Spawning UI auditor...
-```
-
-Build prompt:
-
-```markdown
-Read ~/.claude/agents/ez-ui-auditor.md for instructions.
-
-<objective>
-Conduct 6-pillar visual audit of Phase {phase_number}: {phase_name}
-{If UI-SPEC exists: "Audit against UI-SPEC.md design contract."}
-{If no UI-SPEC: "Audit against abstract 6-pillar standards."}
-</objective>
-
-<files_to_read>
-- {summary_paths} (Execution summaries)
-- {plan_paths} (Execution plans — what was intended)
-- {ui_spec_path} (UI Design Contract — audit baseline, if exists)
-- {context_path} (User decisions, if exists)
-</files_to_read>
-
-<config>
-phase_dir: {phase_dir}
-padded_phase: {padded_phase}
-</config>
-```
-
-Omit null file paths.
-
-```
-Task(
-  prompt=ui_audit_prompt,
-  subagent_type="ez-ui-auditor",
-  model="{UI_AUDITOR_MODEL}",
-  description="UI Audit Phase {N}"
-)
-```
-
-## 4. Handle Return
-
-**If `## UI REVIEW COMPLETE`:**
-
-Display score summary:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► UI AUDIT COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Phase {N}: {Name}** — Overall: {score}/24
-
-| Pillar | Score |
-|--------|-------|
-| Copywriting | {N}/4 |
-| Visuals | {N}/4 |
-| Color | {N}/4 |
-| Typography | {N}/4 |
-| Spacing | {N}/4 |
-| Experience Design | {N}/4 |
-
-Top fixes:
-1. {fix}
-2. {fix}
-3. {fix}
-
-Full review: {path to UI-REVIEW.md}
-
-───────────────────────────────────────────────────────────────
-
-## ▶ Next
-
-- `/ez:verify-work {N}` — UAT testing
-- `/ez:plan-phase {N+1}` — plan next phase
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-```
-
-## 5. Commit (if configured)
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs(${padded_phase}): UI audit review" --files "${PHASE_DIR}/${PADDED_PHASE}-UI-REVIEW.md"
-```
-
-</process>
-
-<success_criteria>
-- [ ] Phase validated
-- [ ] SUMMARY.md files found (execution completed)
-- [ ] Existing review handled (re-audit/view)
-- [ ] ez-ui-auditor spawned with correct context
-- [ ] UI-REVIEW.md created in phase directory
-- [ ] Score summary displayed to user
-- [ ] Next steps presented
-</success_criteria>

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

@@ -1,167 +0,0 @@
-<purpose>
-Audit Nyquist validation gaps for a completed phase. Generate missing tests. Update VALIDATION.md.
-</purpose>
-
-<required_reading>
-@~/.claude/ez-agents/references/ui-brand.md
-</required_reading>
-
-<process>
-
-## 0. Initialize
-
-```bash
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init phase-op "${PHASE_ARG}")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Parse: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`.
-
-```bash
-AUDITOR_MODEL=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" resolve-model ez-nyquist-auditor --raw)
-NYQUIST_CFG=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config get workflow.nyquist_validation --raw)
-```
-
-If `NYQUIST_CFG` is `false`: exit with "Nyquist validation is disabled. Enable via /ez:settings."
-
-Display banner: `EZ > VALIDATE PHASE {N}: {name}`
-
-## 1. Detect Input State
-
-```bash
-VALIDATION_FILE=$(ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null | head -1)
-SUMMARY_FILES=$(ls "${PHASE_DIR}"/*-SUMMARY.md 2>/dev/null)
-```
-
-- **State A** (`VALIDATION_FILE` non-empty): Audit existing
-- **State B** (`VALIDATION_FILE` empty, `SUMMARY_FILES` non-empty): Reconstruct from artifacts
-- **State C** (`SUMMARY_FILES` empty): Exit — "Phase {N} not executed. Run /ez:execute-phase {N} first."
-
-## 2. Discovery
-
-### 2a. Read Phase Artifacts
-
-Read all PLAN and SUMMARY files. Extract: task lists, requirement IDs, key-files changed, verify blocks.
-
-### 2b. Build Requirement-to-Task Map
-
-Per task: `{ task_id, plan_id, wave, requirement_ids, has_automated_command }`
-
-### 2c. Detect Test Infrastructure
-
-State A: Parse from existing VALIDATION.md Test Infrastructure table.
-State B: Filesystem scan:
-
-```bash
-find . -name "pytest.ini" -o -name "jest.config.*" -o -name "vitest.config.*" -o -name "pyproject.toml" 2>/dev/null | head -10
-find . \( -name "*.test.*" -o -name "*.spec.*" -o -name "test_*" \) -not -path "*/node_modules/*" 2>/dev/null | head -40
-```
-
-### 2d. Cross-Reference
-
-Match each requirement to existing tests by filename, imports, test descriptions. Record: requirement → test_file → status.
-
-## 3. Gap Analysis
-
-Classify each requirement:
-
-| Status | Criteria |
-|--------|----------|
-| COVERED | Test exists, targets behavior, runs green |
-| PARTIAL | Test exists, failing or incomplete |
-| MISSING | No test found |
-
-Build: `{ task_id, requirement, gap_type, suggested_test_path, suggested_command }`
-
-No gaps → skip to Step 6, set `nyquist_compliant: true`.
-
-## 4. Present Gap Plan
-
-Call AskUserQuestion with gap table and options:
-1. "Fix all gaps" → Step 5
-2. "Skip — mark manual-only" → add to Manual-Only, Step 6
-3. "Cancel" → exit
-
-## 5. Spawn ez-nyquist-auditor
-
-```
-Task(
-  prompt="Read ~/.claude/agents/ez-nyquist-auditor.md for instructions.\n\n" +
-    "<files_to_read>{PLAN, SUMMARY, impl files, VALIDATION.md}</files_to_read>" +
-    "<gaps>{gap list}</gaps>" +
-    "<test_infrastructure>{framework, config, commands}</test_infrastructure>" +
-    "<constraints>Never modify impl files. Max 3 debug iterations. Escalate impl bugs.</constraints>",
-  subagent_type="ez-nyquist-auditor",
-  model="{AUDITOR_MODEL}",
-  description="Fill validation gaps for Phase {N}"
-)
-```
-
-Handle return:
-- `## GAPS FILLED` → record tests + map updates, Step 6
-- `## PARTIAL` → record resolved, move escalated to manual-only, Step 6
-- `## ESCALATE` → move all to manual-only, Step 6
-
-## 6. Generate/Update VALIDATION.md
-
-**State B (create):**
-1. Read template from `~/.claude/ez-agents/templates/VALIDATION.md`
-2. Fill: frontmatter, Test Infrastructure, Per-Task Map, Manual-Only, Sign-Off
-3. Write to `${PHASE_DIR}/${PADDED_PHASE}-VALIDATION.md`
-
-**State A (update):**
-1. Update Per-Task Map statuses, add escalated to Manual-Only, update frontmatter
-2. Append audit trail:
-
-```markdown
-## Validation Audit {date}
-| Metric | Count |
-|--------|-------|
-| Gaps found | {N} |
-| Resolved | {M} |
-| Escalated | {K} |
-```
-
-## 7. Commit
-
-```bash
-git add {test_files}
-git commit -m "test(phase-${PHASE}): add Nyquist validation tests"
-
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs(phase-${PHASE}): add/update validation strategy"
-```
-
-## 8. Results + Routing
-
-**Compliant:**
-```
-EZ > PHASE {N} IS NYQUIST-COMPLIANT
-All requirements have automated verification.
-▶ Next: /ez:audit-milestone
-```
-
-**Partial:**
-```
-EZ > PHASE {N} VALIDATED (PARTIAL)
-{M} automated, {K} manual-only.
-▶ Retry: /ez:validate-phase {N}
-```
-
-Display `/clear` reminder.
-
-</process>
-
-<success_criteria>
-- [ ] Nyquist config checked (exit if disabled)
-- [ ] Input state detected (A/B/C)
-- [ ] State C exits cleanly
-- [ ] PLAN/SUMMARY files read, requirement map built
-- [ ] Test infrastructure detected
-- [ ] Gaps classified (COVERED/PARTIAL/MISSING)
-- [ ] User gate with gap table
-- [ ] Auditor spawned with complete context
-- [ ] All three return formats handled
-- [ ] VALIDATION.md created or updated
-- [ ] Test files committed separately
-- [ ] Results with routing presented
-</success_criteria>