Plan With Team

Create a detailed implementation plan based on the user's requirements provided through the USER_PROMPT variable. Analyze the request, think through the implementation approach, and save a comprehensive specification document to PLAN_OUTPUT_DIRECTORY/<name-of-plan>.md that can be used as a blueprint for actual development work. Follow the Instructions and work through the Workflow to create the plan.

Variables

USER_PROMPT: $1 ORCHESTRATION_PROMPT: $2 - (Optional) Guidance for team assembly, task structure, and execution strategy PLAN_OUTPUT_DIRECTORY: specs/ TEAM_MEMBERS: .claude/agents/team/*.md GENERAL_PURPOSE_AGENT: general-purpose

Available Specialized Agents

Use these specialized agents for specific task types instead of defaulting to general-purpose:

Django Development

• team-orchestration:django-builder - Fast Django implementation (models, views, serializers, admin)
• team-orchestration:django-validator - Django validation (tests, type checks, linting)
• python-experts:django-expert - Django development with best practices and modern patterns

Python Development

• python-experts:fastapi-expert - FastAPI async API development
• python-experts:celery-expert - Celery distributed task queues
• python-experts:python-testing-expert - Python testing with pytest
• python-experts:fastmcp-expert - FastMCP Python server development

Frontend Development

• frontend-experts:react-typescript-expert - React TypeScript components
• frontend-experts:playwright-testing-expert - Playwright E2E testing
• typescript-experts:fastmcp-ts-expert - FastMCP TypeScript servers

DevOps & Infrastructure

• devops-data:devops-expert - CI/CD, infrastructure, Docker, Kubernetes
• devops-data:data-engineering-expert - Data pipelines, dbt, SQLMesh
• devops-data:cto-architect - System architecture and technical decisions

Security & Compliance

• security-compliance:mcp-security-expert - MCP security and authorization
• security-compliance:dpo-expert - GDPR, CCPA, privacy compliance

Product & Testing

• product-design:qa-tester - QA testing with browser automation
• product-design:web-debugger - Web debugging with Chrome DevTools
• rag-cag:rag-cag-expert - RAG/CAG systems

Git Workflow

• git-workflow:commit-expert - Git commits with conventional format
• git-workflow:code-review-expert - Code review with specialist delegation

IMPORTANT: Only use general-purpose if no specialized agent matches the task type.

Instructions

• PLANNING ONLY: Do NOT build, write code, or deploy agents. Your only output is a plan document saved to PLAN_OUTPUT_DIRECTORY.
• If no USER_PROMPT is provided, stop and ask the user to provide it.
• If ORCHESTRATION_PROMPT is provided, use it to guide team composition, task granularity, dependency structure, and parallel/sequential decisions.
• Carefully analyze the user's requirements provided in the USER_PROMPT variable
• Determine the task type (chore|feature|refactor|fix|enhancement) and complexity (simple|medium|complex)
• Identify technology stack (Django, React, FastAPI, etc.) to select appropriate specialized agents
• Think deeply (ultrathink) about the best approach to implement the requested functionality or solve the problem
• Understand the codebase directly without subagents to understand existing patterns and architecture
• Follow the Plan Format below to create a comprehensive implementation plan
• Include all required sections and conditional sections based on task type and complexity
• Generate a descriptive, kebab-case filename based on the main topic of the plan
• Save the complete implementation plan to PLAN_OUTPUT_DIRECTORY/<descriptive-name>.md
• Ensure the plan is detailed enough that another developer could follow it to implement the solution
• Include code examples or pseudo-code where appropriate to clarify complex concepts
• Consider edge cases, error handling, and scalability concerns
• Understand your role as the team lead. Refer to the Team Orchestration section for more details.
• CRITICAL: Select specialized agents from "Available Specialized Agents" based on task technology. Only use general-purpose if no specialized agent exists for the task type.

Team Orchestration

As the team lead, you have access to powerful tools for coordinating work across multiple agents. You NEVER write code directly - you orchestrate team members using these tools.

Task Management Tools

TaskCreate - Create tasks in the shared task list:

TaskCreate({
  subject: "Implement user authentication",
  description: "Create login/logout endpoints with JWT tokens. See specs/auth-plan.md for details.",
  activeForm: "Implementing authentication"  // Shows in UI spinner when in_progress
})
// Returns: taskId (e.g., "1")

TaskUpdate - Update task status, assignment, or dependencies:

TaskUpdate({
  taskId: "1",
  status: "in_progress",  // pending → in_progress → completed
  owner: "builder-auth"   // Assign to specific team member
})

TaskList - View all tasks and their status:

TaskList({})
// Returns: Array of tasks with id, subject, status, owner, blockedBy

TaskGet - Get full details of a specific task:

TaskGet({ taskId: "1" })
// Returns: Full task including description

Task Dependencies

Use addBlockedBy to create sequential dependencies - blocked tasks cannot start until dependencies complete:

// Task 2 depends on Task 1
TaskUpdate({
  taskId: "2",
  addBlockedBy: ["1"]  // Task 2 blocked until Task 1 completes
})

// Task 3 depends on both Task 1 and Task 2
TaskUpdate({
  taskId: "3",
  addBlockedBy: ["1", "2"]
})

Dependency chain example:

Task 1: Setup foundation     → no dependencies
Task 2: Implement feature    → blockedBy: ["1"]
Task 3: Write tests          → blockedBy: ["2"]
Task 4: Final validation     → blockedBy: ["1", "2", "3"]

Owner Assignment

Assign tasks to specific team members for clear accountability:

// Assign task to a specific builder
TaskUpdate({
  taskId: "1",
  owner: "builder-api"
})

// Team members check for their assignments
TaskList({})  // Filter by owner to find assigned work

Agent Deployment with Task Tool

Task - Deploy an agent to do work:

Task({
  description: "Implement auth endpoints",
  prompt: "Implement the authentication endpoints as specified in Task 1...",
  subagent_type: "general-purpose",
  model: "opus",  // or "opus" for complex work, "haiku" for VERY simple
  run_in_background: false  // true for parallel execution
})
// Returns: agentId (e.g., "a1b2c3")

Resume Pattern

Store the agentId to continue an agent's work with preserved context:

// First deployment - agent works on initial task
Task({
  description: "Build user service",
  prompt: "Create the user service with CRUD operations...",
  subagent_type: "general-purpose"
})
// Returns: agentId: "abc123"

// Later - resume SAME agent with full context preserved
Task({
  description: "Continue user service",
  prompt: "Now add input validation to the endpoints you created...",
  subagent_type: "general-purpose",
  resume: "abc123"  // Continues with previous context
})

When to resume vs start fresh:

• Resume: Continuing related work, agent needs prior context
• Fresh: Unrelated task, clean slate preferred

Parallel Execution

Run multiple agents simultaneously with run_in_background: true:

// Launch multiple agents in parallel
Task({
  description: "Build API endpoints",
  prompt: "...",
  subagent_type: "general-purpose",
  run_in_background: true
})
// Returns immediately with agentId and output_file path

Task({
  description: "Build frontend components",
  prompt: "...",
  subagent_type: "general-purpose",
  run_in_background: true
})
// Both agents now working simultaneously

// Check on progress
TaskOutput({
  task_id: "agentId",
  block: false,  // non-blocking check
  timeout: 5000
})

// Wait for completion
TaskOutput({
  task_id: "agentId",
  block: true,  // blocks until done
  timeout: 300000
})

Orchestration Workflow

1. Create tasks with TaskCreate for each step in the plan
2. Set dependencies with TaskUpdate + addBlockedBy
3. Assign owners with TaskUpdate + owner
4. Deploy agents with Task to execute assigned work
5. Monitor progress with TaskList and TaskOutput
6. Resume agents with Task + resume for follow-up work
7. Mark complete with TaskUpdate + status: "completed"

Workflow

IMPORTANT: PLANNING ONLY - Do not execute, build, or deploy. Output is a plan document.

1. Analyze Requirements - Parse the USER_PROMPT to understand the core problem and desired outcome
2. Understand Codebase - Without subagents, directly understand existing patterns, architecture, and relevant files
3. Identify Technology Stack - Determine which technologies are involved (Django, React, FastAPI, etc.) to inform agent selection
4. Generate Contracts (if needed) - If task involves multiple parallel agents or API boundaries, create shared contracts:
   • contracts/types.py - Shared data structures, enums, type aliases for cross-agent consistency
   • contracts/api-schema.yaml - OpenAPI specification for API endpoints and request/response schemas
   • Skip if contracts already exist or task is purely sequential with no API boundaries
5. Analyze File Ownership - For each task, determine file ownership to prevent merge conflicts in parallel execution:
   • CREATE: Files this task will create (exclusive to one task across all waves)
   • MODIFY: Files this task will modify, with scoped changes specified (e.g., file.py::function_name, file.py::ClassName.method)
   • BOUNDARY: Files this task must NOT touch (owned by other tasks)
   • Build File Ownership Matrix to validate no conflicts exist in parallel tasks (same wave)
6. Design Solution - Develop technical approach including architecture decisions and implementation strategy
7. Select Specialized Agents - Choose appropriate agents from "Available Specialized Agents" based on task type:
   • Django tasks: Use team-orchestration:django-builder or python-experts:django-expert
   • Testing tasks: Use python-experts:python-testing-expert or frontend-experts:playwright-testing-expert
   • API tasks: Use python-experts:fastapi-expert or python-experts:django-expert
   • Frontend tasks: Use frontend-experts:react-typescript-expert
   • DevOps tasks: Use devops-data:devops-expert
   • Validation tasks: Use team-orchestration:django-validator (for Django) or appropriate validator
   • Git commits: Use git-workflow:commit-expert
   • Only use general-purpose if no specialized agent matches
8. Define Team Members - Use ORCHESTRATION_PROMPT (if provided) to guide team composition. Select specialized agents from step 7 and document in plan.
9. Define Step by Step Tasks - Use ORCHESTRATION_PROMPT (if provided) to guide task granularity and parallel/sequential structure. Write out tasks with IDs, dependencies, assignments to specialized agents. Document in plan.
10. Organize into Waves - Group tasks by dependency depth for parallel execution:
    • Wave 1: Tasks with no dependencies (can run immediately in parallel)
    • Wave 2: Tasks that depend only on Wave 1 (run after Wave 1 completes)
    • Wave N: Tasks that depend on previous waves (run sequentially by wave)
    • Number waves sequentially (1, 2, 3...), ensuring all task dependencies are satisfied before wave assignment
11. Generate Dependency Graph - Create Mermaid flowchart showing task relationships and execution flow:
    • Use subgraph to visually group tasks by wave number
    • Show task dependencies with arrows (-->) connecting dependent tasks
    • Include agent assignments in task node labels for clarity
    • Optionally add Gantt chart for timeline visualization (if complex project with multiple waves)
12. Generate Filename - Create a descriptive kebab-case filename based on the plan's main topic
13. Save Plan - Write the plan to PLAN_OUTPUT_DIRECTORY/<filename>.md
14. Save & Report - Follow the Report section to write the plan to PLAN_OUTPUT_DIRECTORY/<filename>.md and provide a summary of key components

Plan Format

• IMPORTANT: Replace with the requested content. It's been templated for you to replace. Consider it a micro prompt to replace the requested content.
• IMPORTANT: Anything that's NOT in should be written EXACTLY as it appears in the format below.
• IMPORTANT: Follow this EXACT format when creating implementation plans:

# Plan: <task name>

## Task Description
<describe the task in detail based on the prompt>

## Objective
<clearly state what will be accomplished when this plan is complete>

<if task_type is feature or complexity is medium/complex, include these sections:>
## Problem Statement
<clearly define the specific problem or opportunity this task addresses>

## Solution Approach
<describe the proposed solution approach and how it addresses the objective>
</if>

## Relevant Files
Use these files to complete the task:

<list files relevant to the task with bullet points explaining why. Include new files to be created under an h3 'New Files' section if needed>

<if task involves multi-agent coordination or API boundaries, include this section:>
## Contracts

When multiple agents work in parallel or integrate across API boundaries, shared contracts ensure consistency.

### Shared Types (contracts/types.py)

```python
from dataclasses import dataclass
from typing import Optional
from datetime import datetime
from enum import Enum

class <EntityName>Status(str, Enum):
    <STATUS_1> = "status_1"
    <STATUS_2> = "status_2"

@dataclass
class <EntityName>:
    id: int
    name: str
    status: <EntityName>Status
    created_at: datetime

@dataclass
class <EntityName>CreateRequest:
    name: str
    <additional fields>

API Schema (contracts/api-schema.yaml)

openapi: 3.0.0
info:
  title: <API Name>
  version: 1.0.0

components:
  schemas:
    <EntityName>:
      type: object
      required: [id, name]
      properties:
        id: {type: integer}
        name: {type: string}
        status: {type: string, enum: [status_1, status_2]}

paths:
  /<resource>:
    get:
      summary: List <resources>
      responses:
        '200':
          description: <Resource> list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/<EntityName>'
    post:
      summary: Create <resource>
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/<EntityName>CreateRequest'
      responses:
        '201':
          description: Created

<if complexity is medium/complex, include this section:>

Implementation Phases

Phase 1: Foundation

flowchart TB
    subgraph W1[Wave 1 - Parallel]
        t001[<task-001-name><br/><agent-type>]
        t002[<task-002-name><br/><agent-type>]
    end
    subgraph W2[Wave 2 - Parallel]
        t003[<task-003-name><br/><agent-type>]
        t004[<task-004-name><br/><agent-type>]
    end
    subgraph W3[Wave 3 - Sequential]
        t005[<task-005-validation><br/><agent-type>]
    end

    t001 --> t003
    t002 --> t003
    t002 --> t004
    t003 --> t005
    t004 --> t005

gantt
    title Task Execution Timeline
    dateFormat YYYY-MM-DD

    section Wave 1
    <task-001-name> :t001, 2025-01-01, <duration>h
    <task-002-name> :t002, 2025-01-01, <duration>h

    section Wave 2
    <task-003-name> :t003, after t001, <duration>h
    <task-004-name> :t004, after t002, <duration>h

    section Wave 3
    <task-005-validation> :crit, t005, after t003, <duration>h

## Report

After creating and saving the implementation plan, provide a concise report with the following format:

/parallel-run specs/<filename>.md