AGENTS.md@templates/codex git:20261019.77261b3A

Immutable. This exact content never changes and is served at /api/v1/blob/adb03210bb503500.

# Global Codex Working Agreements

## Operating Mode

- Complete each request end to end: inspect, plan when useful, implement, verify, and report the important outcome.
- Use high autonomy for reversible local reads, edits, lint, tests, builds, browser evidence, relevant skills, and bounded read-heavy tools.
- Treat repository-controlled package scripts as code execution: inspect the exact script and honor command-policy prompts even when the task itself authorizes local verification.
- Ask before destructive operations, installs or upgrades, credential changes, account or database writes, production or external writes, commit, push, merge, release, publish, or deploy.
- Prefer repo-local `AGENTS.md`, scripts, package managers, helpers, and naming conventions.
- Use `rg` or `rg --files` first. Keep reads and edits scoped.
- Preserve user work; never revert, overwrite, delete, clean, prune, or reformat unrelated changes.
- Do not commit, push, publish, deploy, rotate secrets, or stop user processes unless explicitly requested.
- A Beyin kill guard may hard-block name-based process kills; target a PID instead.
- On Windows, programmatic command execution should resolve `npm.cmd`, `npx.cmd`, and `codex.cmd` safely.

## Completion And Release Boundary

- Ordinary implementation is complete when the requested behavior works and relevant tests, lint, typecheck, build, browser, smoke, or runtime evidence passes.
- Installers, archives, manifests, signatures, tags, releases, and deployment artifacts are outside ordinary completion.
- Enter release work only after the user explicitly asks to package, publish, deploy, or release.
- Do not describe ordinary work as incomplete merely because release artifacts were not regenerated.
- Do not commit or push unless explicitly requested.

## Routing And Delegation

- Classify non-trivial work against installed agents, skills, MCPs, and profile/config flags, then use the narrowest useful route.
- Use `$adaptive-agent-routing` when routing details, aliases, specialist ownership, or surface placement materially affect the task.
- Agent role selection is automatic when delegation is useful; keep the session's own model and profile, let delegated roles run on the catalog worker model with inherited reasoning effort, and do not pass a model override when spawning them, except a stronger model for one security or release review the user asks for.
- Treat `agents.max_threads = 10` (alias of `agents.max_concurrent_threads_per_session`) as a capacity ceiling, not a target. Size the workers per task to the work and to the live capacity recommendation (`beyin kapasite`, or free RAM at 1.5 GB per worker), never above 8; a request above the recommendation is refused with the measured reason (a coordinator is not counted).
- "Takım koşusu" (team run) means `beyin takim`, the AgentChef team run with Codex workers and the `baslat`/`birlestir` gates.
- Spawn an agent only when one of these holds: an autoVerify routing profile matched and files changed, so its verifier runs before the task is reported done; independent parallel work exists; noisy logs or research should be isolated from the main thread; the user explicitly requests delegation.
- Do not spawn for trivial work, strictly sequential work, tightly coupled work, single-file work where delegation adds coordination cost.
- When a request matches a routing profile (the routing-hint line, or your own classification against the profile catalog), load the profile's auto-skill first; if that skill is explicit-only, suggest it to the user instead. If files changed and the profile's verifier is required (`data-systems`, `frontend-ui`, `security-sensitive`, `mcp-connector-change`, `release-or-publish`), run that verifier before reporting done; otherwise suggest it.
- Start at most 2 agents per task without the user naming them; more needs the user's explicit request. Agents the user asks for by name are not counted, and the live capacity limit still applies. The routing-hint line is advice: you still judge whether the work needs it.
- Two routes, both at most two levels deep: Direct, the main session briefs the specialists the task needs itself; Team, for a user-created board task, the main session briefs that task's coordinator, which briefs its own workers.
- Keep write-heavy implementation in the main thread unless the user explicitly requests split write scopes.
- If agents may edit, give them non-overlapping files. The parent session merges: it checks each Changed scope against its brief's Write scope, resolves conflicts or asks the user, and reruns every Done-when check on the merged result before verification.
- Agents inherit approval and sandbox boundaries; never use delegation to bypass them.
- AgentSpace worker sessions must start from a Codex home whose root config keeps `sandbox_mode = "workspace-write"`, `approval_policy = "on-request"`, and `approvals_reviewer = "auto_review"`; an isolated account profile does not inherit these keys from another Codex home.
- A coordinator may delegate only to its cataloged specialist workers, with one coordinator-to-worker level, and never to `general-purpose`, `fork`, or another coordinator.
- Specialist workers must not spawn agents; when another role is needed, they name it under Open questions (`needs: <role> - <why>`) and the parent decides.
- Coordinator-to-coordinator communication is a parent-routed handoff (an escalation), not direct peer spawning; include the question, evidence, conflict, decision needed, and verification need.
- Never inject or request private AgentSpace memory, sessions, credentials, or other machine-local context in coordinator or worker prompts.
- Wait for requested agents unless the user explicitly asks for background work.
- Close completed agent threads when the runtime exposes that operation.

## Explicit Coordination Board Workflow

- Coordinate only after the user explicitly creates or asks to create a task in the active coordination board. Creating that task records the work state; opening a pane, selecting a role, or matching a routing profile never starts work by itself.
- The parent session runs every coordination-board command; coordinators and workers never do, and no agent creates a board task the user did not ask for.
- Brief fields, one brief per worker: Goal, Evidence, Write scope, Boundaries, Done when (the stop condition), Return format, and the user's words verbatim (the `agent-brief` skill; `coordination-board brief-check` checks one).
- Handoff fields: workers return exactly six labeled fields, in order: Outcome, Evidence (commands, paths, observations), Changed scope (`none` if nothing changed), Risks, Open questions, Next verification (`coordination-board handoff-check` checks one). Workers do not message peer coordinators or delegate further.
- Board handoffs carry a Verdict and a Mutation check (`none - <reason>` for documentation-only work).
- If a Beyin vault is present (`~/.beyin/vault.txt`), drive the board only through `beyin pano`; it uses the shared state file and the human-approval gate.
- A board task needs an owner to start and evidence to reach review. It closes only with evidence, a linked report, resolved decisions, and `--verified-by` naming an agent that did not do the work: never the owner, its session, or its coordinator. Pick the verifier by work type: `test_verifier` for checks, `code_reviewer` for diffs, `frontend_verifier` for UI, `security_auditor` for security, or the user.
- Failed verification sends the task back (`review` to `in_progress` with `--reason`); a stuck task is `blocked` with a reason, and unwanted work is `cancelled`. No coordinator, worker, profile, or pane may auto-start, auto-complete, or infer approval.

## Routing Visibility

- Use one compact initial line: `Routing plan:` followed by selected agents, skills, MCPs, commands, and intentional skips.
- Use one compact final table or line: `Routing result:` with completed, failed, blocked, and skipped surfaces plus evidence.
- Do not emit separate lifecycle messages for every agent, skill, or MCP unless the user asks for verbose routing telemetry.
- If an obvious route is skipped, state the concrete reason once.

## Context Surface Placement

- Use the current prompt for one-off constraints and `AGENTS.md` for durable working agreements.
- Use `~/.codex/config.toml` and profile config files for models, reasoning, sandboxing, approvals, features, agents, MCPs, apps, and tool defaults.
- Use skills for reusable workflows, MCPs for live private or external context, rules for narrow command exceptions, and hooks for reviewed lifecycle automation.
- Keep authenticated, database, production, broad-filesystem, and external-write connectors disabled until needed.
- Use `AGENTS.override.md` only temporarily and remove it when no longer applicable.
- Preserve user-owned config overlay values, project trust, active model/profile choices, and unrelated MCPs unless an explicit force operation is requested.

## Skills And MCPs

- When a task clearly matches an available skill, read its full `SKILL.md` before acting and use the narrowest canonical owner.
- Resolve compatibility skill names through the catalog; do not load duplicate aliases together.
- Prefer official OpenAI docs for Codex behavior and official project docs or Context7 for version-sensitive APIs.
- Use browser evidence for rendered UI, semantic code navigation for unfamiliar code, and reasoning helpers only when complexity warrants them.
- Treat MCP servers as capability boundaries; tool allowlists and approval blocks must stay in parity.
- Never store tokens in instructions, skills, docs, rules, shell history, or committed config.

## Multi-Session Process Hygiene

- Use the balanced base for ordinary work and `--profile full` only for a primary session that needs every bundled local stdio MCP. `--profile multi-session` keeps the lightweight Serena bridge enabled while parking the other eager local helpers.
- Do not enable or launch raw Serena directly from agents. The managed Serena bridge starts no Serena/LSP at session startup, reuses one backend for the same canonical project, creates a separate backend only for a genuinely different project/worktree, and reclaims only its own idle child after its TTL.
- Disabling a local MCP in a profile parks its launcher without removing its definition; agents, skills, remote OpenAI docs, built-in memories, hooks, and apps stay available.
- Audit Codex/MCP ownership before cleanup. Active Codex descendants, recent unowned trees, PID-reused processes, and unrelated Node/Python runtimes must never be cleanup candidates.
- Manual stale cleanup requires the exact preview/apply path `npm run chef -- --processes --cleanup-stale [--apply]`. Do not broaden it to name-based process killing.
- AgentChef's reviewed hooks are the only hook context in this setup: the routing hint adds one advisory line of profile, skill, and role identifiers per prompt, and the session-end process sweep is fail-closed and owner-scoped. Do not bypass hook trust, add other context-injecting hooks, or turn these into broad lifecycle automation.

## Token Budget Discipline

- Start with catalogs, manifests, package scripts, summaries, `rg --files`, and focused searches; open full files only when selected.
- Use `context-budget-planner` for repo-wide, research-heavy, documentation-heavy, multi-agent, or long-running work.
- Keep large logs, docs, and agent transcripts out of the main thread; return summaries, evidence paths, commands, and blockers.
- Do not disable agents, skills, MCPs, memory, hooks, or apps merely to reduce tokens.
- Prefer profile knobs such as verbosity, reasoning effort, compaction thresholds, and tool-output limits.
- Specialist and coordinator roles run on the catalog worker model (`gpt-6-luna`); the session the user opens keeps its own model and profile, and reasoning effort stays inherited.
- Run `npm.cmd run token:audit` on Windows, or the repository-equivalent command, for layered context-size diagnostics.

## Implementation Standards

- Make the smallest coherent change that fixes the root cause.
- Prefer the simplest end-to-end implementation that meets the current requirement; avoid speculative abstractions, configuration, and indirection.
- Grow a working system in verified layers. Add a capability on top of a working product instead of trading it for unfinished complexity.
- Keep component responsibilities explicit and modular.
- Reuse proven project or well-maintained dependencies when they reduce complexity or improve reliability; check their documentation and types before reimplementing a capability or adding a package.
- Prefer durable architectural decisions over knowingly temporary stopgaps.
- Preserve documented contracts and user data. Remove obsolete paths only when the project's compatibility and migration policy explicitly permits it.
- Establish reproduction and root cause before unclear bug fixes.
- Add dependencies only after proving they are necessary.
- Do not weaken production code, auth, validation, tests, types, or error handling to make checks pass.
- For refactors, list affected locations, keep behavior stable, and run existing tests unchanged.
- For UI work, verify behavior in a real browser or screenshot-capable flow when available.

## Verification

- Run the narrowest meaningful check first, then broader checks proportional to blast radius.
- Prefer repository scripts for tests, lint, typecheck, build, smoke, status, and runtime verification.
- Runtime probes must be bounded by short per-probe timeouts and expose progress plus offline or no-MCP modes.
- If verification cannot run, report the exact reason and remaining unverified surface.
- For security or release work, include Gitleaks or an equivalent secret scan when available.
- For UI changes, include rendered browser evidence when possible.

## Security And Secrets

- Never print, persist, or infer secrets from environment variables, auth files, cookies, private keys, tokens, or connection strings.
- Ask before irreversible data, billing, production, database, account, permission, or credential changes.
- Treat browser and MCP tools as potentially outside the shell sandbox.
- Before a requested commit or push, inspect status, stage explicit files, and review the staged diff.
- Do not commit environment files, auth state, agent state, dumps, keys, certificates, installers, archives, logs, screenshots, or scratch output unless explicitly confirmed.
- If a secret-like value appears in history, treat it as compromised and rotate it before considering history cleanup.
- Keep approval rules general-purpose; never auto-allow publishing, credential extraction, or destructive file operations.

## Durable Reference

- The installed `$adaptive-agent-routing` skill contains the deferred routing ID catalog, specialist ownership map, skill compatibility aliases, MCP guidance, UI standards, and expanded operating notes.
- Catalogs and validators are canonical for machine-readable agent, skill, MCP, approval, and routing parity.
- Detailed guidance is loaded only when selected; this compact contract remains the always-loaded safety and completion baseline.