agentleFS
wald21x6-opswald21x6-ops/builder-kit/skills/project-memory/SKILL.md

project-memory

Skill1 starsChanged 23 days agoMITView on GitHub

Creates and keeps the .builder/ project files (BRIEF, CURRENT, DECISIONS, LOG, LAUNCH, SPEND) that let any new session continue a build without the user re-explaining anything, and writes hand-off prompts for a fresh session. Use it when starting any build, at every gate or milestone, before ending a long session, when context is getting full, when the user says "new session", "hand off", "save where we are", "continue this later", or when anything is deferred "until launch".

  • Reads credentials

27 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

12 rules. 0 are common, 10 are distinctive, and 2 are very specific to this project.

  • 0

    Common

    Most of the 22 edited versions we read keep these.

  • 10

    Distinctive

    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
  • could be automatic: a setting could enforce it
  1. Very specific:

    Create them from templates/ the first time (copy the folder, then fill in BRIEF.md from stage 1).

    line 15
  2. Distinctive:

    Who decided what is sacred: Only *client* and *user* decisions can be locked.

    line 32
  3. Distinctive:

    Record observations, not guesses: If something broke and the cause isn't proven, write "cause unknown".

    line 36
  4. Distinctive:

    Check paths before writing a hand-off: Every file a hand-off mentions must exist.

    line 38
  5. Very specific:

    Commit before risky work: if the project uses git (git add -A && git commit -m "checkpoint: <gate>").

    line 39
  6. Distinctive:

    When context is getting full, the work changes phase, or the user asks for a new session:

    line 43
  7. Distinctive:

    Update CURRENT.md (especially Next step) and LOG.md.

    line 44
  8. Distinctive:

    When the hand-off is for another AI tool (Codex, Cursor), add: "Work only in <folder or branch>.

    line 52
  9. Distinctive:

    Before finishing, list every file you changed."

    line 53
  10. Distinctive:

    If two sessions (or another AI tool, like Codex or Cursor) edit the same folder, they overwrite each other's work.

    line 56
  11. Distinctive:

    Check git status for changes this session didn't make.

    line 58
  12. Distinctive:

    Never deploy files this session didn't change without saying so.

    line 61

“Common” is measured: kept by at least 6 in 10 of the 22 edited versions of this file we could read. “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
SKILL.md

Project memory

In the builds this kit was made from, users re-explained things Claude should already have known 4–17 times per project. Once a project kept these files and Claude wrote its own hand-off prompts, that dropped to zero in every build that used them. This skill is that system.

The files (.builder/ in the project root)

Create them from templates/ the first time (copy the folder, then fill in BRIEF.md from stage 1). At the same time, keep them private: add .builder/ and .env* to .gitignore, and to .vercelignore if the project deploys to Vercel. BRIEF.md can hold a client's phone number and budget, so it must never be published. The publish check reminds you if it's missing.

FileWhat goes in itUpdate when
BRIEF.mdThe approved Task Card: goal sentence, audience, priority order, first real use, domain/accounts, capsStage 3 approval; any scope change the user approves
CURRENT.mdWhat's true right now: live URLs, what works, what's in progress, Next step, who owns which folderEvery gate, every deploy, end of session
DECISIONS.mdOne row per decision: what · who decided (client / user / Claude-proposed) · date · locked?Whenever something is decided
LOG.mdDated, newest first: what was done, what was learned, what broke and the real cause (or "cause unknown")Every gate
LAUNCH.mdEvery "later", "before launch", "when we go live" item, as checkboxes, each marked blocker or notThe moment anything is deferred
SPEND.mdPaid services: balance · cap · spent so farBefore and after any paid call (the spend guard checks this file)
RESEARCH.mdResearch findings (written by the research skill)Stage 2

The session-start hook reads CURRENT.md and the open LAUNCH.md items into every new session automatically.

Rules that matter

  • Who decided what is sacred. Only client and user decisions can be locked. A Claude-proposed decision is a default that can be revisited. In the data, Claude's own design opinions got written down as "settled", and a passing remark became "the client asked for no menu bar". Write who actually said it, with a date or quote.
  • Inferred goals are labelled inferred, not confirmed until the user confirms them.
  • Record observations, not guesses. If something broke and the cause isn't proven, write "cause unknown". A wrong cause in memory misleads every later session.
  • Check paths before writing a hand-off. Every file a hand-off mentions must exist. One hand-off named a file that didn't.
  • Commit before risky work if the project uses git (git add -A && git commit -m "checkpoint: <gate>"). This gives the user an undo point. Never commit .env files or secrets. Check .gitignore first.

Hand-off to a new session

When context is getting full, the work changes phase, or the user asks for a new session:

  1. Update CURRENT.md (especially Next step) and LOG.md.
  2. Give the user this block to paste into the new session:
Continue the <project> build. Read .builder/CURRENT.md, then .builder/BRIEF.md and the open items in
.builder/LAUNCH.md. Next step: <one line>. Don't re-ask anything those files answer.

Tell the user exactly how to start it: "Open a new Claude Code session in this folder and paste the block above."

When the hand-off is for another AI tool (Codex, Cursor), add: "Work only in <folder or branch>. Don't touch <list>. Before finishing, list every file you changed."

Several sessions or tools in one project

If two sessions (or another AI tool, like Codex or Cursor) edit the same folder, they overwrite each other's work. This happened in 7 of 14 builds. Before starting:

  • Check git status for changes this session didn't make. If there are any, ask whose they are before touching them.
  • Give each session its own git worktree (git worktree add ../<project>-<task> -b <task>), or record in CURRENT.md which folder each session owns.
  • Never deploy files this session didn't change without saying so. The publish guard warns about this.

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.