task-planning

name	task-planning
description	Use when planning implementation Tasks from a design — the plan turn that covers the milestone's in-scope stories with one Task per design component, wires dependsOn, and writes each Task's body.
metadata	{"aep":{"kind":"platform","audience":["design"]}}

Task planning

Cover the milestone's in-scope stories. The instruction carries a "Milestone scope" section the platform computed: each in-scope story is marked COVERED (an existing Task already serves it) or NEEDS TASKS. Your job ends when every NEEDS TASKS story is served by a Task; COVERED stories' existing Tasks are reference, never rework. With no scope section, plan every component that needs work — same rules, whole design in scope.

The unit of work stays the design component. A story is served by the component that cites it (stories in components/<name>/design.json, derived from the cell): plan or extend THAT component's Task. Never invent a component; a story no component cites is the design's gap — say so in your final text and recommend extending the design, never a Task without a home. The platform stamps each Task's "Serves stories" block from the design's citations — you never write it.

What a Task is

• One component, one Task. Title it after the work — "Implement order-service" fresh, "Add refunds to order-service" for a delta. Titles unique and human-readable.
• rationale is one sentence: why this Task exists.
• dependsOn are component names from the design's edges: if order-service calls user-service, its Task depends on ["user-service"]. Never issue numbers; never platform infrastructure (databases, gateways, IDPs). For every component edge A→B, A's Task lists B — dependsOn carries the build order (a cycle is rejected; break it).

Dependency kinds and gates

Dependency kind	Ordering effect	What the rationale records
component	consumer's Task lists the provider in dependsOn	the build-order edge
org-service	none — the provider lives in another project	the cross-project binding
external	none	names the value-collection gate
platform-resource	none	names the provisioning gate

Gates are flagged, never minted: the platform authors gate issues; you emit no Task for a gate. Each design dependency is accounted for exactly once — in dependsOn (component kind) or in a rationale (the other three).

Fresh and incremental are the same flow

• Pending Task of an affected component → updateTask it (re-state scope, refresh dependsOn, rewrite the body) rather than planning a duplicate.
• Component work already done, new stories arrived → plan a delta Task for just the new work, distinctly titled.
• In-flight work → updateTask with a note that the change lands on top; never silently rewrite its scope.
• Untouched components and COVERED stories → do nothing. Silence is correct.
• Obsolete component (has a Task, gone from the design) → updateTask with an obsolescence note; a human closes it.

Split one component into several Tasks only when a single PR physically cannot land the work (e.g. a migration must merge before feature code).

Write the bodies in the same turn

After planning, write every planned Task's full body via updateTask before the turn ends — ## Scope (the concrete work, citing the component's design.json and its openapi.yaml/wireframes.dsl), ## Acceptance (what done means, at work altitude — the validation oracle owns product acceptance), and ## References (the spec paths the coding agent reads). A Task without a body is unfinished planning.

When a tool rejects you

The result names the fix: UNKNOWN_COMPONENT lists the known components; UNKNOWN_REF lists the addressable refs; DUPLICATE_TITLE means pick a distinct title; DEPENDENCY_CYCLE shows the path to break. Correct and re-issue — never re-emit an op that succeeded.