@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.
- package/dist/__tests__/claude-sync.test.js +20 -136
- package/dist/__tests__/claude-sync.test.js.map +1 -1
- package/dist/commands/create.d.ts.map +1 -1
- package/dist/commands/create.js +18 -137
- package/dist/commands/create.js.map +1 -1
- package/dist/commands/init.d.ts +2 -12
- package/dist/commands/init.d.ts.map +1 -1
- package/dist/commands/init.js +21 -70
- package/dist/commands/init.js.map +1 -1
- package/dist/commands/list.d.ts +0 -1
- package/dist/commands/list.d.ts.map +1 -1
- package/dist/commands/list.js +9 -39
- package/dist/commands/list.js.map +1 -1
- package/dist/commands/start.d.ts.map +1 -1
- package/dist/commands/start.js +18 -225
- package/dist/commands/start.js.map +1 -1
- package/dist/commands/update.d.ts.map +1 -1
- package/dist/commands/update.js +15 -28
- package/dist/commands/update.js.map +1 -1
- package/dist/index.js +1 -16
- package/dist/index.js.map +1 -1
- package/dist/lib/claude.d.ts +4 -15
- package/dist/lib/claude.d.ts.map +1 -1
- package/dist/lib/claude.js +44 -331
- package/dist/lib/claude.js.map +1 -1
- package/dist/lib/memory.d.ts +6 -1
- package/dist/lib/memory.d.ts.map +1 -1
- package/dist/lib/memory.js +11 -8
- package/dist/lib/memory.js.map +1 -1
- package/dist/lib/project-config.d.ts +7 -7
- package/dist/lib/project-config.d.ts.map +1 -1
- package/dist/lib/project-config.js +6 -3
- package/dist/lib/project-config.js.map +1 -1
- package/dist/lib/templates.d.ts +1 -39
- package/dist/lib/templates.d.ts.map +1 -1
- package/dist/lib/templates.js +25 -1239
- package/dist/lib/templates.js.map +1 -1
- package/dist/lib/worktree.d.ts +1 -19
- package/dist/lib/worktree.d.ts.map +1 -1
- package/dist/lib/worktree.js +4 -55
- package/dist/lib/worktree.js.map +1 -1
- package/package.json +2 -3
- package/README.md +0 -104
- package/dist/commands/new.d.ts +0 -30
- package/dist/commands/new.d.ts.map +0 -1
- package/dist/commands/new.js +0 -150
- package/dist/commands/new.js.map +0 -1
package/dist/lib/templates.js
CHANGED
|
@@ -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
|
-
'
|
|
43
|
-
'
|
|
44
|
-
'
|
|
45
|
-
'
|
|
46
|
-
'
|
|
47
|
-
'
|
|
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
|
|
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
|
|
93
|
-
'Bash(git
|
|
94
|
-
'Bash(git
|
|
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
|
-
#
|
|
171
|
-
#
|
|
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
|
-
|
|
184
|
-
|
|
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
|
-
|
|
198
|
-
if [[ -z "$WORKTREE_PATH" ]]; then
|
|
45
|
+
if [[ "\$TOOL_NAME" != "Bash" ]]; then
|
|
199
46
|
exit 0
|
|
200
47
|
fi
|
|
201
48
|
|
|
202
|
-
#
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
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
|
|
303
|
-
if echo "
|
|
304
|
-
echo ""
|
|
305
|
-
|
|
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
|