Codex - Global Development Instructions

Core Principles

• Prefer simple, clean, maintainable solutions over complex or clever implementations.
• Make surgical changes: use the smallest reasonable diff, match the existing style, and ask before reimplementing from scratch.
• If you notice unrelated dead code, mention it rather than deleting it. Remove orphan imports, variables, or functions only when your own changes made them unused.
• Practice TDD by default: write or update tests first when the behavior can be captured cleanly, then implement, then refactor.
• Ship production-ready code with clear error handling and input validation.
• Favor self-documenting code: clear names first, comments only where they explain why a non-obvious choice exists.
• Run a complexity check before finishing: if a senior engineer would call the solution overcomplicated, simplify it.
• Never use --no-verify when committing.

Communication Style

• Address the developer as FX when a direct address is useful.
• Be sharp, efficient, and no-nonsense.
• Keep business context in mind and challenge inefficient or brittle approaches when needed.
• Give clear, structured responses with actionable next steps.
• Ask for clarification when a decision is risky, ambiguous, or cannot be inferred from the repo. For low-risk implementation details, make a reasonable assumption and state it.
• If blocked on something the human can resolve faster, stop and ask for help with the specific blocker.

Machines

This config is shared across machines via symlinks, so never assume a platform. Check with uname -s (Darwin / Linux) before reaching for a platform tool.

home-lab hosts the local-ci-cd GitLab stack the CI Compatibility section below assumes. Its sshd takes keys only from nix-darwin's remoteLoginAuthorizedKeys and only from the tailnet — password auth is off, so ssh-copy-id cannot authorise anything there; declare the key and rebuild.

Project roots (decided 2026-11-08; full catalogue in ~/.claude/reference-docs/projects.md):

• ~/projects/<name> holds the human checkouts on every host. home-lab has none; it is the appliance.
• ~/Work/<name> is the SDLC fleet worker's clone root on every host. Worker clones are reset on dispatch, never hand-edit them. The one exception is ~/Work/claude-code-config, the live config checkout on the Linux hosts.
• On the Macs the live config is ~/.config/nix-install/config/claude-code-config (nix-install owns it) and ~/projects/nix-install is a symlink to ~/.config/nix-install.
• On macbook-pro-m3-max, ~/dev is a transitional symlink to ~/projects. Create nothing new under it.

On Omarchy, prefer what the distro already ships over hand-rolling an equivalent:

• omarchy — the top-level CLI (omarchy update, omarchy bar put <plugin> --section right).
• The omarchy-* script family (e.g. omarchy-microphone-test, omarchy-nvme-suspend-fix). Enumerate what is actually installed with compgen -c omarchy | sort -u rather than guessing a name — the set grows with Omarchy releases.
• pacman for packages — never brew. systemctl --user for user services.
• The Omarchy menu is Super + Space; the terminal is Foot (Super + Return).

macOS-only pieces of this framework (cmux, model-shelf volume scanning, the oMLX/qwen harness, /demo narration) are unavailable on Omarchy by design.

Code Quality Standards

Python

• Use uv for dependency management and project setup when the project does not already establish another tool.
• Use comprehensive type hints for application code.
• Prefer clear variable names and strategic docstrings for public or complex behavior.
• Follow SOLID principles and clean architecture where they fit the codebase.
• For FastAPI projects, validate inputs explicitly and keep route handlers thin when practical.

TypeScript

• Use the runtime and package manager already established by the project; prefer Bun when starting new backend TypeScript work.
• Use strong TypeScript types, explicit validation at boundaries, and proper error handling.
• Follow OWASP security guidance for web-facing code.
• Keep backend modules organized so they can evolve toward service boundaries without premature abstraction.

Testing

• Unit tests should cover business logic.
• Integration tests should validate component interactions.
• End-to-end tests should cover important user workflows when the project has an E2E setup or the change touches user-facing flow.
• Do not skip tests unless FX explicitly authorizes: I AUTHORIZE YOU TO SKIP WRITING TESTS THIS TIME.
• Scale test depth to risk and blast radius, but always explain what was and was not verified.

Workflow

Verifiable Goals

For multi-step tasks, state a brief plan with explicit verification per step:

1. [Step] -> verify: [check]
2. [Step] -> verify: [check]

Strong success criteria let work proceed independently. Convert fuzzy asks into verifiable goals:

• "Add validation" -> "Write tests for invalid inputs, then make them pass."
• "Fix the bug" -> "Write a test that reproduces it, then make it pass."

Implementation Discipline

• Read the relevant code before changing it.
• Prefer existing project patterns, helpers, and conventions over new abstractions.
• Keep unrelated refactors out of the diff.
• Use structured parsers and APIs for structured data instead of ad hoc string manipulation when reasonable.
• Before editing files, state what you are about to change.
• After editing, run the narrowest useful verification first, then broaden if the change touches shared behavior.

Piloting the SDLC

sdlc is the controller that owns the build and fix pipelines; the skills are thin wrappers around it. Most of these rules are conventions the controller does not enforce; a rule names its refusal where one exists.

• Look before acting: sdlc status --json, sdlc runs --json, sdlc queue list --json and sdlc doctor --json change no run state. Read them before starting anything.
• Front door only: start work through sdlc fix, sdlc build, sdlc resume, or --enqueue. Never call the run-* internals.
• Never nest: SDLC_BATCH_BUILD set means you are a dispatched agent. Return your <<<RESULT_JSON>>> block; do not start a run. The variable is only a marker: the controller will not refuse a nested run.
• One live run per repo: check sdlc runs --json first. sdlc fix and sdlc resume refuse a second live owner of the same run or scope; a fresh sdlc build is not guarded. A run sdlc runs shows DEAD resumes with plain sdlc resume; use sdlc resume --force only after a refusal, once you have confirmed that pid is no longer the run.
• Long runs are not tool calls: build and fix run for hours. Poll with sdlc status; never block on them.

Codex Tooling

• Use rg or rg --files first for searching files and text.
• Use apply_patch for manual file edits.
• Do not revert user changes unless FX explicitly asks.
• Avoid destructive commands such as git reset --hard or git checkout -- unless explicitly requested.
• When work requires network access, GUI access, or writing outside the workspace sandbox, request approval with a concise justification.
• If FX specifically mentions docs.temenos.com or asks to check Temenos docs, access the site directly with Playwright. Do not use generic web search for that request.
• When researching docs.temenos.com, if the site requires login, stop and ask FX to log in so the authenticated documentation can be accessed. Do not silently substitute public Temenos sources unless FX explicitly approves that fallback.
• If the user asks for a review, lead with findings ordered by severity, include file and line references, then summarize.

CLI Tools

Prefer installed utilities over older shell defaults when working in shell scripts, pipelines, or terminal exploration:

Rules:

• Use shell tools for complex filtering, pipelines, and repository inspection.
• In automation, prefer fd, rg, bat, and jq over legacy alternatives when available.
• Always use scc for line-of-code counting tasks.
• Always use typst for PDF generation unless the project already mandates another tool.

Source Control — local GitLab is master

Every repo under ~/Work uses the local-ci-cd GitLab on home-lab as its authoritative remote; GitHub is a one-way push mirror. Two repos keep GitHub as master: nix-install, and claude-code-config while its controller-driven PR flow still runs there.

• Reach GitLab as http://gitlab.test (port 80 via tailscale serve + split DNS) and set GITLAB_HOST=gitlab.test for glab. Never use the old home-lab…:8080 address — its tailnet mapping is unreliable. A global git insteadOf rewrite still maps stale :8080 remotes to gitlab.test.
• origin is GitLab (http://gitlab.test/root/<repo>.git); the github remote is only the mirror target. Never push to github; never merge on GitHub — mirrors run with keep_divergent_refs, so a GitHub-side merge silently strands GitLab instead of failing.
• Change flow: branch → push origin → merge request on GitLab → the appliance pipeline is green → merge on GitLab. The mirror carries main and tags to GitHub; a GitLab release job publishes the GitHub release only after the mirror has synced the tag.
• Issues and MRs live on GitLab — use glab. gh stays for the two GitHub-master repos and for read-only mirror checks. Do NOT rely on a GitHub MCP server — it has been removed from all environments. glab mr create takes the source project from the cwd; for another repo, POST projects/<id>/merge_requests via glab api.
• Every GitLab-master repo carries .sdlc-forge.yaml (forge: gitlab, gitlab_url: http://gitlab.test): the sdlc controller's auto-detect keys on a "gitlab" substring the hostname lacks. Keep it.
• Keep .github/workflows/ci.yml where it exists — it is the hosted fallback for the single-appliance risk, not a redundant gate.
• New projects start on GitLab. Create the project there, with origin at http://gitlab.test/root/<repo>.git, and commit .sdlc-forge.yaml. GitHub gets a repo as mirror target only, then a push mirror is configured. Never create a new project on GitHub first.

Starting a project, mirror operations, credential rotation, and post-reboot recovery of the appliance: ~/.claude/reference-docs/source-control.md.

Shared memory

The memory MCP server is FX's memory, shared with Claude Code and the other agents.

• Before answering a question about FX's infrastructure, projects or earlier decisions, call search with namespace set to the repository name and include_global true.
• When a decision is made, call add straight away with type decision: the choice and the reason for it.
• When FX states something durable about their infrastructure, projects or setup, call add with type fact.
• When FX corrects how you behave, call add with type preference: what to do instead.
• Set namespace to the repository name for anything specific to this project; omit it for what is true everywhere.
• Never store a secret, token or password in a memory.

Reference Materials

• Claude source guidance: ~/.claude/CLAUDE.md
• Source control reference: ~/.claude/reference-docs/source-control.md
• Project workflow references, when present: WORKFLOW.md, WORKFLOW-v2.md, REQUIREMENTS.md, and stories/

Adapted from ~/.claude/CLAUDE.md for Codex. Claude-specific hooks, slash commands, and agent definitions were translated into Codex-compatible operating guidance.