agentleFS
Everyone-Needs-A-CopilotEveryone-Needs-A-Copilot/claude-copilot/AGENTS.md

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.

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
  1. Distinctive:

    When editing Claude agents, preserve their frontmatter (name, description, tools, model), role/mission, Core Behaviors, output format, …

    line 13
  2. Very specific:

    Read the relevant development guidance in CLAUDE.md when maintaining framework assets, and the corresponding tools/cc/ or tools/tc/ …

    line 15
  3. Very specific:

    Before publishing/notarization, read docs/30-operations/20-notarization-credentials.md.

    line 16
  4. Distinctive:

    Keep shared rules consistent across CLAUDE.md and AGENTS.md.

    line 17
  5. Very specific:

    Check applicable nested AGENTS.md / AGENTS.override.md before working in a subtree.

    line 25
  6. Distinctive:

    Keep shared project requirements consistent with CLAUDE.md when present.

    line 26
  7. Very specific:

    Use relevant skills exposed in this session.

    line 30
  8. Very specific:

    Start with $protocol unless the specialist is obvious.

    line 31
  9. Very specific:

    Keep progress brief and material.

    line 37
  10. Very specific:

    Use cc for memory, skills, Live Docs, and configuration.

    line 41
  11. Very specific:

    Prefer $HOME/.local/bin/cc.

    line 42
  12. Very specific:

    When configuration is needed, run eval "$($HOME/.local/bin/cc env)".

    line 43
  13. Very specific:

    Before planning or implementing against an installed third-party package API, run $HOME/.local/bin/cc docs get <package> --topic <area> …

    line 47
  14. Very specific:

    If cc docs is unavailable, state the limitation and verify against local package files or official documentation before coding.

    line 48
  15. Very specific:

    Before cc skill select, read …

    line 53
  16. Very specific:

    Prefer tc, then ./.venv-tc/bin/tc.

    line 58
  17. Very specific:

    Before completion, run tc task check-qa <id> --json and scripts/copilot-gate.sh --task <id> (in this repo, or under …

    line 68
  18. Very specific:

    After scoped approval, refill useful independent work within native/resource capacity.

    line 72
  19. Very specific:

    If absent, report fallback: tc cycle --help governs exclusive writes, actual cwd/branch, native dispatch, one integrator, current …

    line 74
  20. Distinctive:

    Keep changes focused, preserve user work, omit time estimates, and respect the user's authorization and review boundaries.

    line 82
  21. Distinctive:

    Do not end a subagent prompt with an enumerated reporting checklist.

    line 87
  22. Distinctive:

    When an explanation conflicts with a measurement, follow the measurement and narrow the investigation.

    line 94
  23. Very specific:

    After two hypotheses are falsified, stop hypothesizing.

    line 99
  24. Very specific:

    Read SOUL.md before substantial product-facing work to decide whether the direction belongs here.

    line 103
  25. Very specific:

    Read docs/01-architecture/12-architecture-guiding-principles.md for durable architecture, migration, data, security, performance, or AI …

    line 104
  26. Distinctive:

    When either instrument changes the route, state that before continuing.

    line 105

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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 / tc tools. Keep base agents generic and company-specific behavior in extension tiers.
  • VERSION.json.framework is the framework version authority; package.json.version mirrors it. Component versions in VERSION.json.components are 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.md when maintaining framework assets, and the corresponding tools/cc/ or tools/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.md and CONTRIBUTING.md; for Python tool dependencies and focused tests, use the corresponding tools/cc/ or tools/tc/ project configuration. From the root, bash scripts/check-versions.sh checks version consistency. No application dev server applies.

Instruction Scope

  • Check applicable nested AGENTS.md / AGENTS.override.md before working in a subtree. Preserve scoped rules; references and Claude paths: frontmatter are not automatic Codex imports.
  • Keep shared project requirements consistent with CLAUDE.md when 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. $protocol and specialist names are shorthand, not shell commands or requests to spawn agents. Read only task-relevant skills/references.
  • Start with $protocol unless the specialist is obvious; use $launcher when 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 tc work products.

cc CLI

  • Use cc for memory, skills, Live Docs, and configuration; tc for tasks/work products. The retired Copilot MCP servers and their initiative_*, memory_*, and skill_* tools do not exist.
  • Prefer $HOME/.local/bin/cc; verify bare cc is not the C compiler. Source: Claude Copilot tools/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 docs is 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-separated CC_KNOWLEDGE_REPOS, nearest tier first, reading the first matching sub-path. Never use singular CC_KNOWLEDGE_REPO for 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, section Optional Context. Follow its load-once, receipt, and fallback rules; mandatory instructions are never relevance-filtered.

Task Management

  • Track substantial work in tc PRDs/tasks and store detailed work products there; create missing records. Use cc memory for durable decisions and lessons.
  • Prefer tc, then ./.venv-tc/bin/tc; use --json where supported. Read ~/.copilot/current/codex-copilot/plugins/codex-copilot/skills/task-copilot/SKILL.md when managing tasks.
  • Batch three or more related operations using tc.api, or separately cc.api, with a verified interpreter. Never mix these APIs in one process.
  • Formal initiatives belong in docs/40-initiatives/NN-slug/, indexed in docs/40-initiatives/README.md. Start with one maintained README.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; tc owns live state. Never create docs/initiatives/.

QA Gate Convention

  • For verification-required implementation, set metadata.requiresQa=true and register observable criteria and source scope with tc task contract <id> --file <path> (schemaVersion: 2) before implementing.
  • $me stores implementation evidence; $qa verifies it. Read their installed evidence contracts for those tasks.
  • Capture tc task evidence-identity <id> before and after checks, preserve the exact IDENTITY: line, and rerun affected checks if the tested content changes.
  • Store a task-bound test work product with matching CRITERION: / EXPECTED:, actual observations, inspectable ARTIFACT: evidence, untested scope, and one VERDICT:. Missing required behavior, bare markers, or stale evidence cannot support approval.
  • Before completion, run tc task check-qa <id> --json and scripts/copilot-gate.sh --task <id> (in this repo, or under ~/.copilot/current/claude-copilot/scripts/). Never remove requiresQa to 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 $uids before $uid. Architecture and non-trivial technical work use $ta; $me implements and $qa verifies.
  • 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.

  1. Confirm a mechanism exists in the relevant environment, plan, or account before naming it as the cause.
  2. State what every diagnostic exercised, including the selected key, config, binary, branch, interpreter, and working directory when relevant.
  3. Count failures through one shared dependency as one observation unless that dependency is varied.
  4. After two hypotheses are falsified, stop hypothesizing. Read the code that enforces the behavior and cite file:line.

Decision Instruments

  • Read SOUL.md before 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.md for 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.