@howlil/ez-agents 3.4.2 → 4.0.0

package/commands/ez/reapply-patches.md

@@ -1,124 +0,0 @@
----
-name: ez:reapply-patches
-description: Reapply local modifications after an EZ Agents update
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
----
-
-<purpose>
-After an EZ Agents update wipes and reinstalls files, this command merges user's previously saved local modifications back into the new version. Uses intelligent comparison to handle cases where the upstream file also changed.
-</purpose>
-
-<process>
-
-## Step 1: Detect backed-up patches
-
-Check for local patches directory:
-
-```bash
-# Global install — detect runtime config directory
-if [ -d "$HOME/.config/opencode/ez-local-patches" ]; then
-  PATCHES_DIR="$HOME/.config/opencode/ez-local-patches"
-elif [ -d "$HOME/.opencode/ez-local-patches" ]; then
-  PATCHES_DIR="$HOME/.opencode/ez-local-patches"
-elif [ -d "$HOME/.gemini/ez-local-patches" ]; then
-  PATCHES_DIR="$HOME/.gemini/ez-local-patches"
-else
-  PATCHES_DIR="$HOME/.claude/ez-local-patches"
-fi
-# Local install fallback — check all runtime directories
-if [ ! -d "$PATCHES_DIR" ]; then
-  for dir in .config/opencode .opencode .gemini .claude; do
-    if [ -d "./$dir/ez-local-patches" ]; then
-      PATCHES_DIR="./$dir/ez-local-patches"
-      break
-    fi
-  done
-fi
-```
-
-Read `backup-meta.json` from the patches directory.
-
-**If no patches found:**
-```
-No local patches found. Nothing to reapply.
-
-Local patches are automatically saved when you run /ez:update
-after modifying any EZ Agents workflow, command, or agent files.
-```
-Exit.
-
-## Step 2: Show patch summary
-
-```
-## Local Patches to Reapply
-
-**Backed up from:** v{from_version}
-**Current version:** {read VERSION file}
-**Files modified:** {count}
-
-| # | File | Status |
-|---|------|--------|
-| 1 | {file_path} | Pending |
-| 2 | {file_path} | Pending |
-```
-
-## Step 3: Merge each file
-
-For each file in `backup-meta.json`:
-
-1. **Read the backed-up version** (user's modified copy from `ez-local-patches/`)
-2. **Read the newly installed version** (current file after update)
-3. **Compare and merge:**
-
-   - If the new file is identical to the backed-up file: skip (modification was incorporated upstream)
-   - If the new file differs: identify the user's modifications and apply them to the new version
-
-   **Merge strategy:**
-   - Read both versions fully
-   - Identify sections the user added or modified (look for additions, not just differences from path replacement)
-   - Apply user's additions/modifications to the new version
-   - If a section the user modified was also changed upstream: flag as conflict, show both versions, ask user which to keep
-
-4. **Write merged result** to the installed location
-5. **Report status:**
-   - `Merged` — user modifications applied cleanly
-   - `Skipped` — modification already in upstream
-   - `Conflict` — user chose resolution
-
-## Step 4: Update manifest
-
-After reapplying, regenerate the file manifest so future updates correctly detect these as user modifications:
-
-```bash
-# The manifest will be regenerated on next /ez:update
-# For now, just note which files were modified
-```
-
-## Step 5: Cleanup option
-
-Ask user:
-- "Keep patch backups for reference?" → preserve `ez-local-patches/`
-- "Clean up patch backups?" → remove `ez-local-patches/` directory
-
-## Step 6: Report
-
-```
-## Patches Reapplied
-
-| # | File | Status |
-|---|------|--------|
-| 1 | {file_path} | ✓ Merged |
-| 2 | {file_path} | ○ Skipped (already upstream) |
-| 3 | {file_path} | ⚠ Conflict resolved |
-
-{count} file(s) updated. Your local modifications are active again.
-```
-
-</process>
-
-<success_criteria>
-- [ ] All backed-up patches processed
-- [ ] User modifications merged into new version
-- [ ] Conflicts resolved with user input
-- [ ] Status reported for each file
-</success_criteria>

package/commands/ez/remove-phase.md

@@ -1,31 +0,0 @@
----
-name: ez:remove-phase
-description: Remove a future phase from roadmap and renumber subsequent phases
-argument-hint: <phase-number>
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
----
-<objective>
-Remove an unstarted future phase from the roadmap and renumber all subsequent phases to maintain a clean, linear sequence.
-
-Purpose: Clean removal of work you've decided not to do, without polluting context with cancelled/deferred markers.
-Output: Phase deleted, all subsequent phases renumbered, git commit as historical record.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/remove-phase.md
-</execution_context>
-
-<context>
-Phase: $ARGUMENTS
-
-Roadmap and state are resolved in-workflow via `init phase-op` and targeted reads.
-</context>
-
-<process>
-Execute the remove-phase workflow from @~/.claude/ez-agents/workflows/remove-phase.md end-to-end.
-Preserve all validation gates (future phase check, work check), renumbering logic, and commit.
-</process>

package/commands/ez/research-phase.md

@@ -1,190 +0,0 @@
----
-name: ez:research-phase
-description: Research how to implement a phase (standalone - usually use /ez:plan-phase instead)
-argument-hint: "[phase]"
-allowed-tools:
-  - Read
-  - Bash
-  - Task
----
-
-<objective>
-Research how to implement a phase. Spawns ez-phase-researcher agent with phase context.
-
-**Note:** This is a standalone research command. For most workflows, use `/ez:plan-phase` which integrates research automatically.
-
-**Use this command when:**
-- You want to research without planning yet
-- You want to re-research after planning is complete
-- You need to investigate before deciding if a phase is feasible
-
-**Orchestrator role:** Parse phase, validate against roadmap, check existing research, gather context, spawn researcher agent, present results.
-
-**Why subagent:** Research burns context fast (WebSearch, Context7 queries, source verification). Fresh 200k context for investigation. Main context stays lean for user interaction.
-</objective>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-Normalize phase input in step 1 before any directory lookups.
-</context>
-
-<process>
-
-## 0. Initialize Context
-
-```bash
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init phase-op "$ARGUMENTS")
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Extract from init JSON: `phase_dir`, `phase_number`, `phase_name`, `phase_found`, `commit_docs`, `has_research`, `state_path`, `requirements_path`, `context_path`, `research_path`.
-
-Resolve researcher model:
-```bash
-RESEARCHER_MODEL=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" resolve-model ez-phase-researcher --raw)
-```
-
-## 1. Validate Phase
-
-```bash
-PHASE_INFO=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" roadmap get-phase "${phase_number}")
-```
-
-**If `found` is false:** Error and exit. **If `found` is true:** Extract `phase_number`, `phase_name`, `goal` from JSON.
-
-## 2. Check Existing Research
-
-```bash
-ls .planning/phases/${PHASE}-*/RESEARCH.md 2>/dev/null
-```
-
-**If exists:** Offer: 1) Update research, 2) View existing, 3) Skip. Wait for response.
-
-**If doesn't exist:** Continue.
-
-## 3. Gather Phase Context
-
-Use paths from INIT (do not inline file contents in orchestrator context):
-- `requirements_path`
-- `context_path`
-- `state_path`
-
-Present summary with phase description and what files the researcher will load.
-
-## 4. Spawn ez-phase-researcher Agent
-
-Research modes: ecosystem (default), feasibility, implementation, comparison.
-
-```markdown
-<research_type>
-Phase Research — investigating HOW to implement a specific phase well.
-</research_type>
-
-<key_insight>
-The question is NOT "which library should I use?"
-
-The question is: "What do I not know that I don't know?"
-
-For this phase, discover:
-- What's the established architecture pattern?
-- What libraries form the standard stack?
-- What problems do people commonly hit?
-- What's SOTA vs what Claude's training thinks is SOTA?
-- What should NOT be hand-rolled?
-</key_insight>
-
-<objective>
-Research implementation approach for Phase {phase_number}: {phase_name}
-Mode: ecosystem
-</objective>
-
-<files_to_read>
-- {requirements_path} (Requirements)
-- {context_path} (Phase context from discuss-phase, if exists)
-- {state_path} (Prior project decisions and blockers)
-</files_to_read>
-
-<additional_context>
-**Phase description:** {phase_description}
-</additional_context>
-
-<downstream_consumer>
-Your RESEARCH.md will be loaded by `/ez:plan-phase` which uses specific sections:
-- `## Standard Stack` → Plans use these libraries
-- `## Architecture Patterns` → Task structure follows these
-- `## Don't Hand-Roll` → Tasks NEVER build custom solutions for listed problems
-- `## Common Pitfalls` → Verification steps check for these
-- `## Code Examples` → Task actions reference these patterns
-
-Be prescriptive, not exploratory. "Use X" not "Consider X or Y."
-</downstream_consumer>
-
-<quality_gate>
-Before declaring complete, verify:
-- [ ] All domains investigated (not just some)
-- [ ] Negative claims verified with official docs
-- [ ] Multiple sources for critical claims
-- [ ] Confidence levels assigned honestly
-- [ ] Section names match what plan-phase expects
-</quality_gate>
-
-<output>
-Write to: .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md
-</output>
-```
-
-```
-Task(
-  prompt=filled_prompt,
-  subagent_type="ez-phase-researcher",
-  model="{researcher_model}",
-  description="Research Phase {phase}"
-)
-```
-
-## 5. Handle Agent Return
-
-**`## RESEARCH COMPLETE`:** Display summary, offer: Plan phase, Dig deeper, Review full, Done.
-
-**`## CHECKPOINT REACHED`:** Present to user, get response, spawn continuation.
-
-**`## RESEARCH INCONCLUSIVE`:** Show what was attempted, offer: Add context, Try different mode, Manual.
-
-## 6. Spawn Continuation Agent
-
-```markdown
-<objective>
-Continue research for Phase {phase_number}: {phase_name}
-</objective>
-
-<prior_state>
-<files_to_read>
-- .planning/phases/${PHASE}-{slug}/${PHASE}-RESEARCH.md (Existing research)
-</files_to_read>
-</prior_state>
-
-<checkpoint_response>
-**Type:** {checkpoint_type}
-**Response:** {user_response}
-</checkpoint_response>
-```
-
-```
-Task(
-  prompt=continuation_prompt,
-  subagent_type="ez-phase-researcher",
-  model="{researcher_model}",
-  description="Continue research Phase {phase}"
-)
-```
-
-</process>
-
-<success_criteria>
-- [ ] Phase validated against roadmap
-- [ ] Existing research checked
-- [ ] ez-phase-researcher spawned with context
-- [ ] Checkpoints handled correctly
-- [ ] User knows next steps
-</success_criteria>

package/commands/ez/set-profile.md

@@ -1,34 +0,0 @@
----
-name: ez:set-profile
-description: Switch model profile for EZ Agents agents (quality/balanced/budget)
-argument-hint: <profile>
-allowed-tools:
-  - Read
-  - Write
-  - Bash
----
-
-<objective>
-Switch the model profile used by EZ Agents agents. Controls which Claude model each agent uses, balancing quality vs token spend.
-
-Routes to the set-profile workflow which handles:
-- Argument validation (quality/balanced/budget)
-- Config file creation if missing
-- Profile update in config.json
-- Confirmation with model table display
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/set-profile.md
-</execution_context>
-
-<process>
-**Follow the set-profile workflow** from `@~/.claude/ez-agents/workflows/set-profile.md`.
-
-The workflow handles all logic including:
-1. Profile argument validation
-2. Config file ensuring
-3. Config reading and updating
-4. Model table generation from MODEL_PROFILES
-5. Confirmation display
-</process>

package/commands/ez/stats.md

@@ -1,18 +0,0 @@
----
-name: ez:stats
-description: Display project statistics — phases, plans, requirements, git metrics, and timeline
-allowed-tools:
-  - Read
-  - Bash
----
-<objective>
-Display comprehensive project statistics including phase progress, plan execution metrics, requirements completion, git history stats, and project timeline.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/stats.md
-</execution_context>
-
-<process>
-Execute the stats workflow from @~/.claude/ez-agents/workflows/stats.md end-to-end.
-</process>

package/commands/ez/ui-phase.md

@@ -1,34 +0,0 @@
----
-name: ez:ui-phase
-description: Generate UI design contract (UI-SPEC.md) for frontend phases
-argument-hint: "[phase]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Task
-  - WebFetch
-  - AskUserQuestion
-  - mcp__context7__*
----
-<objective>
-Create a UI design contract (UI-SPEC.md) for a frontend phase.
-Orchestrates ez-ui-researcher and ez-ui-checker.
-Flow: Validate → Research UI → Verify UI-SPEC → Done
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/ui-phase.md
-@~/.claude/ez-agents/references/ui-brand.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS — optional, auto-detects next unplanned phase if omitted.
-</context>
-
-<process>
-Execute @~/.claude/ez-agents/workflows/ui-phase.md end-to-end.
-Preserve all workflow gates.
-</process>

package/commands/ez/ui-review.md

@@ -1,32 +0,0 @@
----
-name: ez:ui-review
-description: Retroactive 6-pillar visual audit of implemented frontend code
-argument-hint: "[phase]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Glob
-  - Grep
-  - Task
-  - AskUserQuestion
----
-<objective>
-Conduct a retroactive 6-pillar visual audit. Produces UI-REVIEW.md with
-graded assessment (1-4 per pillar). Works on any project.
-Output: {phase_num}-UI-REVIEW.md
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/ui-review.md
-@~/.claude/ez-agents/references/ui-brand.md
-</execution_context>
-
-<context>
-Phase: $ARGUMENTS — optional, defaults to last completed phase.
-</context>
-
-<process>
-Execute @~/.claude/ez-agents/workflows/ui-review.md end-to-end.
-Preserve all workflow gates.
-</process>

package/commands/ez/validate-phase.md

@@ -1,35 +0,0 @@
----
-name: ez:validate-phase
-description: Retroactively audit and fill Nyquist validation gaps for a completed phase
-argument-hint: "[phase number]"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
-  - Task
-  - AskUserQuestion
----
-<objective>
-Audit Nyquist validation coverage for a completed phase. Three states:
-- (A) VALIDATION.md exists — audit and fill gaps
-- (B) No VALIDATION.md, SUMMARY.md exists — reconstruct from artifacts
-- (C) Phase not executed — exit with guidance
-
-Output: updated VALIDATION.md + generated test files.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/validate-phase.md
-</execution_context>
-
-<context>
-Phase: $ARGUMENTS — optional, defaults to last completed phase.
-</context>
-
-<process>
-Execute @~/.claude/ez-agents/workflows/validate-phase.md.
-Preserve all workflow gates.
-</process>

package/ez-agents/templates/UI-SPEC.md

@@ -1,100 +0,0 @@
----
-phase: {N}
-slug: {phase-slug}
-status: draft
-shadcn_initialized: false
-preset: none
-created: {date}
----
-
-# Phase {N} — UI Design Contract
-
-> Visual and interaction contract for frontend phases. Generated by ez-ui-researcher, verified by ez-ui-checker.
-
----
-
-## Design System
-
-| Property | Value |
-|----------|-------|
-| Tool | {shadcn / none} |
-| Preset | {preset string or "not applicable"} |
-| Component library | {radix / base-ui / none} |
-| Icon library | {library} |
-| Font | {font} |
-
----
-
-## Spacing Scale
-
-Declared values (must be multiples of 4):
-
-| Token | Value | Usage |
-|-------|-------|-------|
-| xs | 4px | Icon gaps, inline padding |
-| sm | 8px | Compact element spacing |
-| md | 16px | Default element spacing |
-| lg | 24px | Section padding |
-| xl | 32px | Layout gaps |
-| 2xl | 48px | Major section breaks |
-| 3xl | 64px | Page-level spacing |
-
-Exceptions: {list any, or "none"}
-
----
-
-## Typography
-
-| Role | Size | Weight | Line Height |
-|------|------|--------|-------------|
-| Body | {px} | {weight} | {ratio} |
-| Label | {px} | {weight} | {ratio} |
-| Heading | {px} | {weight} | {ratio} |
-| Display | {px} | {weight} | {ratio} |
-
----
-
-## Color
-
-| Role | Value | Usage |
-|------|-------|-------|
-| Dominant (60%) | {hex} | Background, surfaces |
-| Secondary (30%) | {hex} | Cards, sidebar, nav |
-| Accent (10%) | {hex} | {list specific elements only} |
-| Destructive | {hex} | Destructive actions only |
-
-Accent reserved for: {explicit list — never "all interactive elements"}
-
----
-
-## Copywriting Contract
-
-| Element | Copy |
-|---------|------|
-| Primary CTA | {specific verb + noun} |
-| Empty state heading | {copy} |
-| Empty state body | {copy + next step} |
-| Error state | {problem + solution path} |
-| Destructive confirmation | {action name}: {confirmation copy} |
-
----
-
-## Registry Safety
-
-| Registry | Blocks Used | Safety Gate |
-|----------|-------------|-------------|
-| shadcn official | {list} | not required |
-| {third-party name} | {list} | shadcn view + diff required |
-
----
-
-## Checker Sign-Off
-
-- [ ] Dimension 1 Copywriting: PASS
-- [ ] Dimension 2 Visuals: PASS
-- [ ] Dimension 3 Color: PASS
-- [ ] Dimension 4 Typography: PASS
-- [ ] Dimension 5 Spacing: PASS
-- [ ] Dimension 6 Registry Safety: PASS
-
-**Approval:** {pending / approved YYYY-MM-DD}

package/ez-agents/templates/VALIDATION.md

@@ -1,76 +0,0 @@
----
-phase: {N}
-slug: {phase-slug}
-status: draft
-nyquist_compliant: false
-wave_0_complete: false
-created: {date}
----
-
-# Phase {N} — Validation Strategy
-
-> Per-phase validation contract for feedback sampling during execution.
-
----
-
-## Test Infrastructure
-
-| Property | Value |
-|----------|-------|
-| **Framework** | {pytest 7.x / jest 29.x / vitest / go test / other} |
-| **Config file** | {path or "none — Wave 0 installs"} |
-| **Quick run command** | `{quick command}` |
-| **Full suite command** | `{full command}` |
-| **Estimated runtime** | ~{N} seconds |
-
----
-
-## Sampling Rate
-
-- **After every task commit:** Run `{quick run command}`
-- **After every plan wave:** Run `{full suite command}`
-- **Before `/ez:verify-work`:** Full suite must be green
-- **Max feedback latency:** {N} seconds
-
----
-
-## Per-Task Verification Map
-
-| Task ID | Plan | Wave | Requirement | Test Type | Automated Command | File Exists | Status |
-|---------|------|------|-------------|-----------|-------------------|-------------|--------|
-| {N}-01-01 | 01 | 1 | REQ-{XX} | unit | `{command}` | ✅ / ❌ W0 | ⬜ pending |
-
-*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
-
----
-
-## Wave 0 Requirements
-
-- [ ] `{tests/test_file.py}` — stubs for REQ-{XX}
-- [ ] `{tests/conftest.py}` — shared fixtures
-- [ ] `{framework install}` — if no framework detected
-
-*If none: "Existing infrastructure covers all phase requirements."*
-
----
-
-## Manual-Only Verifications
-
-| Behavior | Requirement | Why Manual | Test Instructions |
-|----------|-------------|------------|-------------------|
-| {behavior} | REQ-{XX} | {reason} | {steps} |
-
-*If none: "All phase behaviors have automated verification."*
-
----
-
-## Validation Sign-Off
-
-- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
-- [ ] Sampling continuity: no 3 consecutive tasks without automated verify
-- [ ] Wave 0 covers all MISSING references
-- [ ] No watch-mode flags
-- [ ] Feedback latency < {N}s
-- [ ] `nyquist_compliant: true` set in frontmatter
-
-**Approval:** {pending / approved YYYY-MM-DD}