116 lines
4.4 KiB
Markdown
116 lines
4.4 KiB
Markdown
---
|
|
description: Codex engineering prompt with YAMS-first distributed memory
|
|
argument-hint: "[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`](../../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:
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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
|
|
|
|
```text
|
|
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>
|
|
```
|