From 31b1ebb25db550a3c8e9097fcabc3dd5cb5863ca Mon Sep 17 00:00:00 2001 From: "KOKO\\Mimi" Date: Sat, 15 Aug 2026 01:08:55 +0900 Subject: [PATCH] docs: define consolidated agent workflow --- ...ent-skill-workflow-consolidation-design.md | 276 ++++++++++++++++++ 1 file changed, 276 insertions(+) create mode 100644 docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md diff --git a/docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md b/docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md new file mode 100644 index 0000000..03ed122 --- /dev/null +++ b/docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md @@ -0,0 +1,276 @@ +# 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//`에 모은다. + +이 변경은 개발 운영 계약만 바꾼다. 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//` 아래에 둔다. +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//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// +├── 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//` 경로로 갱신한다. + +- `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//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 /scripts/quick_validate.py .codex/skills/ +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//` 규칙을 따른다. +- 기존 기능 문서가 새 폴더에 모이고 역사적 verdict가 보존된다. +- 자동 계약 테스트, 전체 Python pytest, skill validation과 `git diff --check`가 통과한다.