task-workflow

name	task-workflow
description	Understand the multi-agent task workflow structure. Reference this when working on tasks in a tasks/ directory. Defines main.md format and agent responsibilities.
source_repo	~/repos/task-workflow-plugin
source_path	skills/task-workflow/SKILL.md
disable-model-invocation	true

Task Workflow

Editing This Skill

Canonical source: ~/repos/task-workflow-plugin/skills/task-workflow/SKILL.md

If improving this skill, edit the source file above, NOT ~/.claude/skills/. The cache copy is overwritten on plugin reload.

Directory Structure

tasks/
├── global-task-manager.md   # INDEX of all tasks
├── active/          # Currently being worked on
│   └── T008-feature/
│       ├── main.md              # THE living task document
│       ├── plan-review.md       # Detailed plan review
│       └── code-review-phase-1.md
├── planning/        # Tasks being planned
├── paused/          # On hold
├── completed/       # Done
└── archived/        # Old/cancelled

main.md Structure

The main.md file is the single source of truth for a task. All agents update it.

# T{NNN}: {Task Title}

## Meta
- **Status:** PLANNING | PLAN_REVIEW | READY | EXECUTING_PHASE_{N} | CODE_REVIEW | MERGE_REVIEW | MERGE_READY | COMPLETE | BLOCKED
- **Created:** {date}
- **Last Updated:** {date}
- **Blocked Reason:** {if BLOCKED, why}

## Task
{Original task description from human}

---

## Plan

### Objective
{1-2 sentence outcome from user's perspective}

### Scope
- **In:** {included}
- **Out:** {excluded}

### Phases

#### Phase 1: {title}
- **Objective:** {what this achieves}
- **Tasks:**
  - [ ] Task 1.1: {description}
  - [ ] Task 1.2: {description}
- **Acceptance Criteria:**
  - [ ] AC1: {verifiable outcome}
- **Files:** {files to modify}
- **Dependencies:** {what must be true before starting}

#### Phase 2: {title}
{same structure}

### Decision Matrix

#### Open Questions (Need Human Input)
| # | Question | Options | Impact | Resolution |
|---|----------|---------|--------|------------|
| 1 | {question} | A) ... B) ... | {impact} | OPEN / {answer} |

#### Decisions Made (Autonomous)
| Decision | Choice | Rationale |
|----------|--------|-----------|
| {decision} | {choice} | {why} |

---

## Plan Review
- **Gate:** READY | NEEDSREADY
  {date}
  {1-2 sentence assessment}
  {count} critical, {count} major, {count} minor
  {list questions needing human input}

→ Details: 

---




  EXECUTINGN | COMPLETE | BLOCKED
  {date}
  {date}
  , 
 
  — {what changed}
  {executor observations}
  {if any}


{same structure}

---




  PASS | REVISE | FAIL
  {date}
  {count} critical, {count} major, {count} minor
  {brief assessment}

→ Details: 


{same structure}

---


  MERGEWORK | BLOCKED
  {date}
  {branch-name}
  {assessment}


{CEO-readable summary}

-> Details: 

---


  {date}
  {what was delivered}
  {for future tasks}

Agent Responsibilities

Agent	Reads	Updates in main.md	Creates
Planner	Task section	Plan section, Status→PLAN_REVIEW	—
Plan Reviewer	Plan section	Plan Review section, Status	plan-review.md
Executor	Plan (current phase)	Execution Log section, Status	—
Code Reviewer	Execution Log, git diff	Code Review Log section, Status	code-review-phase-N.md
Phase Reviewer	Code Review Log, next phase	May update Plan with learnings	—
Merge Reviewer	All sections	Merge Review section, Status	merge-review.md

Status Flow

PLANNING → PLAN_REVIEW → READY → EXECUTING_PHASE_1 → CODE_REVIEW 
                ↓                        ↓               ↓
            BLOCKED              BLOCKED (stuck)    REVISE (back to executor, max 3x)
                                                         ↓
                                                       FAIL (re-plan → BLOCKED)
     
After CODE_REVIEW PASS:
  → More phases? → EXECUTING_PHASE_N
  → Last phase? → MERGE_REVIEW → MERGE_READY → (human approves) → COMPLETE

Orchestrator Checks Status

To know what to do, read the Status field:

• PLANNING → spawn planner
• PLAN_REVIEW → spawn plan reviewer
• READY → spawn executor for Phase 1
• EXECUTING_PHASE_N → executor working (or spawn if not running)
• CODE_REVIEW → spawn code reviewer
• BLOCKED → report to human with open questions
• MERGE_REVIEW → spawn merge reviewer
• MERGE_READY → report to human for merge approval
• COMPLETE → report success