brain-upstream
Skill2 starsChanged 12 days agoMITView on GitHub
Record a proposed change to a file the template owns (a brain-* skill, _meta/, a managed block) as an upstream suggestion in docs/UPSTREAM.md, written without this brain's private details, and restore any local edit to that file. Use when a brain-* skill or the harness falls short, when update or doctor reports a local edit to a template-owned file, or to see which suggestions have been answered. Does NOT edit template-owned files or write into the template, where template-intake takes suggestions in, and does NOT fix the brain's own skills, which is brain-write-skill.
- Reads credentials
In this repository10 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- brain-retroSkill
- brain-setupSkill
- brain-syncSkill
- brain-write-modSkill
- brain-write-practiceSkill
- brain-write-scriptSkill
- brain-write-skillSkill
- template-intakeSkill
- template-make-brainSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 64
Write it for any brain: No hostnames, addresses, project or repo names, people, or paths from this machine: write "a nested repo", <host>, …
- Very specific: line 82
If the person needs the edit for now, leave it, and say update stays blocked meanwhile.
- Very specific: line 98
Write into the template, even when template.source is a folder on this machine.
- Very specific: line 101
Check out all of CLAUDE.md, .gitignore or .claude/settings.json to restore a managed part.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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
brain-upstream
A brain never edits a file the template owns, and the template never writes into a brain. A change
one of those files needs travels as a suggestion instead: written here in docs/UPSTREAM.md, read
by template-intake in the template, answered in the template's CHANGELOG.md, and brought back by
the next update.
Where this sits
<!-- where:begin — generated by _meta/brain routing sync; do not edit -->Runs after: brain-retro
Hand to next: brain-sync
Reserved output: writing docs/UPSTREAM.md needs this skill to have run.
<!-- where:end -->Call it directly when: a brain-* skill or _meta/ fell short, or update or doctor named a
local edit to a template-owned file; when it came from a failure, brain-retro should log it first.
When
- A
brain-*skill or the harness fell short on real work, usually handed on bybrain-retro. brain-write-skillorbrain-write-scriptfound that the change belongs in the template.updaterefused because of a local edit, ordoctorwarns that template-owned files differ from_meta/MANIFEST.sha256(an edited, a missing, or an extra file).- The person asks which suggestions have been answered.
Template-owned means _meta/**, .claude/skills/brain-*/**, the managed blocks between the
brain:begin and brain:end markers in CLAUDE.md and .gitignore, and the gate hooks and .env
deny entries in .claude/settings.json; the rest of those three files is the brain's own, like
everything else. A skill of the brain's own is fixed through brain-write-skill.
Record a suggestion
- Look for one already open on the same file and problem:
_meta/brain upstream list. Add to an open entry rather than writing a second; two entries for one problem get two answers. - Find what is installed. The version is
brain.jsontemplate.version. For a local edit,git diff -- <file>shows it. When the edit is already committed, diff against the commit that installed the file: the latestmeta(brain)initialise, adopt or update commit ingit log --oneline -- <file>. Write the entry at the end of
docs/UPSTREAM.md, in exactly this shape, because the harness parses it (upstream list,update) andtemplate-intakereads it:## <YYYY-MM-DD-slug> - template: <version> - files: <paths> - status: open|landed <version>|declined: <reason> ### What happened <what fell short, on what kind of work, and what it cost> ### Proposed change <the change in prose, or a diff against the installed file>The id is today's date and a short kebab-case slug, unique in the file. A new entry's status is
open; the other two values are written later, bybrain-sync.fileslists every path, comma-separated, relative to the brain root.- Write it for any brain. No hostnames, addresses, project or repo names, people, or paths from
this machine: write "a nested repo",
<host>,/home/me/...instead. The answer lands in a public template, andtemplate-intakecarries the reasoning into it. The pre-commit guard checks the entry againstprivacy.deny_patternsand.brain-privatelike any other file, but it only knows the patterns someone wrote down, so reread the entry yourself before saving it. - Show the person the entry.
Restore the local edit, if there is one, only after the entry is written and only on a yes. The entry comes first because until then the edit is the only copy of the proposal; restore at all because
updaterefuses while template-owned files differ from what was installed.- An edited or missing file under
_meta/or abrain-*skill:git checkout -- <file>, or from the installing commit,git checkout <installing commit> -- <file>. - An extra file there that the template never shipped (a hand-made
brain-*skill folder, say): remove it, withgit rm -rwhen it is tracked. Checking it out would do nothing. - A managed block, or the gate and
.enventries in.claude/settings.json: never check out the whole file, which would throw away the brain's own part. Put the block back between its markers from_meta/managed/CLAUDE.block.mdor_meta/managed/gitignore.block, or run the update (brain-setup), which rewrites the blocks and the settings entries.
If the person needs the edit for now, leave it, and say
updatestays blocked meanwhile. After a restore,_meta/brain doctor --quickshows no manifest edit.- An edited or missing file under
- Hand to
brain-syncto commit: the entry asdocs(upstream), a restore alone asmeta(brain): restore <file>.
See the answers
_meta/brain upstream list prints each suggestion's id and status, plus the template's answer when
its CHANGELOG.md has one. Answers arrive with update, and brain-sync flips each answered entry
to landed <version> or declined: <reason> in the commit that brings that update in. Do not flip
them here: the flip records that this brain has taken the answer in, which is that commit.
Never
- Edit a template-owned file to fix it here, even "just for now": the suggestion is the change, and the next update overwrites the edit.
- Write into the template, even when
template.sourceis a folder on this machine. The template reads this file; nothing here writes there. - Restore a file before its entry is written, or without a yes.
- Check out all of
CLAUDE.md,.gitignoreor.claude/settings.jsonto restore a managed part.
Done when
docs/UPSTREAM.mdhas one entry for this change in the shape above,status: open, naming the installed version and every file.- The entry names no host, address, project, person or local path, and the person has seen it.
- Any local edit is restored on a yes and
doctor --quickshows no manifest edit, or the person chose to keep it and knowsupdatestays blocked meanwhile. - The entry is handed to
brain-syncto commit.
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.

