Document multi-agent director workflow
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
190
docs/modernization/director-workflow.md
Normal file
190
docs/modernization/director-workflow.md
Normal file
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user