@howlil/ez-agents 3.4.1 → 3.5.0

package/commands/ez/arch-review.md

@@ -0,0 +1,102 @@
+---
+name: ez:arch-review
+description: Run a Tech Lead architecture review on phase plans. Flags drift from established patterns, technical debt, and design conflicts.
+argument-hint: "<phase>"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<execution_context>
+@~/.claude/ez-agents/workflows/arch-review.md
+</execution_context>
+
+<process>
+Execute the arch-review workflow from @~/.claude/ez-agents/workflows/arch-review.md end-to-end.
+Parse ARGUMENTS for phase number before executing.
+</process>
+
+# /ez:arch-review
+
+Run a Tech Lead architecture review on phase plans. The Tech Lead agent checks plans against established codebase patterns, prior design decisions, and security requirements.
+
+## Usage
+
+```
+/ez:arch-review <phase>
+```
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `phase` | Yes | Phase number to review (e.g., `5`, `5.1`) |
+
+## What Gets Reviewed
+
+1. **Pattern Consistency** — Plans follow established codebase conventions
+2. **Technical Debt Risk** — Plans avoid shortcuts that cost more later
+3. **Cross-Phase Design Conflicts** — Plans don't contradict prior decisions
+4. **Security Architecture** — Auth, input validation, sensitive data handled correctly
+5. **Scalability Concerns** — No N+1 queries, unbounded operations
+6. **Dependency Analysis** — New packages are appropriate and vetted
+
+## Output
+
+```
+## Tech Lead Review: Phase 5 — Authentication
+
+Technical Risk: LOW
+Blockers: 0 | Warnings: 1 | Advisory: 2
+
+### Findings
+
+⚠️ WARNING — Security Architecture
+Plan 5-02 adds POST /api/users endpoint without auth middleware.
+Recommendation: Add requireAuth() middleware to protect this route.
+
+💡 ADVISORY — Pattern Consistency
+Plan 5-01 introduces bcrypt for password hashing. Existing codebase uses
+argon2 in Phase 3. Consider using argon2 for consistency.
+(Both are secure — this is style, not a blocker)
+
+### Overall: APPROVE_WITH_WARNINGS
+Plans are architecturally sound. Address the auth middleware warning before executing.
+```
+
+## Severity Levels
+
+| Level | Meaning | Effect |
+|-------|---------|--------|
+| BLOCKER | Irreversible change or security hole | Must fix before execution |
+| WARNING | Technical debt or missing validation | Highlight and suggest fix |
+| ADVISORY | Alternative worth considering | Informational only |
+
+## Integration with Planning
+
+Arch review fits between planning and execution:
+
+```
+/ez:plan-phase 5      → Plans created
+/ez:arch-review 5     → Tech lead reviews plans
+/ez:execute-phase 5   → Execute with awareness of any warnings
+```
+
+The `execute-phase` workflow automatically spawns a tech lead review when `workflow.agent_discussion` is enabled in config.
+
+## When to Use
+
+- After planning a phase with significant new architecture
+- When introducing new dependencies
+- When modifying auth, payments, or other sensitive systems
+- Before a major milestone
+
+## Related Commands
+
+- `/ez:standup` — Sprint health standup
+- `/ez:plan-phase` — Create phase plans
+- `/ez:execute-phase` — Execute with pre-flight checks
+- `/ez:release` — Release validation

package/commands/ez/execute-phase.md

@@ -31,6 +31,17 @@ Phase: $ARGUMENTS
 
 **Flags:**
 - `--gaps-only` — Execute only gap closure plans (plans with `gap_closure: true` in frontmatter). Use after verify-work creates fix plans.
+- `--no-auto` — Disable all smart orchestration auto-invocations (health check, discuss-phase, verify-work, add-todo). Expert mode.
+- `--verbose` — Show detail for every auto-invocation step.
+- `--skip-discussion` — Skip auto discuss-phase only (more granular than --no-auto).
+
+**Smart Orchestration (auto, unless --no-auto):**
+- Pre: health check (stops on FAIL)
+- Pre (medium/enterprise tier, no CONTEXT.md): discuss-phase --auto
+- Post: verify-work (warnings only, non-blocking)
+- Post (scope creep detected in DISCUSSION.md): add-todo
+
+All auto-invocations appear with `[auto]` prefix in output.
 
 Context files are resolved inside the workflow via `ez-tools init execute-phase` and per-subagent `<files_to_read>` blocks.
 </context>

package/commands/ez/export-session.md

@@ -0,0 +1,79 @@
+---
+name: ez:export-session
+description: Export session for model handoff
+argument-hint: "[session_id] [--format markdown|json] [--output path]"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Export a session summary for handoff to a different model or for archival.
+
+This command:
+- Accepts optional session ID (default: last session)
+- Supports markdown and JSON export formats
+- Writes output to specified path or default location
+- Shows confirmation message with export details
+- Enables seamless model transitions (Claude ↔ Qwen ↔ OpenAI ↔ Kimi)
+</objective>
+
+<execution_context>
+@~/.claude/ez-agents/workflows/export-session.md
+</execution_context>
+
+<context>
+$ARGUMENTS
+
+Parameters:
+- session_id: Optional. Session ID to export (default: last session)
+- --format: Optional. Export format: 'markdown' or 'json' (default: markdown)
+- --output: Optional. Output file path (default: .planning/sessions/export-{session_id}.{ext})
+</context>
+
+<process>
+**Follow the export-session workflow** from @~/.claude/ez-agents/workflows/export-session.md.
+
+The workflow handles all export logic including:
+
+1. **Parse parameters:**
+   - Extract session_id from args (or use "last")
+   - Extract --format flag (default: 'markdown')
+   - Extract --output flag (default: auto-generated)
+
+2. **Resolve session ID:**
+   - If session_id === 'last':
+     - Call SessionManager.getLastSession()
+     - Use session.metadata.session_id
+   - Else: use provided session_id
+
+3. **Validate format:**
+   - Must be 'markdown' or 'json'
+   - If invalid: error "Format must be 'markdown' or 'json'"
+
+4. **Generate output path if not specified:**
+   - For markdown: `.planning/sessions/export-{session_id}.md`
+   - For JSON: `.planning/sessions/export-{session_id}.json`
+
+5. **Export session:**
+   - Create SessionExport instance with SessionManager
+   - Call exportToFile(sessionId, format, outputPath)
+   - Catch SessionExportError and display user-friendly message
+
+6. **Show confirmation:**
+   ```
+   Session exported successfully!
+
+   Session: {session_id}
+   Format: {format}
+   Output: {outputPath}
+
+   You can now share this file with another model or import it later.
+   ```
+
+7. **Offer follow-up actions:**
+   - "Open file?"
+   - "Export another session?"
+   - "Return to work?"
+</process>

package/commands/ez/gather-requirements.md

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

@@ -0,0 +1,72 @@
+---
+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/hotfix.md

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

@@ -0,0 +1,82 @@
+---
+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/join-discord.md

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