panopainter/docs/modernization/director-workflow.md

# 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.
- 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.
- Keep communication terse: no fillers, no cheerleading, no narrative padding.
  Use direct technical wording only.

## 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, 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 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

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.

### 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
- focus on the assigned task first; do not start by reading unrelated docs or
  broad repository areas unless the task explicitly requires it
- 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. |

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.

## 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.
- 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.

## Delegation Flow

1. Director picks two 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.

## 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(s) <TASK-ID-LIST>.
Debt ids: <DEBT-LIST>.
Assigned scope: <FILES/DIRS>.
Validation: <COMMANDS>.

Goal: <ONE PARAGRAPH>.

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: <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.
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.

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.