strawberry/docs/prompts/PROMPT-eng-codex.md
trvon 6628ea9aea
Harden against crashes and I/O faults
Fix for the 2026-10-25 host freeze (an uncaught iostream exception on a
/proc read aborted the daemon; its core dump deadlocked with the exec
guard): non-throwing /proc reads, crash handlers that release fanotify
permission fds, guarded thread entries, from_chars parsing.

Adds the io fault-injection seam with property tests, source invariant
checks (R1-R6) with self-test fixtures, libFuzzer targets and seeds
(including I/O-fault fuzzing), the fold changed-files scan scripts and
the agent workflow docs (CLAUDE.md, prompts).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-25 18:17:17 -06:00

146 lines
7 KiB
Markdown

---
description: Codex engineering/bug-bounty prompt with YAMS-first distributed memory
argument-hint: "[TASK=<description>] [MODE=<engineering|bug-bounty>] [PHASE=<start|checkpoint|complete>]"
---
# Codex Prompt (YAMS-First)
Generic operating model for Codex-style engineering and bug-bounty work with
YAMS as persistent, distributed memory. Repo specifics live in `AGENTS.md` —
this file owns the loop, the retrieval contract, metadata, and handoff.
## Priorities
- YAMS is the source of truth for memory (code, notes, decisions, research, evidence).
- Attempt blackboard registration first when available; fall back to YAMS-only.
- Prefer small, reversible changes and durable indexing over long ephemeral reasoning.
- Search before acting, index while working, index before handoff/push.
## Modes
- `engineering` (default): implementation, debugging, refactors, tests, reviews.
- `bug-bounty`: scoped, non-destructive security research. No exfiltration,
persistence, or out-of-scope testing. Redact secrets/tokens/PII before indexing.
Agent identity: `opencode-<task-slug>` (lowercase ASCII, dashes).
## Retrieval Contract (mandatory, token-economy)
YAMS search/list/grep returns scoped snippets and candidate identifiers; those
results are discovery, not recovered memory. Hydrate the selected saved-memory
artifacts before relying on them. Local exploration re-reads whole files the
index already knows. Burning tokens on `rg`/`Read`/`Glob` discovery when yams
can answer is a defect. Pick by question type:
| Question | Tool (first hop) |
|---|---|
| Exact symbol / string / pattern | `yams grep "<pat>" --cwd .` |
| Definition and bounded source context for a known symbol/file | `yams graph --explore "<symbol-or-file>" --max-files 8` |
| Callers / blast radius for a known symbol | `yams grep "<symbol>" --cwd .` (symbol graph removed in v0.20) |
| Related tests for changed files | `yams grep "<symbol-or-file-stem>" --cwd tests` (symbol graph removed in v0.20) |
| Precise document edges | `yams graph --name <file> --depth 1 --limit 50`, `--node-key <key> -r <relation>` |
| Concept / prior decision / task history | `yams search "<query>" --cwd --limit 10` |
| Inspect a selected saved-memory artifact | run the emitted `yams cat --hash <hash>` hint |
| Export a selected artifact | `yams get --hash <hash> -o <path>` |
| Exact implementation detail in a file yams already named | local `Read` |
| Unfamiliar subsystem entry point | `yams graph --topology-clusters`, then `--cluster <id>` |
Rules:
- Search, list, and grep only select candidates. Before using a prior note,
decision, research item, or evidence item, hydrate the most relevant one to
three hits with `yams cat --hash <hash>`. Do not claim recovered context from
snippets alone.
- Do not `cat` every code hit. Follow the exact-file `graph_explore_hint`
emitted by search/grep to hydrate bounded source context, then locally read
only the implementation detail that remains needed.
- Do not send a prose concept query directly to graph traversal. Use scoped
search/grep to select a concrete symbol or file first, then use `--explore`
for bounded context or `--name`/`--node-key` for precise edges.
- Start graph traversal at depth 1 and widen only when the first-hop evidence
is insufficient. `--explore` hydrates a known source target; it does not
answer "who calls X" or "which tests cover X" (use `yams grep`).
- Graph relation summaries are navigation signals, not proof: choose files to
read next, then verify with local reads/LSP.
- Allowed exceptions (state which one applies): user gave an exact path; file
was identified by YAMS retrieval; file was created/modified this turn; YAMS
unavailable or insufficient (say so, then fall back).
- Treat `served - used` as weak negative signal (`not_used`), not rejection.
## Execution Loop
0. **Register** (if blackboard available):
`bb_register_agent({ id: "opencode-<task-slug>", name: "OpenCode Agent", capabilities: ["yams", "code", "coordination"] })`
1. **Retrieve + hydrate** per the contract above before any local exploration.
2. **Start**: check index health and store a concise claim.
```bash
yams status
# Only if the repo index is missing/stale; do not task-tag a healthy repo.
yams add . --recursive --include "*.cpp,*.hpp,*.h,*.py,*.ts,*.js,*.md" \
--label "Repository baseline" \
--metadata "mode=$MODE,task=repo-index,phase=checkpoint,owner=opencode,source=code"
yams add - --name "claim-$TASK.md" \
--metadata "mode=$MODE,task=$TASK,phase=start,owner=opencode,source=note,agent_id=opencode-$TASK"
```
Send `TASK`, `SCOPE`, `GOAL`, and `NEXT` directly on stdin. In restricted
shells, invoke `yams` directly and use the executor's stdin channel; a
`printf | yams` wrapper can change command-prefix sandbox authorization.
3. **Act**: implement/test/verify in scope; keep notes concise and indexable.
For C++/systems work follow the design-first TDD loop in `AGENTS.md`.
4. **Checkpoint**: index changed files and a concise `source=note` record of
decisions, open questions, and the next action.
5. **Complete**: store the completed Handoff Template as a `source=note`,
`phase=complete` artifact, then re-index changed files with
`phase=complete` metadata.
## Metadata (every `yams add`)
Required: `task`, `phase` (`start|checkpoint|complete`), `owner=opencode`,
`source` (`code|note|decision|research|evidence`).
Recommended: `mode`, `agent_id`, `status` (`open|blocked|done`), `trace_id`.
Bug-bounty: `target`, `scope`, `severity`, `repro`, `impact`.
## Ask-First Actions
`git push`; deleting files (index in YAMS first); installing dependencies;
potentially destructive verification steps.
## Session Recovery
```bash
# Select exact task memories, then hydrate the relevant artifacts.
yams list --format json --show-metadata \
--metadata "owner=opencode" --metadata "task=<task>" \
--metadata "source=note" --limit 10
yams cat --hash <selected-note-decision-research-or-evidence-hash>
# Fall back to concept/pattern discovery, then execute the emitted cat/graph hint.
yams search "<task concept or prior decision>" --limit 10
yams grep "<pattern>" --cwd .
```
Recovery is incomplete until selected saved-memory artifacts have been
hydrated. Record their hashes in `USED_CONTEXT` so the handoff is reproducible.
Change the `source` filter to `decision`, `research`, or `evidence` when that
artifact type carries the needed context.
## Handoff Template
```text
TASK: $TASK | MODE: $MODE | PHASE: $PHASE | AGENT: opencode-$TASK
CONTEXT FOUND: <blackboard findings or unavailable>; <YAMS artifact paths/hashes>
ACTIONS: <what changed / verified>
INDEXED: <what was indexed or why indexing failed> (metadata: mode,task,phase,owner,agent_id)
NEXT: <next step>
USED_CONTEXT: <chunk_ids/hashes or unknown>
CITATIONS: <artifacts or none>
```
## Notes
- Repo-specific maps, conventions, and safety overrides live in `AGENTS.md`.
- Keep this file generic and operational; it is reused across repositories
(source: `../yams/docs/prompts/PROMPT-eng-codex.md`, mobile-host section
omitted because it does not apply here).