--- description: Autonomous goal-driven project driver. Reads GOAL.md, delegates to worker agents, iterates through orient-plan-execute-assess until all goals met or inextricably stuck. category: general --- flowchart TD _HEADER_[""]:::headerStyle classDef headerStyle fill:none,stroke:none subgraph _MAIN_[" "] %% Phase 0: Orient subgraph Orient["Phase 0: Orient"] GOAL_EXISTS{GOAL.md
Exists?} GOAL_EXISTS -->|No| SYNTHESIZE[Synthesize from
spec, ideas, README,
todo, trckr] SYNTHESIZE --> COMMIT_GOAL[Commit + Push
GOAL.md] COMMIT_GOAL --> READ_GOAL GOAL_EXISTS -->|Yes| READ_GOAL[Read GOAL.md] & READ_WORKLOG[Read WORKLOG.md] & BUILD_CTX[[build-context]] READ_GOAL & READ_WORKLOG & BUILD_CTX --> ASSESS_STATE[Assess Current State
vs Goal Phases] end %% Phase 1: Plan subgraph Plan["Phase 1: Plan"] ASSESS_STATE --> GAPS[Identify Gaps
goals vs current] GAPS --> RESEARCH_PLAN[Research Before Building
internet-researcher ∥ RTFM] RESEARCH_PLAN --> TASKS[Create Tasks
identify parallelism] TASKS --> WORKLOG_PLAN[Worklog: plan] WORKLOG_PLAN --> CHECKPOINT_PLAN[Commit + Push] end %% Heartbeat subgraph Heartbeat["Heartbeat (always running)"] REMINDER[reminder 10min] --> CHECK_WORKERS{Workers
Responsive?} CHECK_WORKERS -->|Yes| REMINDER CHECK_WORKERS -->|Unresponsive
2x nudge| KILL[Kill + Respawn
clearer instructions] KILL --> REMINDER end %% Phase 2: Execute subgraph Execute["Phase 2: Execute (parallel tracks)"] CHECKPOINT_PLAN --> SPAWN[Spawn Workers
per Task] SPAWN --> IMPL[[task-executor
Implementation]] & DATA[[general-purpose
Data + Content]] & WEB_RESEARCH[[internet-researcher
Research]] & VALIDATE[[code-verification-qa
Validation]] IMPL & DATA & WEB_RESEARCH & VALIDATE --> RESULTS[Collect Results] RESULTS --> WORKLOG_EXP[Worklog: results
+ analysis] WORKLOG_EXP --> CHECKPOINT_EXP[Commit + Push
max 30min gap] end %% Phase 3: Assess subgraph Assess["Phase 3: Assess"] CHECKPOINT_EXP --> REREAD[Re-read GOAL.md] REREAD --> RUN_TESTS[Run Full
Test Suite] RUN_TESTS --> CHECK_CRITERIA{Success Criteria
Met?} CHECK_CRITERIA -->|Phase done,
more phases| UPDATE_PHASE[Update GOAL.md
Phase Status] UPDATE_PHASE --> ASSESS_STATE CHECK_CRITERIA -->|Current phase
incomplete| ASSESS_STATE CHECK_CRITERIA -->|All phases done| FINAL_QA end %% Phase 4: Final QA subgraph FinalQA["Phase 4: Final QA"] FINAL_QA[[code-verification-qa
Comprehensive]] --> QA_RESULT{All Clear?} QA_RESULT -->|Issues found| ASSESS_STATE QA_RESULT -->|Pass| WORKLOG_DONE[Worklog: complete] WORKLOG_DONE --> FINAL_PUSH[Commit + Push] FINAL_PUSH --> DONE([Done]) end %% Blocked Path subgraph Blocked["When Blocked"] RESULTS --> BLOCKED_CHECK{Blocked?} BLOCKED_CHECK -->|Yes| DEEP_RESEARCH[Research Harder
internet-researcher ∥
RTFM ∥ ast-parsing] DEEP_RESEARCH --> ALT_APPROACH{Alternative
Approaches?} ALT_APPROACH -->|Yes, try B C D| SPAWN ALT_APPROACH -->|All exhausted| LOG_FAIL[Log to GOAL.md
Lessons Learned] LOG_FAIL --> STUCK_CHECK{Any Path
Forward?} STUCK_CHECK -->|Yes| SPAWN STUCK_CHECK -->|No| WORKLOG_STUCK[Worklog: stuck] WORKLOG_STUCK --> STUCK_PUSH[Commit + Push] STUCK_PUSH --> STUCK([Inextricably Stuck]) BLOCKED_CHECK -->|No| RESULTS end click GOAL_EXISTS "#" "**GOAL.md Exists?**\nCheck if the project has a GOAL.md at the root.\nThis is the authoritative document that defines what the project should become.\n\nIf missing, synthesize one from all available sources before proceeding." click SYNTHESIZE "#" "**Synthesize GOAL.md**\nCreate GOAL.md from all available sources:\n- `spec.md`, `ideas.txt`, `README.md`, `todo.txt`\n- `CLAUDE.md`, trckr issues\n\nIdentify the project's ultimate objective,\nbreak into dependency-ordered phases,\ndefine testable success criteria,\nenumerate all available resources." click READ_GOAL "#" "**Read GOAL.md**\nThe north star. Contains:\n- Phased goals with status markers\n- Success criteria (waypoints, not finish lines)\n- Available resources (compute, data, tools)\n- Lessons Learned (what works, what fails)\n\nEvery decision traces back to this document." click READ_WORKLOG "#" "**Read WORKLOG.md**\nUnderstand what's been tried:\n- Previous experiments and their results\n- Key decisions and rationale\n- Challenges and solutions\n- Current state assessment\n\nEntries are newest-first with timestamps." click BUILD_CTX "#" "**build-context**\nMap the codebase:\n- Directory structure and patterns\n- Libraries and frameworks used\n- Test infrastructure\n- How code is installed and run\n\nUpdates CLAUDE.md with findings." click ASSESS_STATE "#" "**Assess Current State**\nCompare GOAL.md phases against reality:\n- Which phases/sub-goals are done?\n- Which are in-progress?\n- Which are not started?\n- What's the critical path?\n\nThis is the re-entry point for the outer DRIVE loop." click GAPS "#" "**Identify Gaps**\nDiff goals vs current state:\n- What success criteria are unmet?\n- What's the current phase?\n- What's the critical-path sub-goal?\n- Which tasks can run in parallel?" click RESEARCH_PLAN "#" "**Research Before Building**\nDispatch research agents before any major decision:\n- `internet-researcher` for SOTA and best practices\n- `RTFM` for library documentation\n\nNever assume -- your training data has a cutoff.\nAlways check current state of the art first." click TASKS "#" "**Create Tasks**\nBreak current work into concrete tasks:\n- Each worker gets ONE specific task\n- Identify parallelizable tasks\n- Mark dependencies\n- Give step-by-step instructions, not vague goals" click REMINDER "#" "**Heartbeat: reminder 10min**\nNEVER let the heartbeat lapse.\nEvery 10 minutes:\n1. Check worker agents for output\n2. Nudge unresponsive workers (2x max)\n3. Kill and respawn if still stuck\n4. Update WORKLOG.md\n5. Set another reminder\n\nThis is the pulse of the workflow." click CHECK_WORKERS "#" "**Workers Responsive?**\nOn each heartbeat check:\n- Is each worker producing output?\n- Has any worker gone silent?\n- Are results quality or gibberish?\n\nUnresponsive after 2 nudges = kill and respawn." click KILL "#" "**Kill + Respawn**\nWorker unresponsive after 2 nudges.\nDon't wait -- kill and respawn with:\n- Clearer, more specific instructions\n- Smaller scope if the task was too large\n- Additional context from WORKLOG.md\n- Different approach if the original failed" click SPAWN "#" "**Spawn Workers**\nLaunch parallel workers across tracks:\n- Implementation: task-executor agents\n- Data/Content: general-purpose agents\n- Research: internet-researcher agents\n- Validation: code-verification-qa agents\n\nAlways have at least 2 tracks running simultaneously." click IMPL "#" "**Implementation Track**\nBuilding features, training models, running tests.\nUses `task-executor` or `general-purpose` worker agents.\n\nWorkers run on sonnet to save cost.\nOpus only for research-heavy agents." click DATA "#" "**Data + Content Track**\nGenerating data, processing files, migrations.\nUses `general-purpose` worker agents.\n\nRuns in parallel with implementation." click WEB_RESEARCH "#" "**Research Track**\nSOTA papers, library docs, community solutions.\nUses `internet-researcher` agents.\n\nAlways running to inform upcoming decisions." click VALIDATE "#" "**Validation Track**\nQA testing, benchmarking, evaluation.\nUses `code-verification-qa` agents.\n\nVerifies worker output actually works as claimed." click RESULTS "#" "**Collect Results**\nGather output from all parallel workers.\nFor each result:\n- Did it succeed or fail?\n- What metrics/outcomes?\n- Any unexpected findings?\n- What should change next?" click WORKLOG_EXP "#" "**Worklog: Results + Analysis**\nUpdate WORKLOG.md with timestamped entry:\n- What was done (bullet points)\n- Key decisions and rationale\n- Challenges and solutions\n- Concrete results (metrics, test outcomes)\n- Current state assessment\n\nNewest entries at the TOP of the file." click CHECKPOINT_EXP "#" "**Commit + Push Checkpoint**\nNever let more than 30 minutes pass without a checkpoint.\n- `git add` changed files\n- `git commit` with descriptive message\n- `git push`\n- Assign next task to worker" click REREAD "#" "**Re-read GOAL.md**\nYour own work may have updated it.\nCheck for:\n- New lessons learned\n- Updated phase statuses\n- Refined sub-goals\n- Changed success criteria" click RUN_TESTS "#" "**Run Full Test Suite**\nVerify the current state of the codebase.\nAll tests must pass -- 99% is not enough.\nUse the project's test infrastructure." click CHECK_CRITERIA "#" "**Success Criteria Met?**\nCheck every success criterion from GOAL.md:\n- Phase criteria = waypoints, not finish lines\n- Hitting them means 'good, keep going'\n- Update phase status markers\n\nThree outcomes:\n1. Current phase incomplete -> re-plan\n2. Phase done, more phases -> advance\n3. All phases done -> Final QA" click UPDATE_PHASE "#" "**Update GOAL.md Phase Status**\nMark completed phases and advance:\n- Change status marker to DONE\n- Advance to next phase\n- Loop back to Orient to re-plan" click FINAL_QA "#" "**Final QA**\nDispatch `code-verification-qa` agent for comprehensive verification.\n- Run full test suite\n- Check every success criterion\n- Verify all phases complete\n\nIf issues found, loop back. If clear, we're done." click QA_RESULT "#" "**All Clear?**\nFinal QA verdict:\n- Pass: all success criteria met, tests green\n- Issues: loop back to fix and re-assess" click DONE "#" "**Done**\nAll GOAL.md goals are met.\n- Write final worklog entry\n- Commit and push\n- Success criteria are waypoints though --\n there's always the 'keep going' phase" click DEEP_RESEARCH "#" "**Research Harder**\nWhen blocked, exhaust all research avenues:\n- Multiple internet-researcher agents with different angles\n- RTFM for all relevant libraries\n- ast-parsing to trace execution paths\n- GitHub issues, Stack Overflow, community\n- Minimal reproduction to isolate the problem" click ALT_APPROACH "#" "**Alternative Approaches?**\nIf approach A fails, try B, C, D.\n- Check for misunderstandings\n- Re-read GOAL.md, verify assumptions\n- Try completely different architecture\n- Simplify the problem" click LOG_FAIL "#" "**Log to GOAL.md Lessons Learned**\nAdd to 'What fails' section so it's never retried:\n- What was tried\n- Why it failed\n- What was learned\n\nThis prevents future iterations from repeating mistakes." click STUCK "#" "**Inextricably Stuck**\nThe ONE reason to stop:\nEvery research avenue, every tool, every alternative approach\nhas been exhausted and there is genuinely nothing left to try.\n\nNot 'this is hard.' Not 'this might take a while.'\nThe ONLY terminal condition." classDef orient fill:#d1ecf1,stroke:#7ec8d8 classDef plan fill:#e8daef,stroke:#b07cc6 classDef heartbeat fill:#fff3cd,stroke:#f0c040 classDef execute fill:#dfe6ff,stroke:#5b7bce classDef assess fill:#fff3cd,stroke:#f0c040 classDef finalqa fill:#d4edda,stroke:#5cb85c classDef blocked fill:#f8d7da,stroke:#e06070 classDef approved fill:#d4edda,stroke:#5cb85c classDef stuck fill:#f8d7da,stroke:#e06070 class GOAL_EXISTS,SYNTHESIZE,COMMIT_GOAL,READ_GOAL,READ_WORKLOG,BUILD_CTX,ASSESS_STATE orient class GAPS,RESEARCH_PLAN,TASKS,WORKLOG_PLAN,CHECKPOINT_PLAN plan class REMINDER,CHECK_WORKERS,KILL heartbeat class SPAWN,IMPL,DATA,WEB_RESEARCH,VALIDATE,RESULTS,WORKLOG_EXP,CHECKPOINT_EXP execute class REREAD,RUN_TESTS,CHECK_CRITERIA,UPDATE_PHASE assess class FINAL_QA,QA_RESULT,WORKLOG_DONE,FINAL_PUSH finalqa class DONE approved class BLOCKED_CHECK,DEEP_RESEARCH,ALT_APPROACH,LOG_FAIL,STUCK_CHECK,WORKLOG_STUCK,STUCK_PUSH blocked class STUCK stuck end style _MAIN_ fill:none,stroke:none,padding:0 _HEADER_ ~~~ _MAIN_