Imported from wangdepin/raca-codex (AGENTS.md). Install upstream with npx skills add wangdepin/raca-codex. Copyright stays with the author.

RACA Workspace Instructions for Codex

This is a RACA research workspace. Act as a research collaborator who can design experiments, run them on local or remote compute, validate outputs, upload artifacts, and keep the dashboard current.

First Context to Load

• Read .codex/raca/lifecycle.md when the user asks to design, run, monitor, validate, harvest, upload, or analyze an experiment.
• Read .codex/raca/commands.md when the user asks for a RACA command-like action such as onboarding, preflight, find compute, harvest, dashboard sync, or benchmark reference.
• Read .claude/rules/experiments.md for the full experiment lifecycle rules.
• Read .claude/rules/huggingface.md before uploading artifacts to HuggingFace.
• Read .claude/rules/workspace.md before creating, moving, or deleting experiment files.
• Read .claude/codemap.md when locating code, notes, references, tools, or dashboard files.

The .claude/ directory remains the source of the detailed RACA playbooks. In Codex, do not rely on Claude slash commands or Claude hooks firing automatically. Translate the user's natural-language request into the matching Codex playbook under .codex/raca/, then perform the steps directly.

Core Workflow

For experiments, maintain this sequence unless the user explicitly overrides it:

1. Design the experiment and create or update its folder under notes/experiments/<experiment_slug>/.
2. Check benchmark or task references before writing code that evaluates, generates data, or trains on a task.
3. Run preflight before compute: red-team brief, adversarial review, and canary proposal.
4. Find suitable compute before submitting a job.
5. Run a canary job before a full job unless the user explicitly skips it.
6. Monitor jobs with timestamps and update experiment state as progress changes.
7. Harvest artifacts as soon as they appear, validate them, upload them to HuggingFace, and update the dashboard.
8. Analyze only after validation.

Tools and Commands

• Use raca auth <cluster> to authenticate a cluster.
• Use raca ssh <cluster> "command" for remote commands.
• Use raca upload and raca download for file transfer.
• Use raca forward for port forwarding.
• Use .tools-venv/bin/python for scripts that need key_handler, hf_utility, or huggingface_hub.
• Use packages/key_handler/key_handler/key_handler.py through key_handler.KeyHandler; never hardcode API keys or tokens.

Safety Rules

• Never commit API keys, SSH credentials, HuggingFace tokens, generated experiment secrets, or private cluster details.
• Never push public_projects/ without explicit user confirmation.
• Never force-push to HuggingFace Spaces.
• Never upload node_modules/, __pycache__/, .venv/, .tools-venv/, or dist/ as experiment artifacts.
• Use model_response as the standard column name for model outputs.
• Always upload useful artifacts to HuggingFace promptly after validation.
• Always sync the dashboard after meaningful experiment state changes.

Codex-Specific Behavior

• If the user says a Claude slash command such as /raca:experiment-preflight, run the matching Codex playbook from .codex/raca/commands.md.
• If a Claude playbook says to dispatch a subagent, use Codex subagents when available. If not, perform a fresh-file-only review yourself and explicitly separate it from the design conversation.
• If a Claude playbook says to use /loop, monitor with repeated timestamped checks through raca ssh or local commands.
• Keep user-facing explanations concise, but record detailed state in the experiment files.