goalpost
CLAUDE.md0 starsChanged 4 months agoMITView on GitHub
Work in this repository is tracked as goal briefs. Anything of consequence starts as a brief and ends as a record of what actually happened. The brief folder is the project's memory: it answers "what have we done here, and why." This system is deliberately small — a folder of markdown files, one slash command, and two advisory hooks. There is no queue, no runner, no orchestrator. If it ever grows one, that was a mistake. Before making a substantive…
In this repositoryOne other file it gives its agents.
- file-organizationSkill
The file
We split this CLAUDE.md into the rules it gives an agent
7 rules. About 0 are common, 5 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
Before making a substantive change to this repository, there should be an active goal brief that covers it.
- Distinctive: line 19
Not substantive (just do it): fixing a typo, tightening a README sentence, poking at something to debug it, running read-only commands, …
- Distinctive: line 23
If you're unsure, the tell is whether a future reader would want to know *why* it happened.
- Distinctive: line 47
Every brief lists the paths its deliverables will land at, before work starts.
- Distinctive: line 55
If work reveals that the declared paths were wrong, change them in the brief and note it in the log.
- Very specific: line 69
Update goals/INDEX.md on every status change.
- Very specific: line 76
Before a brief leaves review, the tree should match the map.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.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
Operating contract
Work in this repository is tracked as goal briefs. Anything of consequence starts as a brief and ends as a record of what actually happened. The brief folder is the project's memory: it answers "what have we done here, and why."
This system is deliberately small — a folder of markdown files, one slash command, and two advisory hooks. There is no queue, no runner, no orchestrator. If it ever grows one, that was a mistake.
The rule
Before making a substantive change to this repository, there should be an active goal brief that covers it.
Substantive means: creating or reorganizing deliverables, writing code that ships, producing research output, changing how the project works.
Not substantive (just do it): fixing a typo, tightening a README sentence, poking at something to debug it, running read-only commands, throwaway exploration you're going to delete.
If you're unsure, the tell is whether a future reader would want to know why it happened. If yes, it wants a brief.
Statuses
| Status | Directory | Meaning |
scoped | goals/scoped/ | Brief written and agreed. Work has not started. |
active | goals/active/ | Being worked right now. |
review | goals/review/ | Deliverables exist. Awaiting human acceptance. Agent stops. |
done | goals/done/ | Accepted. Outcome section filled in. |
closed | goals/closed/ | Ended without shipping. closed_reason says why. |
closed is neutral on purpose. A goal can end because it became obsolete, was
superseded by a better approach, got descoped, or is blocked indefinitely. The
directory records that it ended; the closed_reason field records which. Closed briefs
are kept, never deleted — a goal you decided not to pursue, and the reasoning behind it,
is often worth more later than one you completed.
review exists because some work needs a human to look at it before it counts as done.
An agent moves a brief to review and stops there. Only a human moves it to done.
Deliverables are declared up front
Every brief lists the paths its deliverables will land at, before work starts. This is the load-bearing part of the system.
It forces the scoping to be real — you cannot name paths for a goal you haven't thought
through. It makes completion checkable rather than a matter of opinion: did the declared
files appear, and does the tree still match ORGANIZATION.md? And it gives the hooks
something concrete to compare against.
If work reveals that the declared paths were wrong, change them in the brief and note it in the log. Drifting silently is the failure mode.
Working a goal
- Scope it. Draft the brief. The bar: a testable definition of done, declared deliverable paths, and explicit non-goals. Get agreement before starting.
- Activate it. Move to
goals/active/. - Work it. Append dated entries to the brief's log as you go — decisions made, surprises hit, paths changed. Write them when they happen, not reconstructed at the end.
- Hand it back. Move to
goals/review/and stop. Say what to check. - Close it out. Once accepted, fill in the Outcome section and move to
goals/done/. An Outcome section is not optional — a completed brief without one is just a stale plan.
Update goals/INDEX.md on every status change.
Keeping the repo organized
ORGANIZATION.md declares where things go and why. It is the current-state map; the brief
archive is the history. Both matter, for different questions.
Before a brief leaves review, the tree should match the map. Run the
file-organization skill to check. If the work genuinely needs a new category, amend
ORGANIZATION.md as part of the goal rather than quietly inventing a folder.
Two kinds of memory
Briefs are episodic — what happened, when, why. ORGANIZATION.md and decisions/ are
semantic — what is true now. When a goal produces a durable decision that outlives it,
promote that decision out of the brief into decisions/ so the next person doesn't have
to read forty briefs to learn how things work here.
Writing briefs
The agent drafts, the human approves. Nobody should be hand-writing these; that friction is what kills systems like this.
Match the brief to the goal. A small goal gets a short brief — goal, done-criteria, paths, maybe four lines total. Save the full template for work that warrants it. A brief that takes twenty minutes to write is a planning failure, not thoroughness.
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.

