@howlil/ez-agents 3.5.0 → 4.0.0

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

@@ -1,1107 +1,1089 @@
-<purpose>
-Initialize a new project through unified flow: questioning, research (optional), requirements, roadmap. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes. One workflow takes you from idea to ready-for-planning.
-
-**GSD-2 Enhanced:** Includes health check, cost tracking, crash recovery, fresh context, and stuck detection for production-grade reliability.
-</purpose>
-
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-</required_reading>
-
-<auto_mode>
-## Auto Mode Detection
-
-Check if `--auto` flag is present in $ARGUMENTS.
-
-**If auto mode:**
-- Skip brownfield mapping offer (assume greenfield)
-- Skip deep questioning (extract context from provided document)
-- Config: YOLO mode is implicit (skip that question), but ask granularity/git/agents FIRST (Step 2a)
-- After config: run Steps 6-9 automatically with smart defaults:
-  - Research: Always yes
-  - Requirements: Include all table stakes + features from provided document
-  - Requirements approval: Auto-approve
-  - Roadmap approval: Auto-approve
-
-**Document requirement:**
-Auto mode requires an idea document — either:
-- File reference: `/ez:new-project --auto @prd.md`
-- Pasted/written text in the prompt
-
-If no document content provided, error:
-
-```
-Error: --auto requires an idea document.
-
-Usage:
-  /ez:new-project --auto @your-idea.md
-  /ez:new-project --auto [paste or write your idea here]
-
-The document should describe what you want to build.
-```
-</auto_mode>
-
-<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` or create default)
-- ✅ Git repo initialized (or auto-init)
-- ✅ API keys configured
-
-**If any check fails:**
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► HEALTH CHECK FAILED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-❌ [Failed check description]
-
-Fix:
-  [suggested command]
-
-Example:
-  $ [example command]
-
-Resolve before continuing with project initialization.
-```
-
-**Abort project 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 initial project context:**
-
-```javascript
-const context = await contextManager.requestContext({
-  files: ['README.md', 'package.json'],
-  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 Setup (Step 1) with gathered context.**
-
----
-
-## 1. Setup with Lock File (GSD-2 Pattern)
-
-**Execute initialization with crash recovery:**
-
-```bash
-INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init new-project)
-if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
-```
-
-Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`.
-
-**If `project_exists` is true:** Error — project already initialized. Use `/ez:progress`.
-
-**Create lock file for crash recovery:**
-
-```bash
-# Create auto.lock
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-create \
-  --operation="new-project" \
-  --project-path="$project_path"
-```
-
-**Create `.planning/auto.lock`:**
-```json
-{
-  "pid": 12345,
-  "operation": "new-project",
-  "project_path": "/path/to/project",
-  "started_at": "2026-03-18T12:00:00.000Z",
-  "last_heartbeat": "2026-03-18T12:00:00.000Z",
-  "state": "setup"
-}
-```
-
-**If `has_git` is false:** Initialize git:
-```bash
-git init
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="git_initialized"
-```
-
----
-
-## 2. Brownfield Offer
-
-**If auto mode:** Skip to Step 4 (assume greenfield, synthesize PROJECT.md from provided document).
-
-**If `needs_codebase_map` is true** (from init — existing code detected but no codebase map):
-
-Use AskUserQuestion:
-- header: "Codebase"
-- question: "I detected existing code in this directory. Would you like to map the codebase first?"
-- options:
-  - "Map codebase first" — Run /ez:map-codebase to understand existing architecture (Recommended)
-  - "Skip mapping" — Proceed with project initialization
-
-**If "Map codebase first":**
-```
-Run `/ez:map-codebase` first, then return to `/ez:new-project`
-```
-Exit command.
-
-**If "Skip mapping" OR `needs_codebase_map` is false:** Continue to Step 3.
-
-**Update lock file state:**
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="brownfield_check_complete"
-```
-
----
-
-## 2a. Auto Mode Config (auto mode only)
-
-**If auto mode:** Collect config settings upfront before processing the idea document.
-
-YOLO mode is implicit (auto = YOLO). Ask remaining config questions:
-
-**Round 1 — Core settings (3 questions, no Mode question):**
-
-```
-AskUserQuestion([
-  {
-    header: "Granularity",
-    question: "How finely should scope be sliced into phases?",
-    multiSelect: false,
-    options: [
-      { label: "Coarse (Recommended)", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
-      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" }
-    ]
-  },
-  {
-    header: "Execution",
-    question: "Run plans in parallel?",
-    multiSelect: false,
-    options: [
-      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
-      { label: "Sequential", description: "One plan at a time" }
-    ]
-  },
-  {
-    header: "Git Tracking",
-    question: "Commit planning docs to git?",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
-      { label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
-    ]
-  }
-])
-```
-
-**Round 2 — Workflow agents (same as Step 5):**
-
-```
-AskUserQuestion([
-  {
-    header: "Research",
-    question: "Research before planning each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
-      { label: "No", description: "Plan directly from requirements" }
-    ]
-  },
-  {
-    header: "Plan Check",
-    question: "Verify plans will achieve their goals? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
-      { label: "No", description: "Execute plans without verification" }
-    ]
-  },
-  {
-    header: "Verifier",
-    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
-      { label: "No", description: "Trust execution, skip verification" }
-    ]
-  },
-  {
-    header: "AI Models",
-    question: "Which AI models for planning agents?",
-    multiSelect: false,
-    options: [
-      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
-      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
-      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
-    ]
-  }
-])
-```
-
-Create `.planning/config.json` with mode set to "yolo":
-
-```json
-{
-  "mode": "yolo",
-  "granularity": "[selected]",
-  "parallelization": true|false,
-  "commit_docs": true|false,
-  "model_profile": "quality|balanced|budget",
-  "workflow": {
-    "research": true|false,
-    "plan_check": true|false,
-    "verifier": true|false,
-    "nyquist_validation": depth !== "quick",
-    "auto_advance": true
-  }
-}
-```
-
-**If commit_docs = No:** Add `.planning/` to `.gitignore`.
-
-**Commit config.json:**
-
-```bash
-mkdir -p .planning
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "chore: add project config" --files .planning/config.json
-```
-
-**Persist auto-advance chain flag to config (survives context compaction):**
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set workflow._auto_chain_active true
-```
-
-**Update lock file state:**
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="config_complete"
-```
-
-Proceed to Step 4 (skip Steps 3 and 5).
-
----
-
-## 3. Deep Questioning
-
-**If auto mode:** Skip (already handled in Step 2a). Extract project context from provided document instead and proceed to Step 4.
-
-**Display stage banner:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► QUESTIONING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Open the conversation:**
-
-Ask inline (freeform, NOT AskUserQuestion):
-
-"What do you want to build?"
-
-Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
-
-**Follow the thread:**
-
-Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
-
-Keep following threads. Each answer opens new threads to explore. Ask about:
-- What excited them
-- What problem sparked this
-- What they mean by vague terms
-- What it would actually look like
-- What's already decided
-
-Consult `questioning.md` for techniques:
-- Challenge vagueness
-- Make abstract concrete
-- Surface assumptions
-- Find edges
-- Reveal motivation
-
-**Check context (background, not out loud):**
-
-As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
-
-**Decision gate:**
-
-When you could write a clear PROJECT.md, use AskUserQuestion:
-
-- header: "Ready?"
-- question: "I think I understand what you're after. Ready to create PROJECT.md?"
-- options:
-  - "Create PROJECT.md" — Let's move forward
-  - "Keep exploring" — I want to share more / ask me more
-
-If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
-
-Loop until "Create PROJECT.md" selected.
-
-**Update lock file state:**
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="questioning_complete"
-```
-
----
-
-## 4. Write PROJECT.md
-
-**If auto mode:** Synthesize from provided document. No "Ready?" gate was shown — proceed directly to commit.
-
-Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`.
-
-**For greenfield projects:**
-
-Initialize requirements as hypotheses:
-
-```markdown
-## Requirements
-
-### Validated
-
-(None yet — ship to validate)
-
-### Active
-
-- [ ] [Requirement 1]
-- [ ] [Requirement 2]
-- [ ] [Requirement 3]
-
-### Out of Scope
-
-- [Exclusion 1] — [why]
-- [Exclusion 2] — [why]
-```
-
-All Active requirements are hypotheses until shipped and validated.
-
-**For brownfield projects (codebase map exists):**
-
-Infer Validated requirements from existing code:
-
-1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
-2. Identify what the codebase already does
-3. These become the initial Validated set
-
-```markdown
-## Requirements
-
-### Validated
-
-- ✓ [Existing capability 1] — existing
-- ✓ [Existing capability 2] — existing
-- ✓ [Existing capability 3] — existing
-
-### Active
-
-- [ ] [New requirement 1]
-- [ ] [New requirement 2]
-
-### Out of Scope
-
-- [Exclusion 1] — [why]
-```
-
-**Key Decisions:**
-
-Initialize with any decisions made during questioning:
-
-```markdown
-## Key Decisions
-
-| Decision | Rationale | Outcome |
-|----------|-----------|---------|
-| [Choice from questioning] | [Why] | — Pending |
-```
-
-**Last updated footer:**
-
-```markdown
----
-*Last updated: [date] after initialization*
-```
-
-Do not compress. Capture everything gathered.
-
-**Commit PROJECT.md:**
-
-```bash
-mkdir -p .planning
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: initialize project" --files .planning/PROJECT.md
-```
-
-**Update lock file state:**
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="project_defined"
-```
-
----
-
-## 5. Workflow Preferences
-
-**If auto mode:** Skip — config was collected in Step 2a. Proceed to Step 5.5.
-
-**Check for global defaults** at `~/.ez/defaults.json` using direct path existence checks only.
-Do **not** glob or recursively search home directories for this file.
-If it exists, offer to use saved defaults:
-
-```
-AskUserQuestion([
-  {
-    question: "Use your saved default settings? (from ~/.ez/defaults.json)",
-    header: "Defaults",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Use saved defaults, skip settings questions" },
-      { label: "No", description: "Configure settings manually" }
-    ]
-  }
-])
-```
-
-If "Yes": read `~/.ez/defaults.json`, use those values for config.json, and skip directly to **Commit config.json** below.
-
-If "No" or it doesn't exist: proceed with the questions below.
-
-**Round 1 — Core workflow settings (4 questions):**
-
-```
-questions: [
-  {
-    header: "Mode",
-    question: "How do you want to work?",
-    multiSelect: false,
-    options: [
-      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
-      { label: "Interactive", description: "Confirm at each step" }
-    ]
-  },
-  {
-    header: "Granularity",
-    question: "How finely should scope be sliced into phases?",
-    multiSelect: false,
-    options: [
-      { label: "Coarse", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
-      { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
-      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" }
-    ]
-  },
-  {
-    header: "Execution",
-    question: "Run plans in parallel?",
-    multiSelect: false,
-    options: [
-      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
-      { label: "Sequential", description: "One plan at a time" }
-    ]
-  },
-  {
-    header: "Git Tracking",
-    question: "Commit planning docs to git?",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
-      { label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
-    ]
-  }
-]
-```
-
-**Round 2 — Workflow agents:**
-
-These spawn additional agents during planning/execution. They add tokens and time but improve quality. They add tokens and time but improve quality.
-
-All recommended for important projects. Skip for quick experiments.
-
-```
-questions: [
-  {
-    header: "Research",
-    question: "Research before planning each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Investigate domain, find patterns, surface gotchas" },
-      { label: "No", description: "Plan directly from requirements" }
-    ]
-  },
-  {
-    header: "Plan Check",
-    question: "Verify plans will achieve their goals? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
-      { label: "No", description: "Execute plans without verification" }
-    ]
-  },
-  {
-    header: "Verifier",
-    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
-    multiSelect: false,
-    options: [
-      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
-      { label: "No", description: "Trust execution, skip verification" }
-    ]
-  },
-  {
-    header: "AI Models",
-    question: "Which AI models for planning agents?",
-    multiSelect: false,
-    options: [
-      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
-      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
-      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
-    ]
-  }
-]
-```
-
-Create `.planning/config.json` with all settings:
-
-```json
-{
-  "mode": "yolo|interactive",
-  "granularity": "coarse|standard|fine",
-  "parallelization": true|false,
-  "commit_docs": true|false,
-  "model_profile": "quality|balanced|budget",
-  "workflow": {
-    "research": true|false,
-    "plan_check": true|false,
-    "verifier": true|false,
-    "nyquist_validation": depth !== "quick"
-  }
-}
-```
-
-**If commit_docs = No:**
-- Set `commit_docs: false` in config.json
-- Add `.planning/` to `.gitignore` (create if needed)
-
-**If commit_docs = Yes:**
-- No additional gitignore entries needed
-
-**Commit config.json:**
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "chore: add project config" --files .planning/config.json
-```
-
-**Note:** Run `/ez:settings` anytime to update these preferences.
-
-**Update lock file state:**
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="config_complete"
-```
-
-## 5.5. Resolve Model Profile
-
-Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model`.
-
----
-
-## 6. Research Decision (with Fresh Context - GSD-2 Pattern)
-
-**If auto mode:** Default to "Research first" without asking.
-
-Use AskUserQuestion:
-- header: "Research"
-- question: "Research the domain ecosystem before defining requirements?"
-- options:
-  - "Research first (Recommended)" — Discover standard stack, expected features, architecture patterns
-  - "Skip research" — I know this domain well, go straight to requirements
-
-**If "Research first":**
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► RESEARCHING
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Researching [domain] ecosystem...
-```
-
-Create research directory:
-```bash
-mkdir -p .planning/research
-```
-
-**Determine milestone context:**
-
-Check if this is greenfield or subsequent milestone:
-- If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch)
-- If "Validated" requirements exist → Subsequent milestone (adding to existing app)
-
-Display spawning indicator:
-```
-◆ Spawning 4 researchers in parallel...
-  → Stack research
-  → Features research
-  → Architecture research
-  → Pitfalls research
-```
-
-**Spawn 4 parallel ez-project-researcher agents with FRESH CONTEXT (GSD-2 Pattern):**
-
-Each uses this template with dimension-specific fields:
-
-```
-Task(prompt="
-<research_type>Project Research — {DIMENSION} for [domain].</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, goals)
-- .planning/config.json (workflow settings)
-</pre_loaded_context>
-
-<milestone_context>
-{greenfield_or_subsequent}
-
-Greenfield: Research the standard stack for building [domain] from scratch.
-Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
-</milestone_context>
-
-<question>
-{QUESTION}
-</question>
-
-<files_to_read>
-- {project_path} (Project context and goals)
-</files_to_read>
-
-<downstream_consumer>
-{CONSUMER}
-</downstream_consumer>
-
-<quality_gate>
-{GATES}
-</quality_gate>
-
-<output>
-Write to: .planning/research/{FILE}
-Use template: ~/.claude/ez-agents/templates/research-project/{FILE}
-</output>
-", subagent_type="ez-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
-```
-
-**Dimension-specific fields:**
-
-| Field | Stack | Features | Architecture | Pitfalls |
-|-------|-------|----------|-------------|----------|
-| QUESTION | What's the standard 2025 stack for [domain]? | What features do [domain] products have? | How are [domain] systems typically structured? | What do [domain] projects commonly get wrong? |
-| CONSUMER | Specific libraries with versions, clear rationale, what NOT to use | Table stakes vs differentiators vs anti-features | Component boundaries, data flow, build order | Warning signs, prevention strategy, phase mapping |
-| GATES | Versions current (verify with Context7), rationale explains WHY | Categories clear, complexity noted, dependencies identified | Components clearly defined, data flow explicit | Pitfalls specific to domain, prevention actionable |
-| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
-
-After all 4 complete, spawn synthesizer to create SUMMARY.md:
-
-```
-Task(prompt="
-Synthesize research outputs into SUMMARY.md.
-
-<files_to_read>
-- .planning/research/STACK.md
-- .planning/research/FEATURES.md
-- .planning/research/ARCHITECTURE.md
-- .planning/research/PITFALLS.md
-</files_to_read>
-
-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")
-```
-
-Display research complete banner and key findings:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► RESEARCH COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-## Key Findings
-
-**Stack:** [from SUMMARY.md]
-**Table Stakes:** [from SUMMARY.md]
-**Watch Out For:** [from SUMMARY.md]
-
-Files: `.planning/research/`
-```
-
-**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 7.
-
----
-
-## 7. Define Requirements
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► DEFINING REQUIREMENTS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-**Load context:**
-
-Read PROJECT.md and extract:
-- Core value (the ONE thing that must work)
-- Stated constraints (budget, timeline, tech limitations)
-- Any explicit scope boundaries
-
-**If research exists:** Read research/FEATURES.md and extract feature categories.
-
-**If auto mode:**
-- Auto-include all table stakes features (users expect these)
-- Include features explicitly mentioned in provided document
-- Auto-defer differentiators not mentioned in document
-- Skip per-category AskUserQuestion loops
-- Skip "Any additions?" question
-- Skip requirements approval gate
-- Generate REQUIREMENTS.md and commit directly
-
-**Present features by category (interactive mode only):**
-
-```
-Here are the features for [domain]:
-
-## Authentication
-**Table stakes:**
-- Sign up with email/password
-- Email verification
-- Password reset
-- Session management
-
-**Differentiators:**
-- Magic link login
-- OAuth (Google, GitHub)
-- 2FA
-
-**Research notes:** [any relevant notes]
-
----
-
-## [Next Category]
-...
-```
-
-**If no research:** Gather requirements through conversation instead.
-
-Ask: "What are the main things users need to be able to do?"
-
-For each capability mentioned:
-- Ask clarifying questions to make it specific
-- Probe for related capabilities
-- Group into categories
-
-**Scope each category:**
-
-For each category, use AskUserQuestion:
-
-- header: "[Category]" (max 12 chars)
-- question: "Which [category] features are in v1?"
-- multiSelect: true
-- options:
-  - "[Feature 1]" — [brief description]
-  - "[Feature 2]" — [brief description]
-  - "[Feature 3]" — [brief description]
-  - "None for v1" — Defer entire category
-
-Track responses:
-- Selected features → v1 requirements
-- Unselected table stakes → v2 (users expect these)
-- Unselected differentiators → out of scope
-
-**Identify gaps:**
-
-Use AskUserQuestion:
-- header: "Additions"
-- question: "Any requirements research missed? (Features specific to your vision)"
-- options:
-  - "No, research covered it" — Proceed
-  - "Yes, let me add some" — Capture additions
-
-**Validate core value:**
-
-Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
-
-**Generate REQUIREMENTS.md:**
-
-Create `.planning/REQUIREMENTS.md` with:
-- v1 Requirements grouped by category (checkboxes, REQ-IDs)
-- v2 Requirements (deferred)
-- Out of Scope (explicit exclusions with reasoning)
-- Traceability section (empty, filled by roadmap)
-
-**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
-
-**Requirement quality criteria:**
-
-Good requirements are:
-- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
-- **User-centric:** "User can X" (not "System does Y")
-- **Atomic:** One capability per requirement (not "User can login and manage profile")
-- **Independent:** Minimal dependencies on other requirements
-
-Reject vague requirements. Push for specificity.
-
-Present FULL requirements list for confirmation:
-
-```
-## Project Requirements
-
-### [Category 1]
-- [ ] **CAT1-01**: User can do X
-- [ ] **CAT1-02**: User can do Y
-
-### [Category 2]
-- [ ] **CAT2-01**: User can do Z
-
-Does this capture what you're building? (yes / adjust)
-```
-
-If "adjust": Return to scoping.
-
-**Commit requirements:**
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: define project requirements" --files .planning/REQUIREMENTS.md
-```
-
-**Update lock file state:**
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="requirements_defined"
-```
-
----
-
-## 8. Create Roadmap (with Stuck Detection - GSD-2 Pattern)
-
-Display stage banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► CREATING ROADMAP
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-◆ 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
-```
-
-```
-Task(prompt="
-<planning_context>
-<files_to_read>
-- .planning/PROJECT.md
-- .planning/REQUIREMENTS.md
-- .planning/research/SUMMARY.md (if exists)
-- .planning/config.json
-</files_to_read>
-</planning_context>
-
-<instructions>
-Create roadmap for new project:
-1. Start phase numbering from 1
-2. Derive phases from requirements
-3. Map every requirement to exactly one phase
-4. Derive 2-5 success criteria per phase (observable user behaviors)
-5. Validate 100% coverage
-6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
-7. Return ROADMAP CREATED with summary
-
-Write files first, then return.
-</instructions>
-", subagent_type="ez-roadmapper", model="{roadmapper_model}", description="Create roadmap")
-```
-
-**Handle return:**
-
-**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]
-
-Context Snapshot: .planning/logs/stuck-snapshot-[timestamp].json
-
-Next Steps:
-1. Review context snapshot
-2. Fix [specific issue]
-3. Run: /ez:new-project --retry
-```
-
-**If `## ROADMAP CREATED`:** Read ROADMAP.md, present inline:
-
-```
-## Proposed Roadmap
-
-**[N] phases** | **[X] requirements mapped** | All covered ✓
-
-| # | Phase | Goal | Requirements | Success Criteria |
-|---|-------|------|--------------|------------------|
-| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
-
-### Phase Details
-
-**Phase 1: [Name]**
-Goal: [goal]
-Requirements: [REQ-IDs]
-Success criteria:
-1. [criterion]
-2. [criterion]
-```
-
-**Ask for approval** via AskUserQuestion:
-- "Approve" — Commit and continue
-- "Adjust phases" — Tell me what to change
-- "Review full file" — Show raw ROADMAP.md
-
-**If "Adjust":** Get notes, re-spawn roadmapper with revision context, loop until approved.
-**If "Review":** Display raw ROADMAP.md, re-ask.
-
-**Commit roadmap** (after approval):
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: create project roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
-```
-
-**Update lock file state:**
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="roadmap_created"
-```
-
----
-
-## 9. Release Lock File
-
-**Project initialization complete:**
-
-```bash
-node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-release
-```
-
----
-
-## 10. Done
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- EZ ► PROJECT INITIALIZED ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Project: [Project Name]**
-
-| Artifact       | Location                    |
-|----------------|-----------------------------|
-| Project        | `.planning/PROJECT.md`      |
-| Research       | `.planning/research/`       |
-| Requirements   | `.planning/REQUIREMENTS.md` |
-| Roadmap        | `.planning/ROADMAP.md`      |
-| Config         | `.planning/config.json`     |
-
-**[N] phases** | **[X] requirements** | Ready to build ✓
-
-## ▶ Next Up
-
-**Phase 1: [Phase Name]** — [Goal]
-
-`/ez:discuss-phase 1` — gather context and clarify approach
-
-<sub>`/clear` first → fresh context window</sub>
-
-Also: `/ez:plan-phase 1` — skip discussion, plan directly
-```
-
-</process>
-
-<success_criteria>
-- [ ] Pre-flight health check passed (all systems go)
-- [ ] Lock file created and maintained throughout
-- [ ] PROJECT.md created with clear core value
-- [ ] REQUIREMENTS.md created with REQ-IDs
-- [ ] ROADMAP.md created with phased execution plan
-- [ ] STATE.md initialized
-- [ ] Config.json created with workflow preferences
-- [ ] Research completed (if selected) — 4 parallel agents with fresh context
-- [ ] Requirements gathered and scoped per category
-- [ ] ez-roadmapper spawned with stuck detection
-- [ ] Roadmap files written immediately (not draft)
-- [ ] User feedback incorporated (if any)
-- [ ] All commits made (if planning docs committed)
-- [ ] Lock file released on completion
-- [ ] User knows next step: `/ez:discuss-phase 1`
-
-**Atomic commits:** Each artifact committed immediately after creation.
-
-**GSD-2 Reliability:**
-- ✅ Health check pre-flight validation
-- ✅ Crash recovery via lock files
-- ✅ Fresh context per researcher/agent
-- ✅ Stuck detection with diagnostics during roadmap creation
-</success_criteria>
+<purpose>
+Initialize a new project through unified flow: questioning, research (optional), requirements, roadmap. This is the most leveraged moment in any project — deep questioning here means better plans, better execution, better outcomes. One workflow takes you from idea to ready-for-planning.
+
+**GSD-2 Enhanced:** Includes health check, cost tracking, crash recovery, fresh context, and stuck detection for production-grade reliability.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<auto_mode>
+## Auto Mode Detection
+
+Check if `--auto` flag is present in $ARGUMENTS.
+
+**If auto mode:**
+- Skip brownfield mapping offer (assume greenfield)
+- Skip deep questioning (extract context from provided document)
+- Config: YOLO mode is implicit (skip that question), but ask granularity/git/agents FIRST (Step 2a)
+- After config: run Steps 6-9 automatically with smart defaults:
+  - Research: Always yes
+  - Requirements: Include all table stakes + features from provided document
+  - Requirements approval: Auto-approve
+  - Roadmap approval: Auto-approve
+
+**Document requirement:**
+Auto mode requires an idea document — either:
+- File reference: `/ez:new-project --auto @prd.md`
+- Pasted/written text in the prompt
+
+If no document content provided, error:
+
+```
+Error: --auto requires an idea document.
+
+Usage:
+  /ez:new-project --auto @your-idea.md
+  /ez:new-project --auto [paste or write your idea here]
+
+The document should describe what you want to build.
+```
+</auto_mode>
+
+<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` or create default)
+- ✅ Git repo initialized (or auto-init)
+- ✅ API keys configured
+
+**If any check fails:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► HEALTH CHECK FAILED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+❌ [Failed check description]
+
+Fix:
+  [suggested command]
+
+Example:
+  $ [example command]
+
+Resolve before continuing with project initialization.
+```
+
+**Abort project 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 initial project context:**
+
+```javascript
+const context = await contextManager.requestContext({
+  files: ['README.md', 'package.json'],
+  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 Setup (Step 1) with gathered context.**
+
+---
+
+## 1. Setup with Lock File (GSD-2 Pattern)
+
+**Execute initialization with crash recovery:**
+
+```bash
+INIT=$(node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" init new-project)
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`, `project_path`.
+
+**If `project_exists` is true:** Error — project already initialized. Use `/ez:progress`.
+
+**Create lock file for crash recovery:**
+
+```bash
+# Create auto.lock
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-create \
+  --operation="new-project" \
+  --project-path="$project_path"
+```
+
+**Create `.planning/auto.lock`:**
+```json
+{
+  "pid": 12345,
+  "operation": "new-project",
+  "project_path": "/path/to/project",
+  "started_at": "2026-03-18T12:00:00.000Z",
+  "last_heartbeat": "2026-03-18T12:00:00.000Z",
+  "state": "setup"
+}
+```
+
+**If `has_git` is false:** Initialize git:
+```bash
+git init
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="git_initialized"
+```
+
+---
+
+## 2. Brownfield Offer
+
+**If auto mode:** Skip to Step 4 (assume greenfield, synthesize PROJECT.md from provided document).
+
+**If `needs_codebase_map` is true** (from init — existing code detected but no codebase map):
+
+Use AskUserQuestion:
+- header: "Codebase"
+- question: "I detected existing code in this directory. Would you like to map the codebase first?"
+- options:
+  - "Map codebase first" — Run /ez:map-codebase to understand existing architecture (Recommended)
+  - "Skip mapping" — Proceed with project initialization
+
+**If "Map codebase first":**
+```
+Run `/ez:map-codebase` first, then return to `/ez:new-project`
+```
+Exit command.
+
+**If "Skip mapping" OR `needs_codebase_map` is false:** Continue to Step 3.
+
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="brownfield_check_complete"
+```
+
+---
+
+## 2a. Auto Mode Config (auto mode only)
+
+**If auto mode:** Collect config settings upfront before processing the idea document.
+
+YOLO mode is implicit (auto = YOLO). Ask remaining config questions:
+
+**Round 1 — Core settings (3 questions, no Mode question):**
+
+```
+AskUserQuestion([
+  {
+    header: "Granularity",
+    question: "How finely should scope be sliced into phases?",
+    multiSelect: false,
+    options: [
+      { label: "Coarse (Recommended)", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
+      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" }
+    ]
+  },
+  {
+    header: "Execution",
+    question: "Run plans in parallel?",
+    multiSelect: false,
+    options: [
+      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
+      { label: "Sequential", description: "One plan at a time" }
+    ]
+  },
+  {
+    header: "Git Tracking",
+    question: "Commit planning docs to git?",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
+      { label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
+    ]
+  }
+])
+```
+
+**Round 2 — Workflow agents (same as Step 5):**
+
+```
+AskUserQuestion([
+  {
+    header: "Plan Check",
+    question: "Verify plans will achieve their goals? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
+      { label: "No", description: "Execute plans without verification" }
+    ]
+  },
+  {
+    header: "Verifier",
+    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
+      { label: "No", description: "Trust execution, skip verification" }
+    ]
+  },
+  {
+    header: "AI Models",
+    question: "Which AI models for planning agents?",
+    multiSelect: false,
+    options: [
+      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
+      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
+      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
+    ]
+  }
+])
+```
+
+Create `.planning/config.json` with mode set to "yolo":
+
+```json
+{
+  "mode": "yolo",
+  "granularity": "[selected]",
+  "parallelization": true|false,
+  "commit_docs": true|false,
+  "model_profile": "quality|balanced|budget",
+  "workflow": {
+    "research": true|false,
+    "plan_check": true|false,
+    "verifier": true|false,
+    "nyquist_validation": depth !== "quick",
+    "auto_advance": true
+  }
+}
+```
+
+**If commit_docs = No:** Add `.planning/` to `.gitignore`.
+
+**Commit config.json:**
+
+```bash
+mkdir -p .planning
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "chore: add project config" --files .planning/config.json
+```
+
+**Persist auto-advance chain flag to config (survives context compaction):**
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" config-set workflow._auto_chain_active true
+```
+
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="config_complete"
+```
+
+Proceed to Step 4 (skip Steps 3 and 5).
+
+---
+
+## 3. Deep Questioning
+
+**If auto mode:** Skip (already handled in Step 2a). Extract project context from provided document instead and proceed to Step 4.
+
+**Display stage banner:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► QUESTIONING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Open the conversation:**
+
+Ask inline (freeform, NOT AskUserQuestion):
+
+"What do you want to build?"
+
+Wait for their response. This gives you the context needed to ask intelligent follow-up questions.
+
+**Follow the thread:**
+
+Based on what they said, ask follow-up questions that dig into their response. Use AskUserQuestion with options that probe what they mentioned — interpretations, clarifications, concrete examples.
+
+Keep following threads. Each answer opens new threads to explore. Ask about:
+- What excited them
+- What problem sparked this
+- What they mean by vague terms
+- What it would actually look like
+- What's already decided
+
+Consult `questioning.md` for techniques:
+- Challenge vagueness
+- Make abstract concrete
+- Surface assumptions
+- Find edges
+- Reveal motivation
+
+**Check context (background, not out loud):**
+
+As you go, mentally check the context checklist from `questioning.md`. If gaps remain, weave questions naturally. Don't suddenly switch to checklist mode.
+
+**Decision gate:**
+
+When you could write a clear PROJECT.md, use AskUserQuestion:
+
+- header: "Ready?"
+- question: "I think I understand what you're after. Ready to create PROJECT.md?"
+- options:
+  - "Create PROJECT.md" — Let's move forward
+  - "Keep exploring" — I want to share more / ask me more
+
+If "Keep exploring" — ask what they want to add, or identify gaps and probe naturally.
+
+Loop until "Create PROJECT.md" selected.
+
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="questioning_complete"
+```
+
+---
+
+## 4. Write PROJECT.md
+
+**If auto mode:** Synthesize from provided document. No "Ready?" gate was shown — proceed directly to commit.
+
+Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`.
+
+**For greenfield projects:**
+
+Initialize requirements as hypotheses:
+
+```markdown
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+
+### Out of Scope
+
+- [Exclusion 1] — [why]
+- [Exclusion 2] — [why]
+```
+
+All Active requirements are hypotheses until shipped and validated.
+
+**For brownfield projects (codebase map exists):**
+
+Infer Validated requirements from existing code:
+
+1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
+2. Identify what the codebase already does
+3. These become the initial Validated set
+
+```markdown
+## Requirements
+
+### Validated
+
+- ✓ [Existing capability 1] — existing
+- ✓ [Existing capability 2] — existing
+- ✓ [Existing capability 3] — existing
+
+### Active
+
+- [ ] [New requirement 1]
+- [ ] [New requirement 2]
+
+### Out of Scope
+
+- [Exclusion 1] — [why]
+```
+
+**Key Decisions:**
+
+Initialize with any decisions made during questioning:
+
+```markdown
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| [Choice from questioning] | [Why] | — Pending |
+```
+
+**Last updated footer:**
+
+```markdown
+---
+*Last updated: [date] after initialization*
+```
+
+Do not compress. Capture everything gathered.
+
+**Commit PROJECT.md:**
+
+```bash
+mkdir -p .planning
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: initialize project" --files .planning/PROJECT.md
+```
+
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="project_defined"
+```
+
+---
+
+## 5. Workflow Preferences
+
+**If auto mode:** Skip — config was collected in Step 2a. Proceed to Step 5.5.
+
+**Check for global defaults** at `~/.ez/defaults.json` using direct path existence checks only.
+Do **not** glob or recursively search home directories for this file.
+If it exists, offer to use saved defaults:
+
+```
+AskUserQuestion([
+  {
+    question: "Use your saved default settings? (from ~/.ez/defaults.json)",
+    header: "Defaults",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Use saved defaults, skip settings questions" },
+      { label: "No", description: "Configure settings manually" }
+    ]
+  }
+])
+```
+
+If "Yes": read `~/.ez/defaults.json`, use those values for config.json, and skip directly to **Commit config.json** below.
+
+If "No" or it doesn't exist: proceed with the questions below.
+
+**Round 1 — Core workflow settings (4 questions):**
+
+```
+questions: [
+  {
+    header: "Mode",
+    question: "How do you want to work?",
+    multiSelect: false,
+    options: [
+      { label: "YOLO (Recommended)", description: "Auto-approve, just execute" },
+      { label: "Interactive", description: "Confirm at each step" }
+    ]
+  },
+  {
+    header: "Granularity",
+    question: "How finely should scope be sliced into phases?",
+    multiSelect: false,
+    options: [
+      { label: "Coarse", description: "Fewer, broader phases (3-5 phases, 1-3 plans each)" },
+      { label: "Standard", description: "Balanced phase size (5-8 phases, 3-5 plans each)" },
+      { label: "Fine", description: "Many focused phases (8-12 phases, 5-10 plans each)" }
+    ]
+  },
+  {
+    header: "Execution",
+    question: "Run plans in parallel?",
+    multiSelect: false,
+    options: [
+      { label: "Parallel (Recommended)", description: "Independent plans run simultaneously" },
+      { label: "Sequential", description: "One plan at a time" }
+    ]
+  },
+  {
+    header: "Git Tracking",
+    question: "Commit planning docs to git?",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Planning docs tracked in version control" },
+      { label: "No", description: "Keep .planning/ local-only (add to .gitignore)" }
+    ]
+  }
+]
+```
+
+**Round 2 — Workflow agents:**
+
+These spawn additional agents during planning/execution. They add tokens and time but improve quality. They add tokens and time but improve quality.
+
+All recommended for important projects. Skip for quick experiments.
+
+```
+questions: [
+  {
+    header: "Plan Check",
+    question: "Verify plans will achieve their goals? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Catch gaps before execution starts" },
+      { label: "No", description: "Execute plans without verification" }
+    ]
+  },
+  {
+    header: "Verifier",
+    question: "Verify work satisfies requirements after each phase? (adds tokens/time)",
+    multiSelect: false,
+    options: [
+      { label: "Yes (Recommended)", description: "Confirm deliverables match phase goals" },
+      { label: "No", description: "Trust execution, skip verification" }
+    ]
+  },
+  {
+    header: "AI Models",
+    question: "Which AI models for planning agents?",
+    multiSelect: false,
+    options: [
+      { label: "Balanced (Recommended)", description: "Sonnet for most agents — good quality/cost ratio" },
+      { label: "Quality", description: "Opus for research/roadmap — higher cost, deeper analysis" },
+      { label: "Budget", description: "Haiku where possible — fastest, lowest cost" }
+    ]
+  }
+]
+```
+
+Create `.planning/config.json` with all settings:
+
+```json
+{
+  "mode": "yolo|interactive",
+  "granularity": "coarse|standard|fine",
+  "parallelization": true|false,
+  "commit_docs": true|false,
+  "model_profile": "quality|balanced|budget",
+  "workflow": {
+    "research": true|false,
+    "plan_check": true|false,
+    "verifier": true|false,
+    "nyquist_validation": depth !== "quick"
+  }
+}
+```
+
+**If commit_docs = No:**
+- Set `commit_docs: false` in config.json
+- Add `.planning/` to `.gitignore` (create if needed)
+
+**If commit_docs = Yes:**
+- No additional gitignore entries needed
+
+**Commit config.json:**
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "chore: add project config" --files .planning/config.json
+```
+
+**Note:** Run `/ez:settings` anytime to update these preferences.
+
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="config_complete"
+```
+
+## 5.5. Resolve Model Profile
+
+Use models from init: `researcher_model`, `synthesizer_model`, `roadmapper_model`.
+
+---
+
+## 6. Research Decision (with Fresh Context - GSD-2 Pattern)
+
+**If auto mode:** Default to "Research first" without asking.
+
+Use AskUserQuestion:
+- header: "Research"
+- question: "Research the domain ecosystem before defining requirements?"
+- options:
+  - "Research first (Recommended)" — Discover standard stack, expected features, architecture patterns
+  - "Skip research" — I know this domain well, go straight to requirements
+
+**If "Research first":**
+
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► RESEARCHING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Researching [domain] ecosystem...
+```
+
+Create research directory:
+```bash
+mkdir -p .planning/research
+```
+
+**Determine milestone context:**
+
+Check if this is greenfield or subsequent milestone:
+- If no "Validated" requirements in PROJECT.md → Greenfield (building from scratch)
+- If "Validated" requirements exist → Subsequent milestone (adding to existing app)
+
+Display spawning indicator:
+```
+◆ Spawning 4 researchers in parallel...
+  → Stack research
+  → Features research
+  → Architecture research
+  → Pitfalls research
+```
+
+**Spawn 4 parallel ez-project-researcher agents with FRESH CONTEXT (GSD-2 Pattern):**
+
+Each uses this template with dimension-specific fields:
+
+```
+Task(prompt="
+<research_type>Project Research — {DIMENSION} for [domain].</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, goals)
+- .planning/config.json (workflow settings)
+</pre_loaded_context>
+
+<milestone_context>
+{greenfield_or_subsequent}
+
+Greenfield: Research the standard stack for building [domain] from scratch.
+Subsequent: Research what's needed to add [target features] to an existing [domain] app. Don't re-research the existing system.
+</milestone_context>
+
+<question>
+{QUESTION}
+</question>
+
+<files_to_read>
+- {project_path} (Project context and goals)
+</files_to_read>
+
+<downstream_consumer>
+{CONSUMER}
+</downstream_consumer>
+
+<quality_gate>
+{GATES}
+</quality_gate>
+
+<output>
+Write to: .planning/research/{FILE}
+Use template: ~/.claude/ez-agents/templates/research-project/{FILE}
+</output>
+", subagent_type="ez-project-researcher", model="{researcher_model}", description="{DIMENSION} research")
+```
+
+**Dimension-specific fields:**
+
+| Field | Stack | Features | Architecture | Pitfalls |
+|-------|-------|----------|-------------|----------|
+| QUESTION | What's the standard 2025 stack for [domain]? | What features do [domain] products have? | How are [domain] systems typically structured? | What do [domain] projects commonly get wrong? |
+| CONSUMER | Specific libraries with versions, clear rationale, what NOT to use | Table stakes vs differentiators vs anti-features | Component boundaries, data flow, build order | Warning signs, prevention strategy, phase mapping |
+| GATES | Versions current (verify with Context7), rationale explains WHY | Categories clear, complexity noted, dependencies identified | Components clearly defined, data flow explicit | Pitfalls specific to domain, prevention actionable |
+| FILE | STACK.md | FEATURES.md | ARCHITECTURE.md | PITFALLS.md |
+
+After all 4 complete, spawn synthesizer to create SUMMARY.md:
+
+```
+Task(prompt="
+Synthesize research outputs into SUMMARY.md.
+
+<files_to_read>
+- .planning/research/STACK.md
+- .planning/research/FEATURES.md
+- .planning/research/ARCHITECTURE.md
+- .planning/research/PITFALLS.md
+</files_to_read>
+
+Write to: .planning/research/SUMMARY.md
+Use template: ~/.claude/ez-agents/templates/research-project/SUMMARY.md
+Commit after writing.
+", subagent_type="ez-phase-researcher", model="{synthesizer_model}", description="Synthesize research")
+```
+
+Display research complete banner and key findings:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► RESEARCH COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Key Findings
+
+**Stack:** [from SUMMARY.md]
+**Table Stakes:** [from SUMMARY.md]
+**Watch Out For:** [from SUMMARY.md]
+
+Files: `.planning/research/`
+```
+
+**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 7.
+
+---
+
+## 7. Define Requirements
+
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► DEFINING REQUIREMENTS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Load context:**
+
+Read PROJECT.md and extract:
+- Core value (the ONE thing that must work)
+- Stated constraints (budget, timeline, tech limitations)
+- Any explicit scope boundaries
+
+**If research exists:** Read research/FEATURES.md and extract feature categories.
+
+**If auto mode:**
+- Auto-include all table stakes features (users expect these)
+- Include features explicitly mentioned in provided document
+- Auto-defer differentiators not mentioned in document
+- Skip per-category AskUserQuestion loops
+- Skip "Any additions?" question
+- Skip requirements approval gate
+- Generate REQUIREMENTS.md and commit directly
+
+**Present features by category (interactive mode only):**
+
+```
+Here are the features for [domain]:
+
+## Authentication
+**Table stakes:**
+- Sign up with email/password
+- Email verification
+- Password reset
+- Session management
+
+**Differentiators:**
+- Magic link login
+- OAuth (Google, GitHub)
+- 2FA
+
+**Research notes:** [any relevant notes]
+
+---
+
+## [Next Category]
+...
+```
+
+**If no research:** Gather requirements through conversation instead.
+
+Ask: "What are the main things users need to be able to do?"
+
+For each capability mentioned:
+- Ask clarifying questions to make it specific
+- Probe for related capabilities
+- Group into categories
+
+**Scope each category:**
+
+For each category, use AskUserQuestion:
+
+- header: "[Category]" (max 12 chars)
+- question: "Which [category] features are in v1?"
+- multiSelect: true
+- options:
+  - "[Feature 1]" — [brief description]
+  - "[Feature 2]" — [brief description]
+  - "[Feature 3]" — [brief description]
+  - "None for v1" — Defer entire category
+
+Track responses:
+- Selected features → v1 requirements
+- Unselected table stakes → v2 (users expect these)
+- Unselected differentiators → out of scope
+
+**Identify gaps:**
+
+Use AskUserQuestion:
+- header: "Additions"
+- question: "Any requirements research missed? (Features specific to your vision)"
+- options:
+  - "No, research covered it" — Proceed
+  - "Yes, let me add some" — Capture additions
+
+**Validate core value:**
+
+Cross-check requirements against Core Value from PROJECT.md. If gaps detected, surface them.
+
+**Generate REQUIREMENTS.md:**
+
+Create `.planning/REQUIREMENTS.md` with:
+- v1 Requirements grouped by category (checkboxes, REQ-IDs)
+- v2 Requirements (deferred)
+- Out of Scope (explicit exclusions with reasoning)
+- Traceability section (empty, filled by roadmap)
+
+**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, CONTENT-02)
+
+**Requirement quality criteria:**
+
+Good requirements are:
+- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
+- **User-centric:** "User can X" (not "System does Y")
+- **Atomic:** One capability per requirement (not "User can login and manage profile")
+- **Independent:** Minimal dependencies on other requirements
+
+Reject vague requirements. Push for specificity.
+
+Present FULL requirements list for confirmation:
+
+```
+## Project Requirements
+
+### [Category 1]
+- [ ] **CAT1-01**: User can do X
+- [ ] **CAT1-02**: User can do Y
+
+### [Category 2]
+- [ ] **CAT2-01**: User can do Z
+
+Does this capture what you're building? (yes / adjust)
+```
+
+If "adjust": Return to scoping.
+
+**Commit requirements:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: define project requirements" --files .planning/REQUIREMENTS.md
+```
+
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="requirements_defined"
+```
+
+---
+
+## 8. Create Roadmap (with Stuck Detection - GSD-2 Pattern)
+
+Display stage banner:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► CREATING ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ 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
+```
+
+```
+Task(prompt="
+<planning_context>
+<files_to_read>
+- .planning/PROJECT.md
+- .planning/REQUIREMENTS.md
+- .planning/research/SUMMARY.md (if exists)
+- .planning/config.json
+</files_to_read>
+</planning_context>
+
+<instructions>
+Create roadmap for new project:
+1. Start phase numbering from 1
+2. Derive phases from requirements
+3. Map every requirement to exactly one phase
+4. Derive 2-5 success criteria per phase (observable user behaviors)
+5. Validate 100% coverage
+6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+7. Return ROADMAP CREATED with summary
+
+Write files first, then return.
+</instructions>
+", subagent_type="ez-roadmapper", model="{roadmapper_model}", description="Create roadmap")
+```
+
+**Handle return:**
+
+**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:new-project --retry
+```
+
+**If `## ROADMAP CREATED`:** Read ROADMAP.md, present inline:
+
+```
+## Proposed Roadmap
+
+**[N] phases** | **[X] requirements mapped** | All covered ✓
+
+| # | Phase | Goal | Requirements | Success Criteria |
+|---|-------|------|--------------|------------------|
+| 1 | [Name] | [Goal] | [REQ-IDs] | [count] |
+
+### Phase Details
+
+**Phase 1: [Name]**
+Goal: [goal]
+Requirements: [REQ-IDs]
+Success criteria:
+1. [criterion]
+2. [criterion]
+```
+
+**Ask for approval** via AskUserQuestion:
+- "Approve" — Commit and continue
+- "Adjust phases" — Tell me what to change
+- "Review full file" — Show raw ROADMAP.md
+
+**If "Adjust":** Get notes, re-spawn roadmapper with revision context, loop until approved.
+**If "Review":** Display raw ROADMAP.md, re-ask.
+
+**Commit roadmap** (after approval):
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" commit "docs: create project roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+```
+
+**Update lock file state:**
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-update --state="roadmap_created"
+```
+
+---
+
+## 9. Release Lock File
+
+**Project initialization complete:**
+
+```bash
+node "$HOME/.claude/ez-agents/bin/ez-tools.cjs" lock-release
+```
+
+---
+
+## 10. Done
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ EZ ► PROJECT INITIALIZED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Project: [Project Name]**
+
+| Artifact       | Location                    |
+|----------------|-----------------------------|
+| Project        | `.planning/PROJECT.md`      |
+| Research       | `.planning/research/`       |
+| Requirements   | `.planning/REQUIREMENTS.md` |
+| Roadmap        | `.planning/ROADMAP.md`      |
+| Config         | `.planning/config.json`     |
+
+**[N] phases** | **[X] requirements** | Ready to build ✓
+
+## ▶ Next Up
+
+**Phase 1: [Phase Name]** — [Goal]
+
+`/ez:discuss-phase 1` — gather context and clarify approach
+
+<sub>`/clear` first → fresh context window</sub>
+
+Also: `/ez:plan-phase 1` — skip discussion, plan directly
+```
+
+</process>
+
+<success_criteria>
+- [ ] Pre-flight health check passed (all systems go)
+- [ ] Lock file created and maintained throughout
+- [ ] PROJECT.md created with clear core value
+- [ ] REQUIREMENTS.md created with REQ-IDs
+- [ ] ROADMAP.md created with phased execution plan
+- [ ] STATE.md initialized
+- [ ] Config.json created with workflow preferences
+- [ ] Research completed (if selected) — 4 parallel agents with fresh context
+- [ ] Requirements gathered and scoped per category
+- [ ] ez-roadmapper spawned with stuck detection
+- [ ] Roadmap files written immediately (not draft)
+- [ ] User feedback incorporated (if any)
+- [ ] All commits made (if planning docs committed)
+- [ ] Lock file released on completion
+- [ ] User knows next step: `/ez:discuss-phase 1`
+
+**Atomic commits:** Each artifact committed immediately after creation.
+
+**GSD-2 Reliability:**
+- ✅ Health check pre-flight validation
+- ✅ Crash recovery via lock files
+- ✅ Fresh context per researcher/agent
+- ✅ Stuck detection with diagnostics during roadmap creation
+</success_criteria>