Global work rules: ~/AGENTS.md, ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md

Shared by Claude Code and Codex. The three copies above are deployed from the solo-sdd repository (global/AGENTS.md): edit in the source that solo-sdd status names (the source: line), and run solo-sdd install (from a clone, python3 sync.py push). Pull an edit made in one of the copies with solo-sdd sync pull global/AGENTS.md.

0. Rule order

1. At the start of work in any folder, find the local project rules: AGENTS.md and CLAUDE.md in the current folder and above up to the repository root, solo-sdd/project.md (a project with only openspec/ moves by solo-sdd import openspec), docs/status.md. Read them yourself, without a reminder. Claude does not pick up AGENTS.md automatically, Codex does not pick up CLAUDE.md, so read both.
2. Local rules exist: on any divergence they apply. This file covers only what the local rules are silent about.
3. No local rules: work entirely by this file. If the work in the folder is more than a one-off edit, suggest /project-init in one line.
4. A direct instruction of the user in the current chat wins over both the local and the global rules.

1. Communication

• Reply in the language the user writes in, including the final report and comments for the user.
• Briefly. The result first, then the details. Asked for "briefly": 2-3 sentences.
• Instructions for the user: numbered steps, with the exact name of the button or field ("where to click").
• A report to the owner starts with 2-4 plain lines: what changed for the owner and whether anything is needed from them; file names, settings and PR numbers come after. A step the owner does by hand is written as clicks: the site, the button, the field, what to paste and where it comes from.
• Terminal commands: one block that can be pasted whole; with cd to a full path; no comments on the same line as a command.
• Before asking or saying "this does not exist", reread the chat and the project folder: the user may have given it already. When returning to a project or switching agents: /context-resume.

2. Autonomy

• Do not ask clarifying questions during the work. Make a reasoned decision and list the decisions made in the report.
• Ask only before: paid requests, deleting or overwriting data, actions on prod. The question names what exactly will happen, the number of requests and the amount.
• Whatever you can do yourself, do yourself: running, checking, clicks in the browser, reading logs. Hand manual steps to the user only when you have no access, and say which access exactly.
• Do not stop while there are unfinished items and no real blocker.

Commands and stopping processes

• If a command must not get input, close stdin with < /dev/null. Keep pipes, heredocs and intended input; do not run bare cat, read or interactive interpreters without an input source.
• Run servers and other long-lived processes as managed background tasks and keep their id. Run ordinary builds and tests with a bounded timeout.
• After a timeout, first check the task's state with the standard tool. Do not assume all child processes have ended, and do not "clean them up" by name.
• Do not use pkill, killall, an arbitrary kill (including a numeric PID), osascript, launchctl or shutdown to stop things. Use the built-in stop of the specific task by its id. Managing its processes is the job of the launch environment, which knows what processes it created.
• Do not force a sandbox on all projects: check that the sandbox is compatible with the project's tests before changing the mode. If the sandbox is on for a project on macOS, dev ports need sandbox.network.allowLocalBinding: true. Do not install a build into /Applications without separate consent.

3. What "done" means

• "Done" depends on the kind of work:
  • code: done + checked by tests + checked live on a real scenario + recorded by the project rules (changes: validate, archive; git: commit, push, merge);
    • for a Telegram bot, live means the real bot in Telegram through the connected Telegram tool: open the changed screen, press its buttons, read the reply. A mock or a code run inside the container is not live. After a server update do it before the report;
  • analysis or research: a conclusion, sources with dates, separately what is not confirmed; files do not change;
  • text: facts checked, form and length fit the reader, one ready version;
  • prod: the change is rolled out with consent and checked by the same scenario on prod.
• Git and the change cycle (solo-sdd/) are mandatory where the project and the task provide for them. A one-off text or analysis does not need their cycle.
• Light path: a code edit needs no change when it changes no behaviour a main spec in solo-sdd/specs/ describes, adds no dependency, touches no data, migration or deploy, and changes at most process.light-path.max-files files. Read solo-sdd config get process.light-path and solo-sdd config get process.light-path.max-files; no solo-sdd/ tree or no command: on and 3. Then: the edit, the tests of the edited module, the suite once after the edit, a live check of the edited place, one commit light: <the request> (under delivery.mode: pr the PR title starts with light:). Outside the bounds, a bug in behaviour a spec describes, or off: a change.
• Test runs: while coding only the tests of the edited module (Tests (one)); the whole suite (Tests) once after the last code edit, again only when code changed after that run; after a red run the failed tests first, the suite once they are green. Quiet output (-q, --reporter=dot, --silent); on a red run read only the failure lines.
• Tests prove behaviour: a behaviour a live stand proves gets no second test (a required property test and a bug's regression test excepted); a new case is a row of the existing test; no tests for getters, DTOs, configuration, thin wrappers, private functions a scenario test reaches, one-off scripts or what a CI step checks. Doubles only for external I/O (the network, paid APIs) and the clock; own storage gets a temporary real one or an in-memory fake; the module under test is never mocked. An existing assertion changes or goes only when the behaviour it checks changes on purpose (a MODIFIED or REMOVED requirement); a change of setup, cost or layout keeps every assertion.
• If any of this is missing: write "not done" and what is missing. Green tests by themselves do not mean "done".
• The report names the checks done and, separately, the ones not done with the reason.
• The same edit did not help twice: stop and find the cause instead of a third attempt the same way.

4. Blockers

• No key, access or data: first look for a workaround: mocks, old project data, .env, neighbouring services, documentation.
• No workaround: record what stayed unchecked and what is needed for it (in a change, verification.md and docs/waiting.md), and close everything else.

5. Status and waiting

• Before waiting longer than 2 minutes, say what you wait for and how long.
• In long work, give a status line after every stage.
• Answer a status question with the /work-status skill.

6. Task boundaries

• Asked to analyse, describe or assess: change nothing.
• Asked to fix: change only the named places. Do not rewrite from scratch and do not delete previous versions.
• Work outside the current task becomes a separate task, not done along the way.
• Do not hard-code lists and values that can be got from the source. Temporary hard-coding only on a direct request.

7. Money and resources

• Search, logs and test output run on cheap models; code, review and acceptance on the main one. Effort first, then the model.
• Paid calls to the product model in tests, acceptance and experiments run on the cheapest models.
• Do not start paid requests without approval.
• An external service is needed: free options and free tiers first.
• Watch the context: hand heavy reading to a search subagent (Explore), write code yourself.

8. Secrets and data

• Secrets live only in .env. Do not print them and do not ask to send them in chat: create an empty field and name it.
• Keys, certificates and personal data do not go into git or logs.
• Before an operation on a database or a server, say what will happen to the existing data.
• Use a fact about experience, a metric or a number from history together with its source, date or period and status: confirmed | from an old record | not checked. Apply new calculation rules to new records; recalculating accumulated data only on a direct request.
• All project files are kept inside the project folder.

9. Two agents in one project

• The project has one working folder. Create your copies and worktrees in the built-in Claude Code worktree (claude --worktree <name>, EnterWorktree, isolation: "worktree" of a subagent: the copy goes into the project's .claude/worktrees; this folder must be in .gitignore) or in a temporary folder (git worktree add "${TMPDIR:-/tmp}/wt-<name>") and delete them after yourself. Codex uses only a temporary folder: codex --worktree, /worktree and the create_worktree tool put the copy into ~/.codex/worktrees.
• Before an edit, check git status: another agent may be working next to you. Do not roll back others' changes.
• Before taking a change, check for CLAIM (taken by another agent) and WAITING (waits for an external condition) files in its folder. If either is there, take another.
• An independent review is done by the agent that did not write the code.

10. Orchestration

• You write the code yourself: every handoff between agents loses precision. Subagents are only for independent acceptance and heavy reading (Explore). Independent changes run in parallel through spec-dispatch.
• Codex executors only when the user named the skill codex-orchestration.
• Plan through /spec-plan, debug through /debug-profile. In a project with solo-sdd/ a plugin's own cycle of tests, verification, per-task subagents and code review is not used: spec-next and ship set the cycle.

11. Project mode

• The mode is set in the local rules: demo or prod. If not set, decide by the task: a demo, a defence, a prototype, an MVP mean demo.
• demo: no docker and no deploy, invented data, one demo script, the run command as the first line of the README.
• prod: logs cover every stage so that the cause of a failure can be found from them; there is a deploy instruction.

12. Interface

• A product interface is handed over after checking it against the mockup and clicking every changed element in the browser, on desktop and on a phone. Skill /ui-check.
• /ui-check passes the Hard Gate (antislop rules) with a proof in every line. No DESIGN.md with a Dial line: the interface is marked "draft without direction".
• A personal HTML report without a request for external publication: check display and clicks on desktop; an adaptive check is not required.

13. Git, if the local rules are silent

• After checked work: commit and push. Merge an open PR yourself only when the project's settings let the agent merge (solo-sdd config get delivery.merge-by is agent, or no solo-sdd/ tree), then update the local main branch; with human stop at a green PR: a person merges.
• No --force and no git reset --hard.
• If push or merge triggers a prod deploy (CI, a hook, hosting autodeploy), stop before them and ask. An open PR does not mean a checked prod.
• Skill /ship.

14. Skills

/spec-plan: a plan or a bug list into a queue of small changes · /spec-analyze: a check of a change before code · /spec-next: a change from selection to archive · /ship: commit, push, PR, merge · /work-status: five lines about the state · /spec-audit: an independent check of code against the spec · /ui-check: a check of the interface against the mockup · /copy-check: product texts for people without AI signs or invented facts · /project-init: preparing a new project · /context-resume: restore the context before work · /debug-profile: debugging a service or a bug in code · /agent-quality: AI agent quality by comparison on a set of cases · /evidence-research: comparison and choice on checked facts

Manual commands, only when the user calls them: /relay: another agent's report into work · /blockers: blockers and findings into separate changes · /report: a summary for a period · /health: whether the project's integrations are alive · /changes: a table of change states

Choose a skill by the goal and the expected result, not by a matching word: "analyse" can be about code, logs or a text. If a tool a skill refers to is not in the current environment, take a fallback source (local history, project files, a notes vault) and do not pass off missing data as a fact.

The whole algorithm, with all stages and gates: ~/.local/share/solo-sdd/ALGORITHM.md. The skills of this algorithm are edited in the source from solo-sdd status, in skills/, not in the agent folders: solo-sdd install deploys them and does not overwrite an edit made in place, but shows it.

15. Lessons

• The user corrected you in a way that applies beyond the current task, or you fixed a bug and found its cause: without asking, write one imperative sentence about the class of cause, not the symptom, with no file or line ("Every async call in a handler is awaited", not "add await in api.py"), into the ## Lessons section at the end of the project's AGENTS.md, creating the section if it is missing. This is part of any task, also under "change nothing" or "only the named places"; if the user forbade edits, the report gives it as Lesson (not written): <sentence>. A remark about the current diff only ("rename this variable") is not a lesson.
• First search ## Lessons and the rest of that AGENTS.md: a lesson an existing line covers refines that line instead of adding one. The section holds at most 20 lines; a 21st means merging or generalising the closest lines in the same edit, also without asking.
• No AGENTS.md in the project: create none; the report gives the lesson as Lesson (no AGENTS.md): <sentence>.
• Never write a lesson into the installed global rules (~/AGENTS.md, ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md); a lesson about the solo-sdd process itself goes only into the report as Lesson for solo-sdd: <sentence>.
• The report names every line written or refined in ## Lessons and its file.