diff --git a/docs/modernization/director-workflow.md b/docs/modernization/director-workflow.md index 7569fe6..c9ed7eb 100644 --- a/docs/modernization/director-workflow.md +++ b/docs/modernization/director-workflow.md @@ -24,15 +24,24 @@ The director is the main agent in the user thread. The director 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 +- spawning one `gpt-5.4` captain per independent task group, including + multiple teams when scopes are disjoint - integrating returned changes - running final validation - updating docs/debt/tasks - committing and pushing the verified slice - resetting conversation context after the slice when practical -The director should not delegate the immediate blocking step. If the next local -action is required before anything else can proceed, do that locally. +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 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. ### Team Captain @@ -46,10 +55,13 @@ example: - dependency cleanup - test/hardening work -The captain turns one task-group objective into smaller disjoint subtasks. If -nested subagents are available, the captain may spawn workers. If nested -subagents are not available in the current surface, the captain returns a worker -plan and the director performs the second-level spawns. +The captain owns implementation for its assigned task group. The captain turns +one task-group objective into smaller disjoint subtasks, 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. 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. @@ -96,25 +108,23 @@ has requested `gpt-5.4` captains, so use that override for captains. - Ask for compact final reports: changed files, result, validation, blockers, next recommendation. - Close completed agents after their results are integrated or rejected. -- Prefer one captain and two or three workers over many agents. Coordination - cost can exceed token savings. +- 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. ## Delegation Flow -1. Director picks one `Ready` task or one small group of adjacent tasks from - `docs/modernization/tasks.md`. -2. Director identifies the immediate local blocking step and keeps it local. -3. Director spawns one `gpt-5.4` captain for sidecar decomposition or an - independent task group. -4. Captain returns either: - - a worker plan with disjoint write scopes, or - - completed bounded edits if the captain can finish the task directly. -5. Director or captain spawns worker/explorer agents only for disjoint subtasks. -6. Workers edit only their assigned files and run focused validation when cheap. -7. Director reviews and integrates changes. -8. Director runs the task's listed validation command. -9. Director updates `tasks.md`, `debt.md`, and `roadmap.md` if the task moved. -10. Director commits and pushes the verified slice. +1. Director 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. +3. Captains implement directly or coordinate workers/explorers for disjoint + subtasks. +4. Captains run focused validation when cheap and return changed files, + validation, blockers, and integration notes. +5. Director reviews for scope conflicts and integrates returned changes. +6. Director runs the listed validation command or the quiet checkpoint wrapper. +7. Director updates `tasks.md`, `debt.md`, and `roadmap.md` if tasks moved. +8. Director commits and pushes the verified slice. ## Director Prompt Template For A Captain @@ -128,16 +138,18 @@ Validation: . Goal: . -First, split this into disjoint worker tasks suitable for gpt-5.4-mini or -gpt-5.3-codex-spark. Use gpt-5.4 only for 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. +Own this task group through implementation. Split into disjoint worker tasks +only when that is faster or safer than doing the bounded edits yourself. Use +gpt-5.4 only for 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 -- any task you can safely complete yourself +- completed edits or the exact blocker preventing them +- focused validation run and result - risks/blockers -- minimal context each worker needs +- integration notes for the director ``` ## Captain Prompt Template For A Worker