task-automation

# Task Automation Skill

Automated task execution system for the Journey project. Manages a task manifest and executes tasks via parallel agents.

## When Claude Should Use This Skill

- User says "run tasks", "execute tasks", "dev loop", "work on backlog"
- User asks about task status or pipeline health
- User wants to run multiple tasks in parallel
- User mentions the manifest or available tasks

## Core Concepts

### Task Manifest
Located at `docs/planning/tasks/manifest.json`. Contains:
- Task definitions with ID, title, priority, complexity
- Status tracking (available, claimed, in_progress, completed)
- Dependencies between tasks
- Tags for categorization (backend, frontend, etc.)

### Task Lifecycle
```
available → claimed → in_progress → completed
                  ↓
              blocked/abandoned
```

### Conflict Detection
Tasks conflict if they:
1. Modify the same files (check task spec's "Files to Create/Modify")
2. Both have `backend` tag (may touch server/src/index.ts)
3. Both have `frontend` tag AND modify shared files (App.tsx, routes)

Safe parallel pairs: one backend + one frontend task.

## Workflows

### Single Task Execution
1. Read manifest, find highest priority available task
2. Claim task (update manifest status)
3. Read task file from `docs/planning/tasks/<file>`
4. Execute task (create/modify files per spec)
5. Run build verification (`npm run build`)
6. Update manifest to completed

### Parallel Execution (--parallel N)
1. **Acquire manifest lock** before reading
2. Read manifest, find N non-conflicting available tasks
3. Pre-claim all tasks in manifest (prevents race conditions)
4. **Release manifest lock** after claiming
5. Spawn N background agents via Task tool
6. Each agent works independently on its task
7. Monitor agent outputs for completion
8. **Acquire lock**, update manifest for completed tasks, **release lock**
9. Verify all builds pass

### Manifest Locking Protocol
To prevent race conditions when multiple agents access the manifest:

```bash
# Acquire lock (waits up to 10s if held by another agent)
npx ts-node scripts/manifest-lock.ts acquire <agent-id>

# Release lock when done
npx ts-node scripts/manifest-lock.ts release <agent-id>

# Check lock status
npx ts-node scripts/manifest-lock.ts status

# Force release stale lock (use with caution)
npx ts-node scripts/manifest-lock.ts force-release
```

**Lock Rules:**
- Always acquire lock before reading/modifying manifest
- Release lock immediately after changes are written
- Locks auto-expire after 60 seconds (stale lock protection)
- Lock file: `docs/planning/tasks/manifest.lock` (gitignored)

### Pipeline Check
1. Read manifest
2. Count by status: available, completed, blocked
3. Check if ideation needed (available < threshold)
4. Report pipeline health

### Debt Sweep Integration
Triggered every N cycles (default: 5) during continuous execution:

1. **Check cycle counter** - Track cycles since last debt sweep
2. **Pause execution** when counter hits debt-interval threshold
3. **Run debt sweep** - Scan codebase for new technical debt
4. **Fix eligible items** if `--debt-fix` level is set:
   - Only fix items with effort = trivial or low
   - Fix in severity order: critical → high → medium → low
   - Stop at specified severity level
5. **Update manifests** - `debt-manifest.json` and `debt-report.md`
6. **Report findings** - Show new debt, fixed items, remaining items
7. **Reset counter** and resume task execution

**Debt Sweep Trigger Logic:**
```
cycleCount = cycleCount + 1

if cycleCount >= debtInterval:
    cycleCount = 0
    runDebtSweep()
    
    if debtFixLevel:
        for item in debtItems.sortedBySeverity():
            if item.severity >= debtFixLevel and item.effort in ['trivial', 'low']:
                attemptAutoFix(item)
```

**Auto-Fixable Debt Categories:**
- Security: Remove debug logging of credentials
- Types: Add explicit return types to small functions
- Complexity: Extract obvious helper functions
- Dependencies: Update patch versions
- TODOs: Complete trivial TODOs with clear solutions

## Agent Output Format

All spawned agents MUST output this structured summary:

```
<!-- AGENT_SUMMARY_START -->
{
  "taskId": "<task-id>",
  "status": "completed|partial|failed|blocked",
  "filesCreated": ["<paths>"],
  "filesModified": ["<paths>"],
  "buildStatus": "passed|failed",
  "acceptanceCriteria": {"total": N, "met": N, "failed": N},
  "errors": [],
  "notes": "<summary>"
}
<!-- AGENT_SUMMARY_END -->
```

## Supporting Files

- [parallel-execution.md](parallel-execution.md) - Detailed parallel execution logic
- [manifest-schema.md](manifest-schema.md) - Task manifest structure
- [scripts/agent-status.sh](scripts/agent-status.sh) - Check running agent status

## Usage Examples

**Run single task:**
```
/dev-loop
```

**Run 2 tasks in parallel:**
```
/dev-loop --parallel 2
```

**Continuous with debt sweep every 3 cycles:**
```
/dev-loop --continuous --debt-interval 3
```

**Auto-fix high+ severity debt during continuous run:**
```
/dev-loop --continuous --debt-interval 5 --debt-fix high
```

**Focused feature work (skip debt sweeps):**
```
/dev-loop --continuous --no-debt-sweep
```

**Check status:**
```
/task-status
```

**Natural language (auto-detected):**
- "Let's knock out some tasks"
- "Run the dev loop"
- "What tasks are available?"
- "Execute P1 tasks in parallel"
- "Run tasks and clean up debt along the way"
- "Do a debt sweep every 3 tasks"