Design Agent Planning

Common Contract (Load First)

When this skill is activated, first load skill-common and apply the shared conventions it defines: canonical section order, frontmatter rules, anti-pattern guidance, and the Review In Mind loop in review-in-mind. This skill adds only domain-specific rules below.

Who

Architects, AI engineers, or coding agents building orchestrations that must solve complex, multi-step goals autonomously.

What

Design and implement a Planning pattern where a Planner agent explicitly decomposes a high-level goal into a sequence of atomic sub-tasks (a Plan) before any execution begins.

When

• Triggered by requests like: "design a planning agent", "implement a plan-and-solve workflow", or "use ReAct to solve this multi-step problem".
• Do not use for linear, single-step tasks (e.g., translation, summarization).

Where

Applies to agent orchestration code, especially frameworks supporting directed acyclic graphs (DAGs) like LangGraph or explicit loop chains.

Why

Without a plan, agents often suffer from "context drift" or get stuck in repetitive tool-calling loops because they lose track of the overarching goal. Explicit planning forces the agent to generate a "roadmap", making the subsequent execution steps highly focused and much less prone to hallucination.

Inputs

• High-Level Goal: The complex task to solve.
• Available Tools/Specialists: The capabilities the planner can delegate to.

Output (Logical Evidence)

• Planner Orchestration Code: Code that implements a Planner node, an Executor loop, and a Replanner (if dynamic).
• Plan Schema: A Pydantic model or TypedDict defining a list of SubTask objects.

Optimization Readiness

• Failure Signals: Plans stay too coarse to execute atomically, executors lose track of step state, replanning loops thrash without converging, or tool availability is assumed instead of modeled.
• Evidence To Collect: Plan schemas, execution traces, replanning decisions, and examples of plans that succeeded, stalled, or fragmented into unusable steps.
• Safe Mutation Boundaries: Refine plan-schema fields, planner prompts, executor update rules, and replanning conditions without changing the core planner-executor-replanner architecture.
• Acceptance Criteria: Accept revisions only if the plan breaks work into executable atomic steps, stores progress explicitly in state, and supports controlled replanning when new evidence arrives.
• Rejected Revision Handling: Record over-granular or under-granular planning patterns, weak state-update rules, and failed replanning heuristics so they are not reused blindly.
• Transfer Check: Confirm the workflow still works for both static plan execution and dynamic replanning scenarios.
• Stop Rule: If the available tools or execution ownership are unclear, stop and ask before designing the plan structure.

Constraints (Logical Boundaries)

• Atomic Sub-tasks: The Planner must break tasks down into steps that can be completed by a single tool call or a single specialist agent.
• State Validation: The plan must be stored in the state explicitly so the Executor can cross them off one by one.

One More Thing

If it is unclear what tools the agent has access to, stop and ask the user to clarify the tools before designing the planner.

How (Structural Workflow)

1. Define the Plan Schema

• Create a strict schema for the plan (e.g., a Plan object containing a list of steps, where each step has a description and a status).

2. Implement the Planner Node

• Write the system prompt for the Planner. It must understand the High-Level Goal and the available tools.
• Force the Planner to output structured JSON matching the Plan Schema.

3. Implement the Executor Node(s)

• The Executor node looks at the current state, picks the next incomplete step from the plan, and attempts to execute it.
• After execution, the Executor updates the state to mark the step as complete and appends the result to a scratchpad or memory.

4. (Optional) Implement the Replanner

• For highly dynamic environments, implement a Replanner node that evaluates the execution results. If an execution failed or new information was discovered, the Replanner alters the remaining steps in the plan.

5. Wire the Workflow

• Route: Planner -> Executor.
• Route: Executor -> Replanner (or loop back to Executor if static).
• Add conditional edges to exit when all steps in the plan are marked complete.

Review In Mind (ReviewInMindGenie)

Execute the common review loop in review-in-mind before delivering.

Review lens for this skill:

• Does the planner decompose goals into atomic, ordered, verifiable sub-tasks?
• Are completion states and replanning wired so a skipped or incomplete step fails loudly?
• Does the workflow exit only when all steps are marked complete?