# Project Guidance Refresh 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:** Align project guidance, custom agents, and existing skills with mandatory FEM-vault routing, indexed local Abaqus manual lookup, external user-provided CSV verification, and removal of retired feature artifacts. **Architecture:** Keep the current seven-gate workflow and external CSV artifact model. Add one shared source-routing contract to core guidance, then place concise role-specific instructions only where an agent or skill directly consumes FEM theory or Abaqus manual facts. Remove retired feature files without changing generic user-subroutine or numerical-integration documentation. **Tech Stack:** Markdown, TOML custom-agent definitions, Codex `SKILL.md`, Python unittest fixture text, Git **Spec:** `docs/superpowers/specs/2026-08-18-project-guidance-refresh-design.md` ## Global Constraints - Do not run harness skills, Python tests, Fortran tests, workspace validation, Abaqus jobs, or ODB parsing. - Preserve all pre-existing user changes, including current deletions, manual files, `.codex/config.toml`, and `fem-theory-query/vault-path.txt`. - Treat user-provided displacement, stress, and feature-specific CSV files plus provenance metadata as solver-result verification inputs. - Use `fem-theory-query` for FEM theory, formulation, solver behavior, benchmark, and numerical-verification knowledge. - Use `docs/AbaqusUserSubroutineManual/INDEX_MAP.md`, then `INDEX.md`, then every selected `source_ranges` span for Abaqus User Subroutine manual facts. - Keep `INDEX.md` summaries as retrieval metadata; use source spans as authoritative evidence. - Verify documentation changes with read-only/static checks only. --- ### Task 1: Core Project Guidance **Files:** - Modify: `AGENTS.md` - Modify: `docs/PRD.md` - Modify: `docs/ARCHITECTURE.md` - Modify: `docs/ADR.md` - Modify: `docs/ABAQUS_SUBROUTINE_AGENT_DESIGN.md` - Modify: `docs/research/README.md` **Interfaces:** - Consumes: approved design and existing external CSV artifact contract - Produces: one authoritative source-routing policy inherited by all custom agents and skills - [x] **Step 1: Add the shared source-routing contract to `AGENTS.md`** State three routes explicitly: FEM theory through `fem-theory-query`; Abaqus manual facts through `INDEX_MAP.md` → `INDEX.md` → every selected source span; solver results through user-provided external CSV and provenance artifacts. - [x] **Step 2: Remove misleading workflow wording in `AGENTS.md`** Restore step 5 to TDD no-Abaqus test/reference model design without making harness skills mandatory, restore literal `` and `RED -> GREEN -> VERIFY`, and retain external CSV comparison as the sole solver-result path. - [x] **Step 3: Align PRD and architecture** Add the source-routing requirements, add `docs/AbaqusUserSubroutineManual/` to the repository map, and clarify that agents must not infer ABI facts from generated index summaries. - [x] **Step 4: Record the source-routing decision** Add a new ADR that separates FEM theory evidence, local Abaqus manual evidence, and external CSV result evidence without rewriting historical ADR decisions. - [x] **Step 5: Align agent design and research guidance** Add `fem-theory-query` to every process row that directly consumes FEM knowledge, and add the local manual index protocol to the Research Agent source policy. - [x] **Step 6: Static review Task 1** Read all six files and confirm the three evidence routes have no contradictory wording. Do not execute test commands. ### Task 2: Custom Agent Source Routing **Files:** - Modify: `.codex/agents/research-agent.toml` - Modify: `.codex/agents/formulation-agent.toml` - Modify: `.codex/agents/numerical-review-agent.toml` - Modify: `.codex/agents/io-definition-agent.toml` - Modify: `.codex/agents/implementation-planning-agent.toml` - Modify: `.codex/agents/reference-model-agent.toml` - Modify: `.codex/agents/physics-evaluation-agent.toml` **Interfaces:** - Consumes: shared source-routing policy from Task 1 - Produces: role-specific mandatory source selection without duplicating the full global policy - [x] **Step 1: Update research and interface agents** Require the Research Agent and I/O Definition Agent to locate Abaqus manual sections through `INDEX_MAP.md`, inspect the complete `INDEX.md` record, and read all source ranges before making ABI or product-support claims. - [x] **Step 2: Strengthen FEM routing for theory-owning agents** Change the existing `fem-theory-query` references from optional wording to mandatory wording when Formulation, Numerical Review, Implementation Planning, Reference Model, or Physics Evaluation work needs FEM knowledge. - [x] **Step 3: Preserve role boundaries** Confirm none of the seven agents gains code implementation, Abaqus execution, reference CSV generation, or readiness-approval authority. - [x] **Step 4: Static TOML review** Re-read the edited TOML strings and confirm balanced triple quotes and unchanged `model_reasoning_effort = "extra high"` values. ### Task 3: Existing Skill Source Routing **Files:** - Modify: `.codex/skills/abaqus-subroutine-research/SKILL.md` - Modify: `.codex/skills/abaqus-subroutine-formulation/SKILL.md` - Modify: `.codex/skills/abaqus-subroutine-numerical-review/SKILL.md` - Modify: `.codex/skills/abaqus-subroutine-interface/SKILL.md` - Modify: `.codex/skills/abaqus-subroutine-test-models/SKILL.md` - Modify: `.codex/skills/abaqus-subroutine-physics-sanity/SKILL.md` - Modify: `.codex/skills/abaqus-fortran-tdd/SKILL.md` - Modify: `.codex/skills/abaqus-subroutine-readiness/SKILL.md` - Modify: `.codex/skills/abaqus-subroutine-requirements/SKILL.md` - Modify: `.codex/skills/abaqus-subroutine-validation/SKILL.md` - Inspect only: corresponding `.codex/skills/*/agents/openai.yaml` **Interfaces:** - Consumes: existing `fem-theory-query` skill and local manual index files - Produces: concise imperative instructions within existing project skills; no new skill package - [x] **Step 1: Add manual lookup to research and interface skills** Add `INDEX_MAP.md` and `INDEX.md` to required inputs. Require selection by symbol/section/keyword, reading the complete record, then reading every source span in order. State that summaries are non-authoritative. - [x] **Step 2: Add required FEM sub-skill markers** Use the exact marker `**REQUIRED SUB-SKILL:** Use fem-theory-query` in skills that directly perform formulation, numerical review, benchmark/test-model design, or physics interpretation. - [x] **Step 3: Remove dangling README prerequisites** Remove `Read first` entries for general `docs/*/README.md` files already deleted in the user working tree. Keep feature-specific output contracts so future work can create those directories and documents when needed. - [x] **Step 4: Keep skill metadata stable** Do not change frontmatter descriptions or `agents/openai.yaml` unless the trigger meaning changes. Confirm names remain lowercase hyphen-case and frontmatter contains only `name` and `description`. - [x] **Step 5: Static skill review** Check imperative wording, source-routing consistency, lack of duplicated long explanations, and unchanged no-Abaqus/external CSV boundaries. Per user instruction, do not run skill tests, forward-tests, or validation scripts. ### Task 4: Remove Retired Feature Content **Files:** - Delete: the remaining supplemental research brief for the retired feature - Delete: the remaining feature-specific research brief - Delete: the remaining feature-specific wrapper contract test - Modify: `scripts/test_validate_fortran.py` - Preserve: `docs/AbaqusUserSubroutineManual/**` **Interfaces:** - Consumes: current user deletions of the retired feature - Produces: no remaining versioned retired-feature names or content - [x] **Step 1: Delete the remaining feature-specific files** Remove only the three inventoried feature-specific files. Do not delete generic user-subroutine documentation, the local Abaqus manual, or unrelated research guidance. - [x] **Step 2: Neutralize the generic validator fixture** In `test_manifest_build_commands_create_test_build_directories`, replace the retired feature test name and source paths with `sample_kernel_stiffness`, `src/fortran/sample_kernel.f90`, and `tests/fortran/test_sample_kernel.f90`; update the expected build directory accordingly. Do not change validator behavior. - [x] **Step 3: Search versioned content** Search tracked files for the retired feature identifiers and project-specific variants. Ignore generic numerical integration terminology and generic user-subroutine entry point documentation in the official manual. ### Task 5: Static Verification and Handoff **Files:** - Modify: `PLAN.md` - Modify: `PROGRESS.md` - Modify if a reusable pitfall was found: `WORKNOTE.md` - Inspect: all changed and deleted paths **Interfaces:** - Consumes: Tasks 1–4 - Produces: evidence-backed documentation handoff and one conventional commit - [x] **Step 1: Run allowed static checks** Run only read-only/static commands equivalent to: ```powershell git diff --check git diff --stat git status --short ``` Use text search to confirm manual routing, FEM routing, external CSV verification, and removal of retired feature references. - [x] **Step 2: Re-read changed guidance** Confirm `AGENTS.md`, core docs, agent TOML, and skill Markdown agree on the evidence routes and role boundaries. - [x] **Step 3: Update shared state** Record completed work, exact static checks, skipped tests, and the next action in `PROGRESS.md`. Add to `WORKNOTE.md` only if a reusable repository-specific pitfall arose. - [x] **Step 4: Commit without invoking test hooks** Stage only task-owned changes plus the user's already-requested retired-feature cleanup that belongs to this objective. Commit with a conventional `docs:` message and `--no-verify` because the user explicitly prohibited test execution. Do not include unrelated `.codex/config.toml` or `vault-path.txt` changes unless they were already independently requested and are intentionally part of the user's working tree. - [ ] **Step 5: Push the completed commit** Push the current `dev` branch to its configured upstream after confirming the commit contains no unrelated files.