fix: ensure Task ID is passed to agents in all dispatch instructions

pact-plugin/CLAUDE.md

@@ -244,6 +244,8 @@ Explicit user override ("you code this, don't delegate") should be honored; casu
 
 **If in doubt, delegate!**
 
+**Checkpoint**: Before dispatching any agent, ALWAYS run `TaskCreate` first, then pass the returned `{task_id}` in the agent's prompt. This enables agents to track their own status via the `pact-task-tracking` skill.
+
 #### Invoke Multiple Specialists Concurrently
 
 > ⚠️ **DEFAULT TO CONCURRENT**: When delegating, dispatch multiple specialists together in a single response unless tasks share files or have explicit dependencies. This is not optional—it's the expected mode of orchestration.
@@ -336,6 +338,12 @@ Task(
 
 Use this structure in the `prompt` field to ensure agents have adequate context:
 
+Your assigned Task ID is: {task_id}
+
+**FIRST ACTION (MANDATORY)**
+Before doing anything else, run: `TaskUpdate(taskId={task_id}, status="in_progress")`
+This must be your very first tool call. Do not skip it.
+
 **CONTEXT**
 [Brief background, what phase we are in, and relevant state]
 
@@ -353,6 +361,8 @@ A list of things that include the following:
 - [Best Practices]
 - [Wisdom from lessons learned]
 
+> ⚠️ **Task ID Handoff (MANDATORY)**: Before dispatching any agent, ALWAYS create a Task for it via `TaskCreate` first, then include the returned Task ID as `{task_id}` in the agent's prompt (as shown above). The `pact-task-tracking` skill tells agents to call `TaskUpdate` on start and completion, but agents can only do this if they know their Task ID. Without it, tasks stay in "pending" forever.
+
 ### How to Delegate
 
 Use these commands to trigger PACT workflows for delegating tasks:

pact-plugin/commands/comPACT.md

@@ -15,13 +15,13 @@ Delegate this focused task within a single PACT domain: $ARGUMENTS
 Create a simpler Task hierarchy than full orchestrate:
 
 ```
-1. TaskCreate: Feature task "{verb} {feature}" (single-domain work)
+1. TaskCreate: Feature Task "{verb} {feature}" (single-domain work)
 2. Analyze: How many agents needed?
-3. TaskCreate: Agent task(s) — direct children of feature
-4. TaskUpdate: Feature task addBlockedBy = [all agent IDs]
-5. Dispatch agents concurrently with task IDs
+3. TaskCreate: Agent Task(s) — direct children of feature
+4. TaskUpdate: Feature Task addBlockedBy = [all agent IDs]
+5. Dispatch agents concurrently with Task IDs
 6. Monitor via TaskList until all agents complete
-7. TaskUpdate: Feature task status = "completed"
+7. TaskUpdate: Feature Task status = "completed"
 ```
 
 **Example structure:**
@@ -146,6 +146,8 @@ Before invoking multiple specialists concurrently, perform this coordination che
 When the task contains multiple independent items, invoke multiple specialists together with boundary context:
 
 ```
+Your assigned Task ID is: {task_id}
+
 comPACT mode (concurrent): You are one of [N] specialists working concurrently.
 
 YOUR SCOPE: [specific sub-task and files this agent owns]
@@ -178,6 +180,8 @@ Use a single specialist agent only when:
 
 **Invoke the specialist with**:
 ```
+Your assigned Task ID is: {task_id}
+
 comPACT mode: Work directly from this task description.
 Check docs/plans/, docs/preparation/, docs/architecture/ briefly if they exist—reference relevant context.
 Do not create new documentation artifacts in docs/.
@@ -211,7 +215,7 @@ On signal detected: Follow Signal Task Handling in CLAUDE.md.
 
 1. **Receive handoff** from specialist(s)
 2. **Run tests** — verify work passes. If tests fail → return to specialist for fixes before committing.
-3. **TaskUpdate**: Feature task status = "completed"
+3. **TaskUpdate**: Feature Task status = "completed"
 4. **Create atomic commit(s)** — stage and commit before proceeding
 
 **Next steps** (user decides):

pact-plugin/commands/imPACT.md

@@ -14,13 +14,13 @@ imPACT operates on existing blocker Tasks created by agents:
 1. TaskGet(blocker_id) — understand the blocker context
 2. Triage: redo prior phase? need specialist? need user?
 3. On resolution path chosen:
-   - If delegating: TaskCreate resolution agent task
+   - If delegating: TaskCreate resolution agent Task, include its `{task_id}` in the agent prompt
    - If self-resolving: proceed directly
 4. On resolution complete: TaskUpdate(blocker_id, status="completed")
-5. Blocked agent task is now unblocked
+5. Blocked agent Task is now unblocked
 ```
 
-**Note**: Agents create blocker Tasks and block themselves via `addBlockedBy`. When the blocker is resolved (marked completed), the agent's task becomes unblocked.
+**Note**: Agents create blocker Tasks and block themselves via `addBlockedBy`. When the blocker is resolved (marked completed), the agent's Task becomes unblocked.
 
 ---
 

pact-plugin/commands/orchestrate.md

@@ -11,8 +11,8 @@ Orchestrate specialist PACT agents through the PACT workflow to address: $ARGUME
 Create the full Task hierarchy upfront for workflow visibility:
 
 ```
-1. TaskCreate: Feature task "{verb} {feature}"
-2. TaskCreate: Phase tasks (all upfront):
+1. TaskCreate: Feature Task "{verb} {feature}"
+2. TaskCreate: Phase Tasks (all upfront):
    - "PREPARE: {feature-slug}"
    - "ARCHITECT: {feature-slug}"
    - "CODE: {feature-slug}"
@@ -27,9 +27,9 @@ For each phase execution:
 ```
 a. TaskUpdate: phase status = "in_progress"
 b. Analyze work needed (QDCL for CODE)
-c. TaskCreate: agent task(s) as children of phase
+c. TaskCreate: agent Task(s) as children of phase
 d. TaskUpdate: next phase addBlockedBy = [agent IDs]
-e. Dispatch agents with task IDs in their prompts
+e. Dispatch agents with Task IDs in their prompts
 f. Monitor via TaskList until agents complete
 g. TaskUpdate: phase status = "completed"
 ```
@@ -231,7 +231,7 @@ Each specialist should end with a structured handoff:
 - "Preparation Phase"
 - "Open Questions > Require Further Research"
 
-**Invoke `pact-preparer` with**:
+**Invoke `pact-preparer` with** (include the agent's `{task_id}` from TaskCreate):
 - Task description
 - Plan sections above (if any)
 - "Reference the approved plan at `docs/plans/{slug}-plan.md` for full context."
@@ -269,7 +269,7 @@ If PREPARE ran and ARCHITECT was marked "Skip," compare PREPARE's recommended ap
 - "Key Decisions"
 - "Interface Contracts"
 
-**Invoke `pact-architect` with**:
+**Invoke `pact-architect` with** (include the agent's `{task_id}` from TaskCreate):
 - Task description
 - PREPARE phase outputs
 - Plan sections above (if any)
@@ -347,7 +347,7 @@ Before concurrent dispatch, check internally: shared files? shared interfaces? c
 
 **Include in prompts for concurrent specialists**: "You are working concurrently with other specialists. Your scope is [files]. Do not modify files outside your scope."
 
-**Invoke coder(s) with**:
+**Invoke coder(s) with** (include each agent's `{task_id}` from TaskCreate):
 - Task description
 - ARCHITECT phase outputs (or plan's Architecture Phase if ARCHITECT was skipped)
 - Plan sections above (if any)
@@ -389,7 +389,7 @@ If a sub-task emerges that is too complex for a single specialist invocation:
 - "Test Scenarios"
 - "Coverage Targets"
 
-**Invoke `pact-test-engineer` with**:
+**Invoke `pact-test-engineer` with** (include the agent's `{task_id}` from TaskCreate):
 - Task description
 - CODE phase handoff(s): Pass the handoff summaries from coders for context on what was built
 - Plan sections above (if any)
@@ -422,7 +422,7 @@ On signal detected: Follow Signal Task Handling in CLAUDE.md.
 > **S5 Policy Checkpoint (Pre-PR)**: Before creating PR, verify: "Do all tests pass? Is system integrity maintained? Have S5 non-negotiables been respected throughout?"
 
 1. **Update plan status** (if plan exists): IN_PROGRESS → IMPLEMENTED
-2. **TaskUpdate**: Feature task status = "completed" (all phases done)
+2. **TaskUpdate**: Feature Task status = "completed" (all phases done)
 3. **Verify all work is committed** — CODE and TEST phase commits should already exist; if any uncommitted changes remain, commit them now
 4. **Run `/PACT:peer-review`** to create PR and get multi-agent review
 5. **Present review summary and stop** — orchestrator never merges (S5 policy)

pact-plugin/commands/peer-review.md

@@ -15,25 +15,25 @@ Review the current work: $ARGUMENTS
 Create a review Task hierarchy:
 
 ```
-1. TaskCreate: Review task "Review: {feature}"
+1. TaskCreate: Review Task "Review: {feature}"
 2. Analyze PR: Which reviewers needed?
-3. TaskCreate: Reviewer agent tasks (architect, test-engineer, domain specialists)
-4. TaskUpdate: Review task addBlockedBy = [reviewer IDs]
-5. Dispatch reviewers in parallel
+3. TaskCreate: Reviewer agent Tasks (architect, test-engineer, domain specialists)
+4. TaskUpdate: Review Task addBlockedBy = [reviewer IDs]
+5. Dispatch reviewers in parallel (include each reviewer's `{task_id}` in their prompt)
 6. Monitor until reviewers complete
 7. Synthesize findings
 8. If major issues:
-   a. TaskCreate: Remediation agent tasks
+   a. TaskCreate: Remediation agent Tasks
    b. Dispatch, monitor until complete
-9. TaskCreate: "User: review minor issues" step task
+9. TaskCreate: "User: review minor issues" step Task
 10. Present minor issues to user, record decisions in step metadata
 11. If "fix now" decisions:
-    a. TaskCreate: Remediation agent tasks
+    a. TaskCreate: Remediation agent Tasks
     b. Dispatch, monitor until complete
-12. TaskCreate: "Awaiting merge decision" approval task
+12. TaskCreate: "Awaiting merge decision" approval Task
 13. Present to user, await approval
-14. On approval: TaskUpdate approval completed
-15. TaskUpdate: Review task completed, metadata.artifact = PR URL
+14. On approval: TaskUpdate approval Task completed
+15. TaskUpdate: Review Task completed, metadata.artifact = PR URL
 ```
 
 **Example structure:**
@@ -67,6 +67,29 @@ Select the domain coder based on PR focus:
 - Database changes → **pact-database-engineer** (Query efficiency, schema design, data integrity)
 - Multiple domains → Coder for domain with most significant changes, or all relevant domain coders if changes are equally significant
 
+**Use this prompt template for each reviewer:**
+
+```
+Your assigned Task ID is: {task_id}
+
+PEER REVIEW — Review this PR for issues in your domain of expertise.
+
+PR: {PR URL or branch name}
+
+As the {role} reviewer, evaluate:
+1. Issues in your domain (bugs, design flaws, missing edge cases)
+2. Adherence to project conventions and patterns
+3. Security, performance, or maintainability concerns
+
+Classify each finding as:
+- **Blocking**: Must fix before merge
+- **Minor**: Optional improvement for this PR
+- **Future**: Out of scope; suggest tracking as GitHub issue
+
+Output your findings as a markdown table with columns: Recommendation | Severity | Details.
+If no issues found, state "No issues found."
+```
+
 ---
 
 ## Output Conciseness

pact-plugin/commands/plan-mode.md

@@ -13,14 +13,14 @@ Create a comprehensive implementation plan for: $ARGUMENTS
 Create a planning Task hierarchy:
 
 ```
-1. TaskCreate: Planning task "Plan: {feature}"
+1. TaskCreate: Planning Task "Plan: {feature}"
 2. Analyze: Which specialists to consult?
-3. TaskCreate: Consultation task(s) — one per specialist
-4. TaskUpdate: Planning task addBlockedBy = [consultation IDs]
-5. Dispatch specialists in parallel (planning-only mode)
+3. TaskCreate: Consultation Task(s) — one per specialist
+4. TaskUpdate: Planning Task addBlockedBy = [consultation IDs]
+5. Dispatch specialists in parallel (planning-only mode, include each specialist's `{task_id}` in their prompt)
 6. Monitor until consultations complete
 7. Synthesize → write plan document
-8. TaskUpdate: Planning task completed, metadata.artifact = plan path
+8. TaskUpdate: Planning Task completed, metadata.artifact = plan path
 ```
 
 **Example structure:**
@@ -99,6 +99,8 @@ Invoke relevant specialists **in parallel**, each in **planning-only mode**.
 **Use this prompt template for each specialist:**
 
 ```
+Your assigned Task ID is: {task_id}
+
 PLANNING CONSULTATION ONLY — No implementation, no code changes.
 
 Task: {task description}
@@ -231,7 +233,7 @@ After collecting all specialist outputs, use extended thinking to synthesize:
 
 ### Phase 3: Plan Output
 
-**TaskUpdate**: Planning task completed with artifact path:
+**TaskUpdate**: Planning Task completed with artifact path:
 ```
 TaskUpdate(
   taskId=planning_task_id,
@@ -498,4 +500,4 @@ After the user approves the plan:
 3. If plan exists, use it as the implementation specification
 4. Specialists receive relevant sections of the plan as context
 
-**Task Linkage**: When `/PACT:orchestrate` runs, it checks for a completed Planning task matching the feature. If found, the plan artifact path from `metadata.artifact` is used to locate and reference the approved plan automatically.
+**Task Linkage**: When `/PACT:orchestrate` runs, it checks for a completed Planning Task matching the feature. If found, the plan artifact path from `metadata.artifact` is used to locate and reference the approved plan automatically.

pact-plugin/commands/rePACT.md

@@ -13,17 +13,17 @@ This command initiates a **nested P→A→C→T cycle** for a sub-task that is t
 Create a nested Task hierarchy as a child of the current context:
 
 ```
-1. TaskCreate: Sub-feature task "{verb} {sub-feature}" (child of parent context)
-2. TaskCreate: Nested phase tasks:
+1. TaskCreate: Sub-feature Task "{verb} {sub-feature}" (child of parent context)
+2. TaskCreate: Nested phase Tasks:
    - "PREPARE: {sub-feature-slug}"
    - "ARCHITECT: {sub-feature-slug}"
    - "CODE: {sub-feature-slug}"
    - "TEST: {sub-feature-slug}"
 3. TaskUpdate: Set dependencies:
    - Phase-to-phase blockedBy chain (same as orchestrate)
-   - Parent task addBlockedBy = [sub-feature task]
-4. Execute nested P→A→C→T cycle
-5. On completion: Parent task unblocked
+   - Parent Task addBlockedBy = [sub-feature Task]
+4. Execute nested P→A→C→T cycle (include each agent's `{task_id}` in their prompt)
+5. On completion: Parent Task unblocked
 ```
 
 **Example structure:**
@@ -142,7 +142,7 @@ If you hit the nesting limit:
 ### Branch Behavior
 
 - **No new branch**: rePACT stays on the current feature branch
-- **No PR**: Results integrate into the parent task's eventual PR
+- **No PR**: Results integrate into the parent Task's eventual PR
 - All commits remain part of the current feature work
 
 ---
@@ -179,6 +179,23 @@ Implement the sub-component:
 - Apply S2 coordination if parallel work
 - Output: Code + handoff summary
 
+**Use this prompt template for each specialist:**
+
+```
+Your assigned Task ID is: {task_id}
+
+rePACT nested cycle — sub-task of parent feature.
+
+Parent context: {parent feature description}
+Sub-task: {sub-task description}
+
+Work directly from this sub-task description.
+Stay within the sub-component scope. Do not modify files outside your boundary.
+Smoke test your changes before handoff.
+
+If you hit a blocker, STOP and report it.
+```
+
 ### Phase 4: Mini-Test
 
 Verify the sub-component:
@@ -198,7 +215,7 @@ Complete the nested cycle:
 
 Nested cycles inherit from parent:
 - Current feature branch
-- Parent task context and requirements
+- Parent Task context and requirements
 - Architectural decisions from parent
 - Coding conventions established in parent
 
@@ -294,10 +311,10 @@ On signal detected: Follow Signal Task Handling in CLAUDE.md.
 ## After Completion
 
 When nested cycle completes:
-1. **TaskUpdate**: Sub-feature task status = "completed"
+1. **TaskUpdate**: Sub-feature Task status = "completed"
 2. **Summarize** what was done in the nested cycle
-3. **Report** any decisions that affect the parent task
-4. **Continue** with parent orchestration (parent task now unblocked)
+3. **Report** any decisions that affect the parent Task
+4. **Continue** with parent orchestration (parent Task now unblocked)
 
 **Handoff format**: Use the standard 4-item structure (Produced, Key context, Areas of uncertainty, Open questions). See orchestrate.md § Handoff Format.
 

pact-plugin/commands/wrap-up.md

@@ -12,7 +12,7 @@ Before other cleanup, audit and optionally clean up Task state:
 ```
 1. TaskList: Review all session tasks
 2. For abandoned in_progress tasks: complete or document reason
-3. Verify Feature task reflects final state
+3. Verify Feature Task reflects final state
 4. Archive key context to memory (via pact-memory-agent)
 5. Report task summary: "Session has N tasks (X completed, Y pending)"
 6. IF multi-session mode (CLAUDE_CODE_TASK_LIST_ID set):
@@ -25,8 +25,8 @@ Before other cleanup, audit and optionally clean up Task state:
 
 | Task State | Cleanup Action |
 |------------|----------------|
-| `completed` Feature task | Archive summary, then delete with children |
-| `in_progress` Feature task | Do NOT delete (workflow still active) |
+| `completed` Feature Task | Archive summary, then delete with children |
+| `in_progress` Feature Task | Do NOT delete (workflow still active) |
 | Orphaned `in_progress` | Document abandonment reason, then delete |
 | `pending` blocked forever | Delete with note |
 

pact-plugin/hooks/validate_handoff.py

@@ -6,7 +6,7 @@
 
 Validates that PACT agents:
 1. Complete with proper handoff information (produced, decisions, next steps)
-2. Called TaskUpdate(status="completed") with required metadata (Task integration)
+2. Reported completion via structured HANDOFF text (orchestrator handles TaskUpdate)
 
 Input: JSON from stdin with `transcript`, `agent_id`, and optionally `task_id`
 Output: JSON with `systemMessage` if handoff format is incomplete or Task protocol violated