Workspace — Shared Agent Configuration

This file contains shared rules for all repositories in this workspace. Each member repository may have its own .muse/agent.md with repo-specific additions.

Managed by muse agent-config — regenerate adapters with muse agent-config sync.

Workspace Members

Version Control

This workspace uses Muse for version control — not git, not GitHub.

• Never run git, gh, or any git subcommand.
• Never reference GitHub, GitHub Actions, or GitHub URLs.
• Use muse -C ~/path/to/repo <command> when CWD differs from the target repo.

If you find a git or gh call anywhere — delete it in the same commit.

Commit Convention — Agent-First

This workspace is agent-first: agents do the work, humans provision agents. Every commit made by an agent must carry full provenance. Human commits (direct manual changes without an agent) are the exception, not the norm.

Agent commit — always use this

muse commit -m "feat: ..." \
  --agent-id claude-code \
  --model-id claude-sonnet-4-6 \
  --sign

• --agent-id — identifies the agent type (claude-code, codex, agentception/worker, …)
• --model-id — the specific model that produced the change (claude-sonnet-4-6, …)
• --sign — embeds Ed25519 public key + signature; traces back to gabriel's root mnemonic in ~/.muse/identity.toml

Use the model you are actually running. For Claude Code the current model is claude-sonnet-4-6.

Human commit — manual actions only

muse commit -m "chore: manual config change"

No provenance flags. Their absence is itself a signal that a human acted directly.

Provenance chain

~/.muse/identity.toml     ← root mnemonic (HD wallet seed, gabriel's root identity)
        ↓  HD derivation
   Ed25519 key pair        ← signer_public_key embedded in every --sign commit
        ↓  signs
   CommitRecord            ← agent_id + model_id + signature stored per-commit
        ↓  content-addressed
   sha256:<commit_id>      ← tamper-evident, auditable forever

Agents spawned by agentception receive a derived key via MUSE_AGENT_KEY env var — their commits sign with that key, which itself traces back to gabriel's root identity.

Branch Flow

Always work on a feature branch — never commit directly to main or dev.

muse -C ~/path/to/repo checkout dev
muse -C ~/path/to/repo checkout -b task/my-thing

muse rm <file>     # delete from disk + stage deletion (mirrors git rm)
muse code add .    # stage additions + modifications + already-deleted files
muse commit -m "feat: ..." --agent-id claude-code --model-id claude-sonnet-4-6 --sign

muse -C ~/path/to/repo checkout dev
muse -C ~/path/to/repo merge task/my-thing
muse -C ~/path/to/repo branch -d task/my-thing
muse -C ~/path/to/repo push local dev

Code Intelligence

Testing Rules

Never run the full test suite. It is slow and gabriel runs it when he's ready.

1. Start with muse code test --json — runs only tests relevant to changed files.
2. Run one file at a time when fixing a specific failure:

   python3 -m pytest tests/test_foo.py -q --tb=short
   

3. Run one test by name to verify a fix:

   python3 -m pytest tests/test_foo.py::test_bar -q --tb=short
   

Forbidden

• python3 -m pytest tests/ — runs everything, never do this
• python3 -m pytest with no path — same as above
• pytest -x tests/ or any whole-suite invocation
• Looping retries on the same command after a failure — diagnose first

muse — Agent Configuration

This repository is a member of a workspace. Shared workspace rules live in the parent .muse/agent.md. This file contains only muse-specific additions.

Managed by muse agent-config — regenerate adapters with muse agent-config sync.

Repo-Specific Notes

Snapshot Design Intent — Flat Manifest is Intentional

Muse snapshots are flat path → object_id dicts covering the entire repo in one structure. This is a deliberate architectural choice, not an oversight.

Why not git's recursive tree model?

Git's tree objects provide subtree sharing: two commits that differ only in src/ reuse the same tree object for every other directory. This saves storage at the cost of requiring recursive tree traversal to reconstruct a file's path.

Muse does not use this model because the primary unit of meaning in Muse is not a directory — it is a snapshot of the entire system state. A music arrangement, its samples, its metadata, and its MIDI files are one coherent atomic thing. A genomics dataset, a 3D scene, a financial model — all of these are captured as a single indivisible state, not a hierarchy of independently meaningful subtrees.

The flat manifest reflects that: state is atomic, not hierarchical.

Storage tradeoff

Each snapshot materializes the full path list on disk. For small-to-medium repos (up to ~100k files) this is not a meaningful constraint — snapshot files are just path strings and SHA-256 IDs, not blob bytes. On the wire, delta encoding (delta_upsert/delta_remove) means only changes are transmitted regardless.

If very large file counts become a real constraint, the natural evolution is a tiered manifest: flat below a threshold, chunked or tree-structured above it. The content-addressing model and delta format would not change.

Domain agnosticism

At the storage layer, a MIDI file and a Python file are identical — both are just bytes with a path. Domain semantics live in the content of those bytes, not in how they are stored. Muse is multi-domain (code, music, genomics, 3D, financial modeling) but the object store, snapshot, and commit model are the same for all of them. Do not introduce domain-specific logic into the core storage layer.