WM Workspace Manager
Translate natural-language requests about engineering work into concrete wm CLI actions for multi-repo worktree management.
Related Skills
Use brain-operating-system skill when:
- Including brain directory in workspace (
--folder brain flag)
- Understanding brain repository structure and workflows
- Creating workspace notes or documentation
Command Overview
| Command |
Use Case |
Key Flags |
wm init --feature "<label>" <repos...> |
Start new workspace session |
--checkout-existing, --base, --notes, --no-open |
wm open <session-id> |
Reopen existing workspace |
N/A |
wm extend <session-id> <repo> |
Add repo to session |
N/A |
wm list |
Show active sessions |
N/A |
wm prune <session-id> |
Tear down workspace |
Confirm merges first |
Intent Recognition
Treat these verbs as workspace management signals:
- "start working", "continue", "switch to", "resume", "spin up"
- "I need to migrate...", "I want to build...", "Help me with..."
Feature Label Extraction
- Quoted text: Use verbatim (
"flipper feature improvements" → slug flipper-feature-improvements)
- Trailing description: Infer from rest of sentence
- Normalization: lowercase, replace spaces/slashes with
-, drop punctuation
- Branch naming:
feature/<slug>
Repository Resolution
- Search paths:
~/github/* and ~/code/*/*
- Tokenization: Split on commas,
and, +, or whitespace; discard filler words (on, in, for, the)
- Multiple matches: Offer numbered clarification, wait for choice
- Missing repos: Provide clone command or offer to skip/replace
Command Construction
Base Command
wm init --feature "<feature label>" <repo1> <repo2> ...
Optional Flags
--primary <repo>: When user specifies different anchor--base <branch> or <repo:branch>: For custom base branches--notes "<text>": Capture kickoff context--checkout-existing: Reuse existing worktree/branch--folder brain: Include brain directory without creating worktree--dry-run, --no-open, --verbose: Only when explicitly requested
Preflight Checks
- Existing worktrees: Detect slug conflicts; ask to reuse or create timestamped variant
- Environment variables: Respect
WM_WORKTREES_ROOT, WM_WORKSPACES_ROOT, WM_HISTORY_FILE, WM_REPO_CONFIG
- Collision handling: Append timestamp or numeric suffix if slug exists; log original intent
Execution Flow
- Confirm intent before running (unless clear "yes" signal)
- Run command via terminal tool
- Capture stdout/stderr for summary
- On failure: Surface error, propose remediation, ask whether to retry
Post-Execution Reporting
Identify and report:
- Session ID:
<slug>--<primary-repo>+<other-repos-alphabetical>
- Worktree directories:
<root>/<repo>/<slug>
- VS Code workspace:
~/code/workspaces/<session-id>.code-workspace
- Manifest:
~/code/workspaces/<session-id>.json
- Notes folder:
~/code/workspaces/<session-id>/notes.md (if created)
Follow-Up Suggestions
- "Need to reopen? →
wm open <session-id>"
- "Want to attach repo? →
wm extend <session-id> <repo>"
- "Check active sessions →
wm list"
- "Finish session →
wm prune <session-id>" (confirm merges first)
Session Lifecycle
Start
wm init --feature "queue outcomes migration" hamzo spamurai-next
Resume
wm open <session-id>
# or
wm recent 1
Extend
wm extend <session-id> flipper
Status
wm list
Finish
wm prune <session-id>
Edge Cases
- Existing branches: Offer reuse with
--checkout-existing or create timestamped variant
- Branch collisions: Append suffix, log original intent in manifest
- Missing repos: Provide clone instructions; optionally run if credentials allow
- VS Code trust: Advise on trust workflow if repeated prompts occur
- Non-interactive: Never destructive without user confirmation
Example Walkthrough
User request: "I need to start working on flipper feature improvements in hamzo and spamurai-next"
Your steps:
- Extract feature:
flipper feature improvements → slug flipper-feature-improvements → branch feature/flipper-feature-improvements
- Identify repos:
hamzo, spamurai-next (confirm directories exist)
- Run:
wm init --feature "flipper feature improvements" hamzo spamurai-next
- Report:
- Session ID:
flipper-feature-improvements--hamzo+spamurai-next
- Worktree paths: List each
- VS Code launch status
- Remind about
wm open and wm prune
Including Brain Directory
When user wants the brain workspace (second-brain notes) in the session:
wm init --feature "<label>" --folder brain <repo1> <repo2>
This adds brain to the workspace without creating a worktree (brain isn't a git repo managed by wm).
Communication Guidelines
- Concise task-focused responses
- Surface critical state immediately: success/failure, workspace location, branch names
- Actionable next steps: especially for resume/finish flows
- Clarify only when required: multiple repo matches, unclear feature name
1---2name: wm-workspace-manager3description: Workspace orchestration automation for the wm CLI multi-repo workflow. Use when user wants to start, resume, extend, or manage engineering workspaces with Git worktrees. Handles intent parsing ("start working on X"), repository resolution, feature slugging, branch naming, and wm command construction with proper flags and collision handling.4---5
6# WM Workspace Manager
7
8Translate natural-language requests about engineering work into concrete `wm` CLI actions for multi-repo worktree management.
9
10## Related Skills
11
12**Use `brain-operating-system` skill** when:
13- Including brain directory in workspace (`--folder brain` flag)
14- Understanding brain repository structure and workflows
15- Creating workspace notes or documentation
16
17## Command Overview
18
19| Command | Use Case | Key Flags |
20|---------|----------|-----------|
21| `wm init --feature "<label>" <repos...>` | Start new workspace session | `--checkout-existing`, `--base`, `--notes`, `--no-open` |
22| `wm open <session-id>` | Reopen existing workspace | N/A |
23| `wm extend <session-id> <repo>` | Add repo to session | N/A |
24| `wm list` | Show active sessions | N/A |
25| `wm prune <session-id>` | Tear down workspace | Confirm merges first |
26
27## Intent Recognition
28
29Treat these verbs as workspace management signals:
30- "start working", "continue", "switch to", "resume", "spin up"
31- "I need to migrate...", "I want to build...", "Help me with..."
32
33## Feature Label Extraction
34
351. **Quoted text**: Use verbatim (`"flipper feature improvements"` → slug `flipper-feature-improvements`)
362. **Trailing description**: Infer from rest of sentence
373. **Normalization**: lowercase, replace spaces/slashes with `-`, drop punctuation
384. **Branch naming**: `feature/<slug>`
39
40## Repository Resolution
41
421. **Search paths**: `~/github/*` and `~/code/*/*`
432. **Tokenization**: Split on commas, `and`, `+`, or whitespace; discard filler words (`on`, `in`, `for`, `the`)
443. **Multiple matches**: Offer numbered clarification, wait for choice
454. **Missing repos**: Provide clone command or offer to skip/replace
46
47## Command Construction
48
49### Base Command
50```bash
51wm init --feature "<feature label>" <repo1> <repo2> ...
52```
53
54### Optional Flags
55
56- `--primary <repo>`: When user specifies different anchor
57- `--base <branch>` or `<repo:branch>`: For custom base branches
58- `--notes "<text>"`: Capture kickoff context
59- `--checkout-existing`: Reuse existing worktree/branch
60- `--folder brain`: Include brain directory without creating worktree
61- `--dry-run`, `--no-open`, `--verbose`: Only when explicitly requested
62
63### Preflight Checks
64
651. **Existing worktrees**: Detect slug conflicts; ask to reuse or create timestamped variant
662. **Environment variables**: Respect `WM_WORKTREES_ROOT`, `WM_WORKSPACES_ROOT`, `WM_HISTORY_FILE`, `WM_REPO_CONFIG`
673. **Collision handling**: Append timestamp or numeric suffix if slug exists; log original intent
68
69## Execution Flow
70
711. **Confirm intent** before running (unless clear "yes" signal)
722. **Run command** via terminal tool
733. **Capture stdout/stderr** for summary
744. **On failure**: Surface error, propose remediation, ask whether to retry
75
76## Post-Execution Reporting
77
78Identify and report:
79- **Session ID**: `<slug>--<primary-repo>+<other-repos-alphabetical>`
80- **Worktree directories**: `<root>/<repo>/<slug>`
81- **VS Code workspace**: `~/code/workspaces/<session-id>.code-workspace`
82- **Manifest**: `~/code/workspaces/<session-id>.json`
83- **Notes folder**: `~/code/workspaces/<session-id>/notes.md` (if created)
84
85## Follow-Up Suggestions
86
87- "Need to reopen? → `wm open <session-id>`"
88- "Want to attach repo? → `wm extend <session-id> <repo>`"
89- "Check active sessions → `wm list`"
90- "Finish session → `wm prune <session-id>`" (confirm merges first)
91
92## Session Lifecycle
93
94### Start
95```bash
96wm init --feature "queue outcomes migration" hamzo spamurai-next
97```
98
99### Resume
100```bash
101wm open <session-id>
102# or
103wm recent 1
104```
105
106### Extend
107```bash
108wm extend <session-id> flipper
109```
110
111### Status
112```bash
113wm list
114```
115
116### Finish
117```bash
118wm prune <session-id>
119```
120
121## Edge Cases
122
123- **Existing branches**: Offer reuse with `--checkout-existing` or create timestamped variant
124- **Branch collisions**: Append suffix, log original intent in manifest
125- **Missing repos**: Provide clone instructions; optionally run if credentials allow
126- **VS Code trust**: Advise on trust workflow if repeated prompts occur
127- **Non-interactive**: Never destructive without user confirmation
128
129## Example Walkthrough
130
131**User request**: "I need to start working on flipper feature improvements in hamzo and spamurai-next"
132
133**Your steps**:
1341. Extract feature: `flipper feature improvements` → slug `flipper-feature-improvements` → branch `feature/flipper-feature-improvements`
1352. Identify repos: `hamzo`, `spamurai-next` (confirm directories exist)
1363. Run: `wm init --feature "flipper feature improvements" hamzo spamurai-next`
1374. Report:
138 - Session ID: `flipper-feature-improvements--hamzo+spamurai-next`
139 - Worktree paths: List each
140 - VS Code launch status
141 - Remind about `wm open` and `wm prune`
142
143## Including Brain Directory
144
145When user wants the brain workspace (second-brain notes) in the session:
146
147```bash
148wm init --feature "<label>" --folder brain <repo1> <repo2>
149```
150
151This adds brain to the workspace **without** creating a worktree (brain isn't a git repo managed by wm).
152
153## Communication Guidelines
154
155- **Concise task-focused responses**
156- **Surface critical state immediately**: success/failure, workspace location, branch names
157- **Actionable next steps**: especially for resume/finish flows
158- **Clarify only when required**: multiple repo matches, unclear feature name
majiayu000