docs: refresh Abaqus subroutine guidance
This commit is contained in:
KOKO\Mimi
@@ -0,0 +1,196 @@
|
||||
# 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.
|
||||
|
||||
- [ ] **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.
|
||||
@@ -6,9 +6,9 @@ Abaqus User Subroutine 개발 지침을 다음 세 원칙에 맞게 정비한다
|
||||
|
||||
1. 유한요소 이론과 solver 지식은 `fem-theory-query`를 통해 조사한다.
|
||||
2. Abaqus User Subroutine ABI와 매뉴얼 사실은 로컬 매뉴얼 index를 통해 찾는다.
|
||||
3. 과거 `uel-3d-euler-beam` 기능에 종속된 산출물과 잔존 참조를 제거한다.
|
||||
3. 사용자가 폐기한 과거 feature에 종속된 산출물과 잔존 참조를 제거한다.
|
||||
|
||||
`abaverify`는 도입하지 않는다. Abaqus 해석은 사용자가 다른 PC에서 수행하고, 이 저장소는 사용자가 첨부한 변위·응력 CSV와 provenance artifact를 schema/tolerance 기준으로 비교한다.
|
||||
Abaqus 해석은 사용자가 다른 PC에서 수행하고, 이 저장소는 사용자가 첨부한 변위·응력 CSV와 provenance artifact를 schema/tolerance 기준으로 비교한다.
|
||||
|
||||
## Source Routing
|
||||
|
||||
@@ -29,7 +29,6 @@ Abaqus User Subroutine 개발 지침을 다음 세 원칙에 맞게 정비한다
|
||||
- Abaqus job과 ODB-to-CSV 추출은 사용자가 다른 Abaqus PC에서 수행한다.
|
||||
- 사용자는 변위, 응력 또는 feature contract에서 지정한 결과 CSV와 provenance metadata를 제공한다.
|
||||
- 이 저장소는 ODB를 직접 파싱하지 않고 CSV schema, matching key, unit, coordinate system, tolerance를 비교한다.
|
||||
- `abaverify` 관련 agent, skill, command, artifact contract는 추가하지 않는다.
|
||||
|
||||
## 변경 범위
|
||||
|
||||
@@ -46,16 +45,16 @@ Abaqus User Subroutine 개발 지침을 다음 세 원칙에 맞게 정비한다
|
||||
|
||||
새 매뉴얼 전용 skill은 만들지 않는다. 전역 `AGENTS.md` 규칙과 기존 research/interface skill에 index 탐색 절차를 추가하는 것이 더 단순하며 중복을 줄인다.
|
||||
|
||||
## Euler Beam 제거 범위
|
||||
## 과거 Feature 제거 범위
|
||||
|
||||
이미 삭제된 사용자 변경을 보존하고, 남아 있는 versioned project-specific 항목을 제거한다.
|
||||
|
||||
- `docs/abaqus-uel-subroutines-research.md`
|
||||
- `docs/research/uel-3d-euler-beam-research.md`
|
||||
- `scripts/test_uel_3d_euler_beam_uel.py`
|
||||
- `scripts/test_validate_fortran.py`에 남은 Euler beam 전용 fixture 이름과 경로
|
||||
- 과거 feature 전용 supplemental research brief
|
||||
- 과거 feature 전용 research brief
|
||||
- 과거 feature wrapper contract test
|
||||
- `scripts/test_validate_fortran.py`에 남은 feature 전용 fixture 이름과 경로
|
||||
|
||||
공식 매뉴얼의 backward Euler 문구와 generic `UEL` entry point 설명은 과거 feature 산출물이 아니므로 유지한다.
|
||||
공식 매뉴얼의 수치 적분 용어와 generic user-subroutine entry point 설명은 과거 feature 산출물이 아니므로 유지한다.
|
||||
|
||||
## 범위 제외
|
||||
|
||||
@@ -64,23 +63,21 @@ Abaqus User Subroutine 개발 지침을 다음 세 원칙에 맞게 정비한다
|
||||
- Python, Fortran, workspace test 실행
|
||||
- Abaqus job 실행 또는 ODB 직접 parsing
|
||||
- CSV validator 구현 변경
|
||||
- `abaverify` 도입
|
||||
|
||||
## 정적 검증
|
||||
|
||||
테스트 대신 다음 문서 검사를 수행한다.
|
||||
|
||||
1. 변경 파일을 재독해 source routing과 verification 계약의 충돌을 확인한다.
|
||||
2. versioned 파일에서 `uel-3d-euler-beam`, `uel_3d_euler_beam`, `3D Euler-Bernoulli` 잔존 참조를 검색한다.
|
||||
3. 매뉴얼을 제외한 project guidance에서 `abaverify`가 남지 않았는지 확인한다.
|
||||
4. 변경된 skill frontmatter와 `agents/openai.yaml`의 의미가 일치하는지 확인한다.
|
||||
5. `git diff --check`와 diff 검토만 수행한다.
|
||||
2. versioned 파일에서 폐기된 feature의 식별자와 전용 설명이 남지 않았는지 검색한다.
|
||||
3. 변경된 skill frontmatter와 `agents/openai.yaml`의 의미가 일치하는지 확인한다.
|
||||
4. `git diff --check`와 diff 검토만 수행한다.
|
||||
|
||||
## 성공 기준
|
||||
|
||||
- FEM 관련 지식 탐색이 `fem-theory-query`로 명시된다.
|
||||
- Abaqus 매뉴얼 사용 순서가 `INDEX_MAP.md` → `INDEX.md` → 모든 `source_ranges`로 명시된다.
|
||||
- 외부 Abaqus PC에서 생성한 변위·응력 CSV 비교가 유일한 solver-result verification 경로로 유지된다.
|
||||
- project-specific Euler beam 파일과 versioned 참조가 남지 않는다.
|
||||
- 폐기된 project-specific feature 파일과 versioned 참조가 남지 않는다.
|
||||
- 기존 사용자 변경을 되돌리지 않는다.
|
||||
- Harness skill과 테스트를 실행하지 않는다.
|
||||
|
||||
Reference in New Issue
Block a user