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.

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

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

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

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.