ToDone Task System

An autonomous task delegation system where a cron trigger monitors tasks.md, distributes tasks to isolated git worktrees, and agents report back on completion.

How It Works

sequenceDiagram
    participant Human
    participant tasks.md
    participant Cron as trigger_cron_todone.py
    participant Agent as ADW Agent
    participant Git as Git Worktree

    Human->>tasks.md: Add task [] to worktree section
    Cron->>tasks.md: Poll every N seconds
    Cron->>tasks.md: Mark [in progress, adw_id]
    Cron->>Git: Create sparse worktree
    Cron->>Agent: Spawn subprocess
    Agent->>Git: Execute task
    Agent->>tasks.md: Write [done, commit] or [failed]
    Agent->>Human: Report complete

1. Human adds tasks to tasks.md grouped by worktree
2. adw_trigger_cron_todone.py polls every N seconds for eligible tasks
3. Trigger marks tasks in-progress then spawns a workflow subprocess
4. Agent executes the task in an isolated git worktree (trees/{worktree_name}/)
5. Agent calls /update_task to write success or failure

Task Status State Machine

[]  ──────────────────┐
[blocked] (unblocked) ─┼──> [in progress] ──> [done]
                       │                  └──> [failed]

Status	Meaning
[]	Not started (ready for pickup)
[blocked]	Eligible only when ALL tasks above it in the same worktree are done
[in progress, adw_id]	Currently running
[done, commit, adw_id]	Success with git commit hash
[failed, adw_id]	Failed

tasks.md Format

## Git Worktree feature-auth

[] Add OAuth2 login {opus}
[] Add password reset flow
[blocked] Add MFA support

## Git Worktree data-pipeline

[] Add CSV import endpoint {adw_plan_implement_update_task}
[] Add data validation layer

Tag-Based Routing

Tasks carry inline tags {tag1, tag2} that control model and workflow selection:

Tag	Effect
{opus}	Use claude-opus model
{sonnet}	Use claude-sonnet model (default)
{adw_plan_implement_update_task}	3-phase: /plan → /implement → /update_task
(no tag)	2-phase: /build → /update_task

Quick Start

# 1. Add tasks to tasks.md
echo "## Git Worktree feature-auth\n[] Add OAuth2 login {opus}" >> tasks.md

# 2. Run the cron trigger (polls every 5 seconds)
uv run adws/adw_triggers/adw_trigger_cron_todone.py

# 3. Or run once and exit
uv run adws/adw_triggers/adw_trigger_cron_todone.py --once

# 4. Dry run (no changes, just logs what would run)
uv run adws/adw_triggers/adw_trigger_cron_todone.py --dry-run

Workflow Files

File	Phases	Use For
adw_build_update_task.py	/build → /update_task	Simple tasks (CSV rows, small fixes)
adw_plan_implement_update_task.py	/plan → /implement → /update_task	Complex tasks (new features, models)
adw_triggers/adw_trigger_cron_todone.py	Orchestrator	Monitors tasks.md, spawns subprocesses

Slash Commands

Command	Purpose
/process_tasks	Analyze tasks.md → return eligible tasks as JSON
/init_worktree worktree_name target_dir	Create sparse-checkout git worktree
/mark_in_progress file worktree task adw_id	Update [] → [in progress, adw_id]
/update_task adw_id worktree task status commit error	Update to done or failed
/build adw_id task	Implement task directly (no planning)
/plan adw_id task	Create plan in specs/plan-{adw_id}-*.md
/clean_worktree worktree_name	Remove worktree and its branch

Data Models

From adw_modules/data_models.py:

• Task — Single task with status, adw_id, commit_hash, tags, worktree_name
• Worktree — Section in tasks.md; get_eligible_tasks() implements blocking logic
• SystemTag — Enum of recognized tags; helpers for extracting model and workflow
• ProcessTasksResponse — Parsed output from /process_tasks
• TaskUpdate — Validates success requires commit_hash
• WorkflowState — Tracks plan/implement/update phases
• CronTriggerConfig — polling_interval, dry_run, max_concurrent_tasks