task-progress-knowledge

# Task Progress Knowledge

Guidelines for using TaskCreate/TaskUpdate tools in coordinator agents to provide user visibility into multi-phase workflows.

## When to Use TaskCreate

Use TaskCreate in **coordinator agents** with **3+ major phases**:

- **Code review coordinators** — multiple review phases
- **Bug fix coordinators** — diagnose → fix → test pipeline
- **Refactoring coordinators** — analyze → plan → generate
- **Architecture auditors** — multi-domain audits
- **CI/CD coordinators** — setup/fix/optimize operations

**Do NOT use** for:
- Single-phase operations
- Simple generators
- Leaf agents (non-coordinators)

## TaskCreate Fields

| Field | Purpose | Example |
|-------|---------|---------|
| `subject` | Brief task title (imperative) | "Diagnose bug" |
| `description` | What happens in this phase | "Analyze code to identify bug category and root cause" |
| `activeForm` | Spinner text (present continuous) | "Diagnosing bug..." |

## Workflow Pattern

```
1. TaskCreate (all phases upfront)
   ├── Phase 1: subject="Analyze changes", activeForm="Analyzing changes..."
   ├── Phase 2: subject="Run reviewers", activeForm="Running reviewers..."
   └── Phase 3: subject="Generate report", activeForm="Generating report..."

2. Execute with status updates:
   For each phase:
   ├── TaskUpdate(taskId, status: in_progress)
   ├── ... execute phase work ...
   └── TaskUpdate(taskId, status: completed)
```

## Examples by Coordinator Type

### Bug Fix Coordinator (3 phases)

```
TaskCreate: subject="Diagnose bug", description="Identify bug category, severity, root cause", activeForm="Diagnosing bug..."
TaskCreate: subject="Generate fix", description="Create minimal, safe fix", activeForm="Generating fix..."
TaskCreate: subject="Create regression test", description="Generate test that catches this bug", activeForm="Creating test..."
```

### Code Review Coordinator (3 phases)

```
TaskCreate: subject="Analyze changes", description="Parse git diff, identify changed files", activeForm="Analyzing changes..."
TaskCreate: subject="Run reviewers", description="Execute specialized reviewers by level", activeForm="Running reviewers..."
TaskCreate: subject="Aggregate report", description="Combine findings, determine verdict", activeForm="Aggregating findings..."
```

### Architecture Auditor (4 phases)

```
TaskCreate: subject="Structural audit", description="DDD, Clean, Hexagonal, SOLID", activeForm="Auditing structure..."
TaskCreate: subject="Behavioral audit", description="CQRS, Event Sourcing, EDA", activeForm="Auditing behavior..."
TaskCreate: subject="Integration audit", description="Outbox, Saga, Stability", activeForm="Auditing integration..."
TaskCreate: subject="Cross-pattern analysis", description="Find conflicts between patterns", activeForm="Analyzing patterns..."
```

### CI Coordinator (3 phases)

```
TaskCreate: subject="Analyze configuration", description="Parse CI config, detect issues", activeForm="Analyzing config..."
TaskCreate: subject="Execute operation", description="Run setup/fix/optimize/audit", activeForm="Executing operation..."
TaskCreate: subject="Validate result", description="Verify changes, run syntax checks", activeForm="Validating result..."
```

### Refactor Coordinator (3 phases)

```
TaskCreate: subject="Analyze code quality", description="Run readability and testability reviewers", activeForm="Analyzing code..."
TaskCreate: subject="Plan refactoring", description="Prioritize issues, map to techniques", activeForm="Planning refactoring..."
TaskCreate: subject="Generate recommendations", description="Create actionable report with commands", activeForm="Generating recommendations..."
```

### DDD Auditor (3 phases)

```
TaskCreate: subject="Analyze layers", description="Check Domain, Application, Infrastructure separation", activeForm="Analyzing layers..."
TaskCreate: subject="Check dependencies", description="Detect violations between layers", activeForm="Checking dependencies..."
TaskCreate: subject="Verify patterns", description="Check DDD patterns compliance", activeForm="Verifying patterns..."
```

### Pattern Auditor (4 phases)

```
TaskCreate: subject="Audit stability patterns", description="Circuit Breaker, Retry, Rate Limiter, Bulkhead", activeForm="Auditing stability..."
TaskCreate: subject="Audit behavioral patterns", description="Strategy, State, Chain, Decorator", activeForm="Auditing behavioral..."
TaskCreate: subject="Audit creational patterns", description="Builder, Object Pool, Factory", activeForm="Auditing creational..."
TaskCreate: subject="Audit integration patterns", description="Outbox, Saga, ADR", activeForm="Auditing integration..."
```

## Best Practices

1. **Create all tasks upfront** — user sees full workflow before execution
2. **Keep phases coarse** — 3-5 major phases, not individual steps
3. **Use clear activeForm** — user sees this in spinner during execution
4. **Always complete tasks** — mark as completed even if phase finds nothing
5. **Don't nest tasks** — only coordinator creates tasks, not delegated agents
6. **Handle failures gracefully** — if phase fails, still mark task completed with error note