From e393b3ced1dde35331f7d81c96d985f693d02ce5 Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 15:07:36 -0500
Subject: [PATCH 01/10] feat(protocols): add Task System Integration SSOT to
 pact-protocols.md

Add comprehensive Task Integration section including:
- Hybrid Task Model (phase + specialist subtasks)
- Naming conventions for all task types
- Metadata schemas for Phase, Specialist, and Workflow tasks
- Command integration summary for all PACT workflows
- Algedonic task annotation specifications
- Key principles for task-based orchestration

Part of #112 - PACT Task System Integration
---
 pact-plugin/protocols/pact-protocols.md | 127 ++++++++++++++++++++++++
 1 file changed, 127 insertions(+)

diff --git a/pact-plugin/protocols/pact-protocols.md b/pact-plugin/protocols/pact-protocols.md
index 6aa9d54c..52ce134a 100644
--- a/pact-plugin/protocols/pact-protocols.md
+++ b/pact-plugin/protocols/pact-protocols.md
@@ -620,6 +620,133 @@ For full protocol details, see [algedonic.md](algedonic.md).
 
 ---
 
+## Task System Integration
+
+PACT integrates with Claude Code's native Task system (v2.1.16+), using Task primitives as the **work tracking layer** while preserving PACT's **methodology layer** (VSM, phases, coordination protocols).
+
+### Hybrid Task Model
+
+**Phase tasks** (owned by orchestrator) + **Specialist subtasks** (owned by specialists)
+
+```
+Workflow:
+  PREPARE → ARCHITECT → CODE → TEST  (4 phase tasks, sequential dependencies)
+
+During CODE phase:
+  1. Orchestrator marks CODE in_progress
+  2. Creates subtasks: "Backend: Implement X", "Frontend: Add Y"
+  3. CODE task blockedBy subtasks
+  4. Specialists work in parallel
+  5. Subtasks complete → CODE auto-unblocks
+  6. Orchestrator marks CODE completed
+```
+
+### Naming Conventions
+
+| Task Type | Format | Example |
+|-----------|--------|---------|
+| Phase task | `PHASE` | `PREPARE`, `CODE`, `TEST` |
+| Specialist subtask | `Domain: Work` | `Backend: Implement auth` |
+| Workflow task | `Title Case` | `comPACT`, `Peer Review` |
+| Plan-mode phases | `Plan: Phase` | `Plan: Analyze`, `Plan: Consult` |
+| Nested (rePACT) | `rePACT: PHASE` | `rePACT: PREPARE` |
+
+### Metadata Schemas
+
+#### Phase Task
+
+```javascript
+{
+  taskType: "phase",
+  pactWorkflow: "orchestrate" | "plan-mode",
+  phase: "prepare" | "architect" | "code" | "test",
+  variety: { novelty, scope, uncertainty, risk, total },
+  featureBranch: "feature/...",
+  planRef: "docs/plans/...",
+  subtaskIds: ["4", "5"],
+  handoff: {
+    summary: "...",
+    produced: ["..."],
+    keyDecisions: ["..."],
+    unresolvedItems: [{ priority, description }],
+    nextPhaseContext: "..."
+  }
+}
+```
+
+#### Specialist Subtask
+
+```javascript
+{
+  taskType: "specialist",
+  phaseTaskId: "3",
+  domain: "backend" | "frontend" | "database",
+  specialist: "pact-backend-coder" | ...,
+  agentId: "agent-...",
+  handoff: {
+    produced: ["..."],
+    decisions: ["..."],
+    uncertainties: [{ priority, description }],
+    openQuestions: ["..."]
+  }
+}
+```
+
+#### Workflow Task (comPACT, Peer Review)
+
+```javascript
+{
+  taskType: "workflow",
+  pactWorkflow: "comPACT" | "peer-review",
+  domain: "backend",
+  subtaskIds: ["..."],
+  handoff: { ... }
+}
+```
+
+### Command Integration Summary
+
+| Command | Task Structure |
+|---------|----------------|
+| `/PACT:orchestrate` | 4 phase tasks (sequential) + specialist subtasks per phase |
+| `/PACT:comPACT` | 1 workflow task + parallel specialist subtasks |
+| `/PACT:peer-review` | 1 workflow task + parallel reviewer subtasks |
+| `/PACT:plan-mode` | 4 phase tasks (Analyze→Consult→Synthesize→Present) + planner subtasks |
+| `/PACT:rePACT` | Nested phase tasks with `rePACT:` prefix; parent blockedBy nested TEST |
+| `/PACT:imPACT` | Modifies existing tasks; tracks `imPACTHistory` in metadata |
+
+**Skipped phases**: Create task, immediately mark `completed` with `metadata: { skipped: true, skipReason: "..." }`
+
+### Algedonic Task Annotation
+
+Algedonic signals annotate existing tasks (don't create new):
+
+```javascript
+metadata: {
+  algedonicHalt: {
+    timestamp: "...",
+    category: "SECURITY",
+    issue: "...",
+    awaitingAcknowledgment: true
+  },
+  algedonicHistory: [{
+    type: "HALT",
+    category: "...",
+    triggeredAt: "...",
+    resolvedAt: "...",
+    resolution: "..."
+  }]
+}
+```
+
+### Key Principles
+
+- **Orchestrator owns transitions** — specialists don't update task status; orchestrator does
+- **Reference-based context** — use `planRef`, `phaseTaskId`, `blockedBy` chain; don't duplicate content
+- **Handoffs are structured** — `produced`, `decisions`, `uncertainties` format across all specialists
+
+---
+
 ## Variety Management
 
 Variety = complexity that must be matched with response capacity. Assess task variety before choosing a workflow.

From 2320c639fa9f6d3edee7f23635e94547b754bda7 Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 15:07:42 -0500
Subject: [PATCH 02/10] feat(protocols): add task structure docs to workflows
 and algedonic

pact-workflows.md:
- Add task structure notes to each workflow section
- Reference SSOT in pact-protocols.md for schema details

algedonic.md:
- Add Task Annotation section explaining metadata approach
- Document algedonicHalt and algedonicHistory schemas

Part of #112 - PACT Task System Integration
---
 pact-plugin/protocols/algedonic.md      | 29 +++++++++++++++++
 pact-plugin/protocols/pact-workflows.md | 43 +++++++++++++++++++++++++
 2 files changed, 72 insertions(+)

diff --git a/pact-plugin/protocols/algedonic.md b/pact-plugin/protocols/algedonic.md
index c1a49e28..6b2d817e 100644
--- a/pact-plugin/protocols/algedonic.md
+++ b/pact-plugin/protocols/algedonic.md
@@ -232,3 +232,32 @@ If answers lean toward "potential/normal/suspicion/concerning," consider imPACT
   4. **Report**: Confirm to orchestrator: "HALT resolved: {one-line summary of fix}"
 - Document what was found and how it was resolved
 - Consider whether similar issues might exist elsewhere (orchestrator may request targeted audit)
+
+---
+
+## Task Annotation
+
+Algedonic signals annotate existing tasks rather than creating new ones. This maintains task continuity while recording the emergency event.
+
+### When Annotation Happens
+
+In the signal flow (see Signal Delivery Mechanism above):
+1. Agent emits algedonic signal
+2. Orchestrator receives and surfaces to user
+3. **Orchestrator annotates the current task** with signal metadata
+4. User responds; orchestrator updates annotation with resolution
+
+### Metadata Schema
+
+Tasks carry two algedonic fields:
+
+- **`algedonicHalt`**: Active HALT state (present only while awaiting acknowledgment)
+- **`algedonicHistory`**: Array of all past algedonic events on this task
+
+See [pact-protocols.md](pact-protocols.md#algedonic-task-annotation) for the full schema.
+
+### Why Annotate Tasks
+
+- **Audit trail**: History of viability threats encountered during work
+- **Context preservation**: Resolution details survive session boundaries
+- **Pattern detection**: Multiple algedonics on same task may indicate systemic issues
diff --git a/pact-plugin/protocols/pact-workflows.md b/pact-plugin/protocols/pact-workflows.md
index 1ea10adb..6a2bb6ae 100644
--- a/pact-plugin/protocols/pact-workflows.md
+++ b/pact-plugin/protocols/pact-workflows.md
@@ -8,12 +8,32 @@
 | **rePACT** | Complex sub-tasks within orchestration | Recursive nested P→A→C→T cycle (single or multi-domain) |
 | **imPACT** | When blocked or need to iterate | Triage: Redo prior phase? Additional agents needed? |
 
+**Task integration**: All workflows use Claude Code's native Task system. See SSOT "Task System Integration" for metadata schemas, naming conventions, and command summaries.
+
+---
+
+## PACT (orchestrate) Protocol
+
+**Purpose**: Full multi-phase orchestration for complex/greenfield work.
+
+**Task structure**: 4 phase tasks (`PREPARE` → `ARCHITECT` → `CODE` → `TEST`) with sequential dependencies. Each phase task can have parallel specialist subtasks. Phase tasks use `blockedBy` to enforce sequencing; subtasks use `phaseTaskId` to link back.
+
+**Flow**:
+1. Create feature branch
+2. Execute phases sequentially (each with concurrent specialists where applicable)
+3. Auto-commit after CODE and TEST phases
+4. Run `/PACT:peer-review` when complete
+
+**Skipped phases**: Create task, immediately mark `completed` with `metadata: { skipped: true, skipReason: "..." }`
+
 ---
 
 ## plan-mode Protocol
 
 **Purpose**: Multi-agent planning consultation before implementation. Get specialist perspectives synthesized into an actionable plan.
 
+**Task structure**: 4 phase tasks (`Plan: Analyze` → `Plan: Consult` → `Plan: Synthesize` → `Plan: Present`) + planner subtasks during Consult phase. See SSOT Task Integration for metadata schemas.
+
 **When to use**:
 - Complex features where upfront alignment prevents rework
 - Tasks spanning multiple specialist domains
@@ -50,6 +70,8 @@
 
 **Trigger when**: Blocked; get similar errors repeatedly; or prior phase output is wrong.
 
+**Task structure**: Modifies existing tasks rather than creating new ones. Tracks `imPACTHistory` in task metadata with outcomes and phase changes. See SSOT Task Integration.
+
 **Two questions**:
 1. **Redo prior phase?** — Is the issue upstream in P→A→C→T?
 2. **Additional agents needed?** — Do I need subagents to assist?
@@ -69,6 +91,8 @@ If neither question is "Yes," you're not blocked—continue.
 
 **Core idea**: Single-DOMAIN delegation with light ceremony.
 
+**Task structure**: 1 workflow task (`taskType: "workflow"`) + parallel specialist subtasks. Subtasks linked via `subtaskIds`; workflow task uses `blockedBy` for dependency tracking. See SSOT Task Integration for metadata schemas.
+
 comPACT handles tasks within ONE specialist domain. For independent sub-tasks, it can invoke MULTIPLE specialists of the same type in parallel.
 
 **Available specialists**:
@@ -141,3 +165,22 @@ Invoke multiple specialists of the same type when:
 
 ---
 
+## rePACT Protocol
+
+**Purpose**: Recursive nested PACT cycle for complex sub-tasks discovered during orchestration.
+
+**Task structure**: Nested phase tasks with `rePACT:` prefix (e.g., `rePACT: PREPARE`, `rePACT: CODE`). Parent task uses `blockedBy` linking to nested `rePACT: TEST` task. Max nesting: 2 levels.
+
+**When to use**:
+- Complex sub-component discovered during CODE phase
+- Sub-task needs its own P→A→C→T cycle
+- Single or multi-domain nested work
+
+**Key rules**:
+- Declare nested cycle before starting
+- Parent task blocks until nested TEST completes
+- Nested tasks inherit `featureBranch` from parent
+- Results integrate back into parent workflow
+
+---
+

From 6beec60e979616bf783ae78a35da042447f31178 Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 15:07:52 -0500
Subject: [PATCH 03/10] feat(commands): add Task Management sections to all
 PACT commands

orchestrate.md:
- Task creation at workflow start (4 phase tasks)
- Per-phase task status transitions
- Subtask management and handoff capture

comPACT.md:
- Workflow task creation with specialist subtasks
- Parallel subtask pattern

peer-review.md:
- Reviewer subtasks with verdict/findings structure

plan-mode.md:
- 4 phase tasks with Plan: prefix
- Planner subtasks during Consult phase

rePACT.md:
- Nested tasks with rePACT: prefix
- Parent phase blocking by nested TEST

imPACT.md:
- Task modification logic for blockers
- imPACTHistory tracking schema
- META-BLOCK detection threshold

Part of #112 - PACT Task System Integration
---
 pact-plugin/commands/comPACT.md     | 23 +++++++++
 pact-plugin/commands/imPACT.md      | 55 +++++++++++++++++++++
 pact-plugin/commands/orchestrate.md | 76 +++++++++++++++++++++++++++--
 pact-plugin/commands/peer-review.md | 57 ++++++++++++++++++++++
 pact-plugin/commands/plan-mode.md   | 58 ++++++++++++++++++++++
 pact-plugin/commands/rePACT.md      | 54 ++++++++++++++++++++
 6 files changed, 320 insertions(+), 3 deletions(-)

diff --git a/pact-plugin/commands/comPACT.md b/pact-plugin/commands/comPACT.md
index 79ba5b9a..0541b068 100644
--- a/pact-plugin/commands/comPACT.md
+++ b/pact-plugin/commands/comPACT.md
@@ -115,6 +115,29 @@ Before invoking multiple specialists concurrently, perform this coordination che
 
 ---
 
+## Task Management
+
+Create tasks to track workflow progress:
+
+1. **At start**: Create workflow task `comPACT`
+2. **Before dispatch**: Create specialist subtasks for each work item
+3. **Link**: Workflow `blockedBy` all subtasks (enables parallel execution)
+4. **On completion**: Mark workflow task completed when all subtasks done
+
+**Workflow task metadata**:
+```javascript
+{
+  taskType: "workflow",
+  pactWorkflow: "comPACT",
+  domain: "backend",  // or frontend, database, etc.
+  subtaskIds: ["4", "5"]
+}
+```
+
+**Specialist subtask metadata**: See specialist handoff format in agent definitions.
+
+---
+
 ## Invocation
 
 ### Multiple Specialists Concurrently (Default)
diff --git a/pact-plugin/commands/imPACT.md b/pact-plugin/commands/imPACT.md
index 7f69443b..26a5afe0 100644
--- a/pact-plugin/commands/imPACT.md
+++ b/pact-plugin/commands/imPACT.md
@@ -99,3 +99,58 @@ If the blocker reveals that a sub-task is more complex than expected and needs i
 ```
 /PACT:rePACT backend "implement the OAuth2 token refresh that's blocking us"
 ```
+
+---
+
+## Task Integration
+
+imPACT is triage, not a new workflow. It modifies existing tasks rather than creating new ones.
+
+### Task Behavior
+
+| Action | Task Handling |
+|--------|---------------|
+| **Redo prior phase** | Update phase task status; add to `imPACTHistory` |
+| **Augment present phase** | Create new subtasks under current phase; add to `imPACTHistory` |
+| **Invoke rePACT** | Let rePACT create nested tasks; add to current task's `imPACTHistory` |
+| **Not truly blocked** | Add to `imPACTHistory` with outcome `"clarified"` |
+| **Escalate to user** | Add to `imPACTHistory` with outcome `"escalated"` |
+
+### imPACTHistory Tracking
+
+Every imPACT invocation is recorded in the affected task's metadata:
+
+```javascript
+metadata: {
+  // ... existing task metadata ...
+  imPACTHistory: [
+    {
+      triggeredAt: "2026-01-27T14:30:00Z",
+      outcome: "redo_phase",
+      reason: "Interface mismatch — ARCHITECT phase output incomplete",
+      redoPhase: "architect"
+    },
+    {
+      triggeredAt: "2026-01-27T15:45:00Z",
+      outcome: "augment",
+      reason: "Need parallel backend support for auth flow",
+      subtasksCreated: ["12", "13"]
+    }
+  ]
+}
+```
+
+### imPACTHistory Entry Schema
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `triggeredAt` | ISO timestamp | When imPACT was invoked |
+| `outcome` | enum | `"redo_phase"` \| `"augment"` \| `"repact"` \| `"clarified"` \| `"escalated"` |
+| `reason` | string | Brief explanation of diagnosis and decision |
+| `redoPhase` | string? | Which phase to redo (if `outcome: "redo_phase"`) |
+| `subtasksCreated` | string[]? | IDs of new subtasks (if `outcome: "augment"`) |
+| `rePACTTaskId` | string? | ID of nested rePACT task (if `outcome: "repact"`) |
+
+### META-BLOCK Detection
+
+If `imPACTHistory` reaches 3+ entries without resolution, this triggers an ALERT (META-BLOCK) algedonic signal. The orchestrator must escalate to user.
diff --git a/pact-plugin/commands/orchestrate.md b/pact-plugin/commands/orchestrate.md
index c1b65898..d93ff481 100644
--- a/pact-plugin/commands/orchestrate.md
+++ b/pact-plugin/commands/orchestrate.md
@@ -64,6 +64,42 @@ See [algedonic.md](../protocols/algedonic.md) for signal format and full protoco
 
 ---
 
+## Task Management
+
+At workflow start, create phase tasks to track progress. Use `TodoWrite` to manage tasks throughout.
+
+### Initial Setup (Before Any Phase)
+
+Create 4 phase tasks with sequential dependencies:
+
+```
+TodoWrite([
+  { id: "1", title: "PREPARE", status: "pending", metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "prepare" } },
+  { id: "2", title: "ARCHITECT", status: "pending", blockedBy: ["1"], metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "architect" } },
+  { id: "3", title: "CODE", status: "pending", blockedBy: ["2"], metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "code" } },
+  { id: "4", title: "TEST", status: "pending", blockedBy: ["3"], metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "test" } }
+])
+```
+
+Add to metadata after variety assessment: `variety: { novelty, scope, uncertainty, risk, total }`, `featureBranch`, `planRef` (if plan exists).
+
+### Per-Phase Task Flow
+
+For each phase:
+1. Mark phase `in_progress`
+2. Create specialist subtasks (phase `blockedBy` subtasks)
+3. When subtasks complete, update phase `metadata.handoff` and mark `completed`
+
+### Skipped Phases
+
+When skipping a phase, still create the task but mark immediately completed:
+
+```
+TodoWrite([{ id: "1", title: "PREPARE", status: "completed", metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "prepare", skipped: true, skipReason: "Approved plan exists" } }])
+```
+
+---
+
 ## Before Starting
 
 ### Task Variety Assessment
@@ -193,7 +229,12 @@ Each specialist should end with a structured handoff:
 
 ### Phase 1: PREPARE → `pact-preparer`
 
-**Skip criteria met?** → Proceed to Phase 2.
+**Skip criteria met?** → Mark PREPARE task completed with `skipped: true, skipReason: "..."` → Proceed to Phase 2.
+
+**Task management**:
+1. Mark PREPARE `in_progress`
+2. Create subtask(s): `TodoWrite([{ id: "1-1", title: "Research: {topic}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "1", domain: "prepare", specialist: "pact-preparer" } }])`
+3. Update PREPARE: `blockedBy: ["1-1"]` (and other subtask IDs)
 
 **Plan sections to pass** (if plan exists):
 - "Preparation Phase"
@@ -208,6 +249,8 @@ Each specialist should end with a structured handoff:
 - [ ] Outputs exist in `docs/preparation/`
 - [ ] Specialist handoff received (see Handoff Format below)
 - [ ] If blocker reported → `/PACT:imPACT`
+- [ ] **Update subtask(s)**: Mark `completed` with handoff in metadata
+- [ ] **Update PREPARE task**: Add `metadata.handoff`, mark `completed`
 - [ ] **S4 Checkpoint** (see [pact-s4-checkpoints.md](../protocols/pact-s4-checkpoints.md)): Environment stable? Model aligned? Plan viable?
 
 **Concurrent dispatch within PREPARE**: If research spans multiple independent areas (e.g., "research auth options AND caching strategies"), invoke multiple preparers together with clear scope boundaries.
@@ -230,7 +273,12 @@ If PREPARE ran and ARCHITECT was marked "Skip," compare PREPARE's recommended ap
 
 ### Phase 2: ARCHITECT → `pact-architect`
 
-**Skip criteria met (after re-assessment)?** → Proceed to Phase 3.
+**Skip criteria met (after re-assessment)?** → Mark ARCHITECT task completed with `skipped: true, skipReason: "..."` → Proceed to Phase 3.
+
+**Task management**:
+1. Mark ARCHITECT `in_progress`
+2. Create subtask(s): `TodoWrite([{ id: "2-1", title: "Design: {component}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "2", domain: "architect", specialist: "pact-architect" } }])`
+3. Update ARCHITECT: `blockedBy: ["2-1"]` (and other subtask IDs)
 
 **Plan sections to pass** (if plan exists):
 - "Architecture Phase"
@@ -247,6 +295,8 @@ If PREPARE ran and ARCHITECT was marked "Skip," compare PREPARE's recommended ap
 - [ ] Outputs exist in `docs/architecture/`
 - [ ] Specialist handoff received (see Handoff Format above)
 - [ ] If blocker reported → `/PACT:imPACT`
+- [ ] **Update subtask(s)**: Mark `completed` with handoff in metadata
+- [ ] **Update ARCHITECT task**: Add `metadata.handoff`, mark `completed`
 - [ ] **S4 Checkpoint**: Environment stable? Model aligned? Plan viable?
 
 **Concurrent dispatch within ARCHITECT**: If designing multiple independent components (e.g., "design user service AND notification service"), invoke multiple architects simultaneously. Ensure interface contracts between components are defined as a coordination checkpoint.
@@ -257,6 +307,17 @@ If PREPARE ran and ARCHITECT was marked "Skip," compare PREPARE's recommended ap
 
 **Always runs.** This is the core work.
 
+**Task management**:
+1. Mark CODE `in_progress`
+2. Create subtask(s) for each specialist:
+   ```
+   TodoWrite([
+     { id: "3-1", title: "Backend: {work}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "3", domain: "backend", specialist: "pact-backend-coder" } },
+     { id: "3-2", title: "Frontend: {work}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "3", domain: "frontend", specialist: "pact-frontend-coder" } }
+   ])
+   ```
+3. Update CODE: `blockedBy: ["3-1", "3-2"]` (all subtask IDs)
+
 > **S5 Policy Checkpoint (Pre-CODE)**: Before invoking coders, verify:
 > 1. "Does the architecture align with project principles?"
 > 2. "Am I delegating ALL code changes to specialists?" (orchestrator writes no application code)
@@ -328,6 +389,8 @@ Before concurrent dispatch, check internally: shared files? shared interfaces? c
 - [ ] All tests passing (full test suite; fix any tests your changes break)
 - [ ] Specialist handoff(s) received (see Handoff Format above)
 - [ ] If blocker reported → `/PACT:imPACT`
+- [ ] **Update subtask(s)**: Mark `completed` with handoff in metadata
+- [ ] **Update CODE task**: Add `metadata.handoff`, mark `completed`
 - [ ] **Create atomic commit(s)** of CODE phase work (preserves work before strategic re-assessment)
 - [ ] **S4 Checkpoint**: Environment stable? Model aligned? Plan viable?
 
@@ -350,7 +413,12 @@ If a sub-task emerges that is too complex for a single specialist invocation:
 
 ### Phase 4: TEST → `pact-test-engineer`
 
-**Skip criteria met?** → Proceed to "After All Phases Complete."
+**Skip criteria met?** → Mark TEST task completed with `skipped: true, skipReason: "..."` → Proceed to "After All Phases Complete."
+
+**Task management**:
+1. Mark TEST `in_progress`
+2. Create subtask(s): `TodoWrite([{ id: "4-1", title: "Test: {suite}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "4", domain: "test", specialist: "pact-test-engineer" } }])`
+3. Update TEST: `blockedBy: ["4-1"]` (and other subtask IDs)
 
 **Plan sections to pass** (if plan exists):
 - "Test Phase"
@@ -368,6 +436,8 @@ If a sub-task emerges that is too complex for a single specialist invocation:
 - [ ] All tests passing
 - [ ] Specialist handoff received (see Handoff Format above)
 - [ ] If blocker reported → `/PACT:imPACT`
+- [ ] **Update subtask(s)**: Mark `completed` with handoff in metadata
+- [ ] **Update TEST task**: Add `metadata.handoff`, mark `completed`
 - [ ] **Create atomic commit(s)** of TEST phase work (preserves work before strategic re-assessment)
 
 **Concurrent dispatch within TEST**: If test suites are independent (e.g., "unit tests AND E2E tests" or "API tests AND UI tests"), invoke multiple test engineers at once with clear suite boundaries.
diff --git a/pact-plugin/commands/peer-review.md b/pact-plugin/commands/peer-review.md
index 931143a7..f0f2b375 100644
--- a/pact-plugin/commands/peer-review.md
+++ b/pact-plugin/commands/peer-review.md
@@ -4,6 +4,63 @@ argument-hint: [e.g., feature X implementation]
 ---
 Review the current work: $ARGUMENTS
 
+---
+
+## Task Management
+
+**At workflow start**, create the workflow task and reviewer subtasks:
+
+```
+1. Create workflow task: "Peer Review"
+   - metadata: { taskType: "workflow", pactWorkflow: "peer-review" }
+
+2. Create reviewer subtasks (all parallel):
+   - "Review: Architecture" → pact-architect
+   - "Review: Test coverage" → pact-test-engineer
+   - "Review: {Domain}" → domain specialist (e.g., "Review: Backend")
+
+3. Set workflow task blockedBy all reviewer subtasks
+```
+
+**Reviewer subtask metadata**:
+```javascript
+{
+  taskType: "specialist",
+  workflowTaskId: "<workflow-task-id>",
+  reviewer: "pact-architect" | "pact-test-engineer" | "pact-backend-coder" | ...,
+  focus: "architecture" | "test-coverage" | "backend" | "frontend" | "database"
+}
+```
+
+**On reviewer completion**, capture structured handoff:
+```javascript
+{
+  handoff: {
+    verdict: "approve" | "request-changes" | "comment",
+    findings: [
+      { severity: "blocking" | "minor" | "future", description: "...", recommendation: "..." }
+    ],
+    summary: "One-line review summary"
+  }
+}
+```
+
+**On workflow completion**, aggregate in workflow task metadata:
+```javascript
+{
+  handoff: {
+    overallVerdict: "approve" | "request-changes",
+    reviewerVerdicts: { "architecture": "approve", "test-coverage": "request-changes", ... },
+    consolidatedFindings: [...],  // merged from all reviewers
+    mergeReady: true | false
+  }
+}
+```
+
+---
+
+## Workflow Steps
+
 1. Commit any uncommitted work
 2. Create a PR if one doesn't exist
 3. Review the PR
diff --git a/pact-plugin/commands/plan-mode.md b/pact-plugin/commands/plan-mode.md
index 9da67ab3..d28ea5c0 100644
--- a/pact-plugin/commands/plan-mode.md
+++ b/pact-plugin/commands/plan-mode.md
@@ -38,6 +38,64 @@ See [pact-variety.md](../protocols/pact-variety.md) for the Variety Management a
 
 ---
 
+## Task Management
+
+Plan-mode creates **phase tasks** to track planning progress and **planner subtasks** for specialist consultations. This is planning consultation only — no implementation tasks are created.
+
+### Phase Tasks
+
+Create 4 sequential phase tasks at the start of plan-mode:
+
+| Task Name | blockedBy | Description |
+|-----------|-----------|-------------|
+| `Plan: Analyze` | — | Orchestrator scope analysis |
+| `Plan: Consult` | `Plan: Analyze` | Parallel specialist consultation |
+| `Plan: Synthesize` | `Plan: Consult` | Orchestrator conflict resolution and roadmap |
+| `Plan: Present` | `Plan: Synthesize` | Save plan, resolve user decisions |
+
+### Planner Subtasks
+
+During the **Consult phase**, create subtasks for each specialist being consulted:
+
+| Subtask Name | Example |
+|--------------|---------|
+| `Plan: {Domain} perspective` | `Plan: Backend perspective` |
+| | `Plan: Architecture perspective` |
+| | `Plan: Testing perspective` |
+
+- All planner subtasks run **in parallel** (no inter-dependencies)
+- `Plan: Consult` task is `blockedBy` all its subtasks
+- When all subtasks complete, `Plan: Consult` auto-unblocks
+
+### Phase Task Metadata
+
+```javascript
+{
+  taskType: "phase",
+  pactWorkflow: "plan-mode",
+  phase: "analyze" | "consult" | "synthesize" | "present",
+  featureSlug: "user-auth-jwt",
+  planRef: "docs/plans/user-auth-jwt-plan.md",  // Set after plan is saved
+  subtaskIds: ["4", "5", "6"],  // For Consult phase only
+  handoff: {
+    summary: "Identified 3 specialists needed; 2 conflicts to resolve",
+    keyDecisions: ["Use JWT over sessions"],
+    unresolvedItems: [{ priority: "high", description: "Auth provider choice" }]
+  }
+}
+```
+
+### Key Differences from Orchestrate
+
+| Aspect | plan-mode | orchestrate |
+|--------|-----------|-------------|
+| Phase prefix | `Plan:` | None (`PREPARE`, `CODE`, etc.) |
+| Output | `planRef` to docs/plans/ | Implementation artifacts |
+| Subtask work | Planning analysis | Implementation code |
+| Creates implementation? | No | Yes |
+
+---
+
 ## Your Workflow
 
 ### Phase 0: Orchestrator Analysis
diff --git a/pact-plugin/commands/rePACT.md b/pact-plugin/commands/rePACT.md
index 1cdc4695..5dee49f9 100644
--- a/pact-plugin/commands/rePACT.md
+++ b/pact-plugin/commands/rePACT.md
@@ -8,6 +8,60 @@ This command initiates a **nested P→A→C→T cycle** for a sub-task that is t
 
 ---
 
+## Task Management
+
+### Nested Task Structure
+
+When rePACT starts, create nested phase tasks with `rePACT:` prefix:
+
+```
+rePACT: PREPARE    (nested)
+rePACT: ARCHITECT  (nested)
+rePACT: CODE       (nested)
+rePACT: TEST       (nested)
+```
+
+The parent phase (from the outer orchestration) is `blockedBy` the nested `rePACT: TEST` task. This ensures the parent waits for the full nested cycle to complete.
+
+### Nested Task Metadata
+
+```javascript
+{
+  taskType: "phase",
+  pactWorkflow: "rePACT",
+  phase: "prepare" | "architect" | "code" | "test",
+  nestingLevel: 1 | 2,
+  parentPhaseId: "3",        // ID of the parent phase task that spawned this rePACT
+  parentWorkflow: "orchestrate",
+  domain: "backend" | "frontend" | "database" | null,  // null if multi-domain
+  handoff: { ... }
+}
+```
+
+### Parent-Child Linkage
+
+1. **At rePACT start**: Record `parentPhaseId` from the outer phase that invoked rePACT
+2. **Create 4 nested tasks**: `rePACT: PREPARE` → `rePACT: ARCHITECT` → `rePACT: CODE` → `rePACT: TEST`
+3. **Set dependencies**:
+   - Sequential within nested cycle: ARCH blockedBy PREP, CODE blockedBy ARCH, TEST blockedBy CODE
+   - Parent blocked: Parent phase `blockedBy` nested `rePACT: TEST`
+4. **On completion**: Nested TEST completes → parent phase auto-unblocks
+
+### Example Task Structure
+
+```
+Parent: CODE (id: 3, status: in_progress)
+  └── blockedBy: "7" (rePACT: TEST)
+
+Nested tasks:
+  rePACT: PREPARE   (id: 4, parentPhaseId: "3")
+  rePACT: ARCHITECT (id: 5, parentPhaseId: "3", blockedBy: "4")
+  rePACT: CODE      (id: 6, parentPhaseId: "3", blockedBy: "5")
+  rePACT: TEST      (id: 7, parentPhaseId: "3", blockedBy: "6")
+```
+
+---
+
 ## When to Use rePACT
 
 Use `/PACT:rePACT` when:

From e92c8c29207c0cb244d92ea379fc2fc6c85488de Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 15:07:59 -0500
Subject: [PATCH 04/10] feat(agents): standardize HANDOFF sections across all
 specialists

Add consistent HANDOFF format to all agent definitions:
- Produced: artifacts created/modified
- Decisions: choices made during work
- Uncertainties: items needing orchestrator attention
- Open Questions: unresolved items for future work

Updated agents:
- pact-architect.md (new section)
- pact-backend-coder.md (updated)
- pact-database-engineer.md (updated)
- pact-frontend-coder.md (updated)
- pact-preparer.md (new section)
- pact-test-engineer.md (updated)

Part of #112 - PACT Task System Integration
---
 pact-plugin/agents/pact-architect.md         | 8 ++++++++
 pact-plugin/agents/pact-backend-coder.md     | 8 ++++----
 pact-plugin/agents/pact-database-engineer.md | 8 ++++----
 pact-plugin/agents/pact-frontend-coder.md    | 8 ++++----
 pact-plugin/agents/pact-preparer.md          | 8 ++++++++
 pact-plugin/agents/pact-test-engineer.md     | 8 ++++----
 6 files changed, 32 insertions(+), 16 deletions(-)

diff --git a/pact-plugin/agents/pact-architect.md b/pact-plugin/agents/pact-architect.md
index c28d982f..e467481a 100644
--- a/pact-plugin/agents/pact-architect.md
+++ b/pact-plugin/agents/pact-architect.md
@@ -127,6 +127,14 @@ Before finalizing any architecture, verify:
 
 Your work is complete when you deliver architectural specifications in a markdown file that can guide a development team to successful implementation without requiring clarification of design intent.
 
+**HANDOFF**
+
+End with a structured handoff for the orchestrator (enables task system integration):
+1. **Produced**: Architecture documents created/modified
+2. **Decisions**: Key architectural choices with rationale (patterns, trade-offs, technology selections)
+3. **Uncertainties**: Areas where design assumptions may not hold, integration risks
+4. **Open Questions**: Anything requiring user input or further research
+
 **AUTONOMY CHARTER**
 
 You have authority to:
diff --git a/pact-plugin/agents/pact-backend-coder.md b/pact-plugin/agents/pact-backend-coder.md
index bec2b67e..70866722 100644
--- a/pact-plugin/agents/pact-backend-coder.md
+++ b/pact-plugin/agents/pact-backend-coder.md
@@ -106,11 +106,11 @@ Your work isn't done until smoke tests pass. Smoke tests verify: "Does it compil
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator:
+End with a structured handoff for the orchestrator (enables task system integration):
 1. **Produced**: Files created/modified
-2. **Key context**: Decisions made, patterns used, assumptions
-3. **Areas of uncertainty**: Where bugs might hide, tricky parts (helps TEST phase)
-4. **Open questions**: Anything unresolved
+2. **Decisions**: Key choices made with rationale (patterns used, assumptions)
+3. **Uncertainties**: Where bugs might hide, tricky parts (helps TEST phase)
+4. **Open Questions**: Anything unresolved
 
 **AUTONOMY CHARTER**
 
diff --git a/pact-plugin/agents/pact-database-engineer.md b/pact-plugin/agents/pact-database-engineer.md
index 15aeaece..5a135957 100644
--- a/pact-plugin/agents/pact-database-engineer.md
+++ b/pact-plugin/agents/pact-database-engineer.md
@@ -124,11 +124,11 @@ Your work isn't done until smoke tests pass. Smoke tests verify: "Does the schem
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator:
+End with a structured handoff for the orchestrator (enables task system integration):
 1. **Produced**: Files created/modified (schemas, migrations, queries)
-2. **Key context**: Decisions made (normalization, indexes), patterns used, assumptions
-3. **Areas of uncertainty**: Where performance issues might hide, tricky queries (helps TEST phase)
-4. **Open questions**: Anything unresolved
+2. **Decisions**: Key choices made with rationale (normalization, indexes, patterns used, assumptions)
+3. **Uncertainties**: Where performance issues might hide, tricky queries (helps TEST phase)
+4. **Open Questions**: Anything unresolved
 
 **AUTONOMY CHARTER**
 
diff --git a/pact-plugin/agents/pact-frontend-coder.md b/pact-plugin/agents/pact-frontend-coder.md
index 7285e088..6fb88d9f 100644
--- a/pact-plugin/agents/pact-frontend-coder.md
+++ b/pact-plugin/agents/pact-frontend-coder.md
@@ -97,11 +97,11 @@ Your work isn't done until smoke tests pass. Smoke tests verify: "Does it compil
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator:
+End with a structured handoff for the orchestrator (enables task system integration):
 1. **Produced**: Files created/modified
-2. **Key context**: Decisions made, patterns used, assumptions
-3. **Areas of uncertainty**: Where bugs might hide, tricky parts (helps TEST phase)
-4. **Open questions**: Anything unresolved
+2. **Decisions**: Key choices made with rationale (patterns used, assumptions)
+3. **Uncertainties**: Where bugs might hide, tricky parts (helps TEST phase)
+4. **Open Questions**: Anything unresolved
 
 **AUTONOMY CHARTER**
 
diff --git a/pact-plugin/agents/pact-preparer.md b/pact-plugin/agents/pact-preparer.md
index 441f90ea..04de7168 100644
--- a/pact-plugin/agents/pact-preparer.md
+++ b/pact-plugin/agents/pact-preparer.md
@@ -129,6 +129,14 @@ Remember: Your research forms the foundation for the entire project. Be thorough
 
 MANDATORY: Pass back to the Orchestrator upon completion of your markdown files.
 
+**HANDOFF**
+
+End with a structured handoff for the orchestrator (enables task system integration):
+1. **Produced**: Research documents created/modified
+2. **Decisions**: Key recommendations with rationale (technology choices, approach selections)
+3. **Uncertainties**: Conflicting information found, areas needing validation
+4. **Open Questions**: Anything requiring user input or further investigation
+
 **AUTONOMY CHARTER**
 
 You have authority to:
diff --git a/pact-plugin/agents/pact-test-engineer.md b/pact-plugin/agents/pact-test-engineer.md
index f75d040b..53ffe528 100644
--- a/pact-plugin/agents/pact-test-engineer.md
+++ b/pact-plugin/agents/pact-test-engineer.md
@@ -227,11 +227,11 @@ The orchestrator passes CODE phase handoff summaries. Use these for context:
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator:
+End with a structured handoff for the orchestrator (enables task system integration):
 1. **Produced**: Test files created, coverage achieved
-2. **Key context**: Testing approach, areas prioritized
-3. **Areas of uncertainty**: Edge cases not covered, flaky tests, known issues
-4. **Open questions**: Anything unresolved
+2. **Decisions**: Testing approach chosen, areas prioritized with rationale
+3. **Uncertainties**: Edge cases not covered, flaky tests, known issues
+4. **Open Questions**: Anything unresolved
 
 **AUTONOMY CHARTER**
 

From 04c17002e95c2223c10d89ee0f57a6a63d0a9d73 Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 15:08:05 -0500
Subject: [PATCH 05/10] docs(reference): add Task system reference
 documentation

task-metadata-schema.md:
- Complete field definitions for all 3 task types
- Phase Task, Specialist Subtask, Workflow Task schemas
- Examples and required vs optional field guidance

task-integration-guide.md:
- How Task system integrates with PACT methodology
- Workflow integration details for each command
- Best practices and VSM mapping
- Migration guide for existing sessions

Part of #112 - PACT Task System Integration
---
 .../reference/task-integration-guide.md       | 385 +++++++++++++++
 pact-plugin/reference/task-metadata-schema.md | 446 ++++++++++++++++++
 2 files changed, 831 insertions(+)
 create mode 100644 pact-plugin/reference/task-integration-guide.md
 create mode 100644 pact-plugin/reference/task-metadata-schema.md

diff --git a/pact-plugin/reference/task-integration-guide.md b/pact-plugin/reference/task-integration-guide.md
new file mode 100644
index 00000000..73f48f3c
--- /dev/null
+++ b/pact-plugin/reference/task-integration-guide.md
@@ -0,0 +1,385 @@
+# Task Integration Guide
+
+> **Purpose**: How PACT methodology integrates with Claude Code's native Task system. Reference for orchestrators and developers understanding the hybrid model.
+>
+> **Audience**: PACT orchestrators, plugin developers, users wanting to understand task flow.
+
+---
+
+## Overview
+
+PACT uses Claude Code's Task system as a **work tracking layer** while preserving PACT's **methodology layer**:
+
+| Layer | What It Provides | Owned By |
+|-------|------------------|----------|
+| **Task System** | Status tracking, dependencies, blocking relationships | Claude Code |
+| **PACT Methodology** | VSM structure, phases, coordination protocols, handoffs | PACT framework |
+
+This separation means:
+- Tasks track *what* is happening (status, blockers, completion)
+- PACT protocols define *how* work flows (phases, delegation, quality gates)
+
+---
+
+## The Hybrid Task Model
+
+### Core Concept
+
+**Phase tasks** (owned by orchestrator) contain **specialist subtasks** (owned by specialists).
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  /PACT:orchestrate "Implement user authentication"          │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  PREPARE ──► ARCHITECT ──► CODE ──► TEST                   │
+│  (phase)     (phase)       (phase)   (phase)                │
+│                              │                              │
+│                              ▼                              │
+│                    ┌─────────────────┐                      │
+│                    │ CODE blockedBy: │                      │
+│                    │ - Backend: ...  │ (subtask)            │
+│                    │ - Frontend: ... │ (subtask)            │
+│                    │ - Database: ... │ (subtask)            │
+│                    └─────────────────┘                      │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Why This Model?
+
+1. **Visibility**: Tasks surface work status without reading agent threads
+2. **Dependencies**: `blockedBy` relationships encode phase sequencing
+3. **Parallelism**: Subtasks within a phase can run concurrently
+4. **Handoffs**: Structured metadata captures context for next phase
+
+---
+
+## Workflow Integration
+
+### /PACT:orchestrate
+
+Full PACT cycle with all four phases.
+
+**Task Structure**:
+```
+At start:
+  Create: PREPARE, ARCHITECT, CODE, TEST (4 phase tasks)
+  Set: ARCHITECT blockedBy PREPARE
+       CODE blockedBy ARCHITECT
+       TEST blockedBy CODE
+
+Per phase:
+  1. Mark phase in_progress
+  2. Create specialist subtasks
+  3. Phase blockedBy its subtasks
+  4. Specialists work (parallel)
+  5. Subtasks complete → phase auto-unblocks
+  6. Orchestrator marks phase completed
+```
+
+**Skipped Phases**:
+When a phase is skipped (e.g., skip PREPARE for routine tasks):
+- Create the phase task anyway
+- Immediately mark `completed`
+- Set `metadata: { skipped: true, skipReason: "..." }`
+
+This preserves the audit trail while allowing flexibility.
+
+### /PACT:comPACT
+
+Single-domain delegation with light ceremony.
+
+**Task Structure**:
+```
+Create: 1 workflow task (comPACT)
+Create: Specialist subtasks for work items
+Set: Workflow blockedBy all subtasks
+All subtasks parallel (no inter-dependencies)
+```
+
+**Example**: "Fix 3 backend bugs"
+```
+comPACT (workflow)
+├── Backend: Fix bug #1 (subtask) ──┐
+├── Backend: Fix bug #2 (subtask) ──┼── all parallel
+└── Backend: Fix bug #3 (subtask) ──┘
+```
+
+### /PACT:peer-review
+
+Multi-agent code review before PR.
+
+**Task Structure**:
+```
+Create: 1 workflow task (Peer Review)
+Create: Reviewer subtasks:
+  - Review: Architecture
+  - Review: Test coverage
+  - Review: {Domain} (based on PR focus)
+All reviewers parallel
+Handoff includes verdict + findings
+```
+
+**Verdict Values**:
+- `APPROVED` - Ready to merge
+- `CHANGES_REQUESTED` - Issues must be addressed
+- `NEEDS_DISCUSSION` - Requires user input on trade-offs
+
+### /PACT:plan-mode
+
+Planning consultation before implementation.
+
+**Task Structure**:
+```
+Create: 4 phase tasks (Plan: Analyze → Consult → Synthesize → Present)
+During Consult:
+  Create planner subtasks: Plan: Backend perspective, etc.
+All planners parallel
+Output: planRef to docs/plans/
+```
+
+**Key Difference**: No implementation occurs. Specialists operate in "planning-only mode" (analysis, recommendations, not code).
+
+### /PACT:rePACT
+
+Nested PACT cycle for complex sub-tasks.
+
+**Task Structure**:
+```
+Create: Nested phase tasks with rePACT: prefix
+  rePACT: PREPARE → rePACT: ARCHITECT → rePACT: CODE → rePACT: TEST
+Link: parentPhaseId points to spawning phase
+Block: Parent phase blockedBy nested TEST task
+```
+
+**Nesting Limit**: Maximum 2 levels to prevent infinite recursion.
+
+### /PACT:imPACT
+
+Triage when blocked. Modifies existing tasks rather than creating new ones.
+
+**Task Modifications**:
+- No new workflow task created
+- Tracks `imPACTHistory` in current phase task's metadata
+- May create additional subtasks (if "proceed with help")
+- May reset phase status (if "redo")
+
+---
+
+## Task Lifecycle
+
+### Status Transitions
+
+| Status | Meaning | Triggered By |
+|--------|---------|--------------|
+| `pending` | Not yet started | Task creation |
+| `in_progress` | Work underway | Orchestrator starts phase |
+| `blocked` | Waiting on dependencies | `blockedBy` relationship active |
+| `completed` | Work finished | Orchestrator marks done after handoff |
+
+### Who Updates Status?
+
+**Orchestrator owns all status transitions.**
+
+Specialists:
+- Do NOT update task status
+- Return structured handoffs
+- Report blockers to orchestrator
+
+Orchestrator:
+- Creates tasks
+- Marks `in_progress` when starting
+- Marks `completed` after receiving handoff
+- Handles `blockedBy` relationships
+
+This maintains clean separation: specialists focus on work, orchestrator manages coordination.
+
+---
+
+## Handoff Patterns
+
+### Phase Handoffs
+
+When a phase completes, the orchestrator captures:
+
+```javascript
+handoff: {
+  summary: "Brief description of accomplishments",
+  produced: ["list", "of", "files"],
+  keyDecisions: ["decisions", "with", "rationale"],
+  unresolvedItems: [
+    { priority: "HIGH", description: "Needs attention" }
+  ],
+  nextPhaseContext: "What the next phase needs to know"
+}
+```
+
+### Specialist Handoffs
+
+When a specialist completes, they return:
+
+```javascript
+handoff: {
+  produced: ["files", "created"],
+  decisions: ["implementation", "decisions"],
+  uncertainties: [
+    { priority: "HIGH", description: "Potential issue" }
+  ],
+  openQuestions: ["Unresolved items"]
+}
+```
+
+### Context Flow
+
+```
+PREPARE handoff → ARCHITECT receives nextPhaseContext
+ARCHITECT handoff → CODE receives nextPhaseContext
+CODE handoff → TEST receives nextPhaseContext (especially uncertainties)
+```
+
+**Uncertainty Priority Levels**:
+- **HIGH**: "This could break in production" — TEST must cover
+- **MEDIUM**: "Not 100% confident" — TEST should cover
+- **LOW**: "Edge case I thought of" — TEST discretion
+
+---
+
+## Best Practices
+
+### 1. Reference, Don't Duplicate
+
+Use references to maintain context without bloating task metadata:
+
+| Instead of | Use |
+|------------|-----|
+| Copying plan content into metadata | `planRef: "docs/plans/..."` |
+| Duplicating phase context | `phaseTaskId` to look up parent |
+| Embedding file contents | `produced: ["file/paths"]` |
+
+### 2. Structured Handoffs Over Free Text
+
+Handoffs should be machine-parseable:
+
+```javascript
+// Good
+uncertainties: [
+  { priority: "HIGH", description: "Race condition in token refresh" }
+]
+
+// Avoid
+notes: "There might be a race condition, not sure how serious..."
+```
+
+### 3. Let Dependencies Do the Work
+
+Use `blockedBy` relationships instead of manual coordination:
+
+```javascript
+// Good: Automatic unblocking
+CODE.blockedBy = [subtask1, subtask2, subtask3]
+// When all complete → CODE auto-unblocks
+
+// Avoid: Manual polling
+// "Check if backend finished before starting frontend..."
+```
+
+### 4. Preserve Audit Trail
+
+Even for skipped work, create the task:
+
+```javascript
+// Phase skipped but recorded
+{
+  taskType: "phase",
+  phase: "prepare",
+  status: "completed",
+  skipped: true,
+  skipReason: "Routine task, requirements clear from description"
+}
+```
+
+### 5. Algedonic Signals Annotate, Don't Create
+
+When an algedonic signal fires:
+- Annotate the current task with `algedonicHalt` or `algedonicAlert`
+- Don't create a new "Algedonic" task
+- This keeps signals attached to their context
+
+---
+
+## Relationship to PACT Concepts
+
+### VSM Mapping
+
+| VSM System | Task System Role |
+|------------|------------------|
+| **S1 (Operations)** | Specialist subtasks — the actual work |
+| **S2 (Coordination)** | `blockedBy` relationships, parallel subtask management |
+| **S3 (Control)** | Phase tasks — orchestrator's operational view |
+| **S4 (Intelligence)** | Variety metadata, S4 checkpoints in handoffs |
+| **S5 (Policy)** | Algedonic annotations bypass normal flow |
+
+### Phase Boundaries
+
+Tasks make phase boundaries explicit:
+
+```
+PREPARE completed → S4 checkpoint → ARCHITECT in_progress
+```
+
+The task status transition is the trigger for S4 checkpoint evaluation.
+
+### Parallel Coordination (S2)
+
+Task system supports S2 coordination:
+
+1. **Pre-parallel check**: Before creating parallel subtasks, verify no file conflicts
+2. **Subtask independence**: Parallel subtasks have no `blockedBy` between them
+3. **Convention propagation**: First subtask's decisions noted in metadata for others
+
+---
+
+## Troubleshooting
+
+### Task Stuck in Blocked State
+
+**Check**: Are all `blockedBy` tasks completed?
+
+**Common causes**:
+- Subtask completed but status not updated
+- Circular dependency (shouldn't happen with PACT structure)
+- Subtask failed and wasn't handled
+
+### Missing Handoff Data
+
+**Check**: Did specialist return structured handoff?
+
+**Common causes**:
+- Agent thread ended unexpectedly
+- Handoff not captured in task metadata
+
+**Recovery**: Orchestrator can reconstruct from agent output or re-run subtask.
+
+### Algedonic Signal Not Surfacing
+
+**Check**: Is `awaitingAcknowledgment` or `awaitingDecision` set to `true`?
+
+**Protocol**: Algedonic signals must surface immediately. If task shows signal but user wasn't notified, this is a bug in orchestrator behavior.
+
+---
+
+## Migration Notes
+
+### From Pre-Task PACT
+
+If using PACT before Task integration:
+- Handoff structure remains the same
+- Phase sequencing now explicit in task dependencies
+- Agent coordination unchanged (orchestrator still manages)
+
+### Task System Requirements
+
+- Claude Code v2.1.16+ required
+- Task primitives: create, update status, set blockedBy, add metadata
+- Orchestrator handles all task operations (specialists don't need task access)
diff --git a/pact-plugin/reference/task-metadata-schema.md b/pact-plugin/reference/task-metadata-schema.md
new file mode 100644
index 00000000..0fe5f4df
--- /dev/null
+++ b/pact-plugin/reference/task-metadata-schema.md
@@ -0,0 +1,446 @@
+# Task Metadata Schema Reference
+
+> **Purpose**: Complete schema documentation for PACT task metadata. Use as reference when creating or interpreting task structures.
+>
+> **Context**: PACT integrates with Claude Code's native Task system (v2.1.16+). Tasks use structured metadata to preserve PACT methodology context.
+
+---
+
+## Task Types Overview
+
+| Type | Owner | Purpose | Example Names |
+|------|-------|---------|---------------|
+| **Phase** | Orchestrator | Track PACT phase progress | `PREPARE`, `CODE`, `TEST` |
+| **Specialist** | Specialist agent | Track individual work items | `Backend: Implement auth` |
+| **Workflow** | Orchestrator | Track lightweight workflows | `comPACT`, `Peer Review` |
+
+---
+
+## Phase Task Schema
+
+Phase tasks represent the four PACT phases (Prepare, Architect, Code, Test) or plan-mode phases.
+
+### Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `taskType` | string | Yes | Always `"phase"` |
+| `pactWorkflow` | string | Yes | `"orchestrate"` or `"plan-mode"` |
+| `phase` | string | Yes | `"prepare"` \| `"architect"` \| `"code"` \| `"test"` |
+| `variety` | object | No | Variety assessment (see below) |
+| `featureBranch` | string | No | Git branch name (e.g., `"feature/user-auth"`) |
+| `planRef` | string | No | Path to plan document (e.g., `"docs/plans/user-auth-plan.md"`) |
+| `subtaskIds` | string[] | No | IDs of specialist subtasks belonging to this phase |
+| `skipped` | boolean | No | `true` if phase was skipped |
+| `skipReason` | string | No | Reason for skipping (when `skipped: true`) |
+| `handoff` | object | No | Phase completion handoff (see below) |
+
+### Variety Object
+
+| Field | Type | Range | Description |
+|-------|------|-------|-------------|
+| `novelty` | number | 1-4 | How new is this work? |
+| `scope` | number | 1-4 | How many concerns involved? |
+| `uncertainty` | number | 1-4 | How clear are requirements? |
+| `risk` | number | 1-4 | What's the impact if wrong? |
+| `total` | number | 4-16 | Sum of dimensions |
+
+### Phase Handoff Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `summary` | string | Brief description of what was accomplished |
+| `produced` | string[] | Files or artifacts created/modified |
+| `keyDecisions` | string[] | Important decisions made during the phase |
+| `unresolvedItems` | array | Items needing attention (see below) |
+| `nextPhaseContext` | string | Context the next phase needs to know |
+
+### Unresolved Item Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `priority` | string | `"HIGH"` \| `"MEDIUM"` \| `"LOW"` |
+| `description` | string | What needs attention |
+
+### Example
+
+```javascript
+{
+  taskType: "phase",
+  pactWorkflow: "orchestrate",
+  phase: "code",
+  variety: {
+    novelty: 2,
+    scope: 3,
+    uncertainty: 2,
+    risk: 3,
+    total: 10
+  },
+  featureBranch: "feature/user-auth",
+  planRef: "docs/plans/user-auth-plan.md",
+  subtaskIds: ["4", "5", "6"],
+  handoff: {
+    summary: "Implemented authentication service with JWT tokens",
+    produced: [
+      "src/auth/token-manager.ts",
+      "src/auth/middleware.ts"
+    ],
+    keyDecisions: [
+      "Used JWT with 15min expiry for access tokens",
+      "Refresh tokens stored in httpOnly cookies"
+    ],
+    unresolvedItems: [
+      { priority: "MEDIUM", description: "Token refresh race condition needs testing" }
+    ],
+    nextPhaseContext: "Focus testing on concurrent token refresh scenarios"
+  }
+}
+```
+
+---
+
+## Specialist Subtask Schema
+
+Specialist subtasks represent work delegated to individual specialist agents (coders, architect, preparer, test engineer).
+
+### Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `taskType` | string | Yes | Always `"specialist"` |
+| `phaseTaskId` | string | Yes | ID of parent phase task |
+| `domain` | string | Yes | `"backend"` \| `"frontend"` \| `"database"` \| `"architecture"` \| `"preparation"` \| `"test"` |
+| `specialist` | string | Yes | Agent type (e.g., `"pact-backend-coder"`) |
+| `agentId` | string | No | Claude Code agent instance ID |
+| `handoff` | object | No | Specialist completion handoff (see below) |
+
+### Specialist Handoff Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `produced` | string[] | Files created or modified |
+| `decisions` | string[] | Key implementation decisions with rationale |
+| `uncertainties` | array | Areas of uncertainty (see below) |
+| `openQuestions` | string[] | Unresolved questions for orchestrator |
+
+### Uncertainty Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `priority` | string | `"HIGH"` \| `"MEDIUM"` \| `"LOW"` |
+| `description` | string | What's uncertain and why it matters |
+
+### Example
+
+```javascript
+{
+  taskType: "specialist",
+  phaseTaskId: "3",
+  domain: "backend",
+  specialist: "pact-backend-coder",
+  agentId: "agent-abc123",
+  handoff: {
+    produced: [
+      "src/auth/token-manager.ts",
+      "src/auth/token-manager.test.ts"
+    ],
+    decisions: [
+      "Used symmetric signing for JWTs (faster, simpler for single-service)",
+      "Token storage uses in-memory cache with Redis fallback"
+    ],
+    uncertainties: [
+      { priority: "HIGH", description: "Race condition possible during concurrent token refresh" },
+      { priority: "MEDIUM", description: "Clock skew >5s may cause validation failures" }
+    ],
+    openQuestions: [
+      "Should refresh tokens use rotation?"
+    ]
+  }
+}
+```
+
+---
+
+## Workflow Task Schema
+
+Workflow tasks represent lightweight workflows like comPACT or peer review that don't use the full PACT phase structure.
+
+### Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `taskType` | string | Yes | Always `"workflow"` |
+| `pactWorkflow` | string | Yes | `"comPACT"` \| `"peer-review"` |
+| `domain` | string | No | Primary domain (for comPACT) |
+| `subtaskIds` | string[] | No | IDs of specialist/reviewer subtasks |
+| `handoff` | object | No | Workflow completion handoff |
+
+### Workflow Handoff Object (comPACT)
+
+Same structure as Specialist Handoff.
+
+### Workflow Handoff Object (Peer Review)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `verdict` | string | `"APPROVED"` \| `"CHANGES_REQUESTED"` \| `"NEEDS_DISCUSSION"` |
+| `findings` | array | Review findings (see below) |
+| `summary` | string | Overall review summary |
+
+### Finding Object
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `reviewer` | string | Which reviewer found this |
+| `severity` | string | `"CRITICAL"` \| `"MAJOR"` \| `"MINOR"` \| `"SUGGESTION"` |
+| `category` | string | `"security"` \| `"performance"` \| `"design"` \| `"testing"` \| `"style"` |
+| `description` | string | What was found |
+| `location` | string | File and line (if applicable) |
+
+### Example (comPACT)
+
+```javascript
+{
+  taskType: "workflow",
+  pactWorkflow: "comPACT",
+  domain: "backend",
+  subtaskIds: ["7", "8"],
+  handoff: {
+    produced: ["src/api/validation.ts"],
+    decisions: ["Used Zod for schema validation"],
+    uncertainties: [],
+    openQuestions: []
+  }
+}
+```
+
+### Example (Peer Review)
+
+```javascript
+{
+  taskType: "workflow",
+  pactWorkflow: "peer-review",
+  subtaskIds: ["10", "11", "12"],
+  handoff: {
+    verdict: "CHANGES_REQUESTED",
+    summary: "Good implementation overall; two security items need addressing",
+    findings: [
+      {
+        reviewer: "pact-architect",
+        severity: "MAJOR",
+        category: "security",
+        description: "JWT secret loaded from env but not validated at startup",
+        location: "src/auth/config.ts:15"
+      },
+      {
+        reviewer: "pact-test-engineer",
+        severity: "MINOR",
+        category: "testing",
+        description: "Missing test for token expiry edge case",
+        location: "src/auth/token-manager.test.ts"
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Nested Task Schema (rePACT)
+
+Nested PACT cycles use the same Phase Task schema with additional fields for parent linkage.
+
+### Additional Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `parentPhaseId` | string | Yes | ID of parent phase task that spawned this nested cycle |
+| `nestingLevel` | number | Yes | Depth of nesting (1 or 2; max is 2) |
+
+### Naming Convention
+
+Nested phase tasks use `rePACT:` prefix: `rePACT: PREPARE`, `rePACT: CODE`, etc.
+
+### Example
+
+```javascript
+{
+  taskType: "phase",
+  pactWorkflow: "orchestrate",
+  phase: "code",
+  parentPhaseId: "3",
+  nestingLevel: 1,
+  // ... other phase task fields
+}
+```
+
+---
+
+## Algedonic Annotation Schema
+
+Algedonic signals annotate existing tasks rather than creating new ones. These fields are added to any task's metadata when an algedonic signal is emitted.
+
+### Active Halt Fields
+
+Added when a HALT signal is active (work stopped, awaiting user acknowledgment).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `algedonicHalt.timestamp` | string | ISO timestamp when signal was emitted |
+| `algedonicHalt.category` | string | `"SECURITY"` \| `"DATA"` \| `"ETHICS"` |
+| `algedonicHalt.issue` | string | One-line description of the issue |
+| `algedonicHalt.evidence` | string | What triggered the signal |
+| `algedonicHalt.impact` | string | Why this threatens viability |
+| `algedonicHalt.recommendedAction` | string | Suggested response |
+| `algedonicHalt.awaitingAcknowledgment` | boolean | `true` until user responds |
+
+### Active Alert Fields
+
+Added when an ALERT signal is active (work paused, awaiting user decision).
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `algedonicAlert.timestamp` | string | ISO timestamp when signal was emitted |
+| `algedonicAlert.category` | string | `"QUALITY"` \| `"SCOPE"` \| `"META-BLOCK"` |
+| `algedonicAlert.issue` | string | One-line description |
+| `algedonicAlert.evidence` | string | What triggered the signal |
+| `algedonicAlert.awaitingDecision` | boolean | `true` until user responds |
+
+### History Fields
+
+Tracks resolved algedonic signals for audit trail.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `algedonicHistory` | array | List of resolved signals |
+| `algedonicHistory[].type` | string | `"HALT"` \| `"ALERT"` |
+| `algedonicHistory[].category` | string | Signal category |
+| `algedonicHistory[].triggeredAt` | string | ISO timestamp |
+| `algedonicHistory[].resolvedAt` | string | ISO timestamp |
+| `algedonicHistory[].resolution` | string | How it was resolved |
+
+### Example
+
+```javascript
+{
+  taskType: "phase",
+  phase: "code",
+  // ... other fields ...
+
+  // Active HALT (work stopped)
+  algedonicHalt: {
+    timestamp: "2026-01-27T14:30:00Z",
+    category: "SECURITY",
+    issue: "AWS credentials hardcoded in source file",
+    evidence: "Found in src/config/aws.ts:15",
+    impact: "Credentials exposed if committed",
+    recommendedAction: "Remove credentials, use environment variables",
+    awaitingAcknowledgment: true
+  },
+
+  // Previous signals (resolved)
+  algedonicHistory: [
+    {
+      type: "ALERT",
+      category: "QUALITY",
+      triggeredAt: "2026-01-27T10:15:00Z",
+      resolvedAt: "2026-01-27T10:45:00Z",
+      resolution: "User chose to continue; added TODO for follow-up"
+    }
+  ]
+}
+```
+
+---
+
+## imPACT History Schema
+
+When `/PACT:imPACT` modifies existing tasks, it tracks the history in metadata.
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `imPACTHistory` | array | List of imPACT interventions |
+| `imPACTHistory[].timestamp` | string | When imPACT was invoked |
+| `imPACTHistory[].trigger` | string | What caused the blocker |
+| `imPACTHistory[].outcome` | string | `"redo-solo"` \| `"redo-with-help"` \| `"proceed-with-help"` |
+| `imPACTHistory[].action` | string | What was done to resolve |
+
+### Example
+
+```javascript
+{
+  taskType: "phase",
+  phase: "code",
+  // ... other fields ...
+
+  imPACTHistory: [
+    {
+      timestamp: "2026-01-27T11:00:00Z",
+      trigger: "Type errors after adding new dependency",
+      outcome: "redo-with-help",
+      action: "Re-ran ARCHITECT phase with pact-architect to resolve type conflicts"
+    }
+  ]
+}
+```
+
+---
+
+## Plan-Mode Task Schema
+
+Plan-mode uses phase tasks with plan-specific naming.
+
+### Phase Names
+
+| Phase | Task Name | Purpose |
+|-------|-----------|---------|
+| Analyze | `Plan: Analyze` | Assess scope, select specialists |
+| Consult | `Plan: Consult` | Gather specialist perspectives |
+| Synthesize | `Plan: Synthesize` | Resolve conflicts, sequence work |
+| Present | `Plan: Present` | Save plan, await approval |
+
+### Planner Subtask Naming
+
+During the Consult phase, planner subtasks use: `Plan: {Domain} perspective`
+
+Examples:
+- `Plan: Backend perspective`
+- `Plan: Architecture perspective`
+- `Plan: Database perspective`
+
+### Example
+
+```javascript
+// Phase task
+{
+  taskType: "phase",
+  pactWorkflow: "plan-mode",
+  phase: "consult",
+  subtaskIds: ["2", "3", "4"]
+}
+
+// Planner subtask
+{
+  taskType: "specialist",
+  phaseTaskId: "1",
+  domain: "backend",
+  specialist: "pact-backend-coder",
+  // Operates in "planning-only mode" - analysis, not implementation
+}
+```
+
+---
+
+## Quick Reference: Naming Conventions
+
+| Task Type | Format | Examples |
+|-----------|--------|----------|
+| Phase task | `PHASE` | `PREPARE`, `ARCHITECT`, `CODE`, `TEST` |
+| Specialist subtask | `Domain: Work` | `Backend: Implement auth`, `Frontend: Add login form` |
+| Workflow task | `Title Case` | `comPACT`, `Peer Review` |
+| Plan-mode phases | `Plan: Phase` | `Plan: Analyze`, `Plan: Consult` |
+| Plan-mode subtasks | `Plan: Domain perspective` | `Plan: Backend perspective` |
+| Nested (rePACT) | `rePACT: PHASE` | `rePACT: PREPARE`, `rePACT: CODE` |
+| Review subtasks | `Review: Focus` | `Review: Architecture`, `Review: Test coverage` |

From a4d1c684a535dbec6816622ef87d386fb827fafa Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 15:16:48 -0500
Subject: [PATCH 06/10] fix(review): resolve blocking issues from PR #113
 review
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update verify-protocol-extracts.sh line ranges after Task System Integration
- Regenerate extract files to match SSOT (pact-protocols.md)
- Align orchestrate.md handoff field names with agent definitions
  - 'Key context' → 'Decisions'
  - 'Areas of uncertainty' → 'Uncertainties'
  - 'Open questions' → 'Open Questions'

All 10 protocol extract verifications now pass.
---
 pact-plugin/commands/orchestrate.md           |  8 ++--
 pact-plugin/protocols/pact-documentation.md   |  1 -
 .../protocols/pact-phase-transitions.md       |  1 -
 pact-plugin/protocols/pact-s2-coordination.md |  1 -
 pact-plugin/protocols/pact-workflows.md       | 43 -------------------
 scripts/verify-protocol-extracts.sh           | 10 ++---
 6 files changed, 9 insertions(+), 55 deletions(-)

diff --git a/pact-plugin/commands/orchestrate.md b/pact-plugin/commands/orchestrate.md
index d93ff481..fc3e8cc3 100644
--- a/pact-plugin/commands/orchestrate.md
+++ b/pact-plugin/commands/orchestrate.md
@@ -218,12 +218,12 @@ Each specialist should end with a structured handoff:
 
 ```
 1. **Produced**: Files created/modified
-2. **Key context**: Decisions made, patterns used, assumptions
-3. **Areas of uncertainty**: Where bugs might hide, tricky parts, things to watch
-4. **Open questions**: Anything unresolved
+2. **Decisions**: Key choices made with rationale (patterns used, assumptions)
+3. **Uncertainties**: Where bugs might hide, tricky parts (helps TEST phase)
+4. **Open Questions**: Anything unresolved
 ```
 
-**Example**: `1. Produced: src/middleware/rateLimiter.ts. 2. Key context: Used token bucket with Redis. 3. Areas of uncertainty: Edge case with concurrent resets. 4. Open questions: None.`
+**Example**: `1. Produced: src/middleware/rateLimiter.ts. 2. Decisions: Used token bucket with Redis for distributed rate limiting. 3. Uncertainties: Edge case with concurrent resets. 4. Open Questions: None.`
 
 ---
 
diff --git a/pact-plugin/protocols/pact-documentation.md b/pact-plugin/protocols/pact-documentation.md
index 1bf9fad8..76060eb4 100644
--- a/pact-plugin/protocols/pact-documentation.md
+++ b/pact-plugin/protocols/pact-documentation.md
@@ -22,4 +22,3 @@ If work spans sessions, update CLAUDE.md with:
 - Next steps
 
 ---
-
diff --git a/pact-plugin/protocols/pact-phase-transitions.md b/pact-plugin/protocols/pact-phase-transitions.md
index 0caf1a1d..7126294e 100644
--- a/pact-plugin/protocols/pact-phase-transitions.md
+++ b/pact-plugin/protocols/pact-phase-transitions.md
@@ -86,4 +86,3 @@ For complex features, before Code phase:
 Skip for simple features or when "just build it."
 
 ---
-
diff --git a/pact-plugin/protocols/pact-s2-coordination.md b/pact-plugin/protocols/pact-s2-coordination.md
index f3ae9cc2..d969098b 100644
--- a/pact-plugin/protocols/pact-s2-coordination.md
+++ b/pact-plugin/protocols/pact-s2-coordination.md
@@ -152,4 +152,3 @@ This transforms implicit knowledge into explicit coordination, reducing "surpris
 **Collaboration**: If Backend needs a complex query, ask Database. If Database needs to know access patterns, ask Backend.
 
 ---
-
diff --git a/pact-plugin/protocols/pact-workflows.md b/pact-plugin/protocols/pact-workflows.md
index 6a2bb6ae..1ea10adb 100644
--- a/pact-plugin/protocols/pact-workflows.md
+++ b/pact-plugin/protocols/pact-workflows.md
@@ -8,32 +8,12 @@
 | **rePACT** | Complex sub-tasks within orchestration | Recursive nested P→A→C→T cycle (single or multi-domain) |
 | **imPACT** | When blocked or need to iterate | Triage: Redo prior phase? Additional agents needed? |
 
-**Task integration**: All workflows use Claude Code's native Task system. See SSOT "Task System Integration" for metadata schemas, naming conventions, and command summaries.
-
----
-
-## PACT (orchestrate) Protocol
-
-**Purpose**: Full multi-phase orchestration for complex/greenfield work.
-
-**Task structure**: 4 phase tasks (`PREPARE` → `ARCHITECT` → `CODE` → `TEST`) with sequential dependencies. Each phase task can have parallel specialist subtasks. Phase tasks use `blockedBy` to enforce sequencing; subtasks use `phaseTaskId` to link back.
-
-**Flow**:
-1. Create feature branch
-2. Execute phases sequentially (each with concurrent specialists where applicable)
-3. Auto-commit after CODE and TEST phases
-4. Run `/PACT:peer-review` when complete
-
-**Skipped phases**: Create task, immediately mark `completed` with `metadata: { skipped: true, skipReason: "..." }`
-
 ---
 
 ## plan-mode Protocol
 
 **Purpose**: Multi-agent planning consultation before implementation. Get specialist perspectives synthesized into an actionable plan.
 
-**Task structure**: 4 phase tasks (`Plan: Analyze` → `Plan: Consult` → `Plan: Synthesize` → `Plan: Present`) + planner subtasks during Consult phase. See SSOT Task Integration for metadata schemas.
-
 **When to use**:
 - Complex features where upfront alignment prevents rework
 - Tasks spanning multiple specialist domains
@@ -70,8 +50,6 @@
 
 **Trigger when**: Blocked; get similar errors repeatedly; or prior phase output is wrong.
 
-**Task structure**: Modifies existing tasks rather than creating new ones. Tracks `imPACTHistory` in task metadata with outcomes and phase changes. See SSOT Task Integration.
-
 **Two questions**:
 1. **Redo prior phase?** — Is the issue upstream in P→A→C→T?
 2. **Additional agents needed?** — Do I need subagents to assist?
@@ -91,8 +69,6 @@ If neither question is "Yes," you're not blocked—continue.
 
 **Core idea**: Single-DOMAIN delegation with light ceremony.
 
-**Task structure**: 1 workflow task (`taskType: "workflow"`) + parallel specialist subtasks. Subtasks linked via `subtaskIds`; workflow task uses `blockedBy` for dependency tracking. See SSOT Task Integration for metadata schemas.
-
 comPACT handles tasks within ONE specialist domain. For independent sub-tasks, it can invoke MULTIPLE specialists of the same type in parallel.
 
 **Available specialists**:
@@ -165,22 +141,3 @@ Invoke multiple specialists of the same type when:
 
 ---
 
-## rePACT Protocol
-
-**Purpose**: Recursive nested PACT cycle for complex sub-tasks discovered during orchestration.
-
-**Task structure**: Nested phase tasks with `rePACT:` prefix (e.g., `rePACT: PREPARE`, `rePACT: CODE`). Parent task uses `blockedBy` linking to nested `rePACT: TEST` task. Max nesting: 2 levels.
-
-**When to use**:
-- Complex sub-component discovered during CODE phase
-- Sub-task needs its own P→A→C→T cycle
-- Single or multi-domain nested work
-
-**Key rules**:
-- Declare nested cycle before starting
-- Parent task blocks until nested TEST completes
-- Nested tasks inherit `featureBranch` from parent
-- Results integrate back into parent workflow
-
----
-
diff --git a/scripts/verify-protocol-extracts.sh b/scripts/verify-protocol-extracts.sh
index 99153077..8a6d62f0 100755
--- a/scripts/verify-protocol-extracts.sh
+++ b/scripts/verify-protocol-extracts.sh
@@ -58,13 +58,13 @@ verify "pact-s4-checkpoints.md" "S4 Checkpoints (lines 154-224)" "154,224"
 verify "pact-s4-environment.md" "S4 Environment (lines 226-298)" "226,298"
 verify "pact-s4-tension.md" "S4 Tension (lines 300-363)" "300,363"
 verify "pact-s1-autonomy.md" "S1 Autonomy (lines 505-578)" "505,578"
-verify "pact-variety.md" "Variety (lines 623-684)" "623,684"
+verify "pact-variety.md" "Variety (lines 750-811)" "750,811"
 
 # Combined-range extracts
-verify "pact-s2-coordination.md" "S2 Coordination (lines 365-504 + 823-837)" "365,504" "823,837"
-verify "pact-workflows.md" "Workflows (lines 685-811)" "685,811"
-verify "pact-phase-transitions.md" "Phase Transitions (lines 812-822 + 838-915)" "812,822" "838,915"
-verify "pact-documentation.md" "Documentation (lines 916-940)" "916,940"
+verify "pact-s2-coordination.md" "S2 Coordination (lines 365-504 + 966-979)" "365,504" "966,979"
+verify "pact-workflows.md" "Workflows (lines 812-954)" "812,954"
+verify "pact-phase-transitions.md" "Phase Transitions (lines 955-965 + 981-1057)" "955,965" "981,1057"
+verify "pact-documentation.md" "Documentation (lines 1059-1082)" "1059,1082"
 
 echo ""
 echo "=== Summary ==="

From 9e5b13a2d03715c7fda2bf0d56b823b0b3d982fb Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 16:20:48 -0500
Subject: [PATCH 07/10] docs(review): address minor PR review recommendations

orchestrate.md:
- Update handoff example with realistic multi-file output
- Demonstrate priority-tagged uncertainties [HIGH]

task-metadata-schema.md:
- Add validation guidance (Req? columns, required notes)
- Add algedonicHistory[].resolution field description
- Standardize enum casing to uppercase (HALT, ALERT, SECURITY, etc.)
- Add blockedBy auto-resolution clarification
- Add troubleshooting section for blocked state recovery

task-integration-guide.md:
- Add edge cases for blocked status transitions
- Add parallel subtask coordination scenarios with examples
- Add CODE-to-TEST handoff example in practice
- Add circular dependency troubleshooting entry
---
 pact-plugin/commands/orchestrate.md           |   8 +-
 .../reference/task-integration-guide.md       | 190 ++++++++++++++++++
 pact-plugin/reference/task-metadata-schema.md | 122 +++++++----
 3 files changed, 283 insertions(+), 37 deletions(-)

diff --git a/pact-plugin/commands/orchestrate.md b/pact-plugin/commands/orchestrate.md
index fc3e8cc3..11f6f37c 100644
--- a/pact-plugin/commands/orchestrate.md
+++ b/pact-plugin/commands/orchestrate.md
@@ -223,7 +223,13 @@ Each specialist should end with a structured handoff:
 4. **Open Questions**: Anything unresolved
 ```
 
-**Example**: `1. Produced: src/middleware/rateLimiter.ts. 2. Decisions: Used token bucket with Redis for distributed rate limiting. 3. Uncertainties: Edge case with concurrent resets. 4. Open Questions: None.`
+**Example**:
+```
+1. **Produced**: src/auth/token-manager.ts, src/auth/middleware.ts
+2. **Decisions**: Used JWT with 15min expiry; refresh tokens stored in httpOnly cookies
+3. **Uncertainties**: [HIGH] Race condition possible during concurrent token refresh
+4. **Open Questions**: Should refresh tokens use rotation?
+```
 
 ---
 
diff --git a/pact-plugin/reference/task-integration-guide.md b/pact-plugin/reference/task-integration-guide.md
index 73f48f3c..e625bace 100644
--- a/pact-plugin/reference/task-integration-guide.md
+++ b/pact-plugin/reference/task-integration-guide.md
@@ -243,6 +243,75 @@ CODE handoff → TEST receives nextPhaseContext (especially uncertainties)
 - **MEDIUM**: "Not 100% confident" — TEST should cover
 - **LOW**: "Edge case I thought of" — TEST discretion
 
+### Handoff Example: CODE to TEST
+
+A realistic CODE phase handoff showing how context flows to TEST:
+
+```javascript
+// Backend coder completes auth middleware implementation
+codePhaseHandoff = {
+  produced: [
+    "/src/auth/middleware.ts",
+    "/src/auth/tokens.ts",
+    "/src/auth/types.ts"
+  ],
+  decisions: [
+    "Used jose library for JWT (faster than jsonwebtoken)",
+    "Token refresh uses sliding window (15min inactive = re-auth)",
+    "Rate limiting at 100 req/min per user, stored in Redis"
+  ],
+  uncertainties: [
+    {
+      priority: "HIGH",
+      description: "Race condition possible if two refresh requests arrive simultaneously",
+      location: "/src/auth/tokens.ts:45-60",
+      suggestedTest: "Concurrent refresh token requests with same token"
+    },
+    {
+      priority: "MEDIUM",
+      description: "Redis connection pool size (10) may be insufficient under load",
+      location: "/src/auth/middleware.ts:12",
+      suggestedTest: "Load test with 500+ concurrent users"
+    },
+    {
+      priority: "LOW",
+      description: "Clock skew between servers could affect token expiry",
+      suggestedTest: "Token validation with various iat/exp edge cases"
+    }
+  ],
+  openQuestions: [
+    "Should failed auth attempts be logged to separate audit log?"
+  ]
+};
+```
+
+**How TEST phase uses this handoff**:
+
+```javascript
+// Test engineer receives handoff and prioritizes
+testPlan = {
+  mustCover: [
+    // From HIGH uncertainty
+    "test_concurrent_token_refresh_race_condition",
+  ],
+  shouldCover: [
+    // From MEDIUM uncertainty
+    "test_redis_pool_exhaustion_under_load",
+    // Standard coverage for produced files
+    "test_middleware_rejects_expired_token",
+    "test_middleware_rejects_malformed_token"
+  ],
+  mayDefer: [
+    // From LOW uncertainty
+    "test_clock_skew_tolerance"
+  ],
+  flagForOrchestrator: [
+    // From openQuestions - needs decision, not testing
+    "Audit logging decision needed before security tests"
+  ]
+};
+```
+
 ---
 
 ## Best Practices
@@ -338,6 +407,64 @@ Task system supports S2 coordination:
 2. **Subtask independence**: Parallel subtasks have no `blockedBy` between them
 3. **Convention propagation**: First subtask's decisions noted in metadata for others
 
+#### File Conflict Detection
+
+Before dispatching parallel subtasks, orchestrator checks for shared files:
+
+```javascript
+// Pre-dispatch analysis
+const subtasks = [
+  { domain: "backend", files: ["src/auth/middleware.ts", "src/auth/tokens.ts"] },
+  { domain: "backend", files: ["src/api/users.ts"] },
+  { domain: "backend", files: ["src/auth/middleware.ts", "src/api/health.ts"] }
+];
+
+// Detect conflicts: subtasks 1 and 3 both touch middleware.ts
+const conflicts = detectFileOverlap(subtasks);
+// Result: [{ files: ["src/auth/middleware.ts"], between: [1, 3] }]
+```
+
+**When conflicts detected**:
+- **Option A**: Sequence conflicting subtasks (subtask 3 `blockedBy` subtask 1)
+- **Option B**: Assign clear boundaries ("subtask 1 owns auth exports, subtask 3 owns auth imports only")
+- **Option C**: Merge into single subtask if conflict is substantial
+
+#### Boundary Assignment Example
+
+```javascript
+// Conflict: Two subtasks need to modify user service
+// Resolution: Assign clear boundaries
+
+subtask1.metadata = {
+  assignedBoundary: "UserService.create(), UserService.update()",
+  conventionAuthority: true  // First agent sets patterns
+};
+
+subtask2.metadata = {
+  assignedBoundary: "UserService.delete(), UserService.archive()",
+  followConventions: "subtask1"  // Adopt subtask1's patterns
+};
+```
+
+#### Convention Propagation
+
+First subtask to complete sets conventions for the batch:
+
+```javascript
+// Subtask 1 completes first
+subtask1.handoff = {
+  conventions: {
+    errorFormat: "{ code: string, message: string, details?: object }",
+    loggingPattern: "logger.info({ action, userId, metadata })",
+    validationLib: "zod"
+  }
+};
+
+// Orchestrator propagates to in-progress subtasks
+subtask2.metadata.inheritedConventions = subtask1.handoff.conventions;
+subtask3.metadata.inheritedConventions = subtask1.handoff.conventions;
+```
+
 ---
 
 ## Troubleshooting
@@ -351,6 +478,29 @@ Task system supports S2 coordination:
 - Circular dependency (shouldn't happen with PACT structure)
 - Subtask failed and wasn't handled
 
+#### Edge Case: Subtask Completes But Phase Remains Blocked
+
+**Scenario**: Specialist returns handoff, but orchestrator doesn't update task status (e.g., agent thread ended, context compaction, orchestrator distraction).
+
+**Detection**:
+```javascript
+// Signs of stale blocked state
+const staleIndicators = {
+  blockedByAllComplete: blockedBy.every(t => t.status === "completed"),
+  lastUpdate: "> 5 minutes ago",
+  noActiveAgentThreads: true,
+  phaseStillBlocked: status === "blocked"
+};
+```
+
+**Recovery**:
+1. Verify subtask handoffs are captured in task metadata
+2. If handoffs present: Mark phase `in_progress`, process handoffs, mark `completed`
+3. If handoffs missing: Check agent thread output, reconstruct handoff, or re-run subtask
+4. Update task status to unblock downstream phases
+
+**Prevention**: Orchestrator should process subtask completion within same turn as receiving handoff. Avoid context-switching between subtask completion and status update.
+
 ### Missing Handoff Data
 
 **Check**: Did specialist return structured handoff?
@@ -367,6 +517,46 @@ Task system supports S2 coordination:
 
 **Protocol**: Algedonic signals must surface immediately. If task shows signal but user wasn't notified, this is a bug in orchestrator behavior.
 
+### Circular Dependency Detection
+
+**Context**: PACT's phase structure (PREPARE → ARCHITECT → CODE → TEST) inherently prevents circular dependencies. However, `comPACT` and `rePACT` workflows with manual `blockedBy` assignments could theoretically create cycles.
+
+**Detection**:
+```javascript
+// Check for circular blockedBy before adding dependency
+function wouldCreateCycle(taskId, newBlockerId, allTasks) {
+  const visited = new Set();
+  const stack = [newBlockerId];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (current === taskId) return true; // Cycle detected
+    if (visited.has(current)) continue;
+    visited.add(current);
+
+    const task = allTasks.get(current);
+    if (task?.blockedBy) {
+      stack.push(...task.blockedBy);
+    }
+  }
+  return false;
+}
+```
+
+**How cycles could theoretically occur**:
+- `rePACT` nested cycle creates subtask that blocks its own parent phase
+- `comPACT` with manual dependency adds A → B → C → A chain
+- Orchestrator error setting `blockedBy` to wrong task ID
+
+**Resolution if detected**:
+1. Identify the cycle path (A → B → C → A)
+2. Determine which dependency is erroneous (usually the most recently added)
+3. Remove the incorrect `blockedBy` relationship
+4. Document the error in task metadata for debugging
+5. If unclear which is erroneous, escalate to user
+
+**Prevention**: Standard PACT workflows don't allow arbitrary `blockedBy` assignment. Only orchestrator sets dependencies, following phase sequencing rules. If implementing custom blocking logic, always run cycle detection before adding relationships.
+
 ---
 
 ## Migration Notes
diff --git a/pact-plugin/reference/task-metadata-schema.md b/pact-plugin/reference/task-metadata-schema.md
index 0fe5f4df..99ebe598 100644
--- a/pact-plugin/reference/task-metadata-schema.md
+++ b/pact-plugin/reference/task-metadata-schema.md
@@ -37,6 +37,8 @@ Phase tasks represent the four PACT phases (Prepare, Architect, Code, Test) or p
 
 ### Variety Object
 
+All fields are required when `variety` is present.
+
 | Field | Type | Range | Description |
 |-------|------|-------|-------------|
 | `novelty` | number | 1-4 | How new is this work? |
@@ -47,16 +49,18 @@ Phase tasks represent the four PACT phases (Prepare, Architect, Code, Test) or p
 
 ### Phase Handoff Object
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `summary` | string | Brief description of what was accomplished |
-| `produced` | string[] | Files or artifacts created/modified |
-| `keyDecisions` | string[] | Important decisions made during the phase |
-| `unresolvedItems` | array | Items needing attention (see below) |
-| `nextPhaseContext` | string | Context the next phase needs to know |
+| Field | Type | Req? | Description |
+|-------|------|------|-------------|
+| `summary` | string | Yes | Brief description of what was accomplished |
+| `produced` | string[] | Yes | Files or artifacts created/modified |
+| `keyDecisions` | string[] | No | Important decisions made during the phase |
+| `unresolvedItems` | array | No | Items needing attention (see below) |
+| `nextPhaseContext` | string | No | Context the next phase needs to know |
 
 ### Unresolved Item Object
 
+All fields required.
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `priority` | string | `"HIGH"` \| `"MEDIUM"` \| `"LOW"` |
@@ -116,15 +120,17 @@ Specialist subtasks represent work delegated to individual specialist agents (co
 
 ### Specialist Handoff Object
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `produced` | string[] | Files created or modified |
-| `decisions` | string[] | Key implementation decisions with rationale |
-| `uncertainties` | array | Areas of uncertainty (see below) |
-| `openQuestions` | string[] | Unresolved questions for orchestrator |
+| Field | Type | Req? | Description |
+|-------|------|------|-------------|
+| `produced` | string[] | Yes | Files created or modified |
+| `decisions` | string[] | No | Key implementation decisions with rationale |
+| `uncertainties` | array | No | Areas of uncertainty (see below) |
+| `openQuestions` | string[] | No | Unresolved questions for orchestrator |
 
 ### Uncertainty Object
 
+All fields required.
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `priority` | string | `"HIGH"` \| `"MEDIUM"` \| `"LOW"` |
@@ -181,21 +187,21 @@ Same structure as Specialist Handoff.
 
 ### Workflow Handoff Object (Peer Review)
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `verdict` | string | `"APPROVED"` \| `"CHANGES_REQUESTED"` \| `"NEEDS_DISCUSSION"` |
-| `findings` | array | Review findings (see below) |
-| `summary` | string | Overall review summary |
+| Field | Type | Req? | Description |
+|-------|------|------|-------------|
+| `verdict` | string | Yes | `"APPROVED"` \| `"CHANGES_REQUESTED"` \| `"NEEDS_DISCUSSION"` |
+| `findings` | array | Yes | Review findings (see below) |
+| `summary` | string | Yes | Overall review summary |
 
 ### Finding Object
 
-| Field | Type | Description |
-|-------|------|-------------|
-| `reviewer` | string | Which reviewer found this |
-| `severity` | string | `"CRITICAL"` \| `"MAJOR"` \| `"MINOR"` \| `"SUGGESTION"` |
-| `category` | string | `"security"` \| `"performance"` \| `"design"` \| `"testing"` \| `"style"` |
-| `description` | string | What was found |
-| `location` | string | File and line (if applicable) |
+| Field | Type | Req? | Description |
+|-------|------|------|-------------|
+| `reviewer` | string | Yes | Which reviewer found this |
+| `severity` | string | Yes | `"CRITICAL"` \| `"MAJOR"` \| `"MINOR"` \| `"SUGGESTION"` |
+| `category` | string | Yes | `"SECURITY"` \| `"PERFORMANCE"` \| `"DESIGN"` \| `"TESTING"` \| `"STYLE"` |
+| `description` | string | Yes | What was found |
+| `location` | string | No | File and line (if applicable) |
 
 ### Example (comPACT)
 
@@ -228,14 +234,14 @@ Same structure as Specialist Handoff.
       {
         reviewer: "pact-architect",
         severity: "MAJOR",
-        category: "security",
+        category: "SECURITY",
         description: "JWT secret loaded from env but not validated at startup",
         location: "src/auth/config.ts:15"
       },
       {
         reviewer: "pact-test-engineer",
         severity: "MINOR",
-        category: "testing",
+        category: "TESTING",
         description: "Missing test for token expiry edge case",
         location: "src/auth/token-manager.test.ts"
       }
@@ -282,7 +288,7 @@ Algedonic signals annotate existing tasks rather than creating new ones. These f
 
 ### Active Halt Fields
 
-Added when a HALT signal is active (work stopped, awaiting user acknowledgment).
+Added when a HALT signal is active (work stopped, awaiting user acknowledgment). All fields required when `algedonicHalt` is present.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -296,7 +302,7 @@ Added when a HALT signal is active (work stopped, awaiting user acknowledgment).
 
 ### Active Alert Fields
 
-Added when an ALERT signal is active (work paused, awaiting user decision).
+Added when an ALERT signal is active (work paused, awaiting user decision). All fields required when `algedonicAlert` is present.
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -308,16 +314,16 @@ Added when an ALERT signal is active (work paused, awaiting user decision).
 
 ### History Fields
 
-Tracks resolved algedonic signals for audit trail.
+Tracks resolved algedonic signals for audit trail. All fields required for each history entry.
 
 | Field | Type | Description |
 |-------|------|-------------|
 | `algedonicHistory` | array | List of resolved signals |
 | `algedonicHistory[].type` | string | `"HALT"` \| `"ALERT"` |
-| `algedonicHistory[].category` | string | Signal category |
-| `algedonicHistory[].triggeredAt` | string | ISO timestamp |
-| `algedonicHistory[].resolvedAt` | string | ISO timestamp |
-| `algedonicHistory[].resolution` | string | How it was resolved |
+| `algedonicHistory[].category` | string | Signal category (matches active signal categories) |
+| `algedonicHistory[].triggeredAt` | string | ISO timestamp when signal was emitted |
+| `algedonicHistory[].resolvedAt` | string | ISO timestamp when user responded |
+| `algedonicHistory[].resolution` | string | How it was resolved (e.g., "Fixed and verified", "User override with justification") |
 
 ### Example
 
@@ -359,12 +365,14 @@ When `/PACT:imPACT` modifies existing tasks, it tracks the history in metadata.
 
 ### Fields
 
+All fields required for each history entry.
+
 | Field | Type | Description |
 |-------|------|-------------|
 | `imPACTHistory` | array | List of imPACT interventions |
 | `imPACTHistory[].timestamp` | string | When imPACT was invoked |
 | `imPACTHistory[].trigger` | string | What caused the blocker |
-| `imPACTHistory[].outcome` | string | `"redo-solo"` \| `"redo-with-help"` \| `"proceed-with-help"` |
+| `imPACTHistory[].outcome` | string | `"REDO-SOLO"` \| `"REDO-WITH-HELP"` \| `"PROCEED-WITH-HELP"` |
 | `imPACTHistory[].action` | string | What was done to resolve |
 
 ### Example
@@ -379,7 +387,7 @@ When `/PACT:imPACT` modifies existing tasks, it tracks the history in metadata.
     {
       timestamp: "2026-01-27T11:00:00Z",
       trigger: "Type errors after adding new dependency",
-      outcome: "redo-with-help",
+      outcome: "REDO-WITH-HELP",
       action: "Re-ran ARCHITECT phase with pact-architect to resolve type conflicts"
     }
   ]
@@ -444,3 +452,45 @@ Examples:
 | Plan-mode subtasks | `Plan: Domain perspective` | `Plan: Backend perspective` |
 | Nested (rePACT) | `rePACT: PHASE` | `rePACT: PREPARE`, `rePACT: CODE` |
 | Review subtasks | `Review: Focus` | `Review: Architecture`, `Review: Test coverage` |
+
+---
+
+## Best Practices
+
+### Task Metadata Management
+
+- **Keep metadata current**: Update task status as work progresses, don't batch updates at the end
+- **Use structured handoffs**: Always populate the handoff object when completing a task
+- **Track dependencies explicitly**: Use `blockedBy` to document task relationships
+
+### blockedBy Relationships
+
+The `blockedBy` field allows expressing task dependencies, but note:
+
+- **No auto-resolution**: Claude Code does not automatically resolve `blockedBy` relationships when blocking tasks complete
+- **Manual status management**: The orchestrator must check completion of blocking tasks and manually update dependent task status
+- **Clear blocking chain**: When unblocking a task, verify the full dependency chain is resolved
+
+---
+
+## Troubleshooting
+
+### Task Stuck in Blocked State
+
+**Symptom**: A task shows as blocked even though its blocking dependencies have completed.
+
+**Cause**: `blockedBy` relationships don't auto-resolve in Claude Code. The blocking task completing does not automatically update the blocked task's status.
+
+**Resolution**:
+1. Verify the blocking task(s) are actually complete
+2. Manually update the blocked task's status to reflect it's no longer blocked
+3. Consider removing or clearing the `blockedBy` field once dependencies are satisfied
+
+### Missing Handoff Data
+
+**Symptom**: Phase or specialist task completed but handoff object is empty or missing key fields.
+
+**Resolution**:
+1. Check that the agent was instructed to produce a structured handoff
+2. Review agent output for handoff content that may not have been captured
+3. Manually populate critical handoff fields (produced files, key decisions) if needed

From a074cbd44285b1482104a06709e3cf171e10d7af Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 22:55:41 -0500
Subject: [PATCH 08/10] refactor(agents): remove task system integration noise
 from handoff sections

Agents don't need to know WHY the handoff format exists - they just
need to follow it. The task system is managed by the orchestrator,
not specialist agents.
---
 pact-plugin/agents/pact-architect.md         | 2 +-
 pact-plugin/agents/pact-backend-coder.md     | 2 +-
 pact-plugin/agents/pact-database-engineer.md | 2 +-
 pact-plugin/agents/pact-frontend-coder.md    | 2 +-
 pact-plugin/agents/pact-preparer.md          | 2 +-
 pact-plugin/agents/pact-test-engineer.md     | 2 +-
 6 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/pact-plugin/agents/pact-architect.md b/pact-plugin/agents/pact-architect.md
index e467481a..e4739a05 100644
--- a/pact-plugin/agents/pact-architect.md
+++ b/pact-plugin/agents/pact-architect.md
@@ -129,7 +129,7 @@ Your work is complete when you deliver architectural specifications in a markdow
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator (enables task system integration):
+End with a structured handoff for the orchestrator:
 1. **Produced**: Architecture documents created/modified
 2. **Decisions**: Key architectural choices with rationale (patterns, trade-offs, technology selections)
 3. **Uncertainties**: Areas where design assumptions may not hold, integration risks
diff --git a/pact-plugin/agents/pact-backend-coder.md b/pact-plugin/agents/pact-backend-coder.md
index 70866722..a10502bf 100644
--- a/pact-plugin/agents/pact-backend-coder.md
+++ b/pact-plugin/agents/pact-backend-coder.md
@@ -106,7 +106,7 @@ Your work isn't done until smoke tests pass. Smoke tests verify: "Does it compil
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator (enables task system integration):
+End with a structured handoff for the orchestrator:
 1. **Produced**: Files created/modified
 2. **Decisions**: Key choices made with rationale (patterns used, assumptions)
 3. **Uncertainties**: Where bugs might hide, tricky parts (helps TEST phase)
diff --git a/pact-plugin/agents/pact-database-engineer.md b/pact-plugin/agents/pact-database-engineer.md
index 5a135957..7778cc4f 100644
--- a/pact-plugin/agents/pact-database-engineer.md
+++ b/pact-plugin/agents/pact-database-engineer.md
@@ -124,7 +124,7 @@ Your work isn't done until smoke tests pass. Smoke tests verify: "Does the schem
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator (enables task system integration):
+End with a structured handoff for the orchestrator:
 1. **Produced**: Files created/modified (schemas, migrations, queries)
 2. **Decisions**: Key choices made with rationale (normalization, indexes, patterns used, assumptions)
 3. **Uncertainties**: Where performance issues might hide, tricky queries (helps TEST phase)
diff --git a/pact-plugin/agents/pact-frontend-coder.md b/pact-plugin/agents/pact-frontend-coder.md
index 6fb88d9f..485d13b0 100644
--- a/pact-plugin/agents/pact-frontend-coder.md
+++ b/pact-plugin/agents/pact-frontend-coder.md
@@ -97,7 +97,7 @@ Your work isn't done until smoke tests pass. Smoke tests verify: "Does it compil
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator (enables task system integration):
+End with a structured handoff for the orchestrator:
 1. **Produced**: Files created/modified
 2. **Decisions**: Key choices made with rationale (patterns used, assumptions)
 3. **Uncertainties**: Where bugs might hide, tricky parts (helps TEST phase)
diff --git a/pact-plugin/agents/pact-preparer.md b/pact-plugin/agents/pact-preparer.md
index 04de7168..406199db 100644
--- a/pact-plugin/agents/pact-preparer.md
+++ b/pact-plugin/agents/pact-preparer.md
@@ -131,7 +131,7 @@ MANDATORY: Pass back to the Orchestrator upon completion of your markdown files.
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator (enables task system integration):
+End with a structured handoff for the orchestrator:
 1. **Produced**: Research documents created/modified
 2. **Decisions**: Key recommendations with rationale (technology choices, approach selections)
 3. **Uncertainties**: Conflicting information found, areas needing validation
diff --git a/pact-plugin/agents/pact-test-engineer.md b/pact-plugin/agents/pact-test-engineer.md
index 53ffe528..0064cca9 100644
--- a/pact-plugin/agents/pact-test-engineer.md
+++ b/pact-plugin/agents/pact-test-engineer.md
@@ -227,7 +227,7 @@ The orchestrator passes CODE phase handoff summaries. Use these for context:
 
 **HANDOFF**
 
-End with a structured handoff for the orchestrator (enables task system integration):
+End with a structured handoff for the orchestrator:
 1. **Produced**: Test files created, coverage achieved
 2. **Decisions**: Testing approach chosen, areas prioritized with rationale
 3. **Uncertainties**: Edge cases not covered, flaky tests, known issues

From 84be8a1354028b4fc1252e29ee9052dadeeacf01 Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 23:07:58 -0500
Subject: [PATCH 09/10] fix(comPACT): make Task Management section
 self-contained

Replace dangling reference to agent definitions with inline
specialist subtask metadata example.
---
 pact-plugin/commands/comPACT.md | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/pact-plugin/commands/comPACT.md b/pact-plugin/commands/comPACT.md
index 0541b068..9685987c 100644
--- a/pact-plugin/commands/comPACT.md
+++ b/pact-plugin/commands/comPACT.md
@@ -134,7 +134,15 @@ Create tasks to track workflow progress:
 }
 ```
 
-**Specialist subtask metadata**: See specialist handoff format in agent definitions.
+**Specialist subtask metadata**:
+```javascript
+{
+  taskType: "specialist",
+  workflowTaskId: "<workflow-id>",
+  domain: "backend",
+  specialist: "pact-backend-coder"
+}
+```
 
 ---
 

From 03871f8e3728ec2e693fdcb6f3549544026aa9d2 Mon Sep 17 00:00:00 2001
From: michael-wojcik <5386199+michael-wojcik@users.noreply.github.com>
Date: Tue, 27 Jan 2026 23:18:54 -0500
Subject: [PATCH 10/10] fix(commands): use correct Task tool names and complete
 examples

- Replace TodoWrite with TaskCreate/TaskUpdate across all commands
- Add full task examples with subject, description, activeForm, metadata
- Fix activeForm to use strings (not objects) in plan-mode and rePACT
- Show complete task lifecycle: create, link (addBlockedBy), complete

Files updated: orchestrate.md, comPACT.md, peer-review.md,
plan-mode.md, rePACT.md, imPACT.md
---
 pact-plugin/commands/comPACT.md     |  65 +++++++++----
 pact-plugin/commands/imPACT.md      |  83 ++++++++++++----
 pact-plugin/commands/orchestrate.md | 105 ++++++++++++++-------
 pact-plugin/commands/peer-review.md |  98 ++++++++++++-------
 pact-plugin/commands/plan-mode.md   | 141 +++++++++++++++++++++++-----
 pact-plugin/commands/rePACT.md      | 115 ++++++++++++++++++++---
 6 files changed, 471 insertions(+), 136 deletions(-)

diff --git a/pact-plugin/commands/comPACT.md b/pact-plugin/commands/comPACT.md
index 9685987c..34285c48 100644
--- a/pact-plugin/commands/comPACT.md
+++ b/pact-plugin/commands/comPACT.md
@@ -119,29 +119,62 @@ Before invoking multiple specialists concurrently, perform this coordination che
 
 Create tasks to track workflow progress:
 
-1. **At start**: Create workflow task `comPACT`
+1. **At start**: Create workflow task
 2. **Before dispatch**: Create specialist subtasks for each work item
 3. **Link**: Workflow `blockedBy` all subtasks (enables parallel execution)
-4. **On completion**: Mark workflow task completed when all subtasks done
+4. **On completion**: Mark workflow task completed with handoff
 
-**Workflow task metadata**:
+**Create workflow task**:
 ```javascript
-{
-  taskType: "workflow",
-  pactWorkflow: "comPACT",
-  domain: "backend",  // or frontend, database, etc.
-  subtaskIds: ["4", "5"]
-}
+TaskCreate({
+  subject: "comPACT",
+  description: "Single-domain delegation for backend bug fixes",
+  activeForm: "Running comPACT",
+  metadata: { taskType: "workflow", pactWorkflow: "comPACT", domain: "backend" }
+})
+// Returns task ID, e.g., "1"
 ```
 
-**Specialist subtask metadata**:
+**Create specialist subtasks** (one per work item):
 ```javascript
-{
-  taskType: "specialist",
-  workflowTaskId: "<workflow-id>",
-  domain: "backend",
-  specialist: "pact-backend-coder"
-}
+TaskCreate({
+  subject: "Backend: Fix auth token validation",
+  description: "Fix authentication token expiry check",
+  activeForm: "Fixing auth bug",
+  metadata: { taskType: "specialist", workflowTaskId: "1", domain: "backend", specialist: "pact-backend-coder" }
+})
+// Returns task ID, e.g., "2"
+
+TaskCreate({
+  subject: "Backend: Fix rate limiter bypass",
+  description: "Fix rate limiting not applying to API routes",
+  activeForm: "Fixing rate limiter",
+  metadata: { taskType: "specialist", workflowTaskId: "1", domain: "backend", specialist: "pact-backend-coder" }
+})
+// Returns task ID, e.g., "3"
+```
+
+**Link workflow to subtasks**:
+```javascript
+TaskUpdate({
+  taskId: "1",
+  addBlockedBy: ["2", "3"]
+})
+```
+
+**On completion** (after all subtasks done):
+```javascript
+TaskUpdate({
+  taskId: "1",
+  status: "completed",
+  metadata: {
+    handoff: {
+      produced: ["src/auth/token.ts", "src/middleware/rateLimiter.ts"],
+      testsPass: true,
+      commitSha: "abc123"
+    }
+  }
+})
 ```
 
 ---
diff --git a/pact-plugin/commands/imPACT.md b/pact-plugin/commands/imPACT.md
index 26a5afe0..c20562aa 100644
--- a/pact-plugin/commands/imPACT.md
+++ b/pact-plugin/commands/imPACT.md
@@ -118,26 +118,73 @@ imPACT is triage, not a new workflow. It modifies existing tasks rather than cre
 
 ### imPACTHistory Tracking
 
-Every imPACT invocation is recorded in the affected task's metadata:
+Every imPACT invocation is recorded in the affected task's metadata using TaskUpdate:
 
 ```javascript
-metadata: {
-  // ... existing task metadata ...
-  imPACTHistory: [
-    {
-      triggeredAt: "2026-01-27T14:30:00Z",
-      outcome: "redo_phase",
-      reason: "Interface mismatch — ARCHITECT phase output incomplete",
-      redoPhase: "architect"
-    },
-    {
-      triggeredAt: "2026-01-27T15:45:00Z",
-      outcome: "augment",
-      reason: "Need parallel backend support for auth flow",
-      subtasksCreated: ["12", "13"]
-    }
-  ]
-}
+// Example: Redo prior phase outcome
+TaskUpdate({
+  taskId: "3",  // Current CODE phase task
+  metadata: {
+    // Preserve existing metadata fields
+    taskType: "phase",
+    pactWorkflow: "orchestrate",
+    phase: "code",
+    // Append to imPACTHistory
+    imPACTHistory: [
+      // ... any existing entries ...
+      {
+        triggeredAt: "2026-01-27T14:30:00Z",
+        outcome: "redo_phase",
+        reason: "Interface mismatch — ARCHITECT phase output incomplete",
+        redoPhase: "architect"
+      }
+    ]
+  }
+})
+
+// Example: Augment with parallel agents
+TaskUpdate({
+  taskId: "3",  // Current CODE phase task
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "orchestrate",
+    phase: "code",
+    imPACTHistory: [
+      // ... previous entries ...
+      {
+        triggeredAt: "2026-01-27T14:30:00Z",
+        outcome: "redo_phase",
+        reason: "Interface mismatch — ARCHITECT phase output incomplete",
+        redoPhase: "architect"
+      },
+      {
+        triggeredAt: "2026-01-27T15:45:00Z",
+        outcome: "augment",
+        reason: "Need parallel backend support for auth flow",
+        subtasksCreated: ["12", "13"]
+      }
+    ]
+  }
+})
+
+// Example: Escalate to user after 3+ cycles
+TaskUpdate({
+  taskId: "3",
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "orchestrate",
+    phase: "code",
+    imPACTHistory: [
+      { triggeredAt: "...", outcome: "redo_phase", reason: "..." },
+      { triggeredAt: "...", outcome: "augment", reason: "..." },
+      {
+        triggeredAt: "2026-01-27T16:30:00Z",
+        outcome: "escalated",
+        reason: "3rd imPACT cycle — systemic issue, escalating to user"
+      }
+    ]
+  }
+})
 ```
 
 ### imPACTHistory Entry Schema
diff --git a/pact-plugin/commands/orchestrate.md b/pact-plugin/commands/orchestrate.md
index 11f6f37c..c299fffa 100644
--- a/pact-plugin/commands/orchestrate.md
+++ b/pact-plugin/commands/orchestrate.md
@@ -66,19 +66,39 @@ See [algedonic.md](../protocols/algedonic.md) for signal format and full protoco
 
 ## Task Management
 
-At workflow start, create phase tasks to track progress. Use `TodoWrite` to manage tasks throughout.
+At workflow start, create phase tasks to track progress. Use `TaskCreate` and `TaskUpdate` to manage tasks throughout.
 
 ### Initial Setup (Before Any Phase)
 
-Create 4 phase tasks with sequential dependencies:
-
-```
-TodoWrite([
-  { id: "1", title: "PREPARE", status: "pending", metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "prepare" } },
-  { id: "2", title: "ARCHITECT", status: "pending", blockedBy: ["1"], metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "architect" } },
-  { id: "3", title: "CODE", status: "pending", blockedBy: ["2"], metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "code" } },
-  { id: "4", title: "TEST", status: "pending", blockedBy: ["3"], metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "test" } }
-])
+Create 4 phase tasks, then add sequential dependencies:
+
+```javascript
+// Create the phase tasks
+TaskCreate({
+  subject: "PREPARE",
+  description: "Research and gather requirements",
+  metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "prepare" }
+})
+TaskCreate({
+  subject: "ARCHITECT",
+  description: "Design components and interfaces",
+  metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "architect" }
+})
+TaskCreate({
+  subject: "CODE",
+  description: "Implement the solution",
+  metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "code" }
+})
+TaskCreate({
+  subject: "TEST",
+  description: "Verify implementation quality",
+  metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "test" }
+})
+
+// Add sequential dependencies (assuming task IDs 1-4)
+TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })
+TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })
+TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })
 ```
 
 Add to metadata after variety assessment: `variety: { novelty, scope, uncertainty, risk, total }`, `featureBranch`, `planRef` (if plan exists).
@@ -86,16 +106,39 @@ Add to metadata after variety assessment: `variety: { novelty, scope, uncertaint
 ### Per-Phase Task Flow
 
 For each phase:
-1. Mark phase `in_progress`
-2. Create specialist subtasks (phase `blockedBy` subtasks)
+1. Mark phase `in_progress` with `activeForm`
+2. Create specialist subtasks, block phase on subtasks
 3. When subtasks complete, update phase `metadata.handoff` and mark `completed`
 
+```javascript
+// 1. Start phase
+TaskUpdate({ taskId: "1", status: "in_progress", activeForm: "Preparing" })
+
+// 2. Create subtask, block phase on it
+TaskCreate({
+  subject: "Research: API options",
+  description: "Investigate auth provider APIs",
+  activeForm: "Researching",
+  metadata: { taskType: "specialist", phaseTaskId: "1", specialist: "pact-preparer" }
+})
+TaskUpdate({ taskId: "1", addBlockedBy: ["5"] })  // subtask ID
+
+// 3. Complete subtask and phase
+TaskUpdate({ taskId: "5", status: "completed", metadata: { handoff: { produced: [...] } } })
+TaskUpdate({ taskId: "1", status: "completed", metadata: { handoff: { produced: [...] } } })
+```
+
 ### Skipped Phases
 
-When skipping a phase, still create the task but mark immediately completed:
+When skipping a phase, create as completed with skip metadata:
 
-```
-TodoWrite([{ id: "1", title: "PREPARE", status: "completed", metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "prepare", skipped: true, skipReason: "Approved plan exists" } }])
+```javascript
+TaskCreate({
+  subject: "PREPARE",
+  description: "Research and gather requirements",
+  metadata: { taskType: "phase", pactWorkflow: "orchestrate", phase: "prepare", skipped: true, skipReason: "Approved plan exists" }
+})
+TaskUpdate({ taskId: "1", status: "completed" })
 ```
 
 ---
@@ -238,9 +281,9 @@ Each specialist should end with a structured handoff:
 **Skip criteria met?** → Mark PREPARE task completed with `skipped: true, skipReason: "..."` → Proceed to Phase 2.
 
 **Task management**:
-1. Mark PREPARE `in_progress`
-2. Create subtask(s): `TodoWrite([{ id: "1-1", title: "Research: {topic}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "1", domain: "prepare", specialist: "pact-preparer" } }])`
-3. Update PREPARE: `blockedBy: ["1-1"]` (and other subtask IDs)
+1. `TaskUpdate({ taskId: "1", status: "in_progress", activeForm: "Preparing" })`
+2. Create subtask: `TaskCreate({ subject: "Research: {topic}", description: "...", activeForm: "Researching", metadata: { taskType: "specialist", phaseTaskId: "1", specialist: "pact-preparer" } })`
+3. Block phase on subtask: `TaskUpdate({ taskId: "1", addBlockedBy: ["{subtaskId}"] })`
 
 **Plan sections to pass** (if plan exists):
 - "Preparation Phase"
@@ -282,9 +325,9 @@ If PREPARE ran and ARCHITECT was marked "Skip," compare PREPARE's recommended ap
 **Skip criteria met (after re-assessment)?** → Mark ARCHITECT task completed with `skipped: true, skipReason: "..."` → Proceed to Phase 3.
 
 **Task management**:
-1. Mark ARCHITECT `in_progress`
-2. Create subtask(s): `TodoWrite([{ id: "2-1", title: "Design: {component}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "2", domain: "architect", specialist: "pact-architect" } }])`
-3. Update ARCHITECT: `blockedBy: ["2-1"]` (and other subtask IDs)
+1. `TaskUpdate({ taskId: "2", status: "in_progress", activeForm: "Architecting" })`
+2. Create subtask: `TaskCreate({ subject: "Design: {component}", description: "...", activeForm: "Designing", metadata: { taskType: "specialist", phaseTaskId: "2", specialist: "pact-architect" } })`
+3. Block phase on subtask: `TaskUpdate({ taskId: "2", addBlockedBy: ["{subtaskId}"] })`
 
 **Plan sections to pass** (if plan exists):
 - "Architecture Phase"
@@ -314,15 +357,13 @@ If PREPARE ran and ARCHITECT was marked "Skip," compare PREPARE's recommended ap
 **Always runs.** This is the core work.
 
 **Task management**:
-1. Mark CODE `in_progress`
-2. Create subtask(s) for each specialist:
-   ```
-   TodoWrite([
-     { id: "3-1", title: "Backend: {work}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "3", domain: "backend", specialist: "pact-backend-coder" } },
-     { id: "3-2", title: "Frontend: {work}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "3", domain: "frontend", specialist: "pact-frontend-coder" } }
-   ])
+1. `TaskUpdate({ taskId: "3", status: "in_progress", activeForm: "Implementing" })`
+2. Create subtasks for each specialist:
+   ```javascript
+   TaskCreate({ subject: "Backend: {work}", description: "...", activeForm: "Implementing", metadata: { taskType: "specialist", phaseTaskId: "3", domain: "backend", specialist: "pact-backend-coder" } })
+   TaskCreate({ subject: "Frontend: {work}", description: "...", activeForm: "Implementing", metadata: { taskType: "specialist", phaseTaskId: "3", domain: "frontend", specialist: "pact-frontend-coder" } })
    ```
-3. Update CODE: `blockedBy: ["3-1", "3-2"]` (all subtask IDs)
+3. Block phase on subtasks: `TaskUpdate({ taskId: "3", addBlockedBy: ["{backendId}", "{frontendId}"] })`
 
 > **S5 Policy Checkpoint (Pre-CODE)**: Before invoking coders, verify:
 > 1. "Does the architecture align with project principles?"
@@ -422,9 +463,9 @@ If a sub-task emerges that is too complex for a single specialist invocation:
 **Skip criteria met?** → Mark TEST task completed with `skipped: true, skipReason: "..."` → Proceed to "After All Phases Complete."
 
 **Task management**:
-1. Mark TEST `in_progress`
-2. Create subtask(s): `TodoWrite([{ id: "4-1", title: "Test: {suite}", status: "pending", metadata: { taskType: "specialist", phaseTaskId: "4", domain: "test", specialist: "pact-test-engineer" } }])`
-3. Update TEST: `blockedBy: ["4-1"]` (and other subtask IDs)
+1. `TaskUpdate({ taskId: "4", status: "in_progress", activeForm: "Testing" })`
+2. Create subtask: `TaskCreate({ subject: "Test: {suite}", description: "...", activeForm: "Testing", metadata: { taskType: "specialist", phaseTaskId: "4", specialist: "pact-test-engineer" } })`
+3. Block phase on subtask: `TaskUpdate({ taskId: "4", addBlockedBy: ["{subtaskId}"] })`
 
 **Plan sections to pass** (if plan exists):
 - "Test Phase"
diff --git a/pact-plugin/commands/peer-review.md b/pact-plugin/commands/peer-review.md
index f0f2b375..08385cd1 100644
--- a/pact-plugin/commands/peer-review.md
+++ b/pact-plugin/commands/peer-review.md
@@ -8,53 +8,83 @@ Review the current work: $ARGUMENTS
 
 ## Task Management
 
-**At workflow start**, create the workflow task and reviewer subtasks:
-
+**Create workflow task**:
+```javascript
+TaskCreate({
+  subject: "Peer Review",
+  description: "Multi-agent review of user auth feature",
+  activeForm: "Running peer review",
+  metadata: { taskType: "workflow", pactWorkflow: "peer-review" }
+})
+// Returns task ID, e.g., "1"
 ```
-1. Create workflow task: "Peer Review"
-   - metadata: { taskType: "workflow", pactWorkflow: "peer-review" }
 
-2. Create reviewer subtasks (all parallel):
-   - "Review: Architecture" → pact-architect
-   - "Review: Test coverage" → pact-test-engineer
-   - "Review: {Domain}" → domain specialist (e.g., "Review: Backend")
-
-3. Set workflow task blockedBy all reviewer subtasks
+**Create reviewer subtasks** (all dispatched in parallel):
+```javascript
+TaskCreate({
+  subject: "Review: Architecture",
+  description: "Review design coherence and patterns",
+  activeForm: "Reviewing architecture",
+  metadata: { taskType: "specialist", workflowTaskId: "1", reviewer: "pact-architect", focus: "architecture" }
+})
+// Returns task ID, e.g., "2"
+
+TaskCreate({
+  subject: "Review: Test coverage",
+  description: "Review test coverage and testability",
+  activeForm: "Reviewing tests",
+  metadata: { taskType: "specialist", workflowTaskId: "1", reviewer: "pact-test-engineer", focus: "test-coverage" }
+})
+// Returns task ID, e.g., "3"
+
+TaskCreate({
+  subject: "Review: Backend",
+  description: "Review server-side implementation quality",
+  activeForm: "Reviewing backend",
+  metadata: { taskType: "specialist", workflowTaskId: "1", reviewer: "pact-backend-coder", focus: "backend" }
+})
+// Returns task ID, e.g., "4"
 ```
 
-**Reviewer subtask metadata**:
+**Link workflow to reviewer subtasks**:
 ```javascript
-{
-  taskType: "specialist",
-  workflowTaskId: "<workflow-task-id>",
-  reviewer: "pact-architect" | "pact-test-engineer" | "pact-backend-coder" | ...,
-  focus: "architecture" | "test-coverage" | "backend" | "frontend" | "database"
-}
+TaskUpdate({
+  taskId: "1",
+  addBlockedBy: ["2", "3", "4"]
+})
 ```
 
-**On reviewer completion**, capture structured handoff:
+**On reviewer completion**, update subtask with structured handoff:
 ```javascript
-{
-  handoff: {
-    verdict: "approve" | "request-changes" | "comment",
-    findings: [
-      { severity: "blocking" | "minor" | "future", description: "...", recommendation: "..." }
-    ],
-    summary: "One-line review summary"
+TaskUpdate({
+  taskId: "2",  // architecture reviewer
+  status: "completed",
+  metadata: {
+    handoff: {
+      verdict: "approve",
+      findings: [
+        { severity: "minor", description: "Consider extracting auth middleware", recommendation: "Create shared middleware module" }
+      ],
+      summary: "Architecture sound, minor extraction opportunity"
+    }
   }
-}
+})
 ```
 
-**On workflow completion**, aggregate in workflow task metadata:
+**On workflow completion**, aggregate all reviewer findings:
 ```javascript
-{
-  handoff: {
-    overallVerdict: "approve" | "request-changes",
-    reviewerVerdicts: { "architecture": "approve", "test-coverage": "request-changes", ... },
-    consolidatedFindings: [...],  // merged from all reviewers
-    mergeReady: true | false
+TaskUpdate({
+  taskId: "1",
+  status: "completed",
+  metadata: {
+    handoff: {
+      overallVerdict: "approve",
+      reviewerVerdicts: { "architecture": "approve", "test-coverage": "approve", "backend": "approve" },
+      consolidatedFindings: [/* merged from all reviewers */],
+      mergeReady: true
+    }
   }
-}
+})
 ```
 
 ---
diff --git a/pact-plugin/commands/plan-mode.md b/pact-plugin/commands/plan-mode.md
index d28ea5c0..37afc5dd 100644
--- a/pact-plugin/commands/plan-mode.md
+++ b/pact-plugin/commands/plan-mode.md
@@ -46,43 +46,134 @@ Plan-mode creates **phase tasks** to track planning progress and **planner subta
 
 Create 4 sequential phase tasks at the start of plan-mode:
 
-| Task Name | blockedBy | Description |
-|-----------|-----------|-------------|
-| `Plan: Analyze` | — | Orchestrator scope analysis |
-| `Plan: Consult` | `Plan: Analyze` | Parallel specialist consultation |
-| `Plan: Synthesize` | `Plan: Consult` | Orchestrator conflict resolution and roadmap |
-| `Plan: Present` | `Plan: Synthesize` | Save plan, resolve user decisions |
+```javascript
+// Phase 1: Analyze
+TaskCreate({
+  subject: "Plan: Analyze",
+  description: "Assess scope, determine specialists, derive feature slug",
+  activeForm: "Planning",
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "plan-mode",
+    phase: "analyze",
+    featureSlug: "user-auth-jwt"
+  }
+})  // Returns taskId: "1"
+
+// Phase 2: Consult (blocked by Analyze)
+TaskCreate({
+  subject: "Plan: Consult",
+  description: "Parallel specialist planning consultation",
+  activeForm: "Planning",
+  addBlockedBy: ["1"],
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "plan-mode",
+    phase: "consult",
+    featureSlug: "user-auth-jwt",
+    subtaskIds: []  // Populated when planner subtasks created
+  }
+})  // Returns taskId: "2"
+
+// Phase 3: Synthesize (blocked by Consult)
+TaskCreate({
+  subject: "Plan: Synthesize",
+  description: "Resolve conflicts, build unified roadmap",
+  activeForm: "Planning",
+  addBlockedBy: ["2"],
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "plan-mode",
+    phase: "synthesize",
+    featureSlug: "user-auth-jwt"
+  }
+})  // Returns taskId: "3"
+
+// Phase 4: Present (blocked by Synthesize)
+TaskCreate({
+  subject: "Plan: Present",
+  description: "Save plan to docs/plans/, resolve user decisions",
+  activeForm: "Planning",
+  addBlockedBy: ["3"],
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "plan-mode",
+    phase: "present",
+    featureSlug: "user-auth-jwt",
+    planRef: null  // Set to "docs/plans/user-auth-jwt-plan.md" after save
+  }
+})  // Returns taskId: "4"
+```
 
 ### Planner Subtasks
 
-During the **Consult phase**, create subtasks for each specialist being consulted:
+During the **Consult phase**, create subtasks for each specialist being consulted. All run in parallel:
 
-| Subtask Name | Example |
-|--------------|---------|
-| `Plan: {Domain} perspective` | `Plan: Backend perspective` |
-| | `Plan: Architecture perspective` |
-| | `Plan: Testing perspective` |
+```javascript
+// Backend perspective (no dependencies - runs in parallel)
+TaskCreate({
+  subject: "Plan: Backend perspective",
+  description: "Backend coder planning consultation for user-auth-jwt",
+  activeForm: "Planning",
+  metadata: {
+    taskType: "planner-subtask",
+    pactWorkflow: "plan-mode",
+    parentPhaseId: "2",
+    domain: "backend"
+  }
+})  // Returns taskId: "5"
+
+// Frontend perspective (no dependencies - runs in parallel)
+TaskCreate({
+  subject: "Plan: Frontend perspective",
+  description: "Frontend coder planning consultation for user-auth-jwt",
+  activeForm: "Planning",
+  metadata: {
+    taskType: "planner-subtask",
+    pactWorkflow: "plan-mode",
+    parentPhaseId: "2",
+    domain: "frontend"
+  }
+})  // Returns taskId: "6"
+
+// After creating subtasks, update Consult phase to track them and set blockedBy
+TaskUpdate({
+  taskId: "2",
+  addBlockedBy: ["5", "6"],
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "plan-mode",
+    phase: "consult",
+    featureSlug: "user-auth-jwt",
+    subtaskIds: ["5", "6"]
+  }
+})
+```
 
 - All planner subtasks run **in parallel** (no inter-dependencies)
 - `Plan: Consult` task is `blockedBy` all its subtasks
 - When all subtasks complete, `Plan: Consult` auto-unblocks
 
-### Phase Task Metadata
+### Phase Completion
+
+When a phase completes, update with handoff summary:
 
 ```javascript
-{
-  taskType: "phase",
-  pactWorkflow: "plan-mode",
-  phase: "analyze" | "consult" | "synthesize" | "present",
-  featureSlug: "user-auth-jwt",
-  planRef: "docs/plans/user-auth-jwt-plan.md",  // Set after plan is saved
-  subtaskIds: ["4", "5", "6"],  // For Consult phase only
-  handoff: {
-    summary: "Identified 3 specialists needed; 2 conflicts to resolve",
-    keyDecisions: ["Use JWT over sessions"],
-    unresolvedItems: [{ priority: "high", description: "Auth provider choice" }]
+TaskUpdate({
+  taskId: "3",  // Plan: Synthesize
+  status: "completed",
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "plan-mode",
+    phase: "synthesize",
+    featureSlug: "user-auth-jwt",
+    handoff: {
+      summary: "Identified 3 specialists needed; 2 conflicts to resolve",
+      keyDecisions: ["Use JWT over sessions"],
+      unresolvedItems: [{ priority: "high", description: "Auth provider choice" }]
+    }
   }
-}
+})
 ```
 
 ### Key Differences from Orchestrate
diff --git a/pact-plugin/commands/rePACT.md b/pact-plugin/commands/rePACT.md
index 5dee49f9..f8812486 100644
--- a/pact-plugin/commands/rePACT.md
+++ b/pact-plugin/commands/rePACT.md
@@ -23,19 +23,87 @@ rePACT: TEST       (nested)
 
 The parent phase (from the outer orchestration) is `blockedBy` the nested `rePACT: TEST` task. This ensures the parent waits for the full nested cycle to complete.
 
-### Nested Task Metadata
+### Creating Nested Tasks
+
+When rePACT starts, create 4 nested phase tasks with parent linkage:
 
 ```javascript
-{
-  taskType: "phase",
-  pactWorkflow: "rePACT",
-  phase: "prepare" | "architect" | "code" | "test",
-  nestingLevel: 1 | 2,
-  parentPhaseId: "3",        // ID of the parent phase task that spawned this rePACT
-  parentWorkflow: "orchestrate",
-  domain: "backend" | "frontend" | "database" | null,  // null if multi-domain
-  handoff: { ... }
-}
+// Nested PREPARE (first in cycle - no blockedBy within nested cycle)
+TaskCreate({
+  subject: "rePACT: PREPARE",
+  description: "Research OAuth2 token refresh patterns",
+  activeForm: "Running rePACT",
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "rePACT",
+    phase: "prepare",
+    nestingLevel: 1,
+    parentPhaseId: "3",        // ID of parent CODE phase that spawned this
+    parentWorkflow: "orchestrate",
+    domain: "backend"
+  }
+})  // Returns taskId: "4"
+
+// Nested ARCHITECT (blocked by nested PREPARE)
+TaskCreate({
+  subject: "rePACT: ARCHITECT",
+  description: "Design token refresh component",
+  activeForm: "Running rePACT",
+  addBlockedBy: ["4"],
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "rePACT",
+    phase: "architect",
+    nestingLevel: 1,
+    parentPhaseId: "3",
+    parentWorkflow: "orchestrate",
+    domain: "backend"
+  }
+})  // Returns taskId: "5"
+
+// Nested CODE (blocked by nested ARCHITECT)
+TaskCreate({
+  subject: "rePACT: CODE",
+  description: "Implement token refresh mechanism",
+  activeForm: "Running rePACT",
+  addBlockedBy: ["5"],
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "rePACT",
+    phase: "code",
+    nestingLevel: 1,
+    parentPhaseId: "3",
+    parentWorkflow: "orchestrate",
+    domain: "backend"
+  }
+})  // Returns taskId: "6"
+
+// Nested TEST (blocked by nested CODE)
+TaskCreate({
+  subject: "rePACT: TEST",
+  description: "Smoke test token refresh flow",
+  activeForm: "Running rePACT",
+  addBlockedBy: ["6"],
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "rePACT",
+    phase: "test",
+    nestingLevel: 1,
+    parentPhaseId: "3",
+    parentWorkflow: "orchestrate",
+    domain: "backend"
+  }
+})  // Returns taskId: "7"
+
+// Update parent phase to wait for nested cycle completion
+TaskUpdate({
+  taskId: "3",  // Parent CODE phase
+  addBlockedBy: ["7"],  // Blocked by nested TEST
+  metadata: {
+    // ... existing parent metadata preserved ...
+    nestedCycleId: "7"  // Track nested cycle's final task
+  }
+})
 ```
 
 ### Parent-Child Linkage
@@ -47,6 +115,31 @@ The parent phase (from the outer orchestration) is `blockedBy` the nested `rePAC
    - Parent blocked: Parent phase `blockedBy` nested `rePACT: TEST`
 4. **On completion**: Nested TEST completes → parent phase auto-unblocks
 
+### Nested Phase Completion
+
+When a nested phase completes, update with handoff:
+
+```javascript
+TaskUpdate({
+  taskId: "7",  // rePACT: TEST
+  status: "completed",
+  metadata: {
+    taskType: "phase",
+    pactWorkflow: "rePACT",
+    phase: "test",
+    nestingLevel: 1,
+    parentPhaseId: "3",
+    parentWorkflow: "orchestrate",
+    domain: "backend",
+    handoff: {
+      summary: "Token refresh implemented with 15-min expiry",
+      keyDecisions: ["Used refresh token rotation for security"],
+      areasOfUncertainty: ["Edge case: concurrent refresh requests"]
+    }
+  }
+})
+```
+
 ### Example Task Structure
 
 ```