docs: plan Harness agent step execution roles
This commit is contained in:
KOKO\Mimi
@@ -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"
|
||||||
|
```
|
||||||
Reference in New Issue
Block a user