maxsimcli 5.0.6 → 5.1.0

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

@@ -1,1496 +1,303 @@
 <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.
+Initialize MAXSIM in an existing project with code. Performs a deep parallel codebase scan first, synthesizes findings, confirms with the user, then proceeds with GitHub setup and config. GitHub Issues are the sole source of truth — no local .planning/ directory is created or referenced.
 </purpose>
 
-<required_reading>
-Read all files referenced by the invoking prompt's execution_context before starting.
-@~/.claude/maxsim/references/thinking-partner.md
-@~/.claude/maxsim/references/questioning.md
-</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 --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:**
-
-**If `INIT_CONTEXT` was already loaded by the router** (the init.md workflow runs this before delegating), use that JSON directly — do NOT re-run the CLI command.
+## Phase 1: Prerequisites Gate
 
-**Otherwise**, run:
+Before any user interaction, verify GitHub is accessible.
 
 ```bash
-INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init init-existing)
+gh auth status 2>/dev/null && echo "AUTH_OK" || echo "AUTH_FAIL"
+git remote get-url origin 2>/dev/null && echo "REMOTE_OK" || echo "REMOTE_FAIL"
 ```
 
-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`, `github_ready`, `has_github_remote`, `gh_authenticated`.
-
-**If `has_existing_code` is false AND `has_package_file` is false:**
+**If AUTH_FAIL:**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► NO CODE DETECTED
+ MAXSIM ► GITHUB CLI NOT AUTHENTICATED
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-No source code or package manifest detected in this directory.
-For greenfield projects, use /maxsim:init 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:init" -- This is a greenfield project
+MAXSIM requires GitHub CLI authentication.
 
-**If "Switch":** Print "Run `/maxsim:init` to start a greenfield project." and exit.
-**If "Continue":** Proceed to Step 2.
+Fix: gh auth login
 
-**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
+Then re-run /maxsim:init.
 ```
 
-## Step 1b: GitHub Prerequisites Gate
-
-**This gate is MANDATORY. Do not proceed if it fails.**
-
-Parse init context for `has_github_remote` and `gh_authenticated`:
-
-1. If `has_github_remote` is false:
-   - STOP. Tell user:
-     ```
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      MAXSIM ► NO GITHUB REMOTE FOUND
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Stop. Do not proceed.
 
-     MAXSIM requires a GitHub remote to track phases as Issues.
-
-     To fix: git remote add origin <your-repo-url>
-
-     Then re-run /maxsim:init.
-     ```
-   - Do NOT proceed with initialization.
-
-2. If `gh_authenticated` is false:
-   - STOP. Tell user:
-     ```
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-      MAXSIM ► GITHUB CLI NOT AUTHENTICATED
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-     MAXSIM requires GitHub CLI authentication to create phase issues.
-
-     To fix: gh auth login
-
-     Then re-run /maxsim:init.
-     ```
-   - Do NOT proceed with initialization.
-
-3. Both checks passed — run `github setup` with the project name as the milestone title:
-   ```bash
-   node ~/.claude/maxsim/bin/maxsim-tools.cjs github setup --milestone-title "[project name]"
-   ```
-
-4. If `github setup` fails:
-   - STOP with the error message returned by the tool.
-   - Do not fall back to local-only mode.
-
-5. Record the `project_number` and board details returned by `github setup` for use in the Phase Issue Creation step.
-
-## 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:
+**If REMOTE_FAIL:**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► EXISTING .planning/ DETECTED
+ MAXSIM ► NO GITHUB REMOTE FOUND
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-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:progress (health check) 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
+MAXSIM requires a GitHub remote to track phases as Issues.
 
-**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
+Fix: git remote add origin <url>
 
-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
+Then re-run /maxsim:init.
 ```
 
-Proceed to Step 3.
+Stop. Do not proceed.
 
-**On Cancel:**
-Print: "Cancelled. Run `/maxsim:progress (health check)` to diagnose your .planning/ state."
-Exit workflow.
+## Phase 2: Deep Codebase Scan
 
-## 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/
-```
+Print immediately:
 
 ```
-◆ Spawning 4 codebase mappers in parallel...
-  → Tech mapper (STACK.md)
-  → Architecture mapper (ARCHITECTURE.md)
-  → Quality mapper (CONVENTIONS.md)
-  → Concerns mapper (CONCERNS.md)
+Scanning existing codebase...
 ```
 
-Spawn 4 mapper agents using the Task tool. Follow the EXACT pattern from `templates/workflows/map-codebase.md`.
+Spawn 10+ parallel Research agents to deeply analyze the codebase. Use the Agent tool with `isolation: "worktree"` and `run_in_background: true` for all agents simultaneously.
 
-**CRITICAL:** Spawn mapper agents directly using the Task tool. Do NOT invoke `/maxsim:init (codebase mapping stage)` command (that would exit the current workflow context).
+**Agent 1 — Architecture overview:**
+Prompt: "Analyze the top-level structure of this repository. List all top-level directories (exclude .git, node_modules, vendor, dist, build). Identify the architectural pattern: monorepo, monolith, microservices, library, CLI tool, web app, mobile app, or hybrid. Identify the primary entry point(s). Return JSON with keys: top_level_dirs (array), architecture_pattern (string), entry_points (array), notable_structure_notes (string)."
 
-**Agent 1: Tech Focus**
+**Agent 2 — Language and framework detection:**
+Prompt: "Detect all programming languages used in this repository (by file extension frequency). Identify the primary framework(s): React, Vue, Express, Django, Rails, Spring, etc. Read package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, or equivalent manifest. Return JSON with keys: primary_language (string), secondary_languages (array), frameworks (array), runtime_version (string), project_name (string), project_version (string)."
 
-```
-Task(
-  subagent_type="researcher",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase tech stack",
-  prompt="Focus: tech
+**Agent 3 — Dependency analysis:**
+Prompt: "Read the package manifest (package.json, requirements.txt, pyproject.toml, Cargo.toml, go.mod, etc.). List the top 15 production dependencies and top 10 dev dependencies. Flag any dependencies that are outdated, deprecated, or have known security advisories if detectable from lock files. Return JSON with keys: prod_deps (array of {name, version}), dev_deps (array of {name, version}), flags (array of {name, issue})."
 
-Analyze this codebase for technology stack and external integrations.
+**Agent 4 — Test coverage and quality:**
+Prompt: "Find all test files in this repository (*.test.*, *.spec.*, tests/, __tests__/, spec/). Count them. Identify the test framework(s). Look for coverage config or reports. Check if tests are passing by reading CI status files or recent CI output if present. Return JSON with keys: test_file_count (number), test_frameworks (array), coverage_tool (string or null), coverage_percent (number or null), test_patterns (array), test_quality_notes (string)."
 
-Write these documents to .planning/codebase/:
-- STACK.md - Languages, runtime, frameworks, dependencies, configuration
+**Agent 5 — CI/CD pipeline:**
+Prompt: "Read .github/workflows/, .circleci/config.yml, .gitlab-ci.yml, Jenkinsfile, .travis.yml, or equivalent CI config. Identify all workflow triggers, jobs, test commands, build commands, and deployment targets. Note any broken or disabled workflows. Return JSON with keys: ci_provider (string), workflows (array of {name, triggers, jobs}), test_commands (array), build_commands (array), deploy_targets (array), broken_workflows (array)."
 
-Explore thoroughly. Write documents directly using templates. Return confirmation only."
-)
-```
+**Agent 6 — Code quality and linting:**
+Prompt: "Read .eslintrc*, .prettierrc*, pyproject.toml [tool.ruff or tool.black], .rubocop.yml, .golangci.yml, or equivalent lint/format config. Identify the linter, formatter, and key enforced rules. Check if pre-commit hooks are configured (.pre-commit-config.yaml or .husky/). Return JSON with keys: linter (string), formatter (string), key_rules (array), pre_commit_configured (boolean), lint_notes (string)."
 
-**Agent 2: Architecture Focus**
+**Agent 7 — Database and data layer:**
+Prompt: "Look for ORM configs, migration files (migrations/, db/migrate/, alembic/), schema files (schema.prisma, schema.sql), or database connection setup. Identify: database type (postgres, mysql, sqlite, mongodb, etc.), ORM or query builder, migration tool, and key schema entities. Return JSON with keys: db_type (string or null), orm (string or null), migration_tool (string or null), schema_entities (array of string), data_notes (string)."
 
-```
-Task(
-  subagent_type="researcher",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase architecture",
-  prompt="Focus: arch
+**Agent 8 — Environment and configuration:**
+Prompt: "Read .env.example, .env.sample, .env.template, or any documented environment variable files (do NOT read actual .env files with real secrets). List all documented environment variables and their purpose. Also check for config management patterns (dotenv, 12-factor, secrets managers). Return JSON with keys: env_vars (array of {name, description, required}), config_pattern (string), config_notes (string)."
 
-Analyze this codebase architecture and directory structure.
+**Agent 9 — Deployment and infrastructure:**
+Prompt: "Look for Dockerfile, docker-compose.yml, Kubernetes manifests (k8s/, kubernetes/), Terraform (.tf files), AWS CDK, Pulumi, or serverless.yml. Identify: whether the app is containerized, the orchestration approach, cloud provider, and infrastructure-as-code tool. Return JSON with keys: containerized (boolean), base_image (string or null), orchestration (string or null), cloud_provider (string or null), iac_tool (string or null), deploy_notes (string)."
 
-Write these documents to .planning/codebase/:
-- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
+**Agent 10 — Tech debt and open work:**
+Prompt: "Search source files for TODO, FIXME, HACK, XXX, and DEPRECATED comments. Count occurrences per file. List the top 10 files by comment count. Also run: gh issue list --state open --json number,title,labels,createdAt to get open GitHub issues. Return JSON with keys: todo_files (array of {file, count}), total_todos (number), open_issues (array of {number, title, labels}), debt_notes (string)."
 
-Explore thoroughly. Write documents directly using templates. Return confirmation only."
-)
-```
+**Agent 11 — API surface (if applicable):**
+Prompt: "Look for route definitions, API endpoint declarations, OpenAPI/Swagger specs, GraphQL schemas, or gRPC proto files. Summarize the API surface: how many endpoints/operations, authentication mechanism, versioning strategy. Return JSON with keys: api_type (rest/graphql/grpc/none), endpoint_count (number or null), auth_mechanism (string or null), api_version (string or null), spec_file (string or null), api_notes (string)."
 
-**Agent 3: Quality Focus**
+**Agent 12 — Documentation state:**
+Prompt: "Check for: README.md (and its completeness), docs/ directory, wiki link in repo metadata, inline code comments density (sample 5 files), CHANGELOG.md, ADR records (docs/adr/ or similar). Return JSON with keys: has_readme (boolean), readme_quality (poor/basic/good/comprehensive), has_docs_dir (boolean), has_changelog (boolean), has_adrs (boolean), doc_notes (string)."
 
-```
-Task(
-  subagent_type="researcher",
-  model="{mapper_model}",
-  run_in_background=true,
-  description="Map codebase conventions",
-  prompt="Focus: quality
+After all agents complete, synthesize all JSON outputs into a single `SCAN_FINDINGS` object covering: architecture, languages, frameworks, dependencies, test coverage, CI/CD, code quality, database, environment, deployment, tech debt, API surface, and documentation state.
 
-Analyze this codebase for coding conventions and testing patterns.
+## Phase 3: Findings Presentation and Confirmation
 
-Write these documents to .planning/codebase/:
-- CONVENTIONS.md - Code style, naming, patterns, error handling
+Present synthesized findings to the user:
 
-Explore thoroughly. Write documents directly using templates. Return confirmation only."
-)
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ MAXSIM ► CODEBASE SCAN COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-**Agent 4: Concerns Focus**
+Architecture:   {architecture_pattern}
+Language:       {primary_language} ({secondary_languages})
+Frameworks:     {frameworks}
+Tests:          {test_file_count} files | {coverage_percent}% coverage | {test_frameworks}
+CI/CD:          {ci_provider} — {workflow count} workflows
+Database:       {db_type} via {orm}
+Tech debt:      {total_todos} TODOs | {open_issues count} open issues
+API:            {api_type} — {endpoint_count} endpoints
+Docs:           README: {readme_quality} | Changelog: {has_changelog}
 
+Deploy:         {containerized} | {cloud_provider} | {iac_tool}
 ```
-Task(
-  subagent_type="researcher",
-  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."
-)
-```
+Use AskUserQuestion:
+- header: "Scan Results — Confirm or Correct"
+- questions:
+  1. "Does this look accurate? What should be corrected?" (freeform, optional)
+  2. "What is the primary goal of this project — what problem does it solve?" (freeform)
+  3. "What are the no-gos — things MAXSIM agents must never touch or modify?" (freeform)
+  4. "What are the acceptance criteria for the next milestone?" (freeform)
 
-If `parallelization` is true, spawn all 4 with `run_in_background=true` (parallel). Otherwise spawn sequentially (no `run_in_background`).
+Incorporate any corrections into `PROJECT_CONTEXT`.
 
-Wait for all agents to complete.
+## Phase 4: GitHub Setup
 
-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
-```
+Execute in sequence:
 
-After all agents complete, also create a file tree overview:
+**4a. Ensure labels:**
 
 ```bash
-git ls-files --others --cached --exclude-standard | grep -v node_modules | grep -v __pycache__ | grep -v .next | grep -v dist/ | grep -v build/ | head -200 > .planning/codebase/STRUCTURE.md
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github ensure-labels
 ```
 
-Then wrap it with a header:
+**4b. Create GitHub Project Board:**
 
-Read `.planning/codebase/STRUCTURE.md`, prepend:
-
-```markdown
-# Codebase File Structure
-
-**Generated:** [date]
-
-## File Tree
+```bash
+REPO=$(gh repo view --json owner,name -q '"\(.owner.login)/\(.name)"')
+OWNER=$(gh repo view --json owner -q '.owner.login')
+PROJECT_NAME="{project_name} — MAXSIM"
 
-```
-[file tree content]
+gh project create --owner "$OWNER" --title "$PROJECT_NAME"
 ```
 
----
-*Structure snapshot: [date]*
-```
+Capture the project number.
+
+**4c. Store project board number:**
 
-Verify all documents created:
 ```bash
-ls -la .planning/codebase/
-wc -l .planning/codebase/*.md
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github set-project --number {PROJECT_NUMBER}
 ```
 
-If any document is missing or empty, note the failure and continue.
+**4d. Create initial milestone:**
 
-## Step 4: README Validation
-
-**If `has_readme` is true:**
-
-Read README.md:
 ```bash
-cat README.md
+gh api repos/$REPO/milestones \
+  --method POST \
+  --field title="Milestone 1 — {project_name}" \
+  --field description="Initial milestone created by MAXSIM" \
+  --field state="open"
 ```
 
-Read key scan findings from `.planning/codebase/STACK.md` and `.planning/codebase/ARCHITECTURE.md`.
+Capture the milestone number.
 
-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)
+## Phase 5: Local Setup
 
-Store discrepancy notes in a variable for use in Steps 6 and 9.
+**5a. Write .claude/maxsim/config.json:**
 
-**If `has_readme` is false:** Skip. Note that no README exists for Step 9 context.
+Create `.claude/maxsim/config.json` with:
 
-## 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_checker": 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" }
-    ]
+  "version": "6",
+  "project_name": "{project_name}",
+  "description": "{description}",
+  "architecture": "{architecture_pattern}",
+  "tech_stack": ["{primary_language}", "{frameworks}"],
+  "testing": {
+    "frameworks": ["{test_frameworks}"],
+    "coverage_percent": {coverage_percent}
   },
-  {
-    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" }
-    ]
+  "ci_provider": "{ci_provider}",
+  "database": "{db_type}",
+  "no_gos": ["{no_go items}"],
+  "acceptance_criteria": "{acceptance_criteria}",
+  "github": {
+    "repo": "{owner/repo}",
+    "project_number": {PROJECT_NUMBER},
+    "milestone_number": {MILESTONE_NUMBER}
   },
-  {
-    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_checker": [true|false],
-    "verifier": [true|false]
-  }
+  "scan_date": "{ISO timestamp}",
+  "initialized_at": "{ISO timestamp}"
 }
 ```
 
-**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.
+**5b. Write or update CLAUDE.md:**
 
-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.
-
-Apply thinking-partner behaviors when presenting findings:
-- **Surface unstated assumptions** — "The scan assumes X is your primary framework — is that accurate?"
-- **Make consequences visible** — "Your architecture pattern means Y for future phases."
-- **Propose alternatives** — If concerns were found, suggest approaches: "The scan found tech debt in Z. We could address it early or defer — here are the trade-offs."
-
-## Step 6b: Stack Preference Questions
-
-**If auto mode:** Skip. Use all detected technologies as-is (keep all). Proceed to Step 6c.
-
-Read `.planning/codebase/STACK.md` and extract architecturally significant dependencies.
-
-**Filter to only framework-level choices:**
-- Framework (React, Next.js, Express, Django, etc.)
-- Database (PostgreSQL, MongoDB, Redis, etc.)
-- ORM/Query builder (Drizzle, Prisma, SQLAlchemy, etc.)
-- State management (Redux, Zustand, Vuex, etc.)
-- Testing framework (Vitest, Jest, pytest, etc.)
-- Build tools (Vite, Webpack, tsup, etc.)
-
-**Explicitly EXCLUDE:**
-- Utility libraries (lodash, uuid, date-fns, etc.)
-- Dev tools (prettier, eslint, biome, etc.)
-- Type definitions (@types/*)
-- Runtime dependencies that are implementation details
-
-**Cap at 8-10 items max** to avoid overwhelming the user.
-
-Present to user:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► STACK PREFERENCES
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Your codebase uses these key technologies. For each, do you want to keep, evolve, or replace?
-```
-
-For each significant dependency, use AskUserQuestion:
-- header: "[Technology Name]"
-- question: "[Technology] [version] -- [detected purpose]"
-- options:
-  - "Keep" -- Continue using [Technology] as-is
-  - "Evolve" -- Upgrade or modernize (describe target)
-  - "Replace" -- Switch to alternative (describe replacement)
-
-If "Evolve" or "Replace": capture the target via freeform follow-up.
-
-**Capture decisions as constraints** for CONVENTIONS.md and DECISIONS.md. "Keep" entries become locked stack conventions. "Evolve" entries become phase goals. "Replace" entries become phase goals with migration requirements.
-
-## Step 6c: Convention Confirmation
-
-**If auto mode:** Skip. Promote all scan-detected conventions as-is. Proceed to Step 6d.
-
-Read `.planning/codebase/CONVENTIONS.md` (from the codebase mapper agent) and extract detected coding conventions.
-
-Present scan-detected conventions to user for confirmation:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► CONVENTION CONFIRMATION
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Your codebase uses these patterns. Should new code follow them?
+node ~/.claude/maxsim/bin/maxsim-tools.cjs install write-claude-md \
+  --project-name "{project_name}" \
+  --description "{description}"
 ```
 
-For each major convention category (file naming, error handling, testing patterns, code style):
-
-Use AskUserQuestion:
-- header: "[Convention Category]"
-- question: "Detected: [description of convention]. Should new code follow this?"
-- options:
-  - "Yes, follow this" -- Promote to project convention
-  - "No, change it" -- Describe the preferred convention
-  - "Not sure" -- Skip for now
+If unavailable, write `.claude/maxsim/PROJECT.md` directly with full project context.
 
-If "No, change it": capture the preferred convention via freeform.
+**5c. Commit initialization files:**
 
-**Promote confirmed conventions** to `.planning/CONVENTIONS.md` using the template from `templates/conventions.md`:
-- Tech Stack: from Step 6b stack preferences (keep/evolve decisions)
-- File Layout: from confirmed file structure conventions
-- Error Handling: from confirmed error handling patterns
-- Testing: from confirmed testing conventions
-- Set `{{source}}` to "init-existing scan + user confirmation"
-- Set `{{generated_or_confirmed}}` to "confirmed"
-
-Write `.planning/CONVENTIONS.md` directly using the Write tool (CONVENTIONS.md is not a valid artefakt type):
 ```bash
-# Use the Write tool to create .planning/CONVENTIONS.md with the content above
-```
-
-## Step 6d: No-Gos from Scan
-
-**If auto mode:** Skip. Auto-generate no-gos from CONCERNS.md findings. Proceed to Step 7.
-
-Read `.planning/codebase/CONCERNS.md` (if it exists) and extract findings as candidate no-gos.
-
-Present scan findings as candidate no-gos:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► NO-GOS FROM CODEBASE SCAN
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Based on the codebase scan, here are potential no-gos for new code:
+git add .claude/
+git commit -m "chore: initialize MAXSIM v6"
 ```
 
-For each significant finding from CONCERNS.md:
-
-Use AskUserQuestion:
-- header: "No-Go?"
-- question: "[Finding from CONCERNS.md] -- should this be a no-go for new code?"
-- options:
-  - "Yes, add as no-go" -- This should be explicitly forbidden
-  - "No, skip" -- This is acceptable or not relevant
-  - "Modify" -- I want to adjust the wording
-
-If "Modify": capture adjusted wording via freeform.
-
-After all findings are reviewed:
-
-Use AskUserQuestion:
-- header: "Additional"
-- question: "Any additional no-gos based on your experience with this codebase?"
-- options:
-  - "No, that covers it" -- Proceed
-  - "Yes, let me add" -- Capture additional no-gos
-
-Confirmed no-gos flow into NO-GOS.md during document generation (Step 9f) using the structured template from `templates/no-gos.md`.
-
-## 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**
+## Phase 6: Roadmap (Optional)
 
 Use AskUserQuestion:
-- header: "Pain Points"
-- question: "What pain points or issues brought you to MAXSIM?"
+- header: "Initial Roadmap"
+- question: "Based on the scan findings and your goals, would you like to generate an initial roadmap now?"
 - 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
+  - "Yes, generate roadmap from scan findings" — create phase issues
+  - "No, I'll plan manually with /maxsim:plan" — skip
 
-If "Other": capture freeform response.
+**If "No":** Print completion message and exit.
 
-**Question 2: Project Stage**
+**If "Yes":**
 
-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
+Use the Agent tool with `run_in_background: false` to spawn a Roadmap agent. Self-contained prompt:
 
-If "Yes, some things": capture freeform response.
+"You are creating an initial GitHub roadmap for a MAXSIM v6 project initialized in an existing codebase.
 
-**Question 6: Vision**
+Project details:
+- Name: {project_name}
+- Description: {description}
+- Architecture: {architecture_pattern}
+- Tech stack: {primary_language}, {frameworks}
+- Goals: {goals}
+- Acceptance criteria: {acceptance_criteria}
+- Tech debt to address: {total_todos} TODOs, {open_issue_count} open issues
+- No-gos: {no_gos}
 
-Ask inline (freeform, NOT AskUserQuestion):
+Scan summary:
+- Test coverage: {coverage_percent}%
+- CI provider: {ci_provider}
+- Database: {db_type}
 
-"What is your vision for this project? What are you trying to build? No time horizon needed -- just purpose and direction."
+Create 4–8 phase GitHub Issues on the repo {owner/repo}. Consider:
+- Stabilization phases if coverage is low or debt is high
+- Feature phases aligned with stated goals
+- Infrastructure phases if CI/CD or deploy needs work
 
-Wait for response.
+Each phase issue must:
+1. Have title format: 'Phase N: {phase_name}'
+2. Have label 'phase:{N}'
+3. Have a body with: goal statement, 5–10 acceptance criteria as task list (- [ ] item), and any relevant context from the scan
+4. Be added to milestone #{MILESTONE_NUMBER}
 
-**Thinking-partner follow-up on vision:**
+Commands:
+  gh issue create --title 'Phase N: {name}' --label 'phase:{N}' --milestone {MILESTONE_NUMBER} --body '{body}' --repo {owner/repo}
 
-After the user shares their vision, apply thinking-partner behaviors:
-- Challenge vague statements: "You said 'improve performance' — improve which operations, for which users?"
-- Surface assumptions: "That assumes users will migrate from X — is that the plan?"
-- Propose alternatives if the vision seems narrow: "Have you considered approaching it from Y angle instead?"
+After creating all issues, add each to the GitHub Project Board:
+  gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url {issue_url}
 
-Use 1-2 follow-up AskUserQuestion prompts to sharpen the vision if needed. Don't over-question — 1-2 rounds max.
+Set each issue status to 'To Do':
+  node ~/.claude/maxsim/bin/maxsim-tools.cjs github set-status --issue-number {N} --status 'To Do'
 
-## Step 8: Milestone Suggestion
+Return the list of created issue numbers and titles."
 
-**If auto mode:** Generate a milestone name from the inferred project purpose. Proceed to Step 9.
+After the agent completes, display the phase list.
 
-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 --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 --auto. Review recommended. -->
-```
-
-### 9c: ROADMAP.md
-
-**Skip if merge mode and file exists with all required headers.**
-
-Use template from `templates/roadmap.md`.
+## Completion
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► CREATING ROADMAP
+ MAXSIM ► PROJECT INITIALIZED
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-◆ Spawning roadmapper...
-```
-
-Spawn the planner (roadmap mode) via Task tool to generate the roadmap:
+Project:      {project_name}
+GitHub:       {owner/repo}
+Board:        {project_name} — MAXSIM (#{PROJECT_NUMBER})
+Milestone:    Milestone 1 (#{MILESTONE_NUMBER})
+Phases:       {N} phases created (or "none yet")
+Scanned:      {agent count} analysis agents completed
 
+Next step: /maxsim:go
 ```
-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="planner", 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.
-
-### 9c-ii: Create Phase Issues on GitHub
-
-After the roadmap is finalized (approved or auto-mode), create a GitHub Issue for each phase. This is a mandatory step — phase tracking lives in GitHub, not in local `.planning/phases/` files (per WIRE-02).
-
-Display banner:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► CREATING GITHUB PHASE ISSUES
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-1. Parse `.planning/ROADMAP.md` to extract all phases. For each phase, collect:
-   - `phase_number` (e.g., `01`, `02`)
-   - `phase_name` (e.g., "Foundation")
-   - `goal` (the phase goal statement)
-   - `requirements` (list of REQ-IDs mapped to this phase)
-   - `success_criteria` (list of observable outcomes)
-
-2. For each phase, run `github create-phase`:
-   ```bash
-   node ~/.claude/maxsim/bin/maxsim-tools.cjs github create-phase \
-     --phase-number "[phase_number]" \
-     --phase-name "[phase_name]" \
-     --goal "[goal]"
-   ```
-   The tool auto-adds each issue to the project board with "To Do" status.
-
-3. Track results per phase. If any phase issue creation fails:
-   - Log which phases succeeded and which failed.
-   - Offer targeted retry for failed phases only (do not re-create successful ones).
-
-4. Report completion:
-   ```
-   ✓ Created {N} phase issues on GitHub Project Board #{project_number}
-   ```
-
-**Note:** Per WIRE-02, phase-level artifact files (PLAN.md, SUMMARY.md, RESEARCH.md, CONTEXT.md) are NOT created in `.planning/phases/` during init. These live exclusively as GitHub Issue comments and bodies. The following local files are still created and committed: PROJECT.md, REQUIREMENTS.md, config.json, STATE.md, ROADMAP.md.
-
-### 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 --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).
-
-### 9f: Artefakte Generation
-
-Generate structured artefakte documents from gathered context.
-
-**DECISIONS.md:**
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-write decisions
-```
-
-Write content:
-
-```markdown
-# Key Decisions
-
-**Generated:** [date]
-**Source:** Init-existing initialization
-
-| # | Decision | Rationale | Alternatives Considered | Status |
-|---|----------|-----------|------------------------|--------|
-| 1 | [Config choice: mode] | [Why] | [Other options] | Locked |
-| 2 | [Stage assessment] | [Evidence from scan] | [Other stages considered] | Locked |
-| 3 | [Any constraint decisions from Step 7] | [Why] | [Alternatives] | Locked |
-
----
-*Decisions captured during /maxsim:init initialization*
-```
-
-**ACCEPTANCE-CRITERIA.md:**
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-write acceptance-criteria
-```
-
-Write content:
-
-```markdown
-# Acceptance Criteria
-
-**Generated:** [date]
-**Source:** Init-existing initialization
-
-## Project-Level Criteria
-
-- [ ] [Observable outcome from user's vision]
-- [ ] [Observable outcome from user's vision]
-- [ ] [Stability guard from production constraints, if applicable]
-
-## Phase-Level Criteria
-
-Populated per-phase during /maxsim:plan (discussion stage).
-
----
-*Criteria derived from init-existing initialization*
-```
-
-**NO-GOS.md:**
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs artefakte-write no-gos
-```
-
-Write content:
-
-```markdown
-# No-Gos
-
-**Generated:** [date]
-**Source:** Init-existing initialization
-
-## Must Not Break
-
-[From production constraints / GUARD requirements in REQUIREMENTS.md]
-
-- [Critical thing that cannot break] -- [why]
-
-## Anti-Patterns
-
-[From CONCERNS.md and user input]
-
-- [Approach to avoid] -- [why]
-
-## Scope Boundaries
-
-- [What this milestone is NOT trying to achieve]
-
----
-*No-gos captured during /maxsim:init initialization*
-```
-
-**If auto mode:** Generate artefakte from scan findings with reasonable inferences. Mark uncertain entries with `(inferred)`.
-
-**Commit artefakte:**
-
-```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: generate initialization artefakte" --files .planning/DECISIONS.md .planning/ACCEPTANCE-CRITERIA.md .planning/NO-GOS.md
-```
-
-## Step 9g: Agent Dry-Run Validation
-
-**Always runs after all documents are generated — this is the quality gate for init output.**
-
-Spawn a test agent to validate that all generated docs contain enough information for a fresh agent to start Phase 1 without asking clarifying questions.
-
-```
-Task(prompt="
-You are a fresh agent about to start Phase 1 of this project.
-Read the following files and report what you would need to ask before starting work.
-
-Do NOT infer missing information. If a specific library version is not stated, report it as a gap.
-If the error handling pattern is not described, report it as a gap.
-Your job is to find what is NOT written, not to demonstrate you could figure it out.
-
-<files_to_read>
-- .planning/PROJECT.md
-- .planning/REQUIREMENTS.md
-- .planning/CONVENTIONS.md
-- .planning/NO-GOS.md
-- .planning/ROADMAP.md
-</files_to_read>
-
-Report format:
-
-## DRY-RUN RESULT
-
-### Can Start: YES/NO
-
-### Gaps Found:
-- [What information is missing]
-- [What is ambiguous]
-- [What would need clarification]
-
-### Quality Score: [1-10]
-(10 = could start immediately with zero questions, 1 = need major clarifications)
-", model="{planner_model}", description="Agent readiness dry-run")
-```
-
-**Handle dry-run results:**
-
-**If gaps found (Can Start = NO or Quality Score < 7):**
-- For each gap, update the relevant document to fill it:
-  - Missing tech versions → update CONVENTIONS.md Tech Stack
-  - Missing error handling → update CONVENTIONS.md Error Handling
-  - Ambiguous requirements → update REQUIREMENTS.md
-  - Missing constraints → update NO-GOS.md
-- Commit the fixes:
-  ```bash
-  node ~/.claude/maxsim/bin/maxsim-tools.cjs commit "docs: fill gaps from agent dry-run validation" --files .planning/PROJECT.md .planning/REQUIREMENTS.md .planning/CONVENTIONS.md .planning/NO-GOS.md
-  ```
-
-**If no gaps (Can Start = YES and Quality Score >= 7):**
-- Continue to Step 10.
-
-## 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"
-```
-
-Print structured summary:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- MAXSIM ► INITIALIZATION COMPLETE ✓
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Created:
-  ✓ .planning/config.json         -- Workflow preferences
-  ✓ .planning/PROJECT.md          -- Project context + current state
-  ✓ .planning/CONVENTIONS.md      -- Confirmed coding conventions for agents
-  ✓ .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)
-  ✓ GitHub Project Board #{project_number} -- [N] phase issues created with "To Do" status
-```
-
-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 1 -- plan the first phase
-
-<sub>/clear first → fresh context window</sub>
-
-───────────────────────────────────────────────────────────────
-
-**Also available:**
-- /maxsim:progress -- review the generated roadmap
-- /maxsim:progress -- see project status
-
-───────────────────────────────────────────────────────────────
-```
-
-**End of workflow.**
 
 </process>
 
-<output>
-
-- `.planning/config.json`
-- `.planning/PROJECT.md`
-- `.planning/CONVENTIONS.md`
-- `.planning/REQUIREMENTS.md`
-- `.planning/ROADMAP.md`
-- `.planning/STATE.md`
-- `.planning/DECISIONS.md`
-- `.planning/ACCEPTANCE-CRITERIA.md`
-- `.planning/NO-GOS.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)
-- [ ] GitHub remote detected (gate passed)
-- [ ] GitHub CLI authenticated (gate passed)
-- [ ] `github setup` called successfully — project_number recorded
-- [ ] 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)
-- [ ] `github create-phase` called for every phase — all issues on board with "To Do" status
-- [ ] STATE.md created with pre-populated decisions and blockers
-- [ ] config.json created with workflow settings
-- [ ] .planning/codebase/ populated with scan documents
-- [ ] Git staging completed
-- [ ] Stack preference questions asked (keep/evolve/replace for framework-level choices)
-- [ ] Convention confirmation completed (scan-detected conventions presented to user)
-- [ ] CONVENTIONS.md generated from confirmed conventions
-- [ ] CONCERNS.md findings presented as candidate no-gos
-- [ ] Agent dry-run validation passed (Quality Score >= 7)
-- [ ] Structured summary printed
-- [ ] Next steps suggested: /maxsim:progress then /maxsim:plan 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>
+<constraints>
+- Tool name is Agent (NOT Task)
+- No SlashCommand tool
+- GitHub Issues is the SOLE source of truth — no local .planning/ directory
+- Use `node ~/.claude/maxsim/bin/maxsim-tools.cjs` for CLI operations
+- EnterPlanMode must be used before any code-modifying execution steps
+- Agent spawning uses: Agent tool with isolation:"worktree", run_in_background:true (for parallel scan) or run_in_background:false (for sequential roadmap work)
+- Self-contained agent prompts — every agent prompt includes all context it needs inline, no external references
+- Maximum 4 questions per AskUserQuestion call
+- Do NOT read actual .env files with real secrets — only .env.example or documented equivalents
+- Spawn all scan agents simultaneously; do not wait for one before starting the next
+- Synthesize all agent findings before presenting to user — do not dump raw JSON
+</constraints>