/post-plan-workflow

name: post-plan-workflow
description: "Internal, hook-triggered: materializes MCP items from the approved plan and dispatches implementation."
user-invocable: false

Post-Plan Workflow — Materialize and Implement

Plan approval is the green light for the full pipeline. Proceed through all three phases without stopping; the one expected stop is the turn that ends when a run-wave Method A launch hands control to the async notification (see Phase 2, Route).

Phase 1: Materialize

Complete materialization **before** any implementation begins.

**Prefer a stashed docRef over re-authoring note bodies.** On HTTP+REST workspaces, the `plan-capture` hook stashes the just-approved plan as a plan document as ExitPlanMode fires, and reports the slug via `additionalContext` (`Task Orchestrator: plan stashed as plan document '<slug>' (root <rootId>)`). When that context is present, or `manage_plan_documents(operation="list", rootId=..., status="pending")` confirms a pending document for this root, use it as the source of truth for materialization — quote/reference its content instead of retyping the plan into note bodies. Fall back to the plan text already in context when no stashed doc exists (stdio setups, or the hook failed open).

1. **Create MCP items** from the approved plan using `create_work_tree` (preferred for structured work with dependencies) or `manage_items` (for individual items). Apply appropriate schema tags based on the plan and the project's `.taskorchestrator/config.yaml` — this activates gate enforcement for each item. If the config defines separate schemas for containers vs. child tasks, apply the appropriate tag at each level.

• **Anchor the root under the project when known:** resolve the project rootId from session context (injected by the SessionStart hook) or `.taskorchestrator/config.yaml`'s `project.rootId`. When known, set the new root item's `parentId` to that rootId (directly, or to the appropriate category container beneath it if one already exists) so materialized work lands inside the project's tree instead of at a bare depth 0. When no rootId is known, create at depth 0 as before.
• **Dedup check before each new root or feature item** (children inherit their parent's check): run ONE unscoped `query_items(operation="search", query="<title key terms>", limit=5)`. Unscoped on purpose — depth-0 process-global items such as agent-observations sit outside any project ancestor, so an `ancestorId`-scoped search misses them. Show close matches as one FYI line (role + short id each) and keep materializing — the user decides whether to act; never auto-link, auto-skip or auto-cancel.

2. **Wire dependency edges** between items — use `BLOCKS` only for a semantic dependency (B consumes A's API, output or decision), `fan-out`/`fan-in` patterns for parallel work. Record each edge's reason on the dependent's spec note as one line: `Depends on <blocker short>: <reason>` (dependencies carry no description of their own). When two items in one feature only edit the same file, add no edge: per-file locks serialize a shared file inside one shared-worktree run, while an edge that unblocks at review or terminal costs a separate run (in shared mode an edge that unblocks at work or queue stays in the same run). Name the file in both items' spec notes on one line: `Shared file, lock-serialized: <path> (with <other short>)`. `run-planner plan` warns (advisory, exit 0) on a same-feature edge whose scopes share a file and whose dependent has no `Depends on` line for that blocker. The warning fires only in shared mode. 3. **Check `expectedNotes` in create responses** — if the item's tags match a schema, the response includes the expected note keys and phases. Fill required queue-phase notes (`feature-summary`, `task-scope`, etc.) with content from the plan before advancing.

• **`feature-implementation` root:** keep its `feature-summary` note lean — goal (2-3 sentences), a findings→tasks table mapping plan findings to the child items just created, dependency edges between those children, and a pointer to non-goals (target under 2k chars). Put full alternatives/blast-radius/risk-flags/test-strategy detail in each child's `task-scope` note instead — that's where `/spec-quality`'s full bar applies.
• **Test-owner flag:** for each seat-aware item (any type whose `query_items(operation="schema", itemId=...)` response declares `seats`) that lists no `test-author` seat and whose spec note names test files or test commands, show one FYI line `test owner: <short> lists tests without needs-test-author - add the trait (preferred) or drop the tests; run-wave stops a seat-aware item after its planner (a seat-less item is not stopped; its implementer gets a TESTS ARE YOURS line instead)`. Never add the trait yourself.

4. **Verify all item UUIDs exist** — confirm the full item graph is materialized before proceeding

**If `create_work_tree` fails:** Check partial state with `query_items(operation='overview')`. Delete partial items with `manage_items(operation="delete", itemIds=["<uuid>"], recursive=true)` and retry.

Do NOT dispatch implementation agents until materialization is complete. Agents need MCP item UUIDs to self-report progress.

Phase 2: Implement

Route: run-wave or hand-dispatch

Hand off to `/task-orchestrator:run-wave` only when ALL four conditions hold; each is a concrete probe:

1. **Two or more unblocked leaf items.** At least two leaf items (no children) were materialized and are unblocked: they are absent from `get_blocked_items(ancestorId=<materialized root>)`. 2. **A rootId resolves** (project or personal), in the order run-wave Step 1 uses: session context (`Active project:` or `Personal root:` line), else `project.rootId` from the file on that context's `Config:` line, else `.taskorchestrator/config.yaml`. 3. **Queue notes are filled.** Each of those leaves has its required queue notes filled (`get_context(itemId)` shows no missing queue notes) or is schema-