omar/panopainter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update delegation workflow to coordinator-workers

Browse Source
This commit is contained in:
omigamedev
2026-06-14 13:52:27 +02:00
parent c9fb9fa986
commit e5f2255b08
2 changed files with 97 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
AGENTS.md
View File

@@ -20,7 +20,7 @@ Read these first:
- `docs/modernization/capability-map.md` - behavior that must be preserved. - `docs/modernization/capability-map.md` - behavior that must be preserved.
- `docs/modernization/build-inventory.md` - current build/component inventory. - `docs/modernization/build-inventory.md` - current build/component inventory.
- `docs/modernization/tasks.md` - measurable task tracker and scorecard. - `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. workflow; use only when the user asks for subagents or delegation.
- `docs/adr/0001-modernization-boundaries.md` - component boundary decisions. - `docs/adr/0001-modernization-boundaries.md` - component boundary decisions.
@@ -41,8 +41,9 @@ Read these first:
modernization path. modernization path.
- Use `apply_patch` for manual source/doc edits. - Use `apply_patch` for manual source/doc edits.
- For delegated work, follow `docs/modernization/director-workflow.md`: the - For delegated work, follow `docs/modernization/director-workflow.md`: the
director keeps integration locally, assigns `gpt-5.4` captains to coherent coordinator keeps integration locally, assigns direct worker tasks, uses
task groups, and uses lighter workers only for bounded disjoint subtasks. `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 ## Build And Test

227
docs/modernization/director-workflow.md
View File

@@ -1,203 +1,160 @@
# Modernization Director Workflow # Modernization Coordinator Workflow
Status: live Status: live
Last updated: 2026-06-12 Last updated: 2026-06-14
Use this workflow when the user explicitly asks for subagents, delegation, a Use this workflow when the user explicitly asks for subagents, delegation, a
director, captains, or parallel agent work. Do not spawn subagents just because coordinator, or parallel agent work. Do not spawn subagents just because a task
a task is complex. The default is still one agent executing one task from is complex. The default is still one agent executing one task from
`docs/modernization/tasks.md`. `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 ## Goals
- Save main-thread tokens by keeping long exploration and simple edits out of - Save main-thread tokens by keeping implementation and focused lookup out of
the director context. the coordinator context.
- Use stronger models only where they change the outcome.
- Keep each implementation slice measurable, validated, committed, and pushed. - Keep each implementation slice measurable, validated, committed, and pushed.
- Avoid merge conflicts by giving every agent a disjoint task and file scope. - Avoid merge conflicts by giving every worker a disjoint task and file scope.
- Keep teams rolling: when one team finishes, integrate or park its result and - Keep workers stateless between tasks: when a worker finishes, integrate or
start the next disjoint team without waiting for every other team to finish. reject the result, then clear that worker context before the next assignment.
- Prefer parallel execution whenever scopes are disjoint: run multiple teams at - Keep prompts dense with the exact project/task context workers need so they do
once, and give each team 2 or 3 workers when the work can be split cleanly. not spend tokens re-reading repo docs or re-parsing broad areas.
- Keep communication terse: no fillers, no cheerleading, no narrative padding. - Keep communication terse: no fillers, no cheerleading, no narrative padding.
Use direct technical wording only. Use direct technical wording only.
## Roles ## 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` - choosing the task group from `docs/modernization/tasks.md`
- deciding whether delegation is worth the coordination cost - deciding whether delegation is worth the coordination cost
- spawning one `gpt-5.4` captain per independent task group, including - splitting work into direct worker-sized tasks
multiple teams when scopes are disjoint - packaging the exact context each worker needs
- spawning workers and explorers directly
- integrating returned changes - integrating returned changes
- running final validation - running final validation
- updating docs/debt/tasks - updating docs/debt/tasks
- committing and pushing the verified slice - 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 The coordinator should keep local work minimal. It may do a quick blocking
changes unless a required integration fix is smaller than another delegation check before delegation, such as reading task rows, checking git status, or
round. Prefer giving captains ownership of implementation, focused validation, confirming that two scopes do not overlap. If the next action is substantive
and worker coordination, then use the director context only for scope selection, code or test work, delegate it directly to a worker whenever the scope can be
conflict review, final validation, docs/task updates, commits, and pushes. made clear.
The director may do a quick local blocking check before delegation, such as The coordinator must front-load context. Workers should not be told to "read
reading task rows, checking git status, or confirming that two scopes do not the roadmap" or "inspect the repo" unless that is the task. The coordinator is
overlap. If the next action is substantive code or test work, delegate it to a responsible for extracting and passing:
captain or worker whenever the scope can be made clear.
### Team Captain - task ids and done checks
- debt ids and removal conditions that matter
Use `gpt-5.4` for each captain. A captain owns one coherent task group and is - exact write scope and allowed read scope
responsible for domain-level planning, for example: - required validation commands
- relevant file paths, code references, and current behavior notes
- renderer/export boundary - any repo rules or user constraints that materially affect the task
- 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.
### Workers And Explorers ### Workers And Explorers
Workers perform bounded edits in assigned files. Explorers answer specific Workers perform bounded edits in assigned files. Explorers answer specific
questions and should usually not edit files. 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: Every worker and explorer must be told:
- this repository may have other agents working in parallel - this repository may have other agents working in parallel
- do not revert or overwrite unrelated changes - do not revert or overwrite unrelated changes
- stay inside the assigned scope - stay inside the assigned scope
- focus on the assigned task first; do not start by reading unrelated docs or - use the supplied task context first instead of broad repo/doc review
broad repository areas unless the task explicitly requires it
- report changed files, validation run, and blockers - report changed files, validation run, and blockers
## Model Selection ## Model Selection
| Work Type | Model | Reasoning Effort | Use | | 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. | | 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. |
| 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. | | Direct worker coding task | `gpt-5.3-codex-spark` | `medium` | Bounded implementation in known files with coordinator-supplied context. |
| Risky implementation with cross-file C++ behavior | `gpt-5.4` | `medium` or `high` | Code changes touching contracts, build graph, or live adapters. | | Direct worker lookup or inventory | `gpt-5.3-codex-spark` | `low` or `medium` | `rg` inventory, file ownership map, simple grep-based answers. |
| Bounded implementation in known files | `gpt-5.4-mini` | `medium` | Localized tests, simple adapters, docs/debt updates, small refactors. | | Mechanical docs cleanup | `gpt-5.3-codex-spark` | `low` | Formatting, table updates, command normalization. |
| Fast lookup or inventory | `gpt-5.3-codex-spark` | `low` or `medium` | `rg` inventory, file ownership map, simple grep-based answers. | | 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. |
| 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. |
Prefer the inherited model unless the user requested this director workflow or Workers default to `gpt-5.3-codex-spark`. If a task looks too broad or risky
there is a clear task-specific reason to override. In this workflow, the user for that model, the coordinator should decompose it further or keep the narrow
has requested `gpt-5.4` team leads, so use that override for captains and keep integration step locally instead of inserting an extra management tier.
the director on `gpt-5.4-mini` for orchestration unless a higher-reasoning
escalation is justified.
## Token Discipline ## Context And Token Discipline
- Use `fork_context=false` by default. Pass the task id, relevant files, debt - Use `fork_context=false` by default. Pass the task id, relevant files, debt
ids, validation commands, and only the necessary excerpts. ids, validation commands, and only the necessary excerpts.
- Use `fork_context=true` only when prior conversation details are essential and - Use `fork_context=true` only when prior conversation details are essential and
not already in repo docs. not already captured in the worker prompt.
- Do not paste large logs into prompts. Point agents at log paths and ask for - Do not paste large logs into prompts. Point workers at log paths and ask for
the smallest relevant excerpt. the smallest relevant excerpt.
- Do not ask captains or workers to "read the roadmap" generally. Name the - Do not ask workers to broadly read `AGENTS.md`, the roadmap, or the debt log.
exact task row and debt ids. Summarize the exact rules and rows they need.
- Keep subagent prompts under about 250 words for explorers and 500 words for - Keep worker prompts compact but complete. Shorter is good only if it still
workers/captains unless the task truly needs more. removes the need for worker-side repo rediscovery.
- Ask for compact final reports: changed files, result, validation, blockers, - Ask for compact final reports: changed files, result, validation, blockers,
next recommendation. next recommendation.
- Keep final reports minimal and technical. - Close completed workers after their results are integrated or rejected.
- Close completed agents after their results are integrated or rejected. - Prefer the smallest number of concurrent workers that keeps disjoint work
- Prefer the smallest number of teams that keeps disjoint work moving. Multiple moving.
captains are appropriate when task rows have non-overlapping write scopes and - Use rolling integration: wait for whichever worker finishes first, process the
can validate independently. Avoid many agents in one file family, but do use result, then launch the next disjoint worker with a fresh context window.
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.
## Delegation Flow ## 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. `docs/modernization/tasks.md` with disjoint write scopes.
2. Director assigns each independent task group to a `gpt-5.4` captain, with 2. Coordinator splits each task into direct worker-sized units.
preference for 2 or 3 worker subtasks per team when the scope can be split 3. Coordinator prepares a context packet for each worker with the exact task
cleanly. requirements, file scope, validation commands, and relevant project details.
3. Captains implement directly or coordinate workers/explorers for disjoint 4. Coordinator assigns the task directly to a `gpt-5.3-codex-spark` worker or
subtasks, and may continue through a coherent sequence of adjacent tasks explorer.
within the assigned scope. 5. Worker returns changed files, validation, blockers, and any narrow
4. Captains run focused validation when cheap and return changed files, integration notes.
validation, blockers, and integration notes. 6. Coordinator reviews for scope conflicts, integrates the result, and clears
5. Director waits for whichever team finishes first, reviews for scope that worker context before assigning the next task.
conflicts, integrates returned changes, and starts the next disjoint team 7. Coordinator runs the listed validation command or the quiet checkpoint
while other teams keep running. wrapper for each integrated slice.
6. Director runs the listed validation command or the quiet checkpoint wrapper 8. Coordinator updates `tasks.md`, `debt.md`, and `roadmap.md` if task state or
for each integrated slice. documented behavior moved.
7. Director updates `tasks.md`, `debt.md`, and `roadmap.md` if tasks moved. 9. Coordinator commits and pushes verified slices incrementally.
8. Director commits and pushes verified slices incrementally.
## Director Prompt Template For A Captain ## Coordinator Prompt Template For A Worker
```text ```text
You are the gpt-5.4 team captain for the <group> 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) <TASK-ID-LIST>. Task source: docs/modernization/tasks.md task(s) <TASK-ID-LIST>.
Debt ids: <DEBT-LIST>.
Assigned scope: <FILES/DIRS>.
Validation: <COMMANDS>.
Goal: <ONE PARAGRAPH>. Goal: <ONE PARAGRAPH>.
Done checks: <DONE-CHECKS>.
Own this task group through planning and implementation. Build a small team of Debt ids: <DEBT-LIST>.
`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: <WORKER-TASK>.
Model fit: <WHY THIS MODEL IS ENOUGH>.
Write scope: <FILES/DIRS ONLY>. Write scope: <FILES/DIRS ONLY>.
Read scope: <FILES/DIRS>. Read scope: <FILES/DIRS>.
Validation: <COMMANDS>. Validation: <COMMANDS>.
Repo constraints you must follow:
- <ONLY THE RELEVANT RULES>
Current context you should rely on instead of broad repo/doc review:
- <CURRENT BEHAVIOR NOTE>
- <RELEVANT FILE OR SYMBOL NOTE>
- <WHY THIS SLICE IS SAFE / WHAT MUST NOT CHANGE>
Make the smallest behavior-preserving change that satisfies the done checks. Make the smallest behavior-preserving change that satisfies the done checks.
Do not spend tokens on broad document review or inventory outside the assigned Do not spend tokens on broad document review or inventory outside the assigned
scope unless the task requires it. scope unless the task explicitly requires it. If the task is larger than
Update tests/docs only if listed. If the task is larger than expected, stop and expected, stop and report the split instead of broadening scope.
report the split instead of broadening scope.
Final report: Final report:
- files changed - files changed
@@ -206,13 +163,14 @@ Final report:
- blockers or follow-up - blockers or follow-up
``` ```
## Explorer Prompt Template ## Coordinator Prompt Template For An Explorer
```text ```text
Answer one codebase question for PanoPainter. Answer one codebase question for PanoPainter.
Question: <QUESTION>. Question: <QUESTION>.
Search scope: <FILES/DIRS>. Search scope: <FILES/DIRS>.
Relevant context: <SHORT CONTEXT PACKET>.
Use compiler-aware navigation if this depends on C++ symbols. Use compiler-aware navigation if this depends on C++ symbols.
Do not edit files. Do not edit files.
@@ -229,5 +187,6 @@ Return only:
- Focused validation for the task passed or the failure is documented. - Focused validation for the task passed or the failure is documented.
- `docs/modernization/debt.md` changed when debt was narrowed or closed. - `docs/modernization/debt.md` changed when debt was narrowed or closed.
- `docs/modernization/tasks.md` score changed only for `Done` tasks. - `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 commit contains one coherent slice.
- The branch was pushed. - The branch was pushed.