claude-copilot
AGENTS.md14 starsChanged 9 days agoMITView on GitHub
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 repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- cleanupSkill
- new-productSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
26 rules. About 0 are common, 7 are distinctive, and 19 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
19
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
When editing Claude agents, preserve their frontmatter (name, description, tools, model), role/mission, Core Behaviors, output format, …
- Very specific: line 15
Read the relevant development guidance in CLAUDE.md when maintaining framework assets, and the corresponding tools/cc/ or tools/tc/ …
- Very specific: line 16
Before publishing/notarization, read docs/30-operations/20-notarization-credentials.md.
- Distinctive: line 17
Keep shared rules consistent across CLAUDE.md and AGENTS.md.
- Very specific: line 25
Check applicable nested AGENTS.md / AGENTS.override.md before working in a subtree.
- Distinctive: line 26
Keep shared project requirements consistent with CLAUDE.md when present.
- Very specific: line 30
Use relevant skills exposed in this session.
- Very specific: line 31
Start with $protocol unless the specialist is obvious.
- Very specific: line 37
Keep progress brief and material.
- Very specific: line 41
Use cc for memory, skills, Live Docs, and configuration.
- Very specific: line 42
Prefer $HOME/.local/bin/cc.
- Very specific: line 43
When configuration is needed, run eval "$($HOME/.local/bin/cc env)".
- Very specific: line 47
Before planning or implementing against an installed third-party package API, run $HOME/.local/bin/cc docs get <package> --topic <area> …
- Very specific: line 48
If cc docs is unavailable, state the limitation and verify against local package files or official documentation before coding.
- Very specific: line 53
Before cc skill select, read …
- Very specific: line 58
Prefer tc, then ./.venv-tc/bin/tc.
- Very specific: line 68
Before completion, run tc task check-qa <id> --json and scripts/copilot-gate.sh --task <id> (in this repo, or under …
- Very specific: line 72
After scoped approval, refill useful independent work within native/resource capacity.
- Very specific: line 74
If absent, report fallback: tc cycle --help governs exclusive writes, actual cwd/branch, native dispatch, one integrator, current …
- Distinctive: line 82
Keep changes focused, preserve user work, omit time estimates, and respect the user's authorization and review boundaries.
- Distinctive: line 87
Do not end a subagent prompt with an enumerated reporting checklist.
- Distinctive: line 94
When an explanation conflicts with a measurement, follow the measurement and narrow the investigation.
- Very specific: line 99
After two hypotheses are falsified, stop hypothesizing.
- Very specific: line 103
Read SOUL.md before substantial product-facing work to decide whether the direction belongs here.
- Very specific: line 104
Read docs/01-architecture/12-architecture-guiding-principles.md for durable architecture, migration, data, security, performance, or AI …
- Distinctive: line 105
When either instrument changes the route, state that before continuing.
≈ “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
Agent Instructions
Project Overview
- Project:
claude-copilot - Description: Public Claude Code instruction framework with specialist agents, lifecycle hooks, and the shared cc/tc command-line tools.
- Stack: Markdown agents/skills/commands; shell hooks; Python cc/tc tooling; Node utility scripts
Project-Specific Rules
- This repository owns the public Claude Copilot framework and the shared
cc/tctools. Keep base agents generic and company-specific behavior in extension tiers. VERSION.json.frameworkis the framework version authority;package.json.versionmirrors it. Component versions inVERSION.json.componentsare independent; never update the package version alone.- When editing Claude agents, preserve their frontmatter (name, description, tools, model), role/mission, Core Behaviors, output format, Route To Other Agent, and Task Copilot Integration. Use industry-standard methods and document decision authority.
- Claude runtime guardrails, hook schemas,
@agent-*routing, and slash commands describe the product maintained here; they are not Codex runtime features. Use Codex-native playbooks and visible delegation within the approved scoped plan; Claude hook payloads do not enforce Codex behavior. - Read the relevant development guidance in
CLAUDE.mdwhen maintaining framework assets, and the correspondingtools/cc/ortools/tc/documentation when changing those tools. Do not import Claude session/delegation instructions into Codex. - Before publishing/notarization, read
docs/30-operations/20-notarization-credentials.md. - Keep shared rules consistent across CLAUDE.md and AGENTS.md; preserve scope and place tool-specific rules in their own entrypoint.
Project Commands
- For framework setup and verification, read
README.mdandCONTRIBUTING.md; for Python tool dependencies and focused tests, use the correspondingtools/cc/ortools/tc/project configuration. From the root,bash scripts/check-versions.shchecks version consistency. No application dev server applies.
Instruction Scope
- Check applicable nested
AGENTS.md/AGENTS.override.mdbefore working in a subtree. Preserve scoped rules; references and Claudepaths:frontmatter are not automatic Codex imports. - Keep shared project requirements consistent with
CLAUDE.mdwhen present; preserve scope and keep tool-specific routing separate. Do not import either whole entrypoint into the other.
Codex Copilot
- Use relevant skills exposed in this session.
$protocoland specialist names are shorthand, not shell commands or requests to spawn agents. Read only task-relevant skills/references. - Start with
$protocolunless the specialist is obvious; use$launcherwhen routing is unclear. Apply playbooks locally; if unavailable in the session, inspect~/.copilot/current/codex-copilot/plugins/codex-copilot/skills/<name>/SKILL.md. Report missing capabilities.
Output Contract
- Lead with the answer, decision, result, or blocker. Default to 6 sentences or 5 bullets; expand when completeness requires it. Preserve findings, uncertainty, citations, QA evidence, safety warnings, Task/WP identifiers, and blockers.
- For real decisions, give 2–3 concrete outcome options and a short question. Do not manufacture decisions or ask again for authorized work.
- Keep progress brief and material. Report outcome, changed scope, verification, and limitations at completion; store detail in
tcwork products.
cc CLI
- Use
ccfor memory, skills, Live Docs, and configuration;tcfor tasks/work products. The retired Copilot MCP servers and theirinitiative_*,memory_*, andskill_*tools do not exist. - Prefer
$HOME/.local/bin/cc; verify bareccis not the C compiler. Source: Claude Copilottools/cc/. Config:.claude/cc/config.json; memory:.claude/memory/entries/. - When configuration is needed, run
eval "$($HOME/.local/bin/cc env)"; use returned values instead of machine-specific paths.
Live Docs
- Before planning or implementing against an installed third-party package API, run
$HOME/.local/bin/cc docs get <package> --topic <area> --json. - If
cc docsis unavailable, state the limitation and verify against local package files or official documentation before coding.
Knowledge and Optional Context
- For brand, voice, product, or methodology knowledge, hydrate
cc env; follow project consumption-contract pointers through comma-separatedCC_KNOWLEDGE_REPOS, nearest tier first, reading the first matching sub-path. Never use singularCC_KNOWLEDGE_REPOfor sub-path lookup. Report missing sources; never invent company facts. - Before
cc skill select, read~/.copilot/current/codex-copilot/plugins/codex-copilot/skills/specialist-agents/references/shared-behaviors.md, sectionOptional Context. Follow its load-once, receipt, and fallback rules; mandatory instructions are never relevance-filtered.
Task Management
- Track substantial work in
tcPRDs/tasks and store detailed work products there; create missing records. Usecc memoryfor durable decisions and lessons. - Prefer
tc, then./.venv-tc/bin/tc; use--jsonwhere supported. Read~/.copilot/current/codex-copilot/plugins/codex-copilot/skills/task-copilot/SKILL.mdwhen managing tasks. - Batch three or more related operations using
tc.api, or separatelycc.api, with a verified interpreter. Never mix these APIs in one process. - Formal initiatives belong in
docs/40-initiatives/NN-slug/, indexed indocs/40-initiatives/README.md. Start with one maintainedREADME.md; create supporting files only when current work needs them. Consolidate completed work into that README while retaining required original evidence separately. Markdown holds durable rationale/evidence;tcowns live state. Never createdocs/initiatives/.
QA Gate Convention
- For verification-required implementation, set
metadata.requiresQa=trueand register observable criteria and source scope withtc task contract <id> --file <path>(schemaVersion: 2) before implementing. $mestores implementation evidence;$qaverifies it. Read their installed evidence contracts for those tasks.- Capture
tc task evidence-identity <id>before and after checks, preserve the exactIDENTITY:line, and rerun affected checks if the tested content changes. - Store a task-bound
testwork product with matchingCRITERION:/EXPECTED:, actual observations, inspectableARTIFACT:evidence, untested scope, and oneVERDICT:. Missing required behavior, bare markers, or stale evidence cannot support approval. - Before completion, run
tc task check-qa <id> --jsonandscripts/copilot-gate.sh --task <id>(in this repo, or under~/.copilot/current/claude-copilot/scripts/). Never removerequiresQato bypass QA; installed hooks alone prove neither enforcement nor approval.
Protocol-native parallel execution
After scoped approval, refill useful independent work within native/resource capacity. Protocol conditionally discovers canonical organization policy with cc skill list --scope machine --json and loads the listed parallel-execution name once; both Copilots share it. /orchestrate redirects there.
If absent, report fallback: tc cycle --help governs exclusive writes, actual cwd/branch, native dispatch, one integrator, current independent QA and authorized safe retirement. Read-only research needs no worktree; report missing cycle capability honestly.
Blast-Radius QA: replaces prior QA-depth rules. Test affected behavior; both Copilots read cc skill get blast-radius-qa --scope machine --json.
Framework Rules
- Experience work starts with
$sd/$uxd; visual direction uses$uidsbefore$uid. Architecture and non-trivial technical work use$ta;$meimplements and$qaverifies. - Bugs follow
$qa -> $me -> $qa; security-sensitive work includes$sec; infrastructure changes needing implementation follow$do -> $me -> $qa. - Keep changes focused, preserve user work, omit time estimates, and respect the user's authorization and review boundaries.
- Approved scoped work uses visible, validated native agent fan-out by default; retain runtime limits, exclusive write ownership and the existing task/QA authority.
Delegating to Subagents
- Do not end a subagent prompt with an enumerated reporting checklist.
- The standing return contract is at most three sentences: outcome, root cause if known, and anything anomalous or requiring a decision. Put full evidence in a file and return its path.
- Surface every safety-relevant anomaly in those three sentences; never bury it only in the evidence file.
- Request more depth only when the decision genuinely depends on it.
Debugging Discipline
When an explanation conflicts with a measurement, follow the measurement and narrow the investigation.
- Confirm a mechanism exists in the relevant environment, plan, or account before naming it as the cause.
- State what every diagnostic exercised, including the selected key, config, binary, branch, interpreter, and working directory when relevant.
- Count failures through one shared dependency as one observation unless that dependency is varied.
- After two hypotheses are falsified, stop hypothesizing. Read the code that enforces the behavior and cite
file:line.
Decision Instruments
- Read
SOUL.mdbefore substantial product-facing work to decide whether the direction belongs here; report missing or unfilled purpose rather than inventing it. - Read
docs/01-architecture/12-architecture-guiding-principles.mdfor durable architecture, migration, data, security, performance, or AI pipeline decisions. Report a missing reference and use verified project authority. - When either instrument changes the route, state that before continuing.
Work lifecycle
Read .claude/agents/_shared/work-lifecycle.md once per task and apply its proportional start/resume, during-work, handoff, finish and later-use checkpoints, including direct invocation. Use the existing task and maintained narrative; selective memory pointers must not duplicate them. Preserve exact destructive approval and recovery, original authority and required assets. Substantial QA-required work needs an observable WORK-LIFECYCLE criterion before acceptance freezes; cleanup status and product acceptance remain separate.
At start/resume (including a new PRD or initiative) and finish/merge/pause/handoff, proactively inspect relevant worktrees and surface eligible cleanup with exact paths, recovery and dependency checks, then automatically retire eligible recorded merged worktrees during cleanup under the owner’s 4 November 2026 narrow exception; prepare exact approval for any other deletion. Merge alone is insufficient. Record owned holds and pending approval in the existing task, continue unrelated work, and reuse unchanged prior approval after drift checks.
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.

