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 → (auto-purged)
                  ↓
              blocked/abandoned

Automatic Manifest Cleanup

Completed tasks are automatically purged from the manifest to keep it lean and manageable. This happens:

• After each dev-loop cycle completes
• When updating a task status to "completed"

Cleanup preserves:

• Tasks with status: available, claimed, in_progress, blocked, abandoned
• All metadata and schema configuration

Cleanup removes:

• Tasks with status: completed

This keeps the manifest focused on actionable work. Completed task specs remain in docs/planning/tasks/ for historical reference.

Cleanup implementation: When writing the manifest after marking a task completed, filter out all tasks with "status": "completed" before saving. Keep all other tasks and the schema configuration intact.

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
7. Purge completed tasks from manifest (cleanup step)

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:

# 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)

Manifest Validation

Before executing any tasks, validate the manifest structure:

npx tsx scripts/validate-manifest.ts

If validation fails, fix the issues before proceeding. Common validation errors:

• Invalid task ID format (should be G{number}-{slug})
• Missing required fields (id, title, file, priority, status)
• Invalid status/priority values
• Dependencies referencing non-existent tasks
• File name not matching task ID

The manifest schema is defined at docs/planning/tasks/manifest.schema.json.

Pipeline Check

1. Validate manifest (fail fast if invalid)
2. Read manifest, 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 - Detailed parallel execution logic
• manifest-schema.md - Task manifest structure
• 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"