FESADev/docs/superpowers/specs/2026-08-12-harness-agent-step-execution-design.md

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/<task>/index.json, and approved phases/<task>/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 <phase> 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.