agentleFS
nbdesai1992nbdesai1992/goalpost/CLAUDE.md

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…

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

    Before making a substantive change to this repository, there should be an active goal brief that covers it.

    line 13
  2. Distinctive:

    Not substantive (just do it): fixing a typo, tightening a README sentence, poking at something to debug it, running read-only commands, …

    line 19
  3. Distinctive:

    If you're unsure, the tell is whether a future reader would want to know *why* it happened.

    line 23
  4. Distinctive:

    Every brief lists the paths its deliverables will land at, before work starts.

    line 47
  5. Distinctive:

    If work reveals that the declared paths were wrong, change them in the brief and note it in the log.

    line 55
  6. Very specific:

    Update goals/INDEX.md on every status change.

    line 69
  7. Very specific:

    Before a brief leaves review, the tree should match the map.

    line 76

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

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

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

StatusDirectoryMeaning
scopedgoals/scoped/Brief written and agreed. Work has not started.
activegoals/active/Being worked right now.
reviewgoals/review/Deliverables exist. Awaiting human acceptance. Agent stops.
donegoals/done/Accepted. Outcome section filled in.
closedgoals/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

  1. Scope it. Draft the brief. The bar: a testable definition of done, declared deliverable paths, and explicit non-goals. Get agreement before starting.
  2. Activate it. Move to goals/active/.
  3. 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.
  4. Hand it back. Move to goals/review/ and stop. Say what to check.
  5. 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.

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.