start-vibing-stacks 2.22.0 → 2.24.0

package/stacks/_shared/hooks/user-prompt-submit.ts

@@ -1,15 +1,39 @@
 #!/usr/bin/env node
+// @sv-version: 1.1.0
 /**
  * UserPromptSubmit Hook — Start Vibing Stacks
  *
- * Injects workflow instructions before each user prompt.
- * Reads active-project.json for stack-specific context.
+ * Two responsibilities:
+ *  1. Inject the per-stack workflow + project-standards context block.
+ *  2. Multi-instance coordination: heartbeat the session, capture the title
+ *     from the first prompt (matches `claude --resume`), drain the inbox so
+ *     peer messages reach the user before this turn runs, and warn if active
+ *     peers exist.
  */
 
 import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
-
-const PROJECT_DIR = process.env['CLAUDE_PROJECT_DIR'] || process.cwd();
+import {
+  ACTIVE_MS,
+  ageMs,
+  drainInbox,
+  ensureStateDirs,
+  extractTitle,
+  formatPeer,
+  getGitBranch,
+  getProjectDir,
+  getStateDir,
+  heartbeat,
+  listPeerSessions,
+  readSession,
+  readStdinJson,
+  shortId,
+  truncate,
+  type InboxMessage,
+  type SessionRecord,
+} from './_state.js';
+
+const PROJECT_DIR = getProjectDir();
 const ACTIVE_PROJECT = join(PROJECT_DIR, '.claude', 'config', 'active-project.json');
 const STANDARDS_REVIEW = join(PROJECT_DIR, '.claude', 'config', 'standards-review.json');
 
@@ -36,7 +60,8 @@ interface ReviewFile {
 let standardsContext = '';
 try {
   if (!existsSync(STANDARDS_REVIEW)) {
-    standardsContext = `\n\nSTANDARDS REVIEW NEEDED: No standards-review.json found. ` +
+    standardsContext =
+      `\n\nSTANDARDS REVIEW NEEDED: No standards-review.json found. ` +
       `This project may have existing coding standards (.cursorrules, composer.json configs). ` +
       `Ask the user: "I noticed this project hasn't been scanned for existing standards. ` +
       `Would you like me to review your codebase patterns and adapt my behavior, ` +
@@ -45,26 +70,66 @@ try {
     const review: ReviewFile = JSON.parse(readFileSync(STANDARDS_REVIEW, 'utf8'));
     if (review.status === 'adapted' && review.patterns && review.patterns.length > 0) {
       const patternList = review.patterns.map(p => `- [${p.category}] ${p.name}`).join('\n');
-      standardsContext = `\n\nPROJECT STANDARDS (scanned from ${(review.sources || []).join(', ')}):\n${patternList}\n` +
+      standardsContext =
+        `\n\nPROJECT STANDARDS (scanned from ${(review.sources || []).join(', ')}):\n${patternList}\n` +
         `Follow these project-specific patterns. They take priority over generic defaults.`;
     }
   }
 } catch {}
 
-async function main(): Promise<void> {
-  let hookInput: any = {};
-  try {
-    const chunks: string[] = [];
-    process.stdin.setEncoding('utf8');
-    const timeout = setTimeout(() => process.stdin.destroy(), 1000);
-    for await (const chunk of process.stdin) {
-      chunks.push(chunk);
+function formatInbox(m: InboxMessage): string {
+  const from = m.fromTitle ? `${shortId(m.fromSessionId)} "${m.fromTitle}"` : shortId(m.fromSessionId);
+  return `  [${m.ts}] from ${from}: ${m.message}`;
+}
+
+function buildPeersBlock(stateDir: string, sessionId: string, prompt: string): string {
+  ensureStateDirs(stateDir);
+
+  // Heartbeat + capture title on first prompt of the session.
+  const existing = readSession(stateDir, sessionId);
+  const titleNeeded = !existing || !existing.title || existing.title === '(untitled)';
+  const title = titleNeeded
+    ? extractTitle(existing?.transcriptPath, prompt)
+    : existing!.title;
+
+  const branch = existing?.gitBranch ?? getGitBranch(PROJECT_DIR);
+
+  heartbeat(stateDir, sessionId, 'UserPromptSubmit', {
+    title,
+    cwd: PROJECT_DIR,
+    gitBranch: branch,
+  });
+
+  const peers: SessionRecord[] = listPeerSessions(stateDir, sessionId);
+  const inbox = drainInbox(stateDir, sessionId);
+
+  const parts: string[] = [];
+  if (peers.length > 0) {
+    const activeCount = peers.filter(p => ageMs(p.lastSeenAt) < ACTIVE_MS).length;
+    parts.push('');
+    parts.push(`PEER INSTANCES IN THIS PROJECT (${peers.length}, ${activeCount} active):`);
+    for (const p of peers) parts.push(`  - ${formatPeer(p)}`);
+    if (activeCount > 0) {
+      parts.push(
+        '  ! Edit/Write of files an active peer just touched will be BLOCKED. ' +
+          'Use `/peers notify <id> "message"` to coordinate.'
+      );
     }
-    clearTimeout(timeout);
-    hookInput = JSON.parse(chunks.join('') || '{}');
-  } catch {}
+  }
+
+  if (inbox.length > 0) {
+    parts.push('');
+    parts.push(`INBOX (${inbox.length} message${inbox.length === 1 ? '' : 's'} from peers — surface to the user):`);
+    for (const m of inbox) parts.push(formatInbox(m));
+  }
 
-  const prompt = hookInput.user_prompt || hookInput.prompt || '';
+  return parts.join('\n');
+}
+
+async function main(): Promise<void> {
+  const hookInput = await readStdinJson(1500);
+  const prompt: string =
+    hookInput.user_prompt || hookInput.prompt || hookInput.userPrompt || '';
   if (!prompt.trim()) {
     console.log(JSON.stringify({ continue: true }));
     process.exit(0);
@@ -72,6 +137,17 @@ async function main(): Promise<void> {
 
   const today = new Date().toISOString().split('T')[0];
 
+  let peersBlock = '';
+  const sessionId: string | undefined = hookInput.session_id || hookInput.sessionId;
+  if (sessionId) {
+    const stateDir = getStateDir(PROJECT_DIR);
+    try {
+      peersBlock = buildPeersBlock(stateDir, sessionId, prompt);
+    } catch {
+      peersBlock = '';
+    }
+  }
+
   const systemMessage = `TASK WORKFLOW (Stack: ${stackName}):
 
 0. READ both CLAUDE.md and .claude/config/active-project.json before changes.
@@ -89,7 +165,7 @@ async function main(): Promise<void> {
    a. "## Last Change" (date: ${today}, branch, summary)
    b. Update ALL affected rule/flow sections
 
-6. Run stop-validator before finishing.${standardsContext}`;
+6. Run stop-validator before finishing.${standardsContext}${peersBlock}`;
 
   console.log(JSON.stringify({ continue: true, systemMessage }));
   process.exit(0);
@@ -99,3 +175,5 @@ main().catch(() => {
   console.log(JSON.stringify({ continue: true }));
   process.exit(0);
 });
+
+void truncate;

package/stacks/_shared/skills/multi-instance-coordination/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: multi-instance-coordination
+version: 1.0.0
+description: Coordination protocol when multiple Claude Code instances run in the same project folder. State layout under `.claude/state/`, peer detection, file-edit collision avoidance (hybrid block/warn), and the `/peers` CLI for cross-instance messaging. Use when the user mentions another Claude instance, parallel work, concurrent sessions, the word "peers", or asks about /resume titles, file-touches.jsonl, or `.claude/state/`.
+---
+
+# Multi-Instance Coordination
+
+When two or more Claude Code instances are running in the same project folder, they auto-discover each other through `.claude/state/` and refuse to overwrite each other's uncommitted work.
+
+## Mental model
+
+```
+.claude/state/
+  sessions/<id>.json        registry  (heartbeat = lastSeenAt)
+  sessions/_archive/        sessions ended or gone idle >30min
+  inbox/<id>.jsonl          messages queued FOR that session
+  file-touches.jsonl        append-only log of every Edit/Write
+  file-touches/_archive/    rotated logs (every 1000 lines)
+```
+
+Every hook updates `lastSeenAt` (heartbeat). Thresholds:
+
+| Age of last activity | State    | Effect                                                                 |
+| -------------------- | -------- | ---------------------------------------------------------------------- |
+| < 60s                | active   | Counts for collision detection; PreToolUse may BLOCK Edit/Write.       |
+| 60s – 30min          | idle     | Surfaced as a warning; edits NOT blocked.                              |
+| > 30min              | stale    | Auto-archived on the next sweep.                                       |
+| > 24h                | removed  | Deleted entirely.                                                      |
+
+## How a Claude session announces itself
+
+1. `SessionStart` runs once. It registers the session, extracts a `title` from the transcript (this is the same title that appears in `claude --resume`), lists peers, and drains the inbox.
+2. `UserPromptSubmit` keeps the heartbeat fresh on every user turn. It re-drains the inbox so messages arrive between turns, not stuck waiting for a SessionStart.
+3. `PreToolUse` (matcher `Edit|Write|MultiEdit|NotebookEdit`) checks `file-touches.jsonl` against the target file BEFORE the edit runs.
+4. `PostToolUse` (same matcher) records the touch AFTER a successful edit.
+5. `Stop` / `SessionEnd` archives the session and clears its inbox.
+
+## PreToolUse decision matrix
+
+| Peer who touched the same file last | Peer's heartbeat | Touch age | Decision |
+| ----------------------------------- | ---------------- | --------- | --------------------------------------------- |
+| any                                 | active (<60s)    | < 5min    | **BLOCK** with a recovery hint                |
+| any                                 | idle (60s–30min) | < 5min    | APPROVE + warning in `systemMessage`          |
+| any                                 | stale or gone    | any       | APPROVE silently                              |
+| no peer touched the file            | n/a              | n/a       | APPROVE silently                              |
+
+Override path: wait until the active peer's heartbeat goes idle (60s of no activity), then retry — the hook will downgrade to a warning. If the user explicitly tells you to override, ask them to run `peers notify <id> "I'm taking over <file>"` first so the other instance gets the heads-up.
+
+## Talking to a peer
+
+Always use the `peers` CLI. NEVER write to `.claude/state/inbox/` by hand.
+
+```bash
+# See who is around
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" list
+
+# Send a message (id-prefix is the 8-char short id from `list`)
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" notify a1b2c3d4 "I just committed auth changes"
+
+# See recent file edits across instances
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" locks --minutes 10
+
+# Cleanup zombie sessions (>1h idle)
+npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" cleanup
+```
+
+The `/peers` slash command wraps these.
+
+## Guardrails
+
+- The coordination layer is **single-host**. It does not replace `git pull` or PR review across machines.
+- All state writes are atomic (`.tmp` + `rename`); reads are tolerant of corruption — hooks never block Claude on a broken state file.
+- `.claude/state/` MUST stay gitignored. Committing it would leak per-host PIDs and transcript paths.
+- `peers` is the user-facing surface; the hooks are internal plumbing. Do not invoke `_state.ts` directly.
+
+## Failure modes (and what to do)
+
+| Symptom                                                  | Cause                                | Fix                                                    |
+| -------------------------------------------------------- | ------------------------------------ | ------------------------------------------------------ |
+| `peers list` shows a phantom session                     | Crashed instance left a record       | `peers cleanup` (archives idle, removes >24h)          |
+| Edit blocked but the other instance is gone              | Stale heartbeat, peer never archived | Wait 30min, or run `peers cleanup`                     |
+| Inbox messages didn't arrive                             | Peer is paused / no `UserPromptSubmit` | They will appear on the next prompt the peer submits   |
+| Two edits hit the same file in the same second           | Race condition (rare)                | The append-only log captures both; review with `git diff` |
+
+## See Also
+
+- `git-workflow` — branch and commit hygiene; the coordination layer is an in-flight collision shield, not a replacement for branches.
+- `_state.ts` — shared TypeScript helpers used by every hook.
+- `.claude/state/` README at `.claude/hooks/_state.README.md`.