From 80abcd70b5190dea859a27b6a34931d07f9d0ce3 Mon Sep 17 00:00:00 2001 From: John Preston Date: Fri, 27 Mar 2026 15:28:14 +0700 Subject: [PATCH] [ai] Try using subagents more in Codex. --- .agents/skills/task-think/PROMPTS.md | 54 ++++++++++++++++++++++------ .agents/skills/task-think/SKILL.md | 17 ++++++--- 2 files changed, 56 insertions(+), 15 deletions(-) diff --git a/.agents/skills/task-think/PROMPTS.md b/.agents/skills/task-think/PROMPTS.md index 07d7d1b5f1..cc9fa5d172 100644 --- a/.agents/skills/task-think/PROMPTS.md +++ b/.agents/skills/task-think/PROMPTS.md @@ -1,20 +1,53 @@ # Phase Prompts -Use these templates as Codex subagent messages or, if delegation is unavailable, as same-session checklists. Replace ``, ``, ``, and ``. +Use these templates as Codex subagent messages. Use them as same-session checklists only for Phase 0, intentional main-session build work, Phase 7, or when delegation is unavailable from the start. Replace ``, ``, ``, and ``. ## Orchestration Rules - Phase 0 runs in the main session. -- For Phases 1 through 6, prefer a fresh subagent per phase to keep phase context isolated. +- When delegation is available, use a fresh subagent for Phase 1, Phase 2, Phase 3, each Phase 4 implementation unit, and each Phase 6 pass. Do not switch those phases to same-session midstream because of a timeout or missing artifact. - Phase 7 runs in the main session on Windows because it depends on the final local diff and touched-file set. - Write each phase prompt to `.ai///logs/phase-.prompt.md` before execution. - If you delegate a phase, send the prompt file contents as the initial `spawn_agent` message. +- When writing the phase prompt file, append the standard compact reply block below so the subagent knows exactly how to report completion. - After each phase completes, write `.ai///logs/phase-.result.md` summarizing the status, files touched, and any follow-up notes. - Use `fork_context: false` by default. If the phase depends on thread-only context or UI attachments, pass that context explicitly or enable `fork_context` only for that phase. - Prefer `worker` for phases that write files. Use `default` for plan or review passes if that fits the host better. Use `explorer` only for narrow read-only questions. - When supported, request `model: gpt-5.4` and `reasoning_effort: xhigh` for delegated phases. +- Default wait budget for delegated phases is 15 minutes. Use shorter waits only when the phase is intentionally tiny. +- A `wait_agent` timeout is not failure. On timeout, inspect expected artifact progress before deciding anything. +- If the expected artifact exists and shows progress, wait again. +- If no usable artifact exists yet, send one short follow-up asking the same agent to finish the required artifact and return the standard compact reply block, then wait again. +- If the same agent still produces no usable artifact after two 15-minute waits and one follow-up, close it and retry the phase in a fresh subagent. +- For Phase 1, Phase 2, Phase 3, Phase 4, and Phase 6, if delegated retries still fail, stop and ask the user rather than rerunning the phase locally. - Never use `codex exec`, background shell child processes, or JSONL child-session logging from this skill. +## Standard Compact Reply Block + +Append this verbatim to every delegated phase prompt: + +```text +Before replying in chat, write the required artifact(s) to disk. + +Reply in 8 lines or fewer using exactly these keys: +STATUS: +ARTIFACTS: +TOUCHED: +BLOCKER: + +Do not restate the full context, plan, diff, or long reasoning in the chat reply. +``` + +## Artifact-Based Completion Checks + +- Phase 1 is complete only when `about.md` and `context.md` both exist and are non-empty. +- Phase 2 is complete only when `plan.md` exists, contains a `## Status` section, and no unintended source edits were made. +- Phase 3 is complete only when `plan.md` contains both `Phases:` in the Status section and `Assessed: yes`. +- Phase 4 is complete only when the target phase checkbox changed to checked and the touched-file list matches the owned write set, or the blocker explains any mismatch. +- Phase 5 is complete only when the build outcome is known and the build checkbox is updated on success. +- Phase 6a is complete only when `review.md` exists and contains a verdict line. +- Phase 6b is complete only when the requested fixes were applied and the post-fix build outcome is known. + ## Phase 0: Setup Record the current time now and store it as `$START_TIME`. You will use this at the end to display total elapsed time. @@ -270,8 +303,8 @@ When finished, report what you did, which files you changed, and any issues enco ``` After each implementation phase: -1. Read `plan.md` to confirm the status was updated. -2. Verify the owned write set and touched files make sense. +1. Use a narrow read or search to confirm the status line was updated. +2. Verify the owned write set and touched files with a small diff summary such as `git diff --name-only`. 3. If more phases remain, run the next implementation phase. 4. If all phases are done, proceed to build verification. @@ -466,8 +499,8 @@ When all phases, including build verification, code review, and Windows line end ## Error Handling -- If any phase fails or gets stuck, report the issue to the user and ask how to proceed. -- If `context.md` or `plan.md` is not written properly by a phase, rerun that phase with more specific instructions. +- If any phase fails or gets stuck, follow the timeout and retry rules above. For Phase 1, Phase 2, Phase 3, Phase 4, and Phase 6, do not rerun locally after a timeout; ask the user if delegated retries fail. +- If `context.md` or `plan.md` is not written properly by a phase, rerun that phase in a fresh subagent with more specific instructions. - If build errors persist after the build phase's attempts, report the remaining errors to the user. - If a review-fix phase introduces new build errors that it cannot resolve, report to the user. @@ -475,7 +508,7 @@ When all phases, including build verification, code review, and Windows line end For each phase: 1. Write the full prompt to `.ai///logs/phase-.prompt.md` -2. Delegate by sending that prompt text to a fresh subagent, or use it as a same-session checklist +2. Delegate by sending that prompt text to a fresh subagent, or use it as a same-session checklist only for the designated main-session phases or when delegation was unavailable from the start 3. Save a concise completion note to `.ai///logs/phase-.result.md` For review iterations, include the iteration in the file name, for example: @@ -490,8 +523,9 @@ Use this pattern conceptually for delegated phases: 1. Write the phase prompt file. 2. Spawn a fresh subagent with the phase prompt, usually with `fork_context: false`. -3. Wait when the next step is blocked on that phase. -4. Validate the expected artifact or code changes. -5. Write the result log. +3. Wait in 15-minute intervals when the next step is blocked on that phase, checking artifact progress on timeout. +4. If needed, send one short follow-up to the same agent, then retry once with a fresh subagent before involving the user. +5. Validate the expected artifact or code changes with small shell summaries and the completion checks above. +6. Write the result log from the validated outcome and the compact reply block. Do not replace this pattern with shell-launched `codex exec`. diff --git a/.agents/skills/task-think/SKILL.md b/.agents/skills/task-think/SKILL.md index ac14522ddf..2d5d1c8864 100644 --- a/.agents/skills/task-think/SKILL.md +++ b/.agents/skills/task-think/SKILL.md @@ -1,6 +1,6 @@ --- name: task-think -description: Orchestrate a multi-phase implementation workflow for this repository with artifact files under .ai/// using Codex subagents instead of shell-spawned child processes. Use when the user wants one prompt to drive context gathering, planning, plan assessment, implementation, build verification, and review with persistent artifacts and clear phase handoffs. Prefer spawn_agent/send_input/wait_agent; fall back to same-session execution only when delegation is unavailable or disallowed. +description: Orchestrate a multi-phase implementation workflow for this repository with artifact files under .ai/// using Codex subagents instead of shell-spawned child processes. Use when the user wants one prompt to drive context gathering, planning, plan assessment, implementation, build verification, and review with persistent artifacts, clear phase handoffs, and a thin parent thread. Prefer spawn_agent/send_input/wait_agent, keep heavy pre-build work delegated when possible, and avoid pulling timed-out phases back into the main session. --- # Task Pipeline @@ -78,20 +78,27 @@ Use the phase prompt templates in `PROMPTS.md`. Use Codex subagents as the primary orchestration mechanism. -- Spawn a fresh subagent for context gathering, planning, plan assessment, each implementation phase, and each review or review-fix pass when delegation is available. +- When delegation is available, Phase 1, Phase 2, Phase 3, each Phase 4 implementation unit, and each Phase 6 review or review-fix pass must run in fresh subagents. Do not rerun those phases in the main session midstream just because a wait timed out or an artifact is missing. - Run Phase 7 in the main session on Windows because it depends on the final local file state and the exact touched-file set for the current task. +- The main session may read `context.md` once after Phase 1 and `plan.md` once after Phase 3. After that, prefer narrow shell checks, file existence checks, and status-line reads instead of rereading full documents or diffs. - Prefer `worker` for phases that write files. Use `explorer` only for narrow read-only questions that unblock your next local step. - Keep `fork_context` off by default. Pass the phase prompt and explicit file paths instead of the whole thread unless the phase truly needs prior conversational context or thread-only attachments. - When the platform supports it, request `model: gpt-5.4` and `reasoning_effort: xhigh` for spawned phase agents. If overrides are unavailable, inherit the current session settings. - Write the exact phase prompt to the matching `logs/phase-.prompt.md` file before you delegate. Use the same prompt file as a checklist if you later need to fall back to same-session execution. +- In every delegated prompt, require a compact final reply with only status, artifact paths, touched files, and blocker or `none`. Detailed reasoning belongs in `.ai/` artifacts, not in the chat reply. - After a subagent finishes, verify that the expected artifacts or code changes exist, then write a short result log in `logs/phase-.result.md`. +- For delegated phases, use `wait_agent` with a 15-minute timeout by default. A timeout is not a failure; it only means no final status arrived yet. +- On timeout, inspect the expected artifact and worktree for progress first. If progress exists, wait again. +- If no usable artifact exists yet, send one short follow-up asking the same subagent to finish writing the artifact and return the compact status block, then wait again. +- If the same subagent still produces no usable artifact after two 15-minute waits and one follow-up, close it and rerun that phase in a fresh subagent. - Use `wait_agent` only when the next step is blocked on the result. While the delegated phase runs, do small non-overlapping local tasks such as validating directory structure or preparing the next prompt file. - Build verification is critical-path work. Prefer running the build in the main session, and only delegate a bounded build-fix phase when there is a concrete reason. -- If subagents are unavailable in the current environment, or current policy does not allow delegation for this request, run the phase in the main session using the same prompt files. Never fall back to shell-spawned `codex exec` child processes from this skill. +- If subagents are unavailable in the current environment, or current policy does not allow delegation from the start, run the phase in the main session using the same prompt files. Otherwise, do not switch a pre-build phase to same-session midstream. Never fall back to shell-spawned `codex exec` child processes from this skill. ## Verification Rules - If build or test commands fail due to file locks or access-denied outputs (C1041, LNK1104), stop and ask the user to close locking processes before retrying. +- Treat a delegated phase as complete only when the required artifact or status update exists on disk and matches the phase goals; do not rely on the chat reply alone. - Never claim completion without: - implemented code changes present - build attempt results recorded @@ -110,8 +117,8 @@ Mark complete only when: ## Error Handling -- If any phase fails, times out, or gets stuck, inspect the partial artifacts, tighten the prompt, and retry with a fresh subagent or same-session fallback. Report the issue to the user if you remain blocked. -- If `context.md` or `plan.md` is not written properly by a phase, rerun that phase with more specific instructions. +- If any phase fails, times out, or gets stuck, follow the retry ladder from Execution Mode. After two delegated attempts remain blocked, report the issue to the user. Do not absorb the phase into the main session before build unless delegation was unavailable from the start. +- If `context.md` or `plan.md` is not written properly by a phase, rerun that phase in a fresh subagent with more specific instructions. Do not repair it locally before build unless delegation was unavailable from the start. - If build errors persist after the build phase's attempts, report the remaining errors to the user. - If a review-fix phase introduces new build errors that it cannot resolve, report to the user. - If Phase 7 cannot safely normalize a touched file on Windows, record the failure in the result log and report it in the final summary instead of silently skipping it.