moai-cowork
AGENTS.md307 starsChanged 53 days agoApache-2.0View on GitHub
Every clause here binds a turn regardless of which agent harness drives it. The file is self-sufficient: it does not depend on another instruction file. If a nested AGENTS.md exists, Codex loads it as an additional, more-specific contract; the merged byte budget must cover the whole discovery chain. Budget warning. Codex charges its instruction byte budget against project instruction files only; a personal ~/.codex/AGENTS.md does not shrink it. Overflow is truncated from the tail, silently — no warning, no stderr,…
- Deletes or force-pushes
1 other project uses a version of this.
Adopted by
Most recently taken up by
- modu-ai/cowork-pluginsword for word, first seen Oct 8, 2026
Other versions1 project uses a version of this.
Word for word · 1
- modu-ai/cowork-plugins★ 308100% same
Edited · 0
None found.
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository17 other files it gives its agents.
- moai-cleanSkill
- moai-codemapsSkill
- moai-e2eSkill
- moai-feedbackSkill
- moai-fixSkill
- moai-gateSkill
- moai-goalSkill
- moai-gtdSkill
- moai-harnessSkill
- moai-loopSkill
- moai-mxSkill
- moai-planSkill
- moai-projectSkill
- moai-reviewSkill
- moai-runSkill
- moai-syncSkill
- moai-todoSkill
The file
We split this AGENTS.md into the rules it gives an agent
12 rules. About 0 are common, 9 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 3
Every clause here binds a turn regardless of which agent harness drives it.
- Very specific: line 13
Direct Codex startup: When using codex -C <worktree> directly, read a present worktree-root AGENTS.local.md in full before other project …
- Distinctive: line 61
Baseline-integrity attribution: Every verification claim MUST be attributed to an actually-measured baseline — the command that was run …
- Distinctive: line 163
Scope verification to the change: run the tests the change can affect, then push and let CI run the full suite.
- Distinctive: line 189
1. Surface assumptions: Before implementing anything non-trivial, list assumptions explicitly and wait for confirmation.
- Distinctive: line 207
NOT be used to drop input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility, or one …
- Distinctive: line 218
6. Verify, don't assume: Every task requires evidence of completion.
- Very specific: line 237
Write non-ASCII payloads as native UTF-8: Every tool-call payload carrying conversation_language text — command strings, file content, …
- Distinctive: line 245
XML is reserved for agent-to-agent data transfer: Use semantic XML sections for structured data exchange between agents.
- Distinctive: line 248
Never use time predictions in plans or reports: Use priority labels (High / Medium / Low) and phase ordering ("complete A, then start B").
- Distinctive: line 277
Weigh session length as a cost axis: Prefer one warm session for the same work.
- Very specific: line 326
Run moai --help for the generated, current command surface.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — standing contract for agents in this repository
Every clause here binds a turn regardless of which agent harness drives it. The file is
self-sufficient: it does not depend on another instruction file. If a nested AGENTS.md
exists, Codex loads it as an additional, more-specific contract; the merged byte budget must cover
the whole discovery chain.
Budget warning. Codex charges its instruction byte budget against
project instruction files only; a personal ~/.codex/AGENTS.md does not shrink it. Overflow is
truncated from the tail, silently — no warning, no stderr, exit 0. Clauses below are ordered
most-critical-first for that reason.
Direct Codex startup. When using codex -C <worktree> directly, read a present
worktree-root AGENTS.local.md in full before other project work and follow it as local
project guidance. If it exists but cannot be read, stop and report the failure. The
MoAI Codex launcher injects this file before the session instead; see §8.
This file is the canonical cross-harness contract. Shared detail lives in
.moai/policies/** and .moai/workflows/**. When Claude is installed,
.claude/rules/moai/** and CLAUDE.md expand Claude-only mechanisms (question
channel, subagent spawning, skills, session handoff); they do not override a
cross-harness clause here. Compression removed rationale and incident records,
never an obligation.
Capability bindings. Names below are the neutral tool classes; a row exists only where a harness driving this contract lacks the capability.
| Capability | Claude implementation | If this harness lacks it |
| question-channel | AskUserQuestion | Return a blocker report naming the missing input instead of asking in prose |
| task-list | TaskCreate / TaskUpdate / TaskList / TaskGet | Track the work and report progress in prose |
| design-sync | DesignSync | Skip the design-sync surface; say so in the report |
| agent-spawning | Agent(...) sub-agents | Do the bounded work inline |
| output-style | Claude output styles | Follow this contract directly |
| slash-commands | /moai slash commands | Use the underlying moai CLI verbs |
| workflow-scripts | Workflow scripts (ultracode) | Run the steps sequentially |
| worktree-entry | Claude: moai cc -w <name> for Claude-native trees or moai cc -w <absolute-path> for MoAI trees; Codex app: select Worktree; Codex CLI: moai worktree new <name> then codex -C <absolute-path> | An active Codex session uses git -C <absolute-path>; moai codex -w starts a new session in an existing tree only |
| audit-verdict-file | The auditor agent writes its own verdict or report file | On Codex, start the read-only roles (plan-auditor, sync-auditor, mission-governor, super-advisor) through the launcher, the moai MCP tool codex_role_audit, and never through spawn_agent, which would hand them your own writing sandbox. Pass role, your own worktree root as worktree_root, the task as task, and the verdict or report path under .moai/reports/ as out; the tool returns a job id at once, and codex_role_audit_status / codex_role_audit_result report on it. The role runs as one top-level read-only codex exec process, and the launcher writes the verdict or report file with exactly the returned text, unedited |
Skill("<name>") instructions carry no row, and are read literally. skill-loader is a
capability every harness driving this contract has, so it earns no row above; what is Claude-only
is the per-agent grant, not the reach. Where a harness loads a skill by reading it rather than by
calling a tool, the deployed skill is in .agents/skills/<name>/SKILL.md for Codex and
.claude/skills/<name>/SKILL.md for Claude. The both profile installs both paths.
Skill("moai-workflow-tdd") names the corresponding deployed SKILL.md. Agent bodies keep
the tool-call wording for that reason — it is an address, not a Claude-only instruction.
Codex-side loading is deferred — read the mirrored SKILL.md directly; no loader resolves
Skill("...") calls.
1. Evidence and verification claims
No unobserved claim. An actor MUST NOT assert a verification, a completion, a defect / debt / drift, OR the premise underlying a recommendation it did not actually verify with the domain's mechanical tooling. Evidence absent is not evidence of success — nor of failure. The absence of a failure signal never establishes that a check passed; a text-pattern inference is a hypothesis, not a verified defect; a reference existing does not establish that the referenced capability is still live. Reachability is not justification.
Baseline-integrity attribution. Every verification claim MUST be attributed to an actually-measured baseline — the command that was run plus the output observed, in this run, against this tree. A figure carried over from another package, tree, or point in time is not a baseline; using it as a fresh measurement violates this. Anything unattributed is a Gap, not a Claim.
Evidence-bearing report format. Verification and completion reports SHOULD carry five sections: Claim, Evidence (command plus verbatim output), Baseline-attribution (tree measured in this run), Gaps (explicitly unobserved), and Residual-risk. An empty Gaps section claims nothing was left unobserved and is valid only when true.
2. Git, branches, and the shared checkout
The primary checkout is shared — several sessions may work in it at once, and branch state there is global.
Never change branch state in the primary checkout. Forbidden there: git checkout <branch> /
git switch (relocates every concurrent session's tree); git checkout -b / git switch -c /
git branch (same, plus an unexpected branch); git reset --hard / git checkout -- <path>
(discards work of unknown provenance); git stash (repository-global — it silently absorbs another
session's uncommitted changes); git rebase / git merge onto the checked-out branch (rewrites or
advances shared history mid-operation). Read-only inspection, git fetch, commits to the
already-checked-out branch, and pushing it are permitted.
Re-read branch and commit state immediately before any commit or push — never a value read earlier in the turn, never the branch reported at session start:
git rev-parse --short HEAD
git branch --show-currentA difference from what the turn assumed means another actor is writing the same tree: stop and report the divergence instead of proceeding.
Never sweep-stage. In the primary checkout, never git add -A, git add ., or
git commit -a. Stage by explicit pathspec and re-read git status --short immediately before
staging, so another session's files are visible and excluded. This binds even when no foreign
session was detected — one can arrive after the check, and the sweep is what turns its presence
into lost work.
Detect parallel sessions before a non-trivial direct edit to a shared path (.claude/,
.moai/, internal/, pkg/, cmd/, repo-root config), and surface any divergence:
default_ref="$(git symbolic-ref --quiet --short refs/remotes/origin/HEAD)"
test -n "$default_ref"
git fetch origin "${default_ref#origin/}" 2>&1
git rev-list --count --left-right "$default_ref"...HEAD0 0 or 0 N proceeds; N 0 or N M means resolve before editing. Where another live session
shares the checkout, isolate into a worktree rather than editing in the shared tree. The check
decays — re-run it before any commit and after a long pause. If origin/HEAD is unresolved, stop
and resolve the remote default branch instead of assuming main.
3. Worktrees
Work inside an isolated worktree. moai worktree new <name> creates a MoAI tree under
.moai/worktrees/. Claude Code uses moai cc -w <name> for its native .claude/worktrees/
location or moai cc -w <absolute-path> for a MoAI tree; EnterWorktree(<path>) and
ExitWorktree are Claude Code session tools. Codex app users select Worktree when starting a
chat. Codex CLI uses codex -C <absolute-worktree-path> for a new session; an active Codex
session operates through git -C <absolute-worktree-path> and direct file operations.
moai codex -w only launches a new Codex session in an existing tree. A Codex agent must not
invoke moai cc -w, EnterWorktree, or ExitWorktree. Never create a tree with bare
git worktree add.
From inside a worktree session, <path> must be that worktree's absolute path. Measured on
Claude Code 2.1.275: the guard refuses -C ., a relative path, a runtime-computed path, and any
path outside this worktree; plain git, git -C <own absolute path> and --git-dir=<own .git> pass.
cd <own worktree> && git … also passes the guard, which does NOT make it advisable — the reason
above still holds. A refusal here is the guard reading the command, not a runtime defect.
moai worktree done closes L2 trees only. A tree under .claude/worktrees/ or .moai/worktrees/ is L1, is absent
from the registry, and is disposed by the session-end prompt or by git worktree unlock +
git worktree remove.
A card's branch is unpushed, so its worktree holds the only copy of the work. Dispose of no worktree — L1 or L2 — until the branch is integrated and the remote merge has landed.
Start a new card in a new worktree. A Claude Code session exits its previous worktree first; a Codex lane starts a new session in the new card tree. Create the fresh tree from the remote default branch; never reuse the previous card's tree. Where the new card depends on a prior card's unmerged code, merge that branch inside the new worktree.
Card worktree branches carry the WT- prefix and a descriptive slug, never the card id. Rename
in place immediately after creating the tree: git branch -m WT-<slug>. Re-entry resolves by tree
name, so the rename is safe; the worktree directory keeps the card id.
Three traceability carriers are then mandatory, because the branch name no longer identifies
the card: the dispatch's card: field, the card id in every commit message on the branch, and the
card id in the evidence path (.moai/reports/<card-id>/verdict.md).
4. How verification is run
Scope verification to the change: run the tests the change can affect, then push and let CI run the full suite. A full-suite run on a loaded developer machine measures the machine, not the code.
Never spawn background load. Where a verification needs contention, the load must be
cleanup-guaranteed — kills registered with the test framework's cleanup hook, or a timeout
wrapper bounding the process from outside. A trailing kill is not cleanup.
Scrub the environment in one compound invocation. Inside a worktree, an environment-scrubbed
verification runs as a single unset <VARS> && <command> call; a separate unset does not carry
into the next command, because each invocation is a fresh process.
Batch independent read-only verifications rather than serializing them across turns. Serialize only for a genuine dependency: one command's output feeding another, writes to the same path, or shared-state mutation.
A CodeRabbit row in gh pr checks is not evidence that a review ran — the status reads
success and prints pass identically whether or not one did. Count the row only when BOTH hold:
(1) gh api "repos/$repo/commits/$head_sha/status" reports the CodeRabbit context with
state == "success" and description Review completed; (2) a Merge Risk: line exists whose
commit prefix matches the current headRefOid. Anything else is a gap, not a pass; Review rate
limited means the review never started.
5. Core behaviors
1. Surface assumptions. Before implementing anything non-trivial, list assumptions explicitly and wait for confirmation. State them as a short list and invite correction.
2. Manage confusion actively. On an inconsistency, a conflicting requirement, or an unclear specification: STOP — do not guess; name the confusion, present the tradeoff or question, and wait.
3. Push back when warranted. Say so directly when an approach has a concrete downside, contradicts an established convention without justification, or breaks a tested invariant. State the issue, quantify the downside ("adds ~200 ms latency", not "might be slower"), propose an alternative, and accept an override once the user has full information.
4. Enforce simplicity. Actively resist overcomplexity; generation tends toward over-engineering. Before completing, ask: fewer lines without losing clarity? are these abstractions earning their complexity? would a staff engineer ask "why didn't you just…"? Apply the ladder in order, cheapest capability first: (1) does this need building at all? (2) does a helper, type, or pattern already exist here — reuse it; (3) does the standard library do it; (4) a native platform feature; (5) an already-installed dependency; (6) can it be one line; (7) only then, the minimum code that works. The ladder is language-neutral. Never simplify away safety: it MUST NOT be used to drop input validation at trust boundaries, error handling that prevents data loss, security measures, accessibility, or one runnable check behind non-trivial logic. If an implementation exceeds 3× the estimated minimum viable line count, stop and simplify first.
5. Maintain scope discipline. Touch only what you were asked to touch; drive-by refactors create noise and risk regressions. Do NOT remove comments you do not understand, clean up code orthogonal to the task, refactor adjacent systems as a side effect, delete seemingly-unused code without explicit approval, or add unrequested features because they seem useful. Match the existing style of the file being modified — naming, error handling, import organization; consistency within a file outranks personal preference.
6. Verify, don't assume. Every task requires evidence of completion; "seems right" is never sufficient. Tests passing means showing the test output; a build succeeding, the build output; a file created, reading it back; behavior correct, the runtime evidence. For ad-hoc work without a spec, define the goal as a testable assertion first — "done when X produces Y" — then verify it.
6. Output, language, and format
Respond in the user's configured conversation_language. Code, identifiers, paths, commands,
and flags stay in their original form.
Non-English output must be native idiom, not English mapped word-for-word. When
conversation_language ≠ en, every user-facing surface — chat, reports, README, docs, generated
sites, question text — MUST read as natural native prose. Translation-style calques (carry-over of
English syntax, metaphor, and figurative stock) are prohibited; native idiom is required. Chat uses
the colloquial native register, artifacts the clean native written register. Deliberately-coined
brand terms and established loanwords are not calques.
Write non-ASCII payloads as native UTF-8. Every tool-call payload carrying
conversation_language text — command strings, file content, question text — MUST be native UTF-8;
hand-authored \uXXXX escapes are PROHIBITED, because a malformed escape corrupts the payload into
a validation error and tends to be copied forward. On such a failure, re-author the text from its
intended meaning rather than repairing the escape.
User-facing output is Markdown; never display XML tags to users.
XML is reserved for agent-to-agent data transfer. Use semantic XML sections for structured data exchange between agents; never surface XML structure in user-facing output.
Never use time predictions in plans or reports. Use priority labels (High / Medium / Low) and phase ordering ("complete A, then start B"). Prohibited: "2-3 days", "1 week", "as soon as possible".
7. Tools and command output
Follow tool usage patterns optimized for accuracy and efficiency. Read a file before editing it. Locate before reading — find the file by pattern, find the line by content, then read that region rather than the whole file. Use absolute paths and verify a path exists rather than constructing it from an assumption. Prefer a targeted edit over rewriting a file, and a dedicated tool over a shell equivalent. Retry safety is asymmetric: read-only and idempotent calls may be retried, but a side-effecting one (write, commit, push, PR, deploy, external mutation) that fails ambiguously requires observing current state first and retrying only when the effect is confirmed absent — no success signal is not evidence the effect did not land. After three failures on one operation, report the blocker.
Maintain effectiveness without MCP servers. Where one is unavailable, fall back to web search and fetch for library documentation and established patterns, then continue — analysis quality must not depend on MCP availability.
Keep command output bounded: quiet flags, targeted queries, or redirect-to-file with the exit code and a bounded tail. A runtime output limit is a backstop, not the target.
Prefer the quiet form of routine commands — --no-progress, -q, machine-readable output plus
a targeted filter — not forms emitting spinners, banners, tables, or color noise. The same decision
bytes at a fraction of the context cost.
Weigh session length as a cost axis. Prefer one warm session for the same work; a new or cold session re-pays the always-loaded prefix. Split only when the benefit justifies that cost.
8. Harness-local instructions
moai codex reads the project's common local guidance — the gitignored, never-deployed file that
CLAUDE.md imports last — followed by any legacy local guidance, from the project root. It keeps
each input body under its own source header and passes the result as one Codex-specific session
developer_instructions override. This contract never imports local guidance, which keeps it out of
Codex's discovered chain. In a linked worktree, Claude Code resolves that import when the local
file exists inside the worktree's checkout; it skips an absent file or one outside the project.
Direct codex -C <worktree> uses Codex's AGENTS.md discovery and does not preload a sibling
local file. Direct sessions follow the startup rule above. The MoAI Codex launcher instead
injects that content before the session starts.
Other harness-local settings and memory remain owned by their harness.
Codex Web sessions read AGENTS.md, but local .codex/hooks.json, the status line, and the MoAI
launcher injection do not run there. Treat Web sessions as read-and-review first.
9. Hook Event Coverage
Codex currently wires SessionStart, SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, and SubagentStop. It does not wire PreCompact, PostCompact, PermissionRequest, or Interrupt; Claude-only Notification, PostToolUseFailure, TeammateIdle, and TaskCompleted never fire under Codex. Verify coverage before relying on a hook.
10. Configuration Map
Project configuration lives in .moai/config/sections/*.yaml. Harness, TRUST 5, and phase LSP
thresholds come from harness.yaml, quality.yaml, lsp.yaml, and evaluator profiles; never
duplicate those values inline.
11. moai CLI Verbs
| Verb | Purpose |
moai init <project> --llm claude|codex|both | Scaffold a project and select its LLM harness |
moai update | Sync templates and refresh already-enabled wiring |
moai tool enable codex | Add or refresh Codex wiring in an existing project |
moai hook <event> | Hook dispatcher entry point (drives hooks.json / settings.json) |
moai doctor | Diagnose installation and wiring health |
moai worktree | Worktree lifecycle (sync / remove / clean / recover / done / snapshot / verify / restore) |
moai cc / moai glm / moai gpt | Explicit Claude, GLM, or GPT session launchers |
moai migrate cg | Preview legacy CG migration; role changes require explicit acceptance |
moai version | Print build version and provenance |
moai codex | Codex session launcher — cli launch, status readout, app web; -w <worktree> enters an existing tree and never creates one |
Run moai --help for the generated, current command surface.
12. Status Line Tokens
moai statusline reads .moai/state/ and honors MOAI_STATUSLINE_CONTEXT_SIZE. Read
internal/statusline for the current token set; do not duplicate it here.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

