home / skills / am-will / codex-skills / swarm-planner

swarm-planner skill

safe

This skill helps design dependency-aware plans for parallel multi-agent execution in Python projects, optimizing task parallelism and clear dependencies.

npx playbooks add skill am-will/codex-skills --skill swarm-planner

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

5.4 KB

---
name: swarm-planner
description: >
  [EXPLICIT INVOCATION ONLY] Creates dependency-aware implementation plans optimized for parallel
  multi-agent execution.
metadata:
  invocation: explicit-only
---

# Swarm-Ready Planner

Create implementation plans with explicit task dependencies optimized for parallel agent execution. This skill can be ran inside or outside of Plan Mode. 

## Core Principles

1. **Explore Codebase**: Investigate architecture, patterns, existing implementations, dependencies, and frameworks in use.
2. **Fresh Documentation First**: Use Context7 for ANY external library, framework, or API before planning tasks
3. **Ask Questions**: Clarify ambiguities and seek clarification on scope, constraints, or priorities throughout the planning process. At any time.
4. **Explicit Dependencies**: Every task declares what it depends on, enabling maximum parallelization
5. **Atomic Tasks**: Each task is independently executable by a single agent
6. **Review Before Yield**: A subagent reviews the plan for gaps before finalizing

## Process

### 1. Research

**Codebase investigation:**
- Architecture, patterns, existing implementations
- Dependencies and frameworks in use

### 1a. Optional: Stop to Clarification Questions

- If the architecture is unclear or missing STOP AND YIELD to the user, and request user input (AskUserQuestions) before moving on. Always offer recommendations for clarification questions.
- If architecture is present, skip 1a and move onto next step. 

### 2. Documentation

**Documentation retrieval (REQUIRED for external dependencies):**

Use Context7 skill or MCP to fetch current docs for any libraries/frameworks or APIs that are or will be used in project. If Context7 is not available, use web search.

This ensures version-accurate APIs, correct parameters, and current best practices.

### 3. STOP and Request User Input

When anything is unclear or could reasonably be done multiple ways:
- Stop and ask clarifying questions immediately
- Do not make assumptions about scope, constraints, or priorities
- Questions should reduce risk and eliminate ambiguity
- Always offer recommendations for clarification questions.
- Use request_user_input or AskUserQuestion tool if available. 

### 4. Create Dependency-Aware Plan

Structure the plan with explicit task dependencies using this format:

#### Task Dependency Format

Each task MUST include:
- **id**: Unique identifier (e.g., `T1`, `T2.1`)
- **depends_on**: Array of task IDs that must complete first (empty `[]` for root tasks)
- **description**: What the task accomplishes
- **location**: File paths involved
- **validation**: How to verify completion

**Example:**
```
T1: [depends_on: []] Create database schema migration
T2: [depends_on: []] Install required packages
T3: [depends_on: [T1]] Create repository layer
T4: [depends_on: [T1]] Create service interfaces
T5: [depends_on: [T3, T4]] Implement business logic
T6: [depends_on: [T2, T5]] Add API endpoints
T7: [depends_on: [T6]] Write integration tests
```

Tasks with empty/satisfied dependencies can run in parallel (T1, T2 above).

### 4. Save Plan

Save to `<topic>-plan.md` in the CWD.

### 5. Subagent Review

After saving, spawn a subagent to review the plan:

```
Review this implementation plan for:
1. Missing dependencies between tasks
2. Ordering issues that would cause failures
3. Missing error handling or edge cases
4. Gaps, holes, gotchas.

Provide specific, actionable feedback. Do not ask questions.

Plan location: [file path]
Context: [brief context about the task]
```

If the subagent provides actionable feedback, revise the plan before yielding.


## Plan Template

```markdown
# Plan: [Task Name]

**Generated**: [Date]

## Overview
[Summary of task and approach]

## Prerequisites
- [Tools, libraries, access needed]

## Dependency Graph

```
[Visual representation of task dependencies]
T1 ──┬── T3 ──┐
     │        ├── T5 ── T6 ── T7
T2 ──┴── T4 ──┘
```

## Tasks

### T1: [Name]
- **depends_on**: []
- **location**: [file paths]
- **description**: [what to do]
- **validation**: [how to verify]
- **status**: Not Completed
- **log**: [leave empty, to be filled out later]
- **files edited/created**: [leave empty, to be filled out later]

### T2: [Name]
- **depends_on**: []
- **location**: [file paths]
- **description**: [what to do]
- **validation**: [how to verify]
- **status**: Not Completed
- **log**: [leave empty, to be filled out later]
- **files edited/created**: [leave empty, to be filled out later]

### T3: [Name]
- **depends_on**: [T1]
- **location**: [file paths]
- **description**: [what to do]
- **validation**: [how to verify]
- **status**: Not Completed
- **log**: [leave empty, to be filled out later]
- **files edited/created**: [leave empty, to be filled out later]

[... continue for all tasks ...]

## Parallel Execution Groups

| Wave | Tasks | Can Start When |
|------|-------|----------------|
| 1 | T1, T2 | Immediately |
| 2 | T3, T4 | Wave 1 complete |
| 3 | T5 | T3, T4 complete |
| ... | ... | ... |

## Testing Strategy
- [How to test]
- [What to verify]

## Risks & Mitigations
- [What could go wrong + how to handle]
```

## Important

- Every task must have explicit `depends_on` field
- Root tasks (no dependencies) can be executed in parallel immediately
- Do NOT implement - only create the plan
- Always use Context7 for external dependencies before finalizing tasks
- Always ask questions where ambiguity exists

Overview

This skill creates dependency-aware implementation plans optimized for parallel multi-agent execution. It inspects project structure, external libraries, and constraints to produce atomic, reviewable tasks with explicit dependencies and validation criteria. Plans are saved as markdown and reviewed by a subagent before final delivery.

How this skill works

The skill inspects the codebase to identify architecture, patterns, dependencies, and relevant files, then uses Context7 for up-to-date documentation on any external libraries or APIs. It generates a task graph where each task has an id, depends_on list, location, description, and validation steps. After saving the plan to a topic-based markdown file, a subagent reviews the plan for missing dependencies, ordering issues, and gaps; actionable feedback is incorporated before yielding the final plan.

When to use it

When you need a parallel-executable implementation plan for a code change, feature, or integration.
When multiple agents will execute tasks concurrently and explicit dependencies are required.
When external libraries or APIs are involved and current documentation must be consulted.
When you want atomic, testable work items with clear validation criteria.
When you want a pre-execution review to catch ordering and dependency mistakes.

Best practices

Always run the initial codebase exploration to determine architecture and surface ambiguity.
Use Context7 to fetch version-specific docs for any external dependency before planning tasks.
Stop and ask user clarification questions when architecture, scope, or constraints are unclear.
Keep tasks small and atomic so single agents can execute them without cross-task coordination.
Ensure every task includes explicit validation steps and file locations for traceability.

Example use cases

Planning a new API feature across backend, database migration, and CI so each agent can work in parallel.
Preparing a refactor where dependent modules must be updated in a safe, ordered sequence.
Coordinating integration of a third-party SDK with version-specific API calls and tests.
Breaking down a complex bugfix into independent verification, patch, and test tasks for parallel execution.
Creating release preparation steps that include docs, tests, and deployment checks with explicit dependencies.

FAQ

Does the skill implement code?

No — it only creates dependency-aware implementation plans, not code changes.

How are external libraries handled?

The skill requires fetching current documentation via Context7 before finalizing tasks that touch external libraries.

What happens if the architecture is unclear?

The process stops and yields clarification questions to the user; it does not proceed on assumptions.