From e5f2255b086163d338433c7496e3acaca96fef22 Mon Sep 17 00:00:00 2001 From: omigamedev Date: Sun, 14 Jun 2026 13:52:27 +0200 Subject: [PATCH] Update delegation workflow to coordinator-workers --- AGENTS.md | 7 +- docs/modernization/director-workflow.md | 227 ++++++++++-------------- 2 files changed, 97 insertions(+), 137 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 3798f87..270aca1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,7 +20,7 @@ Read these first: - `docs/modernization/capability-map.md` - behavior that must be preserved. - `docs/modernization/build-inventory.md` - current build/component inventory. - `docs/modernization/tasks.md` - measurable task tracker and scorecard. -- `docs/modernization/director-workflow.md` - multi-agent director/captain +- `docs/modernization/director-workflow.md` - multi-agent coordinator/worker workflow; use only when the user asks for subagents or delegation. - `docs/adr/0001-modernization-boundaries.md` - component boundary decisions. @@ -41,8 +41,9 @@ Read these first: modernization path. - Use `apply_patch` for manual source/doc edits. - For delegated work, follow `docs/modernization/director-workflow.md`: the - director keeps integration locally, assigns `gpt-5.4` captains to coherent - task groups, and uses lighter workers only for bounded disjoint subtasks. + coordinator keeps integration locally, assigns direct worker tasks, uses + `gpt-5.3-codex-spark` workers by default, and gives them the exact project + context needed so they do not spend tokens re-reading repo docs. ## Build And Test diff --git a/docs/modernization/director-workflow.md b/docs/modernization/director-workflow.md index 3aa546a..4281f37 100644 --- a/docs/modernization/director-workflow.md +++ b/docs/modernization/director-workflow.md @@ -1,203 +1,160 @@ -# Modernization Director Workflow +# Modernization Coordinator Workflow Status: live -Last updated: 2026-06-12 +Last updated: 2026-06-14 Use this workflow when the user explicitly asks for subagents, delegation, a -director, captains, or parallel agent work. Do not spawn subagents just because -a task is complex. The default is still one agent executing one task from +coordinator, or parallel agent work. Do not spawn subagents just because a task +is complex. The default is still one agent executing one task from `docs/modernization/tasks.md`. +This file keeps the historical path name `director-workflow.md`, but the active +model is now one coordinator managing workers directly. There is no captain +layer. + ## Goals -- Save main-thread tokens by keeping long exploration and simple edits out of - the director context. -- Use stronger models only where they change the outcome. +- Save main-thread tokens by keeping implementation and focused lookup out of + the coordinator context. - Keep each implementation slice measurable, validated, committed, and pushed. -- Avoid merge conflicts by giving every agent a disjoint task and file scope. -- Keep teams rolling: when one team finishes, integrate or park its result and - start the next disjoint team without waiting for every other team to finish. -- Prefer parallel execution whenever scopes are disjoint: run multiple teams at - once, and give each team 2 or 3 workers when the work can be split cleanly. +- Avoid merge conflicts by giving every worker a disjoint task and file scope. +- Keep workers stateless between tasks: when a worker finishes, integrate or + reject the result, then clear that worker context before the next assignment. +- Keep prompts dense with the exact project/task context workers need so they do + not spend tokens re-reading repo docs or re-parsing broad areas. - Keep communication terse: no fillers, no cheerleading, no narrative padding. Use direct technical wording only. ## Roles -### Director +### Coordinator -The director is the main agent in the user thread. The director owns: +The coordinator is the main agent in the user thread. The coordinator owns: - choosing the task group from `docs/modernization/tasks.md` - deciding whether delegation is worth the coordination cost -- spawning one `gpt-5.4` captain per independent task group, including - multiple teams when scopes are disjoint +- splitting work into direct worker-sized tasks +- packaging the exact context each worker needs +- spawning workers and explorers directly - integrating returned changes - running final validation - updating docs/debt/tasks - committing and pushing the verified slice -- resetting conversation context after the slice when practical +- resetting worker context after each completed or rejected task -The director should keep local work minimal. It should not implement production -changes unless a required integration fix is smaller than another delegation -round. Prefer giving captains ownership of implementation, focused validation, -and worker coordination, then use the director context only for scope selection, -conflict review, final validation, docs/task updates, commits, and pushes. +The coordinator should keep local work minimal. It may do a quick blocking +check before delegation, such as reading task rows, checking git status, or +confirming that two scopes do not overlap. If the next action is substantive +code or test work, delegate it directly to a worker whenever the scope can be +made clear. -The director may do a quick local blocking check before delegation, such as -reading task rows, checking git status, or confirming that two scopes do not -overlap. If the next action is substantive code or test work, delegate it to a -captain or worker whenever the scope can be made clear. +The coordinator must front-load context. Workers should not be told to "read +the roadmap" or "inspect the repo" unless that is the task. The coordinator is +responsible for extracting and passing: -### Team Captain - -Use `gpt-5.4` for each captain. A captain owns one coherent task group and is -responsible for domain-level planning, for example: - -- renderer/export boundary -- legacy adapter retirement -- platform/package parity -- UI lifetime -- dependency cleanup -- test/hardening work - -The captain owns implementation for its assigned task group. A team should be a -captain plus multiple workers when the work can be split into disjoint files. -The captain turns one task-group objective, or a small coherent run of adjacent -task rows, into 2 or 3 smaller disjoint subtasks when possible, spawns or -requests workers when useful, reviews their changes, runs focused validation -when cheap, and returns an integration-ready result. If nested subagents are -available, the captain may spawn workers and continue through the next -compatible subtask after each worker returns. If nested subagents are not -available in the current surface, the captain returns a worker plan and the -director performs the second-level spawns without taking over implementation. - -The captain must not edit broad shared files unless assigned. The captain must -not rewrite the task tracker or roadmap except for a requested status note. +- task ids and done checks +- debt ids and removal conditions that matter +- exact write scope and allowed read scope +- required validation commands +- relevant file paths, code references, and current behavior notes +- any repo rules or user constraints that materially affect the task ### Workers And Explorers Workers perform bounded edits in assigned files. Explorers answer specific questions and should usually not edit files. +Workers do not own repo discovery. They start from the coordinator-provided +context packet and stay inside the assigned scope unless they hit a blocker that +requires a narrow follow-up question. + Every worker and explorer must be told: - this repository may have other agents working in parallel - do not revert or overwrite unrelated changes - stay inside the assigned scope -- focus on the assigned task first; do not start by reading unrelated docs or - broad repository areas unless the task explicitly requires it +- use the supplied task context first instead of broad repo/doc review - report changed files, validation run, and blockers ## Model Selection | Work Type | Model | Reasoning Effort | Use | | --- | --- | --- | --- | -| Director orchestration and integration | `gpt-5.4-mini` | `low` or `medium` | Scope selection, task routing, conflict checks, validation, docs/debt updates, commits, pushes. | -| Team captain for a domain slice | `gpt-5.4` | `medium` default, `high` for renderer/platform architecture | Split a broad domain slice into worker-sized tasks, supervise workers, review results, and integrate changes. | -| Risky implementation with cross-file C++ behavior | `gpt-5.4` | `medium` or `high` | Code changes touching contracts, build graph, or live adapters. | -| Bounded implementation in known files | `gpt-5.4-mini` | `medium` | Localized tests, simple adapters, docs/debt updates, small refactors. | -| Fast lookup or inventory | `gpt-5.3-codex-spark` | `low` or `medium` | `rg` inventory, file ownership map, simple grep-based answers. | -| Mechanical docs cleanup | `gpt-5.3-codex-spark` | `low` | Formatting, table updates, command list normalization. | -| Ambiguous strategy or failed captain escalation | `gpt-5.5` | inherited or `high` | Only when cheaper models are likely to make architectural mistakes. | +| Coordinator orchestration and integration | inherited main-thread model or `gpt-5.4-mini` | `low` or `medium` | Scope selection, task routing, conflict checks, validation, docs/debt updates, commits, pushes. | +| Direct worker coding task | `gpt-5.3-codex-spark` | `medium` | Bounded implementation in known files with coordinator-supplied context. | +| Direct worker lookup or inventory | `gpt-5.3-codex-spark` | `low` or `medium` | `rg` inventory, file ownership map, simple grep-based answers. | +| Mechanical docs cleanup | `gpt-5.3-codex-spark` | `low` | Formatting, table updates, command normalization. | +| Coordinator-only escalation | inherited higher model only when explicitly justified | inherited | Resolve architecture ambiguity, conflict integration, or task decomposition failures without adding a captain layer. | -Prefer the inherited model unless the user requested this director workflow or -there is a clear task-specific reason to override. In this workflow, the user -has requested `gpt-5.4` team leads, so use that override for captains and keep -the director on `gpt-5.4-mini` for orchestration unless a higher-reasoning -escalation is justified. +Workers default to `gpt-5.3-codex-spark`. If a task looks too broad or risky +for that model, the coordinator should decompose it further or keep the narrow +integration step locally instead of inserting an extra management tier. -## Token Discipline +## Context And Token Discipline - Use `fork_context=false` by default. Pass the task id, relevant files, debt ids, validation commands, and only the necessary excerpts. - Use `fork_context=true` only when prior conversation details are essential and - not already in repo docs. -- Do not paste large logs into prompts. Point agents at log paths and ask for + not already captured in the worker prompt. +- Do not paste large logs into prompts. Point workers at log paths and ask for the smallest relevant excerpt. -- Do not ask captains or workers to "read the roadmap" generally. Name the - exact task row and debt ids. -- Keep subagent prompts under about 250 words for explorers and 500 words for - workers/captains unless the task truly needs more. +- Do not ask workers to broadly read `AGENTS.md`, the roadmap, or the debt log. + Summarize the exact rules and rows they need. +- Keep worker prompts compact but complete. Shorter is good only if it still + removes the need for worker-side repo rediscovery. - Ask for compact final reports: changed files, result, validation, blockers, next recommendation. -- Keep final reports minimal and technical. -- Close completed agents after their results are integrated or rejected. -- Prefer the smallest number of teams that keeps disjoint work moving. Multiple - captains are appropriate when task rows have non-overlapping write scopes and - can validate independently. Avoid many agents in one file family, but do use - multiple teams when the scopes are disjoint and the work can advance in - parallel. -- Do not synchronize all teams at a barrier unless validation or merge risk - requires it. Use rolling integration: wait for whichever team finishes first, - process that result, then immediately start another disjoint team if ready - work remains. +- Close completed workers after their results are integrated or rejected. +- Prefer the smallest number of concurrent workers that keeps disjoint work + moving. +- Use rolling integration: wait for whichever worker finishes first, process the + result, then launch the next disjoint worker with a fresh context window. ## Delegation Flow -1. Director picks two or more `Ready` tasks from +1. Coordinator picks one or more `Ready` tasks from `docs/modernization/tasks.md` with disjoint write scopes. -2. Director assigns each independent task group to a `gpt-5.4` captain, with - preference for 2 or 3 worker subtasks per team when the scope can be split - cleanly. -3. Captains implement directly or coordinate workers/explorers for disjoint - subtasks, and may continue through a coherent sequence of adjacent tasks - within the assigned scope. -4. Captains run focused validation when cheap and return changed files, - validation, blockers, and integration notes. -5. Director waits for whichever team finishes first, reviews for scope - conflicts, integrates returned changes, and starts the next disjoint team - while other teams keep running. -6. Director runs the listed validation command or the quiet checkpoint wrapper - for each integrated slice. -7. Director updates `tasks.md`, `debt.md`, and `roadmap.md` if tasks moved. -8. Director commits and pushes verified slices incrementally. +2. Coordinator splits each task into direct worker-sized units. +3. Coordinator prepares a context packet for each worker with the exact task + requirements, file scope, validation commands, and relevant project details. +4. Coordinator assigns the task directly to a `gpt-5.3-codex-spark` worker or + explorer. +5. Worker returns changed files, validation, blockers, and any narrow + integration notes. +6. Coordinator reviews for scope conflicts, integrates the result, and clears + that worker context before assigning the next task. +7. Coordinator runs the listed validation command or the quiet checkpoint + wrapper for each integrated slice. +8. Coordinator updates `tasks.md`, `debt.md`, and `roadmap.md` if task state or + documented behavior moved. +9. Coordinator commits and pushes verified slices incrementally. -## Director Prompt Template For A Captain +## Coordinator Prompt Template For A Worker ```text -You are the gpt-5.4 team captain for the task group in PanoPainter. +You are a `gpt-5.3-codex-spark` worker on PanoPainter. Other agents may be +editing nearby files; do not revert unrelated changes. Task source: docs/modernization/tasks.md task(s) . -Debt ids: . -Assigned scope: . -Validation: . - Goal: . - -Own this task group through planning and implementation. Build a small team of -`gpt-5.4-mini` workers for disjoint subtasks when possible, review their -outputs, and keep looping through the assigned coherent task sequence until the -scope is done, blocked, or no longer safe to continue. Use `gpt-5.4` for broad -domain planning, interface decisions, and risky C++ behavior changes. Keep -tasks small enough to validate. Do not edit outside the assigned scope. Other -agents may be working in parallel; do not revert unrelated changes. - -Return: -- recommended worker tasks with model choice and file scope -- completed edits or the exact blocker preventing them -- focused validation run and result -- risks/blockers -- integration notes for the director -``` - -## Captain Prompt Template For A Worker - -```text -You are a worker on PanoPainter. Other agents may be editing nearby files; do -not revert unrelated changes. - -Task: . -Model fit: . +Done checks: . +Debt ids: . Write scope: . Read scope: . Validation: . +Repo constraints you must follow: +- + +Current context you should rely on instead of broad repo/doc review: +- +- +- + Make the smallest behavior-preserving change that satisfies the done checks. Do not spend tokens on broad document review or inventory outside the assigned -scope unless the task requires it. -Update tests/docs only if listed. If the task is larger than expected, stop and -report the split instead of broadening scope. +scope unless the task explicitly requires it. If the task is larger than +expected, stop and report the split instead of broadening scope. Final report: - files changed @@ -206,13 +163,14 @@ Final report: - blockers or follow-up ``` -## Explorer Prompt Template +## Coordinator Prompt Template For An Explorer ```text Answer one codebase question for PanoPainter. Question: . Search scope: . +Relevant context: . Use compiler-aware navigation if this depends on C++ symbols. Do not edit files. @@ -229,5 +187,6 @@ Return only: - Focused validation for the task passed or the failure is documented. - `docs/modernization/debt.md` changed when debt was narrowed or closed. - `docs/modernization/tasks.md` score changed only for `Done` tasks. +- Each worker result was integrated before that worker context was reused. - The commit contains one coherent slice. - The branch was pushed.