diff --git a/AGENTS.md b/AGENTS.md index 5ba2537..3798f87 100644 --- a/AGENTS.md +++ b/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 diff --git a/docs/modernization/director-workflow.md b/docs/modernization/director-workflow.md new file mode 100644 index 0000000..7569fe6 --- /dev/null +++ b/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 task group in PanoPainter. + +Task source: docs/modernization/tasks.md task . +Debt ids: . +Assigned scope: . +Validation: . + +Goal: . + +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: . +Model fit: . +Write scope: . +Read scope: . +Validation: . + +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: . +Search scope: . +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. diff --git a/docs/modernization/tasks.md b/docs/modernization/tasks.md index 4701730..f8fa138 100644 --- a/docs/modernization/tasks.md +++ b/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