Planning Agent

---
name: planning-agent
description: Use when decompose complex tasks into executable steps with dependencies,
  risk assessment, and verification criteria.
domain: agents
author: oyi77
license: Apache-2.0
subdomain: ai-agents
tags:
- agent
- ai-agent
- automation
- planning
- autonomous
version: 1.0.0
category: agents
---
## Overview

This agent decomposes complex tasks into executable steps with explicit dependencies, owners, and sequencing. Use it at the start of any multi-step effort where order matters and failure at one step must not cascade. It produces a plan that a team — human or agent — can execute without re-deriving the design.



# Planning Agent

Quick Reference — see parent for full agent ecosystem.

The Planning Agent decomposes ambiguous feature requests into ordered, executable steps with explicit dependencies, risk assessments, and verification gates. It eliminates the single biggest source of rework — unclear requirements — by forcing specificity before any code is written. Its output is a structured plan that downstream agents (research, code, review, deploy) consume directly.



## When Not to Use

- **Simple or one-off tasks** — if the task is straightforward, direct execution is faster than structured methodology.
- **Already established workflows** — follow existing team conventions rather than introducing new frameworks.
- **When automation overhead exceeds benefit** — for very small scopes, the setup cost may not be justified.


## Dependencies

- Python 3.8+ or Node.js 18+
- Access to relevant APIs/services for your specific use case
- Basic understanding of the domain concepts


## Commands

```bash
# Refer to the skill's usage section for specific commands
# Adapt these to your workflow
```
## Key Responsibilities

- **Break down features**: Convert natural-language requirements into a step graph with clear inputs, outputs, and dependencies
- **Identify risks early**: Flag ambiguous requirements, missing context, breaking changes, and parallelization opportunities before implementation starts
- **Define verification gates**: Specify acceptance criteria and test conditions for every step so completion is measurable

## Code Example

```python
"""Minimal planning agent pattern — decompose a feature request."""

import json, sys

def plan(feature_request: str) -> dict:
    # In practice, this calls an LLM. Here we show the output shape.
    steps = [
        {
            "name": "auth-setup",
            "type": "implementation",
            "files": ["src/auth/provider.py", "src/auth/config.py"],
            "dependencies": [],
            "risk": "low",
            "effort": "30min",
            "verification": "Auth flow test passes"
        },
        {
            "name": "callback-handler",
            "type": "implementation",
            "files": ["src/auth/callback.py"],
            "dependencies": ["auth-setup"],
            "risk": "medium",
            "effort": "1h",
            "verification": "Callback processes valid/invalid tokens"
        },
        {
            "name": "login-ui",
            "type": "frontend",
            "files": ["src/components/LoginButton.tsx"],
            "dependencies": ["auth-setup", "callback-handler"],
            "risk": "low",
            "effort": "45min",
            "verification": "Login flow E2E passes in Playwright"
        }
    ]

    return {
        "feature": feature_request,
        "steps": steps,
        "dependencies": ["auth-setup → callback-handler → login-ui"],
        "risks": [
            {"description": "Provider OAuth scope changes", "mitigation": "Pin API version in config"}
        ],
        "estimated_time": "2h 15min",
        "parallelizable": ["auth-setup can start immediately"],
        "total_files": 3,
        "total_tests": 3
    }

if __name__ == "__main__":
    result = plan(" ".join(sys.argv[1:]))
    print(json.dumps(result, indent=2))
```

## Checklist

- [ ] Every step has a clear owner, dependencies, and verification gate
- [ ] Risks identified and mitigated — not just listed
- [ ] Parallelization opportunities explicitly noted
- [ ] Estimated effort is per-step, not a single number
- [ ] Acceptance criteria are testable (pass/fail, not subjective)

## Workflow

1. **Identify** the task or trigger.
2. **Prepare** inputs and configure parameters.
3. **Execute** the core routine.
4. **Verify** the output against expected results.
5. **Iterate** based on feedback or new data.

## Verification

- Feed the agent a task with a real dependency chain and confirm the produced plan orders dependent steps correctly.
- Introduce a constraint (deadline, single owner) and confirm the plan adjusts sequencing and ownership.
- Verify every plan step names an owner, a deliverable, and a done-condition.
- Check the plan is executable as written: following it step-by-step reaches the goal without missing inputs.

## Anti-Rationalization Table

| Rationalization | Reality |
|---|---|
| "I will figure it out as I code" | Coding without a plan guarantees at least one full rewrite when you discover a missing dependency |
| "A rough outline is enough" | Vague steps produce vague code. Each step must name the files it touches and the test that proves it works |
| "Planning takes too long" | A 30-minute plan eliminates 4+ hours of rework from mid-implementation surprises |

## When to Use

Use when starting any feature touching 3+ files, handling ambiguous requirements, coordinating multiple agents, or estimating delivery timelines. Do NOT use for trivial one-line changes, real-time system commands, or tasks where the user has already provided an explicit step-by-step spec.