start-vibing-stacks 2.22.0 → 2.23.0

package/README.md

@@ -6,7 +6,7 @@ Multi-stack AI workflow for **Claude Code** & **Cursor**. One command installs a
 npx start-vibing-stacks
 ```
 
-> Latest: **v2.12.0** — `security-auditor` rewritten as stack-aware adversarial auditor with VETO power; `documenter` rewritten with search-optimized memory layer (YAML frontmatter + `_index.json` sidecar); `research-web` MCP-first; CI on Node 22.
+> Latest: **v2.23.0** — multi-instance coordination layer. Two or more Claude Code sessions in the same folder auto-discover each other through `.claude/state/`, share file-edit awareness, and refuse to overwrite each other's uncommitted work. New `/peers` slash command + `peers list/notify/locks/cleanup` CLI.
 
 ---
 
@@ -16,8 +16,8 @@ npx start-vibing-stacks
 |---|---|---|
 | Agents | **7** universal | `research-web` (MCP-first) · `documenter` (memory layer) · `domain-updater` · `commit-manager` · `tester` · `claude-md-compactor` (compaction) · **`security-auditor` (VETO)** |
 | Skills | **22** shared + **7–14** stack-specific + **2–7** frontend | Versioned (`version:` frontmatter), upgradable via `migrate` |
-| Hooks | `stop-validator` · `final-check` · `user-prompt-submit` | Block completion on git/docs/secrets/code-quality issues |
-| Commands | `/feature` · `/fix` · `/research` · `/validate` | Slash commands |
+| Hooks | `session-start` · `user-prompt-submit` · `pre-tool-use` · `post-tool-use` · `stop-validator` · `final-check` | Multi-instance coordination + git/docs/secrets/code-quality gates |
+| Commands | `/feature` · `/fix` · `/research` · `/validate` · `/peers` | Slash commands |
 | Workflows | `ci.yml` + `security.yml` per stack | Copied to `.github/workflows/` when target is empty |
 | Configs | `active-project.json` · `domain-mapping.json` · `security-rules.json` · `standards-review.json` | Drives every agent's stack detection |
 
@@ -82,14 +82,51 @@ your-project/
 │   │   │   ├── _index.json                    # machine-readable, regenerated by documenter
 │   │   │   └── domains/                       # one file per domain (≤ 8 KB each)
 │   │   └── <other skills>/
-│   ├── hooks/                                 # stop-validator, final-check, prompt-submit
-│   ├── commands/                              # /feature, /fix, /research, /validate
+│   ├── hooks/                                 # session-start, pre/post-tool-use, stop-validator, final-check, prompt-submit, peers (CLI)
+│   ├── commands/                              # /feature, /fix, /research, /validate, /peers
+│   ├── state/                                 # multi-instance coordination (gitignored, runtime-managed)
 │   └── config/                                # active-project, domain-mapping, security-rules, ...
 └── .github/workflows/                         # ci.yml + security.yml (if dir was empty)
 ```
 
 ---
 
+## Multiple Claude instances in the same folder
+
+When two or more Claude Code sessions run in the same project, the installed hooks coordinate automatically through `.claude/state/` (gitignored, per-host).
+
+What you get:
+
+- **Auto-discovery** — `SessionStart` registers each session, captures the same title that appears in `claude --resume`, and tells you who else is around.
+- **File-edit collision shield** — `PreToolUse` BLOCKS Edit/Write on a file a peer is actively editing (heartbeat <60s, touched <5min ago). Idle peers (60s–30min) downgrade to a warning; stale peers are ignored.
+- **Cross-instance messaging** — `peers notify <id-prefix> "msg"` queues a message that surfaces in the OTHER instance at its next prompt. The user-prompt-submit hook drains the inbox automatically.
+
+### `/peers` CLI
+
+```bash
+# Inside Claude:
+/peers                  # delegates to the script
+
+# Or from any terminal:
+npx tsx .claude/hooks/peers.ts list
+npx tsx .claude/hooks/peers.ts notify a1b2c3d4 "I just committed auth changes"
+npx tsx .claude/hooks/peers.ts locks --minutes 10
+npx tsx .claude/hooks/peers.ts cleanup
+```
+
+### Heartbeat thresholds
+
+| Last activity | State    | Effect                                                   |
+| ------------- | -------- | -------------------------------------------------------- |
+| < 60s         | active   | Counts for collision detection; BLOCKS conflicting edits |
+| 60s – 30min   | idle     | Surfaced as a warning; edits NOT blocked                 |
+| > 30min       | stale    | Auto-archived                                            |
+| > 24h         | removed  | Deleted                                                  |
+
+Single-host coordination only. It does **not** replace `git` for cross-machine collaboration; it prevents two live sessions on the same laptop from stepping on the same uncommitted file.
+
+---
+
 ## CLI
 
 ```bash

package/dist/setup.js

@@ -68,6 +68,10 @@ export async function setupProject(projectDir, config, options = {}) {
         mkdirSync(join(claudeDir, 'commands'), { recursive: true });
         mkdirSync(join(claudeDir, 'rules'), { recursive: true });
         mkdirSync(join(claudeDir, 'skills', 'codebase-knowledge', 'domains'), { recursive: true });
+        // Multi-instance coordination state (gitignored, runtime-managed)
+        mkdirSync(join(claudeDir, 'state', 'sessions', '_archive'), { recursive: true });
+        mkdirSync(join(claudeDir, 'state', 'inbox'), { recursive: true });
+        mkdirSync(join(claudeDir, 'state', 'file-touches', '_archive'), { recursive: true });
         spinner.text = 'Directory structure created';
         // 2. Copy shared agents (universal)
         const sharedAgentsDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'agents');
@@ -79,6 +83,12 @@ export async function setupProject(projectDir, config, options = {}) {
         // 4. Copy shared hooks
         const sharedHooksDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'hooks');
         const hookCount = copyDirRecursive(sharedHooksDir, join(claudeDir, 'hooks'), options.force);
+        // 4b. Multi-instance coordination README in state dir
+        const stateReadmeSrc = join(PACKAGE_ROOT, 'stacks', '_shared', 'hooks', '_state.README.md');
+        const stateReadmeDest = join(claudeDir, 'state', 'README.md');
+        if (existsSync(stateReadmeSrc) && (!existsSync(stateReadmeDest) || options.force)) {
+            writeFileSync(stateReadmeDest, readFileSync(stateReadmeSrc, 'utf8'));
+        }
         // 5. Copy shared config
         const sharedConfigDir = join(PACKAGE_ROOT, 'stacks', '_shared', 'config');
         copyDirRecursive(sharedConfigDir, join(claudeDir, 'config'), options.force);
@@ -140,13 +150,21 @@ export async function setupProject(projectDir, config, options = {}) {
                 spinner.text = 'Imported .cursorrules into Claude config';
             }
         }
-        // 11b. Ensure CLAUDE.local.md is gitignored
+        // 11b. Ensure CLAUDE.local.md and .claude/state/ are gitignored
         const gitignorePath = join(projectDir, '.gitignore');
         if (existsSync(gitignorePath)) {
-            const gitignore = readFileSync(gitignorePath, 'utf8');
+            let gitignore = readFileSync(gitignorePath, 'utf8');
+            let changed = false;
             if (!gitignore.includes('CLAUDE.local.md')) {
-                writeFileSync(gitignorePath, gitignore.trimEnd() + '\n\n# Claude Code local preferences\nCLAUDE.local.md\n');
+                gitignore = gitignore.trimEnd() + '\n\n# Claude Code local preferences\nCLAUDE.local.md\n';
+                changed = true;
+            }
+            if (!gitignore.match(/^\.claude\/state\/?$/m) && !gitignore.match(/^\.claude\/?$/m)) {
+                gitignore = gitignore.trimEnd() + '\n\n# Claude Code multi-instance coordination state (runtime, per-host)\n.claude/state/\n';
+                changed = true;
             }
+            if (changed)
+                writeFileSync(gitignorePath, gitignore);
         }
         // 11c. Save standards review results
         if (config.standardsReview) {
@@ -230,6 +248,17 @@ export async function setupProject(projectDir, config, options = {}) {
                 deny: [],
             },
             hooks: {
+                SessionStart: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.ts"',
+                                timeout: 10,
+                            },
+                        ],
+                    },
+                ],
                 UserPromptSubmit: [
                     {
                         matcher: '',
@@ -242,6 +271,30 @@ export async function setupProject(projectDir, config, options = {}) {
                         ],
                     },
                 ],
+                PreToolUse: [
+                    {
+                        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-use.ts"',
+                                timeout: 5,
+                            },
+                        ],
+                    },
+                ],
+                PostToolUse: [
+                    {
+                        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use.ts"',
+                                timeout: 5,
+                            },
+                        ],
+                    },
+                ],
                 Stop: [
                     {
                         hooks: [
@@ -253,6 +306,17 @@ export async function setupProject(projectDir, config, options = {}) {
                         ],
                     },
                 ],
+                SessionEnd: [
+                    {
+                        hooks: [
+                            {
+                                type: 'command',
+                                command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validator.ts"',
+                                timeout: 10,
+                            },
+                        ],
+                    },
+                ],
             },
             agents: {
                 'research-web': {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.22.0",
+  "version": "2.23.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/commands/peers.md

@@ -0,0 +1,37 @@
+---
+name: peers
+description: Inspect or talk to other Claude Code instances running in this same project (multi-instance coordination layer).
+version: 1.0.0
+---
+
+# /peers — Multi-Instance Coordination
+
+Use this when the user asks something like:
+
+- "is there another Claude running in this folder?"
+- "tell the other instance I finished the auth work"
+- "who touched `src/x.ts` recently?"
+- "clean up dead sessions"
+
+Run the `peers` CLI via Bash. The script lives at `.claude/hooks/peers.ts` and is installed by `start-vibing-stacks`.
+
+## Usage
+
+| Goal | Command |
+|---|---|
+| List active + idle peer sessions | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" list` |
+| Notify another instance | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" notify <id-prefix> "message"` |
+| See who touched what file recently | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" locks --minutes 10` |
+| Remove stale sessions | `npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/peers.ts" cleanup` |
+
+The `<id-prefix>` is the 8-character short id printed by `peers list`, or any substring of the peer's title.
+
+## Output rules
+
+- Always quote the short id (first 8 chars), the title, and the idle time when reporting peers to the user.
+- If `peers notify` succeeds, tell the user the message will surface in the OTHER instance at the start of its next prompt (drained by `user-prompt-submit.ts`).
+- If `peers list` says "No peer sessions", confirm that to the user and DO NOT suggest workarounds.
+
+## Background
+
+State lives in `.claude/state/` (gitignored). Hooks `session-start.ts`, `user-prompt-submit.ts`, `pre-tool-use.ts`, `post-tool-use.ts` and `stop-validator.ts` keep it in sync. See `multi-instance-coordination` skill for the full protocol.

package/stacks/_shared/hooks/_state.README.md

@@ -0,0 +1,55 @@
+# `.claude/state/` — Multi-Instance Coordination
+
+> This directory is **gitignored** and managed automatically by hooks. Safe to delete; it will be recreated by the next Claude session.
+
+When two or more Claude Code instances run in the same project folder, the hooks under `.claude/hooks/` use this directory to:
+
+1. announce themselves to each other (`sessions/<id>.json`)
+2. record file edits as they happen (`file-touches.jsonl`)
+3. prevent simultaneous writes to the same file (PreToolUse hook reads the touch log)
+4. exchange messages (`inbox/<id>.jsonl` — drained at next prompt)
+
+## Layout
+
+```
+.claude/state/
+  sessions/
+    <session-id>.json          one record per active instance (heartbeat-tracked)
+    _archive/                  sessions ended or stale (>30min idle)
+  inbox/
+    <session-id>.jsonl         queued messages for that session
+  file-touches.jsonl           append-only Edit/Write log (rotates every 1000 lines)
+  file-touches/_archive/       rotated logs
+```
+
+## Heartbeat thresholds
+
+| Last activity | State    | Effect                                                                      |
+| ------------- | -------- | --------------------------------------------------------------------------- |
+| < 60s         | active   | Counts for collision detection. PreToolUse may **block** Edit/Write.        |
+| 60s – 30min   | idle     | Surfaced as a warning in `systemMessage`. Edits are **not** blocked.        |
+| > 30min       | stale    | Auto-archived on the next sweep.                                            |
+| > 24h         | removed  | Deleted entirely.                                                           |
+
+## Viewing peers
+
+From inside Claude or a terminal:
+
+```
+/peers
+```
+
+or directly:
+
+```
+npx tsx .claude/hooks/peers.ts list
+npx tsx .claude/hooks/peers.ts notify <id-prefix> "message"
+npx tsx .claude/hooks/peers.ts locks --minutes 10
+npx tsx .claude/hooks/peers.ts cleanup
+```
+
+## Safety
+
+- All state writes are atomic (`.tmp` + `rename`).
+- All reads are tolerant of corruption — hooks never block Claude on a malformed file.
+- This is a single-host coordination layer. It does **not** replace git; it only prevents two live sessions from stepping on the same uncommitted edit.