workspace.md
markdown
| 1 | # `muse workspace` — multi-repository workspaces |
| 2 | |
| 3 | A *workspace* links multiple independent Muse repositories together under a single manifest, giving you a unified status view, one-shot synchronisation, and a clear model for multi-repo projects. |
| 4 | |
| 5 | ## When to use workspaces vs. worktrees |
| 6 | |
| 7 | | Need | Use | |
| 8 | |------|-----| |
| 9 | | Multiple branches of **one** repo simultaneously | `muse worktree` | |
| 10 | | Multiple **separate** repos that evolve together | `muse workspace` | |
| 11 | |
| 12 | ## Use cases |
| 13 | |
| 14 | - **A film score** with a melody repo, a harmony repo, and a samples repo |
| 15 | - **A machine learning pipeline** with a model repo, a dataset repo, and an eval repo |
| 16 | - **A micro-service backend** where each service lives in its own Muse repo |
| 17 | - **An agent swarm** where each autonomous agent manages its own state repo, and the coordinator workspace tracks them all |
| 18 | |
| 19 | ## Workspace manifest |
| 20 | |
| 21 | The manifest lives at `.muse/workspace.toml`: |
| 22 | |
| 23 | ```toml |
| 24 | [[members]] |
| 25 | name = "core" |
| 26 | url = "https://musehub.ai/acme/core" |
| 27 | path = "repos/core" |
| 28 | branch = "main" |
| 29 | |
| 30 | [[members]] |
| 31 | name = "sounds" |
| 32 | url = "https://musehub.ai/acme/sounds" |
| 33 | path = "repos/sounds" |
| 34 | branch = "v2" |
| 35 | ``` |
| 36 | |
| 37 | ## Subcommands |
| 38 | |
| 39 | ### `muse workspace add <name> <url>` |
| 40 | |
| 41 | Register a member repository. |
| 42 | |
| 43 | ```bash |
| 44 | muse workspace add core https://musehub.ai/acme/core |
| 45 | muse workspace add sounds https://musehub.ai/acme/sounds --branch v2 |
| 46 | muse workspace add data /path/to/local/dataset --path vendor/data |
| 47 | ``` |
| 48 | |
| 49 | | Option | Default | Description | |
| 50 | |--------|---------|-------------| |
| 51 | | `--path` | `repos/<name>` | Relative checkout path inside the workspace | |
| 52 | | `--branch`, `-b` | `main` | Branch to track | |
| 53 | |
| 54 | Registration writes the manifest entry. Run `muse workspace sync` to clone. |
| 55 | |
| 56 | ### `muse workspace list` |
| 57 | |
| 58 | List all registered members with their status. |
| 59 | |
| 60 | ``` |
| 61 | name branch present HEAD url |
| 62 | ────────────────────────────────────────────────────────────────────────────── |
| 63 | core main yes a1b2c3d4ef56 https://musehub.ai/acme/core |
| 64 | sounds v2 yes deadbeef0012 https://musehub.ai/acme/sounds |
| 65 | data main no (not cloned) /path/to/local/dataset |
| 66 | ``` |
| 67 | |
| 68 | ### `muse workspace remove <name>` |
| 69 | |
| 70 | Remove a member from the manifest. The member's directory is **not** deleted. |
| 71 | |
| 72 | ```bash |
| 73 | muse workspace remove sounds |
| 74 | ``` |
| 75 | |
| 76 | ### `muse workspace status` |
| 77 | |
| 78 | Rich status view for all members. |
| 79 | |
| 80 | ``` |
| 81 | Workspace: /Users/me/myproject |
| 82 | |
| 83 | ✅ core branch=main head=a1b2c3d4ef56 |
| 84 | path: /Users/me/myproject/repos/core |
| 85 | url: https://musehub.ai/acme/core |
| 86 | |
| 87 | ❌ data branch=main head=not cloned |
| 88 | path: /Users/me/myproject/repos/data |
| 89 | url: /path/to/local/dataset |
| 90 | ``` |
| 91 | |
| 92 | ### `muse workspace sync [name]` |
| 93 | |
| 94 | Clone or pull all members (or one named member). |
| 95 | |
| 96 | ```bash |
| 97 | muse workspace sync # sync everything |
| 98 | muse workspace sync core # sync only 'core' |
| 99 | ``` |
| 100 | |
| 101 | - If a member directory does not exist, `muse clone` is run to fetch it. |
| 102 | - If a member directory already exists, `muse pull` is run to update it. |
| 103 | |
| 104 | ## Agent workflows |
| 105 | |
| 106 | ### Coordinator + worker pattern |
| 107 | |
| 108 | ```bash |
| 109 | # Coordinator workspace tracks N worker repos: |
| 110 | muse workspace add worker-001 https://musehub.ai/swarm/worker-001 |
| 111 | muse workspace add worker-002 https://musehub.ai/swarm/worker-002 |
| 112 | muse workspace add worker-003 https://musehub.ai/swarm/worker-003 |
| 113 | |
| 114 | # Sync all workers to latest: |
| 115 | muse workspace sync |
| 116 | |
| 117 | # Status across all: |
| 118 | muse workspace status |
| 119 | ``` |
| 120 | |
| 121 | ### Release pipeline |
| 122 | |
| 123 | ```bash |
| 124 | # Pin all members to release branches before archiving: |
| 125 | muse workspace add core https://musehub.ai/acme/core --branch release/v2 |
| 126 | muse workspace add sounds https://musehub.ai/acme/sounds --branch release/v2 |
| 127 | muse workspace sync |
| 128 | |
| 129 | # Archive each member: |
| 130 | for member in repos/*/; do |
| 131 | (cd "$member" && muse archive --output "../../archives/$(basename $member).tar.gz") |
| 132 | done |
| 133 | ``` |
| 134 | |
| 135 | ## Exit codes |
| 136 | |
| 137 | | Code | Meaning | |
| 138 | |------|---------| |
| 139 | | 0 | Success | |
| 140 | | 1 | Validation error, duplicate name, or member not found | |