maxsimcli 5.0.7 → 5.1.0

package/dist/assets/templates/workflows/plan-discuss.md

@@ -1,11 +1,28 @@
 <purpose>
-Discussion stage sub-workflow for /maxsim:plan. Extracts implementation decisions that downstream agents (researcher, planner) need. Analyzes the phase to identify gray areas, lets the user choose what to discuss, then deep-dives each selected area until satisfied.
+Discussion stage sub-workflow for /maxsim:plan. Extracts implementation decisions that
+downstream agents (researcher, planner) need by analyzing the phase, presenting gray areas
+to the user, and conducting a focused dialogue. Posts the resulting context as a GitHub
+Issue comment with <!-- maxsim:type=context -->.
 
-This file is loaded by the plan.md orchestrator. It does NOT handle gate confirmations or stage routing -- the orchestrator handles that. This sub-workflow focuses ONLY on running the discussion and posting the context decisions to GitHub.
+This file is loaded by the plan.md orchestrator. It does NOT handle gate confirmations or
+stage routing -- the orchestrator handles that. This sub-workflow focuses ONLY on running
+the discussion and posting the context decisions to GitHub.
 
-You are a thinking partner, not an interviewer. The user is the visionary -- you are the builder. Your job is to capture decisions that will guide research and planning, not to figure out implementation yourself.
+GitHub Issues is the sole source of truth. No local CONTEXT.md file is written.
+
+You are a thinking partner, not an interviewer. The user is the visionary -- you are the
+builder. Your job is to capture decisions that will guide research and planning, not to
+figure out implementation yourself.
 </purpose>
 
+<critical_rules>
+- Tool name is `Agent` (NOT `Task`)
+- Context is posted to GitHub as a comment with <!-- maxsim:type=context -->
+- Use `node ~/.claude/maxsim/bin/maxsim-tools.cjs` for all CLI operations
+- No local CONTEXT.md file is written -- GitHub is the sole source of truth
+- Do NOT show gate confirmation or next steps -- the orchestrator handles those
+</critical_rules>
+
 <required_reading>
 @~/.claude/maxsim/references/thinking-partner.md
 </required_reading>
@@ -21,9 +38,11 @@ You are a thinking partner, not an interviewer. The user is the visionary -- you
    - "Pull-to-refresh on mobile" -> planner includes that in task specs
    - "Claude's Discretion: loading skeleton" -> planner can decide approach
 
-**Your job:** Capture decisions clearly enough that downstream agents can act on them without asking the user again.
+**Your job:** Capture decisions clearly enough that downstream agents can act on them without
+asking the user again.
 
-**Not your job:** Figure out HOW to implement. That's what research and planning do with the decisions you capture.
+**Not your job:** Figure out HOW to implement. That's what research and planning do with the
+decisions you capture.
 </downstream_awareness>
 
 <philosophy>
@@ -50,26 +69,13 @@ Ask about vision and implementation choices. Capture decisions for downstream ag
 - **Make consequences visible** -- "Infinite scroll means no shareable page positions."
 - **Disagree constructively** -- If an approach has risks, name them.
 - **Follow the thread** -- Build on what they just said. Don't jump topics.
-
-Apply these behaviors within each discussion area. The user should feel like they're thinking through decisions with a collaborator, not answering a survey.
 </philosophy>
 
 <scope_guardrail>
 **CRITICAL: No scope creep.**
 
-The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities.
-
-**Allowed (clarifying ambiguity):**
-- "How should posts be displayed?" (layout, density, info shown)
-- "What happens on empty state?" (within the feature)
-- "Pull to refresh or manual?" (behavior choice)
-
-**Not allowed (scope creep):**
-- "Should we also add comments?" (new capability)
-- "What about search/filtering?" (new capability)
-- "Maybe include bookmarking?" (new capability)
-
-**The heuristic:** Does this clarify how we implement what's already in the phase, or does it add a new capability that could be its own phase?
+The phase boundary comes from ROADMAP.md and is FIXED. Discussion clarifies HOW to implement
+what's scoped, never WHETHER to add new capabilities.
 
 **When user suggests scope creep:**
 ```
@@ -83,34 +89,18 @@ Capture the idea in a "Deferred Ideas" section. Don't lose it, don't act on it.
 </scope_guardrail>
 
 <gray_area_identification>
-Gray areas are **implementation decisions the user cares about** -- things that could go multiple ways and would change the result.
+Gray areas are **implementation decisions the user cares about** -- things that could go
+multiple ways and would change the result.
 
 **How to identify gray areas:**
-
-1. **Read the phase goal** from ROADMAP.md
-2. **Understand the domain** -- What kind of thing is being built?
+1. Read the phase goal from the GitHub Issue description
+2. Understand the domain -- What kind of thing is being built?
    - Something users SEE -> visual presentation, interactions, states matter
    - Something users CALL -> interface contracts, responses, errors matter
    - Something users RUN -> invocation, output, behavior modes matter
    - Something users READ -> structure, tone, depth, flow matter
    - Something being ORGANIZED -> criteria, grouping, handling exceptions matter
-3. **Generate phase-specific gray areas** -- Not generic categories, but concrete decisions for THIS phase
-
-**Don't use generic category labels** (UI, UX, Behavior). Generate specific gray areas:
-
-```
-Phase: "User authentication"
--> Session handling, Error responses, Multi-device policy, Recovery flow
-
-Phase: "Organize photo library"
--> Grouping criteria, Duplicate handling, Naming convention, Folder structure
-
-Phase: "CLI for database backups"
--> Output format, Flag design, Progress reporting, Error recovery
-
-Phase: "API documentation"
--> Structure/navigation, Code examples depth, Versioning approach, Interactive elements
-```
+3. Generate phase-specific gray areas -- Not generic categories, but concrete decisions for THIS phase
 
 **The key question:** What decisions would change the outcome that the user should weigh in on?
 
@@ -128,37 +118,41 @@ Phase: "API documentation"
 Phase number, name, directory, and GitHub issue number come from the orchestrator context.
 
 ```bash
-INIT=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs init phase-op "${PHASE}")
+PHASE_ISSUE=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue \
+  --issue-number $PHASE_ISSUE_NUMBER)
 ```
 
-Parse JSON for: `commit_docs`, `phase_found`, `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded_phase`, `has_research`, `has_context`, `has_plans`, `plan_count`, `roadmap_exists`, `planning_exists`.
-
-Also extract `phase_issue_number` passed from the orchestrator.
+Extract `phase_goal` and `phase_description` from the issue body for use in gray area analysis.
 
-**If `phase_found` is false:** Error -- the orchestrator should have caught this, but fail safe.
+**If issue fetch fails:** Error -- the orchestrator should have caught this, but fail safe:
+```
+Cannot read phase issue #{phase_issue_number}. Check GitHub connection.
+```
 
 ## Step 2: Check Existing Context
 
-Check if a context comment already exists on the phase GitHub Issue by calling:
+Check if a context comment already exists on the phase GitHub Issue:
 ```bash
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue --issue-number $PHASE_ISSUE_NUMBER --include-comments
+ISSUE_DATA=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue \
+  --issue-number $PHASE_ISSUE_NUMBER --include-comments)
 ```
 
-Look for a comment that contains `<!-- maxsim:type=context -->`.
+Look for a comment containing `<!-- maxsim:type=context -->`.
 
 **If a context comment exists:**
 
 Ask the user (via natural conversation):
 ```
 Phase {phase_number} already has context on GitHub Issue #{phase_issue_number}. What would you like to do?
+
 1. Update it -- review and revise existing context
 2. View it -- show me what's there
 3. Use as-is -- keep existing context and return to orchestrator
 ```
 
-- If "Update": Load existing context comment content, continue to Step 3.
+- If "Update": Load existing context comment content, continue to Step 3 with it pre-loaded.
 - If "View": Display context comment contents, then offer update/use-as-is.
-- If "Use as-is": Return control to orchestrator.
+- If "Use as-is": Return control to orchestrator (display "Using existing context from Issue #{phase_issue_number}.").
 
 **If no context comment exists:** Continue to Step 3.
 
@@ -166,15 +160,22 @@ Phase {phase_number} already has context on GitHub Issue #{phase_issue_number}.
 
 Analyze the phase to identify gray areas worth discussing.
 
-**Read the phase description from ROADMAP.md and determine:**
+**Read the phase description from the GitHub Issue and determine:**
 
 1. **Domain boundary** -- What capability is this phase delivering? State it clearly.
 
-2. **Gray areas by category** -- For each relevant category, identify 1-2 specific ambiguities that would change implementation.
+2. **Gray areas** -- For each relevant decision area, identify 1-2 specific ambiguities
+   that would change implementation. Generate phase-specific areas, not generic labels.
 
-3. **Skip assessment** -- If no meaningful gray areas exist (pure infrastructure, clear-cut implementation), note this but still present options.
+   Examples:
+   - Phase "User authentication": Session handling, Error responses, Multi-device policy, Recovery flow
+   - Phase "CLI for database backups": Output format, Flag design, Progress reporting, Error recovery
+   - Phase "API documentation": Structure/navigation, Code examples depth, Versioning approach
 
-**Output your analysis internally, then present to user.**
+3. **Skip assessment** -- If no meaningful gray areas exist (pure infrastructure, clear-cut
+   implementation), note this but still present options.
+
+Output your analysis internally, then proceed to Step 4.
 
 ## Step 4: Present Gray Areas
 
@@ -198,10 +199,10 @@ Which areas do you want to discuss for {phase_name}?
 3. {Specific area 3} -- {what decisions this covers}
 4. {Specific area 4} -- {what decisions this covers}
 
-Select by number (e.g., "1, 3" or "all").
+Select by number (e.g., "1, 3" or "all"). Or say "skip" to proceed without discussion.
 ```
 
-Generate 3-4 **phase-specific** gray areas, not generic categories. Each should be a concrete decision area.
+Generate 3-4 **phase-specific** gray areas -- concrete decision areas, not generic labels.
 
 ## Step 5: Discuss Areas
 
@@ -209,7 +210,8 @@ For each selected area, conduct a focused discussion loop.
 
 **Philosophy: 4 questions, then check.**
 
-Ask 4 questions per area before offering to continue or move on. Each answer often reveals the next question.
+Ask 4 questions per area before offering to continue or move on. Each answer often reveals
+the next question.
 
 **For each area:**
 
@@ -226,6 +228,8 @@ Ask 4 questions per area before offering to continue or move on. Each answer oft
 3. **After 4 questions, check:**
    ```
    More questions about {area}, or move to next?
+   1. More questions
+   2. Next area
    ```
    - If "More" -> ask 4 more, then check again
    - If "Next" -> proceed to next selected area
@@ -242,18 +246,12 @@ Ask 4 questions per area before offering to continue or move on. Each answer oft
    - If "Ready": Proceed to Step 6.
 
 **Adaptive probing (thinking-partner mode):**
-
-Within each area, adapt your questioning based on the user's certainty level:
 - **User is confident** (picks options quickly) -- probe deeper: "You chose X -- have you considered how that interacts with Y?"
 - **User is uncertain** (hedges) -- propose alternatives: "Here are 3 approaches with trade-offs..."
 - **User defers** (picks "You decide") -- accept but name consequences: "I'll go with X because [reason]. That means Y."
 
-Challenge decisions that may have hidden costs. If the user picks something that conflicts with an earlier decision, surface it: "Earlier you said A, but this implies B. Which takes priority?"
-
-**Question design:**
-- Options should be concrete, not abstract ("Cards" not "Option A")
-- Each answer should inform the next question
-- If user gives free text, reflect it back and confirm
+Challenge decisions that may have hidden costs. If the user picks something that conflicts
+with an earlier decision, surface it: "Earlier you said A, but this implies B. Which takes priority?"
 
 **Scope creep handling:**
 If user mentions something outside the phase domain:
@@ -265,19 +263,18 @@ Back to [current area]: [return to current question]"
 ```
 
 Track deferred ideas internally.
-</process>
 
 ## Step 6: Post Context to GitHub
 
 Build the context content in memory, then post it as a comment on the phase GitHub Issue.
 
-**Structure the content by what was discussed:**
+**Structure the context content:**
 
 ```markdown
 <!-- maxsim:type=context -->
 # Phase {X} Context: {Name}
 
-**Phase Goal:** {goal from ROADMAP.md}
+**Phase Goal:** {goal from GitHub Issue}
 **Created:** {date}
 **Requirements:** {requirement IDs if any}
 
@@ -315,29 +312,39 @@ Build the context content in memory, then post it as a comment on the phase GitH
 Post the comment to GitHub:
 ```bash
 TMPFILE=$(mktemp)
-echo "$CONTEXT_CONTENT" > "$TMPFILE"
-node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-comment --issue-number $PHASE_ISSUE_NUMBER --body-file "$TMPFILE" --type context
+cat > "$TMPFILE" << 'BODY_EOF'
+{context_content}
+BODY_EOF
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-comment \
+  --issue-number $PHASE_ISSUE_NUMBER --body-file "$TMPFILE" --type context
 ```
 
-Context decisions are posted as a GitHub comment on phase issue #{phase_issue_number}. No local CONTEXT.md file is written.
+Context decisions are posted as a GitHub comment on phase issue #{phase_issue_number}.
+No local CONTEXT.md file is written.
 
 ## Step 7: Return to Orchestrator
 
-After posting the context comment to GitHub, return control to the plan.md orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the gate between Discussion and Research.
+After posting the context comment to GitHub, return control to the plan.md orchestrator.
+Do NOT show gate confirmation or next steps -- the orchestrator handles the gate between
+Discussion and Research.
 
 Display a brief completion message:
 ```
 Discussion complete. Context decisions posted to GitHub Issue #{phase_issue_number}.
 ```
 
+</process>
+
 <success_criteria>
-- Phase validated against roadmap
-- Gray areas identified through intelligent analysis (not generic questions)
-- User selected which areas to discuss
-- Each selected area explored until user satisfied
-- Scope creep redirected to deferred ideas
-- Context comment captures actual decisions (not vague vision) with <!-- maxsim:type=context --> marker
-- Context posted to GitHub Issue #{phase_issue_number} as a comment (no local CONTEXT.md written)
-- Deferred ideas preserved for future phases
-- Control returned to orchestrator without showing gate or next steps
+- [ ] Phase description read from GitHub Issue (not local ROADMAP.md)
+- [ ] Existing context comment detected from GitHub Issue and handled (update/view/use-as-is)
+- [ ] Gray areas identified through intelligent phase analysis (not generic questions)
+- [ ] User selected which areas to discuss
+- [ ] Each selected area explored with 4-question depth, adaptive probing applied
+- [ ] Scope creep redirected to deferred ideas
+- [ ] Context comment captures actual decisions (not vague vision) with <!-- maxsim:type=context --> marker
+- [ ] Context posted to GitHub Issue #{phase_issue_number} as a comment (no local CONTEXT.md written)
+- [ ] Deferred ideas preserved in context comment
+- [ ] Control returned to orchestrator without showing gate or next steps
+- [ ] Agent tool used (not Task) for any agent spawning
 </success_criteria>

package/dist/assets/templates/workflows/plan-research.md

@@ -1,9 +1,26 @@
 <purpose>
-Research stage sub-workflow for /maxsim:plan. Spawns the researcher agent with phase context to produce research findings, then posts them to GitHub as a comment on the phase issue.
+Research stage sub-workflow for /maxsim:plan. Spawns 5-10 parallel researcher agents (using
+Agent tool with run_in_background=true) to investigate different aspects of the phase in
+parallel, aggregates their findings, and posts the consolidated research to GitHub as a comment
+with <!-- maxsim:type=research -->.
 
-This file is loaded by the plan.md orchestrator. It does NOT handle gate confirmations or stage routing -- the orchestrator handles that. This sub-workflow focuses ONLY on running research and posting the output to GitHub.
+This file is loaded by the plan.md orchestrator. It does NOT handle gate confirmations or
+stage routing -- the orchestrator handles that. This sub-workflow focuses ONLY on running
+research and posting the output to GitHub.
+
+GitHub Issues is the sole source of truth. No local RESEARCH.md file is written.
 </purpose>
 
+<critical_rules>
+- Tool name is `Agent` (NOT `Task`)
+- Agent spawning: Agent(prompt, model, isolation, run_in_background)
+- Parallel agents use run_in_background=true, then collect results
+- Research is posted to GitHub with <!-- maxsim:type=research -->
+- Use `node ~/.claude/maxsim/bin/maxsim-tools.cjs` for all CLI operations
+- No local RESEARCH.md file is written -- GitHub is the sole source of truth
+- Do NOT show gate confirmation or next steps -- the orchestrator handles those
+</critical_rules>
+
 <process>
 
 ## Step 1: Check Prerequisites
@@ -13,7 +30,7 @@ The orchestrator provides phase context. Verify we have what we need:
 - `phase_number`, `phase_name`, `phase_dir`, `padded_phase`, `phase_slug`
 - `researcher_model`, `research_enabled`
 - `has_research` (whether a research comment already exists on the phase issue)
-- `state_path`, `roadmap_path`, `requirements_path`, `context_path`
+- `state_path`, `roadmap_path`, `requirements_path`
 - `phase_req_ids` (requirement IDs that this phase must address)
 - `phase_issue_number` (GitHub Issue number for the phase)
 - `--force-research` flag presence
@@ -26,7 +43,9 @@ RESEARCHER_MODEL=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs resolve-model rese
 
 ## Step 3: Check Existing Research
 
-Determine whether a research comment already exists on the phase GitHub Issue by checking for a comment containing `<!-- maxsim:type=research -->`. This is reflected in the `has_research` flag passed from the orchestrator (which performs the GitHub query).
+Determine whether a research comment already exists on the phase GitHub Issue by checking
+for a comment containing `<!-- maxsim:type=research -->`. This is reflected in the
+`has_research` flag passed from the orchestrator.
 
 **If `has_research` is true AND `--force-research` is NOT set:**
 
@@ -55,124 +74,211 @@ Skipping research stage.
 
 Return control to orchestrator.
 
-## Step 4: Gather Phase Context
+## Step 4: Read Phase Context from GitHub
+
+Fetch the phase issue with all comments to extract context for research scoping:
 
 ```bash
-PHASE_DESC=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs roadmap get-phase "${PHASE}" 2>/dev/null)
+ISSUE_DATA=$(node ~/.claude/maxsim/bin/maxsim-tools.cjs github get-issue \
+  --issue-number $PHASE_ISSUE_NUMBER --include-comments)
 ```
 
-Extract the phase section/description from the JSON output for the researcher prompt.
+Extract from the response:
+- Phase goal and description from the issue body
+- Context comment content (from the `<!-- maxsim:type=context -->` comment, if present)
+
+The context comment determines WHAT to research: user decisions lock certain approaches,
+guiding researchers away from alternatives.
+
+## Step 5: Define Research Domains
+
+Based on the phase description and context decisions, identify 5-10 distinct research domains.
+Each domain should be independently investigatable by a separate agent.
 
-## Step 5: Spawn Researcher
+**Research domain categories (select those relevant to this phase):**
+
+1. **Existing code patterns** -- How is similar functionality implemented in the codebase?
+   File structure, naming conventions, module patterns used.
+2. **Dependencies & libraries** -- What packages/APIs are already available? Which to use?
+3. **API contracts** -- External service interfaces, response shapes, error codes.
+4. **Test patterns** -- How are tests written for this type of code? Coverage expectations.
+5. **Data models** -- Existing schema, types, validation patterns relevant to the phase.
+6. **Integration points** -- Where does this phase connect to existing systems?
+7. **Security & validation** -- Input validation patterns, auth flows, edge cases.
+8. **Performance considerations** -- Known bottlenecks, caching patterns, query patterns.
+9. **Configuration & environment** -- Config file patterns, env vars, feature flags.
+10. **Error handling** -- How errors surface, logging patterns, user-facing error formats.
+
+Select 5-10 domains most relevant to this phase. Define a focused research question for each.
+
+## Step 6: Spawn Parallel Research Agents
 
 Display:
 ```
 Researching Phase {phase_number}: {phase_name}...
+Spawning {N} parallel research agents...
 ```
 
-Construct the research prompt. The researcher must return its findings as a structured markdown document (not write to a local file -- the orchestrator will post findings to GitHub):
+Spawn each researcher as a background Agent. All agents run in parallel:
 
-```markdown
-<objective>
-Research how to implement Phase {phase_number}: {phase_name}
-Answer: "What do I need to know to PLAN this phase well?"
-</objective>
+```
+Agent(
+  prompt="<objective>
+Research Domain: {domain_name}
+Phase: {phase_number} -- {phase_name}
 
-<files_to_read>
-- GitHub Issue #{phase_issue_number} context comment (USER DECISIONS -- locked choices that constrain research)
-- {requirements_path} (Project requirements)
-- {state_path} (Project decisions and history)
-</files_to_read>
+Research Question: {focused question for this domain}
 
-<additional_context>
-**Phase description:** {phase_description from PHASE_DESC}
-**Phase requirement IDs (MUST address):** {phase_req_ids}
+<context>
+Phase Goal: {phase_goal}
+User Decisions (from context comment): {key decisions that constrain this domain}
+Phase Requirements: {phase_req_ids}
+</context>
 
-**Project instructions:** Read ./CLAUDE.md if exists -- follow project-specific guidelines
-**Project skills:** Check .skills/ directory (if exists) -- read SKILL.md files, research should account for project skill patterns
-</additional_context>
+<instructions>
+Investigate this specific domain. Use Read, Grep, Glob to explore the codebase.
+Use WebFetch for external documentation if needed.
 
-<output>
-Return findings as a structured markdown document in your response.
-Do NOT write to a local file -- findings will be posted to GitHub by the orchestrator.
-</output>
-```
+Focus on: what the planner needs to know to create correct tasks for this domain.
+Answer the research question with evidence from the codebase or official sources.
 
-Spawn the researcher:
+<output_format>
+Return findings as structured markdown:
 
-```
-Task(
-  prompt=research_prompt,
-  subagent_type="researcher",
+## {Domain Name}
+
+**Research Question:** {question}
+**Confidence:** HIGH | MEDIUM | LOW
+
+### Findings
+{evidence-backed findings}
+
+### Recommended Approach
+{what the planner should do, based on findings}
+
+### Pitfalls
+{known risks or gotchas to avoid}
+
+### Open Questions
+{anything that needs user decision or remains uncertain}
+</output_format>
+</instructions>",
   model="{researcher_model}",
-  description="Research Phase {phase_number}"
+  isolation=true,
+  run_in_background=true
 )
 ```
 
-## Step 6: Handle Researcher Return
+Spawn all research agents in parallel using `run_in_background=true`. Do not await any
+individual agent before spawning the next.
+
+## Step 7: Collect and Aggregate Findings
+
+After all background agents complete, collect their results.
 
-Parse the researcher's return message:
+For each agent result:
+- Extract the domain findings markdown
+- Note the confidence level (HIGH/MEDIUM/LOW)
+- Note any open questions flagged by the agent
 
-- **`## RESEARCH COMPLETE`:**
-  Extract the research findings document from the researcher's response.
+**Aggregate into a consolidated research document:**
+
+```markdown
+<!-- maxsim:type=research -->
+# Phase {X} Research: {Name}
 
-  Post research findings to GitHub:
-  ```bash
-  TMPFILE=$(mktemp)
-  cat > "$TMPFILE" << 'BODY_EOF'
-  <!-- maxsim:type=research -->
-  {research_findings_document}
-  BODY_EOF
-  node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-comment --issue-number $PHASE_ISSUE_NUMBER --body-file "$TMPFILE" --type research
-  ```
+**Phase Goal:** {goal}
+**Researched:** {date}
+**Domains investigated:** {N}
+**Overall confidence:** {HIGH if all HIGH, MEDIUM if mixed, LOW if any LOW}
 
-  Research findings are posted as a GitHub comment on phase issue #{phase_issue_number}. No local RESEARCH.md file is written.
+## Summary
 
-  Display confirmation:
-  ```
-  Research complete. Findings posted to GitHub Issue #{phase_issue_number}.
-  ```
+{3-5 bullet executive summary of the most important findings}
 
-  Return control to orchestrator.
+---
 
-- **`## RESEARCH BLOCKED`:**
-  Display the blocker reason. Offer options:
-  ```
-  Research blocked: {reason}
+{Insert each domain findings section in order of relevance}
 
-  1. Provide additional context and retry
-  2. Skip research and proceed to planning
-  3. Abort
-  ```
-  Wait for user choice.
+---
 
-  - If "Provide context": Get additional info, re-spawn researcher with augmented prompt.
-  - If "Skip": Return to orchestrator without posting research comment.
-  - If "Abort": Exit workflow.
+## Synthesis: Key Decisions for Planner
 
-- **`## RESEARCH INCONCLUSIVE`:**
-  Display what was attempted. Offer:
-  ```
-  Research inconclusive after {N} attempts.
+{Cross-cutting decisions the planner should make, derived from aggregate findings}
+
+| Decision | Recommended | Rationale |
+|----------|-------------|-----------|
+| {decision area} | {what to do} | {why, from evidence} |
+
+## Open Questions
+
+{Unresolved questions that require user input or further investigation}
+
+---
+*Research created: {date}*
+*Agents: {N} researchers across {N} domains*
+```
+
+## Step 8: Post Research to GitHub
+
+Post the consolidated research as a comment on the phase GitHub Issue:
+
+```bash
+TMPFILE=$(mktemp)
+cat > "$TMPFILE" << 'BODY_EOF'
+{consolidated_research_document}
+BODY_EOF
+node ~/.claude/maxsim/bin/maxsim-tools.cjs github post-comment \
+  --issue-number $PHASE_ISSUE_NUMBER --body-file "$TMPFILE" --type research
+```
+
+Research findings are posted as a GitHub comment on phase issue #{phase_issue_number}.
+No local RESEARCH.md file is written.
+
+Display confirmation:
+```
+Research complete. Findings from {N} agents posted to GitHub Issue #{phase_issue_number}.
+```
+
+## Step 9: Handle Agent Failures
+
+If any research agent fails or returns no findings:
+
+- Log which domain failed: "Agent for '{domain}' returned no findings."
+- Continue with findings from the agents that did succeed.
+- Note the failed domain in the research document under "Incomplete Research".
+- Do NOT block progress on a single failed agent -- partial research is better than none.
+
+If more than half the agents fail:
+```
+Research partially failed. Only {N}/{total} agents returned findings.
+
+1. Retry failed agents
+2. Proceed with partial research
+3. Skip research and proceed to planning
+```
 
-  1. Provide more context and retry
-  2. Skip research
-  3. Abort
-  ```
-  Handle same as BLOCKED options.
+Wait for user choice.
 
-## Step 7: Return to Orchestrator
+## Step 10: Return to Orchestrator
 
-After research is posted to GitHub (or research is skipped), return control to the plan.md orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the gate between Research and Planning.
+After research is posted to GitHub (or research is skipped), return control to the plan.md
+orchestrator. Do NOT show gate confirmation or next steps -- the orchestrator handles the gate
+between Research and Planning.
 
 </process>
 
 <success_criteria>
-- Researcher model resolved from config
-- Existing research detected from GitHub Issue comment (<!-- maxsim:type=research --> marker) and reused unless --force-research
-- researcher agent spawned with full context (GitHub context comment, requirements, state)
-- Research findings returned from researcher as document, then posted as GitHub comment on Issue #{phase_issue_number}
-- No local RESEARCH.md file written
-- Blocked/inconclusive scenarios handled with user options
-- Control returned to orchestrator without showing gate or next steps
+- [ ] Researcher model resolved from config
+- [ ] Existing research detected from GitHub Issue comment (<!-- maxsim:type=research --> marker) and reused unless --force-research
+- [ ] Phase context read from GitHub Issue (context comment + issue body)
+- [ ] 5-10 research domains defined based on phase characteristics
+- [ ] All research agents spawned in parallel using run_in_background=true
+- [ ] Agent tool used (not Task) for all agent spawning
+- [ ] Each agent investigates a distinct, focused domain
+- [ ] Agent failures handled gracefully -- partial research does not block progress
+- [ ] Findings aggregated into consolidated research document
+- [ ] Research document posted as GitHub comment with <!-- maxsim:type=research --> marker
+- [ ] No local RESEARCH.md file written
+- [ ] Control returned to orchestrator without showing gate or next steps
 </success_criteria>