---
name: harness-workflow
description: "Use when planning or running this Abaqus User Subroutine Harness: reading AGENTS.md and docs/*.md, discussing implementation scope, creating or updating phases/index.json, phases/{task}/index.json, phases/{task}/stepN.md, or invoking scripts/execute.py for staged Codex execution."
---

# Harness Workflow

## Overview

Use this skill to turn a user-approved Abaqus User Subroutine task into small, self-contained Harness steps. Keep every step grounded in repository docs, Fortran TDD, no-Abaqus validation, and externally generated reference artifact validation.

## Workflow

1. Read `AGENTS.md`, `docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md`, `docs/PRD.md`, `docs/ARCHITECTURE.md`, and `docs/ADR.md`.
2. Map the task to the seven-step Abaqus User Subroutine process: requirements, research, formulation, interface, TDD test models, Fortran implementation, validation.
3. Discuss unresolved product or technical decisions with the user before writing phase files.
4. Create or update `phases/index.json`, `phases/{task-name}/index.json`, and one `phases/{task-name}/stepN.md` per step.
5. Run the phase with `python scripts/execute.py {task-name}` when asked. Use `--push` only when the user asks.

## Step Design Rules

- Scope each step to one artifact family: requirements, research, formulation, ABI/interface, no-Abaqus tests, Fortran source, validation, or documentation.
- Make every step self-contained. Include required context and file paths.
- Specify interfaces and signatures only when the step owns the interface contract.
- Use executable acceptance criteria, not abstract statements.
- For Fortran behavior changes, require tests first and name the no-Abaqus Fortran/Python driver test or `tests/fortran/manifest.json` entry.
- Preserve the rule that this project does not run Abaqus analyses; solver-result evidence must be externally generated ODB-extracted CSV artifacts.

## Phase Files

Create or update `phases/index.json`:

```json
{
  "phases": [
    {
      "dir": "abaqus-subroutine-feature",
      "status": "pending"
    }
  ]
}
```

Create `phases/{task-name}/index.json`:

```json
{
  "project": "Abaqus User Subroutine Development",
  "phase": "<task-name>",
  "steps": [
    { "step": 0, "name": "requirements", "status": "pending" },
    { "step": 1, "name": "test-models", "status": "pending" },
    { "step": 2, "name": "fortran-implementation", "status": "pending" }
  ]
}
```

Rules:

- `project` comes from `AGENTS.md`.
- `phase` matches the task directory name.
- `steps[].step` starts at `0`.
- Initial status is always `pending`.
- Do not add timestamps when creating files. `scripts/execute.py` records timestamps.

## Step Template

```markdown
# Step {N}: {name}

## Read First

- `/AGENTS.md`
- `/docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md`
- `/docs/ARCHITECTURE.md`
- `/docs/ADR.md`
- {previously created or modified files}

## Task

{Concrete instructions with file paths, interfaces, signatures, and rules.}

## Tests To Write First

- {Exact no-Abaqus Fortran/Python test file, manifest entry, or Python harness test to add before implementation.}

## Acceptance Criteria

```bash
python -m unittest discover -s scripts -p "test_*.py"
python scripts/validate_fortran.py
python scripts/validate_reference_artifacts.py
python scripts/validate_workspace.py
```

## Validation Notes

- Use externally generated ODB-extracted CSV artifacts for solver-result validation evidence.
- Update `phases/{task-name}/index.json` with `completed`, `error`, or `blocked` and a concrete summary/reason.

## Forbidden

- Do not add JavaScript/TypeScript/npm fallback.
- Do not run Abaqus analyses from this project.
- Do not generate reference CSVs unless the user explicitly authorized a reference-artifact phase.
- Do not break existing tests.
```

## Execution And Recovery

Run:

```bash
python scripts/execute.py {task-name}
python scripts/execute.py {task-name} --push
```

If a step is `error`, fix the cause, set it back to `pending`, remove `error_message`, and rerun. If a step is `blocked`, resolve `blocked_reason`, set it back to `pending`, remove `blocked_reason`, and rerun.