Plan mode should leverage the Analyze agent's research framework

[acreeger]

Fixes #879

Plan mode should leverage the Analyze agent's research framework

Summary

The plan command (il plan) runs a single Claude session with plan-prompt.txt but performs no structured codebase or problem space research before decomposing work into child issues. The Analyze agent (iloom-issue-analyzer.md) has a comprehensive research framework that would significantly improve planning quality if leveraged during the planning phase.

Problem

The plan prompt focuses heavily on decomposition methodology (DAG shape, contracts, SIMPLE sizing, wave verification) but has almost no guidance on how to understand the codebase before decomposing. The current state:

Aspect	Analyzer Agent	Plan Prompt
Problem Space Research	Structured framework: domain understanding, alternative approaches, architectural context, edge cases	Nothing explicit — relies on clarifying questions to the user
Third-Party Research	4-tier hierarchy: Skills → Context7 → WebSearch → MCP	Not mentioned
Codebase Research	Systematic: entry points, dependency mapping, pattern recognition, historical context, git blame	One line: "explore the codebase with Read, Glob, Grep tools"
Cross-Cutting Analysis	Full call-chain mapping with affected interfaces	Not present
Research Quality Gates	Detailed failure modes to avoid, quality checklist	None

The quality of issue decomposition depends heavily on understanding the existing codebase. Without structured research, the architect may:

• Miss cross-cutting concerns that should influence how work is split
• Misjudge complexity of child issues
• Overlook existing patterns that child issues should follow
• Create contracts that conflict with existing architecture

Desired Outcome

Plan mode should incorporate the Analyze agent's structured research capabilities so that the architect has thorough codebase and problem space understanding before decomposing work into child issues.

Scope Boundaries

• This is about improving the planning phase's research quality, not changing the decomposition methodology itself
• The analyzer's documentation format (Section 1/Section 2, comment routing) is specific to swarm execution and should NOT be carried over — only the research framework

---

This PR was created automatically by iloom.

[acreeger]

Combined Analysis & Plan - Issue #879

Executive Summary

The plan command (il plan) has minimal research guidance -- three bullet points telling the planner to "explore the codebase" -- while the Analyze agent has a comprehensive 166-line research framework covering problem space, third-party dependencies, and systematic codebase research. This issue adds a planning-adapted version of that research framework to plan-prompt.txt and unblocks the research tools (Context7, ToolSearch) in the plan command's allowed tools whitelist.

Questions and Key Decisions

Question	Answer
Should the research framework be mandatory or optional for the planner?	Mandatory before Phase 2 (Design Exploration), same as the analyzer. The planner should research before decomposing.
Should we add Context7 / ToolSearch to the plan command's allowed tools?	Yes -- the current allowedTools whitelist (plan.ts:468-495) blocks Context7 even if configured. Adding them is required for the third-party research tier to work.
Should the research framework be identical to the analyzer's or adapted?	Adapted for planning context: lighter on regression/historical analysis, heavier on architectural patterns and cross-cutting awareness. The analyze-and-plan agent's lightweight framework is a good model.

Implementation Overview

High-Level Execution Phases

1. Add Research Framework to plan-prompt.txt: Insert structured research guidance into Phase 1 (Understanding) section, adapted from the analyzer's 3-domain framework
2. Update allowed tools in plan.ts: Add Context7 and ToolSearch tools to the allowedTools whitelist so the research framework's third-party research tier actually works
3. Build and verify: Run pnpm build to confirm TypeScript compiles

Quick Stats

• 2 files to modify
• 0 new files to create
• 0 files to delete
• Dependencies: None

---

Complete Analysis and Implementation Details (click to expand)

Research Findings

Problem Space

• Problem: The plan prompt relies on the architect's general knowledge to research before decomposing, with only three bullet points of guidance (plan-prompt.txt:38-40). The analyzer has a proven 3-domain research framework (iloom-issue-analyzer.md:164-330) that produces higher-quality understanding.
• Architectural context: The plan prompt is a Handlebars template rendered by PromptTemplateManager and appended as a system prompt via --append-system-prompt to the Claude CLI session launched by PlanCommand.execute().
• Edge cases:
  • The plan command runs in both interactive mode and autonomous (--yolo) mode. Research guidance must work for both.
  • The plan command can also use Gemini or Codex planners (plan-prompt.txt:9-31). Research guidance should be in a shared section, not within any provider-specific block.
  • Context7/ToolSearch tools may not be configured by all users. The framework must have fallback guidance (WebSearch).

Codebase Research

• Entry point: templates/prompts/plan-prompt.txt:34-41 - "Default Planning (Claude)" section with minimal research guidance
• Phase 1 (Understanding): plan-prompt.txt:155-183 - Currently focused entirely on asking clarifying questions. No structured research.
• Allowed tools whitelist: src/commands/plan.ts:468-495 - Explicitly lists permitted tools. Missing: mcp__context7__resolve-library-id, mcp__context7__get-library-docs, ToolSearch
• Similar patterns:
  • templates/agents/iloom-issue-analyze-and-plan.md:213-247 - Lightweight research framework for SIMPLE tasks, adapted from analyzer
  • templates/agents/iloom-issue-analyzer.md:164-330 - Full Comprehensive Research Framework (3 domains: Problem Space, Third-Party, Codebase)
• Dependencies: plan.ts uses launchClaude() from src/utils/claude.ts:154 which maps allowedTools to --allowed-tools CLI flag

Affected Files

• templates/prompts/plan-prompt.txt:34-41, 155-183 - Needs research framework addition in both the AI Provider section and Phase 1
• src/commands/plan.ts:468-495 - Needs Context7 and ToolSearch added to allowedTools array

Integration Points

• plan-prompt.txt is loaded by PromptTemplateManager.getPrompt('plan', ...) called at plan.ts:461
• The allowedTools array is passed to launchClaude() at plan.ts:511 which maps to --allowed-tools on the Claude CLI
• Existing test at plan.test.ts:264-280 uses arrayContaining so adding new tools won't break it

---

Implementation Plan

Files to Modify

1. templates/prompts/plan-prompt.txt

Change 1 (lines 34-41): Enhance the "Default Planning (Claude)" section to reference structured research in addition to the existing generic guidance.

Replace:

You are the primary planner for this session. Use your capabilities to:
- Gather context by exploring the codebase with Read, Glob, Grep tools
- Use Task subagents for comprehensive research when needed
- Synthesize information into a coherent implementation plan

With guidance that references the new Structured Research Framework section and adds Context7/ToolSearch tool awareness.

Change 2 (lines 155-183): Enhance Phase 1 (Understanding) to include a structured research framework before the clarifying questions section. The new content should be inserted between the Phase 1 header (line 155) and the existing "Ask clarifying questions" content (line 157).

The research framework should include these three domains (adapted from the analyzer's framework):

Domain 1: Problem Space Research

• Understanding the problem domain, user needs, constraints
• Checking README, CLAUDE.md, existing documentation
• Identifying architectural context and constraints
• Edge cases and failure modes

Domain 2: Third-Party Research (when external dependencies involved)

• Research hierarchy: Context7 (primary) then WebSearch (fallback)
• Document API signatures, version-specific notes, common patterns
• Note: Skills tier omitted since the plan command doesn't have Skills access

Domain 3: Codebase Research

• Entry point identification
• Dependency mapping (what uses it, what it uses)
• Pattern recognition (grep for similar implementations)
• Historical context (git blame when unclear)

The framework should emphasize:

• Research BEFORE asking clarifying questions (research informs better questions)
• Using Task subagents for research to keep the main conversation focused on user decisions
• Fallback guidance when tools are unavailable

Key adaptation differences from the analyzer's framework:

• No regression analysis (not relevant for planning)
• No Cross-Cutting Change Analysis section (that's for implementation analysis)
• Lighter overall -- research to inform decomposition, not exhaustive documentation
• Emphasis on using findings to improve issue quality (understanding patterns the child issues should follow)
• Must work for both interactive and autonomous modes

Change 3 (lines 34-41 area): Also enhance the Gemini and Codex planner sections (lines 9-31) to mention the same structured research framework, ensuring all planner providers benefit from the guidance. This is a minor addition -- just referencing that research should happen during Phase 1.

2. src/commands/plan.ts:468-495

Change: Add Context7 and ToolSearch tools to the allowedTools array.

Add after line 487 (WebSearch):

// Context7 research tools (available if user has Context7 configured)
'mcp__context7__resolve-library-id',
'mcp__context7__get-library-docs',
// Tool discovery
'ToolSearch',

Detailed Execution Order

NOTE: These steps are executed in a SINGLE implementation run.

1. Add research framework to plan-prompt.txt

   • Files: templates/prompts/plan-prompt.txt
   • Insert structured research framework into Phase 1 (Understanding) section at line 157
   • Update "Default Planning (Claude)" section at lines 37-40 to reference the framework
   • Verify: Plan prompt contains 3-domain research guidance integrated into Phase 1

2. Add tools to allowed list in plan.ts

   • Files: src/commands/plan.ts
   • Add Context7 tools and ToolSearch to allowedTools array at line 487
   • Verify: allowedTools array includes mcp__context7__resolve-library-id, mcp__context7__get-library-docs, ToolSearch

3. Build and verify

   • Run pnpm build to confirm TypeScript compiles
   • Verify: Build succeeds with no errors

Dependencies and Configuration

None

[acreeger]

Implementation Complete

Summary

Refactored plan command to use the Analyzer agent for research delegation (instead of inlining a duplicate research framework), extracted loadAndPrepare() on AgentManager to DRY up platform-specific agent loading across plan and spin commands, and removed the restrictive allowedTools whitelist from plan mode.

Changes Made

• src/lib/AgentManager.ts: Added loadAndPrepare() method encapsulating load → platform-split (macOS inline vs Linux/Windows disk render) logic
• src/commands/plan.ts: Loads iloom-issue-analyzer agent via loadAndPrepare(), passes to launchClaude. Removed allowedTools whitelist.
• src/commands/ignite.ts: Both execute() and executeSwarmMode() refactored to use loadAndPrepare()
• templates/prompts/plan-prompt.txt: Replaced ~100 lines of inlined research framework with concise instructions to delegate research to the iloom-issue-analyzer agent as a Task subagent
• src/commands/plan.test.ts: Updated agent mocks for loadAndPrepare, added test coverage
• src/commands/ignite.test.ts: Updated ~15 mock agent managers across non-swarm and swarm test paths

Validation Results

• ✅ Tests: 4846 passed / 4846 total
• ✅ Typecheck: Passed
• ✅ Lint: Passed

[acreeger]

iloom Session Summary

Key Themes:

• The plan command now delegates research to the iloom-issue-analyzer agent instead of duplicating its research framework as inline prose
• AgentManager.loadAndPrepare() was extracted to DRY up the platform-specific agent loading pattern that existed in three separate places
• The allowedTools whitelist was removed from the plan command entirely — it was blocking dynamic MCP tools (Gemini, Codex, Context7) that research requires

---

Session Details (click to expand)

Key Insights

• The --allowed-tools flag is a whitelist: only listed tools run without prompting; unlisted tools still require user approval. The --disallowed-tools flag is a hard block: listed tools are removed from the model's context entirely. These have different semantics. For a true capability whitelist, --tools is the correct flag.
• The analyzer agent (iloom-issue-analyzer.md) is deeply instrumented to create and update issue comments as part of its workflow. When launched as a subagent from the plan prompt, the "Do NOT create issue comments" instruction in the Task call is sufficient to suppress this — the subagent prompt takes precedence over the agent's defaults.
• Agent files rendered to disk via renderAgentsToDisk() write to .claude/agents/iloom-*.md. These are already covered by a gitignore pattern (**/.claude/agents/iloom-*) added by the version migration system, so they don't pollute version control.
• AgentManager.loadAgents() mutates the templateVariables object passed to it (via Object.assign). This is currently harmless because callers render their prompt template before calling loadAgents, but it's a latent bug if call order ever changes.

Decisions Made

• Removed allowedTools from plan.ts entirely rather than expanding it. The list was blocking MCP tools (Context7, Gemini, Codex) that are central to the research framework. Since the plan command runs interactively by default, Claude will prompt before using destructive tools anyway. The bypassPermissions path (autoSwarm) is an accepted risk.
• Delegate research via Task subagent to iloom-issue-analyzer rather than inlining a duplicate research framework in the plan prompt. This keeps the research methodology in one place and means improvements to the analyzer automatically benefit planning. The tradeoff is a runtime dependency on the agent being loadable.
• Extracted loadAndPrepare() to AgentManager to encapsulate the macOS-inline vs Linux/Windows-disk-render branching. Both execute() and executeSwarmMode() in ignite.ts, and plan.ts, now call a single method. The swarm path previously used a different targetDir (epicWorktreePath) — this is preserved via the optional targetDir parameter on loadAndPrepare.

Challenges Resolved

• Research framework duplication: The iloom-issue-analyze-and-plan.md agent already had a lightweight adaptation of the analyzer's 3-domain research framework, proving the pattern is portable. This served as the model for how to adapt the analyzer's research approach without carrying over its swarm-specific comment-routing behavior.
• Context7/ToolSearch unavailable in plan: The original allowedTools whitelist didn't include Context7 or ToolSearch tools, so any research guidance referencing them would silently fail. The fix (removing the whitelist) is simpler than maintaining an ever-growing list of approved tools.

Lessons Learned

• When an agent has deeply embedded behavioral defaults (like comment creation), a Task subagent prompt instruction is the correct override mechanism — not disallowedTools or tool restriction.
• The platform split for agent delivery (macOS --agents flag vs Linux .claude/agents/ disk rendering) is a recurring pattern across all commands that launch Claude. Any new command that loads agents should use loadAndPrepare() rather than reimplementing the branching.
• The iloom-*.md gitignore pattern in version migrations means rendered agent files in .claude/agents/ are safe to write from any command context, including non-worktree paths like the main repo root.

---

Generated with 🤖❤️ by iloom.ai