add agents

docs/MULTI_AGENT_RESEARCH_PLAN.md

@@ -0,0 +1,96 @@
+# Multi-Agent Research Plan
+
+## Purpose
+This document is the durable planning memo for FESA's research-oriented multi-agent workflow. It records what the agents should investigate before solver implementation begins.
+
+No solver code should be implemented from this plan directly. Each agent should produce an English technical dossier that an implementer can later follow.
+
+## Project Context
+FESA is a C++17 finite element structural analysis solver. Phase 1 targets a linear static MITC4 shell solver with linear elastic material, nodal loads, fixed boundary conditions, an Abaqus input subset, HDF5-oriented results, and reference-result comparison.
+
+The user will provide Abaqus input files and solved reference result files under a repository `reference/` folder. Abaqus is not available locally, so validation must compare against stored reference artifacts.
+
+## Current Architecture Constraints
+- Follow `AGENTS.md`, `docs/ARCHITECTURE.md`, and `docs/ADR.md`.
+- Use runtime polymorphism for elements, materials, loads, boundary conditions, and analysis algorithms.
+- Keep `Domain` close to immutable after parsing.
+- Use `AnalysisModel` for the active step view.
+- Use `AnalysisState` for mutable physical state and iteration state.
+- Let `DofManager` own DOF definitions, constrained/free DOF mapping, equation numbering, and sparse pattern support.
+- Use Strategy plus Template Method for analysis execution.
+- Use Factory plus Registry for Abaqus keyword to object creation.
+- Keep MKL, TBB, and HDF5 behind adapter/wrapper boundaries.
+- Store results using step/frame/field/history concepts.
+
+## Created Codex Agents
+The first recommended batch has been created under `.codex/agents/`.
+
+1. `fem_literature_researcher`
+   - File: `.codex/agents/fem-literature-researcher.toml`
+   - Role: research FEM shell literature, MITC family background, locking behavior, and implementation implications.
+
+2. `verification_benchmark_researcher`
+   - File: `.codex/agents/verification-benchmark-researcher.toml`
+   - Role: research benchmark cases, reference folder contracts, comparison methods, and acceptance criteria.
+
+3. `mitc4_formulation_researcher`
+   - File: `.codex/agents/mitc4-formulation-researcher.toml`
+   - Role: research MITC4 formulation details and convert them into implementation requirements.
+
+4. `abaqus_compatibility_researcher`
+   - File: `.codex/agents/abaqus-compatibility-researcher.toml`
+   - Role: research the Phase 1 Abaqus input subset and parser compatibility rules.
+
+## Recommended Agent Execution Order
+1. Run `fem_literature_researcher`.
+2. Run `verification_benchmark_researcher`.
+3. Run `mitc4_formulation_researcher`.
+4. Run `abaqus_compatibility_researcher`.
+
+This order keeps theory, verification targets, element formulation, and input compatibility aligned before implementation planning.
+
+## Later Agent Candidates
+These agents should be created after the first four produce dossiers.
+
+1. `solver_architecture_researcher`
+   - Refines responsibilities among `Domain`, `AnalysisModel`, `AnalysisState`, `DofManager`, `Assembler`, and `LinearSolver`.
+
+2. `sparse_solver_researcher`
+   - Researches sparse pattern generation, CSR/COO assembly, MKL PARDISO integration, and TBB-safe assembly strategies.
+
+3. `results_hdf5_schema_researcher`
+   - Designs the HDF5 group/dataset schema for step/frame/field/history outputs.
+
+4. `nonlinear_roadmap_researcher`
+   - Researches geometric nonlinearity, Newton-Raphson, tangent stiffness, increments, and convergence criteria.
+
+5. `thermal_coupling_researcher`
+   - Researches heat transfer, thermal load generation, thermal strain, and thermal-stress coupling.
+
+6. `architecture_guardrail_reviewer`
+   - Reviews dossiers, phase plans, and future implementation against project rules and ADRs.
+
+## User-Provided Inputs Needed
+The following inputs should be requested from the user as the research matures:
+
+1. The intended `reference/` folder layout, or permission to propose one.
+2. At least one simple Abaqus `.inp` file and its solved reference result artifact.
+3. Preferred reference result format if available: `.dat`, `.rpt`, exported `.csv`, HDF5, or another structured format.
+4. Whether Phase 1 should map Abaqus `S4` directly to FESA `MITC4`.
+5. Whether Phase 1 shell nodes use six DOFs per node from the beginning: three translations and three rotations.
+6. Preferred numerical tolerances for reference comparison, or permission for agents to propose initial tolerances per benchmark.
+7. Whether the first implementation plan should target CMake, another build system, or a project-specific build layout.
+
+## Seed Sources
+- Abaqus input syntax rules: https://abaqus-docs.mit.edu/2017/English/SIMACAEMODRefMap/simamod-c-inputsyntax.htm
+- Abaqus shell section behavior: https://abaqus-docs.mit.edu/2017/English/SIMACAEELMRefMap/simaelm-c-shellsectionbehavior.htm
+- OpenSees ShellMITC4 manual: https://opensees.berkeley.edu/OpenSees/manuals/usermanual/640.htm
+- MITC3+/MITC4+ benchmark paper: https://web.mit.edu/kjb/www/Principal_Publications/Performance_of_the_MITC3%2B_and_MITC4%2B_shell_elements_in_widely_used_benchmark_problems.pdf
+- COMSOL Scordelis-Lo benchmark example: https://doc.comsol.com/5.6/doc/com.comsol.help.models.sme.scordelis_lo_roof/scordelis_lo_roof.html
+- NAFEMS nonlinear benchmark survey page: https://www.nafems.org/publications/pubguide/benchmarks/Page6/
+
+## Non-Goals
+- Do not implement solver code.
+- Do not generate phase execution files until the user explicitly asks for implementation planning.
+- Do not require Abaqus execution in local validation.
+- Do not treat unsourced formulas or benchmark constants as final.