Optimize plan generation: Modular task files + orchestrator for 90%+ token reduction in subagent-driven development

[seanGSISG]

Is your feature request related to a problem? Please describe.

When using /superpowers:write-plan, the skill generates a single, often lengthy markdown file containing the entire implementation plan. This becomes problematic when executing the plan with /superpowers:execute-plan and the subagent-driven-development skill, because each subagent loads the FULL context of the entire plan, resulting in significant token waste.

For example, a 13-task implementation plan might be 2000+ lines. If you dispatch 13 subagents, you're loading that full 2000+ line plan 13 times, when each subagent only needs context for its specific task (typically 50-200 lines).

Token waste calculation example:

• Monolithic plan: 2000 lines × 13 subagents = 26,000 lines loaded
• Modular approach: 150 lines per task × 13 subagents = 1,950 lines loaded
• Savings: ~92% reduction in redundant context loading

Describe the solution you'd like

Primary Solution: Modular Task Files by Default

When /superpowers:write-plan is executed, it should:

1. Create a dedicated subdirectory in docs/plans/ named after the plan:

docs/plans/[plan-name]/
     ├── index.md              # Navigation table, quick start, architecture summary
     ├── 00-overview.md        # Executive summary, prerequisites, data models
     ├── task-01-[name].md     # Individual task file
     ├── task-02-[name].md
     ├── ...
     ├── task-N-[name].md
     ├── rollback-plan.md      # Recovery procedures
     ├── troubleshooting.md    # Common issues & solutions
     └── references.md         # Links, completion checklist

2. Each task file should contain:

• Objective (1-2 sentences)
• Prerequisites
• Step-by-step instructions with expected outputs
• Verification commands
• Code review checkpoint indicator
• Estimated time

3. The index.md should provide:

• Navigation table with task numbers, files, descriptions, and time estimates
• Quick start instructions
• Architecture summary
• Execution approach guidance
• Status tracking template (TodoWrite compatible)

Example task file structure:

### Task 7: Backend Azure AD Token Verification

**Objective:** Implement Azure AD ID token verification with signature validation and claims extraction.

**Prerequisites:**
- Task 1-2 complete (Azure AD groups configured)
- Python packages: PyJWT, cryptography

**Steps:**

1. **Create token verification service:**

```python
# backend/app/services/azure_ad_token_verifier.py
# [detailed implementation steps]


Expected Output:
✓ File created: backend/app/services/azure_ad_token_verifier.py

2. Write unit tests (TDD - RED):
[test code]
3. Implement to pass tests (TDD - GREEN):
[implementation code]

Verification:
cd backend && pytest tests/services/test_azure_ad_token_verifier.py -v

Expected Output:
test_verify_valid_token PASSED
test_verify_expired_token PASSED
test_verify_invalid_signature PASSED

Code Review Checkpoint: Yes (critical security component)

Estimated Time: 1 hour

Benefits:

• Token efficiency: Subagents load only relevant task context (90%+ reduction)
• Clarity: Each subagent has a clear, focused mission
• Maintainability: Update individual tasks without affecting others
• Reusability: Tasks can be referenced independently
• Progress tracking: Easier to mark completed tasks
• Parallel execution: Multiple agents can work simultaneously without context conflicts

---

Secondary Solution: Master Orchestrator with Inter-Agent Handoffs

For tasks requiring sequential, synchronized execution, introduce a Master Orchestrator agent that coordinates between subagents and manages handoff documents.

Directory Structure:

docs/plans/[plan-name]/
  ├── orchestrator-instructions.md  # Master orchestrator prompt
  ├── handoffs/
  │   ├── task-01-to-02.md         # Handoff from task 1 to task 2
  │   ├── task-02-to-03.md         # Handoff from task 2 to task 3
  │   └── ...
  └── templates/
      ├── orchestrator-prompt.md    # Template for orchestrator agent
      ├── backend-agent-prompt.md   # Template for backend specialist
      ├── frontend-agent-prompt.md  # Template for frontend specialist
      └── test-agent-prompt.md      # Template for test specialist

Orchestrator Responsibilities:

1. Sequential Coordination:

   • Launch Agent 1 with task-01 context
   • Monitor Agent 1 completion
   • Extract handoff information from Agent 1's output
   • Forward to Agent 2 with task-02 context

2. Handoff Document Generation: After each agent completes, orchestrator creates handoff document containing:

   • Files Created/Modified: List with paths and purposes
   • Shared Utilities: New helper functions, services, or components available
   • Configuration Changes: Environment variables, dependencies, API endpoints
   • Key Decisions: Architectural choices that affect downstream work
   • Test Results: Pass/fail status, coverage metrics
   • Blockers/Warnings: Issues future agents should be aware of
   • Next Agent Context: What the next agent needs to know

2. Context Extraction:

Orchestrator intelligently parses agent output to extract:

# Handoff: Task 4 (MSAL Config) → Task 5 (Login Component)

## Task 4 Completion Summary
- ✅ Status: Complete
- 🕐 Duration: 28 minutes

## Files Created
- @frontend/src/config/msalConfig.ts      # MSAL instance configuration
- @frontend/src/contexts/AuthContext.tsx  # Auth context provider
- @frontend/src/types/auth.types.ts       # TypeScript type definitions

## Shared Utilities Available
- `useMsal()` hook - Access MSAL instance and accounts
- `useAuth()` hook - Higher-level auth state management
- `msalInstance` - Pre-configured MSAL PublicClientApplication

## Configuration
- Added env vars: `VITE_AZURE_CLIENT_ID`, `VITE_AZURE_TENANT_ID`
- MSAL redirect URI: `http://localhost:5173/auth/callback`

## Key Decisions
- Using redirect flow (not popup) for better mobile support
- Storing tokens in sessionStorage (MSAL default)
- Auth state persists across page refreshes

## Test Results
✓ MSAL configuration validates correctly
✓ Auth context provider renders without errors
✓ Hooks return expected shape

## For Next Agent (Task 5 - Login Component)
- Import `useAuth()` from `@/contexts/AuthContext`
- Use `msalInstance.loginRedirect()` for sign-in button
- Check `isAuthenticated` state before showing user info
- Access user via `account.name` and `account.username`

## Error Propagation:
If Agent N fails, orchestrator:
- Captures error context
- Determines if subsequent agents can proceed
- May roll back or adjust plan dynamically

4. Orchestrator Instruction Template:

# Master Orchestrator Guide

You coordinate the sequential execution of tasks for the [PLAN_NAME] implementation, handle agent handoffs, and preserve shared context.

---
## Directory
Plan files live at: `docs/plans/[plan-name]/`
---

## Core Responsibilities
- Execute tasks in order
- Spin up the correct specialist agent for each task
- Track completion criteria
- Generate and save handoff files
- Maintain global state and key decisions

---

## Orchestration Loop

For each task:

### 1) Launch Specialist Agent
- Load task file: task-XX-[name].md
- Provide previous handoff (if any)
- Specify agent type (Backend / Frontend / Test)

### 2) Verify Completion
- Confirm task finished successfully
- Validate against acceptance criteria
- Capture all deliverables

### 3) Produce Handoff Package
Document:
- Files created/updated (with paths)
- Shared utilities (functions/hooks/services)
- Config changes (env vars, deps)
- Architectural decisions
- Test results
- Warnings / prep notes for next agent

Save handoff to: `docs/plans/[plan-name]/handoffs/task-XX-to-YY.md`

### 4) Transfer to Next Agent
Provide:
- Next task file (task-YY-[name].md)
- Previous handoff file
- Relevant excerpts from older handoffs if useful

### 5) Maintain Global Context
Track:
- All created/modified files
- All shared utilities available
- All configuration updates
- Cross-task architecture decisions

---

## Decision Rules

### Run Sequentially When
- Output feeds next task
- Shared files or state involved
- Integration or testing required

### Run in Parallel When
- Tasks are independent
- No shared file modifications
- Later merge is safe

### Pause When
- Critical failure
- Blocker discovered
- Human intervention required

---

## Success Criteria
- Tasks complete in correct order
- Handoff docs contain the essentials only
- No duplicated work
- Each agent gets exactly the context they need

Benefits of Orchestrator Approach:

• Reduced cognitive load: Each agent focuses on one task, orchestrator manages the big picture
• Context efficiency: Agents receive only relevant previous work, not entire plan history
• Automatic documentation: Handoffs create audit trail of implementation
• Error recovery: Orchestrator can retry or adjust strategy on failures
• Parallel optimization: Orchestrator identifies opportunities to run independent tasks concurrently

Describe alternatives you've considered

1. Manual plan splitting: Users manually split plans after generation (tedious, error-prone)
2. Context truncation: Intelligently truncate plan context per subagent (risky, might lose important cross-task dependencies)
3. Single-agent execution: Avoid subagent-driven-development entirely (slower, less parallelizable)
4. Agent-to-agent direct communication: Agents communicate directly without orchestrator (complex, hard to debug, no central coordination)

All alternatives are inferior to generating modular plans with orchestrated execution by default.

---

Additional context

Current workflow (inefficient): Generate monolithic plan (2000+ lines) /superpowers:write-plan

Execute with subagents (loads full 2000+ lines per agent) /superpowers:execute-plan --skill subagent-driven-development

Desired workflow (efficient): Generate modular plan with orchestration support /superpowers:write-plan --name entra-id-sso --with-orchestrator

Execute with orchestrated subagents /superpowers:execute-plan --skill subagent-driven-development --plan docs/plans/entra-id-sso/ --orchestrated

Orchestrator automatically:

1. Launches Task 1 agent
2. Captures output, generates handoff
3. Launches Task 2 agent with Task 1 handoff
4. Repeats until all tasks complete

---

Implementation considerations:

• Backward compatibility: Keep option to generate monolithic plans with --monolithic flag
• Plan naming: Auto-generate directory name from plan title or accept --name parameter
• Task numbering: Zero-padded (task-01, task-02, ..., task-13) for proper sorting
• Index generation: Auto-update index.md when tasks are added/modified
• Orchestrator mode: Make --with-orchestrator opt-in initially, default later for sequential plans
• Handoff format: Standardized markdown structure for machine-readable parsing
• Parallel detection: Orchestrator automatically identifies tasks that can run concurrently

Real-world use case:

A 13-task SSO implementation plan:

• Without orchestrator: Each of 13 agents loads 2000-line monolithic plan (26,000 lines total)
• With modular tasks only: Each of 13 agents loads 150-line task file (1,950 lines total) - 92% savings
• With modular + orchestrator: Each agent loads 150-line task + 300-line handoff from previous agent (5,850 lines total) - 77% savings vs monolithic, but with much better context quality

Why orchestrator is worth the extra tokens:

• The handoff documents provide high-signal context (files created, utilities available) vs. low-signal context (entire plan including irrelevant tasks). - - Agent receives exactly what it needs from previous work without having to parse through unrelated tasks.

Impact:

• This change would make subagent-driven development significantly more efficient and practical for large, multi-task implementation plans, while improving coordination quality through structured handoffs.

[coderabbitai[bot]]

A summary of the changes CodeRabbit can apply:

• Implement the Modular Plan Generation System by adding 10 new files (skills/writing-modular-plans/SKILL.md; skills/writing-orchestrator-plans/SKILL.md; skills/commands/write-modular-plan.md; skills/writing-modular-plans/MIGRATION-GUIDE.md; skills/writing-modular-plans/examples/README.md; IMPLEMENTATION-SUMMARY.md; FEATURE-IMPLEMENTATION.md; IMPLEMENTATION-COMPLETE.md; SUGGESTED-COMMIT-MESSAGE.txt; and the modular plan directory structure under docs/plans/ with index/overview/task files and optional orchestrator/handoffs/templates), and updating README.md (+34 lines), to enable subagent execution with individual 150-line task files (achieving ~92% token reduction), maintain backward compatibility, and provide migration guides, examples, and commit instructions.

• Implement a modular plan generation system (adds skills/writing-modular-plans, skills/writing-orchestrator-plans, skills/commands/write-modular-plan, MIGRATION-GUIDE, examples, IMPLEMENTATION-SUMMARY.md, FEATURE-IMPLEMENTATION.md, IMPLEMENTATION-COMPLETE.md, SUGGESTED-COMMIT-MESSAGE.txt) and update README.md to introduce "Modular Plans (v3.5+)", enabling per-task files and optional orchestrator handoffs to reduce subagent token usage by ~92% while remaining backward-compatible with monolithic plans.

• [ ] ✅ Create PR with these edits
• [ ] 📋 Get copyable edits

[jrevillard]

This would be really nice indeed...

[obra]

I don't actually believe that loading the full plan context is necessarily a "waste" of tokens. There's some value to the subagents actually seeing what the rest of the plan looks like, what they should be expecting from setup, and what is not their job. That said, it's worth testing. There's another way to implement this that might be more straightforward: having the architect/orchestrator tell the subagents the line ranges of the plan file to read to get their direct context.

[seanGSISG]

That's a good point about there may be some value for the agents knowing what to expect etc. However, that is kind of the whole point of the orchestrator, no? It should provide any and all valuable information like that.

Telling the line numbers is a great idea. I have been testing it out with the orchestrator idea and it's been working relatively well. I found that when I altered the writing-plans skill to break up the plan into individual task files that it dramatically increased the time to create the plans. Claude is much better outputting it all to one file. So referencing line numbers or creating some sort of a scripted parser to break up the plans is definitely the way to go.