FESADev/.agents/skills/harness/SKILL.md

name, description

name	description
harness	Plan, materialize, or execute bounded agentic implementation phases with test-first steps, validated state, safe Git ownership, and configured C++ verification.

Harness Workflow

Use Harness for multi-step repository implementation. Read AGENTS.md, docs/HARNESS.md, and docs/HARNESS_WORKFLOW.md before creating phases or executing them. Read the approved upstream feature bundle and docs/TOLERANCE.md when numerical comparison is in scope. For feature work, read Feature document management and the dispatched feature's FEATURED_AGENTS.md, PRD.md, and ADR.md; keep agent reports in that feature folder.

Authorization boundary

A Coordinator dispatch based on an approved feature bundle authorizes routine planning-file creation and bounded local execution with the default workspace-write sandbox. Do not add a separate “approve this plan” or “start implementation?” gate.

Separate explicit user authorization is still required immediately before:

• danger-full-access
• --push, tag, publish, deploy, package, or release
• destructive Git/history or filesystem operations
• licensed external solver execution, credentials, cost, or non-repository side effects

Ownership

Owner	Responsibility
Coordinator	feature state, normalized retry_key, correction budget, dispatch and closure
Planning Agent	assigned phase/index/step files and implementation-plan.md
Executor	branch, current pending Step, transport attempts, timestamps, path-scoped commits and phase advancement
Implementation Agent	only the Executor-selected Step, its code/tests/reports, and Step result payload
Hooks	pre-edit command/TDD guard and configured whole-project Stop validation

The Executor permits at most two transport attempts, including the initial attempt, only when its process wrapper observes a timeout and the Step has not reported a terminal result. A nonzero exit (including 124) alone is not timeout evidence. Reported error/blocked results are preserved without retry even on nonzero exit. Recognized sandbox-helper failures block even on zero exit. These attempts do not consume or reset the Coordinator's one-correction workflow budget.

Plan materialization

Create only the files assigned by Coordinator:

phases/index.json
phases/<phase>/index.json
phases/<phase>/step0.md
phases/<phase>/step1.md
...

The top-level entry is:

{"dir": "<phase>", "status": "pending"}

The phase index is:

{
  "project": "<project>",
  "phase": "<phase>",
  "steps": [
    {
      "step": 0, "name": "<kebab-case-name>", "status": "pending",
      "owned_paths": ["src/example.cpp", "tests/example_test.cpp"]
    }
  ]
}

Replace the example paths with the Step's approved source/header/test/build/report files. owned_paths is a Planning-owned array of exact repository-relative files, not directories or globs. [] permits no implementation-file changes; it is not equivalent to a missing field. Do not include Git internals or phases/ control files. Paths cannot escape through traversal, symlinks or junctions; linked paths are not supported. Backslashes are normalized and Windows case aliases are treated as the same path. Existing completed Steps remain readable without this field. Every pending Step must have a valid list before execution starts; do not infer it from Markdown or automatically migrate historical phases.

Use contiguous Step numbers from zero. A Step must be small enough to complete RED -> observed failure -> minimal GREEN -> focused VERIFY -> full VERIFY in one Codex session; do not leave a red-only Step for a later Step.

Each stepN.md is self-contained and contains:

• files and upstream contracts to read, including the exact feature folder and its FEATURED_AGENTS.md, PRD.md, and ADR.md
• exact owned files, symbols and behavior
• the expected RED failure and minimal GREEN scope
• executable focused/full acceptance commands resolved from project configuration
• architecture, numerical and reference invariants
• explicit out-of-scope items and stopping conditions

Do not invent missing physics, tolerance, schema, toolchain, or reference data in a Step. Return the issue to its owner through Coordinator.

Local execution

Normal execution is:

python scripts/execute.py <phase>

The Executor requires a valid top-level/phase schema and a worktree clean outside the selected phase control-file allowlist before branch checkout. It also requires the Git top-level to equal the Harness root and validates the Implementation Agent profile before changing branch or state. It injects the role, project guardrails, completed Step summaries and the current Step. It rejects nonzero Codex exits even if a Step claimed completion.

The Implementation Agent updates only the current Step:

• completed plus a non-empty summary
• error plus error_message
• blocked plus blocked_reason

The Executor adds timestamps and immutable attempt_history records preserving reported outcomes, process exits, classifications and diagnostics across retries/recovery. It checks changed paths after each attempt and before staging, then checks the actual staged paths before committing. The trusted owned_paths snapshot covers tracked/untracked, staged/unstaged changes and both rename endpoints. Implementation paths and phase metadata are committed separately; raw stepN-output.json stays ignored. An ownership violation stops retry/commit/advancement, records the offending paths, and preserves user files without reverting or expanding the allowlist. Avoid concurrent edits: these checks are not a filesystem sandbox or an atomic guarantee against concurrent writers. Commit groups are not one transaction; a failure after the implementation commit can leave that commit with an error Step. Top/phase control metadata and non-current Steps are immutable during a session; a violation is restored to the trusted snapshot and recorded as an error. The implementation session may not run commit, push, branch, tag, merge/rebase, or history-changing Git commands. Executor verifies symbolic branch and HEAD around every attempt. Control reads reject links and scope escape; control/output writes use atomic replacement so a substituted link target is not overwritten.

Do not run hook scripts manually as substitutes for registered hooks. A PreToolUse pass proves neither RED nor correctness. Stop may skip build/test only for a valid same-session/turn record containing solely repository-local .md edits. Missing/corrupt records or non-document edits take the normal validation path; shell writes and read-only requests without edit records are not guaranteed to skip. A skipped check is not build/test evidence. Do not manipulate hook state to obtain a skip.

Elevated and remote execution

Use danger-full-access only after the user has authorized that exact run, the same command was shown to fail because of the native sandbox, and execution is in a clean linked Git worktree:

$env:FEM_HARNESS_CODEX_SANDBOX = "danger-full-access"
python scripts/execute.py <phase> --approve-danger-full-access
Remove-Item Env:FEM_HARNESS_CODEX_SANDBOX

The environment value alone is insufficient. The Executor rejects a primary or dirty worktree.

Use --push only when the user explicitly authorized pushing the completed feature branch:

python scripts/execute.py <phase> --push

Recovery and handoff

Do not manually erase failure evidence and immediately rerun. Return the exact command/exit, classification, artifact paths and retry_key to Coordinator. After the owning upstream/environment/user decision is resolved, Coordinator records the retry decision and preserved failure evidence in coordination.md, then explicitly assigns the Planning Agent a recovery edit of the phase index. With the Executor stopped, that agent changes only the current failed/blocked Step's status to pending; it does not alter other Steps, top-level phase state, timestamps, or the feature workflow. Coordinator does not edit phase files itself. The Executor clears stale summary/failure/block fields and timestamps on restart, retaining attempt_history. For a legacy Step missing owned_paths, Planning needs a separate explicit assignment to supply the approved list before execution; the status-only recovery edit does not grant that change. This is an assigned file edit, not an automatic recovery command or an additional correction allowance.

Report the final phase state, commits created, commands and exit codes, test counts, ignored/untracked raw output, unexecuted checks and residual risks. Never call a phase complete when any Step is non-completed.