taskgraph-plan-work

name	taskgraph-plan-work
description	Plan, decompose, organize, and update work in Taskgraph. Use when a request needs a project, roadmap, milestone, task, or subtask hierarchy; acceptance criteria; priorities; dependencies; or safe Taskgraph mutations.

Taskgraph Plan Work

Use Taskgraph to turn a goal into a tree of small, concrete, claimable actions. The unit of work is a granular action with verifiable acceptance criteria, not a phase or milestone. Keep the hierarchy clear, put blockers in typed relationships, and verify every write.

Rules

• Use the Taskgraph tools, not direct file or HTTP writes.
• Resolve a supplied path or title with tg_resolve before changing it. Prefer the returned ID for later calls.
• Use one client_ref per item in a create request. Refer to an item created in the same request as $client_ref.
• Keep one concern per item. Put the result or test condition in acceptance_criteria.
• Decompose to the leaf. Actions are the smallest claimable unit: one deliverable, one concern, verifiable acceptance criteria. Milestones, phases, and other containers only group and order actions — they are not work.
• Plan leaves, not phases. Every action must be claimable and completable by one agent in one focused session; if it is not, split it.
• Treat blocks as blocker → blocked. Use hard for a true gate and soft for a ranking hint.
• Use atomic: true for related changes. Use dry_run: true when the plan is large or needs path and relationship checks.
• Re-read the created or patched item and its graph after a write.
• Do not invent tg_mutate_batch operations. The current server routes that name through the create-items input; use tg_create_items, tg_patch_item, and tg_mutate_relationships for supported writes.
• The pi extension publishes full schemas for every tool. If a strict client rejects valid arguments, report the error as a schema compatibility issue; do not bypass the tools with direct file writes.

Plan a hierarchy

1. Resolve the requested parent. If no parent exists, create a project or roadmap root.
2. Build a tree whose leaves are actions and whose containers (projects, roadmaps, milestones) only group and order work. A milestone or phase is never claimable work.
3. Decompose until each action:
   • has a title that names a concrete deliverable or behavior — Return a helpful error for malformed config, not Improve error handling;
   • can be completed by one agent in one focused work session;
   • has acceptance criteria a checker can verify without the planner present;
   • spans one concern or module — if it needs several unrelated files or decisions, it is at least two actions.
4. Write the metadata at creation time. Every action gets a short description (context and bounds), verifiable acceptance criteria, tags for the domain or area, and a priority when known. An action without acceptance criteria is a smell: sharpen the deliverable or split the task.
5. Add dependencies in the same atomic request when both items are new. Use hard only for a real gate.
6. Inspect the result with tg_get_item or tg_get_graph and re-check granularity: containers should have concrete children, and no leaf should read like a phase.

Use this shape unless the user asks for another one:

{
  "items": [
    {"client_ref":"root","kind":"project","title":"Compiler rewrite"},
    {"client_ref":"frontend","parent":"$root","kind":"milestone","title":"Frontend: lexer and parser"},
    {"client_ref":"lex-idents","parent":"$frontend","kind":"task","execution_mode":"action","title":"Tokenize identifiers and keywords","description":"Scan source into a token stream; longest match wins."
    
  
   
    
  
   
   

Built-in defaults make projects, roadmaps, and milestones containers and make tasks and subtasks actions. Set execution_mode or completion_policy when the work needs a different behavior.

Create work safely

Call tg_create_items with items, optional relationships, atomic, and dry_run. Include description, priority, due_at, not_before, tags, acceptance_criteria, required_capabilities, and custom_fields only when they help execution.

Granular work ships with its metadata attached: every action should carry at least a description, verifiable acceptance criteria, and tags. Bare actions with empty descriptions and no criteria produce bare output and force the implementer to guess scope.

For a dry run, review path conflicts, missing parents, and relationship errors. Then repeat the same request with dry_run: false.

Change existing work

1. Call tg_get_item to obtain the current version.
2. Call tg_patch_item with ref, expected_version, and only the fields to change.
3. Use tag_operations, acceptance_operations, and custom_field_operations for those subrecords.
4. Re-read the item. On VERSION_CONFLICT, fetch the item again, review the new state, and retry only if the requested change still applies.

Use tg_mutate_relationships to add, remove, waive, unwaive, or change a relationship. Give a waiver reason. Stop and show the cycle if the server returns DEPENDENCY_CYCLE.

Keep plans usable

• Do not create duplicate items after a timeout until you inspect the workspace or retry the same request with the same client references.
• Do not use a container as executable work unless the user asks for it.
• Do not add a hard dependency just because work is related.
• Do not create broad, generic actions that could swallow several deliverables. If a title needs various, general, improve, or etc. to describe its scope, split it.
• Do not collapse a milestone or phase into one task. Give the phase a container and put its concrete deliverables underneath as separate actions.
• Report created IDs and canonical paths so the next agent can resolve them.