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**

```powershell
$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:

```text
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:

```text
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**

```powershell
@'
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**

```powershell
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**

```powershell
$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:

```text
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**

```powershell
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**

```powershell
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**

```powershell
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"
```