gabriel / muse public
docs agent-guide docs/185-muse-vs-muse-dev-idiom #1 / 1
AI Agent gabriel · 1 day ago · Sep 10, 2026 · Diff

docs(agent-guide): document when to use muse vs muse-dev (#185)

Gabriel noticed I kept using plain `muse` for ordinary VCS operations even while Phases 1-3 stood up the muse/muse-dev split, and asked for it to be documented so future agents don't have to infer the rule from behavior.

Adds a dedicated section: `muse` (stable, installer venv) is the default for everything, including work inside ~/ecosystem/muse itself — ordinary content work (docs, tests, features, commit/merge/push) is not "developing muse's CLI," it's just using a VCS tool. `muse-dev` (editable, live source) is only for exercising a CLI/engine code change you just made to muse itself. Also documents the Phase 3 guard rail's existence and rationale so agents that hit it understand why, rather than reflexively setting MUSE_DEV_ALLOW_CANONICAL=1 to make an error go away.

Also added a condensed version of the same rule to the sub-agent boilerplate block, since sub-agents only ever see that snippet, not the full doc.

sha256:055a23adbc9f95a2b8db00703e661d8dcce5be185c5eff1282f84e47e9adb59d sha
sha256:c4f1efcedc75c6d1eda18b7f73bbe06081120c20afd3aa3eb688a63cc22389c7 parent
+1 ~2 symbols
1 changed · 1164 in snapshot files
sha256:da65632600e14f065e4b3305e4288b68546be9b44b90bb94428d4940cda14d57 snapshot
+1
symbol added
~2
symbols modified
1
file changed
1164
files in snapshot
0
dead code introduced
Semantic Changes 3 symbols
~ docs/agent-guide.md .md 1 symbol added, 2 symbols modified
+ muse vs muse-dev — which one to use section muse vs muse-dev — which one to use L28–63
~ Muse Ecosystem — Agent Guide
~ Sub-Agents Must Use Muse Too
Files Changed
~1
1164 in snapshot
~ docs/agent-guide.md .md
← Older Oldest on docs/185-muse-vs-muse-dev-idiom
All commits
Newer → Latest on docs/185-muse-vs-muse-dev-idiom

0 comments

No comments yet. Be the first to start the discussion.

To add a comment, use the Muse CLI: muse hub commit comment sha256:055a23adbc9f95a2b8db00703e661d8dcce5be185c5eff1282f84e47e9adb59d --body "your comment"