lstormm

Imported from pgbarletta/lstormm (AGENTS.md). Install upstream with npx skills add pgbarletta/lstormm. Copyright stays with the author.

Read This At The Start Of Every Session

This documentation must be read at the start of every session.

Use the Codebase Map First (and keep it updated)

Resolving the correct codebase-docs/ directory

codebase-docs/ and plans/ are branch-scoped, following the same convention as worktree directories. Determine which one to use from the active worktree:

If no worktree is specified, assume stormm/ and therefore codebase-docs/ and plans/.

What to read

Before touching the repository, you must read:

• <docs_dir>/codebasemap.md
• every Mermaid diagram in <docs_dir>/assets/ (*.mmd)
• <docs_dir>/testing.md before running any MCP test tool
• the relevant per-module source index file from <docs_dir>/source-index/ for any code you will modify

Treat these docs as the source of truth for architecture, compute/data flow, capability boundaries, invariants (units/determinism/precision), and the source-file + symbol index.

When proposing any change, you must:

1. cite the relevant section(s) of codebasemap.md and any relevant assets/*.mmd by path,
2. identify the exact files/symbols you will touch (repo-relative paths + symbol names), and
3. list the invariants/tests/validation expectations that must remain true.

After modifying the codebase, you must update the branch-scoped <docs_dir>/ to match reality:

• revise codebasemap.md sections affected (architecture/capabilities/invariants/etc.)
• update the per-module source index in <docs_dir>/source-index/<module>.md for any files whose classes/functions/globals changed
• add/update Mermaid diagrams in assets/ if flows/modules changed
• note changes in OPEN QUESTIONS / ASSUMPTIONS only if they remain unresolved

Repository Structure

This wrapper repository contains one or more stormm worktrees:

./ # Wrapper root ├── stormm/ # Default worktree (main/dev) ├── _stormm/ # Worktrees for feature branches │ ├── src/stormm/ # Package source │ ├── tests/ │ └── pyproject.toml ├── codebase-docs/ # Default docs (main/dev) ├── plans/ # Default plans (main/dev) ├── _codebase-docs/ # Branch-scoped docs ├── _plans/ # Branch-scoped plans └── AGENTS.md

All paths in plans, codebasemap.md, and Mermaid diagrams are relative to a worktree root. The plan specifies which worktree to use (e.g., rbfe1_stormm/).

If no worktree is specified, assume stormm/.

Example:

• Plan says: rbfe1_stormm/
• Plan path: src/Accelerator/hybrid.h
• Read path: rbfe1_stormm/src/Accelerator/hybrid.h
• Docs path: rbfe1_codebase-docs/codebasemap.md
• Plans path: rbfe1_plans/<topic>-yy-mm-dd.md

Before doing any task in this repository, read the corresponding codebase-docs/codebasemap.md and the relevant files it references.

Prompt Inventory

Prompts currently available in .codex/agents/:

• .codex/agents/architect.md
• .codex/agents/chief-of-staff.md
• .codex/agents/codebaser.md
• .codex/agents/code-reviewer.md
• .codex/agents/coder.md
• .codex/agents/mapper.md
• .codex/agents/planner.md
• .codex/agents/prwriter.md
• .codex/agents/reader.md

Feature or refactor loop:

1. chief-of-staff for scoping when the request is ambiguous or cross-cutting
2. architect for design when APIs, memory model, precision, or CUDA behavior may change
3. planner for the concrete execution plan
4. coder for implementation
5. code-reviewer after substantive diffs
6. codebaser or mapper to synchronize architecture docs when repo behavior or flows changed

Run only the stages relevant to the request. Validation should use the project instructions in stormm/README.md, stormm/CMakeLists.txt, and codebase-docs/; do not invent Amber/Fortran workflows for this C++/CUDA project.

Mandatory Loop Triggers

When the user explicitly asks for a new feature or a refactor, run the preferred feature loop by default instead of skipping directly to implementation or ad hoc edits.

Before that loop begins:

1. Ask the user for the new branch name.
2. Create a new git worktree for that branch.
3. Place the worktree directory next to stormm/ (it has to be created inside the parent directory)
4. Name the directory <branch>_stormm.

Example:

• branch name dev
• worktree directory ../dev_stormm

Do not silently choose the branch name for the user in these cases.

Committing and PRs

Never add or remove or commit anything unless the user explicitely asks so. When the user asks to "commit", "write a commit", "draft a PR", or similar, use the prwriter prompt (.codex/agents/prwriter.md).

Working inside the opencode container

If $HOME is /srv/opencode-home/ then you are currently working inside the ocd container.