baram2584/FESADev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9e74398655db56eb523d56fd1c9249b904cced30
FESADev/docs/superpowers/plans/2026-08-15-agent-skill-workflow-consolidation.md
T
KOKO\Mimi 8e046019ed docs: add agent workflow consolidation plan
2026-08-15 01:31:28 +09:00

47 KiB
Raw Blame History

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/<feature-id>/.

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/<feature-id>/.
  • 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/<feature-id>/ 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:

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/<feature-id>/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/<feature-id>/" 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/<feature-id>/" 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:

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
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/<feature-id>/ bundles consumed by every surviving agent and skill.

  • Step 1: Create and verify the two explicit target directories

Run:

$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
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
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:

# 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:

# 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:

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:

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
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:

- 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/<feature-id>/numerical-review.md and docs/<feature-id>/reference-model.md.
- Hand both reports to I/O Definition Agent through Coordinator Agent.

Use this input order:

1. Coordinator handoff and user constraints.
2. AGENTS.md and docs/SOLVER_AGENT_DESIGN.md.
3. docs/<feature-id>/requirements.md.
4. docs/<feature-id>/research.md.
5. docs/<feature-id>/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:

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:

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:

FORMULATION REVIEW -> REFERENCE CASE INVENTORY -> CLASSIFY -> REPORT -> I/O HANDOFF

The Output Contract must name:

docs/<feature-id>/numerical-review.md
docs/<feature-id>/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:

$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:

.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:

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
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:

RED -> OBSERVED FAILURE -> MINIMAL GREEN -> FOCUSED VERIFY
    -> FULL MSVC BUILD/CTEST -> ARTIFACT CHECK
    -> COMPARE -> CLASSIFY -> REPORT

Add exact ownership of:

docs/<feature-id>/implementation-report.md
docs/<feature-id>/build-test.md
docs/<feature-id>/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:

- 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:

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:

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:

docs/<feature-id>/implementation-plan.md
docs/<feature-id>/implementation-report.md
docs/<feature-id>/build-test.md
docs/<feature-id>/reference-comparison.md
docs/<feature-id>/corrections.md

Include the literal workflow marker used by the test:

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:

$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:

.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:

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
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:

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

Require docs/<feature-id>/coordination.md, the eight-stage worklist, and these work-item statuses:

pending | in-progress | passed | needs-rework | blocked

Each dispatch package must contain:

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:

needs-reference-model
needs-build-test
needs-reference-verification
pass-for-reference-verification

Use this live workflow state set:

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:

- You are a sub-agent dispatched by Coordinator Agent.
- Work only on the assigned stage and declared docs/<feature-id>/ 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/<feature-id>/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:

.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/<feature-id>/. 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:

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
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/<feature-id>/.
  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:

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/<feature-id>/ 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/<feature-id>/.

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:

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:

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
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

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
uv run --with pytest python -m pytest -v -rs

Expected: all repository Python tests PASS.

  • Step 3: Validate every remaining project-local skill
$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
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:

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:

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/<feature-id>/ 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
Reference in New Issue View Git Blame Copy Permalink