diff --git a/docs/superpowers/plans/2026-08-15-agent-skill-workflow-consolidation.md b/docs/superpowers/plans/2026-08-15-agent-skill-workflow-consolidation.md new file mode 100644 index 0000000..3edf881 --- /dev/null +++ b/docs/superpowers/plans/2026-08-15-agent-skill-workflow-consolidation.md @@ -0,0 +1,1157 @@ +# FESA Agent/Skill Workflow Consolidation Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Consolidate the FESA development workflow into eight stages, merge three redundant agents and two redundant skills into their approved owners, make `coordinator-agent` the main orchestrator, and group all feature evidence under `docs//`. + +**Architecture:** Keep one main Coordinator and ten specialist sub-agents. Merge reference-model preparation into Numerical Review and merge build/test plus reference comparison into Implementation, while retaining separate evidence documents for auditability. Migrate existing feature documents without rewriting historical owners or verdicts, and protect the resulting structure with repository-level Python contract tests. + +**Tech Stack:** Codex agent TOML, project-local Codex `SKILL.md` and `agents/openai.yaml`, Markdown workflow contracts, Python 3 standard library (`pathlib`, `tomllib`), pytest, PowerShell, Git. + +## Global Constraints + +- The approved design is `docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md`. +- All new feature evidence lives under exactly `docs//`. +- Keep separate `implementation-report.md`, `build-test.md`, and `reference-comparison.md` files even though one Implementation Agent owns them. +- Keep separate `numerical-review.md` and `reference-model.md` files even though one Numerical Review Agent owns them. +- `coordinator-agent` is the only main agent; every other `.codex/agents/*.toml` profile is a sub-agent. +- Keep `correction-agent` as an on-demand rework sub-agent outside the eight numbered stages. +- Preserve `model_reasoning_effort = "extra high"` in every agent profile. +- Preserve historical document content, `owner_agent`, status, and numerical verdict; only relocate files and repair path references. +- Do not create empty evidence files for outputs that never existed. Create `corrections.md` only after a real correction. +- Do not modify solver C++ source, C++ tests, CMake/CTest configuration, `.codex/hooks.json`, Harness executor behavior, phase status/result content, or `reference/` artifacts. +- Keep project-local `harness` planning/execution boundaries unchanged. +- Use conventional commit messages. + +--- + +## Final File Map + +### Create + +- `tests/test_agent_skill_workflow_contract.py`: static contract tests for agent inventory, skill inventory, hierarchy, merged responsibilities, output layout, and live-path cleanup. +- `docs/linear-static-3d-euler-beam/coordination.md`: migrated feature worklist and closure inventory. +- `docs/linear-static-mitc4-shell/coordination.md`: migrated feature worklist and closure inventory. + +### Modify + +- `AGENTS.md`: eight-stage process, consolidated agent/skill table, main/sub-agent policy, and `docs//` layout. +- `.codex/agents/coordinator-agent.toml`: main-agent orchestration, dispatch loop, worklist, gate decisions, and rework control. +- `.codex/agents/requirement-agent.toml`: sub-agent contract, new paths, and Numerical Review handoff for reference evidence. +- `.codex/agents/research-agent.toml`: sub-agent contract, new paths, and Numerical Review handoff for reference candidates. +- `.codex/agents/formulation-agent.toml`: sub-agent contract, new paths, and consolidated Numerical Review handoff. +- `.codex/agents/numerical-review-agent.toml`: numerical review plus reference-model ownership. +- `.codex/agents/io-definition-agent.toml`: sub-agent contract and final HDF5 projection ownership after merged review. +- `.codex/agents/implementation-planning-agent.toml`: new paths, consolidated skill inputs, and Implementation-only downstream validation handoff. +- `.codex/agents/implementation-agent.toml`: TDD implementation, MSVC build/CTest, reference comparison, and three-document evidence ownership. +- `.codex/agents/correction-agent.toml`: on-demand rework from Implementation evidence and return to Implementation. +- `.codex/agents/physics-evaluation-agent.toml`: consume Implementation-owned reference comparison and route model gaps to Numerical Review. +- `.codex/agents/release-agent.toml`: audit consolidated Implementation evidence and new paths. +- `.codex/skills/fesa-numerical-review/SKILL.md`: absorb reference-case inventory and readiness workflow. +- `.codex/skills/fesa-numerical-review/agents/openai.yaml`: describe consolidated numerical/reference review. +- `.codex/skills/fesa-cpp-msvc-tdd/SKILL.md`: absorb build/test reporting and reference comparison workflow. +- `.codex/skills/fesa-cpp-msvc-tdd/agents/openai.yaml`: describe consolidated implementation/verification work. +- `.codex/skills/fesa-requirements-baseline/SKILL.md`: new output path and Numerical Review handoff. +- `.codex/skills/fesa-research-evidence/SKILL.md`: new output path and Numerical Review handoff. +- `.codex/skills/fesa-formulation-spec/SKILL.md`: new output path and consolidated handoff. +- `.codex/skills/fesa-io-contract/SKILL.md`: new output path and final HDF5/reference mapping responsibility. +- `.codex/skills/fesa-physics-sanity/SKILL.md`: new paths and consolidated failure routing. +- `.codex/skills/fesa-release-readiness/SKILL.md`: new paths and consolidated gate evidence. +- `docs/SOLVER_AGENT_DESIGN.md`: surviving roles, eight-stage flowchart, gates, status transitions, and output layout. +- `docs/SOLVER_SKILL_DESIGN.md`: eight workflow skills and consolidated agent-to-skill mapping. +- Moved feature documents and tracked plan/spec/phase documents containing old feature-document paths: repair path references only. + +### Delete after absorption + +- `.codex/agents/reference-model-agent.toml` +- `.codex/agents/build-test-executor-agent.toml` +- `.codex/agents/reference-verification-agent.toml` +- `.codex/skills/fesa-reference-models/` +- `.codex/skills/fesa-reference-comparison/` +- Agent-oriented output-folder README files under `docs/coordination/`, `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/`, and `docs/releases/`. + +--- + +### Task 1: Add RED workflow-contract tests + +**Files:** + +- Create: `tests/test_agent_skill_workflow_contract.py` +- Read: `docs/superpowers/specs/2026-08-15-agent-skill-workflow-consolidation-design.md` + +**Interfaces:** + +- Consumes: approved agent names, skill names, feature folders, artifact filenames, and mandatory contract phrases from the design. +- Produces: pytest functions used as acceptance gates by Tasks 2–6. + +- [ ] **Step 1: Create the static contract test module** + +Add this complete test module: + +```python +from pathlib import Path +import tomllib + + +ROOT = Path(__file__).resolve().parents[1] +AGENT_DIR = ROOT / ".codex" / "agents" +SKILL_DIR = ROOT / ".codex" / "skills" + +EXPECTED_AGENTS = { + "coordinator-agent", + "correction-agent", + "formulation-agent", + "implementation-agent", + "implementation-planning-agent", + "io-definition-agent", + "numerical-review-agent", + "physics-evaluation-agent", + "release-agent", + "requirement-agent", + "research-agent", +} + +EXPECTED_SKILLS = { + "fem-theory-query", + "fesa-cpp-msvc-tdd", + "fesa-formulation-spec", + "fesa-io-contract", + "fesa-numerical-review", + "fesa-physics-sanity", + "fesa-release-readiness", + "fesa-requirements-baseline", + "fesa-research-evidence", +} + +LEGACY_OUTPUT_DIRS = { + "coordination", + "requirements", + "research", + "formulations", + "numerical-reviews", + "io-definitions", + "reference-models", + "implementation-plans", + "build-test-reports", + "corrections", + "reference-verifications", + "physics-evaluations", + "releases", +} + +FEATURE_FILES = { + "linear-static-3d-euler-beam": { + "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", + "physics-evaluation.md", + "release.md", + }, + "linear-static-mitc4-shell": { + "coordination.md", + "requirements.md", + "research.md", + "formulation.md", + "numerical-review.md", + "reference-model.md", + "io.md", + "implementation-plan.md", + "build-test.md", + "reference-comparison.md", + "physics-evaluation.md", + "release.md", + }, +} + +LIVE_CONTRACT_FILES = ( + ROOT / "AGENTS.md", + ROOT / "docs" / "SOLVER_AGENT_DESIGN.md", + ROOT / "docs" / "SOLVER_SKILL_DESIGN.md", +) + +RETIRED_TOKENS = ( + "reference-model-agent", + "reference model agent", + "build-test-executor-agent", + "build/test executor agent", + "reference-verification-agent", + "reference verification agent", + "fesa-reference-models", + "fesa-reference-comparison", + "docs/coordination/", + "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/", +) + + +def read(path: Path) -> str: + return path.read_text(encoding="utf-8") + + +def live_contract_text() -> str: + paths = list(LIVE_CONTRACT_FILES) + paths.extend(sorted(AGENT_DIR.glob("*.toml"))) + paths.extend(sorted(SKILL_DIR.glob("*/SKILL.md"))) + return "\n".join(read(path) for path in paths) + + +def test_agent_inventory_is_consolidated(): + actual = {path.stem for path in AGENT_DIR.glob("*.toml")} + assert actual == EXPECTED_AGENTS + + +def test_project_skill_inventory_is_consolidated(): + actual = { + path.name + for path in SKILL_DIR.iterdir() + if path.is_dir() and (path / "SKILL.md").is_file() + } + assert actual == EXPECTED_SKILLS + + +def test_existing_feature_artifacts_are_bundled(): + docs_dir = ROOT / "docs" + for legacy_dir in LEGACY_OUTPUT_DIRS: + assert not (docs_dir / legacy_dir).exists(), legacy_dir + + for feature_id, expected_files in FEATURE_FILES.items(): + feature_dir = docs_dir / feature_id + actual_files = {path.name for path in feature_dir.glob("*.md")} + assert actual_files == expected_files + + +def test_numerical_review_absorbs_reference_model_contract(): + assert not (AGENT_DIR / "reference-model-agent.toml").exists() + assert not (SKILL_DIR / "fesa-reference-models").exists() + text = read(SKILL_DIR / "fesa-numerical-review" / "SKILL.md").lower() + for marker in ( + "numerical-review.md", + "reference-model.md", + "reference case inventory", + "source identity", + "row precheck", + "tolerance", + "pass-for-io-definition", + ): + assert marker in text + + +def test_implementation_absorbs_build_test_and_reference_comparison(): + assert not (AGENT_DIR / "build-test-executor-agent.toml").exists() + assert not (AGENT_DIR / "reference-verification-agent.toml").exists() + assert not (SKILL_DIR / "fesa-reference-comparison").exists() + text = read(SKILL_DIR / "fesa-cpp-msvc-tdd" / "SKILL.md").lower() + for marker in ( + "implementation-report.md", + "build-test.md", + "reference-comparison.md", + "artifact check -> compare -> classify -> report", + "pass-for-physics-evaluation", + ): + assert marker in text + + +def test_agent_hierarchy_is_explicit(): + coordinator = read(AGENT_DIR / "coordinator-agent.toml").lower() + assert "main agent" in coordinator + assert "docs//coordination.md" in coordinator + assert "worklist" in coordinator + assert "sub-agent dispatch" in coordinator + + for path in sorted(AGENT_DIR.glob("*.toml")): + if path.name == "coordinator-agent.toml": + continue + text = read(path).lower() + assert "sub-agent" in text, path.name + assert "coordinator agent" in text, path.name + + +def test_live_contracts_have_no_retired_names_or_paths(): + text = live_contract_text().lower() + assert "docs//" in text + for token in RETIRED_TOKENS: + assert token not in text, token + + +def test_live_guidance_declares_eight_stage_workflow(): + for path in LIVE_CONTRACT_FILES: + text = read(path) + assert "8단계" in text, path + assert "docs//" in text, path + + +def test_agent_toml_and_skill_ui_metadata_are_parseable(): + for path in sorted(AGENT_DIR.glob("*.toml")): + parsed = tomllib.loads(read(path)) + assert parsed["name"] == path.stem + assert parsed["model_reasoning_effort"] == "extra high" + + for skill_name in EXPECTED_SKILLS: + skill_dir = SKILL_DIR / skill_name + skill_text = read(skill_dir / "SKILL.md") + ui_text = read(skill_dir / "agents" / "openai.yaml") + assert f"name: {skill_name}" in skill_text + assert f"${skill_name}" in ui_text +``` + +- [ ] **Step 2: Run each new behavior test and record RED evidence** + +Run: + +```powershell +uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py -v +``` + +Expected: `test_agent_toml_and_skill_ui_metadata_are_parseable` passes. The other eight tests fail because the old agents, old skills, old document folders, old paths, old stage count, and non-hierarchical agent contracts still exist. + +- [ ] **Step 3: Commit the RED contract tests** + +```powershell +git add tests/test_agent_skill_workflow_contract.py +git commit -m "test: define consolidated agent workflow contract" +``` + +--- + +### Task 2: Migrate existing evidence into feature folders + +**Files:** + +- Create: `docs/linear-static-3d-euler-beam/coordination.md` +- Create: `docs/linear-static-mitc4-shell/coordination.md` +- Move: the 23 existing feature evidence files listed below. +- Delete: the 13 old agent-oriented README files after their common policy is covered by the approved design and later live-contract updates. +- Test: `tests/test_agent_skill_workflow_contract.py::test_existing_feature_artifacts_are_bundled` + +**Interfaces:** + +- Consumes: existing Markdown evidence with historical statuses and the final filename map. +- Produces: canonical `docs//` bundles consumed by every surviving agent and skill. + +- [ ] **Step 1: Create and verify the two explicit target directories** + +Run: + +```powershell +$targets = @( + (Resolve-Path -LiteralPath 'docs').Path + '\linear-static-3d-euler-beam', + (Resolve-Path -LiteralPath 'docs').Path + '\linear-static-mitc4-shell' +) +$docsRoot = (Resolve-Path -LiteralPath 'docs').Path +foreach ($target in $targets) { + if (-not $target.StartsWith($docsRoot + '\')) { throw "Target escaped docs: $target" } + New-Item -ItemType Directory -Path $target -Force | Out-Null +} +``` + +Expected: both resolved targets are direct children of `C:\git\FESADev\docs`. + +- [ ] **Step 2: Move the Euler beam evidence using this exact mapping** + +```powershell +Move-Item -LiteralPath 'docs\requirements\linear-static-3d-euler-beam.md' -Destination 'docs\linear-static-3d-euler-beam\requirements.md' +Move-Item -LiteralPath 'docs\research\linear-static-3d-euler-beam-research.md' -Destination 'docs\linear-static-3d-euler-beam\research.md' +Move-Item -LiteralPath 'docs\formulations\3d-isoparametric-euler-beam-formulation.md' -Destination 'docs\linear-static-3d-euler-beam\formulation.md' +Move-Item -LiteralPath 'docs\numerical-reviews\linear-static-3d-euler-beam-review.md' -Destination 'docs\linear-static-3d-euler-beam\numerical-review.md' +Move-Item -LiteralPath 'docs\reference-models\linear-static-3d-euler-beam-reference-models.md' -Destination 'docs\linear-static-3d-euler-beam\reference-model.md' +Move-Item -LiteralPath 'docs\io-definitions\linear-static-3d-euler-beam-io.md' -Destination 'docs\linear-static-3d-euler-beam\io.md' +Move-Item -LiteralPath 'docs\implementation-plans\linear-static-3d-euler-beam.md' -Destination 'docs\linear-static-3d-euler-beam\implementation-plan.md' +Move-Item -LiteralPath 'docs\implementation-plans\linear-static-3d-euler-beam-implementation-report.md' -Destination 'docs\linear-static-3d-euler-beam\implementation-report.md' +Move-Item -LiteralPath 'docs\build-test-reports\linear-static-3d-euler-beam.md' -Destination 'docs\linear-static-3d-euler-beam\build-test.md' +Move-Item -LiteralPath 'docs\reference-verifications\linear-static-3d-euler-beam-reference-verification.md' -Destination 'docs\linear-static-3d-euler-beam\reference-comparison.md' +Move-Item -LiteralPath 'docs\physics-evaluations\linear-static-3d-euler-beam-physics-evaluation.md' -Destination 'docs\linear-static-3d-euler-beam\physics-evaluation.md' +Move-Item -LiteralPath 'docs\releases\linear-static-3d-euler-beam-release.md' -Destination 'docs\linear-static-3d-euler-beam\release.md' +``` + +Expected: all 12 sources disappear and all 12 destinations exist without content rewriting. + +- [ ] **Step 3: Move the MITC4 evidence using this exact mapping** + +```powershell +Move-Item -LiteralPath 'docs\requirements\linear-static-mitc4-shell.md' -Destination 'docs\linear-static-mitc4-shell\requirements.md' +Move-Item -LiteralPath 'docs\research\linear-static-mitc4-shell-research.md' -Destination 'docs\linear-static-mitc4-shell\research.md' +Move-Item -LiteralPath 'docs\formulations\mitc4-shell-formulation.md' -Destination 'docs\linear-static-mitc4-shell\formulation.md' +Move-Item -LiteralPath 'docs\numerical-reviews\linear-static-mitc4-shell-review.md' -Destination 'docs\linear-static-mitc4-shell\numerical-review.md' +Move-Item -LiteralPath 'docs\reference-models\linear-static-mitc4-shell-reference-models.md' -Destination 'docs\linear-static-mitc4-shell\reference-model.md' +Move-Item -LiteralPath 'docs\io-definitions\linear-static-mitc4-shell-io.md' -Destination 'docs\linear-static-mitc4-shell\io.md' +Move-Item -LiteralPath 'docs\implementation-plans\linear-static-mitc4-shell-implementation-plan.md' -Destination 'docs\linear-static-mitc4-shell\implementation-plan.md' +Move-Item -LiteralPath 'docs\build-test-reports\linear-static-mitc4-shell-build-test.md' -Destination 'docs\linear-static-mitc4-shell\build-test.md' +Move-Item -LiteralPath 'docs\reference-verifications\linear-static-mitc4-shell-reference-verification.md' -Destination 'docs\linear-static-mitc4-shell\reference-comparison.md' +Move-Item -LiteralPath 'docs\physics-evaluations\linear-static-mitc4-shell-physics-evaluation.md' -Destination 'docs\linear-static-mitc4-shell\physics-evaluation.md' +Move-Item -LiteralPath 'docs\releases\linear-static-mitc4-shell-release.md' -Destination 'docs\linear-static-mitc4-shell\release.md' +``` + +Expected: all 11 sources disappear and all 11 destinations exist. Do not create `implementation-report.md` because no historical MITC4 implementation report exists. + +- [ ] **Step 4: Add the Euler beam coordination inventory** + +Create `docs/linear-static-3d-euler-beam/coordination.md` with this evidence, preserving the already-approved release verdict: + +```markdown +# Linear Static 3D Euler Beam Coordination Report + +## Metadata + +- feature_id: linear-static-3d-euler-beam +- status: completed +- owner_agent: coordinator-agent +- date: 2026-08-15 +- migration_note: Existing evidence was relocated without rerunning workflow gates. + +## Worklist + +| stage | owner | status | evidence | +| --- | --- | --- | --- | +| 1. requirements | requirement-agent | passed | `requirements.md` | +| 2. research | research-agent | passed | `research.md` | +| 3. formulation | formulation-agent | passed | `formulation.md` | +| 4. numerical and reference | numerical-review-agent | passed | `numerical-review.md`; `reference-model.md` | +| 5. I/O | io-definition-agent | passed | `io.md` | +| 6. implementation and verification | implementation-planning-agent; implementation-agent | passed | `implementation-plan.md`; `implementation-report.md`; `build-test.md`; `reference-comparison.md` | +| 7. physics | physics-evaluation-agent | passed | `physics-evaluation.md` | +| 8. release | release-agent | passed | `release.md` | + +## Current Progress + +- active_sub_agent: none +- next_handoff: none +- closure_evidence: `release.md` status `ready-for-release` +- workflow_disposition: completed + +## Decision Log + +| date | decision | evidence | rationale | +| --- | --- | --- | --- | +| 2026-08-15 | Record migrated workflow as completed | `release.md` | Preserve the existing release verdict without retroactive gate execution. | + +## Blockers and Rework + +- active_blockers: none +- correction_attempt_count: 0 +- needs_user_decision: false +``` + +- [ ] **Step 5: Add the MITC4 coordination inventory** + +Create `docs/linear-static-mitc4-shell/coordination.md` with this content: + +```markdown +# Linear Static MITC4 Shell Coordination Report + +## Metadata + +- feature_id: linear-static-mitc4-shell +- status: completed +- owner_agent: coordinator-agent +- date: 2026-08-15 +- migration_note: Existing evidence was relocated without rerunning workflow gates. + +## Worklist + +| stage | owner | status | evidence | +| --- | --- | --- | --- | +| 1. requirements | requirement-agent | passed | `requirements.md` | +| 2. research | research-agent | passed | `research.md` | +| 3. formulation | formulation-agent | passed | `formulation.md` | +| 4. numerical and reference | numerical-review-agent | passed | `numerical-review.md`; `reference-model.md` | +| 5. I/O | io-definition-agent | passed | `io.md` | +| 6. implementation and verification | implementation-planning-agent; implementation-agent | passed | `implementation-plan.md`; `build-test.md`; `reference-comparison.md` | +| 7. physics | physics-evaluation-agent | passed | `physics-evaluation.md` | +| 8. release | release-agent | passed | `release.md` | + +## Current Progress + +- active_sub_agent: none +- next_handoff: none +- closure_evidence: `release.md` status `ready-for-release` +- workflow_disposition: completed +- historical_gap: No standalone `implementation-report.md` existed before migration; no replacement was fabricated. + +## Decision Log + +| date | decision | evidence | rationale | +| --- | --- | --- | --- | +| 2026-08-15 | Record migrated workflow as completed | `release.md` | Preserve the existing release verdict without retroactive gate execution. | + +## Blockers and Rework + +- active_blockers: none +- correction_attempt_count: 0 +- needs_user_decision: false +``` + +- [ ] **Step 6: Remove the old output-folder README files** + +Delete only these files with `apply_patch`; do not recursively delete directories: + +```text +docs/coordination/README.md +docs/requirements/README.md +docs/research/README.md +docs/formulations/README.md +docs/numerical-reviews/README.md +docs/io-definitions/README.md +docs/reference-models/README.md +docs/implementation-plans/README.md +docs/build-test-reports/README.md +docs/corrections/README.md +docs/reference-verifications/README.md +docs/physics-evaluations/README.md +docs/releases/README.md +``` + +- [ ] **Step 7: Run the bundle contract test** + +Run: + +```powershell +uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py::test_existing_feature_artifacts_are_bundled -v +``` + +Expected: PASS. Broken links are allowed temporarily and are repaired in Task 6. + +- [ ] **Step 8: Commit the evidence migration** + +```powershell +git add -A docs/linear-static-3d-euler-beam docs/linear-static-mitc4-shell docs/coordination 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 +git commit -m "docs: group solver evidence by feature" +``` + +--- + +### Task 3: Merge Reference Model into Numerical Review + +**Files:** + +- Modify: `.codex/agents/numerical-review-agent.toml:1` +- Delete: `.codex/agents/reference-model-agent.toml` +- Modify: `.codex/skills/fesa-numerical-review/SKILL.md:1` +- Modify: `.codex/skills/fesa-numerical-review/agents/openai.yaml:1` +- Delete: `.codex/skills/fesa-reference-models/SKILL.md` +- Delete: `.codex/skills/fesa-reference-models/agents/openai.yaml` +- Test: `tests/test_agent_skill_workflow_contract.py::test_numerical_review_absorbs_reference_model_contract` + +**Interfaces:** + +- Consumes: `requirements.md`, `research.md`, `formulation.md`, stored `reference/` artifacts, and the approved tolerance contract. +- Produces: `numerical-review.md` and `reference-model.md` with status `pass-for-io-definition` when both reviews pass. + +- [ ] **Step 1: Expand the Numerical Review Agent mission and inputs** + +In `.codex/agents/numerical-review-agent.toml`, retain all math/numerical checks and add these exact responsibilities: + +```text +- Act as a sub-agent dispatched by Coordinator Agent for the consolidated numerical/reference gate. +- Inventory exact existing reference input and required CSV paths without modifying them. +- Define blocking and warning-only quantities, source identity/components, row prechecks, and approved tolerance. +- Produce docs//numerical-review.md and docs//reference-model.md. +- Hand both reports to I/O Definition Agent through Coordinator Agent. +``` + +Use this input order: + +```text +1. Coordinator handoff and user constraints. +2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md. +3. docs//requirements.md. +4. docs//research.md. +5. docs//formulation.md. +6. Existing stored reference artifacts under reference/, read-only. +``` + +The agent must not require `io.md`. It defines logical quantities and source identity; I/O Definition owns the final HDF5 dataset projection. + +- [ ] **Step 2: Define the two-document output and statuses** + +Keep the existing Numerical Review report sections and add a separate Reference Model report contract with: + +```text +Metadata +Reference Acceptance Scope +Reference Case Inventory +Source Identity and Component Contract +Row Prechecks +Tolerance and Blocking/Warning Policy +Open Issues and I/O Handoff +``` + +Use only these consolidated statuses: + +```text +pass-for-io-definition +needs-formulation-revision +needs-research +needs-reference-artifacts +needs-user-decision +blocked +``` + +- [ ] **Step 3: Merge the two skill workflows** + +Update `.codex/skills/fesa-numerical-review/SKILL.md` so its frontmatter description triggers for both numerical review and reference-case readiness. Its workflow must include: + +```text +FORMULATION REVIEW -> REFERENCE CASE INVENTORY -> CLASSIFY -> REPORT -> I/O HANDOFF +``` + +The Output Contract must name: + +```text +docs//numerical-review.md +docs//reference-model.md +``` + +Absorb exact-path inventory, blocking/warning quantities, source identity/component matching, +missing/extra/duplicate/nonfinite row prechecks, approved tolerance, and read-only artifact boundaries +from the retiring skill. Do not include final HDF5 dataset paths; route that mapping to I/O Definition. + +- [ ] **Step 4: Regenerate the consolidated skill UI metadata** + +Run: + +```powershell +$generator = Join-Path $env:USERPROFILE '.codex\skills\.system\skill-creator\scripts\generate_openai_yaml.py' +python $generator '.codex\skills\fesa-numerical-review' ` + --interface 'display_name=FESA Numerical and Reference Review' ` + --interface 'short_description=Review numerical and reference readiness' ` + --interface 'default_prompt=Use $fesa-numerical-review to review FESA numerical and reference-model readiness.' +``` + +Expected: `agents/openai.yaml` contains the three quoted interface values and the default prompt names `$fesa-numerical-review`. + +- [ ] **Step 5: Delete the absorbed agent and skill files** + +Delete the three retiring files with `apply_patch`: + +```text +.codex/agents/reference-model-agent.toml +.codex/skills/fesa-reference-models/SKILL.md +.codex/skills/fesa-reference-models/agents/openai.yaml +``` + +The empty `.codex/skills/fesa-reference-models/` directory then disappears from Git. + +- [ ] **Step 6: Run the focused consolidation test** + +Run: + +```powershell +uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py::test_numerical_review_absorbs_reference_model_contract -v +``` + +Expected: PASS. + +- [ ] **Step 7: Commit the numerical/reference consolidation** + +```powershell +git add -A .codex/agents/numerical-review-agent.toml .codex/agents/reference-model-agent.toml .codex/skills/fesa-numerical-review .codex/skills/fesa-reference-models +git commit -m "refactor: merge reference model into numerical review" +``` + +--- + +### Task 4: Merge Build/Test and Reference Comparison into Implementation + +**Files:** + +- Modify: `.codex/agents/implementation-agent.toml:1` +- Delete: `.codex/agents/build-test-executor-agent.toml` +- Delete: `.codex/agents/reference-verification-agent.toml` +- Modify: `.codex/skills/fesa-cpp-msvc-tdd/SKILL.md:1` +- Modify: `.codex/skills/fesa-cpp-msvc-tdd/agents/openai.yaml:1` +- Delete: `.codex/skills/fesa-reference-comparison/SKILL.md` +- Delete: `.codex/skills/fesa-reference-comparison/agents/openai.yaml` +- Test: `tests/test_agent_skill_workflow_contract.py::test_implementation_absorbs_build_test_and_reference_comparison` +- Test: `tests/test_agent_skill_workflow_contract.py::test_agent_inventory_is_consolidated` +- Test: `tests/test_agent_skill_workflow_contract.py::test_project_skill_inventory_is_consolidated` + +**Interfaces:** + +- Consumes: `implementation-plan.md`, all upstream feature documents, generated `results.h5`, exact reference input/CSV paths, `.harness/config.json`, and the unchanged Harness execution contract. +- Produces: `implementation-report.md`, `build-test.md`, and `reference-comparison.md`; success hands `pass-for-physics-evaluation` to Coordinator. + +- [ ] **Step 1: Expand the Implementation Agent execution contract** + +In `.codex/agents/implementation-agent.toml`, preserve the current Harness Step ownership rules and replace the downstream-only validation handoff with this full sequence: + +```text +RED -> OBSERVED FAILURE -> MINIMAL GREEN -> FOCUSED VERIFY + -> FULL MSVC BUILD/CTEST -> ARTIFACT CHECK + -> COMPARE -> CLASSIFY -> REPORT +``` + +Add exact ownership of: + +```text +docs//implementation-report.md +docs//build-test.md +docs//reference-comparison.md +``` + +The agent remains forbidden from modifying requirements, formulation, numerical/reference contracts, +I/O contracts, tolerance policies, declared inputs, or Abaqus reference CSV files. + +- [ ] **Step 2: Absorb Build/Test reporting** + +Move these requirements from the retiring Build/Test profile into Implementation: + +```text +- Resolve commands from .harness/config.json first, then project defaults. +- Record command, exit code, duration, stdout/stderr tail, failed test names, and environment. +- Classify configure, compile, link, test, reference-comparison, harness, environment, and upstream-contract failures. +- Stop after the first decisive failure unless the implementation plan explicitly requires another diagnostic command. +- Preserve MSVC x64 Debug and CTest command order. +``` + +`build-test.md` keeps the historical Build/Test report sections but sets `owner_agent: implementation-agent`. + +- [ ] **Step 3: Absorb Reference Comparison reporting** + +Move these requirements from the retiring Reference Verification profile into Implementation: + +```text +ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT +``` + +Require exact declared input/CSV paths, generated `results.h5`, HDF5 projection from `io.md`, +source identity/component matching, row uniqueness/finite checks, and approved tolerance. Reject +missing, extra, duplicate, and nonfinite required rows before tolerance. Preserve warning-only behavior. + +Use these final statuses: + +```text +in-progress +pass-for-physics-evaluation +needs-correction +needs-reference-artifacts +needs-environment-fix +needs-upstream-decision +blocked +``` + +- [ ] **Step 4: Expand `fesa-cpp-msvc-tdd`** + +Update its frontmatter and body to cover planning, TDD implementation, build/test reporting, +correction, and reference comparison. The Output Contract must name: + +```text +docs//implementation-plan.md +docs//implementation-report.md +docs//build-test.md +docs//reference-comparison.md +docs//corrections.md +``` + +Include the literal workflow marker used by the test: + +```text +ARTIFACT CHECK -> COMPARE -> CLASSIFY -> REPORT +``` + +Send `pass-for-physics-evaluation` evidence to Physics Evaluation Agent through Coordinator Agent. + +- [ ] **Step 5: Regenerate the consolidated skill UI metadata** + +Run: + +```powershell +$generator = Join-Path $env:USERPROFILE '.codex\skills\.system\skill-creator\scripts\generate_openai_yaml.py' +python $generator '.codex\skills\fesa-cpp-msvc-tdd' ` + --interface 'display_name=FESA C++ TDD and Verification' ` + --interface 'short_description=Implement and verify FESA C++ work' ` + --interface 'default_prompt=Use $fesa-cpp-msvc-tdd to plan, implement, build, test, and reference-verify FESA C++ work.' +``` + +Expected: the default prompt explicitly names `$fesa-cpp-msvc-tdd`. + +- [ ] **Step 6: Delete the absorbed agent and skill files** + +Delete with `apply_patch`: + +```text +.codex/agents/build-test-executor-agent.toml +.codex/agents/reference-verification-agent.toml +.codex/skills/fesa-reference-comparison/SKILL.md +.codex/skills/fesa-reference-comparison/agents/openai.yaml +``` + +- [ ] **Step 7: Run focused agent/skill inventory tests** + +Run: + +```powershell +uv run --with pytest python -m pytest ` + tests/test_agent_skill_workflow_contract.py::test_implementation_absorbs_build_test_and_reference_comparison ` + tests/test_agent_skill_workflow_contract.py::test_agent_inventory_is_consolidated ` + tests/test_agent_skill_workflow_contract.py::test_project_skill_inventory_is_consolidated -v +``` + +Expected: all three tests PASS. + +- [ ] **Step 8: Commit the implementation/verification consolidation** + +```powershell +git add -A .codex/agents/implementation-agent.toml .codex/agents/build-test-executor-agent.toml .codex/agents/reference-verification-agent.toml .codex/skills/fesa-cpp-msvc-tdd .codex/skills/fesa-reference-comparison +git commit -m "refactor: merge implementation verification workflow" +``` + +--- + +### Task 5: Make Coordinator the main orchestrator and normalize all sub-agent contracts + +**Files:** + +- Modify: `.codex/agents/coordinator-agent.toml:1` +- Modify: every ten surviving sub-agent TOML files under `.codex/agents/`. +- Modify: all eight surviving `fesa-*` `SKILL.md` files under `.codex/skills/`. +- Test: `tests/test_agent_skill_workflow_contract.py::test_agent_hierarchy_is_explicit` + +**Interfaces:** + +- Consumes: consolidated stage owners and canonical feature-document paths from Tasks 2–4. +- Produces: one main-agent dispatch protocol and ten bounded sub-agent return contracts. + +- [ ] **Step 1: Rewrite the Coordinator mission and execution loop** + +In `.codex/agents/coordinator-agent.toml`, identify it with the exact phrase `main agent` and define: + +```text +INTAKE -> STATE AUDIT -> WORKLIST UPDATE -> SUB-AGENT DISPATCH + -> EVIDENCE CHECK -> GATE DECISION -> STATUS REPORT +``` + +Require `docs//coordination.md`, the eight-stage worklist, and these work-item statuses: + +```text +pending | in-progress | passed | needs-rework | blocked +``` + +Each dispatch package must contain: + +```text +feature_id +target_sub_agent +required_inputs +expected_outputs +acceptance_gate +stop_condition +missing_evidence +``` + +Coordinator must update `coordination.md` before dispatch and after evidence return. It must not +perform specialist math review, code implementation, build/test, comparison, physics, or release +judgment itself. + +- [ ] **Step 2: Replace obsolete Coordinator states and routes** + +Remove these intermediate routes and statuses: + +```text +needs-reference-model +needs-build-test +needs-reference-verification +pass-for-reference-verification +``` + +Use this live workflow state set: + +```text +intake +needs-requirements +needs-research +needs-formulation +needs-numerical-review +needs-io-definition +needs-implementation-plan +ready-for-implementation +needs-implementation +needs-correction +needs-physics-evaluation +needs-release +ready-for-release +completed +needs-user-decision +blocked +``` + +Route reference artifact/tolerance gaps to Numerical Review, HDF5 projection gaps to I/O Definition, +compile/test/comparison failures to Implementation first, and repeated or unclear implementation +failures to Correction. Stop automatic rework when the same classification reaches two attempts. + +- [ ] **Step 3: Mark all specialist profiles as sub-agents** + +Add this invariant to every surviving non-Coordinator TOML: + +```text +- You are a sub-agent dispatched by Coordinator Agent. +- Work only on the assigned stage and declared docs// outputs. +- Do not dispatch peer agents or advance the workflow yourself. +- Return output paths, status, evidence summary, and blockers to Coordinator Agent. +``` + +Preserve each profile's technical hard boundaries and `model_reasoning_effort = "extra high"`. + +- [ ] **Step 4: Normalize surviving agent paths and handoffs** + +Apply these exact path/owner changes: + +| Agent | Reads | Writes or returns | +| --- | --- | --- | +| Requirement | `docs//requirements.md` when revising | `requirements.md`; theory to Research; reference acceptance to Numerical Review | +| Research | `requirements.md` | `research.md`; formulation evidence to Formulation; benchmark/reference evidence to Numerical Review | +| Formulation | `requirements.md`, `research.md` | `formulation.md`; all review evidence to Numerical Review | +| Numerical Review | `requirements.md`, `research.md`, `formulation.md` | `numerical-review.md`, `reference-model.md`; both to I/O Definition | +| I/O Definition | upstream bundle documents including `reference-model.md` | `io.md`; final HDF5 projection to Implementation Planning | +| Implementation Planning | all upstream bundle documents | `implementation-plan.md`; one handoff to Implementation | +| Implementation | all upstream bundle documents and `implementation-plan.md` | `implementation-report.md`, `build-test.md`, `reference-comparison.md` | +| Correction | Implementation-owned reports and code/test/CMake evidence | `corrections.md`; rerun request to Implementation | +| Physics Evaluation | `reference-comparison.md`, `reference-model.md`, physics contracts | `physics-evaluation.md`; model gaps to Numerical Review | +| Release | all feature bundle evidence | `release.md`; closure recommendation to Coordinator | + +- [ ] **Step 5: Normalize all surviving FESA skill paths and handoffs** + +Update the Inputs, Output Contract, Quality Gate, and Handoff sections of these files: + +```text +.codex/skills/fesa-requirements-baseline/SKILL.md +.codex/skills/fesa-research-evidence/SKILL.md +.codex/skills/fesa-formulation-spec/SKILL.md +.codex/skills/fesa-numerical-review/SKILL.md +.codex/skills/fesa-io-contract/SKILL.md +.codex/skills/fesa-cpp-msvc-tdd/SKILL.md +.codex/skills/fesa-physics-sanity/SKILL.md +.codex/skills/fesa-release-readiness/SKILL.md +``` + +Every feature-document path must start with `docs//`. Remove all handoffs to retired +agents and skills. Preserve `fem-theory-query` and project-local `harness` usage where already valid. + +- [ ] **Step 6: Run the hierarchy test** + +Run: + +```powershell +uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py::test_agent_hierarchy_is_explicit -v +``` + +Expected: PASS. + +- [ ] **Step 7: Commit the Coordinator and sub-agent contracts** + +```powershell +git add .codex/agents .codex/skills +git commit -m "refactor: make coordinator the main workflow agent" +``` + +--- + +### Task 6: Align repository guidance and repair document links + +**Files:** + +- Modify: `AGENTS.md:1` +- Modify: `docs/SOLVER_AGENT_DESIGN.md:1` +- Modify: `docs/SOLVER_SKILL_DESIGN.md:1` +- Modify: moved files under `docs/linear-static-3d-euler-beam/` and `docs/linear-static-mitc4-shell/` only where old paths appear. +- Modify: tracked Markdown under `docs/superpowers/plans/`, `docs/superpowers/specs/`, and `phases/` only where an old feature-document path must be repaired. +- Test: `tests/test_agent_skill_workflow_contract.py::test_live_contracts_have_no_retired_names_or_paths` +- Test: `tests/test_agent_skill_workflow_contract.py::test_live_guidance_declares_eight_stage_workflow` +- Test: `tests/test_agent_skill_workflow_contract.py::test_agent_toml_and_skill_ui_metadata_are_parseable` + +**Interfaces:** + +- Consumes: canonical agent/skill contracts and bundle paths from Tasks 2–5. +- Produces: one consistent human-readable workflow with no retired live references and valid historical links. + +- [ ] **Step 1: Rewrite the AGENTS workflow sections** + +In `AGENTS.md`: + +1. Replace agent-oriented source-of-truth folders with `docs//`. +2. Replace the numbered process with the approved eight stages. +3. Replace the Agent/Skill Workflow table with the exact stage/owner/skill/output mapping from the design. +4. State that Coordinator is the main agent and every other profile is a sub-agent. +5. Keep Correction outside the numbered stages as on-demand rework. +6. Keep the Implementation Planning Agent's project-local `harness` approval/materialization contract unchanged. +7. Remove retired agent names, retired skill names, and retired output paths. + +- [ ] **Step 2: Rewrite `docs/SOLVER_AGENT_DESIGN.md` around the surviving roles** + +The document must contain: + +```text +Coordinator main-agent orchestration +10 surviving sub-agent roles +8-stage development-process table +8-stage Mermaid workflow +Numerical/reference merged gate +I/O-owned final HDF5 projection +Implementation-owned TDD/build/test/reference comparison gate +Correction rework loop +docs// artifact tree +``` + +Remove standalone Reference Model, Build/Test Executor, and Reference Verification sections. + +- [ ] **Step 3: Rewrite `docs/SOLVER_SKILL_DESIGN.md` around eight workflow skills** + +List the eight surviving `fesa-*` skills exactly as specified in the design. Document that: + +- `fesa-numerical-review` owns both numerical and reference readiness procedures. +- `fesa-cpp-msvc-tdd` owns implementation planning, TDD, MSVC validation, correction, and reference comparison procedures. +- `fem-theory-query`, project-local `harness`, and `review` remain supporting skills. +- Skill output paths use only `docs//`. + +Update the validation count from ten workflow skills to eight. + +- [ ] **Step 4: Repair exact feature-document paths in moved and historical Markdown** + +Use `rg` to inventory references before editing: + +```powershell +rg -n --hidden --glob '!.git/**' --glob '*.md' ` + 'docs/(requirements|research|formulations|numerical-reviews|io-definitions|reference-models|implementation-plans|build-test-reports|corrections|reference-verifications|physics-evaluations|releases|coordination)/' ` + AGENTS.md docs phases +``` + +Apply the Task 2 filename mapping with `apply_patch`. Update only path strings in historical +evidence and phase/spec/plan records; preserve their agent names, statuses, timestamps, commands, +results, and verdict prose. The current consolidation design and this plan may retain old paths +inside migration descriptions because those references describe sources being removed. + +- [ ] **Step 5: Run live-contract and metadata tests** + +Run: + +```powershell +uv run --with pytest python -m pytest ` + tests/test_agent_skill_workflow_contract.py::test_live_contracts_have_no_retired_names_or_paths ` + tests/test_agent_skill_workflow_contract.py::test_live_guidance_declares_eight_stage_workflow ` + tests/test_agent_skill_workflow_contract.py::test_agent_toml_and_skill_ui_metadata_are_parseable -v +``` + +Expected: all three tests PASS. + +- [ ] **Step 6: Commit the live workflow documentation** + +```powershell +git add AGENTS.md docs phases +git commit -m "docs: align consolidated solver workflow" +``` + +--- + +### Task 7: Run full validation and close the refactor + +**Files:** + +- Verify: all files changed in Tasks 1–6. +- Do not modify: solver C++, C++ tests, CMake/CTest files, Harness hooks/executor, or reference artifacts unless a validation check reveals an accidental edit that must be reverted from this task's own changes. + +**Interfaces:** + +- Consumes: the complete consolidated workflow. +- Produces: fresh validation evidence and a clean implementation handoff. + +- [ ] **Step 1: Run the focused workflow-contract suite** + +```powershell +uv run --with pytest python -m pytest tests/test_agent_skill_workflow_contract.py -v +``` + +Expected: 9 tests PASS, 0 fail. + +- [ ] **Step 2: Run the complete Python suite** + +```powershell +uv run --with pytest python -m pytest -v -rs +``` + +Expected: all repository Python tests PASS. + +- [ ] **Step 3: Validate every remaining project-local skill** + +```powershell +$validator = Join-Path $env:USERPROFILE '.codex\skills\.system\skill-creator\scripts\quick_validate.py' +$validationFailed = $false +Get-ChildItem -LiteralPath '.codex\skills' -Directory | Sort-Object Name | ForEach-Object { + python $validator $_.FullName + if ($LASTEXITCODE -ne 0) { $validationFailed = $true } +} +if ($validationFailed) { exit 1 } +``` + +Expected: every remaining skill reports valid frontmatter and naming. + +- [ ] **Step 4: Check the final agent/skill inventory and working-tree scope** + +```powershell +Get-ChildItem -LiteralPath '.codex\agents' -Filter '*.toml' | Sort-Object Name | Select-Object -ExpandProperty Name +Get-ChildItem -LiteralPath '.codex\skills' -Directory | Sort-Object Name | Select-Object -ExpandProperty Name +git diff --check +git status --short +``` + +Expected: + +- 11 agent TOMLs: one Coordinator plus ten sub-agents. +- 9 project-local skill directories: eight FESA workflow skills plus `fem-theory-query`. +- `git diff --check` exits 0. +- No solver C++, C++ test, CMake, hook, executor, or `reference/` artifact appears in the task diff. + +- [ ] **Step 5: Confirm no final C++ validation is required** + +Inspect the changed-file list: + +```powershell +git diff --name-only HEAD~6..HEAD +``` + +Expected: only agent/skill configuration, Markdown, and the Python contract test changed. Record +that MSVC build and CTest were not run because no C++ production, C++ test, or CMake/CTest file +changed. + +- [ ] **Step 6: Commit only validation-driven corrections if any were required** + +If Steps 1–5 required corrections, stage only those corrections and commit: + +```powershell +git add -A +git commit -m "fix: correct consolidated workflow contracts" +``` + +If no corrections were required, do not create an empty commit. + +--- + +## Acceptance Traceability + +| Approved requirement | Implemented by | Verified by | +| --- | --- | --- | +| Merge reference-model stage into numerical review | Task 3 | `test_numerical_review_absorbs_reference_model_contract` | +| Merge Build/Test and Reference Comparison into Implementation | Task 4 | `test_implementation_absorbs_build_test_and_reference_comparison` | +| Merge the corresponding skills | Tasks 3–4 | focused merge tests and skill validation | +| Store evidence by feature under `docs//` | Task 2 | `test_existing_feature_artifacts_are_bundled` | +| Make Coordinator the main orchestrator | Task 5 | `test_agent_hierarchy_is_explicit` | +| Focus Coordinator output on worklist and progress | Tasks 2 and 5 | coordination documents and hierarchy test | +| Preserve historical evidence | Tasks 2 and 6 | migration diff review and bundle inventory | +| Remove stale live references | Tasks 5–6 | `test_live_contracts_have_no_retired_names_or_paths` | +| Keep configs and skill metadata valid | Tasks 3–7 | TOML/metadata pytest and `quick_validate.py` |