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

7 KiB

description argument-hint
Codex engineering/bug-bounty prompt with YAMS-first distributed memory [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

  1. Register (if blackboard available): bb_register_agent({ id: "opencode-<task-slug>", name: "OpenCode Agent", capabilities: ["yams", "code", "coordination"] })
  2. Retrieve + hydrate per the contract above before any local exploration.
  3. Start: check index health and store a concise claim.
    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.
  4. Act: implement/test/verify in scope; keep notes concise and indexable. For C++/systems work follow the design-first TDD loop in AGENTS.md.
  5. Checkpoint: index changed files and a concise source=note record of decisions, open questions, and the next action.
  6. 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

# 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

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).