/mycelium

name: mycelium
description: >
  Hidden layer of structured git notes for agent collaboration. When working in any
  git repo, check for notes on objects you touch before acting, and leave notes after
  meaningful work. Uses git notes directly — helper script and workflow scripts included.

Mycelium

Structured notes attached to git objects via `refs/notes/mycelium`.

**Before working on a file, check for its note. After meaningful work, leave a note.**

That’s the whole contract. Mycelium is the storage layer. Richer arrival / history workflows can live in skill scripts.

On arrival

Start every session with:

mycelium.sh find constraint                 # project principles & rules
mycelium.sh find warning                    # known fragile things
scripts/context-workflow.sh <file>          # recommended arrival workflow (repo checkout)

If you only have the runtime file and not this repo checkout, do the same workflow manually:

mycelium.sh read <file>                     # exact note on current object
mycelium.sh read HEAD                       # current commit note
# plus raw git notes show on parent dirs / root as needed

Before leaving:

mycelium.sh note HEAD -k context -m "What I did and why."
mycelium.sh note <changed-file> -k <kind> -m "What future agents should know."

If you made a decision, use `kind decision` and add a `tested-by` edge to the test that validates it. If you found something fragile, use `kind warning`.

Core commands

Use these as the protocol-ish primitives:

mycelium.sh note [target] -k <kind> -m <body>   # write
mycelium.sh read [target]                        # read exact note on current object
mycelium.sh follow [target]                      # read + resolve edges
mycelium.sh refs [target]                        # inbound references
mycelium.sh find <kind>                          # search by kind
mycelium.sh kinds                                # vocabulary in use
mycelium.sh list                                 # all annotated objects
mycelium.sh branch [use|merge] [name]            # branch-scoped notes
mycelium.sh doctor                               # graph facts
mycelium.sh dump                                 # everything, greppable

Workflow scripts in this repo

These are recommended workflows, not part of the core CLI:

scripts/context-workflow.sh <path> [ref]                    # current file + parent dirs + current commit
scripts/path-history.sh <path> [ref]                        # older file notes via git history
scripts/note-history.sh <target>                            # note overwrite history via notes ref
scripts/compost-workflow.sh [path|oid] [--compost|--renew]  # explicit stale/renew workflow

Use them when you want richer context, but keep in mind they are recipes built on top of git + mycelium primitives.

Rule of thumb:

• `context-workflow.sh` = default arrival workflow for a path
• `path-history.sh` = explicit historical notes for a file
• `note-history.sh` = overwrite history for one note target
• `compost-workflow.sh` = opt-in stale/renew lifecycle for repos that still want it

If a repo still wants an explicit stale/renew lifecycle, use `scripts/compost-workflow.sh`. The simpler default is to use git-native history first and write a fresh current note when older context still matters.

Patterns

Three patterns cover most usage.

Pattern 1: One ref accumulates many notes

A file can collect notes from different agents over time.

mycelium.sh note src/auth.ts -k summary -m "Handles OAuth2 refresh flow."
mycelium.sh note src/auth.ts -k warning -m "Token refresh has a race condition."
mycelium.sh refs src/auth.ts

When you need older notes on that file, use git history rather than a special core lifecycle command:

scripts/path-history.sh src/auth.ts

Pattern 2: One note connects many refs

A single note can link to multiple objects via edges.

mycelium.sh note SKILL.md -k decision -t "Packaged as an agent skill" \
  -e "depends-on blob:$(git rev-parse HEAD:README.md)" \
  -m "The skill teaches agents the convention on-demand."

mycelium.sh follow SKILL.md

Use this whenever a note’s meaning involves more than one object.

Pattern 3: Planning graph

Use `depends-on` edges to structure planned work.

mycelium.sh note src/auth.ts -k context -t "Planned: fix race condition" \
  -m "Need mutex around token refresh. See warning note."

mycelium.sh note src/http.ts -k context -t "Planned: retry after refresh" \
  -m "HTTP client should retry once after auth refresh."

mycelium.sh note HEAD -k context -t "Plan: auth hardening" \
  -e "depends-on blob:$(git rev-parse HEAD:src/auth.ts)" \
  -e "depends-on blob:$(git rev-parse HEAD:src/http.ts)" \
  -m "Two files need coordinated changes."

Check for notes

mycelium.sh read path/to/file.ts              # exact note on current object
mycelium.sh follow HEAD                       # note + where its edges lead
mycelium.sh refs path/to/file.ts              # all notes pointing at target
mycelium.sh find decision                     # all decisions
mycelium.sh find constraint                   # all constraints
git log --notes=mycelium --oneline -20        # recent commits with notes

Or with raw git:

git notes --ref=mycelium show $(git rev-parse HEAD:path/to/file.ts) 2>/dev/null
git notes --ref=mycelium show HEAD 2>/dev/null

Leave notes

mycelium.sh note -k context -m "Why I did this."                     # HEAD
mycelium.sh note path/to/file.ts -k summary -m "What this does."     # file
mycelium.sh note src/auth/ -k constraint -m "Must be retryable."     # directory
mycelium.sh note . -k value -m "Project-level principle."            # project
mycelium.sh note -k decision -t "Use YAML" -m "Needs comments."     # decision

Target stability

Every target has different stability.

| Target | Stable? | Use when |