AbaqusSubroutineDev/docs/superpowers/plans/2026-08-18-project-guidance-refresh.md

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

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

• 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 <feature-id> and RED -> GREEN -> VERIFY, and retain external CSV comparison as the sole solver-result path.

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

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

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

• 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

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

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

• Step 3: Preserve role boundaries

Confirm none of the seven agents gains code implementation, Abaqus execution, reference CSV generation, or readiness-approval authority.

• 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

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

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

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

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

• 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

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

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

• 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

• Step 1: Run allowed static checks

Run only read-only/static commands equivalent to:

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.

• Step 2: Re-read changed guidance

Confirm AGENTS.md, core docs, agent TOML, and skill Markdown agree on the evidence routes and role boundaries.

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

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