claude-multi-session 2.5.0 → 2.5.1

package/bin/setup.js

@@ -43,6 +43,10 @@ const CLAUDE_MD_END_MARKER = '<!-- claude-multi-session:end -->';
 
 // This teaches the main Claude session how to orchestrate team workers.
 // Wrapped in markers so we can find and remove it later.
+//
+// IMPORTANT: This content MUST stay in sync with docs/ORCHESTRATOR-CLAUDE.md.
+// When updating rules or adding features, update BOTH files.
+// Failure to sync caused all test runs 1-6 to use stale orchestrator rules.
 const STRATEGY_CONTENT = `
 ${CLAUDE_MD_START_MARKER}
 
@@ -52,11 +56,39 @@ You have access to a Multi-Session MCP server (\`mcp__multi-session__*\` tools)
 
 IMPORTANT: When the user asks you to build something complex (more than 2 related tasks), use the multi-session system to parallelize the work instead of doing everything yourself.
 
+## Step 0: Verify Your Tools
+
+Before starting ANY orchestration work, call \`server_version()\` to verify you're running the latest MCP tools. If the response shows a version mismatch, tell the user to restart Claude Code before proceeding — stale tools cause phantom failures.
+
+## How to Orchestrate
+
+### Rule 0: Define shared conventions BEFORE spawning workers
+Before spawning workers, fill in the CONVENTION CHECKLIST. Either publish as an artifact (\`shared-conventions\`) or embed in every worker's prompt.
+
+=== CONVENTION CHECKLIST (define every item before spawning) ===
+- [ ] Response format: e.g., \`{ data: <result> }\`
+- [ ] Error format: e.g., \`{ error: <message> }\`
+- [ ] Status codes: create=201, read=200, update=200, delete=200, notFound=404, badRequest=400, conflict=409
+- [ ] Naming: e.g., snake_case for DB columns, camelCase for JS variables
+- [ ] File paths: relative only, never absolute
+- [ ] Enum/status values: list EXACT strings (e.g., "pending", "in_progress", "completed" — NOT "Pending" or "InProgress")
+- [ ] Boolean handling: true/false vs 1/0 — pick one, specify it
+- [ ] Date format: ISO 8601 strings, Unix timestamps, or other — specify which
+- [ ] Audit/log action names: exact strings (e.g., "created" vs "create" vs "CREATE")
+- [ ] Shared column names: list exact DB column names for tables multiple workers reference
+
+Missing even ONE item causes convention mismatches that the orchestrator then has to fix manually — which violates Rule 6.
+
+NEVER assume workers will independently agree on conventions — they won't.
+
 ### Rule 1: You are the ORCHESTRATOR — not the implementer
 - Plan the work, spawn workers, monitor progress
 - Do NOT implement code yourself when you can delegate
+- Do NOT create project foundation files (package.json, db.js, app.js, server.js) yourself — spawn a setup worker for Phase 0
 - Do NOT read full outputs from workers — check artifacts and contract status instead
 
+**Phase 0: Foundation Setup** — If the project needs shared infrastructure (database, app skeleton, package.json), spawn a \`setup\` worker FIRST. Wait for its \`project-foundation\` artifact before spawning other workers. Do NOT create these files yourself.
+
 ### Rule 2: Use team_spawn for multi-session work
 IMPORTANT: Spawn ALL independent workers in a SINGLE message with multiple tool calls. This makes them run in parallel.
 
@@ -64,10 +96,36 @@ IMPORTANT: Spawn ALL independent workers in a SINGLE message with multiple tool
 - Workers have team_ask, team_send_message, team_broadcast tools
 - They can publish and read artifacts directly
 - You should NOT relay messages between them
+- If workers need each other's output, tell them to use team_ask
+- Note: team_ask is a **fallback** for unexpected ambiguity. In well-orchestrated projects where you provide all context upfront, team_ask may never be called — this is the ideal case.
+
+### Rule 4: Post-Phase Verification (MANDATORY)
+After ALL workers in a phase complete, BEFORE spawning the next phase, STOP and fill in this checklist:
+
+=== PHASE GATE CHECKPOINT (fill in before EVERY team_spawn after Phase 0) ===
+
+Phase completing: ___  →  Phase starting: ___
+
+1. \`artifact_list()\`
+   Expected artifacts: [___]
+   All present? YES / NO
+
+2. \`artifact_get({ artifactId: "___", reader: "orchestrator" })\`
+   Content valid and complete? YES / NO
+
+3. \`team_roster()\`
+   All previous-phase workers idle? YES / NO
+
+4. \`artifact_readers({ artifactId: "___" })\`
+   All expected consumers listed? YES / NO
+
+PROCEED ONLY IF all answers are YES.
+If any is NO → diagnose and fix before continuing.
+
+Count your phases upfront. If you have N phases, fill in this checkpoint exactly N-1 times (between every adjacent pair of phases). Skipping verification for later phases is the #1 cause of test failures.
 
-### Rule 4: Monitor without micromanaging
-Use \`team_roster()\`, \`contract_list()\`, \`artifact_list()\` to check progress.
-Only intervene when a session is BLOCKED or FAILED.
+Only intervene in workers when a session is BLOCKED or FAILED.
+Do NOT verify worker output by reading files directly — check artifacts instead.
 
 ### Rule 5: Always tell workers to publish artifacts
 Every worker prompt should include instructions to:
@@ -76,16 +134,54 @@ Every worker prompt should include instructions to:
 3. Publish output as artifacts (\`artifact_publish\`)
 4. Broadcast completion (\`team_broadcast\`)
 5. Update status to idle when done (\`team_update_status\`)
+6. Follow shared conventions defined in Rule 0 (include them in the prompt or reference the conventions artifact)
+
+### Rule 6: Don't fix worker code yourself (pragmatic exception for trivial fixes)
+
+=== FIX PROTOCOL (when you must fix worker code directly) ===
+STOP. Before editing any file a worker created, answer these questions:
+
+1. Is this fix ≤ 3 lines?
+   NO → \`send_message\` to worker or spawn fix-worker. Do NOT fix yourself.
+   YES → continue to step 2.
+
+2. Is the worker done (idle status in \`team_roster\`)?
+   NO → \`send_message\` to worker. Do NOT fix yourself.
+   YES → continue to step 3.
+
+3. Make the fix.
+
+4. Broadcast: \`team_broadcast({ from: "orchestrator", content: "Fixed [file]:[lines] — [description of change]" })\`
+
+5. Re-publish: If the fix changes data in a published artifact, call \`artifact_publish\` to update it.
+
+NEVER skip steps 4-5. Unannounced fixes cause downstream workers to use stale assumptions.
+
+If the failure is due to convention mismatch (wrong response format, etc.), that's YOUR fault — update the conventions and notify the affected workers.
+
+### Rule 7: Verify artifacts between phases (Phase Gates)
+Use the PHASE GATE CHECKPOINT from Rule 4 between every pair of phases. This is the same checklist — Rule 7 reinforces that it applies to EVERY phase transition, not just the first one.
+
+After all workers finish, verify they consumed shared artifacts:
+\`\`\`
+mcp__multi-session__artifact_readers({ artifactId: "shared-conventions" })
+\`\`\`
+This shows which workers actually read the conventions. If a worker is missing, they may have ignored the shared contract.
+
+NEVER trust a worker's self-reported completion — verify the artifact exists yourself.
+
+## Quick Reference
 
-### Quick Reference
 | You want to... | Use this tool |
 |----------------|---------------|
-| Multi-person project (3+ tasks) | \`team_spawn\` (multiple in parallel) |
-| Single isolated task | \`delegate_task\` |
-| Check who's working | \`team_roster\` |
+| Verify tools before starting | \`server_version\` |
+| Build a multi-person project | \`team_spawn\` (multiple in parallel) |
+| Run a single isolated task | \`delegate_task\` |
+| Check who's working on what | \`team_roster\` |
 | See published outputs | \`artifact_list\` |
-| Task completion status | \`contract_list\` |
-| Send correction to worker | \`send_message\` to that session |
+| See task completion status | \`contract_list\` |
+| Send a correction to a worker | \`send_message\` to that session |
+| Check who read an artifact | \`artifact_readers\` |
 
 ### When NOT to Delegate
 - Simple tasks (< 5 min, < 3 files) — do it yourself
@@ -305,8 +401,27 @@ function addGuide(scope) {
     existing = fs.readFileSync(claudeMdPath, 'utf-8');
   }
 
-  // Check if our section already exists (avoid duplicates)
+  // Check if our section already exists
   if (existing.includes(CLAUDE_MD_START_MARKER)) {
+    // Extract current content between markers and compare with latest
+    const startIdx = existing.indexOf(CLAUDE_MD_START_MARKER);
+    const endIdx = existing.indexOf(CLAUDE_MD_END_MARKER);
+    if (startIdx !== -1 && endIdx !== -1) {
+      const currentContent = existing.slice(startIdx, endIdx + CLAUDE_MD_END_MARKER.length).trim();
+      const newContent = STRATEGY_CONTENT.trim();
+      if (currentContent === newContent) {
+        result.skipped = true;
+        return result;
+      }
+      // Content is stale — replace our section, preserve user's other content
+      const before = existing.slice(0, startIdx).trimEnd();
+      const after = existing.slice(endIdx + CLAUDE_MD_END_MARKER.length).trimStart();
+      const updated = (before ? before + '\n\n' : '') + newContent + (after ? '\n\n' + after : '\n');
+      fs.writeFileSync(claudeMdPath, updated, 'utf-8');
+      result.updated = true;
+      return result;
+    }
+    // Malformed markers — skip to be safe
     result.skipped = true;
     return result;
   }
@@ -410,10 +525,15 @@ function runPostinstallHint() {
       write('  Run "cms-setup" to configure orchestrator guide.');
       write('');
     } else {
-      // Already registered — just print a hint
+      // Already registered — check if CLAUDE.md guide needs updating
       write('');
-      write('  claude-multi-session: Already configured.');
-      write('  Run "cms-setup" to reconfigure or "cms-setup --uninstall" to remove.');
+      const guideResult = addGuide('global');
+      if (guideResult.updated) {
+        write('  claude-multi-session: Orchestrator guide updated in ~/.claude/CLAUDE.md');
+        write('  Restart Claude Code to use the latest rules.');
+      } else {
+        write('  claude-multi-session: Already configured and up to date.');
+      }
       write('');
     }
   } catch {
@@ -563,9 +683,19 @@ async function runInteractiveSetup(flags) {
   if (wantGuide === null) {
     // Tell the user what will happen before they confirm
     if (guideAlreadyInjected) {
-      // Already there — no need to ask
-      clack.log.info(`Orchestrator guide already in ${guideDisplayPath} — nothing to do.`);
-      wantGuide = false;
+      // Check if content is stale
+      const currentFile = fs.readFileSync(guideTargetPath, 'utf-8');
+      const startIdx = currentFile.indexOf(CLAUDE_MD_START_MARKER);
+      const endIdx = currentFile.indexOf(CLAUDE_MD_END_MARKER);
+      const currentContent = currentFile.slice(startIdx, endIdx + CLAUDE_MD_END_MARKER.length).trim();
+      const isStale = currentContent !== STRATEGY_CONTENT.trim();
+      if (isStale) {
+        clack.log.warn(`Orchestrator guide in ${guideDisplayPath} is outdated.`);
+        wantGuide = true; // Auto-update — addGuide handles the replacement
+      } else {
+        clack.log.info(`Orchestrator guide in ${guideDisplayPath} is up to date.`);
+        wantGuide = false;
+      }
     } else if (guideFileExists) {
       // File exists — reassure user their content is safe
       clack.log.info(`Found existing ${guideDisplayPath} — your content will be preserved.`);
@@ -599,8 +729,10 @@ async function runInteractiveSetup(flags) {
   if (wantGuide) {
     const guideResult = addGuide(scope);
 
-    if (guideResult.skipped) {
-      clack.log.warn('Orchestrator guide already in CLAUDE.md — skipped.');
+    if (guideResult.updated) {
+      clack.log.success(`Updated orchestrator guide in ${guideDisplayPath} (new rules synced)`);
+    } else if (guideResult.skipped) {
+      clack.log.info('Orchestrator guide already up to date — skipped.');
     } else if (guideResult.created) {
       clack.log.success(`Created ${guideDisplayPath} with orchestrator guide`);
     } else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-multi-session",
-  "version": "2.5.0",
+  "version": "2.5.1",
   "description": "Multi-session orchestrator for Claude Code CLI — spawn, control, pause, resume, and send multiple inputs to Claude Code sessions programmatically",
   "main": "src/index.js",
   "bin": {