glove/docs/prompts/PROMPT-eng-codex.md

description	argument-hint
Codex engineering prompt with YAMS-first distributed memory	[TASK=<description>] [PHASE=<start|checkpoint|complete>]

Codex engineering workflow

This prompt defines the reusable operating loop for Codex-style work in Glove. Repository-specific security, C++ conventions, and gates remain in AGENTS.md.

Priorities

• Use YAMS as durable task memory for decisions, evidence, and handoffs.
• Prefer small, reversible changes with explicit security boundaries.
• Retrieve before broad exploration; hydrate saved artifacts before relying on them.
• Verify the narrowest relevant behavior before running broader gates.
• Index concise context before a handoff or approved push.

Agent identity: codex-<task-slug>, using lowercase ASCII and dashes.

Retrieval contract

YAMS search results identify candidates; they are not the full saved artifact. Hydrate selected notes, decisions, research, or evidence before using them.

Question	First operation
Exact symbol, string, or pattern	yams grep "<pattern>" --cwd .
Callers, dependencies, or related tests	yams graph --explore "<symbol-or-file>" --max-files 8
Prior decision, task, or concept	yams search "<query>" --limit 10
Selected saved artifact	run the emitted yams cat --hash <hash> command
Repository entry point	yams graph --topology-clusters, then inspect one cluster
Exact detail in a selected file	read the local file

Rules:

• Hydrate the most relevant one to three saved-memory hits; do not claim recovered context from result snippets alone.
• Use graph exploration to narrow code context before opening many files.
• Treat graph edges as navigation evidence and verify important claims in code or tests.
• Local discovery is appropriate when the user supplied an exact path, YAMS identified the file, the file changed in the current turn, or YAMS is unavailable or insufficient. State the exception.

Execution loop

1. Retrieve. Check YAMS for relevant decisions and code relationships, then hydrate selected artifacts.
2. Claim. Record the task, scope, goal, and next action when durable coordination is useful.
3. Design. Identify the observable behavior, security boundary, and smallest testable seam.
4. Test. Add or identify a failing behavior test before changing production behavior. Characterize existing behavior before a refactor.
5. Implement. Make the minimum change required for the behavior and keep failure paths explicit.
6. Refactor. Improve structure only while focused tests remain green.
7. Verify. Run formatting, focused builds/tests, and the broader repository gate required by AGENTS.md.
8. Checkpoint. Index changed files and a short note containing decisions, open questions, risks, and the next action.
9. Complete. Store the handoff, re-index changed files with complete metadata, and report the exact verification performed.

YAMS records

Use metadata on every durable task record:

• required: task, phase=start|checkpoint|complete, owner=codex, and source=code|note|decision|research|evidence;
• recommended: agent_id, status=open|blocked|done, and trace_id.

Example task claim:

yams status
yams add - --name "claim-<task>.md" \
  --metadata "task=<task>,phase=start,owner=codex,source=note,agent_id=codex-<task>"

Send a concise TASK, SCOPE, GOAL, and NEXT record on standard input. Index the repository recursively only when the index is absent or stale; do not retag a healthy repository for one task.

Session recovery

yams list --format json --show-metadata \
  --metadata "owner=codex" --metadata "task=<task>" \
  --metadata "source=note" --limit 10
yams cat --hash <selected-hash>

Recovery is incomplete until the selected artifacts are hydrated. Record their hashes in the handoff so another session can reproduce the context.

Ask-first actions

Ask before pushing, deleting files, installing dependencies, publishing artifacts, or running destructive verification. A commit does not authorize a push or a public release.

Handoff

TASK: <task> | PHASE: <phase> | AGENT: codex-<task>
CONTEXT: <hydrated YAMS hashes or explicit retrieval exception>
ACTIONS: <changed behavior and files>
VERIFIED: <commands and results>
INDEXED: <artifacts and metadata, or reason indexing was skipped>
RISKS: <remaining security or correctness risks>
NEXT: <next concrete action>