From ab69a3d0e2f631f067c66985486dffd236d31c02 Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Wed, 12 Aug 2026 15:02:22 +0900 Subject: [PATCH] docs: plan Harness agent step execution roles --- ...2026-08-12-harness-agent-step-execution.md | 190 ++++++++++++++++++ 1 file changed, 190 insertions(+) create mode 100644 docs/superpowers/plans/2026-08-12-harness-agent-step-execution.md diff --git a/docs/superpowers/plans/2026-08-12-harness-agent-step-execution.md b/docs/superpowers/plans/2026-08-12-harness-agent-step-execution.md new file mode 100644 index 0000000..f040d97 --- /dev/null +++ b/docs/superpowers/plans/2026-08-12-harness-agent-step-execution.md @@ -0,0 +1,190 @@ +# 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" +```