From 85cd17da5700d1f52f9ecea052f751fb3245224b Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Wed, 12 Aug 2026 11:19:27 +0900 Subject: [PATCH] docs: design Harness phase step execution roles --- ...-12-harness-agent-step-execution-design.md | 129 ++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-12-harness-agent-step-execution-design.md diff --git a/docs/superpowers/specs/2026-08-12-harness-agent-step-execution-design.md b/docs/superpowers/specs/2026-08-12-harness-agent-step-execution-design.md new file mode 100644 index 0000000..96e84a0 --- /dev/null +++ b/docs/superpowers/specs/2026-08-12-harness-agent-step-execution-design.md @@ -0,0 +1,129 @@ +# Harness Agent Step Execution Design + +## Status + +- date: `2026-08-12` +- status: `approved-approach-awaiting-written-spec-review` +- approved_approach: `executor-centered-single-path` +- scope: Implementation Planning Agent, Implementation Agent, Harness workflow guidance + +## Purpose + +FESA implementation work shall use one explicit Harness execution path. The +Implementation Planning Agent converts an approved implementation plan into +self-contained phase Steps after user approval. The Step Executor selects and runs +those Steps sequentially. The Implementation Agent executes only the current Step and +does not independently expand its scope to the remaining implementation plan. + +## Required Reading + +Both the Implementation Planning Agent and Implementation Agent shall read these +documents before Harness planning or execution: + +- `AGENTS.md` +- `.agents/skills/harness/SKILL.md` +- `docs/HARNESS.md` +- `docs/HARNESS_WORKFLOW.md` +- `docs/SOLVER_AGENT_DESIGN.md` +- the approved feature implementation plan and applicable upstream feature contracts + +The agents shall also inspect `.codex/hooks.json`, `.harness/config.json` when present, +and the relevant `phases/` indexes and Step file for execution work. + +## Planning Contract + +The Implementation Planning Agent shall: + +1. prepare a multi-Step draft from approved upstream contracts; +2. keep one layer or module in each self-contained Step; +3. include required-reading paths, RED/GREEN/VERIFY work, exact acceptance commands, + status rules, and concrete prohibitions; +4. obtain explicit user approval before creating or updating `phases/` planning files; +5. create only `phases/index.json`, `phases//index.json`, and approved + `phases//stepN.md` files; +6. never run `scripts/execute.py` merely because a plan or phase draft is ready. + +Harness execution requires a separate explicit user request. + +## Execution Contract + +After an explicit Harness execution request, `scripts/execute.py ` is the +single phase runner. It owns branch selection, first-pending-Step selection, Step +session creation, retries, timestamps, commit separation, next-Step advancement, and +top-level phase completion. + +The Implementation Agent shall: + +1. require an approved implementation plan and materialized phase files; +2. execute only the current `stepN.md` selected and supplied by the Executor; +3. read the Step prerequisites and relevant previous-Step summaries before editing; +4. complete RED, observed expected failure, minimal GREEN, focused VERIFY, and the + Step's full acceptance commands within the same Step; +5. avoid starting a later pending Step or performing unlisted implementation-plan + work; +6. update only the current Step's Codex-owned status fields: + - success: `status=completed` plus one-line `summary`; + - after the allowed failed correction attempts: `status=error` plus + `error_message`; + - user intervention required: `status=blocked` plus `blocked_reason`, then stop; +7. leave `started_at`, `completed_at`, `failed_at`, `blocked_at`, task timestamps, + next-Step selection, and top-level phase status to the Executor. + +If approved phase files are absent or the supplied Step conflicts with an approved +upstream contract, the Implementation Agent shall not fall back to the broad plan. It +shall report `needs-upstream-decision` or `blocked` through the documented handoff. + +## Hooks and Scripts + +`.codex/hooks.json` is the authoritative hook registration used during Harness Step +sessions: + +- PreToolUse calls `scripts/hooks/pre_tool_use.py` to reject dangerous commands and + enforce the related-test-file guardrail for C++ production edits. +- Stop calls `scripts/hooks/stop_validation.py` to run the discovered whole-project + MSVC build/test validation before a Step may end. + +These hooks run automatically through Codex hook registration. Agents shall inspect +the registration and comply with hook outcomes, but shall not manually invoke the +hook Python entry points as a substitute for actual tool interception or Stop. +PreToolUse is not proof that RED occurred; the Implementation Agent must execute and +record the Step's RED and GREEN commands itself. + +The approved script boundary is: + +- `scripts/execute.py`: phase runner; run only after a separate explicit user request; +- Step acceptance commands: run by the Implementation Agent as written, resolving + `.harness/config.json` first and otherwise using documented Harness defaults; +- `uv run --with pytest python -m pytest -v -rs`: additionally required only when + Harness Python, hook, runner, or Agent/Skill configuration behavior is changed. + +## Files to Align + +The implementation will make surgical changes to: + +- `.codex/agents/implementation-planning-agent.toml` +- `.codex/agents/implementation-agent.toml` +- `.agents/skills/harness/SKILL.md` +- `.codex/skills/fesa-cpp-msvc-tdd/SKILL.md` +- `docs/SOLVER_AGENT_DESIGN.md` +- `docs/implementation-plans/README.md` + +`docs/HARNESS.md` and `docs/HARNESS_WORKFLOW.md` already document the runner, hooks, +validation, retry, and state lifecycle. They become mandatory references rather than +being duplicated in full in every Agent or Skill instruction. + +## Validation + +The change is complete when: + +- both Agent TOML files parse; +- the changed skills pass `quick_validate.py`; +- both agents explicitly require `docs/HARNESS.md` and + `docs/HARNESS_WORKFLOW.md`; +- the Implementation Agent explicitly follows only the Executor-selected current + Step and respects Executor-owned fields; +- hook behavior and `scripts/execute.py` authorization are consistent across the + Agent, Skill, and guide documents; +- Harness Python tests pass because hook/Agent/Skill behavior is in scope; +- no phase execution, C++ implementation, reference mutation, or Abaqus execution + occurs as part of this policy edit.