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

- [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 `<feature-id>` 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.