feat: integrate PACT with Claude Code Task system (#112)

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:
+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:

pact-plugin/agents/pact-backend-coder.md

@@ -108,9 +108,9 @@ Your work isn't done until smoke tests pass. Smoke tests verify: "Does it compil
 
 End with a structured handoff for the orchestrator:
 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**
 

pact-plugin/agents/pact-database-engineer.md

@@ -126,9 +126,9 @@ Your work isn't done until smoke tests pass. Smoke tests verify: "Does the schem
 
 End with a structured handoff for the orchestrator:
 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**
 

pact-plugin/agents/pact-frontend-coder.md

@@ -99,9 +99,9 @@ Your work isn't done until smoke tests pass. Smoke tests verify: "Does it compil
 
 End with a structured handoff for the orchestrator:
 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**
 

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:
+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:

pact-plugin/agents/pact-test-engineer.md

@@ -229,9 +229,9 @@ The orchestrator passes CODE phase handoff summaries. Use these for context:
 
 End with a structured handoff for the orchestrator:
 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**
 

pact-plugin/commands/comPACT.md

@@ -115,6 +115,70 @@ Before invoking multiple specialists concurrently, perform this coordination che
 
 ---
 
+## Task Management
+
+Create tasks to track workflow progress:
+
+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 with handoff
+
+**Create workflow task**:
+```javascript
+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"
+```
+
+**Create specialist subtasks** (one per work item):
+```javascript
+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"
+    }
+  }
+})
+```
+
+---
+
 ## Invocation
 
 ### Multiple Specialists Concurrently (Default)

pact-plugin/commands/imPACT.md

@@ -99,3 +99,105 @@ 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 using TaskUpdate:
+
+```javascript
+// 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
+
+| 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.