maxsimcli 3.5.3 → 3.7.0

package/dist/assets/templates/workflows/init-existing.md

@@ -0,0 +1,1099 @@
+<purpose>
+Initialize MAXSIM in an existing codebase through a scan-first-then-ask flow. This workflow detects existing `.planning/` state, runs codebase analysis (4 mapper agents), validates README against scan findings, asks scan-informed questions with smart defaults, and generates stage-aware planning documents. Supports `--auto` mode for fully autonomous initialization.
+
+Output: `.planning/` directory with config.json, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md, and codebase/ analysis docs.
+</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 all questions (conflict resolution, config, existing state, future direction, milestone)
+- Run full codebase scan (always)
+- Infer everything from code: purpose, stack, architecture, stage, vision
+- Auto mode does NOT require an idea document (unlike new-project's --auto)
+- Default config: stage=MVP, branching_strategy=none, model_profile=balanced, mode=yolo, depth=standard
+- After scan: generate all documents with smart inferences
+- Add `<!-- Auto-generated by /maxsim:init-existing --auto. Review recommended. -->` comment at top of each generated document
+- Auto mode still creates all documents: config.json, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
+- If `.planning/` exists: auto mode defaults to merge behavior (keep existing, fill gaps, re-scan)
+- If `.planning/` does not exist: create fresh
+</auto_mode>
+
+<process>
+
+## Step 1: Setup (Init Context)
+
+**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
+
+```bash
+INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init init-existing)
+```
+
+Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `mapper_model`, `commit_docs`, `project_exists`, `planning_exists`, `planning_files`, `has_codebase_map`, `has_existing_code`, `has_package_file`, `has_git`, `has_readme`, `conflict_detected`, `existing_file_count`, `brave_search_available`, `parallelization`, `project_path`, `codebase_dir`.
+
+**If `has_existing_code` is false AND `has_package_file` is false:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► NO CODE DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+No source code or package manifest detected in this directory.
+For greenfield projects, use /maxsim:new-project instead.
+```
+
+Use AskUserQuestion:
+- header: "Continue?"
+- question: "No code detected. Continue with init-existing anyway, or switch to new-project?"
+- options:
+  - "Continue anyway" -- I know there's code here (maybe in subdirectories)
+  - "Switch to /maxsim:new-project" -- This is a greenfield project
+
+**If "Switch":** Print "Run `/maxsim:new-project` to start a greenfield project." and exit.
+**If "Continue":** Proceed to Step 2.
+
+**In auto mode:** If no code detected, proceed anyway (scan will find what it can).
+
+**If `has_git` is false:** Initialize git:
+```bash
+git init
+```
+
+## Step 2: Conflict Resolution
+
+**If auto mode:** Skip dialog. If `conflict_detected`, use merge behavior automatically (keep existing files, fill gaps, always re-scan codebase). Proceed to Step 3.
+
+**If `conflict_detected` is false:** Create `.planning/` directory, proceed to Step 3:
+```bash
+mkdir -p .planning
+```
+
+**If `conflict_detected` is true:**
+
+Show existing files:
+```bash
+ls -la .planning/ 2>/dev/null
+```
+
+Present conflict dialog:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► EXISTING .planning/ DETECTED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Found {existing_file_count} files in .planning/:
+[list files with last-modified dates from ls output]
+
+How should I proceed?
+```
+
+Use AskUserQuestion:
+- header: "Conflict"
+- question: "`.planning/` already exists. How should I proceed?"
+- options:
+  - "Merge (Recommended)" -- Keep existing files, fill gaps, re-scan codebase
+  - "Overwrite" -- Delete existing .planning/ and start fresh
+  - "Cancel" -- Exit (run /maxsim:health to diagnose)
+
+**On Merge:**
+- Note which core files exist: config.json, PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
+- For each missing file: will be created in Step 9
+- For each existing file: check for required section headers in Step 9. If missing headers, fill gaps
+- Always re-scan codebase (Step 3 deletes and recreates `.planning/codebase/`)
+- Proceed to Step 3
+
+**On Overwrite:**
+
+Use AskUserQuestion:
+- header: "Backup"
+- question: "Back up existing .planning/ to .planning.bak/ before overwrite?"
+- options:
+  - "Yes (Recommended)" -- Save backup to .planning.bak/
+  - "No" -- Delete without backup
+
+If yes:
+```bash
+rm -rf .planning.bak/ 2>/dev/null
+mv .planning/ .planning.bak/
+mkdir -p .planning
+```
+
+If no:
+```bash
+rm -rf .planning/
+mkdir -p .planning
+```
+
+Proceed to Step 3.
+
+**On Cancel:**
+Print: "Cancelled. Run `/maxsim:health` to diagnose your .planning/ state."
+Exit workflow.
+
+## Step 3: Codebase Scan
+
+Always runs, regardless of conflict mode. The codebase scan is always fresh.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► SCANNING CODEBASE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Ensure `.planning/codebase/` exists (delete and recreate if exists):
+```bash
+rm -rf .planning/codebase/
+mkdir -p .planning/codebase/
+```
+
+```
+◆ Spawning 4 codebase mappers in parallel...
+  → Tech mapper (STACK.md)
+  → Architecture mapper (ARCHITECTURE.md)
+  → Quality mapper (CONVENTIONS.md)
+  → Concerns mapper (CONCERNS.md)
+```
+
+Spawn 4 mapper agents using the Task tool. Follow the EXACT pattern from `templates/workflows/map-codebase.md`.
+
+**CRITICAL:** Spawn mapper agents directly using the Task tool. Do NOT invoke `/maxsim:map-codebase` command (that would exit the current workflow context).
+
+**Agent 1: Tech Focus**
+
+```
+Task(
+  subagent_type="maxsim-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase tech stack",
+  prompt="Focus: tech
+
+Analyze this codebase for technology stack and external integrations.
+
+Write these documents to .planning/codebase/:
+- STACK.md - Languages, runtime, frameworks, dependencies, configuration
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only."
+)
+```
+
+**Agent 2: Architecture Focus**
+
+```
+Task(
+  subagent_type="maxsim-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase architecture",
+  prompt="Focus: arch
+
+Analyze this codebase architecture and directory structure.
+
+Write these documents to .planning/codebase/:
+- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only."
+)
+```
+
+**Agent 3: Quality Focus**
+
+```
+Task(
+  subagent_type="maxsim-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase conventions",
+  prompt="Focus: quality
+
+Analyze this codebase for coding conventions and testing patterns.
+
+Write these documents to .planning/codebase/:
+- CONVENTIONS.md - Code style, naming, patterns, error handling
+
+Explore thoroughly. Write documents directly using templates. Return confirmation only."
+)
+```
+
+**Agent 4: Concerns Focus**
+
+```
+Task(
+  subagent_type="maxsim-codebase-mapper",
+  model="{mapper_model}",
+  run_in_background=true,
+  description="Map codebase concerns",
+  prompt="Focus: concerns
+
+Analyze this codebase for technical debt, known issues, and areas of concern.
+
+Write this document to .planning/codebase/:
+- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
+
+Explore thoroughly. Write document directly using template. Return confirmation only."
+)
+```
+
+If `parallelization` is true, spawn all 4 with `run_in_background=true` (parallel). Otherwise spawn sequentially (no `run_in_background`).
+
+Wait for all agents to complete.
+
+Print per-agent completion status:
+```
+✓ Tech mapper complete: STACK.md
+✓ Architecture mapper complete: ARCHITECTURE.md
+✓ Quality mapper complete: CONVENTIONS.md
+✓ Concerns mapper complete: CONCERNS.md
+```
+
+After all agents complete, also create a file tree overview:
+
+```bash
+find . -type f | grep -v node_modules | grep -v .git | grep -v .planning | grep -v __pycache__ | grep -v .next | grep -v dist/ | grep -v build/ | head -200 > .planning/codebase/STRUCTURE.md
+```
+
+Then wrap it with a header:
+
+Read `.planning/codebase/STRUCTURE.md`, prepend:
+
+```markdown
+# Codebase File Structure
+
+**Generated:** [date]
+
+## File Tree
+
+```
+[file tree content]
+```
+
+---
+*Structure snapshot: [date]*
+```
+
+Verify all documents created:
+```bash
+ls -la .planning/codebase/
+wc -l .planning/codebase/*.md
+```
+
+If any document is missing or empty, note the failure and continue.
+
+## Step 4: README Validation
+
+**If `has_readme` is true:**
+
+Read README.md:
+```bash
+cat README.md
+```
+
+Read key scan findings from `.planning/codebase/STACK.md` and `.planning/codebase/ARCHITECTURE.md`.
+
+Compare README claims against scan findings. **Only flag clear contradictions:**
+- README says "React app" but code is all Python → flag
+- README describes features not visible in code → do NOT flag (different scopes are normal)
+- README mentions deprecated tech but code uses current versions → flag
+- README is empty or minimal → note for later (PROJECT.md will capture this)
+
+Store discrepancy notes in a variable for use in Steps 6 and 9.
+
+**If `has_readme` is false:** Skip. Note that no README exists for Step 9 context.
+
+## Step 5: Config Questions
+
+**If auto mode:** Skip. Use defaults and write config:
+```json
+{
+  "mode": "yolo",
+  "depth": "standard",
+  "parallelization": true,
+  "commit_docs": false,
+  "model_profile": "balanced",
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true
+  }
+}
+```
+
+Write `.planning/config.json` with defaults and proceed to Step 9 (document generation).
+
+**If interactive mode:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► CONFIGURATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Check for global defaults** at `~/.maxsim/defaults.json`. If the file exists, offer to use saved defaults:
+
+```
+AskUserQuestion([
+  {
+    question: "Use your saved default settings? (from ~/.maxsim/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 `~/.maxsim/defaults.json`, use those values, skip to **Write config.json** below.
+
+If "No" or defaults.json doesn't exist, ask:
+
+**Round 1 -- Core settings:**
+
+```
+AskUserQuestion([
+  {
+    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: "Depth",
+    question: "How thorough should planning be?",
+    multiSelect: false,
+    options: [
+      { label: "Quick", description: "Ship fast (3-5 phases, 1-3 plans each)" },
+      { label: "Standard (Recommended)", description: "Balanced scope and speed (5-8 phases, 3-5 plans each)" },
+      { label: "Comprehensive", description: "Thorough coverage (8-12 phases, 5-10 plans each)" }
+    ]
+  },
+  {
+    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" }
+    ]
+  }
+])
+```
+
+**Round 2 -- Git and branching:**
+
+Auto-detect branching strategy from git:
+```bash
+git branch -a 2>/dev/null
+```
+
+If feature/* or develop branches exist, suggest that strategy. Otherwise default to 'none'.
+
+```
+AskUserQuestion([
+  {
+    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 3 -- Workflow agents:**
+
+```
+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" }
+    ]
+  }
+])
+```
+
+**Write config.json:**
+
+```json
+{
+  "mode": "[yolo|interactive]",
+  "depth": "[quick|standard|comprehensive]",
+  "parallelization": true,
+  "commit_docs": [true|false],
+  "model_profile": "[quality|balanced|budget]",
+  "workflow": {
+    "research": [true|false],
+    "plan_check": [true|false],
+    "verifier": [true|false]
+  }
+}
+```
+
+**If commit_docs = No:** Add `.planning/` to `.gitignore`.
+
+Write `.planning/config.json`:
+```bash
+mkdir -p .planning
+```
+Use the Write tool to create `.planning/config.json`.
+
+## Step 6: Existing State Confirmation
+
+**If auto mode:** Skip. Use scan findings as-is. Proceed to Step 9.
+
+Read the scan outputs:
+```bash
+cat .planning/codebase/STACK.md
+cat .planning/codebase/ARCHITECTURE.md
+cat .planning/codebase/CONVENTIONS.md
+cat .planning/codebase/CONCERNS.md
+```
+
+Present scan findings as a "new developer onboarding overview":
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► CODEBASE SCAN COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+## Your Project
+
+**Purpose:** [Inferred from README + ARCHITECTURE.md analysis]
+**Tech Stack:** [From STACK.md -- e.g., React 18 + TypeScript 5.3, Express.js backend]
+**Architecture:** [From ARCHITECTURE.md -- e.g., Monorepo with 3 packages]
+**Key Patterns:** [From CONVENTIONS.md -- e.g., repository pattern, React hooks]
+**Known Concerns:** [From CONCERNS.md -- e.g., 12 TODOs, no auth test coverage]
+
+Confidence: ~85% -- some inferences may need correction.
+```
+
+Include confidence qualifiers for uncertain findings:
+- Stack detection from package.json = HIGH confidence
+- Architecture inference from file structure = MEDIUM confidence
+- Purpose inference from README = MEDIUM-HIGH confidence
+- Pattern inference from code sampling = MEDIUM confidence
+
+If README discrepancies were found in Step 4, flag them:
+```
+Warning: README Discrepancy: Your README describes [X] but the code implements [Y]. Which is current?
+```
+
+Ask user to confirm or correct via AskUserQuestion:
+- header: "Scan"
+- question: "Does this look right? Correct anything that's wrong."
+- options:
+  - "Looks correct" -- Proceed with these findings
+  - "Some corrections" -- Let me fix some details
+
+If "Some corrections": ask "What needs correcting?" (freeform), capture corrections, apply to working context.
+
+## Step 7: Future Direction Questions
+
+**If auto mode:** Skip. Generate generic "continue development" goals. Proceed to Step 9.
+
+Ask these questions sequentially using AskUserQuestion:
+
+**Question 1: Pain Points**
+
+Use AskUserQuestion:
+- header: "Pain Points"
+- question: "What pain points or issues brought you to MAXSIM?"
+- options:
+  - "Codebase complexity" -- Hard to track what's where, need structure
+  - "No planning" -- Building ad-hoc, want a roadmap
+  - "Tech debt" -- Need organized approach to cleanup
+  - "New features" -- Want to add features systematically
+  - "Other" -- Let me explain
+
+If "Other": capture freeform response.
+
+**Question 2: Project Stage**
+
+Infer default from scan: tests exist + CI config = production; some tests = MVP; no tests = prototype.
+
+Use AskUserQuestion:
+- header: "Stage"
+- question: "What stage is your project in?"
+- options:
+  - "Prototype" -- Early exploration, things change rapidly
+  - "MVP" -- Core features working, refining toward release
+  - "Production" -- Users depend on it, stability matters
+  - "Maintenance" -- Stable, focused on fixes and incremental improvements
+
+**Question 3: Production Sub-Questions (only if stage = Production or Maintenance)**
+
+If the user selected Production or Maintenance:
+
+Use AskUserQuestion:
+- header: "Constraints"
+- question: "What absolutely cannot be broken? (These become MUST NOT requirements)"
+- options:
+  - "Let me describe" -- I'll list specific things
+
+Capture their response (freeform). These become MUST NOT entries in REQUIREMENTS.md.
+
+Use AskUserQuestion:
+- header: "Deployment"
+- question: "Deployment requirements?"
+- options:
+  - "Zero-downtime required" -- Can't take the service down for deploys
+  - "Downtime OK" -- Brief maintenance windows are acceptable
+  - "No deployments planned" -- Not deploying changes to production
+
+Use AskUserQuestion:
+- header: "Staging"
+- question: "Do you have a staging environment?"
+- options:
+  - "Yes" -- Changes go through staging first
+  - "No" -- Deploy directly to production
+  - "Partial" -- Some things have staging, others don't
+
+Use AskUserQuestion:
+- header: "Rollback"
+- question: "Is a rollback plan needed for changes?"
+- options:
+  - "Yes" -- Must be able to undo any change quickly
+  - "No" -- Forward-fix is acceptable
+  - "Depends" -- For some changes yes, others no
+
+**Question 4: General Constraints**
+
+Use AskUserQuestion:
+- header: "Limits"
+- question: "What constraints should I know about? (deadlines, backward compatibility, things that can't change)"
+- options:
+  - "No major constraints" -- Flexible on approach
+  - "Some constraints" -- Let me describe them
+
+If "Some constraints": capture freeform response.
+
+**Question 5: Missing Context**
+
+Use AskUserQuestion:
+- header: "Context"
+- question: "Is there anything the scan may have missed? (external integrations, business rules, organizational constraints)"
+- options:
+  - "Scan covered it" -- Nothing major missing
+  - "Yes, some things" -- Let me add context
+
+If "Yes, some things": capture freeform response.
+
+**Question 6: Vision**
+
+Ask inline (freeform, NOT AskUserQuestion):
+
+"What is your vision for this project? What are you trying to build? No time horizon needed -- just purpose and direction."
+
+Wait for response.
+
+## Step 8: Milestone Suggestion
+
+**If auto mode:** Generate a milestone name from the inferred project purpose. Proceed to Step 9.
+
+Synthesize all gathered information and suggest a first milestone:
+
+```
+Based on what you have and where you're going, I'd suggest:
+
+**Milestone: [Suggested Name]**
+Reasoning: [Why this milestone makes sense given current state and goals]
+```
+
+Use AskUserQuestion:
+- header: "Milestone"
+- question: "Does this milestone name work?"
+- options:
+  - "Yes" -- Use this name
+  - "Rename" -- I have a different name in mind
+
+If "Rename": ask "What would you like to call it?" (freeform), capture response.
+
+## Step 9: Document Generation
+
+Generate all planning documents. In merge mode, check if each file exists first. For existing files, check for required section headers. If a required header is missing, add the section. If present, leave it. For missing files, create from scratch.
+
+**Merge mode section-detection rules:**
+- PROJECT.md: required headers `## Core Value`, `## Key Decisions`
+- REQUIREMENTS.md: required headers `## Requirements` (or `## v1` / `## v2` etc.)
+- ROADMAP.md: required headers `## Phases`, `## Progress`
+- STATE.md: required headers `## Current Position`, `## Accumulated Context`
+
+If a required header is missing from an existing file, add the section at the end. If present, leave the file as-is.
+
+### 9a: PROJECT.md
+
+**Skip if merge mode and file exists with all required headers.**
+
+Use template from `templates/project.md` as base. Fill in:
+
+**Standard sections:**
+- Project name (from README or directory name)
+- What This Is (from scan findings + README + user corrections)
+- Core Value (inferred from scan purpose or user's vision)
+- Requirements section (initial Active requirements from user goals)
+- Context section (technical environment from scan)
+- Constraints (from production sub-questions + general constraints)
+- Key Decisions table (from config choices + user decisions)
+
+**Extra sections for existing projects (per CONTEXT.md Decision 4):**
+
+Add these AFTER the standard sections:
+
+```markdown
+## Current State Summary
+
+[Condensed scan findings as onboarding overview for future agents.
+Include: tech stack, architecture pattern, key design patterns, current capabilities.]
+
+## Known Risks / Tech Debt
+
+[From CONCERNS.md + user additions from Step 7.
+Format as actionable list with severity indicators.]
+
+## Codebase Analysis
+
+Detailed codebase analysis available in:
+- `.planning/codebase/STACK.md` -- Technology stack
+- `.planning/codebase/ARCHITECTURE.md` -- Architecture patterns
+- `.planning/codebase/CONVENTIONS.md` -- Code conventions
+- `.planning/codebase/CONCERNS.md` -- Known issues and tech debt
+- `.planning/codebase/STRUCTURE.md` -- File tree overview
+```
+
+If README discrepancies were found in Step 4:
+```markdown
+## README Validation Note
+
+README may be outdated in the following areas:
+- [discrepancy 1]
+- [discrepancy 2]
+Consider updating README to reflect current state.
+```
+
+If no discrepancies, omit this section.
+
+**If auto mode:** Add at top of file:
+```markdown
+<!-- Auto-generated by /maxsim:init-existing --auto. Review recommended. -->
+```
+
+### 9b: REQUIREMENTS.md
+
+**Skip if merge mode and file exists with all required headers.**
+
+Use stage-aware format per CONTEXT.md Decision 4:
+
+**Prototype stage:**
+```markdown
+# Requirements: [Project Name]
+
+**Defined:** [date]
+**Core Value:** [from PROJECT.md]
+**Stage:** Prototype
+
+## Requirements
+
+Lightweight requirements for rapid exploration.
+
+- [ ] [Goal 1 -- informal description]
+- [ ] [Goal 2 -- informal description]
+- [ ] [Goal 3 -- informal description]
+
+## Out of Scope
+
+- [Exclusion] -- [reason]
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| [Goal 1] | Phase 1 | Pending |
+
+---
+*Requirements defined: [date]*
+```
+
+**MVP stage:**
+```markdown
+# Requirements: [Project Name]
+
+**Defined:** [date]
+**Core Value:** [from PROJECT.md]
+**Stage:** MVP
+
+## v1 Requirements
+
+User stories for initial release.
+
+### [Category 1]
+
+- [ ] **[CAT]-01**: As a user, I can [action] so that [benefit]
+- [ ] **[CAT]-02**: As a user, I can [action] so that [benefit]
+
+### [Category 2]
+
+- [ ] **[CAT]-01**: As a user, I can [action] so that [benefit]
+
+## v2 Requirements
+
+Deferred to future release.
+
+- **[CAT]-01**: [description]
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| [Feature] | [Why excluded] |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| [CAT]-01 | Phase 1 | Pending |
+
+**Coverage:**
+- v1 requirements: [X] total
+- Mapped to phases: [Y]
+- Unmapped: [Z]
+
+---
+*Requirements defined: [date]*
+```
+
+**Production stage:**
+```markdown
+# Requirements: [Project Name]
+
+**Defined:** [date]
+**Core Value:** [from PROJECT.md]
+**Stage:** Production
+
+## v1 Requirements
+
+Formal acceptance criteria with stability guards.
+
+### [Category 1]
+
+- [ ] **[CAT]-01**: [Specific, testable requirement]
+  - Acceptance: [measurable criterion]
+- [ ] **[CAT]-02**: [Specific, testable requirement]
+  - Acceptance: [measurable criterion]
+
+### Stability Guards
+
+These are MUST NOT requirements derived from production constraints:
+
+- [ ] **GUARD-01**: MUST NOT break [critical thing from production sub-questions]
+- [ ] **GUARD-02**: MUST NOT cause downtime during [operation]
+- [ ] **GUARD-03**: MUST NOT remove backward compatibility with [system]
+
+## v2 Requirements
+
+- **[CAT]-01**: [description]
+
+## Out of Scope
+
+| Feature | Reason |
+|---------|--------|
+| [Feature] | [Why excluded] |
+
+## Traceability
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| [CAT]-01 | Phase 1 | Pending |
+| GUARD-01 | All phases | Active |
+
+**Coverage:**
+- v1 requirements: [X] total
+- Guards: [Y] total
+- Mapped to phases: [Z]
+
+---
+*Requirements defined: [date]*
+```
+
+**Maintenance stage:** Same as Production format with additional stability focus:
+```markdown
+### Maintenance Focus
+
+- [ ] **MAINT-01**: All existing tests continue to pass after changes
+- [ ] **MAINT-02**: No regression in [critical metric]
+```
+
+**If auto mode:** Add at top of file:
+```markdown
+<!-- Auto-generated by /maxsim:init-existing --auto. Review recommended. -->
+```
+
+### 9c: ROADMAP.md
+
+**Skip if merge mode and file exists with all required headers.**
+
+Use template from `templates/roadmap.md`.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► CREATING ROADMAP
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+◆ Spawning roadmapper...
+```
+
+Spawn the `maxsim-roadmapper` agent via Task tool to generate the roadmap:
+
+```
+Task(prompt="
+<planning_context>
+
+<files_to_read>
+- .planning/PROJECT.md (Project context)
+- .planning/REQUIREMENTS.md (Requirements)
+- .planning/config.json (Depth and mode settings)
+</files_to_read>
+
+<scan_context>
+The project is an EXISTING codebase being initialized. Scan findings summary:
+
+**Tech Stack:** [from STACK.md]
+**Architecture:** [from ARCHITECTURE.md]
+**Key Patterns:** [from CONVENTIONS.md]
+**Known Concerns:** [from CONCERNS.md]
+</scan_context>
+
+<user_context>
+**Vision:** [user's vision from Step 7, or inferred from scan in auto mode]
+**Pain Points:** [from Step 7]
+**Stage:** [prototype/MVP/production/maintenance]
+**Milestone:** [suggested milestone name from Step 8]
+</user_context>
+
+</planning_context>
+
+<instructions>
+Create roadmap for an EXISTING project:
+1. Derive 3-5 concrete suggested phases based on actual scan findings and stated goals
+2. NO TBD placeholder phases -- every phase must be specific and actionable
+3. Map every v1 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
+
+This is an existing project -- phases should address real found issues and user goals,
+not generic setup phases. The codebase already exists.
+
+Write files first, then return. This ensures artifacts persist even if context is lost.
+</instructions>
+", subagent_type="maxsim-roadmapper", model="{roadmapper_model}", description="Create roadmap for existing project")
+```
+
+**Handle roadmapper return:**
+
+**If `## ROADMAP BLOCKED`:**
+- Present blocker information
+- Work with user to resolve
+- Re-spawn when resolved
+
+**If `## ROADMAP CREATED`:**
+
+Read the created ROADMAP.md and present it inline:
+
+```
+## Proposed Roadmap
+
+**[N] phases** | **[X] requirements mapped** | All v1 requirements covered
+
+| # | Phase | Goal | Requirements |
+|---|-------|------|--------------|
+| 1 | [Name] | [Goal] | [REQ-IDs] |
+| 2 | [Name] | [Goal] | [REQ-IDs] |
+| 3 | [Name] | [Goal] | [REQ-IDs] |
+```
+
+**If auto mode:** Skip approval gate. Proceed to Step 9d.
+
+**If interactive mode:**
+
+Use AskUserQuestion:
+- header: "Roadmap"
+- question: "Does this roadmap structure work for you?"
+- options:
+  - "Approve" -- Commit and continue
+  - "Adjust phases" -- Tell me what to change
+  - "Review full file" -- Show raw ROADMAP.md
+
+If "Approve": continue.
+If "Adjust phases": get feedback, re-spawn roadmapper with revision context, re-present. Loop until approved.
+If "Review full file": display raw `cat .planning/ROADMAP.md`, then re-ask.
+
+### 9d: STATE.md
+
+**Skip if merge mode and file exists with all required headers.**
+
+If the roadmapper already created STATE.md (it usually does), verify it exists. If not, create using template from `templates/state.md`.
+
+Pre-populate:
+- **Project Reference:** Core value from PROJECT.md, current focus = Phase 1
+- **Current Position:** Phase 1 of [N], ready to plan
+- **Decisions section:** Add constraints as decisions (e.g., "Must maintain backward compatibility with API v1")
+- **Blockers section:** Add known tech debt and risks from CONCERNS.md as blockers
+
+**If auto mode:** Add at top of file:
+```markdown
+<!-- Auto-generated by /maxsim:init-existing --auto. Review recommended. -->
+```
+
+### 9e: config.json
+
+Already written in Step 5. If merge mode and config.json existed, it was preserved (unless user chose overwrite).
+
+## Step 10: Git Stage and Summary
+
+Stage all changed files:
+```bash
+git add .planning/
+```
+
+If `commit_docs` is true:
+```bash
+git commit -m "docs: initialize MAXSIM in existing project via /maxsim:init-existing"
+```
+
+Print structured summary:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► INITIALIZATION COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Created:
+  ✓ .planning/config.json         -- Workflow preferences
+  ✓ .planning/PROJECT.md          -- Project context + current state
+  ✓ .planning/REQUIREMENTS.md     -- [Stage]-format requirements
+  ✓ .planning/ROADMAP.md          -- [Milestone name] + [N] phases
+  ✓ .planning/STATE.md            -- Pre-populated project memory
+  ✓ .planning/codebase/           -- Full codebase analysis (4 docs + structure)
+```
+
+If auto mode, append:
+```
+Documents were auto-generated from codebase analysis. Review recommended before starting execution.
+```
+
+Print next steps:
+
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Phase 1: [Phase Name]** -- [Goal from ROADMAP.md]
+
+/maxsim:plan-phase 1 -- plan the first phase
+
+<sub>/clear first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- /maxsim:roadmap -- review the generated roadmap
+- /maxsim:progress -- see project status
+
+───────────────────────────────────────────────────────────────
+```
+
+**End of workflow.**
+
+</process>
+
+<output>
+
+- `.planning/config.json`
+- `.planning/PROJECT.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/ROADMAP.md`
+- `.planning/STATE.md`
+- `.planning/codebase/STACK.md`
+- `.planning/codebase/ARCHITECTURE.md`
+- `.planning/codebase/CONVENTIONS.md`
+- `.planning/codebase/CONCERNS.md`
+- `.planning/codebase/STRUCTURE.md`
+
+</output>
+
+<success_criteria>
+
+- [ ] .planning/ directory created (or merged)
+- [ ] Git repo initialized (if not already)
+- [ ] Conflict detection completed (merge/overwrite/cancel dialog)
+- [ ] Codebase scan completed (4 mapper agents spawned)
+- [ ] README validated against scan findings
+- [ ] Config questions answered (or auto-defaulted)
+- [ ] Existing state presented and confirmed (or auto-inferred)
+- [ ] Future direction gathered (pain points, stage, constraints, vision)
+- [ ] Production sub-questions asked (if production/maintenance stage)
+- [ ] Milestone suggested and confirmed
+- [ ] PROJECT.md created with brownfield extra sections
+- [ ] REQUIREMENTS.md created with stage-aware format
+- [ ] ROADMAP.md created with 3-5 concrete phases (no TBD)
+- [ ] STATE.md created with pre-populated decisions and blockers
+- [ ] config.json created with workflow settings
+- [ ] .planning/codebase/ populated with scan documents
+- [ ] Git staging completed
+- [ ] Structured summary printed
+- [ ] Next steps suggested: /maxsim:roadmap then /maxsim:plan-phase 1
+
+**Auto mode criteria:**
+- [ ] All questions skipped
+- [ ] Smart defaults applied
+- [ ] All documents flagged as auto-generated
+- [ ] Review recommendation printed
+
+**Merge mode criteria:**
+- [ ] Existing files preserved where complete
+- [ ] Missing files created
+- [ ] Incomplete files had gaps filled
+- [ ] Codebase always re-scanned
+
+**Atomic commits:** Each artifact committed if commit_docs is true.
+
+</success_criteria>