Document multi-agent director workflow

AGENTS.md

@@ -19,6 +19,9 @@ Read these first:
   entry with validation and removal conditions.
 - `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
+  workflow; use only when the user asks for subagents or delegation.
 - `docs/adr/0001-modernization-boundaries.md` - component boundary decisions.
 
 ## Working Rules
@@ -37,6 +40,9 @@ Read these first:
 - Use CMake as the source of truth. Legacy Visual Studio project files are not the
   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.
 
 ## Build And Test
 

docs/modernization/director-workflow.md

@@ -0,0 +1,190 @@
+# Modernization Director Workflow
+
+Status: live
+Last updated: 2026-06-12
+
+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
+`docs/modernization/tasks.md`.
+
+## 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.
+- Keep each implementation slice measurable, validated, committed, and pushed.
+- Avoid merge conflicts by giving every agent a disjoint task and file scope.
+
+## Roles
+
+### Director
+
+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
+- 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.
+
+### Team Captain
+
+Use `gpt-5.4` for each captain. A captain owns one coherent task group, for
+example:
+
+- renderer/export boundary
+- legacy adapter retirement
+- platform/package parity
+- UI lifetime
+- 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 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 perform bounded edits in assigned files. Explorers answer specific
+questions and should usually not edit files.
+
+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
+- report changed files, validation run, and blockers
+
+## Model Selection
+
+| Work Type | Model | Reasoning Effort | Use |
+| --- | --- | --- | --- |
+| Captain for a task group | `gpt-5.4` | `medium` default, `high` for renderer/platform architecture | Split task, supervise workers, summarize integration. |
+| 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. |
+
+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` captains, so use that override for captains.
+
+## 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
+  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.
+- 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.
+
+## 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.
+
+## Director Prompt Template For A Captain
+
+```text
+You are the gpt-5.4 team captain for the <group> task group in PanoPainter.
+
+Task source: docs/modernization/tasks.md task <TASK-ID>.
+Debt ids: <DEBT-LIST>.
+Assigned scope: <FILES/DIRS>.
+Validation: <COMMANDS>.
+
+Goal: <ONE PARAGRAPH>.
+
+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.
+
+Return:
+- recommended worker tasks with model choice and file scope
+- any task you can safely complete yourself
+- risks/blockers
+- minimal context each worker needs
+```
+
+## 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>.
+Read scope: <FILES/DIRS>.
+Validation: <COMMANDS>.
+
+Make the smallest behavior-preserving change that satisfies the done checks.
+Update tests/docs only if listed. If the task is larger than expected, stop and
+report the split instead of broadening scope.
+
+Final report:
+- files changed
+- behavior changed
+- validation run and result
+- blockers or follow-up
+```
+
+## Explorer Prompt Template
+
+```text
+Answer one codebase question for PanoPainter.
+
+Question: <QUESTION>.
+Search scope: <FILES/DIRS>.
+Use compiler-aware navigation if this depends on C++ symbols.
+Do not edit files.
+
+Return only:
+- answer
+- supporting file references
+- confidence and caveats
+```
+
+## Final Integration Checklist
+
+- No worker changed files outside its assigned scope without calling it out.
+- No generated logs or build output were committed.
+- 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.
+- The commit contains one coherent slice.
+- The branch was pushed.

docs/modernization/tasks.md

@@ -20,6 +20,9 @@ new broad roadmap paragraph.
   stays `Ready` or becomes `Blocked` with the reason.
 - After a verified task is committed and pushed, reset conversation context
   before starting the next task when practical.
+- When the user asks for subagents or delegation, follow
+  `docs/modernization/director-workflow.md` and keep each delegated task mapped
+  to a row in this tracker.
 
 ## Progress Scorecard