taskgraph-plan-work

name	taskgraph-plan-work
description	Plan, decompose, organize, and update work in the Taskgraph MCP. 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 the Taskgraph MCP to turn a goal into a small, usable work tree. Keep the hierarchy clear, put blockers in typed relationships, and verify every write.

Rules

• Use the MCP tools, not direct SQLite 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.
• 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 current server publishes empty input schemas for several supported handlers, including create, patch, and relationship mutation. If a strict MCP client rejects valid arguments, report a schema compatibility issue; do not bypass the MCP with direct database writes.

Plan a hierarchy

1. Resolve the requested parent. If no parent exists, create a project or roadmap root.
2. Create the smallest useful tree. Use container kinds for grouping and action kinds for executable work.
3. Add acceptance criteria and tags at creation time when they are known.
4. Add dependencies in the same atomic request when both items are new.
5. Inspect the result with tg_get_item or tg_get_graph.

Use this shape unless the user asks for another one:

{
  "items": [
    {"client_ref":"root","kind":"project","title":"Compiler rewrite"},
    {"client_ref":"parse","parent":"$root","kind":"task","title":"Parse input","execution_mode":"action","acceptance_criteria":["Reject malformed input with a useful error"]},
    {"client_ref":"tests","parent":"$root","kind":"task","title"
  
   
    
  
   
   

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.

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.
• Report created IDs and canonical paths so the next agent can resolve them.