diff --git a/pact-plugin/CLAUDE.md b/pact-plugin/CLAUDE.md index 8e7e24c1..b8aa5484 100644 --- a/pact-plugin/CLAUDE.md +++ b/pact-plugin/CLAUDE.md @@ -244,6 +244,8 @@ Explicit user override ("you code this, don't delegate") should be honored; casu **If in doubt, delegate!** +**Checkpoint**: Before dispatching any agent, ALWAYS run `TaskCreate` first, then pass the returned `{task_id}` in the agent's prompt. This enables agents to track their own status via the `pact-task-tracking` skill. + #### Invoke Multiple Specialists Concurrently > ⚠️ **DEFAULT TO CONCURRENT**: When delegating, dispatch multiple specialists together in a single response unless tasks share files or have explicit dependencies. This is not optional—it's the expected mode of orchestration. @@ -336,6 +338,12 @@ Task( Use this structure in the `prompt` field to ensure agents have adequate context: +Your assigned Task ID is: {task_id} + +**FIRST ACTION (MANDATORY)** +Before doing anything else, run: `TaskUpdate(taskId={task_id}, status="in_progress")` +This must be your very first tool call. Do not skip it. + **CONTEXT** [Brief background, what phase we are in, and relevant state] @@ -353,6 +361,8 @@ A list of things that include the following: - [Best Practices] - [Wisdom from lessons learned] +> ⚠️ **Task ID Handoff (MANDATORY)**: Before dispatching any agent, ALWAYS create a Task for it via `TaskCreate` first, then include the returned Task ID as `{task_id}` in the agent's prompt (as shown above). The `pact-task-tracking` skill tells agents to call `TaskUpdate` on start and completion, but agents can only do this if they know their Task ID. Without it, tasks stay in "pending" forever. + ### How to Delegate Use these commands to trigger PACT workflows for delegating tasks: diff --git a/pact-plugin/commands/comPACT.md b/pact-plugin/commands/comPACT.md index 26e0e404..ceb166a4 100644 --- a/pact-plugin/commands/comPACT.md +++ b/pact-plugin/commands/comPACT.md @@ -15,13 +15,13 @@ Delegate this focused task within a single PACT domain: $ARGUMENTS Create a simpler Task hierarchy than full orchestrate: ``` -1. TaskCreate: Feature task "{verb} {feature}" (single-domain work) +1. TaskCreate: Feature Task "{verb} {feature}" (single-domain work) 2. Analyze: How many agents needed? -3. TaskCreate: Agent task(s) — direct children of feature -4. TaskUpdate: Feature task addBlockedBy = [all agent IDs] -5. Dispatch agents concurrently with task IDs +3. TaskCreate: Agent Task(s) — direct children of feature +4. TaskUpdate: Feature Task addBlockedBy = [all agent IDs] +5. Dispatch agents concurrently with Task IDs 6. Monitor via TaskList until all agents complete -7. TaskUpdate: Feature task status = "completed" +7. TaskUpdate: Feature Task status = "completed" ``` **Example structure:** @@ -146,6 +146,8 @@ Before invoking multiple specialists concurrently, perform this coordination che When the task contains multiple independent items, invoke multiple specialists together with boundary context: ``` +Your assigned Task ID is: {task_id} + comPACT mode (concurrent): You are one of [N] specialists working concurrently. YOUR SCOPE: [specific sub-task and files this agent owns] @@ -178,6 +180,8 @@ Use a single specialist agent only when: **Invoke the specialist with**: ``` +Your assigned Task ID is: {task_id} + comPACT mode: Work directly from this task description. Check docs/plans/, docs/preparation/, docs/architecture/ briefly if they exist—reference relevant context. Do not create new documentation artifacts in docs/. @@ -211,7 +215,7 @@ On signal detected: Follow Signal Task Handling in CLAUDE.md. 1. **Receive handoff** from specialist(s) 2. **Run tests** — verify work passes. If tests fail → return to specialist for fixes before committing. -3. **TaskUpdate**: Feature task status = "completed" +3. **TaskUpdate**: Feature Task status = "completed" 4. **Create atomic commit(s)** — stage and commit before proceeding **Next steps** (user decides): diff --git a/pact-plugin/commands/imPACT.md b/pact-plugin/commands/imPACT.md index 8cc6b3c9..48810d6f 100644 --- a/pact-plugin/commands/imPACT.md +++ b/pact-plugin/commands/imPACT.md @@ -14,13 +14,13 @@ imPACT operates on existing blocker Tasks created by agents: 1. TaskGet(blocker_id) — understand the blocker context 2. Triage: redo prior phase? need specialist? need user? 3. On resolution path chosen: - - If delegating: TaskCreate resolution agent task + - If delegating: TaskCreate resolution agent Task, include its `{task_id}` in the agent prompt - If self-resolving: proceed directly 4. On resolution complete: TaskUpdate(blocker_id, status="completed") -5. Blocked agent task is now unblocked +5. Blocked agent Task is now unblocked ``` -**Note**: Agents create blocker Tasks and block themselves via `addBlockedBy`. When the blocker is resolved (marked completed), the agent's task becomes unblocked. +**Note**: Agents create blocker Tasks and block themselves via `addBlockedBy`. When the blocker is resolved (marked completed), the agent's Task becomes unblocked. --- diff --git a/pact-plugin/commands/orchestrate.md b/pact-plugin/commands/orchestrate.md index 2fa1f5af..b92f67a1 100644 --- a/pact-plugin/commands/orchestrate.md +++ b/pact-plugin/commands/orchestrate.md @@ -11,8 +11,8 @@ Orchestrate specialist PACT agents through the PACT workflow to address: $ARGUME Create the full Task hierarchy upfront for workflow visibility: ``` -1. TaskCreate: Feature task "{verb} {feature}" -2. TaskCreate: Phase tasks (all upfront): +1. TaskCreate: Feature Task "{verb} {feature}" +2. TaskCreate: Phase Tasks (all upfront): - "PREPARE: {feature-slug}" - "ARCHITECT: {feature-slug}" - "CODE: {feature-slug}" @@ -27,9 +27,9 @@ For each phase execution: ``` a. TaskUpdate: phase status = "in_progress" b. Analyze work needed (QDCL for CODE) -c. TaskCreate: agent task(s) as children of phase +c. TaskCreate: agent Task(s) as children of phase d. TaskUpdate: next phase addBlockedBy = [agent IDs] -e. Dispatch agents with task IDs in their prompts +e. Dispatch agents with Task IDs in their prompts f. Monitor via TaskList until agents complete g. TaskUpdate: phase status = "completed" ``` @@ -231,7 +231,7 @@ Each specialist should end with a structured handoff: - "Preparation Phase" - "Open Questions > Require Further Research" -**Invoke `pact-preparer` with**: +**Invoke `pact-preparer` with** (include the agent's `{task_id}` from TaskCreate): - Task description - Plan sections above (if any) - "Reference the approved plan at `docs/plans/{slug}-plan.md` for full context." @@ -269,7 +269,7 @@ If PREPARE ran and ARCHITECT was marked "Skip," compare PREPARE's recommended ap - "Key Decisions" - "Interface Contracts" -**Invoke `pact-architect` with**: +**Invoke `pact-architect` with** (include the agent's `{task_id}` from TaskCreate): - Task description - PREPARE phase outputs - Plan sections above (if any) @@ -347,7 +347,7 @@ Before concurrent dispatch, check internally: shared files? shared interfaces? c **Include in prompts for concurrent specialists**: "You are working concurrently with other specialists. Your scope is [files]. Do not modify files outside your scope." -**Invoke coder(s) with**: +**Invoke coder(s) with** (include each agent's `{task_id}` from TaskCreate): - Task description - ARCHITECT phase outputs (or plan's Architecture Phase if ARCHITECT was skipped) - Plan sections above (if any) @@ -389,7 +389,7 @@ If a sub-task emerges that is too complex for a single specialist invocation: - "Test Scenarios" - "Coverage Targets" -**Invoke `pact-test-engineer` with**: +**Invoke `pact-test-engineer` with** (include the agent's `{task_id}` from TaskCreate): - Task description - CODE phase handoff(s): Pass the handoff summaries from coders for context on what was built - Plan sections above (if any) @@ -422,7 +422,7 @@ On signal detected: Follow Signal Task Handling in CLAUDE.md. > **S5 Policy Checkpoint (Pre-PR)**: Before creating PR, verify: "Do all tests pass? Is system integrity maintained? Have S5 non-negotiables been respected throughout?" 1. **Update plan status** (if plan exists): IN_PROGRESS → IMPLEMENTED -2. **TaskUpdate**: Feature task status = "completed" (all phases done) +2. **TaskUpdate**: Feature Task status = "completed" (all phases done) 3. **Verify all work is committed** — CODE and TEST phase commits should already exist; if any uncommitted changes remain, commit them now 4. **Run `/PACT:peer-review`** to create PR and get multi-agent review 5. **Present review summary and stop** — orchestrator never merges (S5 policy) diff --git a/pact-plugin/commands/peer-review.md b/pact-plugin/commands/peer-review.md index 9d53ff8b..05c5c4f4 100644 --- a/pact-plugin/commands/peer-review.md +++ b/pact-plugin/commands/peer-review.md @@ -15,25 +15,25 @@ Review the current work: $ARGUMENTS Create a review Task hierarchy: ``` -1. TaskCreate: Review task "Review: {feature}" +1. TaskCreate: Review Task "Review: {feature}" 2. Analyze PR: Which reviewers needed? -3. TaskCreate: Reviewer agent tasks (architect, test-engineer, domain specialists) -4. TaskUpdate: Review task addBlockedBy = [reviewer IDs] -5. Dispatch reviewers in parallel +3. TaskCreate: Reviewer agent Tasks (architect, test-engineer, domain specialists) +4. TaskUpdate: Review Task addBlockedBy = [reviewer IDs] +5. Dispatch reviewers in parallel (include each reviewer's `{task_id}` in their prompt) 6. Monitor until reviewers complete 7. Synthesize findings 8. If major issues: - a. TaskCreate: Remediation agent tasks + a. TaskCreate: Remediation agent Tasks b. Dispatch, monitor until complete -9. TaskCreate: "User: review minor issues" step task +9. TaskCreate: "User: review minor issues" step Task 10. Present minor issues to user, record decisions in step metadata 11. If "fix now" decisions: - a. TaskCreate: Remediation agent tasks + a. TaskCreate: Remediation agent Tasks b. Dispatch, monitor until complete -12. TaskCreate: "Awaiting merge decision" approval task +12. TaskCreate: "Awaiting merge decision" approval Task 13. Present to user, await approval -14. On approval: TaskUpdate approval completed -15. TaskUpdate: Review task completed, metadata.artifact = PR URL +14. On approval: TaskUpdate approval Task completed +15. TaskUpdate: Review Task completed, metadata.artifact = PR URL ``` **Example structure:** @@ -67,6 +67,29 @@ Select the domain coder based on PR focus: - Database changes → **pact-database-engineer** (Query efficiency, schema design, data integrity) - Multiple domains → Coder for domain with most significant changes, or all relevant domain coders if changes are equally significant +**Use this prompt template for each reviewer:** + +``` +Your assigned Task ID is: {task_id} + +PEER REVIEW — Review this PR for issues in your domain of expertise. + +PR: {PR URL or branch name} + +As the {role} reviewer, evaluate: +1. Issues in your domain (bugs, design flaws, missing edge cases) +2. Adherence to project conventions and patterns +3. Security, performance, or maintainability concerns + +Classify each finding as: +- **Blocking**: Must fix before merge +- **Minor**: Optional improvement for this PR +- **Future**: Out of scope; suggest tracking as GitHub issue + +Output your findings as a markdown table with columns: Recommendation | Severity | Details. +If no issues found, state "No issues found." +``` + --- ## Output Conciseness diff --git a/pact-plugin/commands/plan-mode.md b/pact-plugin/commands/plan-mode.md index c55351f1..f5c77bc1 100644 --- a/pact-plugin/commands/plan-mode.md +++ b/pact-plugin/commands/plan-mode.md @@ -13,14 +13,14 @@ Create a comprehensive implementation plan for: $ARGUMENTS Create a planning Task hierarchy: ``` -1. TaskCreate: Planning task "Plan: {feature}" +1. TaskCreate: Planning Task "Plan: {feature}" 2. Analyze: Which specialists to consult? -3. TaskCreate: Consultation task(s) — one per specialist -4. TaskUpdate: Planning task addBlockedBy = [consultation IDs] -5. Dispatch specialists in parallel (planning-only mode) +3. TaskCreate: Consultation Task(s) — one per specialist +4. TaskUpdate: Planning Task addBlockedBy = [consultation IDs] +5. Dispatch specialists in parallel (planning-only mode, include each specialist's `{task_id}` in their prompt) 6. Monitor until consultations complete 7. Synthesize → write plan document -8. TaskUpdate: Planning task completed, metadata.artifact = plan path +8. TaskUpdate: Planning Task completed, metadata.artifact = plan path ``` **Example structure:** @@ -99,6 +99,8 @@ Invoke relevant specialists **in parallel**, each in **planning-only mode**. **Use this prompt template for each specialist:** ``` +Your assigned Task ID is: {task_id} + PLANNING CONSULTATION ONLY — No implementation, no code changes. Task: {task description} @@ -231,7 +233,7 @@ After collecting all specialist outputs, use extended thinking to synthesize: ### Phase 3: Plan Output -**TaskUpdate**: Planning task completed with artifact path: +**TaskUpdate**: Planning Task completed with artifact path: ``` TaskUpdate( taskId=planning_task_id, @@ -498,4 +500,4 @@ After the user approves the plan: 3. If plan exists, use it as the implementation specification 4. Specialists receive relevant sections of the plan as context -**Task Linkage**: When `/PACT:orchestrate` runs, it checks for a completed Planning task matching the feature. If found, the plan artifact path from `metadata.artifact` is used to locate and reference the approved plan automatically. +**Task Linkage**: When `/PACT:orchestrate` runs, it checks for a completed Planning Task matching the feature. If found, the plan artifact path from `metadata.artifact` is used to locate and reference the approved plan automatically. diff --git a/pact-plugin/commands/rePACT.md b/pact-plugin/commands/rePACT.md index 965fcd30..66ab2999 100644 --- a/pact-plugin/commands/rePACT.md +++ b/pact-plugin/commands/rePACT.md @@ -13,17 +13,17 @@ This command initiates a **nested P→A→C→T cycle** for a sub-task that is t Create a nested Task hierarchy as a child of the current context: ``` -1. TaskCreate: Sub-feature task "{verb} {sub-feature}" (child of parent context) -2. TaskCreate: Nested phase tasks: +1. TaskCreate: Sub-feature Task "{verb} {sub-feature}" (child of parent context) +2. TaskCreate: Nested phase Tasks: - "PREPARE: {sub-feature-slug}" - "ARCHITECT: {sub-feature-slug}" - "CODE: {sub-feature-slug}" - "TEST: {sub-feature-slug}" 3. TaskUpdate: Set dependencies: - Phase-to-phase blockedBy chain (same as orchestrate) - - Parent task addBlockedBy = [sub-feature task] -4. Execute nested P→A→C→T cycle -5. On completion: Parent task unblocked + - Parent Task addBlockedBy = [sub-feature Task] +4. Execute nested P→A→C→T cycle (include each agent's `{task_id}` in their prompt) +5. On completion: Parent Task unblocked ``` **Example structure:** @@ -142,7 +142,7 @@ If you hit the nesting limit: ### Branch Behavior - **No new branch**: rePACT stays on the current feature branch -- **No PR**: Results integrate into the parent task's eventual PR +- **No PR**: Results integrate into the parent Task's eventual PR - All commits remain part of the current feature work --- @@ -179,6 +179,23 @@ Implement the sub-component: - Apply S2 coordination if parallel work - Output: Code + handoff summary +**Use this prompt template for each specialist:** + +``` +Your assigned Task ID is: {task_id} + +rePACT nested cycle — sub-task of parent feature. + +Parent context: {parent feature description} +Sub-task: {sub-task description} + +Work directly from this sub-task description. +Stay within the sub-component scope. Do not modify files outside your boundary. +Smoke test your changes before handoff. + +If you hit a blocker, STOP and report it. +``` + ### Phase 4: Mini-Test Verify the sub-component: @@ -198,7 +215,7 @@ Complete the nested cycle: Nested cycles inherit from parent: - Current feature branch -- Parent task context and requirements +- Parent Task context and requirements - Architectural decisions from parent - Coding conventions established in parent @@ -294,10 +311,10 @@ On signal detected: Follow Signal Task Handling in CLAUDE.md. ## After Completion When nested cycle completes: -1. **TaskUpdate**: Sub-feature task status = "completed" +1. **TaskUpdate**: Sub-feature Task status = "completed" 2. **Summarize** what was done in the nested cycle -3. **Report** any decisions that affect the parent task -4. **Continue** with parent orchestration (parent task now unblocked) +3. **Report** any decisions that affect the parent Task +4. **Continue** with parent orchestration (parent Task now unblocked) **Handoff format**: Use the standard 4-item structure (Produced, Key context, Areas of uncertainty, Open questions). See orchestrate.md § Handoff Format. diff --git a/pact-plugin/commands/wrap-up.md b/pact-plugin/commands/wrap-up.md index 994bb86e..1ea801fd 100644 --- a/pact-plugin/commands/wrap-up.md +++ b/pact-plugin/commands/wrap-up.md @@ -12,7 +12,7 @@ Before other cleanup, audit and optionally clean up Task state: ``` 1. TaskList: Review all session tasks 2. For abandoned in_progress tasks: complete or document reason -3. Verify Feature task reflects final state +3. Verify Feature Task reflects final state 4. Archive key context to memory (via pact-memory-agent) 5. Report task summary: "Session has N tasks (X completed, Y pending)" 6. IF multi-session mode (CLAUDE_CODE_TASK_LIST_ID set): @@ -25,8 +25,8 @@ Before other cleanup, audit and optionally clean up Task state: | Task State | Cleanup Action | |------------|----------------| -| `completed` Feature task | Archive summary, then delete with children | -| `in_progress` Feature task | Do NOT delete (workflow still active) | +| `completed` Feature Task | Archive summary, then delete with children | +| `in_progress` Feature Task | Do NOT delete (workflow still active) | | Orphaned `in_progress` | Document abandonment reason, then delete | | `pending` blocked forever | Delete with note | diff --git a/pact-plugin/hooks/validate_handoff.py b/pact-plugin/hooks/validate_handoff.py index 59945f19..e092ce1b 100755 --- a/pact-plugin/hooks/validate_handoff.py +++ b/pact-plugin/hooks/validate_handoff.py @@ -6,7 +6,7 @@ Validates that PACT agents: 1. Complete with proper handoff information (produced, decisions, next steps) -2. Called TaskUpdate(status="completed") with required metadata (Task integration) +2. Reported completion via structured HANDOFF text (orchestrator handles TaskUpdate) Input: JSON from stdin with `transcript`, `agent_id`, and optionally `task_id` Output: JSON with `systemMessage` if handoff format is incomplete or Task protocol violated diff --git a/pact-plugin/protocols/pact-protocols.md b/pact-plugin/protocols/pact-protocols.md index 95428515..cd132b81 100644 --- a/pact-plugin/protocols/pact-protocols.md +++ b/pact-plugin/protocols/pact-protocols.md @@ -562,7 +562,7 @@ When a sub-task is complex enough to warrant its own PACT treatment: **Protocol:** 1. **Declare**: "Invoking nested PACT for {sub-task}" 2. **Execute**: Run mini-PACT cycle (may skip phases if not needed) -3. **Integrate**: Merge results back to parent task +3. **Integrate**: Merge results back to parent Task 4. **Report**: Include nested work in handoff to orchestrator **Constraints:** @@ -573,7 +573,7 @@ When a sub-task is complex enough to warrant its own PACT treatment: **Example:** ``` -Parent task: "Implement user authentication service" +Parent Task: "Implement user authentication service" Nested PACT: "Research and implement OAuth2 token refresh mechanism" - Mini-Prepare: Research OAuth2 refresh token best practices - Mini-Architect: Design token storage and refresh flow @@ -893,15 +893,15 @@ Tasks progress through: `pending` → `in_progress` → `completed` Use `addBlockedBy` to express dependencies: ``` -CODE phase task -├── blockedBy: [ARCHITECT task ID] -└── Agent tasks within CODE - └── blockedBy: [CODE phase task ID] +CODE phase Task +├── blockedBy: [ARCHITECT Task ID] +└── Agent Tasks within CODE + └── blockedBy: [CODE phase Task ID] ``` ### Metadata Conventions -Agent tasks include metadata for context: +Agent Tasks include metadata for context: ```json { @@ -917,18 +917,18 @@ Agent tasks include metadata for context: ### Integration with PACT Signals -- **Algedonic signals**: Emit via task metadata or direct escalation -- **Variety signals**: Note in task metadata when complexity differs from estimate -- **Handoff**: Store structured handoff in task metadata on completion +- **Algedonic signals**: Emit via Task metadata or direct escalation +- **Variety signals**: Note in Task metadata when complexity differs from estimate +- **Handoff**: Store structured handoff in Task metadata on completion ### Example Flow -1. Orchestrator creates Feature task: "Implement user authentication" (parent container) -2. Orchestrator creates PREPARE phase task under the Feature task -3. Orchestrator dispatches pact-preparer with agent task (blocked by PREPARE phase task) -4. Preparer completes, updates task to completed with handoff metadata -5. Orchestrator marks PREPARE complete, creates ARCHITECT phase task -6. Orchestrator creates CODE phase task (blocked by ARCHITECT phase task) +1. Orchestrator creates Feature Task: "Implement user authentication" (parent container) +2. Orchestrator creates PREPARE phase Task under the Feature Task +3. Orchestrator dispatches pact-preparer with agent Task (blocked by PREPARE phase Task) +4. Preparer completes, updates Task to completed with handoff metadata +5. Orchestrator marks PREPARE complete, creates ARCHITECT phase Task +6. Orchestrator creates CODE phase Task (blocked by ARCHITECT phase Task) 7. Pattern continues through remaining phases --- diff --git a/pact-plugin/protocols/pact-s1-autonomy.md b/pact-plugin/protocols/pact-s1-autonomy.md index f7be2ac7..d2b2f058 100644 --- a/pact-plugin/protocols/pact-s1-autonomy.md +++ b/pact-plugin/protocols/pact-s1-autonomy.md @@ -37,7 +37,7 @@ When a sub-task is complex enough to warrant its own PACT treatment: **Protocol:** 1. **Declare**: "Invoking nested PACT for {sub-task}" 2. **Execute**: Run mini-PACT cycle (may skip phases if not needed) -3. **Integrate**: Merge results back to parent task +3. **Integrate**: Merge results back to parent Task 4. **Report**: Include nested work in handoff to orchestrator **Constraints:** @@ -48,7 +48,7 @@ When a sub-task is complex enough to warrant its own PACT treatment: **Example:** ``` -Parent task: "Implement user authentication service" +Parent Task: "Implement user authentication service" Nested PACT: "Research and implement OAuth2 token refresh mechanism" - Mini-Prepare: Research OAuth2 refresh token best practices - Mini-Architect: Design token storage and refresh flow diff --git a/pact-plugin/protocols/pact-task-hierarchy.md b/pact-plugin/protocols/pact-task-hierarchy.md index 9231ecde..53b4505d 100644 --- a/pact-plugin/protocols/pact-task-hierarchy.md +++ b/pact-plugin/protocols/pact-task-hierarchy.md @@ -34,15 +34,15 @@ Tasks progress through: `pending` → `in_progress` → `completed` Use `addBlockedBy` to express dependencies: ``` -CODE phase task -├── blockedBy: [ARCHITECT task ID] -└── Agent tasks within CODE - └── blockedBy: [CODE phase task ID] +CODE phase Task +├── blockedBy: [ARCHITECT Task ID] +└── Agent Tasks within CODE + └── blockedBy: [CODE phase Task ID] ``` ### Metadata Conventions -Agent tasks include metadata for context: +Agent Tasks include metadata for context: ```json { @@ -58,17 +58,17 @@ Agent tasks include metadata for context: ### Integration with PACT Signals -- **Algedonic signals**: Emit via task metadata or direct escalation -- **Variety signals**: Note in task metadata when complexity differs from estimate -- **Handoff**: Store structured handoff in task metadata on completion +- **Algedonic signals**: Emit via Task metadata or direct escalation +- **Variety signals**: Note in Task metadata when complexity differs from estimate +- **Handoff**: Store structured handoff in Task metadata on completion ### Example Flow -1. Orchestrator creates Feature task: "Implement user authentication" (parent container) -2. Orchestrator creates PREPARE phase task under the Feature task -3. Orchestrator dispatches pact-preparer with agent task (blocked by PREPARE phase task) -4. Preparer completes, updates task to completed with handoff metadata -5. Orchestrator marks PREPARE complete, creates ARCHITECT phase task -6. Orchestrator creates CODE phase task (blocked by ARCHITECT phase task) +1. Orchestrator creates Feature Task: "Implement user authentication" (parent container) +2. Orchestrator creates PREPARE phase Task under the Feature Task +3. Orchestrator dispatches pact-preparer with agent Task (blocked by PREPARE phase Task) +4. Preparer completes, updates Task to completed with handoff metadata +5. Orchestrator marks PREPARE complete, creates ARCHITECT phase Task +6. Orchestrator creates CODE phase Task (blocked by ARCHITECT phase Task) 7. Pattern continues through remaining phases diff --git a/pact-plugin/skills/pact-task-tracking/SKILL.md b/pact-plugin/skills/pact-task-tracking/SKILL.md index 38bed0d5..ccaa6872 100644 --- a/pact-plugin/skills/pact-task-tracking/SKILL.md +++ b/pact-plugin/skills/pact-task-tracking/SKILL.md @@ -11,29 +11,37 @@ description: | > **Reference**: See [Claude Code Task System](https://docs.anthropic.com/en/docs/claude-code/tasks) for full API documentation. -> **Note**: The orchestrator passes your assigned task ID when dispatching you. Use this ID in all TaskUpdate calls. +## Your Task ID -You have been assigned Task ID: {task_id} +CRITICAL: Look in your prompt for this line: +``` +Your assigned Task ID is: +``` +Extract the number. That is **YOUR_TASK_ID** for every `TaskUpdate` call below. -## On Start +> **If no such line exists in your prompt**, skip all `TaskUpdate` calls in this protocol. Your work proceeds normally; only Task tracking is skipped. -Before any other work, update your task status: +## On Start (MANDATORY FIRST ACTION) + +**Your very first tool call MUST be `TaskUpdate`.** Do not read files, do not invoke skills, do not begin any work until you have executed: ``` -TaskUpdate(taskId="{task_id}", status="in_progress") +TaskUpdate(taskId=YOUR_TASK_ID, status="in_progress") ``` +This is a prerequisite gate. Nothing else proceeds until this call is made. If you skip this step, the orchestrator has no visibility into your status and cannot coordinate work across agents. + ## On Blocker If you cannot proceed: -1. Create a blocker task: +1. Create a blocker Task: ``` TaskCreate(subject="Resolve: {description}", metadata={"type": "blocker"}) ``` -2. Link it to your task: +2. Link it to your Task: ``` - TaskUpdate(taskId="{task_id}", addBlockedBy=[blocker_id]) + TaskUpdate(taskId=YOUR_TASK_ID, addBlockedBy=[blocker_id]) ``` 3. Stop work and report: "BLOCKER: {description}" @@ -41,24 +49,24 @@ If you cannot proceed: When you detect a viability threat: -1. Create an algedonic task: +1. Create an algedonic Task: ``` TaskCreate(subject="⚠️ [HALT|ALERT]: {category}", metadata={"type": "algedonic", "level": "...", "category": "..."}) ``` -2. Link it to your task: +2. Link it to your Task: ``` - TaskUpdate(taskId="{task_id}", addBlockedBy=[algedonic_id]) + TaskUpdate(taskId=YOUR_TASK_ID, addBlockedBy=[algedonic_id]) ``` 3. Stop immediately 4. Report signal to orchestrator -## On Completion +## On Completion (REQUIRED) -After all work is done: +Before returning your final response, mark your Task as completed: ``` TaskUpdate( - taskId="{task_id}", + taskId=YOUR_TASK_ID, status="completed", metadata={ "produced": ["file1.ts", "file2.ts"], @@ -68,3 +76,4 @@ TaskUpdate( ) ``` +Do not end your work without making this call. The orchestrator relies on completion status to coordinate subsequent phases. diff --git a/pact-plugin/skills/pact-task-tracking/test_skill_loading.py b/pact-plugin/skills/pact-task-tracking/test_skill_loading.py index 8324593d..7ab26ae1 100644 --- a/pact-plugin/skills/pact-task-tracking/test_skill_loading.py +++ b/pact-plugin/skills/pact-task-tracking/test_skill_loading.py @@ -82,8 +82,12 @@ def test_has_on_completion_section(self, skill_content): """Skill must include 'On Completion' section.""" assert "## On Completion" in skill_content, "SKILL.md must include '## On Completion' section" - def test_task_id_placeholder_present(self, skill_content): - """Skill must include task_id placeholder for orchestrator injection.""" - assert "{task_id}" in skill_content, ( - "SKILL.md must include '{task_id}' placeholder for task ID injection" - ) + def test_text_based_reporting_keywords(self, skill_content): + """Skill must include key text-based reporting protocol references.""" + # Under the new model, agents report status via structured text + # (HANDOFF, BLOCKER, ALGEDONIC) rather than {task_id} placeholders. + required_keywords = ["Blocker", "Completion"] + for keyword in required_keywords: + assert keyword in skill_content, ( + f"SKILL.md must reference '{keyword}' for text-based reporting protocol" + )