@memnexus-ai/mx-agent-cli 0.1.50 → 0.1.52

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/dist/__tests__/claude-sync.test.js +20 -136
  2. package/dist/__tests__/claude-sync.test.js.map +1 -1
  3. package/dist/commands/create.d.ts.map +1 -1
  4. package/dist/commands/create.js +18 -137
  5. package/dist/commands/create.js.map +1 -1
  6. package/dist/commands/init.d.ts +2 -12
  7. package/dist/commands/init.d.ts.map +1 -1
  8. package/dist/commands/init.js +21 -70
  9. package/dist/commands/init.js.map +1 -1
  10. package/dist/commands/list.d.ts +0 -1
  11. package/dist/commands/list.d.ts.map +1 -1
  12. package/dist/commands/list.js +9 -39
  13. package/dist/commands/list.js.map +1 -1
  14. package/dist/commands/start.d.ts.map +1 -1
  15. package/dist/commands/start.js +18 -225
  16. package/dist/commands/start.js.map +1 -1
  17. package/dist/commands/update.d.ts.map +1 -1
  18. package/dist/commands/update.js +15 -28
  19. package/dist/commands/update.js.map +1 -1
  20. package/dist/index.js +1 -16
  21. package/dist/index.js.map +1 -1
  22. package/dist/lib/claude.d.ts +4 -15
  23. package/dist/lib/claude.d.ts.map +1 -1
  24. package/dist/lib/claude.js +44 -331
  25. package/dist/lib/claude.js.map +1 -1
  26. package/dist/lib/memory.d.ts +6 -1
  27. package/dist/lib/memory.d.ts.map +1 -1
  28. package/dist/lib/memory.js +11 -8
  29. package/dist/lib/memory.js.map +1 -1
  30. package/dist/lib/project-config.d.ts +7 -7
  31. package/dist/lib/project-config.d.ts.map +1 -1
  32. package/dist/lib/project-config.js +6 -3
  33. package/dist/lib/project-config.js.map +1 -1
  34. package/dist/lib/templates.d.ts +1 -39
  35. package/dist/lib/templates.d.ts.map +1 -1
  36. package/dist/lib/templates.js +25 -1239
  37. package/dist/lib/templates.js.map +1 -1
  38. package/dist/lib/worktree.d.ts +1 -19
  39. package/dist/lib/worktree.d.ts.map +1 -1
  40. package/dist/lib/worktree.js +4 -55
  41. package/dist/lib/worktree.js.map +1 -1
  42. package/package.json +2 -3
  43. package/README.md +0 -104
  44. package/dist/commands/new.d.ts +0 -30
  45. package/dist/commands/new.d.ts.map +0 -1
  46. package/dist/commands/new.js +0 -150
  47. package/dist/commands/new.js.map +0 -1
@@ -9,540 +9,53 @@
9
9
  * Grants bash access and restricts to the worktree directory.
10
10
  */
11
11
  export const SETTINGS_JSON_TEMPLATE = JSON.stringify({
12
- CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: '1',
13
- hooks: {
14
- PreToolUse: [
15
- {
16
- matcher: 'Bash',
17
- hooks: [
18
- { type: 'command', command: '.claude/hooks/worktree-guard.sh' },
19
- { type: 'command', command: '.claude/hooks/mx-guard-hook.sh' },
20
- ],
21
- },
22
- ],
23
- PreCompact: [
24
- {
25
- matcher: '',
26
- hooks: [{ type: 'command', command: '.claude/hooks/auto-checkpoint.sh' }],
27
- },
28
- ],
29
- SessionStart: [
30
- {
31
- matcher: 'compact',
32
- hooks: [{ type: 'command', command: '.claude/hooks/reload-checkpoint.sh' }],
33
- },
34
- {
35
- matcher: '',
36
- hooks: [{ type: 'command', command: '.claude/hooks/set-terminal-appearance.sh' }],
37
- },
38
- ],
39
- },
40
12
  permissions: {
41
13
  allow: [
42
- 'mcp__MX__search_memories',
43
- 'mcp__MX__create_memory',
44
- 'mcp__MX__retrieve_episodic_memory',
45
- 'mcp__MX__get_patterns',
46
- 'mcp__MX__detect_patterns',
47
- 'mcp__MX__get_topic_summary',
48
- 'mcp__MX__search_semantic_facts',
49
- 'mcp__MX__find_conversations_by_topic',
50
- 'mcp__MX__graphrag_query',
51
- 'mcp__MX__get_memory_usage',
52
- 'mcp__MX__list_conversations',
53
- 'Bash',
54
- 'Read',
55
- 'Edit',
56
- 'Write',
57
- 'Glob',
58
- 'Grep',
59
- 'WebFetch',
60
- 'WebSearch',
61
- 'Task',
62
- 'NotebookEdit',
14
+ 'Bash(*)',
15
+ 'Read(*)',
16
+ 'Write(*)',
17
+ 'Edit(*)',
18
+ 'Glob(*)',
19
+ 'Grep(*)',
63
20
  ],
64
21
  deny: [
65
- 'Bash(rm -rf /*)',
66
- 'Bash(rm -rf /)',
67
- 'Bash(rm -rf ~)',
68
- 'Bash(rm -rf ~/*)',
69
- 'Bash(dd if=/dev/zero *)',
70
- 'Bash(mkfs *)',
71
- 'Bash(shred *)',
72
- 'Bash(git reset --hard *)',
73
- 'Bash(git clean -fd *)',
74
- 'Bash(git clean -fdx *)',
75
- 'Bash(kubectl delete namespace *)',
76
- 'Bash(kubectl delete node *)',
77
- 'Bash(helm uninstall *)',
78
- 'Bash(az group delete *)',
79
- 'Bash(az aks delete *)',
80
- 'Bash(az deployment group delete *)',
81
22
  'Bash(git checkout main)',
82
- 'Bash(git checkout main *)',
83
- 'Bash(git checkout -)',
84
- 'Bash(git switch main)',
85
- 'Bash(git switch main *)',
86
- 'Bash(git checkout -b *)',
87
- 'Bash(git switch -c *)',
88
- 'Bash(git switch --create *)',
89
- 'Bash(git branch * *)',
90
- 'Bash(git merge *)',
23
+ 'Bash(git checkout master)',
91
24
  'Bash(git push origin main)',
92
- 'Bash(git push origin main *)',
93
- 'Bash(git push -u origin main)',
94
- 'Bash(git push -u origin main *)',
95
- 'Bash(git push --force *)',
96
- 'Bash(git push -f *)',
97
- ],
98
- ask: [
99
- 'Bash(sudo *)',
100
- 'Bash(chown *)',
101
- 'Bash(docker kill *)',
102
- 'Bash(docker rm *)',
103
- 'Bash(docker rmi *)',
104
- 'Bash(kubectl delete pod *)',
105
- 'Bash(kubectl delete deployment *)',
106
- 'Bash(kubectl delete service *)',
107
- 'Bash(kubectl drain *)',
108
- 'Bash(kubectl taint *)',
109
- 'Bash(helm upgrade *)',
110
- 'Bash(helm rollback *)',
111
- 'Bash(az aks upgrade *)',
112
- 'Bash(az aks scale *)',
113
- 'Bash(az deployment group create *)',
114
- 'Bash(az vm delete *)',
115
- 'Bash(az storage account delete *)',
25
+ 'Bash(git push origin master)',
26
+ 'Bash(git switch main)',
27
+ 'Bash(git switch master)',
116
28
  ],
117
29
  },
118
30
  }, null, 2);
119
- /**
120
- * mx-guard-hook.sh — PreToolUse hook that runs mx-guard check before
121
- * allowing git push commands.
122
- */
123
- export const MX_GUARD_HOOK_SH_TEMPLATE = `#!/bin/bash
124
- # mx-guard pre-push enforcement hook
125
- # Runs mx-guard check before allowing git push commands.
126
- # Deployed by mx-agent create via syncClaudeConfig().
127
- #
128
- # Exit codes:
129
- # 0 = allow (not a push command, or mx-guard passes)
130
- # 2 = block (mx-guard found errors)
131
-
132
- # Read hook input from stdin
133
- INPUT=$(cat)
134
- COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
135
-
136
- # Only intercept git push commands
137
- if [[ ! "$COMMAND" =~ ^git\\ push ]]; then
138
- exit 0
139
- fi
140
-
141
- # Check if mx-guard is available
142
- if ! command -v mx-guard &>/dev/null; then
143
- echo "⚠ mx-guard not installed — skipping pre-push validation"
144
- echo " Install: pnpm install -g @memnexus-ai/mx-guard"
145
- exit 0
146
- fi
147
-
148
- # Run mx-guard check (change-aware — only checks files on current branch)
149
- echo "Running mx-guard check before push..."
150
- echo ""
151
-
152
- mx-guard check
153
- GUARD_EXIT=$?
154
-
155
- if [ $GUARD_EXIT -ne 0 ]; then
156
- echo ""
157
- echo "mx-guard: push blocked. Fix the errors above before pushing."
158
- echo " To check specific rules: mx-guard check --rule <category>"
159
- echo " To see all rules: mx-guard rules"
160
- exit 2
161
- fi
162
-
163
- exit 0
164
- `;
165
31
  /**
166
32
  * Stub worktree-guard.sh hook.
167
33
  * Blocks branch switching to main and force-pushes.
168
34
  */
169
- export const WORKTREE_GUARD_SH_TEMPLATE = `#!/bin/bash
170
- # Worktree isolation guard - runs before every Bash command
171
- # Exit 0 = allow, Exit 2 = block (non-zero exit blocks the command)
172
- #
173
- # This hook enforces worktree isolation by:
174
- # 1. Blocking cd commands that leave the worktree directory
175
- # 2. Blocking dangerous git operations (belt-and-suspenders with settings.json)
176
- #
177
- # Requires environment variables set by \`worktree start\`:
178
- # - CLAUDE_WORKTREE_PATH: Absolute path to worktree (e.g., /workspace/.worktrees/foo)
179
- # - CLAUDE_WORKTREE_NAME: Worktree name (e.g., foo)
35
+ export const WORKTREE_GUARD_SH_TEMPLATE = `#!/usr/bin/env bash
36
+ # worktree-guard.sh Claude Code PreToolUse hook
37
+ # Blocks dangerous git operations in worktrees.
38
+ # Customise this file for your project's safety requirements.
180
39
 
181
40
  set -euo pipefail
182
41
 
183
- # Read the tool input from stdin (JSON format)
184
- INPUT=$(cat)
185
-
186
- # Extract the command - handle both direct command and tool_input formats
187
- COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // .command // empty' 2>/dev/null)
188
-
189
- if [[ -z "$COMMAND" ]]; then
190
- # Can't parse command, allow it (fail open)
191
- exit 0
192
- fi
193
-
194
- # Get worktree path from environment
195
- WORKTREE_PATH="\${CLAUDE_WORKTREE_PATH:-}"
42
+ TOOL_NAME="\${CLAUDE_TOOL_NAME:-}"
43
+ TOOL_INPUT="\${CLAUDE_TOOL_INPUT:-}"
196
44
 
197
- # If no worktree restriction set, allow everything
198
- if [[ -z "$WORKTREE_PATH" ]]; then
45
+ if [[ "\$TOOL_NAME" != "Bash" ]]; then
199
46
  exit 0
200
47
  fi
201
48
 
202
- # Normalize worktree path (remove trailing slash)
203
- WORKTREE_PATH="\${WORKTREE_PATH%/}"
204
-
205
- # Get current working directory
206
- CURRENT_DIR=$(pwd)
207
-
208
- # ============================================================
209
- # Rule 1: Block cd to paths outside worktree
210
- # ============================================================
211
- if echo "$COMMAND" | grep -qE '^\\s*cd\\s+' || echo "$COMMAND" | grep -qE '&&\\s*cd\\s+' || echo "$COMMAND" | grep -qE ';\\s*cd\\s+'; then
212
- # Extract cd target(s) from command
213
- # This handles: cd /path, cd path, command && cd path, etc.
214
-
215
- # Get all cd targets
216
- CD_TARGETS=$(echo "$COMMAND" | grep -oE 'cd\\s+[^;&|]+' | sed 's/cd\\s*//' | tr -d '"'"'" || true)
217
-
218
- for TARGET in $CD_TARGETS; do
219
- # Skip empty targets
220
- [[ -z "$TARGET" ]] && continue
221
-
222
- # Resolve the path
223
- if [[ "$TARGET" == /* ]]; then
224
- # Absolute path
225
- RESOLVED="$TARGET"
226
- elif [[ "$TARGET" == "~"* ]]; then
227
- # Home directory path
228
- RESOLVED="\${TARGET/#\\~/$HOME}"
229
- else
230
- # Relative path - resolve from current directory
231
- RESOLVED=$(cd "$CURRENT_DIR" 2>/dev/null && cd "$TARGET" 2>/dev/null && pwd) || RESOLVED=""
232
- fi
233
-
234
- # Normalize resolved path
235
- RESOLVED="\${RESOLVED%/}"
236
-
237
- # Allow /tmp and /var/tmp
238
- if [[ "$RESOLVED" == /tmp* ]] || [[ "$RESOLVED" == /var/tmp* ]]; then
239
- continue
240
- fi
241
-
242
- # Allow paths within worktree
243
- if [[ "$RESOLVED" == "$WORKTREE_PATH"* ]]; then
244
- continue
245
- fi
246
-
247
- # Allow the scratchpad directory
248
- if [[ "$RESOLVED" == *"/scratchpad"* ]]; then
249
- continue
250
- fi
251
-
252
- # Allow the user's home directory (for inspecting global tools, configs, etc.)
253
- if [[ -n "$HOME" ]] && [[ "$RESOLVED" == "$HOME"* ]]; then
254
- continue
255
- fi
256
-
257
- # Block: path is outside worktree
258
- if [[ -n "$RESOLVED" ]]; then
259
- echo ""
260
- echo "BLOCKED: Cannot navigate outside worktree"
261
- echo " Target: $TARGET"
262
- echo " Resolved: $RESOLVED"
263
- echo " Allowed: $WORKTREE_PATH (and /tmp)"
264
- echo ""
265
- echo "You are working in worktree: \${CLAUDE_WORKTREE_NAME:-unknown}"
266
- echo "Stay within your assigned worktree directory."
267
- echo ""
268
- exit 2
269
- fi
270
- done
271
- fi
272
-
273
- # ============================================================
274
- # Rule 2: Block git operations that could tangle state
275
- # (Belt-and-suspenders with settings.json deny rules)
276
- # ============================================================
277
-
278
- # Block checkout to main
279
- if echo "$COMMAND" | grep -qE 'git\\s+(checkout|switch)\\s+main(\\s|$)'; then
280
- echo ""
281
- echo "BLOCKED: Cannot switch to main branch"
282
- echo " Command: $COMMAND"
283
- echo " Worktree: \${CLAUDE_WORKTREE_NAME:-unknown}"
284
- echo ""
285
- echo "To work on main, use a different worktree or the root workspace."
286
- echo ""
287
- exit 2
288
- fi
289
-
290
- # Block checkout -b (new branch creation)
291
- if echo "$COMMAND" | grep -qE 'git\\s+(checkout\\s+-b|switch\\s+(-c|--create))'; then
292
- echo ""
293
- echo "BLOCKED: Cannot create new branches"
294
- echo " Command: $COMMAND"
295
- echo " Worktree: \${CLAUDE_WORKTREE_NAME:-unknown}"
296
- echo ""
297
- echo "Work on your assigned branch. Create PRs to merge changes."
298
- echo ""
299
- exit 2
49
+ # Block checkout/switch to base branch
50
+ if echo "\$TOOL_INPUT" | grep -qE 'git (checkout|switch) (main|master|develop)'; then
51
+ echo "Blocked: cannot switch to base branch from a worktree." >&2
52
+ exit 1
300
53
  fi
301
54
 
302
- # Block merge
303
- if echo "$COMMAND" | grep -qE 'git\\s+merge\\s'; then
304
- echo ""
305
- echo "BLOCKED: Cannot merge branches directly"
306
- echo " Command: $COMMAND"
307
- echo " Worktree: \${CLAUDE_WORKTREE_NAME:-unknown}"
308
- echo ""
309
- echo "Use pull requests to merge changes."
310
- echo ""
311
- exit 2
312
- fi
313
-
314
- # Block push to main
315
- if echo "$COMMAND" | grep -qE 'git\\s+push\\s+.*\\s*origin\\s+main'; then
316
- echo ""
317
- echo "BLOCKED: Cannot push to main"
318
- echo " Command: $COMMAND"
319
- echo ""
320
- echo "Push to your worktree branch and create a PR."
321
- echo ""
322
- exit 2
323
- fi
324
-
325
- # ============================================================
326
- # All checks passed - allow the command
327
- # ============================================================
328
- exit 0
329
- `;
330
- /**
331
- * auto-checkpoint.sh — PreCompact hook that saves a checkpoint memory
332
- * before context compaction so agents can resume after losing context.
333
- */
334
- export const AUTO_CHECKPOINT_SH_TEMPLATE = `#!/bin/bash
335
- # auto-checkpoint.sh — Claude Code PreCompact hook
336
- # Saves a checkpoint memory before context compaction so agents can resume
337
- # after losing context. Uses the /mx-checkpoint template format.
338
- #
339
- # Fires on: PreCompact (auto or manual compaction)
340
- # Input: JSON on stdin with transcript_path, session_id, trigger
341
- # Output: none (side-effect only — saves memory via mx CLI)
342
- # Exit: always 0 (never blocks compaction)
343
-
344
- # Fail-open: any error → allow compaction without saving
345
- trap 'exit 0' ERR
346
-
347
- # ── 1. Parse hook input ──────────────────────────────────────────────────
348
- INPUT=$(cat)
349
-
350
- TRANSCRIPT_PATH=$(echo "$INPUT" | jq -r '.transcript_path // empty' 2>/dev/null)
351
- SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty' 2>/dev/null)
352
- TRIGGER=$(echo "$INPUT" | jq -r '.trigger // .source // "auto"' 2>/dev/null)
353
-
354
- # Skip if no transcript available or jq missing
355
- if [[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]]; then
356
- exit 0
357
- fi
358
-
359
- command -v jq >/dev/null 2>&1 || exit 0
360
- command -v mx >/dev/null 2>&1 || exit 0
361
-
362
- # ── 2. Extract context from transcript ───────────────────────────────────
363
-
364
- # Recent user/assistant text (last ~200 lines of transcript, text content only)
365
- RECENT_TEXT=$(tail -200 "$TRANSCRIPT_PATH" | \\
366
- jq -r '
367
- select(.type == "user" or .type == "assistant") |
368
- .message.content[]? |
369
- select(.type == "text") |
370
- .text // empty
371
- ' 2>/dev/null | tail -c 8000)
372
-
373
- # Files touched (from tool_use entries: Read, Edit, Write, Glob)
374
- FILES_TOUCHED=$(tail -500 "$TRANSCRIPT_PATH" | \\
375
- jq -r '
376
- select(.type == "assistant") |
377
- .message.content[]? |
378
- select(.type == "tool_use") |
379
- .input.file_path // empty
380
- ' 2>/dev/null | grep -v '^\$' | sort -u | head -30)
381
-
382
- # Git branch and PR references
383
- GIT_BRANCH="\${CLAUDE_WORKTREE_BRANCH:-}"
384
- if [[ -z "$GIT_BRANCH" ]]; then
385
- GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
386
- fi
387
-
388
- # GitHub issue/PR references from recent text
389
- GH_REFS=$(echo "$RECENT_TEXT" | grep -oE '#[0-9]+|PR #[0-9]+|issue #[0-9]+' 2>/dev/null | sort -u | head -10 | tr '\\n' ', ' | sed 's/,\$//')
390
-
391
- # Worktree info
392
- WORKTREE_NAME="\${CLAUDE_WORKTREE_NAME:-unknown}"
393
- WORKTREE_PATH="\${CLAUDE_WORKTREE_PATH:-$(pwd)}"
394
-
395
- # ── 3. Format checkpoint memory ─────────────────────────────────────────
396
-
397
- # Build files list (indented)
398
- FILES_LIST=""
399
- if [[ -n "$FILES_TOUCHED" ]]; then
400
- FILES_LIST=$(echo "$FILES_TOUCHED" | sed 's/^/- /')
401
- fi
402
-
403
- CONTENT="[Auto-Checkpoint] Context compaction (\${TRIGGER}) — \${WORKTREE_NAME}
404
-
405
- Branch: \${GIT_BRANCH}
406
- Session: \${SESSION_ID}
407
- GitHub refs: \${GH_REFS:-none detected}
408
-
409
- Goal: [Auto-captured checkpoint before context compaction]
410
-
411
- Current status: Context window reached capacity. This checkpoint captures the working state just before compaction so the next session can resume.
412
-
413
- Key files:
414
- \${FILES_LIST:-No file paths detected in recent transcript.}
415
-
416
- Key terms: \${WORKTREE_NAME}, \${GIT_BRANCH}, auto-checkpoint, context-compaction
417
-
418
- Next steps: Resume work from this checkpoint. Review the recent context below to understand what was in progress.
419
-
420
- ---
421
- Recent context (last messages before compaction):
422
-
423
- \${RECENT_TEXT:-No recent text extracted from transcript.}"
424
-
425
- # ── 4. Save checkpoint memory ───────────────────────────────────────────
426
-
427
- # Use a named memory so it's easy to find and gets overwritten each compaction
428
- mx memories create \\
429
- --name "auto-checkpoint-\${WORKTREE_NAME}" \\
430
- --conversation-id "NEW" \\
431
- --content "$CONTENT" \\
432
- --topics "checkpoint,context-compaction" \\
433
- >/dev/null 2>&1 || true
434
-
435
- # Always allow compaction to proceed
436
- exit 0
437
- `;
438
- /**
439
- * reload-checkpoint.sh — SessionStart hook (compact) that re-injects
440
- * the auto-checkpoint memory after context compaction.
441
- */
442
- export const RELOAD_CHECKPOINT_SH_TEMPLATE = `#!/bin/bash
443
- # reload-checkpoint.sh — Claude Code SessionStart hook (matcher: compact)
444
- # Re-injects the auto-checkpoint memory after context compaction.
445
- #
446
- # Fires on: SessionStart with source=compact (after compaction)
447
- # Input: JSON on stdin with session_id, source
448
- # Output: stdout text is injected into Claude's context
449
- # Exit: always 0
450
-
451
- # Fail-open: any error → start session without checkpoint injection
452
- trap 'exit 0' ERR
453
-
454
- # ── 1. Determine worktree name ──────────────────────────────────────────
455
-
456
- WORKTREE_NAME="\${CLAUDE_WORKTREE_NAME:-}"
457
-
458
- # If no worktree env var, try to detect from cwd
459
- if [[ -z "$WORKTREE_NAME" ]]; then
460
- INPUT=$(cat)
461
- CWD=$(echo "$INPUT" | jq -r '.cwd // empty' 2>/dev/null)
462
- if [[ "$CWD" == */.worktrees/* ]]; then
463
- WORKTREE_NAME=$(echo "$CWD" | sed 's|.*/.worktrees/||' | cut -d'/' -f1)
464
- fi
465
- fi
466
-
467
- # Can't identify worktree → nothing to reload
468
- if [[ -z "$WORKTREE_NAME" ]]; then
469
- exit 0
470
- fi
471
-
472
- command -v mx >/dev/null 2>&1 || exit 0
473
-
474
- # ── 2. Retrieve checkpoint memory ───────────────────────────────────────
475
-
476
- CHECKPOINT=$(mx memories get --name "auto-checkpoint-\${WORKTREE_NAME}" 2>/dev/null)
477
-
478
- if [[ -z "$CHECKPOINT" || "$CHECKPOINT" == *"not found"* || "$CHECKPOINT" == *"404"* ]]; then
479
- exit 0
480
- fi
481
-
482
- # Extract just the content field from the JSON response
483
- CONTENT=$(echo "$CHECKPOINT" | jq -r '.content // empty' 2>/dev/null)
484
-
485
- if [[ -z "$CONTENT" ]]; then
486
- exit 0
487
- fi
488
-
489
- # ── 3. Output checkpoint for context injection ──────────────────────────
490
- # Text written to stdout by SessionStart hooks is added to Claude's context.
491
-
492
- cat <<CHECKPOINT_EOF
493
- ## Auto-Checkpoint Recovery
494
-
495
- The following checkpoint was automatically saved before the last context compaction.
496
- Use it to resume your work. The checkpoint captures what you were working on,
497
- which files were involved, and the recent conversation context.
498
-
499
- ---
500
-
501
- \${CONTENT}
502
-
503
- ---
504
-
505
- **Action:** Review this checkpoint and continue where you left off.
506
- If you need more context, search memories with: mx memories search --query "<topic>" --recent 24h
507
- CHECKPOINT_EOF
508
-
509
- exit 0
510
- `;
511
- /**
512
- * set-terminal-appearance.sh — SessionStart hook that sets VS Code terminal
513
- * tab title and color via OSC escape sequences written to /dev/tty.
514
- */
515
- export const SET_TERMINAL_APPEARANCE_SH_TEMPLATE = `#!/bin/bash
516
- # set-terminal-appearance.sh — Claude Code SessionStart hook
517
- # Sets the VS Code terminal tab title and color for the agent team.
518
- #
519
- # Fires on: SessionStart (all — no matcher filter)
520
- # Input: JSON on stdin (ignored)
521
- # Output: none (side-effect: writes OSC sequences to /dev/tty)
522
- # Exit: always 0
523
- #
524
- # Reads CLAUDE_TEAM_NAME and CLAUDE_TEAM_COLOR from environment
525
- # (set by mx-agent start via launchClaudeSession).
526
- # Writes escape sequences to /dev/tty to bypass Claude's stdin/stdout,
527
- # ensuring the tab title/color persist after Claude's TUI initializes.
528
-
529
- TEAM_NAME="\${CLAUDE_TEAM_NAME:-}"
530
- TEAM_COLOR="\${CLAUDE_TEAM_COLOR:-}"
531
-
532
- # Nothing to set — not launched via mx-agent
533
- if [[ -z "$TEAM_NAME" ]]; then
534
- exit 0
535
- fi
536
-
537
- # Drain stdin (hook contract requires reading input)
538
- cat > /dev/null 2>&1 || true
539
-
540
- # OSC 0: Set terminal tab title
541
- printf '\\033]0;%s\\007' "$TEAM_NAME" > /dev/tty 2>/dev/null || true
542
-
543
- # OSC 633;P;tabColor: Set VS Code tab color (VS Code 1.94+ shell integration)
544
- if [[ -n "$TEAM_COLOR" ]]; then
545
- printf '\\033]633;P;tabColor=%s\\007' "$TEAM_COLOR" > /dev/tty 2>/dev/null || true
55
+ # Block force push to base branch
56
+ if echo "\$TOOL_INPUT" | grep -qE 'git push .*(--force|-f).*(main|master|develop)'; then
57
+ echo "Blocked: force push to base branch is not allowed." >&2
58
+ exit 1
546
59
  fi
547
60
 
548
61
  exit 0
@@ -572,731 +85,4 @@ Replace the contents below with your project-specific agent instructions.
572
85
  2. Do not push to the base branch directly — create a PR.
573
86
  3. Follow the project's coding conventions.
574
87
  `;
575
- /**
576
- * .mcp.json deployed to each worktree root.
577
- * Configures the MX (MemNexus) MCP server for Claude Code.
578
- */
579
- export const MCP_JSON_TEMPLATE = JSON.stringify({
580
- mcpServers: {
581
- memnexus: {
582
- type: 'stdio',
583
- command: 'mx',
584
- args: ['mcp', 'serve'],
585
- },
586
- },
587
- }, null, 2) + '\n';
588
- // ── Templates for `mx-agent new` ────────────────────────────────────────────
589
- export function newProjectDockerfileTemplate() {
590
- return `FROM mcr.microsoft.com/devcontainers/base:ubuntu-22.04
591
-
592
- # Remove stale Yarn repo (has expired GPG key that breaks apt update)
593
- RUN rm -f /etc/apt/sources.list.d/yarn.list /usr/share/keyrings/yarn.gpg 2>/dev/null || true
594
-
595
- # Install Node.js 22 from NodeSource
596
- RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \\
597
- && apt-get install -y nodejs \\
598
- && npm install -g npm@latest
599
-
600
- # Install development tools
601
- RUN apt-get update && apt-get install -y \\
602
- bubblewrap \\
603
- gh \\
604
- jq \\
605
- socat \\
606
- && rm -rf /var/lib/apt/lists/*
607
-
608
- WORKDIR /workspace
609
- ENTRYPOINT ["sleep", "infinity"]
610
- `;
611
- }
612
- export function newProjectDevcontainerJsonTemplate(projectName) {
613
- const safeName = projectName.replace(/[^a-z0-9-]/g, '-');
614
- return JSON.stringify({
615
- name: projectName,
616
- build: {
617
- dockerfile: 'Dockerfile',
618
- context: '..',
619
- },
620
- overrideCommand: false,
621
- workspaceFolder: '/workspace',
622
- workspaceMount: 'source=${localWorkspaceFolder},target=/workspace,type=bind,consistency=cached',
623
- mounts: [
624
- `source=${safeName}-shell-history,target=/commandhistory,type=volume`,
625
- `source=${safeName}-gh-config,target=/home/vscode/.config/gh,type=volume`,
626
- `source=${safeName}-claude-config,target=/home/vscode/.claude,type=volume`,
627
- ],
628
- customizations: {
629
- vscode: {
630
- extensions: ['Anthropic.claude-code'],
631
- settings: {
632
- 'editor.formatOnSave': true,
633
- },
634
- },
635
- },
636
- postCreateCommand: 'bash /workspace/.devcontainer/post-create.sh',
637
- postStartCommand: 'bash /workspace/.devcontainer/post-start.sh',
638
- remoteUser: 'vscode',
639
- updateRemoteUserUID: true,
640
- }, null, 2) + '\n';
641
- }
642
- export function newProjectPostCreateShTemplate(projectName) {
643
- return `#!/bin/bash
644
- set -e
645
-
646
- echo "========================================"
647
- echo " Setting up ${projectName}"
648
- echo "========================================"
649
-
650
- # Fix volume permissions (named volumes created as root)
651
- sudo chown -R \$(id -u):\$(id -g) /home/vscode/.config/gh 2>/dev/null || true
652
- sudo chown -R \$(id -u):\$(id -g) /home/vscode/.claude 2>/dev/null || true
653
-
654
- # Configure persistent shell history
655
- if [ -d /commandhistory ]; then
656
- sudo chown -R \$(id -u):\$(id -g) /commandhistory 2>/dev/null || true
657
- touch /commandhistory/.bash_history 2>/dev/null || true
658
- if ! grep -q "HISTFILE=/commandhistory/.bash_history" ~/.bashrc 2>/dev/null; then
659
- echo 'export HISTFILE=/commandhistory/.bash_history' >> ~/.bashrc
660
- fi
661
- fi
662
-
663
- # Configure Git safe.directory for the workspace (required for worktrees)
664
- echo "Configuring Git..."
665
- git config --global --add safe.directory /workspace
666
-
667
- # Configure npm global prefix (avoids EACCES when running as non-root vscode user)
668
- echo "Configuring npm..."
669
- mkdir -p "\$HOME/.npm-global"
670
- npm config set prefix "\$HOME/.npm-global"
671
- if ! grep -q 'export PATH="\$HOME/.npm-global/bin:\$PATH"' ~/.bashrc 2>/dev/null; then
672
- echo 'export PATH="\$HOME/.npm-global/bin:\$PATH"' >> ~/.bashrc
673
- fi
674
- export PATH="\$HOME/.npm-global/bin:\$PATH"
675
-
676
- # Install Claude Code CLI
677
- echo "Installing Claude Code..."
678
- curl -fsSL https://claude.ai/install.sh | bash || true
679
- # Claude Code installs to ~/.local/bin on newer versions, ~/.claude/bin on older
680
- if [ -f "\$HOME/.local/bin/claude" ]; then
681
- if ! grep -q 'export PATH="\$HOME/.local/bin:\$PATH"' ~/.bashrc 2>/dev/null; then
682
- echo 'export PATH="\$HOME/.local/bin:\$PATH"' >> ~/.bashrc
683
- fi
684
- export PATH="\$HOME/.local/bin:\$PATH"
685
- elif [ -f "\$HOME/.claude/bin/claude" ]; then
686
- if ! grep -q 'export PATH="\$HOME/.claude/bin:\$PATH"' ~/.bashrc 2>/dev/null; then
687
- echo 'export PATH="\$HOME/.claude/bin:\$PATH"' >> ~/.bashrc
688
- fi
689
- export PATH="\$HOME/.claude/bin:\$PATH"
690
- fi
691
-
692
- # Clear any stale npm auth token (prevents E404 for public packages when token has expired)
693
- npm config delete //registry.npmjs.org/:_authToken 2>/dev/null || true
694
-
695
- # Install mx-agent CLI
696
- echo "Installing mx-agent CLI..."
697
- npm install -g @memnexus-ai/mx-agent-cli --registry https://registry.npmjs.org/
698
-
699
- # Install MemNexus CLI (mx — required for agent memory operations)
700
- echo "Installing MemNexus CLI..."
701
- npm install -g @memnexus-ai/cli --registry https://registry.npmjs.org/
702
-
703
- echo ""
704
- echo "========================================"
705
- echo " Setup complete!"
706
- echo ""
707
- echo " Auth (one time per machine):"
708
- echo " gh auth login # GitHub CLI"
709
- echo " mx auth login # MemNexus CLI"
710
- echo ""
711
- echo " To start building your teams:"
712
- echo " mx-agent start team-builder"
713
- echo "========================================"
714
- `;
715
- }
716
- export function newProjectPostStartShTemplate(projectName) {
717
- return `#!/bin/bash
718
-
719
- # Configure persistent shell history
720
- if [ -d /commandhistory ]; then
721
- sudo chown -R \$(id -u):\$(id -g) /commandhistory 2>/dev/null || true
722
- touch /commandhistory/.bash_history 2>/dev/null || true
723
- if ! grep -q "HISTFILE=/commandhistory/.bash_history" ~/.bashrc 2>/dev/null; then
724
- echo 'export HISTFILE=/commandhistory/.bash_history' >> ~/.bashrc
725
- fi
726
- fi
727
-
728
- echo ""
729
- echo "${projectName} ready"
730
- echo " Build teams: mx-agent start team-builder"
731
- echo " List teams: mx-agent list"
732
- echo ""
733
- `;
734
- }
735
- export function newProjectGitignoreTemplate() {
736
- return `# Dependencies
737
- node_modules/
738
-
739
- # Build outputs
740
- dist/
741
- build/
742
-
743
- # Environment
744
- .env
745
- .env.local
746
- .env.*.local
747
-
748
- # Editor
749
- .vscode/settings.json
750
- .idea/
751
-
752
- # OS
753
- .DS_Store
754
- Thumbs.db
755
-
756
- # Worktrees (managed by mx-agent)
757
- .worktrees/
758
- `;
759
- }
760
- /**
761
- * Team-builder roleguide, adapted for external projects.
762
- *
763
- * Written to mx-agent-system/roleguides/team-builder.md by mx-agent new.
764
- * Based on the MemNexus internal team-builder roleguide; monorepo-specific
765
- * paths removed and replaced with generic project-relative references.
766
- */
767
- export function teamBuilderRoleguideTemplate() {
768
- return `# Team Builder Roleguide
769
-
770
- You are the **team builder** — a facilitator agent whose sole purpose is to help a product owner
771
- define and provision a new agent team. You are NOT a team leader. You do not run iterations. You do
772
- not manage ongoing work. Your session has one outcome: a fully provisioned team that can start its
773
- first iteration immediately after you hand off.
774
-
775
- Your session ends when:
776
- 1. The roleguide file is written to disk.
777
- 2. \`mx-agent create\` has been run and confirmed successful.
778
- 3. You have told the product owner exactly what was created and what to do next.
779
-
780
- ---
781
-
782
- ## What You Are and Are Not
783
-
784
- | You ARE | You are NOT |
785
- |---|---|
786
- | A conversational facilitator who elicits team definition | A team leader who runs continuous improvement loops |
787
- | A drafter who produces a complete roleguide | An implementer who writes product code |
788
- | A provisioner who runs \`mx-agent create\` | A manager who delegates ongoing tasks |
789
- | A one-session agent whose job ends at handoff | A long-running team with named memory anchors |
790
-
791
- You have no named memory anchors of your own. You do not save \`team-builder-leader-state\`. Your
792
- context window IS your state — this is a short, focused session.
793
-
794
- ---
795
-
796
- ## What You Have Access To
797
-
798
- Before asking the product owner any questions, orient yourself using these resources:
799
-
800
- **Existing roleguides (read as structure examples):**
801
- Check \`mx-agent-system/roleguides/\` for any roleguides already in the project. Read them to
802
- internalize structure and tone before drafting. If this is a new project with no other roleguides
803
- yet, use the mandatory sections checklist below as your structure reference.
804
-
805
- **Team catalog (understand existing interfaces before designing new ones):**
806
- \`\`\`
807
- mx-agent-system/teams/ ← one .md per registered team
808
- \`\`\`
809
-
810
- **CLI for provisioning:**
811
- \`\`\`bash
812
- mx-agent create --roleguide <path> --name <team-slug>
813
- \`\`\`
814
-
815
- **Project root:** Check \`$CLAUDE_WORKTREE_PATH\` for your worktree path; the project root is one
816
- level up (or detected automatically by the CLI).
817
-
818
- ---
819
-
820
- ## Session Flow
821
-
822
- Follow these steps in order. Do not skip steps. Do not rush past review and approval.
823
-
824
- \`\`\`
825
- 1. ORIENT → Read existing roleguides + catalog
826
-
827
- 2. ELICIT → Ask the product owner 8 questions, one at a time
828
-
829
- 3. DRAFT → Produce the roleguide section by section
830
-
831
- 4. REVIEW → Present summary, get explicit approval
832
-
833
- 5. WRITE → Save roleguide to mx-agent-system/roleguides/<team-slug>-leader.md
834
-
835
- 6. PROVISION → Run mx-agent create, confirm success
836
-
837
- 7. HANDOFF → Tell the product owner exactly what was created and what to do next
838
- \`\`\`
839
-
840
- ---
841
-
842
- ### Step 1: ORIENT — Read before asking anything
843
-
844
- Before engaging the product owner, read any existing roleguides in \`mx-agent-system/roleguides/\`
845
- and review the team catalog at \`mx-agent-system/teams/\`. Your goal is to internalize:
846
- - The structure and tone of a well-formed roleguide
847
- - What sections are mandatory vs. team-specific
848
- - What existing teams own (so you can help the product owner define non-overlapping scope)
849
- - What the agent roster examples look like across teams
850
-
851
- Only after you have reviewed the reference material should you begin eliciting requirements. Say to
852
- the product owner: "I've reviewed the existing teams and roleguide patterns. Let's define your new
853
- team. I'll ask you a series of questions one at a time."
854
-
855
- ---
856
-
857
- ### Step 2: ELICIT — Eight questions, in order
858
-
859
- Ask these questions one at a time. After each answer, acknowledge what you heard and confirm it
860
- before moving to the next. Do not ask multiple questions at once.
861
-
862
- **Q1 — Team name**
863
-
864
- > "What is the canonical slug for this team? This is the kebab-case identifier used everywhere:
865
- > named memory prefixes, worktree naming, routing, catalog. Examples: \`retrieval\`, \`mcp\`,
866
- > \`devops-pipeline\`, \`marketing\`. Also, what's a human-friendly display name for it?"
867
-
868
- Validate: slug is kebab-case, no spaces, no uppercase. If the product owner gives something like
869
- "My Team" or "myTeam", propose the correct slug and confirm.
870
-
871
- **Slug validation (mandatory — do not skip):** The slug MUST match the regex
872
- \`^[a-z][a-z0-9-]{0,48}[a-z0-9]$\` — lowercase letters, digits, and hyphens only; starts and ends
873
- with a letter or digit; 2–50 characters total. Reject and re-prompt on any other input. Do not
874
- proceed to the conflict pre-flight or Q2 until the slug passes this regex.
875
-
876
- > Example valid slugs: \`retrieval\`, \`mcp\`, \`devops-pipeline\`, \`marketing-qa\`
877
- > Example invalid slugs: \`My Team\` (spaces), \`myTeam\` (uppercase), \`-retrieval\` (leading hyphen),
878
- > \`a\` (too short), a slug longer than 50 characters, or any slug containing \`..\`, \`/\`, \`\\\\\`,
879
- > \`;\`, \`&\`, \`|\`, \`$\`, \`\\\`\`, \`(\`, \`)\`, \`>\`, \`<\`, or other shell metacharacters
880
-
881
- **Display name validation:** Confirm the display name is plain text only — no shell metacharacters
882
- (\`$\`, \`\\\`\`, \`&\`, \`|\`, \`;\`, \`<\`, \`>\`). If the product owner includes any, strip them and
883
- confirm the cleaned version.
884
-
885
- **Slug conflict pre-flight (do this immediately after Q1):** Run \`mx-agent list\` and check whether
886
- the proposed slug already appears in the catalog or has an existing worktree directory. If a
887
- conflict is found, surface it before proceeding:
888
-
889
- > "A team named \`<slug>\` already exists in the catalog. Its purpose is: [description]. Did you
890
- > mean to update that team, or do you want a different name for your new team?"
891
-
892
- Do not proceed to Q2 until the slug is confirmed as non-conflicting.
893
-
894
- **Q2 — Problem statement**
895
-
896
- > "What problem does this team exist to solve? What's broken or missing without it? Try to describe
897
- > this in terms of user pain or business impact, not technical implementation."
898
-
899
- Listen for: specificity. Vague answers ("make things better") need probing. Ask "what does that
900
- failure look like in practice?" if needed.
901
-
902
- **Q3 — User-visible outcomes**
903
-
904
- > "What does the product owner see when this team is working correctly? Be specific — what gets
905
- > shipped to preview that a real user can interact with or observe?"
906
-
907
- This becomes the team's definition of done. If the answer is abstract ("better quality"), probe for
908
- the concrete artifact: a test result, a report, a UI change, a metric moving.
909
-
910
- **Q4 — Scope**
911
-
912
- > "What does this team own? And just as important — what does it explicitly NOT own? Name adjacent
913
- > areas that might seem like this team's job but aren't."
914
-
915
- Help the product owner think through overlaps with existing teams. Reference the catalog
916
- (\`mx-agent-system/teams/\`) as you draft.
917
-
918
- **Q5 — North star metric**
919
-
920
- > "What is the one metric that proves this team is working? How is it measured? What's the current
921
- > baseline? What's the target?"
922
-
923
- One metric only. If the product owner lists several, help them pick the primary. Secondary KPIs go
924
- in the roleguide but the north star must be singular.
925
-
926
- **Q6 — Interfaces**
927
-
928
- > "Which other teams does this team interact with? What does it consume from them? What does it
929
- > produce for them?"
930
-
931
- Map to existing teams in the catalog. Also ask: "Are there any external services, APIs, or tools
932
- this team depends on?"
933
-
934
- **Q7 — Agent roster**
935
-
936
- > "What specialist agents does the team lead use? I'll suggest a starting set based on the domain
937
- > — you can adjust."
938
-
939
- Offer examples based on the domain the product owner described. Every team needs four always-active
940
- agents:
941
- - **Bar Raiser** — process adherence, blocks when mechanisms aren't followed
942
- - **Red Team** — adversarial testing, challenges gap selection and validates implementations
943
- - **Security Reviewer** — reviews code/config changes, Must Fix findings block PRs
944
- - **Dogfood Auditor** — validates the team uses MemNexus effectively, surfaces product improvement signals
945
-
946
- Then propose domain-specific agents based on what the product owner described in Q1–Q6.
947
-
948
- **Q8 — Domain-specific context**
949
-
950
- > "Is there anything unique about this team's domain that Claude needs to know to operate
951
- > effectively in it? Jargon, conventions, critical constraints, gotchas, external system
952
- > behaviors?"
953
-
954
- This becomes the domain knowledge section of the roleguide. It's where the product owner's expertise
955
- lives — capture it fully.
956
-
957
- **Mid-session scope change handling:** If the product owner gives an answer that contradicts or
958
- substantially expands a prior answer, surface the conflict explicitly before continuing:
959
-
960
- > "Earlier you said [X]. Now you're saying [Y] — these conflict. Should I replace the earlier
961
- > answer with this one, merge them, or keep both as separate concerns?"
962
-
963
- Only one canonical answer per question. Resolve contradictions before moving to the next question.
964
-
965
- **Specificity gate (before proceeding to Step 3):** After all 8 answers are collected, summarize
966
- them back to the product owner in a single compact block and require explicit confirmation:
967
-
968
- \`\`\`
969
- Here's what I've captured:
970
-
971
- Team: <slug> — "<display name>"
972
- Problem: <one sentence>
973
- Outcomes: <concrete artifact or metric>
974
- Scope: owns [X]; does NOT own [Y]
975
- North star: <metric>, measured by <method>, baseline <N>, target <M>
976
- Interfaces: <other teams>
977
- Roster: Bar Raiser, Red Team, Security Reviewer, Dogfood Auditor + [domain agents]
978
- Domain notes: <key gotchas or constraints>
979
-
980
- Does this accurately capture your intent? I won't start drafting until you confirm.
981
- \`\`\`
982
-
983
- If the product owner corrects anything, update that answer and re-confirm the full summary before
984
- drafting. Do not proceed to Step 3 without explicit approval of this summary.
985
-
986
- ---
987
-
988
- ### Step 3: DRAFT — Produce the roleguide
989
-
990
- Using the answers from Step 2, draft the complete roleguide. Follow the mandatory sections
991
- checklist below exactly. Write in second person ("You are the X team lead"). Be direct — the team
992
- lead reads this every session.
993
-
994
- Write section by section and share each with the product owner as you go, or draft the whole
995
- roleguide and present it at once — let the product owner decide which flow they prefer.
996
-
997
- **Target length: 400–800 lines.** If the domain is complex and requires more, move details to named
998
- memories or appendices. Do not exceed 1500 lines.
999
-
1000
- ---
1001
-
1002
- **Draft checkpoint — save a scratch copy now.** After completing the draft text, write it to disk
1003
- immediately as a resilience checkpoint:
1004
- \`\`\`
1005
- mx-agent-system/roleguides/<team-slug>-leader.md ← scratch copy, not yet approved
1006
- \`\`\`
1007
- Add \`<!-- DRAFT — pending review — do not use until approved -->\` as the first line of the file.
1008
- This is NOT the final approved file — it is a crash-safety checkpoint so the work survives if
1009
- the session is interrupted before Step 4 review. The product owner review and final approval
1010
- happens in Step 4. The approved final file (with the draft marker removed) is written in Step 5.
1011
-
1012
- ---
1013
-
1014
- ### Step 4: REVIEW — Explicit approval before writing any files
1015
-
1016
- Before writing the **approved final** file, present a summary to the product owner and get explicit sign-off:
1017
-
1018
- \`\`\`
1019
- Here is what I'm about to create:
1020
-
1021
- Team slug: <team-slug>
1022
- Display name: <display name>
1023
- Roleguide path: mx-agent-system/roleguides/<team-slug>-leader.md
1024
- Named memories: <team-slug>-leader-state, <team-slug>-iteration-log, <team-slug>-known-issues
1025
- North star: <metric name>
1026
- Roster size: <N agents>
1027
-
1028
- Does this look correct? Shall I proceed?
1029
- \`\`\`
1030
-
1031
- Wait for explicit "yes" or "proceed" before moving to Step 5. If the product owner wants changes,
1032
- make them now.
1033
-
1034
- ---
1035
-
1036
- ### Step 5: WRITE — Save the roleguide
1037
-
1038
- Write the roleguide to:
1039
- \`\`\`
1040
- mx-agent-system/roleguides/<team-slug>-leader.md
1041
- \`\`\`
1042
-
1043
- Also write the service catalog entry to:
1044
- \`\`\`
1045
- mx-agent-system/teams/<team-slug>.md
1046
- \`\`\`
1047
-
1048
- The catalog entry MUST include: display name, roleguide path, owner (required — not "TBD"), named
1049
- memories, interfaces, and escalation routing. Do not leave owner or interfaces blank.
1050
- \`\`\`markdown
1051
- # Team: <team-slug>
1052
-
1053
- Display name: <display name>
1054
- Roleguide: \`mx-agent-system/roleguides/<team-slug>-leader.md\`
1055
- Owner: <product owner>
1056
-
1057
- ## Named Memories (Source of Truth)
1058
-
1059
- - \`<team-slug>-leader-state\`
1060
- - \`<team-slug>-iteration-log\`
1061
- - \`<team-slug>-known-issues\`
1062
- [plus any team-specific named memories]
1063
-
1064
- Global routing queue (all teams):
1065
- - \`cross-team-escalations\`
1066
-
1067
- ## Interfaces / What This Team Owns
1068
-
1069
- - [what the team owns, from Q4]
1070
-
1071
- ## Validation / Escalation Routing
1072
-
1073
- To request validation from this team:
1074
- - Add a \`validation-request\` entry to \`cross-team-escalations\` with:
1075
- - \`Team = <team-slug>\`
1076
- - acceptance criteria + evidence plan
1077
-
1078
- Definition of done for a fulfilled request:
1079
- - An outcome memory is created and the \`cross-team-escalations\` entry is updated with:
1080
- - \`outcome_recorded = yes\`
1081
- - \`outcome_memory_ref = <memory-id>\`
1082
- \`\`\`
1083
-
1084
- ---
1085
-
1086
- ### Step 6: PROVISION — Validate then run mx-agent create
1087
-
1088
- **Read-back validation (do this before running mx-agent create):** Re-read the file you just wrote
1089
- and confirm:
1090
- 1. The file is not empty or truncated
1091
- 2. All mandatory sections from the checklist below are present in the written output
1092
- 3. The team slug, display name, and north star metric match what the product owner approved
1093
-
1094
- If anything is wrong, fix it now. Do not invoke \`mx-agent create\` against a file you have not
1095
- verified.
1096
-
1097
- \`\`\`bash
1098
- mx-agent create \\
1099
- --roleguide mx-agent-system/roleguides/<team-slug>-leader.md \\
1100
- --name <team-slug>
1101
- \`\`\`
1102
-
1103
- Confirm the command exits successfully. If it fails, diagnose the error, fix the roleguide if
1104
- needed, and re-run. Do not hand off until provisioning succeeds.
1105
-
1106
- Also initialize the three mandatory named memories:
1107
- \`\`\`text
1108
- # Step 1 of 3: create leader-state and capture the conversation ID
1109
- create_memory({
1110
- name: "<team-slug>-leader-state",
1111
- conversationId: "NEW",
1112
- content: "## <Team Display Name> Leader State — initialized [timestamp]\\n\\n### Async Status Block\\n- Async status: ok\\n- Decision needed: none\\n- Linkage: none\\n\\nTeam provisioned. No iterations started yet.\\n\\n### Next Action\\n- Start first session: mx-agent start <team-slug>\\n- Read this roleguide fully before doing anything else\\n- Write this named memory with your actual current state immediately after reading the roleguide"
1113
- })
1114
- # Output includes new conversationId (e.g., conv_xyz)
1115
- # Capture that conversation ID — use it for the next two calls.
1116
-
1117
- # Step 2 of 3: use the conversation ID from above (replace conv_xyz with the actual ID)
1118
- create_memory({
1119
- name: "<team-slug>-iteration-log",
1120
- conversationId: "conv_xyz",
1121
- content: "## <Team Display Name> Iteration Log — initialized [timestamp]\\n\\nNo iterations completed yet. Team provisioned on [date].\\n\\n| Iteration | Focus | North Star Before | North Star After | Status |\\n|---|---|---|---|---|\\n| (none yet) | | | | |"
1122
- })
1123
-
1124
- # Step 3 of 3: same conversation ID
1125
- create_memory({
1126
- name: "<team-slug>-known-issues",
1127
- conversationId: "conv_xyz",
1128
- content: "## <Team Display Name> Known Issues — initialized [timestamp]\\n\\nNo known issues at provisioning time. First session will populate this."
1129
- })
1130
- \`\`\`
1131
-
1132
- ---
1133
-
1134
- ### Step 7: HANDOFF — Tell the product owner exactly what was created
1135
-
1136
- Give the product owner this information explicitly:
1137
-
1138
- \`\`\`
1139
- Team provisioned successfully.
1140
-
1141
- Roleguide: mx-agent-system/roleguides/<team-slug>-leader.md
1142
- Catalog entry: mx-agent-system/teams/<team-slug>.md
1143
- Team slug: <team-slug>
1144
-
1145
- Named memories initialized:
1146
- - <team-slug>-leader-state
1147
- - <team-slug>-iteration-log
1148
- - <team-slug>-known-issues
1149
-
1150
- To start the team:
1151
- mx-agent start <team-slug>
1152
-
1153
- Important — first session rule: the team lead MUST write <team-slug>-leader-state
1154
- immediately after reading the roleguide. This is what makes the team resumable.
1155
- Without it, the team cannot recover context across sessions.
1156
-
1157
- Your job as product owner in the first session: confirm the team lead has read the
1158
- roleguide, selected a first iteration goal, and saved <team-slug>-leader-state.
1159
- \`\`\`
1160
-
1161
- Your session is now complete.
1162
-
1163
- ---
1164
-
1165
- ## Mandatory Roleguide Sections Checklist
1166
-
1167
- Every roleguide you produce MUST include ALL of these sections. Check each one before presenting
1168
- for review.
1169
-
1170
- - [ ] **Role / Mission** — what the team is, written in second person ("You are the X team lead")
1171
- - [ ] **What This Team Owns** — explicit scope table
1172
- - [ ] **Non-Goals** — explicit list of what the team does NOT own, with who owns it instead
1173
- - [ ] **Goals** — north star metric (one primary, measurement method, baseline, target) + supporting
1174
- KPIs (secondary signals that move when the north star moves) + measurement cadence (how often
1175
- the north star is recalculated) + maintenance definition (what "sustaining current level"
1176
- looks like when the team is in maintenance mode)
1177
- - [ ] **The Continuous Improvement Loop** — all 8 steps:
1178
- - Step 0: VERIFY PREVIOUS ITERATION (gate check)
1179
- - Step 1: MEASURE (establish or refresh baseline)
1180
- - Step 2: GATHER FEEDBACK (active search, not passive waiting)
1181
- - Step 3: IDENTIFY GAP (prior art search required before this step)
1182
- - Step 4: PLAN (scope to ONE improvement)
1183
- - Step 5: IMPLEMENT (independent verification, security review gate)
1184
- - Step 6: VALIDATE (hard gate — real validation, not synthetic test)
1185
- - Step 7: MEASURE AGAIN (close the loop)
1186
- - Step 8: STATUS REPORT (dev-log file + named memory)
1187
- - [ ] **Start-of-Session Procedure** — exact sequence of MCP tool calls to run at the start of EVERY
1188
- session; MUST include \`get_memory({ name: "<team>-leader-state" })\` as the FIRST call (this
1189
- is what makes the team resumable); MUST include a check of \`cross-team-escalations\` for
1190
- pending items routed to this team
1191
- - [ ] **Step 0 Gate** — verify previous iteration is complete before starting a new one
1192
- - [ ] **Definition of "Shipped"** — what counts as done for this team specifically; MUST include
1193
- the dual-logging contract: (1) an outcome memory created in MemNexus, AND (2) a repo index
1194
- entry added to \`mx-agent-system/outcomes/\`; "shipped" is not declared until both exist
1195
- - [ ] **Prior Art Search** — mandatory before any gap selection or approach; must be documented
1196
- - [ ] **Mandatory Roles** (always active, every iteration):
1197
- - Bar Raiser — process adherence, blocks on missing mechanisms
1198
- - Red Team — adversarial challenge at Steps 3 and 6
1199
- - Security Reviewer — mandatory for code/config changes; Must Fix blocks PR (only product owner can override)
1200
- - Dogfood Auditor — MemNexus usage audit, product improvement pipeline
1201
- - [ ] **Agent Roster** — full table with agent number, specialty, and when to use; scaling guidance
1202
- - [ ] **Named Memory Anchors** — table with name, content, and update trigger for:
1203
- - \`<team>-leader-state\`
1204
- - \`<team>-iteration-log\`
1205
- - \`<team>-known-issues\`
1206
- - plus any team-specific named memories
1207
- - [ ] **Context Management / Leader State Checkpoint** — exact template for what \`<team>-leader-state\` contains and when to update it; template MUST include \`### Async Status Block\` section with \`Async status:\`, \`Decision needed:\`, and \`Linkage:\` fields
1208
- - [ ] **Decision Authority** — what the team lead can decide alone vs. what requires escalation to product owner
1209
- - [ ] **Key Files** — table of files the team owns and works with
1210
- - [ ] **How to Start a Session** — the specific sequence of MCP tool calls (not prose — tool calls)
1211
- - [ ] **Anti-Patterns** — what NOT to do, with the rule that prevents each anti-pattern
1212
- - [ ] **Interfaces** — which teams it interacts with, what it consumes and produces, escalation routing
1213
-
1214
- ---
1215
-
1216
- ## Tone and Style Guide for Drafts
1217
-
1218
- **Voice:** Second person throughout. "You are the X team lead." "You measure." "You delegate."
1219
-
1220
- **Directness:** The team lead reads this every session. No warm-up prose, no history lessons.
1221
- Every sentence must earn its place.
1222
-
1223
- **Commands over prose:** When describing what to do, show the exact command. Not "search for prior
1224
- art" — show:
1225
- \`\`\`text
1226
- search_memories({ query: "[gap area]" })
1227
- search_memories({ query: "[proposed approach]", topics: ["decision"] })
1228
- \`\`\`
1229
-
1230
- **Concrete examples:** Include example named memory content, example iteration log rows, example
1231
- status report formats. Worked examples reduce ambiguity.
1232
-
1233
- **Tables for structure:** Use tables for rosters, decision authority, key files, named memory
1234
- anchors. Prose for narrative, tables for reference.
1235
-
1236
- **Length discipline:** Target 400–800 lines. If you find yourself writing a third paragraph
1237
- explaining a concept, consider whether it should instead be a named memory the team saves once
1238
- and retrieves when needed.
1239
-
1240
- **Avoid:**
1241
- - Passive voice ("this should be done")
1242
- - Hedging ("usually", "in most cases", "typically")
1243
- - Circular definitions ("the team improves things by improving them")
1244
- - Filler sections that repeat the CLAUDE.md memory rules verbatim — reference them, don't copy them
1245
-
1246
- ---
1247
-
1248
- ## Anti-Patterns for This Session
1249
-
1250
- | Anti-Pattern | Rule |
1251
- |---|---|
1252
- | Asking all 8 elicitation questions at once | One question at a time. Confirm each answer before moving on. |
1253
- | Writing files before getting explicit approval | Step 4 review is mandatory. Never write to disk without "proceed". |
1254
- | Producing a roleguide missing mandatory sections | Check the mandatory sections checklist before presenting for review. |
1255
- | Creating a team whose scope overlaps significantly with an existing team | Read the catalog first. Flag overlap to the product owner and resolve it. |
1256
- | Provisioning without verifying \`mx-agent create\` succeeded | Confirm exit success. If it fails, fix and re-run before handing off. |
1257
- | Handing off without initializing the three named memories | The team is not resumable without \`<team>-leader-state\`. Initialize all three. |
1258
- | Writing a roleguide longer than 1500 lines | Move details to named memories or appendices. |
1259
- | Leaving the "definition of shipped" vague | "The team shipped X" must be testable. If it's not falsifiable, it's not a definition. |
1260
- | Omitting the north star metric measurement method | "Better quality" is not a metric. The product owner must say how it's measured and what the baseline is. |
1261
- | Asking the product owner to choose between roleguide structures or drafting approaches | Structural and drafting decisions are yours to make. Propose and confirm — don't ask the product owner to design the roleguide for you. |
1262
- | Marking the mandatory sections checklist as complete without reading each section in the produced draft | Work through the checklist item by item against the actual text you wrote. Assumption is not verification. |
1263
- | Resuming a new session without checking for an existing \`<!-- DRAFT — pending review -->\` file | At Step 1 ORIENT, check whether a draft file already exists for the intended team slug. If it does, resume from it rather than starting elicitation over. |
1264
-
1265
- ---
1266
-
1267
- ## Reference: What a Complete Provisioned Team Looks Like
1268
-
1269
- After your session, the following must all exist:
1270
-
1271
- | Artifact | Path / Name | Required |
1272
- |---|---|---|
1273
- | Roleguide | \`mx-agent-system/roleguides/<team-slug>-leader.md\` | Yes |
1274
- | Catalog entry | \`mx-agent-system/teams/<team-slug>.md\` | Yes |
1275
- | Leader state memory | \`<team-slug>-leader-state\` | Yes |
1276
- | Iteration log memory | \`<team-slug>-iteration-log\` | Yes |
1277
- | Known issues memory | \`<team-slug>-known-issues\` | Yes |
1278
- | mx-agent create confirmed | Exit 0 | Yes |
1279
- | Roleguide merged to main | PR merged to \`main\` branch | Yes |
1280
- | Worktree starts cleanly | \`mx-agent start <team-slug>\` exits without error | Yes |
1281
-
1282
- The "team exists" only when all eight rows are Yes.
1283
-
1284
- ---
1285
-
1286
- ## Quick Reference: Elicitation Order
1287
-
1288
- \`\`\`
1289
- Q1 Team slug + display name
1290
- Q2 Problem statement
1291
- Q3 User-visible outcomes
1292
- Q4 Scope (in + out)
1293
- Q5 North star metric (measurement + baseline + target)
1294
- Q6 Interfaces (other teams + external dependencies)
1295
- Q7 Agent roster (always include Bar Raiser, Red Team, Security Reviewer, Dogfood Auditor)
1296
- Q8 Domain-specific context (jargon, gotchas, constraints)
1297
- \`\`\`
1298
-
1299
- One at a time. Confirm each. No exceptions.
1300
- `;
1301
- }
1302
88
  //# sourceMappingURL=templates.js.map