panopainter/docs/modernization/director-workflow.md

# Modernization Coordinator Workflow

Status: live
Last updated: 2026-06-16

Use this workflow when the user explicitly asks for subagents, delegation, a
coordinator, 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`.

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

- Save main-thread tokens by keeping implementation and focused lookup out of
  the coordinator context.
- Treat thread compaction as wasted budget. Prefer small active context,
  committed resume state, and fresh follow-on threads over carrying long stale
  history.
- Keep each implementation slice measurable, validated, committed, and pushed.
- Avoid merge conflicts by giving every worker a disjoint task and file scope.
- Do not leave workers idle. Either give a worker another coherent follow-on
  task while its context is still useful, or close it promptly.
- Reuse worker context only for closely related follow-on tasks in the same
  local area; otherwise close the worker and start a fresh one with a new
  minimal packet.
- Keep prompts dense with the exact project/task context workers need so they do
  not spend tokens re-reading repo docs or re-parsing broad areas.
- Keep communication terse: no fillers, no cheerleading, no narrative padding.
  Use direct technical wording only.

## Roles

### Coordinator

The coordinator is the main agent in the user thread. The coordinator owns:

- choosing the task group from `docs/modernization/tasks.md`
- deciding whether delegation is worth the coordination cost
- splitting work into direct worker-sized tasks
- packaging the exact context each worker needs
- spawning workers and explorers directly
- integrating returned changes
- running final validation
- updating docs/debt/tasks
- committing and pushing the verified slice
- either assigning coherent follow-on work to an active worker or closing that
  worker once its useful context window is over

The coordinator should keep local work minimal. It may do a quick 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 directly to a worker whenever the scope can be
made clear.

The coordinator must front-load context. Workers should not be told to "read
the roadmap", "read AGENTS.md", or "inspect the repo" unless that is the task.
The coordinator is responsible for extracting and passing:

- task ids and done checks
- debt ids and removal conditions that matter
- exact write scope and allowed read scope
- required validation commands
- the specific build/test preset or target names the worker may need
- the exact code-exploration tools to use for the slice, such as `rg` or the
  compiler-aware `clangd_nav.py` helper
- relevant file paths, code references, and current behavior notes
- any repo rules or user constraints that materially affect the task

### Workers And Explorers

Workers perform bounded edits in assigned files. Explorers answer specific
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.

Workers may be kept alive for more than one assignment only when the next task
is coherent with the current one: same subsystem, overlapping read scope,
similar validation path, and no avoidable context rebuild. Do not keep workers
alive just because a slot is available.

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
- use the supplied task context first instead of broad repo/doc review
- report changed files, validation run, and blockers

## Model Selection

| Work Type | Model | Reasoning Effort | Use |
| --- | --- | --- | --- |
| Coordinator orchestration and integration | `gpt-5.4` | `low` or `medium` | Scope selection, task routing, conflict checks, validation, docs/debt updates, commits, pushes, and worker packet preparation. |
| Direct worker coding task | `gpt-5.4-mini` | `medium` | Bounded implementation in known files with coordinator-supplied context. |
| Direct worker lookup or inventory | `gpt-5.4-mini` | `low` or `medium` | `rg` inventory, file ownership map, simple grep-based answers. |
| Mechanical docs cleanup | `gpt-5.4-mini` | `low` | Formatting, table updates, command normalization. |
| 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. |

Workers default to `gpt-5.4-mini`. If a task looks too broad or risky
for that model, the coordinator should decompose it further or keep the narrow
integration step locally instead of inserting an extra management tier.

## Context And 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 captured in the worker prompt.
- Do not let the coordinator thread drift toward compaction. Once a verified
  slice is committed and pushed, prefer a fresh thread for the next slice if
  the remaining context is no longer tight.
- Do not paste large logs into prompts. Point workers at log paths and ask for
  the smallest relevant excerpt.
- Do not ask workers to broadly read `AGENTS.md`, the roadmap, the debt log, or
  other repo-wide docs. Summarize the exact rules and rows they need.
- Default worker context to a minimal operating packet: task id, assigned file
  scope, build command, test command, and code-exploration command hints.
- Keep worker prompts compact but complete. Shorter is good only if it still
  removes the need for worker-side repo rediscovery.
- Ask for compact final reports: changed files, result, validation, blockers,
  next recommendation.
- Keep active workers busy with another coherent task when that is cheaper than
  restarting context; otherwise close them immediately after integration.
- Close workers that are done, blocked, or no longer have a strong context
  advantage so they do not accumulate and saturate worker slots.
- Prefer the smallest number of concurrent workers that keeps disjoint work
  moving.
- Use rolling integration: wait for whichever worker finishes first, process the
  result, then either reuse that worker for the next coherent slice or close it
  before launching a fresh worker for unrelated work.
- Prefer committed repo state over chat history as the handoff mechanism between
  slices so worker and coordinator prompts stay short.

## Delegation Flow

1. Coordinator picks one or more `Ready` tasks from
   `docs/modernization/tasks.md` with disjoint write scopes.
2. Coordinator splits each task into direct worker-sized units, grouping
   coherent follow-on work when one worker can finish it efficiently without
   broadening scope.
3. Coordinator prepares a context packet for each worker with the exact task
   requirements, file scope, validation commands, and relevant project details.
4. Coordinator assigns the task directly to a `gpt-5.4-mini` worker or
   explorer.
5. Worker returns changed files, validation, blockers, and any narrow
   integration notes.
6. Coordinator reviews for scope conflicts, integrates the result, and decides
   whether to give that same worker another coherent task or close it.
7. Coordinator runs the listed validation command or the quiet checkpoint
   wrapper for each integrated slice.
8. Coordinator updates `tasks.md`, `debt.md`, and `roadmap.md` if task state or
   documented behavior moved.
9. Coordinator commits and pushes verified slices incrementally.

## Coordinator Prompt Template For A Worker

```text
You are a `gpt-5.4-mini` 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>.
Goal: <ONE PARAGRAPH>.
Done checks: <DONE-CHECKS>.
Debt ids: <DEBT-LIST>.
Write scope: <FILES/DIRS ONLY>.
Read scope: <FILES/DIRS>.
Validation: <COMMANDS>.
Code exploration: <RG OR CLANGD_NAV COMMANDS TO USE>.

Repo constraints you must follow:
- <ONLY THE RELEVANT RULES>

Minimal 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>

Do not read repo-wide docs unless this task explicitly requires it. Use only
the supplied context, the listed file scope, and the build/test/code-exploration
commands above.

If the coordinator gives you a second task, accept it only when it is coherent
with the current scope and does not require broad repo rediscovery. Otherwise
say that a fresh worker should be used.

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 explicitly requires it. 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
```

## Coordinator Prompt Template For An Explorer

```text
Answer one codebase question for PanoPainter.

Question: <QUESTION>.
Search scope: <FILES/DIRS>.
Relevant context: <SHORT CONTEXT PACKET>.
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.
- Each worker result was integrated before that worker was reused.
- Reused workers only handled coherent follow-on tasks with a real context
  advantage.
- Done or blocked workers were closed instead of being left idle.
- The coordinator did not carry unnecessary stale history when a fresh thread
  would have been cheaper than compaction.
- The commit contains one coherent slice.
- The branch was pushed.