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.