Codex Project Instructions

These instructions translate the durable project rules from the Claude setup into Codex behavior for this repository.

Command And Git Safety

• Use rtk for supported commands when rtk --version and rtk gain succeed. If it is missing or unverified, run commands directly. RTK is optional; do not retry a failed wrapped command automatically when it may already have performed a write.
• Use direct commands or rtk proxy <command> when raw output is needed for debugging or validation.
• Keep changes local unless the user explicitly asks for git commit, git push, PR creation, or GitHub CLI write actions.
• For this repository, run tests, builds, and agent reviews locally. GitHub is for release pushes and release artifacts only. Keep GitHub Actions disabled; do not add workflows, open development PRs, or push development branches. Prepare shipping evidence locally and publish only as part of an explicitly requested release.
• Run git status before staging or committing.
• Stage files by name. Do not use git add . or git add -A.
• Prefer git revert over destructive history rewrites. Do not run git reset --hard unless explicitly requested.
• Never commit .env, private keys, certificates, token/password/secret files, logs, coverage output, local build output, or private IDE settings.

Worktree And Dev Server Safety

• Before starting a dev server, rebuilding a database, or running migrations, verify the current path and worktree.
• Check the target port before starting a server. If occupied, identify the owner and either stop it with user intent or choose another port.
• Do not background long-running dev servers with shell &; use the harness-managed background/session mechanism.
• Before reporting a service as running, verify it responds with curl or an equivalent request.
• Verify required environment variables and generated/compiled dependencies before starting services.

Roadmap Continuity

• Read ROADMAP.md before work on its planned capabilities. Use its stable item IDs to identify scope and the next action across devices.
• When a roadmap item progresses, update its checkbox only after its acceptance checks pass. Update Current focus, the date, validation summary, limitations and next action in the same change. Keep partially completed or blocked items unchecked.
• Keep roadmap entries portable and suitable for publication: repository-relative references and factual engineering results only. Never copy local session records, private data or review attribution into the roadmap.
• A roadmap update does not authorize a commit, push or release. Follow the existing Git and publication instructions.

Code Quality

• Make the smallest defensible change that solves the requested problem.
• Do not add speculative features or infrastructure.
• Prefer editing existing files over creating new abstractions.
• Add helpers only when they remove real duplication or are used at least three times.
• For TypeScript, preserve strictness. Do not introduce any, // @ts-ignore, or unjustified eslint-disable.
• Fix lint/type errors in files you touch.
• Keep pattern symmetry within a change: if you alter one occurrence of a recurring pattern in touched files, update the matching touched occurrences.

Review And Validation

• Roadmap acceptance requires a bounded validation against real GitHub pull requests from projects we own or have pushed from this device. Pin the PR base and submitted head, follow the original change contract, and exercise the relevant Forgeflow behavior on that actual change.
• Automated unit, fixture and regression checks support implementation safety; they do not replace real-PR validation or justify roadmap closure by themselves. Record the selected PR, pinned revisions, observed behavior and remaining limits before marking an item complete.
• Reuse a small relevant PR scope and focused checks. Do not launch broad synthetic workflow or model-comparison batches unless the user explicitly authorizes them.
• Keep feature validation proportional: default to one bounded owned-PR walkthrough and the smallest relevant safety checks. A generic instruction to continue or finish checks does not authorize repeated full review comparisons. Treat multi-arm model benchmarks and repeated review cohorts as separate work requiring an explicit request for that experiment; a minimum-repetition rule in an evaluation contract is not authorization to run it.
• ForgeFlow task owners may pull implemented capability procedures on demand after recording grounded relevance, bounded scope, available prerequisites and a task-compatible budget through the existing selector. Evaluation status preserves benefit limits and does not require a separate activation question. Keywords/include overrides alone are insufficient; current permissions and explicit exclusions still apply. Reuse existing agents and evidence rather than adding review cohorts or experiments.
• Define the bounded functional acceptance before validation and stop when it passes. One relevant owned-PR walkthrough plus focused safety checks is the default; add another case only for a concrete unresolved acceptance requirement or regression.
• Report functional acceptance, concrete defects, and deferred qualification separately. A correct named budget blocker satisfies safe failure behavior; do not require every PR to become ready at an arbitrarily reduced budget. General benefit, latency/cost studies, and additional platform coverage are separate qualification work and do not reopen an accepted feature.
• Do not add closure requirements after observing results. If scope is corrected, record the changed acceptance explicitly and preserve earlier outcomes; never present deferred or failed qualification as a passing test.
• Before invoking Forgeflow or asking for review, re-read the changed files.
• Run relevant typecheck, lint, and tests for non-trivial changes.
• Report validation commands and failures plainly.
• Do not claim CI passed or a reviewer approved unless that actually happened in the current artifacts.
• End implementation work with a short validation checklist when manual checks remain.

PR And Written Output

• PR bodies should contain only substantiated claims: what changed, why, tests run, and known deferrals.
• Avoid status-report tables, fictional approvals, unverifiable production claims, and filler forgeflow output.
• Keep small-change writeups small.
• Avoid AI-ish prose in user-facing writing: no em dashes, no rhetorical contrast templates, no inflated abstractions, and no stock transition words.

Local Session Files

• plan.md, progress.md, and .claude/handoff.md are local session artifacts.
• They should stay ignored and should not be committed.
• Use them for long-running work when the current state needs to survive context compaction.

Local-only workflow boundary

• Treat every .forgeflow/ directory, its contents, and workflow agent identities as local working context only. Never stage, commit, push, attach, upload, or sync this state, including through memory-sync commands. Use Git's local info/exclude for generated state; never force-add it. Ignore rules do not protect already tracked files.
• Never include local artifact paths, agent names, persona names, role labels, agent verdict attribution, or workflow signatures in PR titles, bodies, comments, commit messages, release notes, or published artifacts. Describe the change and observed validation in ordinary engineering language. Keep detailed review attribution and evidence links in local reports.
• Never insert workflow agent identities or local evidence references into application source, comments, docstrings, tests, fixtures, identifiers, UI text, or shipped documentation. Use domain-based names and explain technical reasons without agent attribution.
• Before staging or publishing, inspect the actual staged diff, outgoing commits, and public text. A local-state file or workflow attribution leak blocks the action until corrected. Do not silently delete local evidence or rewrite existing history; report already tracked or committed state for cleanup.
• These rules govern project work produced with Forgeflow. Forgeflow's own maintained agent definitions, integration code, and documentation may name the agents and state paths needed to implement the tool; generated session state is always local. Ordinary domain terms that happen to match a role name are not workflow attribution.
• Local CLI labels, orchestration messages, and local report schemas may retain identities. This boundary takes precedence over instructions to copy local reports into public output or sync session memory.