@howlil/ez-agents 3.5.0 → 4.0.0

package/commands/ez/gather-requirements.md

@@ -1,117 +0,0 @@
----
-name: gather-requirements
-description: Gather BDD/Gherkin requirements for a phase via user interview. Produces .feature files with MoSCoW tagging and INVEST validation.
-usage: /ez:gather-requirements [phase] [--auto]
----
-
-# /ez:gather-requirements
-
-Gather machine-verifiable BDD requirements for a phase. Spawns the `ez-requirements-agent` to interview you and produce Gherkin `.feature` files with MoSCoW priorities.
-
-## Usage
-
-```
-/ez:gather-requirements [phase] [--auto]
-```
-
-## Arguments
-
-| Argument | Description |
-|----------|-------------|
-| `phase` | Phase number (e.g., `5`, `5.1`). Defaults to next unplanned phase. |
-| `--auto` | Skip interview — derive requirements from ROADMAP.md and CONTEXT.md automatically. |
-
-## What It Does
-
-1. **Reads** existing REQUIREMENTS.md and phase CONTEXT.md to understand scope
-2. **Interviews** you about user stories, acceptance criteria, and edge cases (unless `--auto`)
-3. **Writes** `.feature` files to `specs/features/{domain}/` in your project
-4. **Validates** INVEST criteria for each user story
-5. **Tags** every scenario with MoSCoW (`@must/@should/@could/@wont`) and tier (`@mvp/@medium/@enterprise`)
-6. **Creates** `.planning/phases/XX-name/XX-ACCEPTANCE-CRITERIA.md` — phase gate document
-7. **Updates** `.planning/REQUIREMENTS-BDD.md` — traceability matrix
-
-## Output Structure
-
-```
-specs/
-  features/
-    {domain}/
-      {feature}.feature     ← Gherkin scenarios with MoSCoW tags
-.planning/
-  phases/
-    XX-name/
-      XX-ACCEPTANCE-CRITERIA.md  ← Phase gate: @must scenarios
-  REQUIREMENTS-BDD.md            ← Traceability matrix
-```
-
-## Workflow
-
-```
-/ez:gather-requirements 5
-  → ez-requirements-agent interviews you
-  → Creates specs/features/...
-  → Creates ACCEPTANCE-CRITERIA.md
-  → Updates REQUIREMENTS-BDD.md
-
-/ez:plan-phase 5
-  → Planner reads .feature files
-  → Plans address @must scenarios
-  → BDD cross-check in plan
-```
-
-## Flags
-
-### --auto
-
-Skip the interactive interview. Requirements agent derives scenarios from:
-- ROADMAP.md phase description and goal
-- Phase CONTEXT.md (if from `/ez:discuss-phase`)
-- Existing REQUIREMENTS.md
-
-Use when you have detailed context already captured and want fast requirements generation.
-
-```
-/ez:gather-requirements 5 --auto
-```
-
-## Examples
-
-```bash
-# Interactive — gather requirements for phase 5
-/ez:gather-requirements 5
-
-# Auto-derive from existing context
-/ez:gather-requirements 5 --auto
-
-# Gather for decimal gap-closure phase
-/ez:gather-requirements 5.1
-```
-
-## Integration with Planning
-
-Requirements gathered here feed directly into:
-
-- **`/ez:plan-phase`** — Planner cross-checks plans against `.feature` files, ensures @must scenarios are addressed
-- **`/ez:verify-work`** — Verifier checks BDD pass rate in VERIFICATION.md
-- **`/ez:release`** — Release gate checks @must scenario coverage before promoting tier
-
-## INVEST Quick Guide
-
-Every user story (Feature + scenarios) must be:
-
-| Letter | Criterion | Check |
-|--------|-----------|-------|
-| I | Independent | Can develop without other features |
-| N | Negotiable | Implementation details not locked in Then clauses |
-| V | Valuable | Feature statement explains user benefit |
-| E | Estimable | Steps are detailed enough to estimate |
-| S | Small | ≤8 @must scenarios fit in one phase |
-| T | Testable | All Then clauses are automatable |
-
-## Related Commands
-
-- `/ez:discuss-phase` — Capture design decisions (run before gather-requirements)
-- `/ez:plan-phase` — Create implementation plans (run after gather-requirements)
-- `/ez:verify-work` — Verify BDD scenarios pass after implementation
-- `/ez:release` — Release with BDD coverage gate

package/commands/ez/git-workflow.md

@@ -1,72 +0,0 @@
----
-name: ez:git-workflow
-description: Git workflow management for phase-based development
-argument-hint: "<operation> [options] — operations: create-phase, create-branch, merge, release, hotfix, rollback, validate, changelog"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - Grep
-  - Glob
----
-<objective>
-Manage Git workflow operations for phase-based development with enterprise-grade branch management, validation, and merging.
-
-**Operations:**
-- `create-phase <N> <slug>` — Create phase branch (e.g., `phase/15-git-workflow`)
-- `create-branch <type> <slug>` — Create feature/fix/docs/refactor branch
-- `merge <source> <target>` — Merge branches with validation
-- `release <version>` — Create and manage release branch
-- `hotfix <description>` — Create hotfix branch from main
-- `rollback <phase-number>` — Rollback a phase
-- `validate <branch>` — Validate branch before merge
-- `changelog <from-tag> [to-tag]` — Generate changelog from commits
-</objective>
-
-<execution_context>
-@ez-agents/bin/lib/git-workflow-engine.cjs
-@ez-agents/bin/lib/git-utils.cjs
-@ez-agents/bin/lib/git-errors.cjs
-@.planning/config.json
-</execution_context>
-
-<context>
-**Branch Hierarchy:**
-```
-main (production) ← develop (staging) ← phase/* ← {feature,fix,docs,refactor}/*
-```
-
-**Configuration:**
-- Merge strategies from `.planning/config.json`
-- Enterprise mode settings (PR requirements, reviewers)
-- Validation levels (minimal, standard, full)
-
-**Environment:**
-- GITHUB_TOKEN required for enterprise PR workflow
-- GITHUB_TOKEN required for branch protection checks
-</context>
-
-<process>
-1. Parse operation and arguments
-2. Initialize GitWorkflowEngine with config
-3. Execute requested operation:
-   - **create-phase**: Call `engine.createPhaseBranch(phaseNumber, phaseSlug)`
-   - **create-branch**: Call `engine.createWorkBranch(type, ticketId, slug)`
-   - **merge**: Call `engine.mergeBranch(source, target, options)`
-   - **release**: Call `engine.createReleaseBranch(version)` then `engine.mergeReleaseToMain(releaseBranch)`
-   - **hotfix**: Call `engine.createHotfix(description)` then `engine.mergeHotfix(hotfixBranch, version)`
-   - **rollback**: Call `engine.rollbackPhase(phaseNumber)`
-   - **validate**: Call `engine.validateBeforeMerge(branch, validationLevel)`
-   - **changelog**: Call `engine.generateChangelog(fromTag, toTag)`
-4. Handle errors with appropriate error classes
-5. Log operation result
-6. Return success/failure status
-</process>
-
-<error_handling>
-- `BranchExistsError`: Branch already exists, suggest different name or delete first
-- `BranchNotFoundError`: Source/target branch doesn't exist
-- `MergeConflictError`: Conflicts detected, provide conflict resolution guidance
-- `ValidationFailedError`: Validation checks failed, list specific failures
-- `GitWorkflowError`: General git workflow error
-</error_handling>

package/commands/ez/health.md

@@ -1,22 +0,0 @@
----
-name: ez:health
-description: Diagnose planning directory health and optionally repair issues
-argument-hint: [--repair]
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - AskUserQuestion
----
-<objective>
-Validate `.planning/` directory integrity and report actionable issues. Checks for missing files, invalid configurations, inconsistent state, and orphaned plans.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/health.md
-</execution_context>
-
-<process>
-Execute the health workflow from @~/.claude/ez-agents/workflows/health.md end-to-end.
-Parse --repair flag from arguments and pass to workflow.
-</process>

package/commands/ez/hotfix.md

@@ -1,120 +0,0 @@
----
-name: ez:hotfix
-description: Create and complete a hotfix branch. Branches from production tag, fixes, then merges to main (and develop for enterprise).
-argument-hint: "start <name> | complete <name> <version>"
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - Glob
-  - Grep
----
-
-<execution_context>
-@~/.claude/ez-agents/workflows/hotfix.md
-</execution_context>
-
-<process>
-Execute the hotfix workflow from @~/.claude/ez-agents/workflows/hotfix.md end-to-end.
-Parse ARGUMENTS for subcommand (start|complete), name, and version before executing.
-</process>
-
-# /ez:hotfix
-
-Create and complete a hotfix for a critical production bug. Hotfix branches from the production tag (or main), applies the fix, then merges atomically to both main and develop (if using GitFlow).
-
-## Usage
-
-```
-/ez:hotfix start <name>
-/ez:hotfix complete <name> <version>
-```
-
-## Commands
-
-### start
-
-Create a hotfix branch from main:
-
-```bash
-/ez:hotfix start critical-bug
-# Creates: hotfix/critical-bug from main
-# Prints: current version + how to complete
-```
-
-### complete
-
-Finish and release the hotfix:
-
-```bash
-/ez:hotfix complete critical-bug 1.0.1
-# 1. Runs security gates
-# 2. Runs tests
-# 3. Merges hotfix/critical-bug → main
-# 4. Tags: v1.0.1
-# 5. If GitFlow: syncs to develop
-# 6. Creates rollback plan
-# 7. Updates CHANGELOG.md
-```
-
-## Why Hotfix?
-
-A hotfix keeps the main branch clean while you're fixing bugs:
-
-```
-Without hotfix:                  With hotfix:
-main:  A──B──C──D──[broken]      main:  A──B──C──D──fix──tag
-              ↑                              ↑
-         You committed                  hotfix/bug branches
-         incomplete work                here, merges when done
-         to main
-```
-
-No incomplete work on main. No risk of accidentally shipping in-progress features.
-
-## Tier Behavior
-
-The hotfix workflow adapts to your release tier:
-
-| Tier | Hotfix From | Hotfix To | Sync To |
-|------|-------------|-----------|---------|
-| MVP | main | main | — |
-| Medium | main | main (PR) | — |
-| Enterprise | main | main | develop |
-
-In enterprise mode, after merging to main the hotfix is also merged to develop so no work is lost.
-
-## Example Session
-
-```bash
-# Production bug reported: login broken for @gmail.com users
-/ez:hotfix start gmail-login-fix
-
-# Now on hotfix/gmail-login-fix branch
-# ... make the fix ...
-# git add src/auth/login.ts
-# git commit -m "fix(auth): handle + character in email addresses"
-
-# Release the fix
-/ez:hotfix complete gmail-login-fix 1.0.1
-# Tests run, security gates pass
-# Merged to main, tagged v1.0.1
-# Changelog updated
-# Rollback plan created
-#
-# Ready to push:
-#   git push origin main && git push origin v1.0.1
-```
-
-## Rollback Plan
-
-Every hotfix creates a rollback plan in case the fix itself breaks something:
-```
-.planning/releases/v1.0.1-ROLLBACK-PLAN.md
-```
-
-## Related Commands
-
-- `/ez:release` — Full release workflow
-- `/ez:verify-work` — Verify fix before completing

package/commands/ez/import-session.md

@@ -1,82 +0,0 @@
----
-name: ez:import-session
-description: Import session from file
-argument-hint: "<file.json> [--source-model model]"
-allowed-tools:
-  - Read
-  - Write
-  - Bash
-  - AskUserQuestion
----
-
-<objective>
-Import a session from an exported file to continue work or switch models.
-
-This command:
-- Accepts a session file path (JSON format)
-- Validates file exists and is valid JSON
-- Validates session structure and chain integrity
-- Calls SessionImport.import() with optional source model adapter
-- Shows session summary after import
-- Offers to resume imported session
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/import-session.md
-</execution_context>
-
-<context>
-$ARGUMENTS
-
-Parameters:
-- file_path: Required. Path to session export file (.json)
-- --source-model: Optional. Source model for adapter (claude, qwen, openai, kimi)
-</context>
-
-<process>
-**Follow the import-session workflow** from @~/.claude/ez-agents/workflows/import-session.md.
-
-The workflow handles all import logic including:
-
-1. **Validate file path:**
-   - Check file exists using fs.existsSync
-   - If not: error "File not found: {path}"
-   - Check file ends with .json
-   - If not: error "Import file must be .json format"
-
-2. **Parse parameters:**
-   - Extract file_path from args
-   - Extract --source-model flag (optional)
-
-3. **Import session:**
-   - Create SessionImport instance with SessionManager
-   - Call import(file_path, { sourceModel })
-   - Catch SessionImportError and display:
-     - Error type
-     - Validation errors
-     - Suggested fix
-
-4. **Show import confirmation:**
-   ```
-   Session imported successfully!
-
-   Session ID: {sessionId}
-   Source: {file_path}
-   Original model: {model}
-   Original phase: {phase}
-
-   Warnings: {warnings if any}
-   ```
-
-5. **Show session summary:**
-   - Display key info from imported session:
-     - Tasks completed
-     - Tasks incomplete
-     - Key decisions
-     - File changes
-
-6. **Offer follow-up actions:**
-   - "Resume this session?"
-   - "View session chain?"
-   - "Return to current session?"
-</process>

package/commands/ez/insert-phase.md

@@ -1,32 +0,0 @@
----
-name: ez:insert-phase
-description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
-argument-hint: <after> <description>
-allowed-tools:
-  - Read
-  - Write
-  - Bash
----
-
-<objective>
-Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
-
-Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
-
-Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/insert-phase.md
-</execution_context>
-
-<context>
-Arguments: $ARGUMENTS (format: <after-phase-number> <description>)
-
-Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
-</context>
-
-<process>
-Execute the insert-phase workflow from @~/.claude/ez-agents/workflows/insert-phase.md end-to-end.
-Preserve all validation gates (argument parsing, phase verification, decimal calculation, roadmap updates).
-</process>

package/commands/ez/join-discord.md

@@ -1,18 +0,0 @@
----
-name: ez:join-discord
-description: Join the EZ Agents Discord community
----
-
-<objective>
-Display the Discord invite link for the EZ Agents community server.
-</objective>
-
-<output>
-# Join the EZ Agents Discord
-
-Connect with other EZ Agents users, get help, share what you're building, and stay updated.
-
-**Invite link:** https://discord.gg/ez-agents
-
-Click the link or paste it into your browser to join.
-</output>

package/commands/ez/list-phase-assumptions.md

@@ -1,46 +0,0 @@
----
-name: ez:list-phase-assumptions
-description: Surface Claude's assumptions about a phase approach before planning
-argument-hint: "[phase]"
-allowed-tools:
-  - Read
-  - Bash
-  - Grep
-  - Glob
----
-
-<objective>
-Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
-
-Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
-Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
-</objective>
-
-<execution_context>
-@~/.claude/ez-agents/workflows/list-phase-assumptions.md
-</execution_context>
-
-<context>
-Phase number: $ARGUMENTS (required)
-
-Project state and roadmap are loaded in-workflow using targeted reads.
-</context>
-
-<process>
-1. Validate phase number argument (error if missing or invalid)
-2. Check if phase exists in roadmap
-3. Follow list-phase-assumptions.md workflow:
-   - Analyze roadmap description
-   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
-   - Present assumptions clearly
-   - Prompt "What do you think?"
-4. Gather feedback and offer next steps
-</process>
-
-<success_criteria>
-
-- Phase validated against roadmap
-- Assumptions surfaced across five areas
-- User prompted for feedback
-- User knows next steps (discuss context, plan phase, or correct assumptions)
-  </success_criteria>

package/commands/ez/list-sessions.md

@@ -1,96 +0,0 @@
----
-name: ez:list-sessions
-description: List all sessions
-argument-hint: "[--limit N] [--json]"
-allowed-tools:
-  - Read
-  - Bash
----
-
-<objective>
-List all sessions with metadata and disk usage summary.
-
-This command:
-- Lists sessions with: session_id, started_at, ended_at, model, phase, plan, status
-- Sorts by date (newest first)
-- Shows disk usage summary
-- Supports --limit N parameter to restrict output
-- Supports --json flag for machine-readable output
-</objective>
-
-<execution_context>
-None - Direct command implementation
-</execution_context>
-
-<context>
-$ARGUMENTS
-
-Parameters:
-- --limit: Optional. Maximum sessions to display (default: 20)
-- --json: Optional. Output as JSON instead of table
-</context>
-
-<process>
-Execute the following workflow:
-
-1. **Parse parameters:**
-   - Extract --limit flag (default: 20)
-   - Extract --json flag (default: false)
-
-2. **List sessions:**
-   - Create SessionManager instance
-   - Call listSessions()
-   - Slice to limit
-
-3. **Calculate disk usage:**
-   - Read all session files from .planning/sessions/
-   - Sum file sizes
-   - Format as KB/MB
-
-4. **Display table (non-JSON mode):**
-   ```
-   Sessions (showing {N} of {total}):
-
-   | Session ID | Started | Ended | Model | Phase | Plan | Status |
-   |------------|---------|-------|-------|-------|------|--------|
-   {rows}
-
-   Disk usage: {size} ({file_count} sessions)
-   ```
-
-   Example output:
-   ```
-   Sessions (showing 5 of 12):
-
-   | Session ID              | Started           | Ended             | Model  | Phase | Plan | Status    |
-   |-------------------------|-------------------|-------------------|--------|-------|------|-----------|
-   | session-20260319-143052 | 2026-03-19T14:30  | 2026-03-19T15:45  | qwen   | 18    | 18   | completed |
-   | session-20260319-120000 | 2026-03-19T12:00  | 2026-03-19T13:15  | claude | 17    | 16   | completed |
-   | session-20260319-090000 | 2026-03-19T09:00  | 2026-03-19T10:30  | qwen   | 17    | 15   | completed |
-
-   Disk usage: 2.4 MB (12 sessions)
-   ```
-
-5. **JSON mode:**
-   - Output: { sessions: [...], disk_usage: bytes, total: count }
-   ```json
-   {
-     "sessions": [
-       {
-         "session_id": "session-20260319-143052",
-         "started_at": "2026-03-19T14:30:52.000Z",
-         "ended_at": "2026-03-19T15:45:00.000Z",
-         "model": "qwen",
-         "phase": 18,
-         "plan": 18,
-         "status": "completed"
-       }
-     ],
-     "disk_usage": 2516582,
-     "total": 12
-   }
-   ```
-
-6. **Handle empty state:**
-   - If no sessions: output "No sessions found. Start working to create your first session."
-</process>