FESADev/docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md

# FESA Agent/Skill 개발 프로세스 통합 설계

## Metadata

- date: 2026-08-15
- status: approved-design
- scope: FESA 개발 workflow, custom agent, project-local skill, agent 산출물 배치

## 목표

FESA 기능 개발 workflow를 요구사항 단위로 단순화한다. 중복된 agent와 skill을 실제로
병합하고, `coordinator-agent`를 유일한 main agent로 두며, 모든 단계별 산출물을
`docs/<feature-id>/`에 모은다.

이 변경은 개발 운영 계약만 바꾼다. Solver C++ 구현, CMake/CTest target, Harness executor,
hook 동작, Abaqus reference artifact와 승인된 FEM 기능 계약은 변경하지 않는다.

## 핵심 결정

1. 기존 reference model 계약 준비 단계는 Numerical Review 단계에 병합한다.
2. 기존 Build/Test와 Reference Comparison 단계는 C++ Implementation 단계에 병합한다.
3. 병합된 단계의 agent와 skill도 각각 하나로 병합한다.
4. Agent 수를 줄이되 build/test와 reference comparison 증거 문서는 별도로 유지한다.
5. 모든 agent 산출물은 `docs/<feature-id>/` 아래에 둔다.
6. `coordinator-agent`는 main agent이고 나머지 agent는 Coordinator가 호출하는 sub-agent다.
7. `correction-agent`는 정규 단계가 아니라 반복되거나 원인이 불명확한 실패를 다루는
   재작업 sub-agent로 유지한다.

## 단순화된 개발 프로세스

| 단계 | 담당 sub-agent | 필수 skill | 산출물 |
| --- | --- | --- | --- |
| 1. 요구조건 | `requirement-agent` | `fesa-requirements-baseline` | `requirements.md` |
| 2. 연구 | `research-agent` | `fesa-research-evidence`, 필요 시 `fem-theory-query` | `research.md` |
| 3. 정식화 | `formulation-agent` | `fesa-formulation-spec` | `formulation.md` |
| 4. 수치 검토 + reference model 계약 | `numerical-review-agent` | 확장된 `fesa-numerical-review` | `numerical-review.md`, `reference-model.md` |
| 5. I/O 정의 | `io-definition-agent` | `fesa-io-contract` | `io.md` |
| 6. 구현 계획 + C++ 구현 + build/test + reference comparison | `implementation-planning-agent`, `implementation-agent` | 확장된 `fesa-cpp-msvc-tdd`와 계획 시 project-local `harness` | `implementation-plan.md`, `implementation-report.md`, `build-test.md`, `reference-comparison.md` |
| 7. 물리 검토 | `physics-evaluation-agent` | `fesa-physics-sanity` | `physics-evaluation.md` |
| 8. 배포 준비 | `release-agent` | `fesa-release-readiness` | `release.md` |

`coordinator-agent`는 위 단계 밖에서 전체 workflow와 handoff를 관리하고
`coordination.md`를 소유한다. `correction-agent`는 Coordinator가 재작업을 요청할 때만
`corrections.md`에 원인, 수정, 재검증 결과를 추가한다.

## Agent 통합

### Numerical Review 통합

`reference-model-agent`의 책임을 `numerical-review-agent`에 흡수하고
`.codex/agents/reference-model-agent.toml`을 제거한다.

병합된 Numerical Review Agent는 다음 두 판단을 함께 소유한다.

- 정식화의 차원, 부호, 좌표 변환, Jacobian, 적분, locking, rigid-body mode와 검증 준비도
- 기존 reference input/CSV의 존재, 비교량, blocking/warning 정책, source identity/component,
  row precheck와 승인된 tolerance

기존 Reference Model Agent가 I/O 문서를 입력으로 요구하던 순환 의존성은 제거한다.
`reference-model.md`는 exact input/CSV, 비교량, source identity/component와 tolerance를
확정한다. 다음 I/O 단계가 이를 소비해 `io.md`에서 최종 HDF5 dataset projection과 CSV
column mapping을 정의한다.

### Implementation 통합

`build-test-executor-agent`와 `reference-verification-agent`의 책임을
`implementation-agent`에 흡수하고 다음 파일을 제거한다.

- `.codex/agents/build-test-executor-agent.toml`
- `.codex/agents/reference-verification-agent.toml`

병합된 Implementation Agent는 한 단계 안에서 다음 순서를 완료한다.

```text
RED -> observed failure -> minimal GREEN -> focused VERIFY
    -> full MSVC x64 Debug build/CTest -> reference artifact check
    -> blocking/warning reference comparison -> report
```

하나의 agent가 수행하더라도 증거는 다음 세 문서로 분리한다.

- `implementation-report.md`: 구현 범위, RED/GREEN/VERIFY, 코드 변경과 traceability
- `build-test.md`: 환경, 명령, exit code, 실패 분류와 CTest 결과
- `reference-comparison.md`: artifact inventory, row identity, tolerance와 quantity별 결과

Implementation 단계의 최종 성공 상태는 `pass-for-physics-evaluation`이다. Compile, link,
ordinary test 또는 명확한 implementation-owned mismatch는 Implementation Agent가 먼저
수정한다. 같은 failure classification이 반복되거나 원인이 불명확하면 Coordinator가
`correction-agent`를 호출한다.

## Skill 통합

### Numerical Review skill

`fesa-reference-models`의 reference inventory, comparison scope, identity, row precheck,
tolerance와 handoff 계약을 `fesa-numerical-review`에 흡수한다. 다음 디렉터리를 제거한다.

- `.codex/skills/fesa-reference-models/`

확장된 `fesa-numerical-review`는 `numerical-review.md`와 `reference-model.md`를 모두
산출하고 I/O Definition Agent에 두 문서를 handoff한다.

### C++ TDD skill

`fesa-reference-comparison`의 `ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT`, deterministic
row matching, nonfinite/누락/추가/중복 row rejection과 tolerance 적용 계약을
`fesa-cpp-msvc-tdd`에 흡수한다. 다음 디렉터리를 제거한다.

- `.codex/skills/fesa-reference-comparison/`

확장된 `fesa-cpp-msvc-tdd`는 구현 계획, TDD 구현, MSVC build/CTest, failure correction과
reference comparison을 하나의 구현 단계 절차로 정의한다. Project-local `harness`의 계획
승인, phase materialization, executor와 hook 계약은 변경하지 않는다.

통합 후 FESA workflow skill은 다음 8개다.

- `fesa-requirements-baseline`
- `fesa-research-evidence`
- `fesa-formulation-spec`
- `fesa-numerical-review`
- `fesa-io-contract`
- `fesa-cpp-msvc-tdd`
- `fesa-physics-sanity`
- `fesa-release-readiness`

`fem-theory-query`와 project-local `harness`, `review`는 별도 보조 skill로 유지한다.

## Agent 계층과 Coordinator Orchestration

통합 후 `.codex/agents/`에는 main agent 1개와 sub-agent 10개가 남는다.

- main: `coordinator-agent`
- sub-agents: `requirement-agent`, `research-agent`, `formulation-agent`,
  `numerical-review-agent`, `io-definition-agent`, `implementation-planning-agent`,
  `implementation-agent`, `correction-agent`, `physics-evaluation-agent`, `release-agent`

Coordinator는 다음 순서로 동작한다.

```text
INTAKE -> STATE AUDIT -> WORKLIST UPDATE -> SUB-AGENT DISPATCH
       -> EVIDENCE CHECK -> GATE DECISION -> STATUS REPORT
```

Coordinator는 한 번에 다음 유효 단계의 owner만 호출한다. Sub-agent는 전달받은 단계와
산출물만 처리하고 peer agent를 직접 호출하거나 다음 단계로 진행하지 않는다. 완료 후
산출물 경로, status, 핵심 evidence, blocker를 Coordinator에 반환한다.

`docs/<feature-id>/coordination.md`는 다음 정보를 중심으로 작성한다.

- feature scope와 현재 목표
- 8단계 worklist
- 단계별 owner, 상태, 산출물 경로와 완료 evidence
- 현재 실행 중인 sub-agent와 다음 handoff
- blocker, 사용자 결정과 failure classification
- correction attempt count와 반복 실패 stop condition
- gate transition decision log와 최종 workflow closure

Worklist 항목 상태는 `pending | in-progress | passed | needs-rework | blocked`만 사용한다.
동일 failure classification이 두 번 반복되면 자동 재작업을 중단하고 전체 workflow를
`needs-user-decision` 또는 `blocked`로 전환한다.

## Gate 계약

1. Requirements gate: `requirements.md`가 승인된 범위, acceptance criteria, 검증량과
   tolerance를 가진다.
2. Research gate: `research.md`가 필요한 이론과 검증 evidence를 제공한다.
3. Formulation gate: `formulation.md`가 구현 가능한 수치 계약을 제공한다.
4. Numerical/reference gate: `numerical-review.md`와 `reference-model.md`가 모두 통과한다.
5. I/O gate: `io.md`가 reference identity를 authoritative HDF5 dataset과 연결한다.
6. Implementation gate: 구현 계획, RED/GREEN evidence, MSVC build/CTest와 blocking reference
   comparison이 모두 통과한다.
7. Physics gate: `physics-evaluation.md`가 `pass-for-release-agent`다.
8. Release gate: `release.md`가 `ready-for-release`이고 Coordinator가 closure를 기록한다.

## 요구사항 단위 산출물 구조

```text
docs/<feature-id>/
├── coordination.md
├── requirements.md
├── research.md
├── formulation.md
├── numerical-review.md
├── reference-model.md
├── io.md
├── implementation-plan.md
├── implementation-report.md
├── build-test.md
├── reference-comparison.md
├── corrections.md
├── physics-evaluation.md
└── release.md
```

산출물이 필요하지 않았거나 기존 workflow에서 생성되지 않은 경우 빈 placeholder 문서를
만들지 않는다. `corrections.md`는 실제 correction이 발생할 때만 생성한다.

## 기존 문서 마이그레이션

현재 agent별 폴더의 기능 문서를 다음 두 요구사항 폴더로 이동한다.

- `docs/linear-static-3d-euler-beam/`
- `docs/linear-static-mitc4-shell/`

파일 내용과 당시 `owner_agent`, status, numerical verdict는 역사적 evidence이므로 바꾸지
않는다. 내부 문서 경로만 새 위치로 갱신한다. 삭제된 agent 이름이 기존 evidence의
소유자로 기록된 경우도 그대로 보존한다.

기존 `docs/requirements/`, `docs/research/`, `docs/formulations/`,
`docs/numerical-reviews/`, `docs/io-definitions/`, `docs/reference-models/`,
`docs/implementation-plans/`, `docs/build-test-reports/`, `docs/corrections/`,
`docs/reference-verifications/`, `docs/physics-evaluations/`, `docs/releases/`,
`docs/coordination/`의 기능 문서와 필요한 내부 링크를 옮긴 뒤 agent별 README는 제거한다.
공통 운영 계약은 `AGENTS.md`, `docs/SOLVER_AGENT_DESIGN.md`,
`docs/SOLVER_SKILL_DESIGN.md`에 통합한다.

기존 두 기능은 `ready-for-release` evidence를 가지고 있으므로 새 `coordination.md`에서
`completed`로 inventory한다. 누락된 과거 산출물을 새 문서로 꾸미거나 새 workflow를
소급 실행하지 않는다.

다음 항목은 이동하거나 변경하지 않는다.

- `docs/PRD.md`, `docs/ARCHITECTURE.md`, `docs/ADR.md`
- `docs/reference-papers/`와 기타 공통 기술 문서
- `reference/` 아래의 Abaqus input/CSV artifact
- `phases/`의 실행 상태와 Harness 실행 결과 본문. 이동된 문서를 가리키는 path reference만
  기계적으로 갱신할 수 있다.
- Solver C++ source, tests, CMake/CTest configuration

## 문서와 참조 갱신

현재 실행 계약에서는 제거된 agent/skill과 기존 agent별 산출물 경로를 사용하지 않는다.
다음 파일군을 새 workflow와 `docs/<feature-id>/` 경로로 갱신한다.

- `AGENTS.md`
- `.codex/agents/*.toml`
- `.codex/skills/*/SKILL.md`와 대상 `agents/openai.yaml`
- `docs/SOLVER_AGENT_DESIGN.md`
- `docs/SOLVER_SKILL_DESIGN.md`
- 이동한 기능 문서의 내부 링크
- 기존 경로를 입력으로 사용하는 관련 계획, spec, phase 문서

역사적 산출물 본문에 기록된 과거 agent 이름과 status는 stale reference 검사 대상에서
제외하지만, 새 입력 경로를 가리키는 링크는 유효해야 한다.

## 검증 전략

`tests/test_agent_skill_workflow_contract.py`를 추가해 다음 정적 계약을 검증한다.

- 남은 agent 파일 집합이 main 1개와 sub-agent 10개인지 확인
- 제거 대상 agent 3개와 skill 2개가 존재하지 않는지 확인
- Coordinator가 main 역할과 `docs/<feature-id>/coordination.md` worklist를 정의하는지 확인
- 모든 다른 agent가 sub-agent 역할과 Coordinator handoff를 정의하는지 확인
- 병합 대상 skill의 핵심 workflow와 output contract가 destination skill에 존재하는지 확인
- 현재 실행 계약에 제거된 agent/skill 이름이나 기존 agent별 출력 경로가 없는지 확인
- 모든 TOML이 parse되고 각 skill의 frontmatter와 UI metadata가 유효한지 확인

검증 명령은 다음과 같다.

```powershell
uv run --with pytest python -m pytest -v -rs
python <skill-creator>/scripts/quick_validate.py .codex/skills/<remaining-skill>
git diff --check
```

`quick_validate.py`는 남아 있는 project-local skill 각각에 실행한다. 이번 변경은 C++
production과 CMake/CTest를 수정하지 않으므로 MSVC build와 CTest는 필수 검증 범위가 아니다.

## 완료 기준

- 8단계 workflow가 `AGENTS.md`, agent config와 설계 문서에서 동일하다.
- 삭제 대상 agent와 skill이 제거되고 모든 책임과 quality gate가 destination에 보존된다.
- `coordinator-agent`가 main agent로서 sub-agent dispatch와 worklist 갱신을 소유한다.
- 모든 새 산출물 경로가 `docs/<feature-id>/` 규칙을 따른다.
- 기존 기능 문서가 새 폴더에 모이고 역사적 verdict가 보존된다.
- 자동 계약 테스트, 전체 Python pytest, skill validation과 `git diff --check`가 통과한다.