@howlil/ez-agents 3.4.2 → 3.5.0

package/commands/ez/package-manager.md

@@ -0,0 +1,316 @@
+# Package Manager Command
+
+## Overview
+
+The `package-manager` command provides flexible package manager support for ez-agents, enabling seamless operation with **npm**, **yarn**, and **pnpm**. It automatically detects available package managers, respects existing lockfiles, and provides configuration-driven defaults for consistent team workflows.
+
+### Features
+
+- **Auto-Detection**: Intelligently detects available package managers (pnpm, yarn, npm) on the system
+- **Lockfile Respect**: Honors existing lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml)
+- **Configuration Control**: Configurable default package manager in `.planning/config.json`
+- **Cross-Platform Execution**: Consistent shell syntax across Windows, macOS, and Linux
+- **Full Command Support**: install, add, remove operations for all three package managers
+- **Backward Compatibility**: Maintains existing npm compatibility for legacy projects
+
+## Usage
+
+```bash
+ez package-manager <subcommand> [options]
+```
+
+### Subcommands
+
+#### `detect` - Detect available package manager
+
+Automatically detects the available package manager using a priority-based strategy.
+
+```bash
+ez package-manager detect
+```
+
+**Output format (JSON):**
+```json
+{
+  "manager": "pnpm",
+  "source": "lockfile",
+  "confidence": "high",
+  "lockfilePath": "/path/to/pnpm-lock.yaml"
+}
+```
+
+**Detection Sources:**
+- `config` - From `.planning/config.json` packageManager.default
+- `lockfile` - From existing lockfile presence
+- `system` - From system availability check
+- `fallback` - Default to npm when nothing else is available
+
+**Confidence Levels:**
+- `high` - Config or lockfile detection
+- `medium` - System availability detection
+- `low` - Fallback to npm
+
+---
+
+#### `install` - Install dependencies
+
+Install dependencies from lockfile.
+
+```bash
+ez package-manager install [--frozen] [--production]
+```
+
+**Options:**
+- `--frozen` - Use frozen lockfile install (CI/CD safe)
+- `--production` - Production install (exclude devDependencies)
+
+**Examples:**
+```bash
+# Standard install
+ez package-manager install
+
+# Frozen lockfile install (CI/CD)
+ez package-manager install --frozen
+
+# Production install
+ez package-manager install --production
+```
+
+**Package Manager Commands:**
+- npm: `npm install [--frozen-lockfile] [--production]`
+- yarn: `yarn install [--frozen-lockfile] [--production]`
+- pnpm: `pnpm install [--frozen-lockfile] [--prod]`
+
+---
+
+#### `add` - Add package(s)
+
+Add new package(s) to the project.
+
+```bash
+ez package-manager add <package> [--dev|-D]
+```
+
+**Options:**
+- `--dev` or `-D` - Add as devDependency
+
+**Examples:**
+```bash
+# Add production dependency
+ez package-manager add lodash
+
+# Add dev dependency
+ez package-manager add eslint --dev
+ez package-manager add prettier -D
+
+# Add multiple packages
+ez package-manager add react react-dom
+```
+
+**Package Manager Commands:**
+- npm: `npm install [--save-dev] <package>`
+- yarn: `yarn add [--dev] <package>`
+- pnpm: `pnpm add [--save-dev] <package>`
+
+---
+
+#### `remove` - Remove package(s)
+
+Remove package(s) from the project.
+
+```bash
+ez package-manager remove <package>
+```
+
+**Examples:**
+```bash
+# Remove single package
+ez package-manager remove lodash
+
+# Remove multiple packages
+ez package-manager remove eslint prettier
+```
+
+**Package Manager Commands:**
+- npm: `npm uninstall <package>`
+- yarn: `yarn remove <package>`
+- pnpm: `pnpm remove <package>`
+
+---
+
+#### `info` - Show package manager info
+
+Display current package manager information.
+
+```bash
+ez package-manager info
+```
+
+**Output format (JSON):**
+```json
+{
+  "manager": "pnpm",
+  "source": "lockfile",
+  "cwd": "/path/to/project",
+  "lockfile": "/path/to/pnpm-lock.yaml"
+}
+```
+
+---
+
+## Configuration
+
+Configure package manager behavior in `.planning/config.json`:
+
+```json
+{
+  "packageManager": {
+    "default": "npm",
+    "autoDetect": true,
+    "respectLockfile": true,
+    "frozenLockfileInCI": true
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `default` | string | `"npm"` | Default package manager (`npm`, `yarn`, or `pnpm`) |
+| `autoDetect` | boolean | `true` | Enable automatic package manager detection |
+| `respectLockfile` | boolean | `true` | Respect existing lockfiles when detecting |
+| `frozenLockfileInCI` | boolean | `true` | Use frozen lockfile installs in CI environments |
+
+---
+
+## Detection Priority
+
+The package manager detection follows a priority-based strategy:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              Package Manager Detection Pipeline              │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 1: Configuration (highest priority)                  │
+│  - Check .planning/config.json → packageManager.default    │
+│  - If found and installed, use configured manager           │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 2: Lockfile Detection                                │
+│  - Check for pnpm-lock.yaml → use pnpm                     │
+│  - Check for yarn.lock → use yarn                          │
+│  - Check for package-lock.json → use npm                   │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 3: System Availability                               │
+│  - Check which managers are installed                       │
+│  - Prefer pnpm > yarn > npm (performance order)            │
+├─────────────────────────────────────────────────────────────┤
+│  Layer 4: Fallback                                          │
+│  - Default to npm (always available with Node)             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Detection Examples
+
+| Scenario | Detected Manager | Source |
+|----------|-----------------|--------|
+| Config says `pnpm`, pnpm installed | `pnpm` | config |
+| No config, `pnpm-lock.yaml` exists | `pnpm` | lockfile |
+| No config, `yarn.lock` exists | `yarn` | lockfile |
+| No config, `package-lock.json` exists | `npm` | lockfile |
+| No lockfile, pnpm/yarn/npm installed | `pnpm` | system |
+| No lockfile, only npm installed | `npm` | system |
+| Nothing detected | `npm` | fallback |
+
+---
+
+## Cross-Platform Support
+
+The package manager command works identically across all platforms:
+
+- **Windows** - Uses `execFile` for cross-platform execution
+- **macOS** - Native Unix shell compatibility
+- **Linux** - Native Unix shell compatibility
+
+### Implementation Details
+
+- All commands use `execFile` (not `exec`) for security and cross-platform compatibility
+- All paths use `path.join()` for proper path separator handling
+- No shell injection vulnerabilities (shell: false)
+- 5-minute timeout for all operations
+- 10MB buffer for command output
+
+---
+
+## Package Manager Commands Reference
+
+### npm
+
+| Operation | Command |
+|-----------|---------|
+| Install | `npm install` |
+| Frozen Install | `npm install --frozen-lockfile` |
+| Add Package | `npm install <pkg>` |
+| Add Dev Package | `npm install --save-dev <pkg>` |
+| Remove Package | `npm uninstall <pkg>` |
+| Lockfile | `package-lock.json` |
+
+### yarn
+
+| Operation | Command |
+|-----------|---------|
+| Install | `yarn install` |
+| Frozen Install | `yarn install --frozen-lockfile` |
+| Add Package | `yarn add <pkg>` |
+| Add Dev Package | `yarn add --dev <pkg>` |
+| Remove Package | `yarn remove <pkg>` |
+| Lockfile | `yarn.lock` |
+
+### pnpm
+
+| Operation | Command |
+|-----------|---------|
+| Install | `pnpm install` |
+| Frozen Install | `pnpm install --frozen-lockfile` |
+| Add Package | `pnpm add <pkg>` |
+| Add Dev Package | `pnpm add --save-dev <pkg>` |
+| Remove Package | `pnpm remove <pkg>` |
+| Lockfile | `pnpm-lock.yaml` |
+
+---
+
+## Error Handling
+
+The command provides detailed error messages for common issues:
+
+- **No package manager detected** - Falls back to npm with warning
+- **Lockfile validation failed** - Logs warning but continues
+- **Command execution failed** - Returns stderr output with context
+- **Unknown subcommand** - Lists available subcommands
+
+---
+
+## Library API
+
+The package manager modules are also available for programmatic use:
+
+```javascript
+const {
+  PackageManagerService,
+  PackageManagerDetector,
+  PackageManagerExecutor,
+  LockfileValidator
+} = require('./ez-agents/bin/lib/index.cjs');
+
+// Use the service
+const service = new PackageManagerService(cwd);
+await service.initialize();
+await service.install({ frozenLockfile: true });
+await service.add(['lodash'], { dev: true });
+```
+
+See individual module files for detailed API documentation:
+- `ez-agents/bin/lib/package-manager-detector.cjs`
+- `ez-agents/bin/lib/package-manager-executor.cjs`
+- `ez-agents/bin/lib/lockfile-validator.cjs`
+- `ez-agents/bin/lib/package-manager-service.cjs`

package/commands/ez/plan-phase.md

@@ -1,7 +1,7 @@
 ---
 name: ez:plan-phase
 description: Create detailed phase plan (PLAN.md) with verification loop
-argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>]"
+argument-hint: "[phase] [--auto] [--research] [--skip-research] [--gaps] [--skip-verify] [--prd <file>] [--no-auto] [--verbose]"
 agent: ez-planner
 allowed-tools:
   - Read
@@ -35,6 +35,14 @@ Phase number: $ARGUMENTS (optional — auto-detects next unplanned phase if omit
 - `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
 - `--skip-verify` — Skip verification loop
 - `--prd <file>` — Use a PRD/acceptance criteria file instead of discuss-phase. Parses requirements into CONTEXT.md automatically. Skips discuss-phase entirely.
+- `--no-auto` — Disable smart orchestration (skip auto discuss-phase for sensitive areas).
+- `--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):**
+- Detects sensitive area keywords in phase name/goal: `auth`, `login`, `jwt`, `oauth`, `database`, `migration`, `schema`, `payment`, `billing`, `security`
+- If detected AND no CONTEXT.md exists: auto-runs `discuss-phase --auto` before planning
+- All auto-invocations appear with `[auto]` prefix in output
 
 Normalize phase input in step 2 before any directory lookups.
 </context>

package/commands/ez/preflight.md

@@ -0,0 +1,79 @@
+---
+name: preflight
+description: Run release checklist validation without creating a release. Shows pass/fail for all tier checklist items.
+usage: /ez:release preflight <tier>
+---
+
+# /ez:release preflight
+
+Run the release checklist for a tier without creating a branch, tag, or changelog. Use this to see what's blocking or passing before you commit to a release.
+
+## Usage
+
+```
+/ez:release preflight <tier>
+```
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `tier` | Yes | `mvp`, `medium`, or `enterprise` |
+
+## What It Checks
+
+Runs security gates + tier checklist without side effects:
+
+```
+/ez:release preflight medium
+
+Security Gates (4/4):
+  ✓ No secrets in committed files
+  ✓ npm audit — no critical vulnerabilities
+  ✓ No production TODOs
+  ✓ .env files in .gitignore
+
+Medium Checklist (12/18):
+  ✓ All @must BDD scenarios passing
+  ✗ Test coverage ≥ 80% — Coverage: 71% (need 9% more)
+  ✓ npm audit — clean
+  ✓ No secrets in committed files
+  ✓ Application starts
+  ✓ Rollback documented
+  ✓ All @should BDD scenarios passing
+  ✗ Test coverage ≥ 80% — 71% (need +9%)
+  ? Staging environment parity — requires manual verification
+  ? Monitoring/alerts configured — requires manual verification
+  ✓ No console.log in prod
+  ? Performance baseline — requires manual verification
+  ...
+
+Production Readiness Score: 74/100 — CONDITIONAL
+
+Blockers: 0
+Warnings: 2 (coverage below threshold)
+Manual items: 6 (need human verification)
+
+To release: /ez:release medium v1.5.0
+```
+
+## When to Use
+
+- Before starting a release to know what you need to fix
+- When onboarding to a new tier to understand the gap
+- During development to track progress toward release readiness
+
+## Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| ✓ | Automated check passed |
+| ✗ | Automated check failed |
+| ? | Requires manual human verification |
+| ○ | Skipped (not applicable) |
+
+## Related Commands
+
+- `/ez:release mvp v1.0.0` — Execute the actual release
+- `/ez:hotfix` — Emergency fix on released version
+- `/ez:standup` — Sprint health check

package/commands/ez/progress.md

@@ -1,12 +1,12 @@
 ---
 name: ez:progress
 description: Check project progress, show context, and route to next action (execute or plan)
+argument-hint: "[--no-auto]"
 allowed-tools:
   - Read
   - Bash
   - Grep
   - Glob
-  - SlashCommand
 ---
 <objective>
 Check project progress, summarize recent work and what's ahead, then intelligently route to the next action - either executing an existing plan or creating the next one.
@@ -18,6 +18,18 @@ Provides situational awareness before continuing work.
 @~/.claude/ez-agents/workflows/progress.md
 </execution_context>
 
+<context>
+Arguments: $ARGUMENTS
+
+**Flags:**
+- `--no-auto` — Disable silent health check auto-invocation.
+
+**Smart Orchestration (auto, unless --no-auto):**
+- Pre: health check (warns in report on FAIL, does not stop progress)
+
+Health check result is silent on pass. Only shown in output if health fails.
+</context>
+
 <process>
 Execute the progress workflow from @~/.claude/ez-agents/workflows/progress.md end-to-end.
 Preserve all routing logic (Routes A through F) and edge case handling.

package/commands/ez/release.md

@@ -0,0 +1,153 @@
+---
+name: ez:release
+description: Create a tier-aware release with branch automation, changelog generation, security gates, and rollback plan.
+usage: /ez:release <tier> <version>
+argument-hint: "<tier> <version> | preflight <tier>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<execution_context>
+@~/.claude/ez-agents/workflows/release.md
+</execution_context>
+
+<process>
+Execute the release workflow from @~/.claude/ez-agents/workflows/release.md end-to-end.
+Parse ARGUMENTS for tier, version, and flags before executing.
+</process>
+
+# /ez:release
+
+Create a production release. Automates branch strategy, security gates, tier checklist, changelog generation, and rollback plan based on the target tier (mvp/medium/enterprise).
+
+## Usage
+
+```
+/ez:release <tier> <version>
+/ez:release preflight <tier>
+```
+
+## Arguments
+
+| Argument | Required | Description |
+|----------|----------|-------------|
+| `tier` | Yes | `mvp`, `medium`, or `enterprise` |
+| `version` | Yes | Semver version (e.g., `1.0.0`, `2.1.0`) |
+
+## Release Tiers
+
+### MVP (`/ez:release mvp v1.0.0`)
+For: "Ship working software fast"
+- Scope: @must scenarios only
+- Coverage: 60% minimum
+- Git: Trunk-based (tag directly on main)
+- Checklist: 6 items
+- Typical use: First public release, early access
+
+### Medium (`/ez:release medium v1.1.0`)
+For: "Production-ready for real users"
+- Scope: @must + @should scenarios
+- Coverage: 80% minimum
+- Git: GitHub Flow (release branch → PR → main)
+- Checklist: 18 items
+- Typical use: General availability, paying customers
+
+### Enterprise (`/ez:release enterprise v2.0.0`)
+For: "Compliance-grade production"
+- Scope: All MoSCoW priorities
+- Coverage: 95% minimum
+- Git: GitFlow (release/vX.Y.Z → develop → main)
+- Checklist: 30 items
+- Typical use: Enterprise customers, regulated industries
+
+## Auto-Invocation (Smart Orchestration)
+
+Based on tier, this command automatically runs pre-flight checks before the release:
+
+| Tier | Auto Pre-flight |
+|------|----------------|
+| `mvp` | None — proceed directly to release checklist |
+| `medium` | `[auto]` verify-work (if no existing VERIFICATION.md) |
+| `enterprise` | `[auto]` verify-work → `[auto]` audit-milestone → `[auto]` arch-review |
+
+All auto-invocations appear with `[auto]` prefix in output.
+
+Override with `--no-auto` to skip all pre-invocations.
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `--no-auto` | Skip all auto pre-flight invocations |
+
+## What It Does
+
+1. **Smart pre-flight** (auto, tier-based — see above)
+2. **Validates** state (clean working tree, tests passing, coverage meets tier threshold)
+3. **Runs security gates** (no secrets, no critical vulns, no production TODOs)
+4. **Evaluates tier checklist** (6/18/30 items based on tier)
+5. **Creates release branch** (per tier git strategy)
+6. **Generates changelog** (from commits since last tag)
+7. **Bumps version** in package.json
+8. **Creates rollback plan** in `.planning/releases/`
+9. **Tags the release** with `v{version}`
+10. **Reports Production Readiness Score** (0-100)
+
+## Output Example
+
+```
+## Release: v1.0.0 (mvp tier)
+
+Security Gates: 4/4 passed
+Checklist: 6/6 items passed
+Production Readiness Score: 96/100
+
+Branch: main (trunk-based)
+Tag: v1.0.0
+Changelog: Updated
+Rollback Plan: .planning/releases/v1.0.0-ROLLBACK-PLAN.md
+
+✓ Ready to push:
+  git push origin main && git push origin v1.0.0
+```
+
+## Tier Promotion
+
+Promote tier when ready for more users:
+
+```bash
+# Start MVP
+/ez:release mvp v1.0.0
+
+# 3 months later, enough users for proper testing
+/ez:release medium v1.5.0
+
+# Enterprise deal signed
+/ez:release enterprise v2.0.0
+```
+
+Each promotion checks that previous tier requirements are still satisfied.
+
+## Preflight Check
+
+Run checklist without creating release:
+
+```bash
+/ez:release preflight mvp
+/ez:release preflight enterprise
+```
+
+Shows which items pass/fail without creating branch or tag.
+
+## Related Commands
+
+- `/ez:hotfix` — Emergency fix on released version
+- `/ez:standup` — Check sprint health before release
+- `/ez:arch-review` — Architecture review before release
+- `/ez:verify-work` — Manual verification before release