AGENTS.md

You must follow all of the rules, checks and recommendations in this file for every request.

The user will comment out anything that they dont want included in your instructions. If something is commented out, it should be ignored.

Pre-work

Confirm all of these items are present before starting work on a task:

Eslint is configured and active (for javascrpt based projects)
Eslint rules include no explicit or implicit any
There is a pnpm lint script to run typescript across all of the project
There is a precommit hook for running lint
There is a precommit hook for running typechecks
There is a precommit hook for running unit test suite
There is a precommit hook for running smoke test suite

Work rules

DO NOT RUN git add, git commit or git push commands
DO NOT RUN any rm type commands (that permanently delete things with no means of recovery)
Do not "custom code" things when there are high-quality, well-supported libs/packages already in exsitence that can be used instead - always search for and recommend well supported popular libraries first.
Follow directions and do not make assumptions or take liberties without explicitly asking and getting written confirmation. We do not want you to be improvising, only listening and following directions

Development flow

Do not make assumptions about errors and error correction - always first research the most updated documentation on all relevant libraries and things involved and Ensure that there are robust verbose logging and telemetry at every item. And point so that debugging becomes easy and scientific.

Conversation preferences/rules

When you are providing any commands for the user to run at the command line, provide them in a way that is compatible for the user to simply copy and paste the entire item in one go Knowing that the user is receiving your response inside an existing terminal and this terminal does not support unwrapping lines. So if any line is longer than just a few characters, it will end up on the next line and break the command... Also, the user is using ZSH, which does not support comments.
Keep your explanations and responses as concise as possible to limit the amount of reading that needs to be done without sacrificing critical context.

Verifiability & accountability

Utilize all available MCP servers to have as much context and information as possible to ensure code adds/edits are done correctly and efficiently
If there is no available relevant MCP server for a specific need enabled in the environment do a web search for potential options and recommend them to the user for setup

Acceptance Criteria

Before asking the user to do anything to check your work or go see the changes, make sure that you do it first and confirm with logging, screenshots and any other tools available that the implementation was done correctly and bug free. These are items that must be done before you can consider your work done on a task.

AUTOMATED CHECKS:

Before calling a task finished:

Run lint to ensure there are no errors or warnings surfacing (they must be fixed, not ignored)
Run typecheck to ensure there are no errors or warnings surfacing (they must be fixed, not ignored)
Run unit tests to ensure there are no errors or warnings surfacing
Run axe tests
Run validate products

MANUAL CHECKS:

Use the playwright MCP to visually inspect any relevant visual changes and expectations in both desktop and mobile view, and use it to get console and network logs to make sure all warnings/errors are clear

Always prefer to use playwright MCP in HEADLESS MODE as to not disrupt user's computer with browser windows if possible * sometimes headless may not work like in the case of working on browser extensions

Raw

explainer.md

EXPLAINER

Create and configure an AGENTS.md file

Update AGENTS.md as you go with improvements/reflections

Anytime you find a bug write a test to cover it.

-anytime you find a solution to a problem that has taken more than one request, you should figure out what the difference was that the AI actually did to catch it and fix it and try and turn that into one of your agent rules:

Configure your ~/.codex/config.toml file with relevant MCP servers

An example config:

# ── ESLint (lint/fix via MCP)
[mcp_servers.eslint]
command = "npx"
args = ["@eslint/mcp@latest"]

# ── Circuit (Snowfort) – Electron automation
[mcp_servers.circuit_electron]
command = "npx"
args = ["@snowfort/circuit-electron@latest"]
# For Electron dev apps, the tools will launch your app; they don't attach to an already-running process.

# ── Electron
[mcp_servers.electron_debug]
command = "npx"
args = ["-y", "electron-mcp-server"]

[mcp_servers.electron_terminal]
command = "npx"
args = ["-y", "electron-terminal-mcp"]

[mcp_servers.vitest]
command = "npx"
args = ["-y", "@madrus/vitest-mcp-server@latest"]
env = { VITEST_PROJECT_DIR = "/absolute/path/to/your/project" }

[mcp_servers.test_runner]
command = "npx"
args = ["-y", "test-runner-mcp"]

# ── BrowserTools (logs, network, audits from Chrome via extension)
[mcp_servers.browser_tools]
command = "npx"
args = ["@agentdeskai/browser-tools-mcp@latest"]
# NOTE: You also run the sidecar in a terminal:  npx @agentdeskai/browser-tools-server@latest

# ── Circuit (Snowfort) – Web automation
[mcp_servers.circuit_web]
command = "npx"
args = ["@snowfort/circuit-web@latest"]
# Example dev flags:
# args = ["@snowfort/circuit-web@latest", "--headed", "--browser", "chromium"]

# ── Browser automation: Playwright
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
# Optional examples:
# args = ["@playwright/mcp@latest", "--browser", "chromium", "--caps", "pdf"]
# args = ["@playwright/mcp@latest", "--allowed-origins", "https://serp.ai;https://github.com"]

Example successes

Provide acceptance criteria for each request and how the agent should do it.

Manual check by me confirms

Note: Could improve this even more by generating a report to verify.

Raw

gitflow.md

Gitflow

1. Use a feature branch for every new feature

Create a feature branch

git checkout -b some-feature

Work with codex to carefully plan out a step by step PLAN.md file for the next 'feature' youre working on:

Have codecs update it as you work through it.

It will help you and it stay on track and also provide context for later conversations if needed.

2. Verify every diff after each request (manually verify)

You may not know how to write the code exactly, but you should know what is supposed to be getting coded.

If you don't know what's going on, you have to stop doing what you're doing and learn a little bit more.

Once you know enough to understand if things sort of look right or wrong, then you're ready to read every single diff that the AI is doing and verify in your head mentally that yes, this is good or no, this is going in the wrong direction.