@howlil/ez-agents 3.4.2 → 4.0.0

package/ez-agents/workflows/new-milestone.md

@@ -2,6 +2,8 @@
 
 Start a new milestone cycle for an existing project. Loads project context, gathers milestone goals (from MILESTONE-CONTEXT.md or conversation), updates PROJECT.md and STATE.md, optionally runs parallel research, defines scoped requirements with REQ-IDs, spawns the roadmapper to create phased execution plan, and commits all artifacts. Brownfield equivalent of new-project.
 
+**GSD-2 Enhanced:** Includes crash recovery, cost tracking, fresh context, and stuck detection for production-grade reliability.
+
 </purpose>
 
 <required_reading>
@@ -12,12 +14,138 @@ Read all files referenced by the invoking prompt's execution_context before star
 
 <process>
 
+## 0. Pre-Flight Health Check (GSD-2 Pattern)
+
+**MANDATORY FIRST STEP — Validate environment before ANY operation:**
+
+```bash
+# Run health check
+HEALTH=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" doctor --json)
+```
+
+**Check:**
+- ✅ Node.js version >= 16.7.0
+- ✅ AI tools available (Claude, OpenCode, etc.)
+- ✅ Config valid (`.planning/config.json`)
+- ✅ Git repo initialized
+- ✅ API keys configured
+
+**If any check fails:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► HEALTH CHECK FAILED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❌ [Failed check description]
+
+Fix:
+  [suggested command]
+
+Example:
+  $ [example command]
+
+Resolve before continuing with milestone initialization.
+```
+
+**Abort milestone init until resolved.**
+
+---
+
+## 0a. Gather Initial Context (CONTEXT-01, CONTEXT-02)
+
+**Initialize ContextManager for context gathering:**
+
+```javascript
+const ContextManager = require('../bin/lib/context-manager.cjs');
+const contextManager = new ContextManager(process.cwd());
+```
+
+**Request milestone-specific context:**
+
+```javascript
+const context = await contextManager.requestContext({
+  files: ['.planning/PROJECT.md', '.planning/STATE.md', '.planning/ROADMAP.md'],
+  urls: []
+});
+```
+
+**Agent can request additional context using:**
+- `ez-tools context read <pattern>` — Read local files
+- `ez-tools context fetch <url>` — Fetch URL content (requires user confirmation)
+
+**Update STATE.md with context sources:**
+
+```javascript
+await contextManager.updateStateMd();
+```
+
+**Continue to Load Context (Step 1) with gathered context.**
+
+---
+
 ## 1. Load Context
 
-- Read PROJECT.md (existing project, validated requirements, decisions)
-- Read MILESTONES.md (what shipped previously)
-- Read STATE.md (pending todos, blockers)
-- Check for MILESTONE-CONTEXT.md (from /ez:discuss-milestone)
+Read PROJECT.md (existing project, validated requirements, decisions)
+Read MILESTONES.md (what shipped previously)
+Read STATE.md (pending todos, blockers)
+Check for MILESTONE-CONTEXT.md (from /ez:discuss-milestone)
+
+---
+
+## 1a. Initialize Milestone Cost Tracking (GSD-2 Pattern)
+
+**Create/Update metrics.json:**
+
+```bash
+# Initialize milestone budget
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" cost-init \
+  --milestone="v[X.Y]" \
+  --budget-ceiling=50.00 \
+  --alert-threshold=0.8
+```
+
+**Create `.planning/metrics.json`:**
+```json
+{
+  "milestone": "v[X.Y]",
+  "started_at": "2026-03-18T12:00:00.000Z",
+  "budget": {
+    "ceiling": 50.00,
+    "alert_threshold": 0.8,
+    "projected": 0.00,
+    "spent": 0.00
+  },
+  "phases": {},
+  "cumulative": {
+    "total_tokens": 0,
+    "total_cost_usd": 0.00,
+    "by_provider": {}
+  }
+}
+```
+
+**Display budget info:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► MILESTONE BUDGET
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Milestone: v[X.Y]
+Budget Ceiling: $50.00
+Alert Threshold: 80% ($40.00)
+
+You will be warned when spending reaches 80% of budget.
+Auto-pause at $50.00.
+
+View anytime: /ez:cost
+```
+
+**Commit metrics.json:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "chore: initialize milestone budget" --files .planning/metrics.json
+```
+
+---
 
 ## 2. Gather Milestone Goals
 
@@ -31,12 +159,56 @@ Read all files referenced by the invoking prompt's execution_context before star
 - Wait for their response, then use AskUserQuestion to probe specifics
 - If user selects "Other" at any point to provide freeform input, ask follow-up as plain text — not another AskUserQuestion
 
+---
+
+## 2a. Create Lock File (GSD-2 Pattern)
+
+**Before any major operation:**
+
+```bash
+# Create auto.lock
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-create \
+  --operation="new-milestone" \
+  --milestone="v[X.Y]"
+```
+
+**Create `.planning/auto.lock`:**
+```json
+{
+  "pid": 12345,
+  "operation": "new-milestone",
+  "milestone": "v[X.Y]",
+  "started_at": "2026-03-18T12:00:00.000Z",
+  "last_heartbeat": "2026-03-18T12:00:00.000Z",
+  "state": "gathering_goals"
+}
+```
+
+**Update heartbeat every 5 minutes:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-heartbeat
+```
+
+**On completion:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-release
+```
+
+**On crash/restart:**
+- Detect orphaned lock (PID dead)
+- Synthesize recovery briefing
+- Resume from last known state
+
+---
+
 ## 3. Determine Milestone Version
 
 - Parse last version from MILESTONES.md
 - Suggest next version (v1.0 → v1.1, or v2.0 for major)
 - Confirm with user
 
+---
+
 ## 4. Update PROJECT.md
 
 Add/update:
@@ -54,6 +226,8 @@ Add/update:
 
 Update Active requirements section and "Last updated" footer.
 
+---
+
 ## 5. Update STATE.md
 
 ```markdown
@@ -67,14 +241,23 @@ Last activity: [today] — Milestone v[X.Y] started
 
 Keep Accumulated Context section from previous milestone.
 
+---
+
 ## 6. Cleanup and Commit
 
 Delete MILESTONE-CONTEXT.md if exists (consumed).
 
 ```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: start milestone v[X.Y] [Name]" --files .planning/PROJECT.md .planning/STATE.md .planning/metrics.json
 ```
 
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="context_loaded"
+```
+
+---
+
 ## 7. Load Context and Resolve Models
 
 ```bash
@@ -84,6 +267,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Extract from init JSON: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `research_enabled`, `current_milestone`, `project_exists`, `roadmap_exists`.
 
+---
+
 ## 8. Research Decision
 
 AskUserQuestion: "Research the domain ecosystem for new features before defining requirements?"
@@ -100,6 +285,11 @@ node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set workflow.research tru
 node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set workflow.research false
 ```
 
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="research_decision"
+```
+
 **If "Research first":**
 
 ```
@@ -115,13 +305,27 @@ node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set workflow.research fal
 mkdir -p .planning/research
 ```
 
-Spawn 4 parallel ez-project-researcher agents. Each uses this template with dimension-specific fields:
+**Spawn 4 parallel ez-project-researcher agents with FRESH CONTEXT (GSD-2 Pattern):**
+
+Each uses this template with dimension-specific fields:
 
 **Common structure for all 4 researchers:**
 ```
 Task(prompt="
 <research_type>Project Research — {DIMENSION} for [new features].</research_type>
 
+<fresh_context>
+CONTEXT RESET: This is a fresh 200K session.
+No accumulated garbage from prior tasks.
+Only relevant context pre-loaded below.
+</fresh_context>
+
+<pre_loaded_context>
+- .planning/PROJECT.md excerpt (core value, milestone goals)
+- .planning/REQUIREMENTS.md excerpt (active requirements)
+- .planning/ROADMAP.md excerpt (phase structure)
+</pre_loaded_context>
+
 <milestone_context>
 SUBSEQUENT MILESTONE — Adding [target features] to existing app.
 {EXISTING_CONTEXT}
@@ -171,7 +375,7 @@ Synthesize research outputs into SUMMARY.md.
 Write to: .planning/research/SUMMARY.md
 Use template: ~/.claude/ez-agents/templates/research-project/SUMMARY.md
 Commit after writing.
-", subagent_type="ez-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
+", subagent_type="ez-phase-researcher", model="{synthesizer_model}", description="Synthesize research")
 ```
 
 Display key findings from SUMMARY.md:
@@ -185,8 +389,15 @@ Display key findings from SUMMARY.md:
 **Watch Out For:** [from SUMMARY.md]
 ```
 
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="research_complete"
+```
+
 **If "Skip research":** Continue to Step 9.
 
+---
+
 ## 9. Define Requirements
 
 ```
@@ -258,7 +469,14 @@ If "adjust": Return to scoping.
 node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: define milestone v[X.Y] requirements" --files .planning/REQUIREMENTS.md
 ```
 
-## 10. Create Roadmap
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="requirements_defined"
+```
+
+---
+
+## 10. Create Roadmap (with Stuck Detection - GSD-2 Pattern)
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -268,6 +486,16 @@ node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: define milestone v
 ◆ Spawning roadmapper...
 ```
 
+**Initialize stuck detection:**
+
+```bash
+# Start stuck watcher
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" stuck-watch start \
+  --operation="roadmap-creation" \
+  --max-retries=1 \
+  --timeout=300
+```
+
 **Starting phase number:** Read MILESTONES.md for last phase number. Continue from there (v1.0 ended at phase 5 → v1.1 starts at phase 6).
 
 ```
@@ -299,7 +527,41 @@ Write files first, then return.
 
 **Handle return:**
 
-**If `## ROADMAP BLOCKED`:** Present blocker, work with user, re-spawn.
+**If `## ROADMAP BLOCKED`:**
+1. Log error type and location
+2. Retry ONCE with diagnostic context:
+```
+Task(prompt="
+<retry_context>
+PREVIOUS ATTEMPT FAILED
+Error Type: [error_type]
+Error Location: [location]
+Suggested Fix: [fix]
+
+CONTEXT SNAPSHOT FOR DEBUGGING:
+[snapshot of files read]
+
+Please try again with this diagnostic information.
+</retry_context>
+", subagent_type="ez-roadmapper", model="{roadmapper_model}", description="Create roadmap (retry)")
+```
+3. If fails again → STOP with exact failure report:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► ROADMAP CREATION FAILED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Error Type: [type]
+Error Location: [file:line]
+Suggested Fix: [action]
+
+Debug: Run `/ez:debug` to see current session state
+
+Next Steps:
+1. Review error details
+2. Fix [specific issue]
+3. Run: /ez:plan-milestone --retry
+```
 
 **If `## ROADMAP CREATED`:** Read ROADMAP.md, present inline:
 
@@ -335,7 +597,60 @@ Success criteria:
 node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: create milestone v[X.Y] roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 ```
 
-## 11. Done
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="roadmap_created"
+```
+
+---
+
+## 11. Release Lock File
+
+**Milestone initialization complete:**
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-release
+```
+
+---
+
+## 12. Post-Milestone Cost Report (GSD-2 Pattern)
+
+**After all commits complete:**
+
+```bash
+# Generate cost report
+COST_REPORT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" cost-report \
+  --milestone="v[X.Y]" \
+  --format=summary)
+```
+
+**Display:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► MILESTONE INITIALIZATION COST
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Milestone: v[X.Y]
+Phases: [N]
+Requirements: [X]
+
+Initialization Cost:
+- Research: $[X.XX] ([N] tokens)
+- Requirements: $[X.XX] ([N] tokens)
+- Roadmap: $[X.XX] ([N] tokens)
+- Total: $[X.XX] ([N] tokens)
+
+Budget Remaining: $[XX.XX] of $[XX.XX]
+
+Projected Total (based on similar milestones): $[XX.XX]
+
+View detailed report: /ez:cost --milestone=v[X.Y]
+```
+
+---
+
+## 13. Done
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -350,6 +665,7 @@ node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: create milestone v
 | Research       | `.planning/research/`       |
 | Requirements   | `.planning/REQUIREMENTS.md` |
 | Roadmap        | `.planning/ROADMAP.md`      |
+| Metrics        | `.planning/metrics.json`    |
 
 **[N] phases** | **[X] requirements** | Ready to build ✓
 
@@ -367,18 +683,31 @@ Also: `/ez:plan-phase [N]` — skip discussion, plan directly
 </process>
 
 <success_criteria>
+- [ ] Pre-flight health check passed (all systems go)
+- [ ] Cost tracking initialized (metrics.json created)
+- [ ] Lock file created and maintained throughout
 - [ ] PROJECT.md updated with Current Milestone section
 - [ ] STATE.md reset for new milestone
 - [ ] MILESTONE-CONTEXT.md consumed and deleted (if existed)
-- [ ] Research completed (if selected) — 4 parallel agents, milestone-aware
+- [ ] Research completed (if selected) — 4 parallel agents, milestone-aware, fresh context
 - [ ] Requirements gathered and scoped per category
 - [ ] REQUIREMENTS.md created with REQ-IDs
 - [ ] ez-roadmapper spawned with phase numbering context
+- [ ] Stuck detection active during roadmap creation
 - [ ] Roadmap files written immediately (not draft)
 - [ ] User feedback incorporated (if any)
 - [ ] ROADMAP.md phases continue from previous milestone
 - [ ] All commits made (if planning docs committed)
+- [ ] Lock file released on completion
+- [ ] Cost report displayed
 - [ ] User knows next step: `/ez:discuss-phase [N]`
 
 **Atomic commits:** Each phase commits its artifacts immediately.
+
+**GSD-2 Reliability:**
+- ✅ Crash recovery via lock files
+- ✅ Cost transparency via metrics.json
+- ✅ Fresh context per researcher/agent
+- ✅ Stuck detection with diagnostics
+- ✅ Health check pre-flight validation
 </success_criteria>