Overview

Implement integration between PACT framework and Claude Code's native Task system (v2.1.16+), aligning PACT's work tracking with Anthropic's development direction.

Supersedes: #110 (initial research and exploration)
Research docs: docs/research/pact-task-integration-brainstorm-session.md

Design Decisions

Alignment Framing

PACT adopts Task primitives as its work tracking layer, while maintaining its own methodology layer (VSM, phases, coordination protocols).

Hybrid Task Model

Phase tasks (owned by orchestrator) + Specialist subtasks (owned by specialists)

Phase Tasks (upfront, sequential):
  PREPARE → ARCHITECT → CODE → TEST

When orchestrator starts CODE phase:
  - Creates specialist subtasks: "Backend: Implement X", "Frontend: Add Y"
  - Phase task blocked by its subtasks
  - When subtasks complete → phase auto-unblocks → orchestrator completes phase

Naming Conventions

Metadata Schemas

Phase Task:

{
  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, nextPhaseContext }
}

Specialist Subtask:

{
  taskType: "specialist",
  phaseTaskId: "3",
  domain: "backend" | "frontend" | "database",
  specialist: "pact-backend-coder" | ...,
  agentId: "agent-abc123",
  handoff: { produced, decisions, uncertainties, openQuestions }
}

Workflow Task (comPACT, Peer Review):

{
  taskType: "workflow",
  pactWorkflow: "comPACT" | "peer-review",
  domain: "backend",
  subtaskIds: [...]
}

Command Integration

Status Transitions

• Orchestrator owns both transitions (in_progress and completed)
• Specialist subtasks block their parent phase task
• Phase auto-unblocks when all subtasks complete
• Orchestrator decides when to mark phase completed

Skipped Phases

Create task, immediately mark completed with skip indicator:

{ status: "completed", metadata: { skipped: true, skipReason: "..." }}

Algedonic Integration

Annotate existing tasks (don't create new ones):

metadata: {
  algedonicHalt: { category, issue, awaitingAcknowledgment },
  algedonicHistory: [{ type, category, triggeredAt, resolvedAt, resolution }]
}

Implementation Checklist

Files to Modify

Commands:

• commands/orchestrate.md — 4 phase tasks + specialist subtasks + skip handling
• commands/comPACT.md — Workflow task + specialist subtasks
• commands/peer-review.md — Workflow task + reviewer subtasks
• commands/plan-mode.md — 4 phase tasks + planner subtasks
• commands/rePACT.md — Nested phase tasks with parent linking
• commands/imPACT.md — Task modification logic

Protocols:

• protocols/pact-protocols.md — Add task integration section (SSOT)
• protocols/pact-workflows.md — Add task structure for each workflow
• protocols/algedonic.md — Add task annotation section
• Run ./scripts/verify-protocol-extracts.sh to verify sync

Agents:

• agents/pact-backend-coder.md — Standardize handoff format
• agents/pact-frontend-coder.md — Standardize handoff format
• agents/pact-database-engineer.md — Standardize handoff format
• agents/pact-test-engineer.md — Standardize handoff format
• agents/pact-architect.md — Standardize handoff format
• agents/pact-preparer.md — Standardize handoff format

Files to Create

• reference/task-metadata-schema.md — Document all schemas
• reference/task-integration-guide.md — How Task system integrates with PACT

Validation Criteria

Key Insights from Research

• Token usage explains 80% of multi-agent performance variance (Anthropic)
• Task owner is singular → orchestrator owns phase tasks, specialists own subtasks
• Task system designed for: Pipeline, Fan-out, Fan-in, Swarm patterns
• PACT execution is Pipeline + Fan-out + Fan-in combined