# Abaqus User Subroutine Agent Design

## Purpose

This document maps the project agents and skills to the Abaqus User Subroutine development process. The working language is Fortran with Intel oneAPI Fortran, and Abaqus execution remains opt-in.

## Abaqus User Subroutine development process

1. Subroutine requirements analysis
2. Books, papers, and research evidence
3. Finite element formulation for implementation
4. Subroutine input/output parameter definition
5. TDD test model design
6. Fortran code implementation
7. Subroutine validation

## Agent Mapping

| Process step | Primary agents | Primary skills |
| --- | --- | --- |
| 1. Subroutine requirements analysis | Requirement Agent, Coordinator Agent | `abaqus-subroutine-requirements` |
| 2. Books, papers, and research evidence | Research Agent | `abaqus-subroutine-research`, `fem-theory-query` |
| 3. Finite element formulation for implementation | Formulation Agent, Numerical Review Agent | `abaqus-subroutine-formulation`, `abaqus-subroutine-numerical-review`, `fem-theory-query` |
| 4. Subroutine input/output parameter definition | I/O Definition Agent | `abaqus-subroutine-interface`, `fem-theory-query` |
| 5. TDD test model design | Reference Model Agent, Implementation Planning Agent | `abaqus-subroutine-test-models`, `fem-theory-query` |
| 6. Fortran code implementation | Implementation Planning Agent, Implementation Agent, Correction Agent | `abaqus-fortran-tdd` |
| 7. Subroutine validation | Build/Test Executor Agent, Reference Verification Agent, Physics Evaluation Agent, Release Agent | `abaqus-subroutine-validation`, `abaqus-subroutine-physics-sanity`, `abaqus-subroutine-readiness`, `fem-theory-query` |

## Source Selection Contract

- Use `fem-theory-query` for finite element theory, formulation, solver behavior, benchmark selection, and numerical or physics interpretation.
- For Abaqus User Subroutine ABI and manual facts, read `docs/AbaqusUserSubroutineManual/INDEX_MAP.md`, locate the full record in `INDEX.md`, and then read every listed `source_ranges` span in order.
- Treat `INDEX.md` summaries as retrieval metadata, not authoritative implementation evidence.
- Treat user-provided ODB-extracted CSV and provenance artifacts as solver-result inputs; agents do not run Abaqus or parse ODB files in this project.

## Gates

- Requirements gate: every must requirement has measurable acceptance criteria and verification method.
- Research gate: source-backed facts are separated from inference and applicability limits are explicit.
- Formulation gate: stress update, consistent tangent, state variables, and numerical risks are documented.
- Interface gate: Abaqus ABI arguments, update responsibilities, tensor ordering, units, and CSV extraction schemas are explicit.
- Test model gate: no-Abaqus tests and reference artifact contracts are defined before implementation.
- Implementation gate: Fortran production changes follow RED -> GREEN -> VERIFY and pass no-Abaqus validation.
- Validation gate: reference artifacts include `.inp`, source hash, Abaqus version, compiler version, msg/dat/log tail, and extracted CSV evidence before comparison.

## Validation Defaults

- Default no-Abaqus path: `python scripts/validate_fortran.py`.
- Reference artifact contract check: `python scripts/validate_reference_artifacts.py`.
- Workspace gate: `python scripts/validate_workspace.py`.
- Abaqus execution: performed by the user on another Abaqus PC; agents in this project consume the resulting CSV and provenance artifacts.