gabriel / muse public
docs BREAKING task/doc-consolidation #1 / 1
gabriel · 168 days ago · Apr 13, 2026 · Diff

docs: consolidate agent-guide and AGENTS to eliminate duplication

agent-guide.md: 994 → 242 lines. Stripped full JSON field reference schemas, coord/worktree/workspace command listings, MSign internals, and living-docs rule (musehub-specific). Kept the unique high-ROI content: ecosystem map, no-git rule, sub-agent boilerplate, VCS command table, branch flow, deploy, auth setup, code intelligence reflexes, Gitism glossary.

AGENTS.md: 1990 → 256 lines. Removed Muse Flow (250+ lines duplicated from agent-guide), Code Domain Semantic Porcelain (1300+ lines duplicated from agent-guide), and full JSON field reference (300+ lines duplicated). Kept only muse-specific content: architecture map, layer rules, branch enforcement, code/typing/testing standards, verification checklist, scope of authority, anti-patterns, auth trust management, MuseHub interactions, quick reference.

sha256:31ca312bd2eb54f3c57b44a8feb921fa881e9f93c5eb5779fb79b8a9e80de884 sha
sha256:fad7beb1a07d5a8fe48e2d1475709d0736800fb55a674a910b56c1e8c5c57dce parent
+42 ~16 −256 symbols
sha256:99dd6df50a53c3ededc6a0c238f7fb2c2f98b66110d437d45b33ca0c9cd6ab93 snapshot
+42
symbols added
~16
symbols modified
−256
symbols removed
−2
dead symbols removed
Semantic Changes 314 symbols
~ AGENTS.md .md 15 symbols added, 157 symbols removed, 13 symbols modified
~ table@L1980
− Anti-Patterns (never do these) section Anti-Patterns (never do these) L535–553
− Layer rules (hard constraints) section Layer rules (hard constraints) L99–109
− code@L53 variable variable code@L53 L53–98
− Trust management section Trust management L581–615
− code[bash]@L587 variable variable code[bash]@L587 L587–600
− code[bash]@L604 variable variable code[bash]@L604 L604–612
− code[bash]@L568 variable variable code[bash]@L568 L568–572
− code[bash]@L575 variable variable code[bash]@L575 L575–578
− code[toml]@L557 variable variable code[toml]@L557 L557–565
− Branch Discipline — Absolute Rule section Branch Discipline — Absolute Rule L109–163
− Enforcement protocol section Enforcement protocol L150–163
− table@L152 section table@L152 L152–158
− The lifecycle section The lifecycle L113–150
− Code Domain Semantic Porcelain section Code Domain Semantic Porcelain L653–1226
− Read and navigate — find and inspect symbols section 1. Read and navigate — find and inspect symbols L693–735
− code[bash]@L695 variable variable code[bash]@L695 L695–732
− Query DSL — SQL for your codebase section 10. Query DSL — SQL for your codebase L966–998
− code[bash]@L971 variable variable code[bash]@L971 L971–995
− Test selection and execution — muse code test section 11. Test selection and execution — muse code test L998–1067
− code[bash]@L1005 variable variable code[bash]@L1005 L1005–1056
− Documentation — muse code docs section 12. Documentation — muse code docs L1067–1133
− code[bash]@L1074 variable variable code[bash]@L1074 L1074–1119
− Type Health — muse code type section 13. Type Health — muse code type L1133–1184
− code[bash]@L1137 variable variable code[bash]@L1137 L1137–1164
− table@L1167 section table@L1167 L1167–1174
− History — understand how symbols evolved section 2. History — understand how symbols evolved L735–780
− code[bash]@L737 variable variable code[bash]@L737 L737–777
− Impact and risk — before you change anything section 3. Impact and risk — before you change anything L780–815
− code[bash]@L782 variable variable code[bash]@L782 L782–812
− Coupling and hidden dependencies section 4. Coupling and hidden dependencies L815–838
− code[bash]@L817 variable variable code[bash]@L817 L817–835
− Code health — churn, stability, duplication, test gaps section 5. Code health — churn, stability, duplication, test gaps L838–881
− code[bash]@L840 variable variable code[bash]@L840 L840–878
− Architecture and topology section 6. Architecture and topology L881–913
− code[bash]@L883 variable variable code[bash]@L883 L883–910
− Quality gates — run before every merge section 7. Quality gates — run before every merge L913–928
− code[bash]@L915 variable variable code[bash]@L915 L915–925
− Surgical modification — agent-safe code changes section 8. Surgical modification — agent-safe code changes L928–956
− code[bash]@L930 variable variable code[bash]@L930 L930–953
− Staging (code domain) section 9. Staging (code domain) L956–966
− code[bash]@L958 variable variable code[bash]@L958 L958–963
− Agent decision guide — which command for which question? section Agent decision guide — which command for which question? L1184–1226
− table@L1186 section table@L1186 L1186–1223
− section Stop doing this. Do this instead. L667–693
− table@L669 section table@L669 L669–690
− JSON Field Reference — Agent-Exact Output Schemas section JSON Field Reference — Agent-Exact Output Schemas L1226–1978
− Global Gitism Glossary section Global Gitism Glossary L1953–1978
− table@L1957 section table@L1957 L1957–1975
− muse blame <file> --porcelain section muse blame <file> --porcelain L1483–1498
− code[json]@L1487 variable variable code[json]@L1487 L1487–1491
− muse branch --json section muse branch --json L1337–1363
− code[json]@L1341 variable variable code[json]@L1341 L1341–1352
− table@L1355 section table@L1355 L1355–1360
− muse code api-surface --json section muse code api-surface --json L1779–1806
− code[json]@L1781 variable variable code[json]@L1781 L1781–1801
− muse code breakage --json section muse code breakage --json L1720–1742
− code[json]@L1722 variable variable code[json]@L1722 L1722–1737
− muse code cat "<address>" --json section muse code cat "<address>" --json L1586–1610
− code[json]@L1588 variable variable code[json]@L1588 L1588–1607
− muse code clones --json section muse code clones --json L1845–1869
− code[json]@L1847 variable variable code[json]@L1847 L1847–1866
− muse code codemap --json section muse code codemap --json L1759–1779
− code[json]@L1761 variable variable code[json]@L1761 L1761–1776
− muse code compare <ref_a> <ref_b> --json section muse code compare <ref_a> <ref_b> --json L1695–1720
− code[json]@L1697 variable variable code[json]@L1697 L1697–1715
− muse code dead --json section muse code dead --json L1649–1677
− code[json]@L1651 variable variable code[json]@L1651 L1651–1672
− muse code deps "<file>" --json section muse code deps "<file>" --json L1632–1649
− code[json]@L1634 variable variable code[json]@L1634 L1634–1646
− muse code find-symbol --name "<name>" --json section muse code find-symbol --name "<name>" --json L1905–1929
− code[json]@L1907 variable variable code[json]@L1907 L1907–1926
− muse code gravity --explain "<address>" --json section muse code gravity --explain "<address>" --json L1677–1695
− code[json]@L1679 variable variable code[json]@L1679 L1679–1692
− muse code grep "<pattern>" --json section muse code grep "<pattern>" --json L1561–1586
− code[json]@L1563 variable variable code[json]@L1563 L1563–1583
− muse code hotspots --json section muse code hotspots --json L1742–1759
− code[json]@L1744 variable variable code[json]@L1744 L1744–1756
− muse code impact "<address>" --json section muse code impact "<address>" --json L1610–1632
− code[json]@L1612 variable variable code[json]@L1612 L1612–1627
− muse code languages --json section muse code languages --json L1869–1888
− code[json]@L1871 variable variable code[json]@L1871 L1871–1885
− muse code semantic-test-coverage --json section muse code semantic-test-coverage --json L1806–1845
− code[json]@L1808 variable variable code[json]@L1808 L1808–1842
− muse code symbol-log "<address>" --json section muse code symbol-log "<address>" --json L1929–1953
− code[json]@L1931 variable variable code[json]@L1931 L1931–1948
− muse code symbols --json section muse code symbols --json L1533–1561
− code[json]@L1535 variable variable code[json]@L1535 L1535–1556
− muse code test --dry-run --json section muse code test --dry-run --json L1888–1905
− code[json]@L1890 variable variable code[json]@L1890 L1890–1900
− muse diff --json section muse diff --json L1363–1385
− code[json]@L1365 variable variable code[json]@L1365 L1365–1379
− muse log --json section muse log --json L1268–1308
− code[json]@L1274 variable variable code[json]@L1274 L1274–1292
− table@L1298 section table@L1298 L1298–1305
− muse merge --dry-run <branch> --json section muse merge --dry-run <branch> --json L1462–1483
− code[json]@L1464 variable variable code[json]@L1464 L1464–1478
− muse reflog --json section muse reflog --json L1407–1429
− code[json]@L1409 variable variable code[json]@L1409 L1409–1426
− muse rev-parse <ref> --json section muse rev-parse <ref> --json L1385–1393
− code[json]@L1387 variable variable code[json]@L1387 L1387–1390
− muse show --json section muse show --json L1308–1337
− code[json]@L1312 variable variable code[json]@L1312 L1312–1334
− muse snapshot-diff <commit_a> <commit_b> --json section muse snapshot-diff <commit_a> <commit_b> --json L1498–1513
− code[json]@L1500 variable variable code[json]@L1500 L1500–1510
− muse stash --json / muse stash list --json section muse stash --json / muse stash list --json L1429–1462
− code[json]@L1433 variable variable code[json]@L1433 L1433–1444
− code[json]@L1447 variable variable code[json]@L1447 L1447–1459
− muse status --json section muse status --json L1233–1268
− code[json]@L1235 variable variable code[json]@L1235 L1235–1257
− table@L1260 section table@L1260 L1260–1265
− muse symbolic-ref HEAD --json section muse symbolic-ref HEAD --json L1393–1407
− code[json]@L1395 variable variable code[json]@L1395 L1395–1404
− muse workspace status --json section muse workspace status --json L1513–1533
− code[json]@L1517 variable variable code[json]@L1517 L1517–1530
− Muse Flow section Muse Flow L195–449
− Branch topology section Branch topology L210–235
− code@L212 variable variable code@L212 L212–224
− code@L227 variable variable code@L227 L227–234
− Enforcement checklist section Enforcement checklist L433–449
− table@L435 section table@L435 L435–446
− Ephemeral branches section Ephemeral branches L244–255
− table@L246 section table@L246 L246–254
− Hotfix cycle section Hotfix cycle L378–408
− code[bash]@L380 variable variable code[bash]@L380 L380–407
− Inspecting history and topology section Inspecting history and topology L408–417
− code[bash]@L410 variable variable code[bash]@L410 L410–416
− Permanent branches section Permanent branches L235–244
− table@L237 section table@L237 L237–241
− Phase 0 — Pre-flight (before you branch) section Phase 0 — Pre-flight (before you branch) L255–281
− code[bash]@L259 variable variable code[bash]@L259 L259–280
− Phase 1 — While working section Phase 1 — While working L281–293
− code[bash]@L283 variable variable code[bash]@L283 L283–292
− Phase 2 — Integration pre-flight (before opening a proposal) section Phase 2 — Integration pre-flight (before opening a proposal) L293–316
− code[bash]@L295 variable variable code[bash]@L295 L295–315
− Phase 3 — CI (runs automatically on every proposal push) section Phase 3 — CI (runs automatically on every proposal push) L316–328
− Phase 4 — Conflict resolution (when it does happen) section Phase 4 — Conflict resolution (when it does happen) L328–353
− code[bash]@L332 variable variable code[bash]@L332 L332–352
− Release cycle section Release cycle L353–378
− code[bash]@L355 variable variable code[bash]@L355 L355–377
− Swarm coordination principles section Swarm coordination principles L417–433
− Why Muse Flow is different section Why Muse Flow is different L199–210
− table@L632 section table@L632 L632–642
− table@L621 section table@L621 L621–626
− Releases and remote status section Releases and remote status L643–653
− table@L645 section table@L645 L645–650
− section No legacy. No deprecated. No exceptions. L39–51
− Ask the user first section Ask the user first L526–535
− Decide yourself section Decide yourself L519–526
− table@L483 section table@L483 L483–489
− Typing — Zero-Tolerance Rules section Typing — Zero-Tolerance Rules L460–481
− table@L466 section table@L466 L466–478
− Version Control — Muse Only section Version Control — Muse Only L163–195
− Starting work section Starting work L176–184
− code@L178 variable variable code@L178 L178–183
− The mental model section The mental model L167–176
− While working section While working L184–195
− code@L186 variable variable code@L186 L186–192
+ Anti-Patterns section Anti-Patterns L163–180
+ Layer rules section Layer rules L60–70
+ code@L32 variable variable code@L32 L32–59
+ Trust management (shared filesystems, Docker, CI) section Trust management (shared filesystems, Docker, CI) L199–210
+ code[bash]@L201 variable variable code[bash]@L201 L201–207
+ code[bash]@L193 variable variable code[bash]@L193 L193–198
+ code[toml]@L184 variable variable code[toml]@L184 L184–192
+ Branch Discipline section Branch Discipline L70–99
+ table@L224 section table@L224 L224–233
+ table@L214 section table@L214 L214–219
+ Releases section Releases L234–244
+ code[bash]@L236 variable variable code[bash]@L236 L236–241
+ table@L127 section table@L127 L127–133
+ Typing — Zero-Tolerance section Typing — Zero-Tolerance L109–125
+ table@L111 section table@L111 L111–122
~ Muse — Agent Contract
~ Agent Role
~ Architecture
~ Authentication
~ Code Standards
~ Mission
~ MuseHub Interactions
~ Issues
~ Proposals
~ Scope of Authority
~ Testing Standards
~ Verification Checklist
~ docs/agent-guide.md .md 27 symbols added, 99 symbols removed, 3 symbols modified
− Deploying to Staging and Production section Deploying to Staging and Production L359–388
− code[bash]@L366 variable variable code[bash]@L366 L366–379
− JSON Field Reference — Agent-Exact Output Schemas section JSON Field Reference — Agent-Exact Output Schemas L556–995
− Global Gitism Glossary section Global Gitism Glossary L975–995
− table@L979 section table@L979 L979–995
− muse branch --json section muse branch --json L655–679
− code[json]@L659 variable variable code[json]@L659 L659–670
− table@L671 section table@L671 L671–676
− muse code cat "<address>" --json section muse code cat "<address>" --json L868–892
− code[json]@L870 variable variable code[json]@L870 L870–889
− muse code compare <ref_a> <ref_b> --json section muse code compare <ref_a> <ref_b> --json L952–975
− code[json]@L954 variable variable code[json]@L954 L954–970
− muse code dead --json section muse code dead --json L926–952
− code[json]@L928 variable variable code[json]@L928 L928–949
− muse code deps "<file>" --json section muse code deps "<file>" --json L913–926
− code[json]@L915 variable variable code[json]@L915 L915–923
− muse code grep "<pattern>" --json section muse code grep "<pattern>" --json L843–868
− code[json]@L845 variable variable code[json]@L845 L845–865
− muse code impact "<address>" --json section muse code impact "<address>" --json L892–913
− code[json]@L894 variable variable code[json]@L894 L894–908
− muse code symbols --json section muse code symbols --json L815–843
− code[json]@L817 variable variable code[json]@L817 L817–838
− muse diff --json section muse diff --json L679–698
− code[json]@L681 variable variable code[json]@L681 L681–695
− muse log --json section muse log --json L594–632
− code[json]@L600 variable variable code[json]@L600 L600–618
− table@L622 section table@L622 L622–629
− muse merge --dry-run <branch> --json section muse merge --dry-run <branch> --json L761–782
− code[json]@L763 variable variable code[json]@L763 L763–777
− muse reflog --json section muse reflog --json L720–742
− code[json]@L722 variable variable code[json]@L722 L722–739
− muse rev-parse <ref> --json section muse rev-parse <ref> --json L698–706
− code[json]@L700 variable variable code[json]@L700 L700–703
− muse show --json section muse show --json L632–655
− code[json]@L636 variable variable code[json]@L636 L636–652
− muse stash list --json section muse stash list --json L742–761
− code[json]@L746 variable variable code[json]@L746 L746–758
− muse status --json section muse status --json L562–594
− code[json]@L564 variable variable code[json]@L564 L564–586
− table@L587 section table@L587 L587–591
− muse symbolic-ref HEAD --json section muse symbolic-ref HEAD --json L706–720
− code[json]@L708 variable variable code[json]@L708 L708–717
− muse workspace status --json section muse workspace status --json L782–815
− code[json]@L786 variable variable code[json]@L786 L786–802
− table@L803 section table@L803 L803–810
− Living Documentation — Type Contracts and Tests Must Stay Current section Living Documentation — Type Contracts and Tests Must Stay Current L520–543
− Muse Auth — MSign (Ed25519 per-request signing) section Muse Auth — MSign (Ed25519 per-request signing) L419–520
− Agent subprocess key injection section Agent subprocess key injection L507–520
− code[bash]@L511 variable variable code[bash]@L511 L511–515
− Decommission / rotate a key section Decommission / rotate a key L446–454
− code[bash]@L448 variable variable code[bash]@L448 L448–451
− How MSign works section How MSign works L454–471
− code@L458 variable variable code@L458 L458–461
− code@L463 variable variable code@L463 L463–466
− Identity store section Identity store L423–436
− code[toml]@L427 variable variable code[toml]@L427 L427–435
− Making raw API calls section Making raw API calls L471–503
− code[python]@L473 variable variable code[python]@L473 L473–502
− Setup (first time on a new hub) section Setup (first time on a new hub) L436–446
− code[bash]@L438 variable variable code[bash]@L438 L438–443
− When a push returns 404 ("Repository not found on remote") section When a push returns 404 ("Repository not found on remote") L503–507
− Muse Code Intelligence — Replace Your Reflexes section Muse Code Intelligence — Replace Your Reflexes L267–317
− Pre-task ritual section Pre-task ritual L293–317
− code[bash]@L295 variable variable code[bash]@L295 L295–314
− Three questions, three tools — do not confuse them section Three questions, three tools — do not confuse them L287–293
− table@L273 section table@L273 L273–286
− Muse Coord — Multi-Agent Coordination section Muse Coord — Multi-Agent Coordination L198–224
− code[bash]@L202 variable variable code[bash]@L202 L202–221
− Muse Core Workflow — Replace Your Git Reflexes section Muse Core Workflow — Replace Your Git Reflexes L63–198
− Commands section Commands L107–148
− table@L109 section table@L109 L109–147
− Cross-repo operations — always use -C section Cross-repo operations — always use -C L67–107
− code[bash]@L71 variable variable code[bash]@L71 L71–76
− code[bash]@L78 variable variable code[bash]@L78 L78–83
− code[bash]@L88 variable variable code[bash]@L88 L88–96
− code[bash]@L98 variable variable code[bash]@L98 L98–106
− MuseHub Connection section MuseHub Connection L188–198
− code[bash]@L190 variable variable code[bash]@L190 L190–195
− Tags and Releases section Tags and Releases L177–188
− code[bash]@L179 variable variable code[bash]@L179 L179–187
− muse content-grep — OR syntax and regex metacharacters section muse content-grep — OR syntax and regex metacharacters L148–177
− code[bash]@L152 variable variable code[bash]@L152 L152–156
− code[bash]@L161 variable variable code[bash]@L161 L161–174
− Muse Flow — Branch Topology section Muse Flow — Branch Topology L317–359
− The standard cycle section The standard cycle L332–359
− code[bash]@L334 variable variable code[bash]@L334 L334–356
− code@L319 variable variable code@L319 L319–329
− Muse Provenance — First-Class Agent Metadata class section Muse Provenance — First-Class Agent Metadata L388–419
− code[bash]@L392 variable variable code[bash]@L392 L392–399
− code[bash]@L409 variable variable code[bash]@L409 L409–416
− Muse Workspace — Multi-Repo Composition section Muse Workspace — Multi-Repo Composition L241–267
− code[bash]@L245 variable variable code[bash]@L245 L245–255
− code[bash]@L257 variable variable code[bash]@L257 L257–264
− Muse Worktree — Parallel Branch Work section Muse Worktree — Parallel Branch Work L224–241
− code[bash]@L228 variable variable code[bash]@L228 L228–236
− section Non-Negotiable: No git. No GitHub. Ever. L29–41
− code@L53 variable variable code@L53 L53–60
− The Ecosystem — Three Repos, One Platform section The Ecosystem — Three Repos, One Platform L13–29
− table@L17 section table@L17 L17–22
+ Auth — MSign (Ed25519) section Auth — MSign (Ed25519) L159–176
+ code[bash]@L163 variable variable code[bash]@L163 L163–169
+ Branch Flow section Branch Flow L102–144
+ Standard cycle section Standard cycle L117–144
+ code[bash]@L119 variable variable code[bash]@L119 L119–141
+ code@L104 variable variable code@L104 L104–114
+ Code Intelligence — Replace Your Reflexes section Code Intelligence — Replace Your Reflexes L185–220
+ Pre-task ritual section Pre-task ritual L209–220
+ code[bash]@L211 variable variable code[bash]@L211 L211–217
+ Three questions, three commands — do not confuse them section Three questions, three commands — do not confuse them L203–209
+ table@L189 section table@L189 L189–202
+ Deploy (MuseHub) section Deploy (MuseHub) L144–159
+ code[bash]@L148 variable variable code[bash]@L148 L148–154
+ Gitism Glossary section Gitism Glossary L220–243
+ table@L224 section table@L224 L224–243
+ Muse Commands section Muse Commands L42–102
+ -C — cross-repo targeting section -C — cross-repo targeting L46–65
+ code[bash]@L48 variable variable code[bash]@L48 L48–53
+ code[bash]@L56 variable variable code[bash]@L56 L56–64
+ Core commands section Core commands L65–89
+ table@L67 section table@L67 L67–88
+ muse content-grep — regex gotchas section muse content-grep — regex gotchas L89–102
+ code[bash]@L93 variable variable code[bash]@L93 L93–97
+ section No git. No GitHub. Ever. L19–28
+ code@L32 variable variable code@L32 L32–39
+ Three Repos, One Platform section Three Repos, One Platform L7–19
+ table@L9 section table@L9 L9–14
~ Muse Ecosystem — Agent Guide
~
~ Sub-Agents Must Use Muse Too
← Older Oldest on task/doc-consolidation
All commits
Newer → Latest on task/doc-consolidation

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:31ca312bd2eb54f3c57b44a8feb921fa881e9f93c5eb5779fb79b8a9e80de884 --body "your comment"