agentleFS
derrickmehaffyderrickmehaffy/brain-template/.claude/skills/brain-upstream/SKILL.md

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

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
  1. Very specific:

    Write it for any brain: No hostnames, addresses, project or repo names, people, or paths from this machine: write "a nested repo", <host>, …

    line 64
  2. Very specific:

    If the person needs the edit for now, leave it, and say update stays blocked meanwhile.

    line 82
  3. Very specific:

    Write into the template, even when template.source is a folder on this machine.

    line 98
  4. Very specific:

    Check out all of CLAUDE.md, .gitignore or .claude/settings.json to restore a managed part.

    line 101

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

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

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 by brain-retro.
  • brain-write-skill or brain-write-script found that the change belongs in the template.
  • update refused because of a local edit, or doctor warns 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

  1. 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.
  2. Find what is installed. The version is brain.json template.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 latest meta(brain) initialise, adopt or update commit in git log --oneline -- <file>.
  3. Write the entry at the end of docs/UPSTREAM.md, in exactly this shape, because the harness parses it (upstream list, update) and template-intake reads 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, by brain-sync. files lists every path, comma-separated, relative to the brain root.

  4. 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, and template-intake carries the reasoning into it. The pre-commit guard checks the entry against privacy.deny_patterns and .brain-private like any other file, but it only knows the patterns someone wrote down, so reread the entry yourself before saving it.
  5. Show the person the entry.
  6. 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 update refuses while template-owned files differ from what was installed.

    • An edited or missing file under _meta/ or a brain-* 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, with git rm -r when it is tracked. Checking it out would do nothing.
    • A managed block, or the gate and .env entries 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.md or _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 update stays blocked meanwhile. After a restore, _meta/brain doctor --quick shows no manifest edit.

  7. Hand to brain-sync to commit: the entry as docs(upstream), a restore alone as meta(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.source is 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, .gitignore or .claude/settings.json to restore a managed part.

Done when

  • docs/UPSTREAM.md has 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 --quick shows no manifest edit, or the person chose to keep it and knows update stays blocked meanwhile.
  • The entry is handed to brain-sync to commit.

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.