modify documents

.codex/skills/fem-formulation-spec/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: fem-formulation-spec
+description: Use when an approved structural FEM feature needs an implementation-ready mathematical formulation before numerical review or coding.
+---
+
+# FEM Formulation Specification
+
+Translate approved requirements and research into a complete mathematical contract, independent of programming APIs and storage formats.
+
+## Inputs
+
+- `docs/<feature-id>/requirements.md`
+- `docs/<feature-id>/research.md`
+- Governing standards and approved analysis assumptions
+
+## Workflow
+
+1. Fix primary variables, degrees of freedom, units, coordinates, signs, configuration, and boundary-condition conventions.
+2. Derive governing strong and weak forms with all natural and essential boundary terms.
+3. Define discretization, interpolation, kinematics, constitutive update contract, element residual/internal and external forces, and consistent tangent or stiffness.
+4. Define mapping, Jacobian validity, quadrature, state/history evolution, constraints, and result recovery that apply to the selected analysis family.
+5. State dimensions, invariants, algorithm pseudocode, numerical risks, and tests capable of falsifying each derivation.
+
+Read [analysis-family guidance](references/analysis-families.md) and apply only the sections selected by the requirements. Use [workflow and decision authority](../fem-requirements-baseline/references/workflow-and-decisions.md) for unresolved physics choices and [evidence and handoff](../fem-requirements-baseline/references/evidence-and-handoff.md) for return data.
+
+## Output
+
+Follow [Feature document management](../../../docs/FEATURE_DOCUMENTATION.md): read the Coordinator's
+feature context, keep main reports concise, and link necessary owned details in the same feature folder.
+
+Create or revise `docs/<feature-id>/formulation.md` with assumptions; variables; strong/weak forms; discretization; kinematics; constitutive contract; element equations; integration; algorithms; recovery; numerical risks; verification implications; and handoff.
+
+## Evidence
+
+Every equation defines symbols, dimensions, configuration, sign, coordinate basis, and source or derivation. Show linearization when a consistent tangent is required. Link risks and checks to requirement IDs.
+
+## Boundary
+
+Do not design source-level APIs, parsers, storage schemas, or implementation tasks. Do not silently choose physics, stabilization, interpolation, constitutive behavior, or solver semantics outside the approved contract; return that critical choice for decision.

.codex/skills/fem-formulation-spec/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "FEM Formulation Specification"
+  short_description: "Specify structural FEM mathematics"
+  default_prompt: "Use $fem-formulation-spec to specify the mathematics for an approved structural FEM feature."

.codex/skills/fem-formulation-spec/references/analysis-families.md

@@ -0,0 +1,33 @@
+# Structural Analysis Family Guidance
+
+Read only the family selected by the approved requirements. Coupled features apply each relevant section and define the coupling terms explicitly.
+
+## Common
+
+Check DOF ordering, boundary conditions, units, coordinate transforms, rigid-body modes, element orientation, residual convention, output location, and conservation or equilibrium identities.
+
+## Linear static
+
+Define linearization assumptions, stiffness symmetry expectations, load assembly, constraint treatment, reactions, patch tests, rigid-body/null-space checks, and mesh-convergence quantities.
+
+## Nonlinear static
+
+Define configuration and strain/stress measures, state update, residual and consistent tangent, load/time parameter, convergence norms, increment/cutback behavior, path dependence, and energy or work checks.
+
+## Modal, eigenvalue, and buckling
+
+Define matrix problem, boundary conditions, mass or geometric stiffness, eigensolver target, normalization, repeated-mode handling, sign/phase invariance, residual norms, and mode correlation. Distinguish linearized buckling from nonlinear collapse.
+
+## Dynamics
+
+Define mass and damping, initial conditions, time integration, stability and algorithmic dissipation, load history, time-step convergence, energy balance, frequency/phase measures, and modal truncation where applicable.
+
+## Contact and constraints
+
+Define gap and normal orientation, active-set/search semantics, normal and tangential laws, enforcement method, consistent contributions, state transitions, penetration/slip measures, and action-reaction checks.
+
+## Material nonlinearity
+
+Define admissible state, yield/failure surface, flow/evolution laws, integration algorithm, consistent material tangent, history initialization, loading/unloading cases, and single-point constitutive tests.
+
+Do not apply an irrelevant checklist merely for completeness. If the family is ambiguous and the choice changes physical meaning or acceptance, return `needs-user-decision`.