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

Harness Agent Step Execution Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make FESA planning and implementation agents use the approved Harness phase lifecycle, with the Implementation Agent restricted to the Executor-selected current Step.

Architecture: Keep scripts/execute.py as the only phase runner after separate user authorization. Agent TOML files define role-specific planning/execution boundaries; the Harness and FESA TDD skills plus project guides provide the shared lifecycle without duplicating the full Harness documentation.

Tech Stack: Codex Agent TOML, Markdown skills and guides, Python 3 Harness runner/hooks, pytest, PowerShell.

Global Constraints

• Both agents must read docs/HARNESS.md and docs/HARNESS_WORKFLOW.md for Harness work.
• Phase files may be created only after the multi-Step draft is explicitly approved.
• scripts/execute.py may run only after a separate explicit user request.
• The Executor owns branch selection, pending-Step selection, retries, timestamps, commits, next-Step advancement, and top-level phase status.
• The Implementation Agent executes only the current Executor-selected stepN.md and completes RED, expected failure, minimal GREEN, and VERIFY inside that Step.
• PreToolUse and Stop hooks run through .codex/hooks.json; their Python entry points are not manual substitutes for hook execution.
• No phase execution, C++ implementation, Abaqus execution, or reference-artifact mutation belongs to this policy change.

---

Task 1: Agent Harness role contracts

Files:

• Modify: .codex/agents/implementation-planning-agent.toml
• Modify: .codex/agents/implementation-agent.toml

Interfaces:

• Consumes: approved design docs/superpowers/specs/2026-08-12-harness-agent-step-execution-design.md; current Harness lifecycle in .agents/skills/harness/SKILL.md, docs/HARNESS.md, and docs/HARNESS_WORKFLOW.md.

• Produces: explicit planning-agent reference/approval rules and implementation-agent current-Step execution/state ownership rules.

• Step 1: Run the static RED check

$files = @(
  '.codex/agents/implementation-planning-agent.toml',
  '.codex/agents/implementation-agent.toml'
)
foreach ($file in $files) {
  if (-not (Select-String -LiteralPath $file -SimpleMatch 'docs/HARNESS.md' -Quiet)) {
    Write-Error "$file does not require docs/HARNESS.md"
  }
  if (-not (Select-String -LiteralPath $file -SimpleMatch 'docs/HARNESS_WORKFLOW.md' -Quiet)) {
    Write-Error "$file does not require docs/HARNESS_WORKFLOW.md"
  }
}
if (-not (Select-String -LiteralPath '.codex/agents/implementation-agent.toml' -SimpleMatch 'Executor-selected current Step' -Quiet)) {
  Write-Error 'Implementation Agent is not restricted to the current Step'
}

Expected: FAIL for the missing Harness-document references and current-Step rule.

• Step 2: Add the Planning Agent contract

Add mandatory reads for docs/HARNESS.md, docs/HARNESS_WORKFLOW.md, and .codex/hooks.json. Preserve the existing sequence:

multi-Step draft -> explicit user approval -> phases planning files
separate explicit Harness execution request -> scripts/execute.py

State that the planning agent never selects or executes a Step and does not write Executor-owned timestamps.

• Step 3: Add the Implementation Agent contract

Require this execution recipe:

approved plan + materialized phase files + Executor-selected current stepN.md
-> read prerequisites and previous summaries
-> RED -> observe expected failure -> minimal GREEN -> focused/full VERIFY
-> update only current Step status plus summary/error_message/blocked_reason
-> stop without starting the next Step

Name .codex/hooks.json, scripts/hooks/pre_tool_use.py, and scripts/hooks/stop_validation.py. State that hooks run automatically, do not prove RED, and are not manually invoked as substitutes for registered hooks. Reserve timestamps, retry control, commits, and next-Step selection for the Executor.

• Step 4: Parse and rerun the static check

@'
import pathlib, tomllib
for path in pathlib.Path('.codex/agents').glob('*.toml'):
    with path.open('rb') as stream:
        tomllib.load(stream)
print('ALL_AGENT_TOML_OK')
'@ | python -

rg -n "docs/HARNESS.md|docs/HARNESS_WORKFLOW.md|Executor-selected current Step|scripts/execute.py|PreToolUse|Stop" `
  .codex/agents/implementation-planning-agent.toml `
  .codex/agents/implementation-agent.toml

Expected: TOML parse passes and every required boundary is visible.

• Step 5: Commit

git add .codex/agents/implementation-planning-agent.toml .codex/agents/implementation-agent.toml
git commit -m "docs: bind implementation agents to Harness steps"

Task 2: Shared Harness skill and guide alignment

Files:

• Modify: .agents/skills/harness/SKILL.md
• Modify: .codex/skills/fesa-cpp-msvc-tdd/SKILL.md
• Modify: docs/SOLVER_AGENT_DESIGN.md
• Modify: docs/implementation-plans/README.md

Interfaces:

• Consumes: Task 1 Agent terminology and role ownership.

• Produces: one consistent Executor/Step/hook lifecycle discoverable by both agents.

• Step 1: Run the shared-contract RED check

$files = @('.agents/skills/harness/SKILL.md', '.codex/skills/fesa-cpp-msvc-tdd/SKILL.md')
foreach ($file in $files) {
  if (-not (Select-String -LiteralPath $file -SimpleMatch 'docs/HARNESS.md' -Quiet)) {
    Write-Error "$file does not route to docs/HARNESS.md"
  }
  if (-not (Select-String -LiteralPath $file -SimpleMatch 'docs/HARNESS_WORKFLOW.md' -Quiet)) {
    Write-Error "$file does not route to docs/HARNESS_WORKFLOW.md"
  }
}

Expected: FAIL because the current skills omit these mandatory references.

• Step 2: Update the Harness skill

Add a concise required-reading section and an Executor/Implementation-Agent ownership section. Preserve the existing phase schemas. Explicitly distinguish:

Executor-owned: branch, pending Step, retry, timestamps, commits, advancement
Agent-owned: current Step work and status payload fields
Hook-owned: PreToolUse interception and Stop whole-project validation

• Step 3: Update FESA TDD skill and guides

Make the TDD skill require both Harness documents and materialized phase files for implementation. Update the solver-agent and implementation-plan guides with the same current-Step recipe, automatic hook use, status-field split, and separate Executor authorization. Avoid copying all 600 lines of HARNESS_WORKFLOW.md; link to it.

• Step 4: Validate skills and Harness behavior

python C:/Users/baram/.codex/skills/.system/skill-creator/scripts/quick_validate.py .agents/skills/harness
python C:/Users/baram/.codex/skills/.system/skill-creator/scripts/quick_validate.py .codex/skills/fesa-cpp-msvc-tdd
uv run --with pytest python -m pytest -v -rs
git diff --check

Expected: both skills are valid, Harness Python tests pass, and no whitespace error is reported.

• Step 5: Run final policy and scope checks

rg -n "docs/HARNESS.md|docs/HARNESS_WORKFLOW.md|Executor-selected current Step|current Step|scripts/execute.py|PreToolUse|Stop" `
  .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

git diff --name-only HEAD -- reference phases src include tests CMakeLists.txt
git status --short

Expected: required policies are present; no reference, phase, C++, test, or CMake file changed.

• Step 6: Commit

git add .agents/skills/harness/SKILL.md .codex/skills/fesa-cpp-msvc-tdd/SKILL.md `
  docs/SOLVER_AGENT_DESIGN.md docs/implementation-plans/README.md
git commit -m "docs: align Harness step execution guidance"