# FESA Solver Skill Rebuild Plan ## 목적 이 문서는 FESA 유한요소 기반 구조해석 솔버 개발에 사용할 project-local Codex skill 구성을 정의한다. Agent는 역할과 책임 단위이고, skill은 여러 Agent가 반복적으로 사용하는 절차와 검증 도구 단위다. 따라서 skill은 Agent와 1:1로 대응하지 않는다. 대신 요구조건, 연구, 정식화, I/O 계약, reference model, C++ TDD 구현, reference 비교, 물리 검토, release readiness처럼 솔버 개발 과정에서 반복되는 작업 흐름을 기준으로 구성한다. ## 설계 원칙 - Skill은 `.codex/skills//SKILL.md`에 둔다. - 각 skill은 필수 frontmatter `name`, `description`과 UI metadata `agents/openai.yaml`을 가진다. - Skill 본문은 agent TOML의 역할 설명을 반복하지 않고, 입력, 절차, 산출물, 금지사항, 품질 gate, handoff를 정의한다. - Skill은 `AGENTS.md`와 `docs/SOLVER_AGENT_DESIGN.md`를 공통 상위 기준으로 읽는다. - Abaqus, Nastran 또는 reference solver 실행은 skill 범위에 포함하지 않는다. - Abaqus reference CSV 파일 생성/수정은 skill 범위에 포함하지 않는다. - C++ 구현 관련 skill은 C++17 이상, MSVC, CMake, CTest, TDD 원칙을 따른다. - C++ 검증 명령은 `.harness/config.json` 또는 `docs/HARNESS.md`의 자동 감지 기본값을 따른다. - Harness Python 변경은 `uv run --with pytest python -m pytest -v -rs`로 검증한다. ## Skill 구성 | Skill | 적용 개발 과정 | 주요 사용자 Agent | 대표 산출물 | | --- | --- | --- | --- | | `fesa-requirements-baseline` | 1. 솔버 기능 요구조건 정의 | Requirement Agent, Coordinator Agent | `docs/requirements/.md` | | `fesa-research-evidence` | 2. 책, 논문 등 연구자료 조사 | Research Agent, Formulation Agent | `docs/research/-research.md` | | `fesa-formulation-spec` | 3. 코드 구현을 위한 유한요소 정식화 | Formulation Agent, Implementation Planning Agent | `docs/formulations/-formulation.md` | | `fesa-numerical-review` | 3. 정식화 독립 수치 검토 | Numerical Review Agent, Coordinator Agent | `docs/numerical-reviews/-review.md` | | `fesa-io-contract` | 4. 솔버 입출력 데이터 정의 | I/O Definition Agent, Reference Verification Agent | `docs/io-definitions/-io.md` | | `fesa-reference-models` | 5. TDD/reference 테스트모델 작성 | Reference Model Agent, Implementation Planning Agent | `docs/reference-models/-reference-models.md` | | `fesa-cpp-msvc-tdd` | 6. 코드 구현 및 build/test correction | Implementation Planning Agent, Implementation Agent, Build/Test Executor Agent, Correction Agent | implementation plan/report, build/test report, correction report | | `fesa-reference-comparison` | 7. reference solver 결과와 구현 solver 결과 비교 | Reference Verification Agent | `docs/reference-verifications/-reference-verification.md` | | `fesa-physics-sanity` | 8. tolerance 통과 후 물리 타당성 검토 | Physics Evaluation Agent | `docs/physics-evaluations/-physics-evaluation.md` | | `fesa-release-readiness` | 9. 솔버 기능 배포 준비 | Release Agent, Coordinator Agent | `docs/releases/-release.md` | ## 개발 과정별 사용 예 예시 기능: `isoparametric-3d-euler-beam` 1. Requirement Agent는 `fesa-requirements-baseline`을 사용해 기능 범위, 제외 범위, 입력, 출력, 검증 물리량, tolerance, `Requirement Verification Matrix`를 작성한다. 2. Research Agent는 `fesa-research-evidence`를 사용해 3D Euler beam element 이론, benchmark 후보, source reliability, applicability limits를 정리한다. 3. Formulation Agent는 `fesa-formulation-spec`을 사용해 strong form, weak form, shape functions, B matrix, element stiffness, output recovery를 정리한다. 4. Numerical Review Agent는 `fesa-numerical-review`를 사용해 rigid body modes, patch test, stiffness symmetry, Jacobian, locking 위험을 검토하고 `pass-for-implementation-planning` 여부를 판단한다. 5. I/O Definition Agent는 `fesa-io-contract`를 사용해 지원할 Abaqus `.inp` keyword subset, `results.h5` schema, reference CSV comparison row schema를 정의한다. 6. Reference Model Agent는 `fesa-reference-models`를 사용해 기존 input/required CSV reference-case inventory와 비교 mapping을 작성한다. 7. Implementation Planning Agent는 먼저 project-local `harness`를 사용해 사용자 승인용 multi-Step 초안을 만들고, 승인 후 phase files를 생성한다. 그 뒤 Implementation Agent와 함께 `fesa-cpp-msvc-tdd` 계약에 따라 RED/GREEN/VERIFY를 수행한다. 8. Reference Verification Agent는 `fesa-reference-comparison`을 사용해 구현 solver `results.h5` rows와 Abaqus reference CSV rows를 tolerance 기준으로 비교한다. 9. Physics Evaluation Agent는 `fesa-physics-sanity`를 사용해 global equilibrium, reaction consistency, displacement direction, symmetry, model coverage를 검토한다. 10. Release Agent는 `fesa-release-readiness`를 사용해 gate evidence, acceptance traceability, known limitations, release notes draft를 작성한다. ## Skill별 핵심 계약 ### `fesa-requirements-baseline` - 기능 요청을 검증 가능한 요구조건 baseline으로 만든다. - `shall` 문장과 `FESA-REQ--###` id를 사용한다. - 모든 `must` 요구조건은 verification method와 acceptance criteria를 가져야 한다. - FEM 정식화, C++ 구현, Abaqus reference CSV 생성 또는 수정, release readiness 판단은 하지 않는다. ### `fesa-research-evidence` - 연구 질문, source inventory, source reliability tier, benchmark 후보를 정리한다. - 검증된 사실과 추론을 분리한다. - source gap은 open issue로 남긴다. - FEM 정식화 확정이나 reference value 생성을 하지 않는다. ### `fesa-formulation-spec` - strong form, weak form, discretization, kinematics, constitutive contract, element equations를 구분해 작성한다. - Jacobian, derivative transform, numerical integration, output recovery, numerical risks를 명시한다. - C++ API, parser, file ownership은 설계하지 않는다. - Numerical Review Agent 검토 전 최종 승인 상태로 두지 않는다. ### `fesa-numerical-review` - 정식화를 수치 알고리즘 계약으로 독립 검토한다. - dimensions, signs, DOF ordering, coordinate transforms, Jacobian, integration rule, stiffness symmetry, rigid body modes, patch test, hourglass, locking을 확인한다. - `pass-for-implementation-planning`은 구현 계획 가능 상태만 의미한다. - 정식화 문서를 직접 수정하지 않는다. - 이후 Reference Model 문서, artifact naming, README, metadata, provenance 또는 portfolio가 없다는 이유로 formulation verdict를 실패시키지 않는다. ### `fesa-io-contract` - FESA solver input이 지원할 Abaqus `.inp` subset을 정의한다. - model data와 history data를 구분한다. - 내부 semantic model 계약, HDF5 output schema, reference CSV comparison row schema를 정의한다. - parser 구현이나 full Abaqus compatibility claim은 하지 않는다. ### `fesa-reference-models` - 기능이 실제로 사용하는 기존 reference case를 inventory한다. - Exact input/required CSV path, case purpose, blocking/warning quantity, HDF5 projection, source ID/component matching과 tolerance만 정의한다. - Required comparison file이 없을 때만 `needs-reference-artifacts`로 둔다. Canonical naming, README, metadata, provenance와 비교하지 않는 quantity CSV는 요구하지 않는다. ### `fesa-cpp-msvc-tdd` - C++ 구현을 `RED -> GREEN -> VERIFY` 순서로 수행한다. - C++ production 변경에는 관련 C++ test file이 있어야 한다. - 기본 검증 명령: ```powershell cmake -S . -B .harness/build -A x64 cmake --build .harness/build --config Debug ctest --test-dir .harness/build -C Debug -R --output-on-failure ctest --test-dir .harness/build -C Debug --output-on-failure ``` Preset 또는 직접 MSBuild 프로젝트는 `.harness/config.json`의 설정을 사용한다. Harness Python, Hook, agent config를 변경한 경우에는 다음 명령도 실행한다. ```powershell uv run --with pytest python -m pytest -v -rs ``` - 실패는 `configure | compile | link | test | reference-comparison | harness | environment | upstream-contract`로 분류한다. - 요구조건, 정식화, I/O 계약, reference artifact, tolerance policy를 바꾸지 않는다. ### project-local `harness` - Implementation Planning Agent가 구현 요청을 여러 독립 Step으로 분해할 때 사용한다. - 한 Step은 하나의 layer/module만 소유하고 prerequisite file, TDD RED/GREEN/VERIFY, exact acceptance command와 구체적 금지사항을 포함한다. - 사용자에게 Step 초안을 먼저 제시한다. 승인 후에만 `phases/index.json`, `phases//index.json`, `phases//stepN.md`를 생성한다. - 계획 작성과 executor 실행을 구분하며, `scripts/execute.py`는 별도 사용자 요청 없이 실행하지 않는다. ### `fesa-reference-comparison` - `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT` 순서로 수행한다. - 선언된 input, required Abaqus CSV, `results.h5`, source ID/component mapping과 tolerance를 확인한다. Missing/extra/duplicate/nonfinite required row는 비교 전에 실패한다. - max absolute error, max relative error, RMS error, norm error, missing rows, extra rows를 보고한다. - Reference pass는 physics validation이나 release readiness를 의미하지 않는다. ### `fesa-physics-sanity` - Reference comparison 통과 후 물리 타당성을 검토한다. - global equilibrium, reaction consistency, displacement direction, symmetry, element force balance, stress/strain sanity, rigid body mode, model coverage를 확인한다. - 문서화된 물리 기대값이 없으면 pass를 선언하지 않는다. - `pass-for-release-agent`는 Release Agent 검토 가능 상태만 의미한다. ### `fesa-release-readiness` - `GATE AUDIT -> TRACEABILITY CHECK -> RELEASE DOCUMENTATION -> RELEASE VERDICT` 순서로 수행한다. - `pass-for-reference-verification`, `pass-for-physics-evaluation`, `pass-for-release-agent` evidence를 요구한다. - Known Limitations와 Release Notes Draft를 작성한다. - 사용자 명시 요청 없이 publish, deploy, package, tag, commit, external release를 수행하지 않는다. ## Agent와 Skill 관계 | Agent | 주로 사용하는 Skill | | --- | --- | | Coordinator Agent | `fesa-requirements-baseline`, `fesa-reference-models`, `fesa-release-readiness` | | Requirement Agent | `fesa-requirements-baseline` | | Research Agent | `fesa-research-evidence` | | Formulation Agent | `fesa-formulation-spec` | | Numerical Review Agent | `fesa-numerical-review` | | I/O Definition Agent | `fesa-io-contract` | | Reference Model Agent | `fesa-reference-models` | | Implementation Planning Agent | project-local `harness`, `fesa-formulation-spec`, `fesa-reference-models`, `fesa-cpp-msvc-tdd` | | Implementation Agent | `fesa-cpp-msvc-tdd` | | Build/Test Executor Agent | `fesa-cpp-msvc-tdd` | | Correction Agent | `fesa-cpp-msvc-tdd` | | Reference Verification Agent | `fesa-reference-comparison`, `fesa-io-contract` | | Physics Evaluation Agent | `fesa-physics-sanity` | | Release Agent | `fesa-release-readiness` | ## 검증 기준 Skill 구성은 실제 `.codex/skills/` 파일을 source of truth로 삼아 정적 계약과 repository pytest suite로 검증한다. 검증 항목: - 10개 solver skill의 `SKILL.md` 존재 여부 - YAML frontmatter의 `name`, `description` - 공통 섹션: `Inputs`, `Workflow`, `Output Contract`, `Boundaries`, `Quality Gate`, `Handoff` - `AGENTS.md`와 `docs/SOLVER_AGENT_DESIGN.md` 참조 - skill-specific 핵심 문구와 산출물 경로 - `agents/openai.yaml` UI metadata - 이 문서가 아니라 실제 skill 파일이 기준이 되도록 `docs/SOLVER_SKILL_DESIGN.md`에 대한 skill 본문 참조 금지 검증 명령: ```powershell uv run --with pytest python -m pytest -v -rs ``` 개별 skill schema를 점검할 때는 현재 Codex 설치에 포함된 `skill-creator` validator를 사용하되 사용자 홈을 하드코딩한 경로를 프로젝트 계약으로 두지 않는다. ## v1 범위 - v1은 `SKILL.md`와 `agents/openai.yaml`만 포함한다. - 별도 `scripts/`, `references/`, `assets/`는 만들지 않는다. - 반복 사용 중 절차가 안정화되면 deterministic comparison script, reference artifact template, report template 같은 resource를 별도 후속 작업으로 분리한다. - 이 문서는 skill 구성을 설명하는 계획 문서이며, 실제 실행 지침의 source of truth는 각 `.codex/skills//SKILL.md`이다.