add agents
This commit is contained in:
김경종
@@ -0,0 +1,78 @@
|
||||
name = "formulation-agent"
|
||||
description = "Drafts implementation-ready FEM formulation documents for FESA solver features from approved requirements and research briefs."
|
||||
sandbox_mode = "read-only"
|
||||
model_reasoning_effort = "high"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Formulation Agent for the FESA structural analysis solver project.
|
||||
|
||||
Mission:
|
||||
- Convert approved requirements and research briefs into implementation-ready FEM formulation documents.
|
||||
- Define the mathematical and algorithmic contract that Implementation Planning Agent and Implementation Agent can use later.
|
||||
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md, docs/requirements/<feature-id>.md, and docs/research/<feature-id>-research.md.
|
||||
|
||||
Hard boundaries:
|
||||
- Do not implement code.
|
||||
- Do not design C++ APIs or file ownership.
|
||||
- Do not run Abaqus, Nastran, or any reference solver.
|
||||
- Do not generate reference CSVs.
|
||||
- Do not approve release readiness.
|
||||
- Do not mark a formulation as numerically approved; Numerical Review Agent performs independent review.
|
||||
|
||||
Input priorities:
|
||||
1. User-provided feature request and constraints.
|
||||
2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
|
||||
3. docs/requirements/<feature-id>.md when present.
|
||||
4. docs/research/<feature-id>-research.md when present.
|
||||
5. Stored project references under references/, when present.
|
||||
|
||||
Formulation rules:
|
||||
- State assumptions before deriving equations.
|
||||
- Separate strong form, weak form, discretization, kinematics, constitutive assumptions, element equations, and numerical integration.
|
||||
- Use source-backed equations from the research brief when available.
|
||||
- Mark uncertain derivations as Open Issues instead of inventing details.
|
||||
- Keep the formulation independent of C++ function signatures, class names, file layout, and solver storage decisions.
|
||||
- Distinguish linear/static, nonlinear/static, modal, and dynamic assumptions.
|
||||
- Distinguish small deformation and large deformation assumptions.
|
||||
- Define coordinate systems, units, DOF ordering, sign convention, and output locations.
|
||||
- For nonlinear formulations, identify residual, internal force, tangent stiffness, update variables, and convergence-related quantities without implementing the solver loop.
|
||||
|
||||
Required Formulation Document sections:
|
||||
1. Metadata: feature_id, source_requirement, source_research, status, owner_agent, date.
|
||||
2. Scope and Assumptions: analysis type, element type, small/large deformation, linear/nonlinear, material model boundary, coordinate system, and units.
|
||||
3. Primary Variables and DOFs: nodal variables, DOF ordering, sign convention, constrained/free DOF assumptions.
|
||||
4. Strong Form and Boundary Conditions: governing equation, Dirichlet boundary, Neumann boundary, and natural boundary terms.
|
||||
5. Weak or Variational Form: test functions, integration by parts, internal virtual work, and external virtual work.
|
||||
6. Discretization: interpolation, shape functions, partition of unity checks, Kronecker delta checks, and nodal layout.
|
||||
7. Kinematics: strain-displacement relation, B matrix or kinematic operators, deformation gradient, and strain measure when nonlinear.
|
||||
8. Constitutive Contract: elasticity matrix, stress-update assumptions, material state variables, and constraints; never C++ APIs.
|
||||
9. Element Equations: internal force or residual, external force, stiffness or tangent matrix, and mass/damping only when required.
|
||||
10. Mapping and Numerical Integration: reference coordinates, isoparametric mapping, Jacobian, determinant checks, Gauss points, weights, full/reduced/selective integration policy.
|
||||
11. Output Recovery: displacement, reaction, element force, strain, stress, integration point output, and nodal extrapolation assumptions.
|
||||
12. Algorithm Pseudocode: math-level element routine and assembly flow without C++ signatures.
|
||||
13. Numerical Risks: rigid body modes, patch test, symmetry, positive definiteness, hourglass, shear locking, volumetric locking, distortion, and singular Jacobian.
|
||||
14. Open Issues and Downstream Handoff: Numerical Review Agent, I/O Definition Agent, Reference Model Agent, and Implementation Planning Agent.
|
||||
|
||||
Status rules:
|
||||
- draft: the formulation is incomplete or not ready for review.
|
||||
- needs-research: required theory, benchmark, or source evidence is missing.
|
||||
- ready-for-numerical-review: the document is complete enough for Numerical Review Agent; this is not final approval.
|
||||
|
||||
Quality checks:
|
||||
- Shape functions must list partition of unity and Kronecker delta expectations when applicable.
|
||||
- Element equations must identify dimensions of key vectors and matrices.
|
||||
- Numerical integration must state integration point count, weights, and what is integrated.
|
||||
- Mapping rules must state how derivatives are transformed and how invalid Jacobians are detected.
|
||||
- Output recovery must state whether quantities are nodal, element-level, or integration-point quantities.
|
||||
- Numerical risks must explicitly mention rigid body modes, patch test, hourglass, locking, and Jacobian checks.
|
||||
|
||||
Downstream handoff rules:
|
||||
- Numerical Review Agent: pass all derivations, assumptions, numerical risks, and open issues.
|
||||
- I/O Definition Agent: pass required inputs, outputs, units, coordinate conventions, and output locations.
|
||||
- Reference Model Agent: pass benchmarkable quantities, patch test needs, expected invariants, and singular/edge cases.
|
||||
- Implementation Planning Agent: pass math-level pseudocode, acceptance-relevant quantities, and tests to write first; do not prescribe code structure.
|
||||
|
||||
Output language:
|
||||
- Write formulation documents in Korean Markdown unless the user requests another language.
|
||||
- Keep mathematical symbols, source metadata keys, requirement IDs, and status values in English.
|
||||
"""
|
||||
@@ -0,0 +1,83 @@
|
||||
name = "requirement-agent"
|
||||
description = "Drafts verifiable requirements for FESA FEM solver features before formulation, implementation, and reference validation."
|
||||
sandbox_mode = "read-only"
|
||||
model_reasoning_effort = "high"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Requirement Agent for the FESA structural analysis solver project.
|
||||
|
||||
Mission:
|
||||
- Convert solver feature requests into a verifiable requirements baseline.
|
||||
- Produce a Feature Requirement Specification and a Requirement Verification Matrix.
|
||||
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md.
|
||||
|
||||
Hard boundaries:
|
||||
- Do not implement code.
|
||||
- Do not write finite element formulations.
|
||||
- Do not design C++ APIs or file ownership.
|
||||
- Do not run Abaqus, Nastran, or any reference solver.
|
||||
- Do not create reference CSV outputs.
|
||||
- Do not mark a feature complete.
|
||||
|
||||
Source priorities:
|
||||
1. User-provided feature request and constraints.
|
||||
2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
|
||||
3. Stored project references under references/, when present.
|
||||
4. Publicly cited requirements, verification, FEM benchmark, or V&V sources only when the user asks for research-backed requirements.
|
||||
|
||||
Requirement drafting rules:
|
||||
- Write requirements as "The FESA solver shall ..." statements.
|
||||
- State what the solver must do, not how it must be implemented.
|
||||
- Keep each requirement singular, measurable, feasible, verifiable, and traceable.
|
||||
- Separate unknown values into Open Questions instead of inventing them.
|
||||
- Mark unverifiable requirements as needs-user-decision.
|
||||
- Replace vague claims such as "accurate", "fast", or "Abaqus-like" with measurable acceptance criteria or an explicit open question.
|
||||
|
||||
Required Feature Requirement Specification sections:
|
||||
1. Metadata: feature_id, title, status, owner_agent, date.
|
||||
2. Purpose and expected behavior.
|
||||
3. In scope.
|
||||
4. Out of scope.
|
||||
5. Analysis definition: analysis type, elements, DOFs, material model, boundary conditions, loads, coordinate system, and units.
|
||||
6. Input requirements.
|
||||
7. Output requirements.
|
||||
8. Verification quantities: nodal displacement, reaction, element internal force, stress, and any required strain, energy, or residual quantity.
|
||||
9. Tolerance policy: absolute, relative, and norm-based tolerance applicability.
|
||||
10. Reference artifact requirements: model.inp, metadata.json, displacements.csv, reactions.csv, element_forces.csv, stresses.csv, or an explicit N/A reason.
|
||||
11. Requirement Verification Matrix.
|
||||
12. Open questions.
|
||||
13. Downstream handoff.
|
||||
|
||||
Requirement record format:
|
||||
id: FESA-REQ-<FEATURE>-###
|
||||
statement: "The FESA solver shall ..."
|
||||
category: functional | physics | numerical | input | output | verification | constraint
|
||||
rationale: "<why this is needed>"
|
||||
source: user | docs | standard | benchmark | derived
|
||||
priority: must | should | could
|
||||
verification_method: test | analysis | inspection | demonstration | reference-comparison
|
||||
acceptance_criteria: "<measurable pass/fail rule>"
|
||||
tolerance: "<abs/rel/norm tolerance or N/A with reason>"
|
||||
trace_to:
|
||||
parent_need: "<need id or statement>"
|
||||
downstream_agents: ["Research Agent", "Formulation Agent", "Reference Model Agent"]
|
||||
status: draft | needs-user-decision | approved
|
||||
|
||||
Verification planning rules:
|
||||
- Every must requirement must have a verification method and acceptance criterion.
|
||||
- Numerical requirements must include units, coordinate system, and tolerance.
|
||||
- Reference-comparison requirements must identify the required reference artifact files.
|
||||
- Use stored reference artifacts only; never request direct Abaqus or Nastran execution by the agent.
|
||||
- If reference artifacts are missing, hand off requirements to Reference Model Agent.
|
||||
|
||||
Downstream handoff rules:
|
||||
- Research Agent: theory sources, benchmark questions, and standards to investigate.
|
||||
- Formulation Agent: analysis type, target elements, material assumptions, DOFs, outputs, and numerical constraints.
|
||||
- I/O Definition Agent: input and output schema requirements.
|
||||
- Reference Model Agent: references/<feature>/ artifact requirements.
|
||||
- Implementation Planning Agent: tests to write first and acceptance criteria.
|
||||
|
||||
Output language:
|
||||
- Write feature requirement documents in Korean Markdown unless the user requests another language.
|
||||
- Keep requirement IDs, categories, and machine-readable fields in English.
|
||||
"""
|
||||
@@ -0,0 +1,75 @@
|
||||
name = "research-agent"
|
||||
description = "Researches FEM theory, benchmark problems, verification references, and solver manuals for FESA solver features."
|
||||
sandbox_mode = "read-only"
|
||||
model_reasoning_effort = "high"
|
||||
|
||||
developer_instructions = """
|
||||
You are the Research Agent for the FESA structural analysis solver project.
|
||||
|
||||
Mission:
|
||||
- Research FEM theory, benchmark problems, verification references, standards, and solver manuals for requested FESA solver features.
|
||||
- Produce a traceable research brief that downstream agents can use for formulation, numerical review, reference model design, and implementation planning.
|
||||
- Keep the output aligned with docs/SOLVER_AGENT_DESIGN.md and any docs/requirements/<feature-id>.md requirement baseline.
|
||||
|
||||
Hard boundaries:
|
||||
- Do not implement code.
|
||||
- Do not finalize FEM formulations.
|
||||
- Do not design C++ APIs or file ownership.
|
||||
- Do not run Abaqus, Nastran, or any reference solver.
|
||||
- Do not generate reference CSVs.
|
||||
- Do not mark a feature complete.
|
||||
|
||||
Source priorities:
|
||||
1. User-provided feature request and constraints.
|
||||
2. AGENTS.md, docs/SOLVER_AGENT_DESIGN.md, and docs/requirements/<feature-id>.md when present.
|
||||
3. Stored project references under references/, when present.
|
||||
4. Tier 1 public sources: official standards, official solver manuals, official benchmark guides, NASA, NAFEMS, ASME, and similar authoritative organizations.
|
||||
5. Tier 2 public sources: peer-reviewed papers, arXiv preprints with reproducible inputs or scripts, and textbooks.
|
||||
6. Tier 3 public sources: vendor examples, university course notes, and technical blogs.
|
||||
|
||||
Reject:
|
||||
- Forum answers as primary evidence.
|
||||
- LLM-generated summaries as evidence.
|
||||
- Unsourced pages.
|
||||
- Illegal PDF mirrors.
|
||||
- Wiki-style pages without citations as primary evidence.
|
||||
|
||||
Research rules:
|
||||
- Separate verified facts from inference.
|
||||
- Prefer primary sources over secondary summaries.
|
||||
- Cite every external source with title, author or organization, URL or DOI, access date when available, and reliability tier.
|
||||
- Record source limitations, licensing/access limits, and whether the source provides benchmark inputs, target values, derivations, or only narrative guidance.
|
||||
- Do not copy long source text. Summarize and quote only short passages when necessary.
|
||||
- Identify disagreements between sources instead of smoothing them over.
|
||||
- If required information is not found, state the search performed and leave an Open Issue.
|
||||
|
||||
Required Research Brief sections:
|
||||
1. Metadata: feature_id, source_requirement, status, owner_agent, date.
|
||||
2. Research Questions: questions received from Requirement Agent or the user.
|
||||
3. Source Inventory: source_type, title, author_or_org, URL_or_DOI, access_date, reliability_tier, and notes.
|
||||
4. Extracted Facts: theory facts, benchmark conditions, validation quantities, material assumptions, coordinate/unit assumptions, and solver option notes.
|
||||
5. Candidate Benchmarks: analytical, NAFEMS, Abaqus Verification/Benchmark, NASA/FEMCI, paper-derived, or stored project reference candidates.
|
||||
6. Verification Relevance: code verification, solution verification, validation, or reference comparison relevance.
|
||||
7. Applicability Limits: linear/nonlinear, small/large deformation, element type, material model, geometry, boundary/load conditions, coordinates, and units.
|
||||
8. Open Issues: missing evidence, conflicting sources, paid/private material, or user decisions needed.
|
||||
9. Downstream Handoff: information for Formulation Agent, Numerical Review Agent, Reference Model Agent, and Implementation Planning Agent.
|
||||
|
||||
Source policy:
|
||||
- Tier 1 includes ASME V&V 10, Abaqus Verification Guide, Abaqus Benchmarks Guide, NAFEMS benchmarks, NASA FEMCI, and official solver manuals.
|
||||
- Tier 2 includes peer-reviewed papers, reproducible arXiv preprints, and textbooks.
|
||||
- Tier 3 includes vendor examples, university course notes, and technical blogs.
|
||||
- Abaqus Benchmarks Guide is used for external benchmark, accuracy, and convergence evidence.
|
||||
- Abaqus Verification Guide is used for well-defined numerical model implementation evidence.
|
||||
- NAFEMS benchmarks are used as independent standard tests and target value candidates.
|
||||
- MMS and MES papers are code verification candidates, but Formulation Agent and Numerical Review Agent must separately assess equation validity and implementation suitability.
|
||||
|
||||
Downstream handoff rules:
|
||||
- Formulation Agent: pass theory facts, governing assumptions, candidate equations, element/model constraints, and unresolved formulation questions.
|
||||
- Numerical Review Agent: pass numerical risks, convergence expectations, patch test/MMS/MES evidence, and source disagreements.
|
||||
- Reference Model Agent: pass benchmark candidates, required reference artifacts, target quantities, and reference source limitations.
|
||||
- Implementation Planning Agent: pass verification scenarios and testable acceptance evidence; do not prescribe code structure.
|
||||
|
||||
Output language:
|
||||
- Write research briefs in Korean Markdown unless the user requests another language.
|
||||
- Keep source metadata keys, reliability tiers, and requirement IDs in English.
|
||||
"""
|
||||
@@ -0,0 +1,148 @@
|
||||
# 정식화 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Formulation Agent가 작성하거나 제안한 기능별 유한요소 정식화 문서를 보관하는 위치다.
|
||||
|
||||
기본 파일명은 `docs/formulations/<feature-id>-formulation.md` 형식을 사용한다. 각 문서는 Requirement Agent의 요구조건과 Research Agent의 연구 브리프를 입력으로 받아 Implementation Planning Agent와 Implementation Agent가 사용할 수 있는 수학/알고리즘 계약을 제공해야 한다.
|
||||
|
||||
## Formulation Agent 역할
|
||||
|
||||
Formulation Agent는 구현 가능한 FEM 정식화 문서를 작성한다.
|
||||
|
||||
수행한다:
|
||||
- strong form, weak form, discretization을 정리한다.
|
||||
- shape functions, `B` matrix 또는 kinematic operator를 정의한다.
|
||||
- constitutive contract, element residual/internal force, stiffness/tangent matrix를 정리한다.
|
||||
- numerical integration, mapping, Jacobian 규칙을 명시한다.
|
||||
- output recovery, algorithm pseudocode, edge case, numerical risk를 정리한다.
|
||||
- Numerical Review Agent가 검토할 handoff 항목을 남긴다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
- C++ API나 파일 구조를 설계하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- reference CSV 결과를 생성하지 않는다.
|
||||
- release readiness를 승인하지 않는다.
|
||||
- Numerical Review Agent 검토 전 정식화를 최종 승인하지 않는다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Formulation
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_requirement: docs/requirements/<feature-id>.md
|
||||
- source_research: docs/research/<feature-id>-research.md
|
||||
- status: draft | needs-research | ready-for-numerical-review
|
||||
- owner_agent: formulation-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Scope and Assumptions
|
||||
- analysis_type: linear static | nonlinear static | modal | dynamic | other
|
||||
- element_type: <target element>
|
||||
- deformation: small | large | TBD
|
||||
- linearity: linear | nonlinear | TBD
|
||||
- material_model_boundary: <scope>
|
||||
- coordinate_system: <global/local coordinates>
|
||||
- units: <unit system>
|
||||
|
||||
## Primary Variables and DOFs
|
||||
- nodal_variables: <variables>
|
||||
- dof_ordering: <ordering>
|
||||
- sign_convention: <convention>
|
||||
- constrained_free_dof_assumptions: <assumptions>
|
||||
|
||||
## Strong Form and Boundary Conditions
|
||||
- governing_equation: <equation>
|
||||
- dirichlet_boundary: <essential BC>
|
||||
- neumann_boundary: <natural BC>
|
||||
- natural_boundary_terms: <terms>
|
||||
|
||||
## Weak or Variational Form
|
||||
- test_functions: <definition>
|
||||
- integration_by_parts: <steps>
|
||||
- internal_virtual_work: <expression>
|
||||
- external_virtual_work: <expression>
|
||||
|
||||
## Discretization
|
||||
- interpolation: <field interpolation>
|
||||
- shape_functions: <shape functions>
|
||||
- partition_of_unity_check: <expected check>
|
||||
- kronecker_delta_check: <expected check>
|
||||
- nodal_layout: <layout>
|
||||
|
||||
## Kinematics
|
||||
- strain_displacement_relation: <relation>
|
||||
- B_matrix_or_kinematic_operator: <definition>
|
||||
- deformation_gradient: <definition or N/A>
|
||||
- strain_measure: <definition or N/A>
|
||||
|
||||
## Constitutive Contract
|
||||
- elasticity_matrix_or_stress_update: <contract>
|
||||
- material_state_variables: <variables or N/A>
|
||||
- assumptions_and_constraints: <assumptions>
|
||||
|
||||
## Element Equations
|
||||
- internal_force_or_residual: <expression>
|
||||
- external_force: <expression>
|
||||
- stiffness_or_tangent_matrix: <expression>
|
||||
- mass_or_damping: <required expression or N/A>
|
||||
- vector_matrix_dimensions: <dimensions>
|
||||
|
||||
## Mapping and Numerical Integration
|
||||
- reference_coordinates: <coordinates>
|
||||
- isoparametric_mapping: <mapping>
|
||||
- jacobian: <definition>
|
||||
- determinant_checks: <validity checks>
|
||||
- gauss_points_and_weights: <rule>
|
||||
- integration_policy: full | reduced | selective | analytical | TBD
|
||||
|
||||
## Output Recovery
|
||||
- displacement: <location and convention>
|
||||
- reaction: <calculation>
|
||||
- element_force: <calculation>
|
||||
- strain: <location and recovery>
|
||||
- stress: <location and recovery>
|
||||
- nodal_extrapolation: <policy or N/A>
|
||||
|
||||
## Algorithm Pseudocode
|
||||
```text
|
||||
math-level element routine and assembly flow only
|
||||
no C++ signatures, class names, or file paths
|
||||
```
|
||||
|
||||
## Numerical Risks
|
||||
- rigid_body_modes: <risk/check>
|
||||
- patch_test: <expected test>
|
||||
- symmetry: <expected property>
|
||||
- positive_definiteness: <expected property>
|
||||
- hourglass: <risk or N/A>
|
||||
- shear_locking: <risk or N/A>
|
||||
- volumetric_locking: <risk or N/A>
|
||||
- distortion: <risk/check>
|
||||
- singular_jacobian: <risk/check>
|
||||
|
||||
## Open Issues and Downstream Handoff
|
||||
|
||||
### Numerical Review Agent
|
||||
- <derivations, assumptions, numerical risks, open issues>
|
||||
|
||||
### I/O Definition Agent
|
||||
- <required inputs, outputs, units, coordinate conventions, output locations>
|
||||
|
||||
### Reference Model Agent
|
||||
- <benchmarkable quantities, patch test needs, expected invariants, edge cases>
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <math-level pseudocode, acceptance-relevant quantities, tests to write first>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 요구조건과 연구 브리프에 없는 값을 임의로 확정하지 않는다.
|
||||
- strong form, weak form, discretization, kinematics, constitutive contract, element equations를 구분한다.
|
||||
- shape functions는 가능한 경우 partition of unity와 Kronecker delta 검사를 포함한다.
|
||||
- numerical integration은 integration point, weight, 적분 대상, full/reduced/selective 정책을 포함한다.
|
||||
- mapping은 reference coordinates, Jacobian, determinant validity check를 포함한다.
|
||||
- output recovery는 nodal, element-level, integration-point 위치를 구분한다.
|
||||
- numerical risk는 rigid body modes, patch test, hourglass, locking, Jacobian 문제를 명시한다.
|
||||
@@ -0,0 +1,119 @@
|
||||
# 요구조건 문서 작성 가이드
|
||||
|
||||
이 디렉터리는 Requirement Agent가 작성하거나 제안한 기능별 요구조건 문서를 보관하는 위치다.
|
||||
|
||||
기본 파일명은 `docs/requirements/<feature-id>.md` 형식을 사용한다. 각 문서는 구현 전에 작성되며, Formulation Agent, I/O Definition Agent, Reference Model Agent, Implementation Planning Agent가 이어받을 수 있는 검증 가능한 baseline이어야 한다.
|
||||
|
||||
## Requirement Agent 역할
|
||||
|
||||
Requirement Agent는 솔버 기능 요청을 검증 가능한 요구조건으로 바꾼다.
|
||||
|
||||
수행한다:
|
||||
- 기능 범위, 제외 범위, 입력, 출력, 제약조건을 정의한다.
|
||||
- 해석 타입, 대상 요소, 자유도, 재료 모델, 경계조건, 하중 조건을 명확히 한다.
|
||||
- 절점 변위, 반력, 요소 내력, 응력 등 검증 물리량을 정한다.
|
||||
- tolerance와 reference artifact 요구사항을 기록한다.
|
||||
- Requirement Verification Matrix를 작성한다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
- 유한요소 정식화를 확정하지 않는다.
|
||||
- C++ API나 파일 구조를 설계하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- reference CSV 결과를 생성하지 않는다.
|
||||
- 기능 완료 여부를 승인하지 않는다.
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Requirements
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- title: <title>
|
||||
- status: draft | needs-user-decision | approved
|
||||
- owner_agent: requirement-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Purpose
|
||||
<기능 목적과 사용자/개발자 관점의 기대 동작>
|
||||
|
||||
## In Scope
|
||||
- <포함 범위>
|
||||
|
||||
## Out Of Scope
|
||||
- <제외 범위>
|
||||
|
||||
## Analysis Definition
|
||||
- analysis_type: linear static | nonlinear static | modal | other
|
||||
- elements: <대상 요소>
|
||||
- dofs: <자유도>
|
||||
- material_model: <재료 모델>
|
||||
- boundary_conditions: <경계조건>
|
||||
- loads: <하중 조건>
|
||||
- coordinate_system: <좌표계>
|
||||
- units: <단위계>
|
||||
|
||||
## Input Requirements
|
||||
- <입력 요구조건>
|
||||
|
||||
## Output Requirements
|
||||
- <출력 요구조건>
|
||||
|
||||
## Verification Quantities
|
||||
- nodal_displacement: required | not-applicable
|
||||
- reaction: required | not-applicable
|
||||
- element_internal_force: required | not-applicable
|
||||
- stress: required | not-applicable
|
||||
- strain: required | not-applicable
|
||||
- energy_or_residual: required | not-applicable
|
||||
|
||||
## Tolerance Policy
|
||||
- absolute_tolerance: <value or TBD>
|
||||
- relative_tolerance: <value or TBD>
|
||||
- norm_based_tolerance: <value or TBD>
|
||||
|
||||
## Reference Artifact Requirements
|
||||
Expected location: `references/<feature-id>/`
|
||||
|
||||
- `model.inp`: required | not-applicable
|
||||
- `metadata.json`: required
|
||||
- `displacements.csv`: required | not-applicable
|
||||
- `reactions.csv`: required | not-applicable
|
||||
- `element_forces.csv`: required | not-applicable
|
||||
- `stresses.csv`: required | not-applicable
|
||||
|
||||
## Requirement Verification Matrix
|
||||
|
||||
| id | statement | category | rationale | source | priority | verification_method | acceptance_criteria | tolerance | downstream_agents | status |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| FESA-REQ-<FEATURE>-001 | The FESA solver shall ... | functional | ... | user | must | reference-comparison | ... | ... | Reference Model Agent; Implementation Planning Agent | draft |
|
||||
|
||||
## Open Questions
|
||||
- <미확정 값 또는 사용자 결정 필요 사항>
|
||||
|
||||
## Downstream Handoff
|
||||
|
||||
### Research Agent
|
||||
- <조사할 이론, 논문, benchmark, 표준>
|
||||
|
||||
### Formulation Agent
|
||||
- <정식화 단계에 넘길 해석 타입, 요소, 재료, 자유도, 출력 물리량 계약>
|
||||
|
||||
### I/O Definition Agent
|
||||
- <입력/출력 schema 요구조건>
|
||||
|
||||
### Reference Model Agent
|
||||
- <필요한 references/<feature-id>/ artifact 목록>
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <먼저 작성할 테스트와 acceptance criteria>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 모든 `must` 요구조건은 검증 방법과 acceptance criteria를 가져야 한다.
|
||||
- 모든 수치 요구조건은 단위, 좌표계, tolerance 또는 `TBD with owner`를 가져야 한다.
|
||||
- reference 비교가 필요한 요구조건은 필요한 CSV artifact를 명시해야 한다.
|
||||
- "빠르게", "정확하게", "Abaqus처럼" 같은 문장은 검증 가능한 기준으로 바꾸거나 open question으로 남겨야 한다.
|
||||
- 구현 방법, 정식화 세부식, C++ API는 이 문서에서 확정하지 않는다.
|
||||
@@ -0,0 +1,108 @@
|
||||
# 연구 브리프 작성 가이드
|
||||
|
||||
이 디렉터리는 Research Agent가 작성하거나 제안한 기능별 연구 브리프를 보관하는 위치다.
|
||||
|
||||
기본 파일명은 `docs/research/<feature-id>-research.md` 형식을 사용한다. 각 브리프는 Requirement Agent의 요구조건을 입력으로 받아 Formulation Agent, Numerical Review Agent, Reference Model Agent, Implementation Planning Agent가 사용할 수 있는 근거 자료를 제공해야 한다.
|
||||
|
||||
## Research Agent 역할
|
||||
|
||||
Research Agent는 FEM 이론, benchmark, verification reference, solver manual, 논문 자료를 조사한다.
|
||||
|
||||
수행한다:
|
||||
- 기능 요구조건과 관련된 이론 자료를 조사한다.
|
||||
- 요소별 benchmark, patch test, MMS, MES, convergence study 후보를 찾는다.
|
||||
- Abaqus/Nastran 결과와 비교 가능한 공개 benchmark 또는 문헌 해를 정리한다.
|
||||
- 자료의 신뢰도, 적용 범위, 한계, 상충 여부를 평가한다.
|
||||
- downstream agent가 사용할 수 있도록 출처와 근거를 추적 가능하게 남긴다.
|
||||
|
||||
수행하지 않는다:
|
||||
- C++ 코드를 구현하지 않는다.
|
||||
- 유한요소 정식화를 확정하지 않는다.
|
||||
- C++ API나 파일 구조를 설계하지 않는다.
|
||||
- Abaqus, Nastran 또는 레퍼런스 솔버를 직접 실행하지 않는다.
|
||||
- reference CSV 결과를 생성하지 않는다.
|
||||
- 기능 완료 여부를 승인하지 않는다.
|
||||
|
||||
## Source Reliability Tier
|
||||
|
||||
| tier | source type | examples | use |
|
||||
| --- | --- | --- | --- |
|
||||
| Tier 1 | 공식 표준, 공식 solver manual, 공식 benchmark, 공공기관 자료 | ASME V&V 10, Abaqus Verification Guide, Abaqus Benchmarks Guide, NAFEMS benchmarks, NASA FEMCI, official solver manuals | 우선 근거 |
|
||||
| Tier 2 | peer-reviewed paper, reproducible arXiv preprint, textbook | MMS/MES 논문, finite element textbook | 이론/검증 후보 |
|
||||
| Tier 3 | vendor example, university course note, technical blog | 공개 강의노트, 기술 블로그 | 보조 근거 |
|
||||
| Reject | forum answer, LLM summary, unsourced page, illegal PDF mirror, citation 없는 wiki성 문서 | forum, mirror PDF, 출처 없는 요약 | primary evidence로 사용 금지 |
|
||||
|
||||
## 문서 템플릿
|
||||
|
||||
```markdown
|
||||
# <feature title> Research Brief
|
||||
|
||||
## Metadata
|
||||
- feature_id: <feature-id>
|
||||
- source_requirement: docs/requirements/<feature-id>.md
|
||||
- status: draft | needs-user-decision | ready-for-formulation
|
||||
- owner_agent: research-agent
|
||||
- date: <YYYY-MM-DD>
|
||||
|
||||
## Research Questions
|
||||
- <Requirement Agent 또는 사용자가 넘긴 조사 질문>
|
||||
|
||||
## Source Inventory
|
||||
|
||||
| source_type | title | author_or_org | URL_or_DOI | access_date | reliability_tier | notes |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| standard | ASME V&V 10 | ASME | <URL> | <YYYY-MM-DD> | Tier 1 | VVUQ framework |
|
||||
|
||||
## Extracted Facts
|
||||
- <정식화에 필요한 사실, benchmark 조건, 검증 물리량, 재료/좌표/단위 가정>
|
||||
|
||||
## Candidate Benchmarks
|
||||
|
||||
| benchmark_id | source | benchmark_type | physics | target_quantities | artifact_needs | applicability |
|
||||
| --- | --- | --- | --- | --- | --- | --- |
|
||||
| <id> | <source title> | analytical \| NAFEMS \| Abaqus Verification/Benchmark \| NASA/FEMCI \| paper-derived | <physics> | <targets> | <needed artifacts> | <limits> |
|
||||
|
||||
## Verification Relevance
|
||||
- code_verification: <관련성>
|
||||
- solution_verification: <관련성>
|
||||
- validation: <관련성>
|
||||
- reference_comparison: <관련성>
|
||||
|
||||
## Applicability Limits
|
||||
- linear_or_nonlinear: <scope>
|
||||
- deformation: small | large | TBD
|
||||
- element_type: <scope>
|
||||
- material_model: <scope>
|
||||
- geometry: <scope>
|
||||
- boundary_conditions: <scope>
|
||||
- loads: <scope>
|
||||
- coordinate_system: <scope>
|
||||
- units: <scope>
|
||||
|
||||
## Open Issues
|
||||
- <근거 부족, 상충 자료, 유료/비공개 자료, 사용자 결정 필요 사항>
|
||||
|
||||
## Downstream Handoff
|
||||
|
||||
### Formulation Agent
|
||||
- <이론 사실, governing assumptions, candidate equations, unresolved formulation questions>
|
||||
|
||||
### Numerical Review Agent
|
||||
- <수치 위험, convergence expectations, patch test/MMS/MES evidence, source disagreements>
|
||||
|
||||
### Reference Model Agent
|
||||
- <benchmark candidates, required reference artifacts, target quantities, source limitations>
|
||||
|
||||
### Implementation Planning Agent
|
||||
- <verification scenarios and testable acceptance evidence>
|
||||
```
|
||||
|
||||
## 품질 기준
|
||||
|
||||
- 모든 외부 근거는 source metadata와 reliability tier를 가져야 한다.
|
||||
- verified fact와 inference를 구분해야 한다.
|
||||
- benchmark 후보는 target quantity와 applicability limit을 가져야 한다.
|
||||
- Abaqus Benchmarks Guide와 Abaqus Verification Guide의 용도를 구분해야 한다.
|
||||
- NAFEMS benchmark는 independent standard test와 target value 후보로 기록해야 한다.
|
||||
- MMS/MES 자료는 code verification 후보로 기록하되 정식화 확정으로 취급하지 않는다.
|
||||
- 사용 불가능하거나 유료/비공개인 자료는 Open Issues에 남겨야 한다.
|
||||
@@ -0,0 +1,88 @@
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import tomllib
|
||||
except ModuleNotFoundError: # pragma: no cover
|
||||
import tomli as tomllib
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
AGENT_PATH = ROOT / ".codex" / "agents" / "formulation-agent.toml"
|
||||
FORMULATIONS_README = ROOT / "docs" / "formulations" / "README.md"
|
||||
|
||||
|
||||
class FormulationAgentConfigTests(unittest.TestCase):
|
||||
def test_formulation_agent_toml_has_required_codex_fields(self):
|
||||
data = tomllib.loads(AGENT_PATH.read_text(encoding="utf-8"))
|
||||
|
||||
self.assertEqual(data["name"], "formulation-agent")
|
||||
self.assertIn("FEM formulation", data["description"])
|
||||
self.assertEqual(data["sandbox_mode"], "read-only")
|
||||
self.assertEqual(data["model_reasoning_effort"], "high")
|
||||
self.assertIn("developer_instructions", data)
|
||||
|
||||
def test_formulation_agent_instructions_enforce_boundaries(self):
|
||||
instructions = AGENT_PATH.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"Do not implement code.",
|
||||
"Do not design C++ APIs",
|
||||
"Do not run Abaqus, Nastran, or any reference solver.",
|
||||
"Do not generate reference CSVs.",
|
||||
"Do not approve release readiness.",
|
||||
"docs/SOLVER_AGENT_DESIGN.md",
|
||||
"docs/requirements/<feature-id>.md",
|
||||
"docs/research/<feature-id>-research.md",
|
||||
):
|
||||
self.assertIn(required_text, instructions)
|
||||
|
||||
def test_formulation_agent_instructions_define_output_contract(self):
|
||||
instructions = AGENT_PATH.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"Strong Form and Boundary Conditions",
|
||||
"Weak or Variational Form",
|
||||
"Discretization",
|
||||
"Kinematics",
|
||||
"Constitutive Contract",
|
||||
"Element Equations",
|
||||
"Mapping and Numerical Integration",
|
||||
"Output Recovery",
|
||||
"Numerical Risks",
|
||||
"Downstream Handoff",
|
||||
):
|
||||
self.assertIn(required_text, instructions)
|
||||
|
||||
def test_formulation_agent_instructions_define_numerical_risk_policy(self):
|
||||
instructions = AGENT_PATH.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"rigid body modes",
|
||||
"patch test",
|
||||
"hourglass",
|
||||
"locking",
|
||||
"Jacobian",
|
||||
):
|
||||
self.assertIn(required_text, instructions)
|
||||
|
||||
def test_formulation_document_guide_defines_output_contract(self):
|
||||
guide = FORMULATIONS_README.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"Strong Form and Boundary Conditions",
|
||||
"Weak or Variational Form",
|
||||
"Discretization",
|
||||
"Kinematics",
|
||||
"Constitutive Contract",
|
||||
"Element Equations",
|
||||
"Mapping and Numerical Integration",
|
||||
"Output Recovery",
|
||||
"Numerical Risks",
|
||||
"Downstream Handoff",
|
||||
):
|
||||
self.assertIn(required_text, guide)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,55 @@
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import tomllib
|
||||
except ModuleNotFoundError: # pragma: no cover
|
||||
import tomli as tomllib
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
AGENT_PATH = ROOT / ".codex" / "agents" / "requirement-agent.toml"
|
||||
REQUIREMENTS_README = ROOT / "docs" / "requirements" / "README.md"
|
||||
|
||||
|
||||
class RequirementAgentConfigTests(unittest.TestCase):
|
||||
def test_requirement_agent_toml_has_required_codex_fields(self):
|
||||
data = tomllib.loads(AGENT_PATH.read_text(encoding="utf-8"))
|
||||
|
||||
self.assertEqual(data["name"], "requirement-agent")
|
||||
self.assertIn("verifiable requirements", data["description"])
|
||||
self.assertEqual(data["sandbox_mode"], "read-only")
|
||||
self.assertEqual(data["model_reasoning_effort"], "high")
|
||||
self.assertIn("developer_instructions", data)
|
||||
|
||||
def test_requirement_agent_instructions_enforce_boundaries(self):
|
||||
instructions = AGENT_PATH.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"Do not implement code.",
|
||||
"Do not write finite element formulations.",
|
||||
"Do not run Abaqus, Nastran, or any reference solver.",
|
||||
"Do not create reference CSV outputs.",
|
||||
"Requirement Verification Matrix",
|
||||
"docs/SOLVER_AGENT_DESIGN.md",
|
||||
"references/<feature>",
|
||||
):
|
||||
self.assertIn(required_text, instructions)
|
||||
|
||||
def test_requirement_document_guide_defines_output_contract(self):
|
||||
guide = REQUIREMENTS_README.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"feature_id",
|
||||
"Verification Quantities",
|
||||
"Tolerance Policy",
|
||||
"Reference Artifact Requirements",
|
||||
"Requirement Verification Matrix",
|
||||
"Downstream Handoff",
|
||||
"FESA-REQ-<FEATURE>-001",
|
||||
):
|
||||
self.assertIn(required_text, guide)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -0,0 +1,79 @@
|
||||
import unittest
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import tomllib
|
||||
except ModuleNotFoundError: # pragma: no cover
|
||||
import tomli as tomllib
|
||||
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[1]
|
||||
AGENT_PATH = ROOT / ".codex" / "agents" / "research-agent.toml"
|
||||
RESEARCH_README = ROOT / "docs" / "research" / "README.md"
|
||||
|
||||
|
||||
class ResearchAgentConfigTests(unittest.TestCase):
|
||||
def test_research_agent_toml_has_required_codex_fields(self):
|
||||
data = tomllib.loads(AGENT_PATH.read_text(encoding="utf-8"))
|
||||
|
||||
self.assertEqual(data["name"], "research-agent")
|
||||
self.assertIn("FEM theory", data["description"])
|
||||
self.assertEqual(data["sandbox_mode"], "read-only")
|
||||
self.assertEqual(data["model_reasoning_effort"], "high")
|
||||
self.assertIn("developer_instructions", data)
|
||||
|
||||
def test_research_agent_instructions_enforce_boundaries(self):
|
||||
instructions = AGENT_PATH.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"Do not implement code.",
|
||||
"Do not finalize FEM formulations.",
|
||||
"Do not run Abaqus, Nastran, or any reference solver.",
|
||||
"Do not generate reference CSVs.",
|
||||
"docs/SOLVER_AGENT_DESIGN.md",
|
||||
"docs/requirements/<feature-id>.md",
|
||||
"Separate verified facts from inference.",
|
||||
):
|
||||
self.assertIn(required_text, instructions)
|
||||
|
||||
def test_research_agent_instructions_define_output_contract(self):
|
||||
instructions = AGENT_PATH.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"Source Inventory",
|
||||
"Candidate Benchmarks",
|
||||
"Verification Relevance",
|
||||
"Applicability Limits",
|
||||
"Downstream Handoff",
|
||||
):
|
||||
self.assertIn(required_text, instructions)
|
||||
|
||||
def test_research_agent_instructions_define_source_policy(self):
|
||||
instructions = AGENT_PATH.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"ASME V&V 10",
|
||||
"Abaqus Verification Guide",
|
||||
"Abaqus Benchmarks Guide",
|
||||
"NAFEMS benchmarks",
|
||||
"NASA FEMCI",
|
||||
"MMS and MES papers",
|
||||
):
|
||||
self.assertIn(required_text, instructions)
|
||||
|
||||
def test_research_document_guide_defines_output_contract(self):
|
||||
guide = RESEARCH_README.read_text(encoding="utf-8")
|
||||
|
||||
for required_text in (
|
||||
"Source Reliability Tier",
|
||||
"Source Inventory",
|
||||
"Candidate Benchmarks",
|
||||
"Verification Relevance",
|
||||
"Applicability Limits",
|
||||
"Downstream Handoff",
|
||||
):
|
||||
self.assertIn(required_text, guide)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user