copilot-tools
AGENTS.md1 starsChanged 4 months agoMITView on GitHub
Enabled features: session-handoff, session-history, spec-driven, parallel-agents, operator-agents, branching-strategy, tracked-backlog. Generated by copilot-tools 1.4.0 for C:\Users\darin\repos\copilot-tools. Everything between the markers is regenerated by operator projects; write anything of your own outside them. All work happens in a worktree. Never edit the primary checkout. Use operator worktree new|finish. - Leave worktrees you did not create alone. Nothing outside tells an idle tree from an occupied one. By hand: the worktrees skill. Probes, reproductions, scratch copies and fixtures go in a temp directory,…
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 31,700 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 repository23 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- templates/copilot-instructions.mdCopilot instructions
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
- backlogSkill
- code-intelligenceSkill
- field-notesSkill
- operator-backlog-newitemSkill
- operator-backlog-refinementSkill
- operator-backlog-scrumSkill
- peer-agentsSkill
- request-auditSkill
- spec-drivenSkill
- worktreesSkill
The file
We split this AGENTS.md into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 27
Tell your subagents the same thing, by name: No tool can check a prompt you wrote.
- Distinctive: line 115
Volunteer them — don't wait to be asked: No skill can be loaded on noticing something transferable.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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
<!-- BEGIN operator:managed -->copilot-tools — working conventions
Enabled features: session-handoff, session-history, spec-driven, parallel-agents, operator-agents, branching-strategy, tracked-backlog.
Generated by copilot-tools 1.4.0 for C:\Users\darin\repos\copilot-tools.
Everything between the markers is regenerated by operator projects;
write anything of your own outside them.
Git Worktrees — Always
All work happens in a worktree. Never edit the primary checkout. Use operator worktree
new|finish.
- Leave worktrees you did not create alone. Nothing outside tells an idle tree from an occupied one.
By hand: the worktrees skill.
Scratch Files — Never in the Checkout
Probes, reproductions, scratch copies and fixtures go in a temp directory, never in a checkout.
- Tell your subagents the same thing, by name. No tool can check a prompt you wrote.
- An explanation that fits the evidence is not the explanation. Reproduce the mechanism before explaining the artifact.
Why: docs/rationale.md.
Handing a Worktree to a Subagent
Commit before you delegate. Staging is not enough. Point reviewers at git diff main...HEAD.
- Forbid the mutating git verbs by name —
stash,checkout,reset,clean,restore,rebase. Git plumbing writes no new files. - Verify the worktree before you read the findings. A reviewer once destroyed 454 lines and mentioned it in passing.
Project Configuration System
Do not offer to enroll this directory or write to the project catalog. This project is already registered.
- Project id:
c48add2d-aedc-45e5-a562-946da32753ff - Project directory:
C:\Users\darin\.operator\projects\c48add2d-aedc-45e5-a562-946da32753ff - Feature settings:
C:\Users\darin\.operator\projects\c48add2d-aedc-45e5-a562-946da32753ff\features.json
Handoff and other state live there. Change features:
operator projectsSession Handoff Protocol
Enabled by feature flag: session-handoff
operator session start --instance NAME, and to close:
operator session end --instance NAME --status TEXT --next TEXT, plus --done to release
the work item.
- Write it proactively. Noticing that context has got heavy is a judgement no tool can make.
- Never write the handoff file by hand — it destroys an unread one and raises no restart marker.
Session History
Enabled by feature flag: session-history
Recorded by operator session start|end. No schema to paste, no table to create.
- A session left open is recorded as abandoned, not lost. Say what happened rather than reopening it quietly.
Parallel Agents
Enabled by feature flag: parallel-agents
Claim before you edit: operator work request|release|list.
- A refused claim is an answer. Take other ready work; never wait, never take a claim a peer holds.
Tracked Backlog
Enabled by feature flag: tracked-backlog
Open work belongs in the repository, not in a handoff. operator backlog ready|close; format in
the backlog skill.
- Evidence is what was measured — a command and its output, a mutation that ran green. Without it, a rumour.
- Never seed an item you have not verified yourself.
- A guard that cannot fire reads exactly like coverage. Violate each check once and watch it go red.
Field Notes (Agent Journal)
A cross-project journal on working with AI, in its own repository. See the field-notes skill.
- Volunteer them — don't wait to be asked. No skill can be loaded on noticing something transferable.
- Don't edit an old entry to make it right. Being wrong is data.
Specification-Driven Development
Enabled by feature flag: spec-driven
Specs are the source of truth, under .specify/ and specs/.
- Write factual specs, not aspirational ones, naming real code in every claim. Should reads exactly like does.
Operator — Peer Agents
Enabled by feature flag: operator-agents
operator starts a peer, not a sub-agent: its own process and git work, still running after you
stop watching.
- A boundary is enforceable once declared.
operator ownership checkrefuses a branch that left its subproject; undeclared, only your instruction enforces it. - Answer what you are asked before you end your session. A peer blocked on your reply is burning sessions doing nothing.
See the peer-agents skill.
Branching Strategy
Enabled by feature flag: branching-strategy
mainis the integration branch; never commit to it directly. There is nodevelopbranch — don't create one, don't assume one.feat/,fix/,docs/offmain, worked in a worktree. Conventional commits.
<!-- END operator:managed -->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.