# Feature Proposal: Parallel Plan Deepening > **Priority:** Medium > **Complexity:** Low > **Estimated Effort:** 5-8 days > **Status:** Proposal > **Date:** 2026-02-09 > **Dependencies:** [Knowledge Accumulation](feature-knowledge-accumulation.md) (recommended, not required) > **Related:** [Overview Analysis](compound-engineering-analysis.md) · [Multi-Agent Review](feature-multi-agent-review.md) --- ## Problem Statement Makima's planning phase currently suffers from **single-pass planning**: - A supervisor creates a plan based on its immediate analysis of the task - **No systematic research** is conducted before finalizing the plan - **Edge cases are discovered during execution**, requiring mid-stream plan changes - **Best practices are not consulted** — the plan relies solely on the model's training knowledge - **Existing project learnings** (if the knowledge accumulation feature exists) are not surfaced during planning - **Revision rate is high** — an estimated ~40% of plans require significant changes after execution begins The result: plans are shallow, execution discovers problems that planning should have caught, and contracts take longer than necessary. --- ## How Compound Engineering Solves This The compound engineering plugin's `/deepen-plan` command takes an existing plan and enhances it by spawning **20-40 parallel research agents**: ``` ┌──────────────────────────────────────────────────────────────┐ │ /deepen-plan │ │ │ │ Input: Initial plan (from /plan) │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ Best │ │ Edge │ │ Dep. │ │ Pattern │ │ │ │ Practice │ │ Case │ │ Research │ │ Matching │ │ │ │ Agent 1 │ │ Agent 1 │ │ Agent 1 │ │ Agent 1 │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ │ ┌────┴─────┐ ┌────┴─────┐ ┌────┴─────┐ ┌────┴─────┐ │ │ │ Best │ │ Edge │ │ Security │ │ Existing │ │ │ │ Practice │ │ Case │ │ Concerns │ │ Learning │ │ │ │ Agent 2 │ │ Agent 2 │ │ Agent │ │ Agent │ │ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ │ │ │ │ │ │ ... (20-40 agents per plan item) ... │ │ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Synthesis Agent │ │ │ │ - Merge research into plan │ │ │ │ - Add edge case handling │ │ │ │ - Insert best practice notes │ │ │ │ - Flag risks and dependencies │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ Enhanced Plan (Deepened) │ │ - Original steps preserved │ │ - Edge cases added per step │ │ - Best practices annotated │ │ - Risks flagged │ │ - Dependencies clarified │ └──────────────────────────────────────────────────────────────┘ ``` The key insight: **research is embarrassingly parallel**. Each plan item can be researched independently, and each research dimension (best practices, edge cases, security, etc.) is independent. --- ## Proposed Makima Implementation ### 1. New Supervisor Command: `makima supervisor deepen-plan` ```bash # Deepen the current contract's plan makima supervisor deepen-plan # Deepen with specific focus areas makima supervisor deepen-plan --focus "security,edge-cases,performance" # Deepen with explicit plan file reference makima supervisor deepen-plan --plan-file plan.md # Control parallelism makima supervisor deepen-plan --max-agents 10 # Include knowledge base search (requires Knowledge Accumulation feature) makima supervisor deepen-plan --search-learnings ``` ### 2. Research Agent Categories Each plan item is researched along multiple dimensions: | Agent Category | Purpose | Example Output | |----------------|---------|----------------| | **Best Practices** | Industry standards for the technology/pattern | "Use parameterized queries for all DB operations" | | **Edge Cases** | Boundary conditions and error scenarios | "Handle concurrent modification of shared resource" | | **Dependency Research** | Compatibility, versions, known issues | "Library X v3 has breaking changes from v2" | | **Security Concerns** | Security implications of the planned approach | "JWT stored in localStorage is vulnerable to XSS" | | **Performance Implications** | Performance characteristics and bottlenecks | "N+1 query risk with eager loading disabled" | | **Pattern Matching** | Similar patterns in the existing codebase | "Module Y already implements this pattern; follow its conventions" | | **Existing Learnings** | Prior solutions from knowledge base | "Similar issue solved in contract Z; see docs/solutions/..." | ### 3. Deepening Flow ``` ┌─────────────┐ ┌──────────────────┐ ┌────────────────┐ │ Original │ │ Research Phase │ │ Enhanced Plan │ │ Plan │────▶│ │────▶│ │ │ │ │ Per plan item: │ │ Original + │ │ Step 1 │ │ - Best practices │ │ annotations │ │ Step 2 │ │ - Edge cases │ │ │ │ Step 3 │ │ - Dependencies │ │ Step 1 │ │ Step 4 │ │ - Security │ │ ├ Edge cases │ │ │ │ - Performance │ │ ├ Best pracs │ │ │ │ - Patterns │ │ └ Risks │ │ │ │ - Learnings │ │ Step 2 │ │ │ │ │ │ ├ Edge cases │ │ │ │ All in parallel │ │ └ ... │ └─────────────┘ └──────────────────┘ └────────────────┘ ``` **Implementation using existing infrastructure:** ```bash # Step 1: Parse plan into items plan_items=$(makima supervisor get-plan-items) # Step 2: For each item, spawn research agents as a group for item in $plan_items; do makima supervisor spawn-group "deepen-${item.id}" \ --tasks "[ {\"name\": \"best-practices\", \"plan\": \"Research best practices for: ${item.description}\"}, {\"name\": \"edge-cases\", \"plan\": \"Identify edge cases for: ${item.description}\"}, {\"name\": \"security\", \"plan\": \"Analyze security implications of: ${item.description}\"}, {\"name\": \"performance\", \"plan\": \"Assess performance implications of: ${item.description}\"} ]" \ --share-worktree \ --read-only done # Step 3: Wait for all groups makima supervisor wait-group "deepen-*" --timeout 300 # Step 4: Synthesize results into enhanced plan makima supervisor synthesize-plan ``` ### 4. Enhanced Plan Format The deepened plan augments each step with structured annotations: ```markdown ## Step 3: Implement JWT Authentication ### Original Plan Add JWT-based authentication middleware to the API gateway. Generate tokens on login, validate on each request. ### Research Findings #### Best Practices - Use RS256 (asymmetric) for microservices, HS256 for monoliths - Set short access token TTL (15 min) with refresh token rotation - Include only essential claims (sub, exp, iat, roles) - Never store sensitive data in JWT payload (it's base64, not encrypted) #### Edge Cases - Token expiry during long-running requests - Clock skew between services (use ±30s leeway) - Concurrent refresh token rotation (race condition) - Token size exceeding header limits (>8KB with many claims) #### Security Concerns - **P2**: JWT in localStorage is XSS-vulnerable; prefer httpOnly cookies - **P3**: Missing CSRF protection if using cookies - **P2**: No token revocation mechanism for compromised tokens #### Performance Notes - JWT validation is CPU-bound (RS256 ~1ms per validation) - Consider caching decoded tokens for repeated validation - Refresh token DB lookup adds latency (~5ms) #### Existing Learnings - See: docs/solutions/security-practices/jwt-refresh-token-rotation.md - Previous contract "Auth Service Refactor" used similar pattern ### Risks - [ ] Clock skew handling not in original plan - [ ] Token revocation strategy needed - [ ] CSRF protection if using cookie storage ``` ### 5. Integration with Knowledge Base When the Knowledge Accumulation feature is available, `deepen-plan` automatically includes a **learning search agent** for each plan item: ``` Research Agent: "Search existing learnings relevant to JWT authentication" Results: - docs/solutions/security-practices/jwt-refresh-token-rotation.md (relevance: 0.92) - docs/solutions/api-patterns/authentication-middleware-pattern.md (relevance: 0.78) - docs/solutions/debugging-techniques/token-expiry-debugging.md (relevance: 0.65) ``` These results are included in the deepened plan with direct links. --- ## Integration with Existing Makima Features ### Contract Phases Plan deepening occurs during the **Plan phase**, between initial plan creation and phase transition to Execute: ``` Plan Phase Timeline: 1. Supervisor creates initial plan 2. makima supervisor deepen-plan ← NEW 3. User reviews deepened plan 4. makima supervisor advance-phase execute ``` ### Supervisor/Worker Hierarchy Research agents are spawned as **worker tasks** under the supervisor. Uses the existing `spawn-task` infrastructure with the proposed `spawn-group`/`wait-group` from the [Multi-Agent Review](feature-multi-agent-review.md) proposal. ### Contract Files The deepened plan replaces or augments the plan document as a contract file: ```rust File { contract_id: contract.id, contract_phase: "plan", name: "Implementation Plan (Deepened)", body: vec![ // Enhanced plan content with annotations ], } ``` ### Directive System For directive-based workflows, plan deepening can be added as a step: ```rust DirectiveStep { name: "deepen-plan", description: "Enhance implementation plan with parallel research", depends_on: [initial_plan_step_id], task_plan: "Run deepen-plan on the initial plan...", } ``` ### Phase Guards If `phase_guard` is enabled, the user reviews the deepened plan before approving transition to execute. This is the natural checkpoint for plan quality. --- ## Implementation Plan ### Phase 1: Core Command (2-3 days) | Task | Effort | Description | |------|--------|-------------| | `deepen-plan` command | 1 day | Parse plan, spawn research groups | | Research agent templates | 0.5 days | Default prompts for each category | | Synthesis logic | 1 day | Merge research into annotated plan | | Plan file update | 0.5 days | Write deepened plan as contract file | ### Phase 2: Knowledge Integration (1-2 days) | Task | Effort | Description | |------|--------|-------------| | Learning search agent | 0.5 days | Search knowledge base per plan item | | Result integration | 0.5 days | Include learning links in plan | | Fallback when no KB | 0.5 days | Graceful degradation without KB | ### Phase 3: Configuration & Polish (2-3 days) | Task | Effort | Description | |------|--------|-------------| | Config file support | 0.5 days | `.makima/deepen.yaml` | | Focus area filtering | 0.5 days | `--focus` flag implementation | | Concurrency control | 0.5 days | `--max-agents` limit | | Documentation | 0.5 days | User guide | | Tests | 1 day | Unit + integration | --- ## Configuration Examples ### Repository-Level Configuration ```yaml # .makima/deepen.yaml version: 1 deepen: # Auto-deepen when plan is created auto_trigger: false # Maximum agents per plan item max_agents_per_item: 5 # Total maximum concurrent agents max_concurrent: 20 # Timeout per research agent (seconds) agent_timeout: 120 # Research dimensions to include dimensions: - best-practices - edge-cases - security - performance - dependencies - patterns - learnings # Requires Knowledge Accumulation # Minimum plan items to trigger deepening min_plan_items: 3 # Search learnings (requires Knowledge Accumulation) search_learnings: true search_min_relevance: 0.5 ``` ### Inline Usage ```bash # Quick deepen with defaults makima supervisor deepen-plan # Focused deepen for security-sensitive work makima supervisor deepen-plan --focus security,edge-cases # Deepen with more agents for complex plans makima supervisor deepen-plan --max-agents 30 # Deepen without knowledge base search makima supervisor deepen-plan --no-learnings ``` --- ## Open Questions 1. **Plan format parsing**: How should the system parse existing plans to identify discrete items? Markdown headers? Numbered lists? YAML structure? 2. **Research depth vs. cost**: 20-40 agents per deepening is expensive. Should there be a "lite" mode with fewer agents? 3. **Deepening multiple times**: Can a plan be deepened iteratively? Should subsequent deepenings build on previous research? 4. **User-provided context**: Should users be able to provide additional context (e.g., "this project uses PostgreSQL, not MySQL") to guide research? 5. **Codebase analysis**: Should research agents analyze the existing codebase to find relevant patterns, or only reason from general knowledge? 6. **Conflicting research**: When research agents disagree (e.g., one says "use Redis" and another says "avoid Redis"), how should the synthesis handle it? --- ## Alternatives Considered | Alternative | Pros | Cons | Decision | |-------------|------|------|----------| | Sequential research (one agent) | Simple, cheaper | Slow; misses multi-perspective insights | Rejected — parallel is core value | | Automatic deepening (always on) | No manual step | Adds latency to every plan; unnecessary for simple tasks | Optional auto-trigger | | Web search integration | Real-time information | Inconsistent quality; potential hallucination from web results | Deferred — consider for v2 | | User-provided research questions | Targeted research | Requires user to know what to ask | Complement — support alongside auto-research | | LLM-only research (no task spawning) | Simpler, no infrastructure | Limited by single context window; no parallelism | Rejected — defeats the purpose | --- ## Priority & Complexity Assessment - **Priority: MEDIUM** — Plan deepening significantly improves plan quality, but it's enhancement over an already-functional planning workflow. The compound engineering plugin's data shows ~40% plan revision reduction. - **Complexity: LOW** — This feature is largely a composition of existing primitives (task spawning, group waiting, plan file updates). The main new work is research agent prompts and synthesis logic. - **Risk: LOW** — Worst case is slightly better plans. No system changes required. Can be adopted incrementally.