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 owns at most two process/session transport attempts. They do not consume or reset the Coordinator's one-correction workflow budget. An implementation, upstream-contract, environment, or physics failure is returned for Coordinator classification rather than automatically looped.

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"}
  ]
}

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. It commits implementation paths and phase metadata separately, ignores raw stepN-output.json, normalizes the index before path-scoped staging, and never stages changes outside the declared ownership boundary. 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; a Stop pass proves only the configured build/test gate.

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 may reset the current Step to pending; stale summary/failure/block timestamps are cleared by the Executor.

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.