gsd-init 1.0.0

package/README.md

@@ -0,0 +1,41 @@
+# gsd-init
+
+Set up the GSD observer/worker tmux system in your project.
+
+## Usage
+
+```bash
+npx gsd-init
+```
+
+With auto-confirm:
+```bash
+npx gsd-init --yes
+```
+
+## What it does
+
+1. Installs observer scripts to `~/.claude/gsd-observer/`
+2. Registers a Stop hook in `.claude/settings.json`
+3. Prints next steps for starting the observer and worker sessions
+
+## Requirements
+
+- Node.js >= 16
+- tmux
+- jq
+- Claude Code CLI (`claude`)
+- GSD (superpowers plugin) installed in Claude Code
+
+## After install
+
+```bash
+# Start Observer session first
+~/.claude/gsd-observer/scripts/start-observer.sh
+
+# Start Worker session in your project directory
+~/.claude/gsd-observer/scripts/start-worker.sh /path/to/project
+
+# Verify setup
+~/.claude/gsd-observer/scripts/verify.sh
+```

package/bin/gsd-init.js

@@ -0,0 +1,216 @@
+#!/usr/bin/env node
+'use strict';
+// Node version check — must use syntax valid in Node 14+ for compatibility
+var major = parseInt(process.version.slice(1).split('.')[0], 10);
+if (major < 16) {
+  process.stderr.write('gsd-init requires Node.js >= 16 (found ' + process.version + ')\n');
+  process.exit(1);
+}
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+const OBS_ROOT = process.env.GSD_INIT_OBS_ROOT || path.join(os.homedir(), '.claude', 'gsd-observer');
+
+const TEMPLATE_FILES = [
+  { src: 'agents/gsd-observer.md',      dst: 'agents/gsd-observer.md' },
+  { src: 'hooks/gsd-stop-hook.sh',      dst: 'hooks/gsd-stop-hook.sh' },
+  { src: 'scripts/start-observer.sh',   dst: 'scripts/start-observer.sh' },
+  { src: 'scripts/start-worker.sh',     dst: 'scripts/start-worker.sh' },
+  { src: 'scripts/wake-observer.sh',    dst: 'scripts/wake-observer.sh' },
+  { src: 'scripts/notify-worker.sh',    dst: 'scripts/notify-worker.sh' },
+  { src: 'scripts/teardown.sh',         dst: 'scripts/teardown.sh' },
+  { src: 'scripts/verify.sh',           dst: 'scripts/verify.sh' },
+  { src: 'schema/event.json',           dst: 'schema/event.json' },
+  { src: 'schema/response.json',        dst: 'schema/response.json' },
+];
+
+const SH_FILES = [
+  'hooks/gsd-stop-hook.sh',
+  'scripts/start-observer.sh',
+  'scripts/start-worker.sh',
+  'scripts/wake-observer.sh',
+  'scripts/notify-worker.sh',
+  'scripts/teardown.sh',
+  'scripts/verify.sh',
+];
+
+const GSD_ENTRY = {
+  matcher: '',
+  hooks: [{ type: 'command', command: '~/.claude/gsd-observer/hooks/gsd-stop-hook.sh' }]
+};
+
+function getSettingsLabel(settingsPath) {
+  if (!fs.existsSync(settingsPath)) return '[create]';
+  var data;
+  try { data = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); }
+  catch (e) { return '[error]'; }
+  var stopArr = (data.hooks && data.hooks.Stop) ? data.hooks.Stop : [];
+  var alreadyRegistered = stopArr.some(function(entry) {
+    return JSON.stringify(entry).includes('gsd-stop-hook.sh');
+  });
+  return alreadyRegistered ? '[skip]' : '[merge]';
+}
+
+function planInstall(tmplDir, obsRoot, projDir) {
+  var homeDir = os.homedir();
+  var ops = [];
+  for (var i = 0; i < TEMPLATE_FILES.length; i++) {
+    var f = TEMPLATE_FILES[i];
+    var dest = path.join(obsRoot, f.dst);
+    var label = fs.existsSync(dest) ? '[overwrite]' : '[create]';
+    var relDisplay = dest.startsWith(homeDir)
+      ? '~' + dest.slice(homeDir.length)
+      : dest;
+    ops.push({ dest: dest, label: label, relative: relDisplay });
+  }
+  var settingsPath = path.join(projDir, '.claude', 'settings.json');
+  ops.push({ dest: settingsPath, label: getSettingsLabel(settingsPath), relative: '.claude/settings.json' });
+  return ops;
+}
+
+// Stubs — implemented in later tasks
+function formatDryRun(ops) {
+  var lines = ['gsd-init — GSD Observer/Worker setup', '', 'Files to install:'];
+  for (var i = 0; i < ops.length; i++) {
+    var op = ops[i];
+    // Pad label to 14 chars for alignment: '[create]' is 8, '[overwrite]' is 11, '[merge]' is 7, '[skip]' is 6
+    var padded = op.label + ' '.repeat(Math.max(1, 14 - op.label.length));
+    lines.push('  ' + padded + op.relative);
+  }
+  return lines.join('\n');
+}
+function mkdirpSync(dir) { fs.mkdirSync(dir, { recursive: true }); }
+function copyTemplates(tmplDir, obsRoot) {
+  for (var i = 0; i < TEMPLATE_FILES.length; i++) {
+    var f = TEMPLATE_FILES[i];
+    var src = path.join(tmplDir, f.src);
+    var dest = path.join(obsRoot, f.dst);
+    mkdirpSync(path.dirname(dest));
+    fs.copyFileSync(src, dest);
+  }
+}
+function chmodScripts(obsRoot) {
+  for (var i = 0; i < SH_FILES.length; i++) {
+    fs.chmodSync(path.join(obsRoot, SH_FILES[i]), 0o755);
+  }
+}
+function mergeSettings(projDir, entry) {
+  var settingsPath = path.join(projDir, '.claude', 'settings.json');
+  if (!fs.existsSync(settingsPath)) {
+    var newData = { hooks: { Stop: [entry] } };
+    fs.writeFileSync(settingsPath, JSON.stringify(newData, null, 2) + '\n');
+    return;
+  }
+  var raw = fs.readFileSync(settingsPath, 'utf8');
+  var data;
+  try { data = JSON.parse(raw); }
+  catch (e) { throw new Error('Malformed JSON in ' + settingsPath + ': ' + e.message); }
+
+  var stopArr = (data.hooks && data.hooks.Stop) ? data.hooks.Stop : [];
+  var alreadyRegistered = stopArr.some(function(e) {
+    return JSON.stringify(e).includes('gsd-stop-hook.sh');
+  });
+  if (alreadyRegistered) return;
+
+  if (!data.hooks) data.hooks = {};
+  if (!data.hooks.Stop) data.hooks.Stop = [];
+  data.hooks.Stop.push(entry);
+  fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + '\n');
+}
+function prompt(question) {
+  return new Promise(function(resolve) {
+    var rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, function(answer) {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === 'y');
+    });
+  });
+}
+
+function printSummary() {
+  console.log([
+    '',
+    'Done! Next steps:',
+    '  1. Start Observer first:  ~/.claude/gsd-observer/scripts/start-observer.sh',
+    '  2. Start Worker:          ~/.claude/gsd-observer/scripts/start-worker.sh <project-dir>',
+    '  3. Run GSD in the Worker tmux pane — Observer will co-pilot automatically.',
+    '',
+    '  Observer agent prompt: ~/.claude/gsd-observer/agents/gsd-observer.md',
+    '  Verify setup:          ~/.claude/gsd-observer/scripts/verify.sh',
+    '',
+    'Teardown:',
+    '  ~/.claude/gsd-observer/scripts/teardown.sh',
+    '  (or manually: tmux kill-session -t gsd-worker && tmux kill-session -t gsd-observer &&',
+    '   rm -f /tmp/gsd-event-*.json /tmp/gsd-response-*.json /tmp/gsd-last-event-phase)',
+  ].join('\n'));
+}
+
+async function run() {
+  var args = process.argv.slice(2);
+  var skipPrompt = args.indexOf('--yes') !== -1 || args.indexOf('-y') !== -1;
+  var projDir = process.env.GSD_INIT_PROJ_DIR || process.cwd();
+
+  var ops = planInstall(TEMPLATES_DIR, OBS_ROOT, projDir);
+
+  // Abort on malformed settings.json early
+  var errOp = null;
+  for (var i = 0; i < ops.length; i++) {
+    if (ops[i].label === '[error]') { errOp = ops[i]; break; }
+  }
+  if (errOp) {
+    console.error('Error: Malformed JSON in ' + errOp.dest + ' — fix or remove it and retry.');
+    process.exit(1);
+  }
+
+  console.log(formatDryRun(ops));
+  console.log('');
+  console.log('Proceed? [y/N]');
+
+  if (!skipPrompt) {
+    var proceed = await prompt('');
+    if (!proceed) {
+      console.log('Aborted.');
+      process.exit(0);
+    }
+  }
+
+  // Step 1: create ~/.claude/gsd-observer subdirs
+  var subdirs = ['agents', 'hooks', 'scripts', 'schema'];
+  for (var j = 0; j < subdirs.length; j++) {
+    var subdir = path.join(OBS_ROOT, subdirs[j]);
+    try { mkdirpSync(subdir); }
+    catch (e) { console.error('Error creating ' + subdir + ': ' + e.message); process.exit(1); }
+  }
+
+  // Step 2: create project .claude/
+  var dotClaudeDir = path.join(projDir, '.claude');
+  try { mkdirpSync(dotClaudeDir); }
+  catch (e) { console.error('Error creating ' + dotClaudeDir + ': ' + e.message); process.exit(1); }
+
+  // Step 3: copy templates
+  try { copyTemplates(TEMPLATES_DIR, OBS_ROOT); }
+  catch (e) { console.error('Error copying templates to ' + OBS_ROOT + ': ' + e.message); process.exit(1); }
+
+  // Step 4: chmod .sh files
+  try { chmodScripts(OBS_ROOT); }
+  catch (e) { console.error('Error setting permissions in ' + OBS_ROOT + ': ' + e.message); process.exit(1); }
+
+  // Step 5: merge settings.json
+  try { mergeSettings(projDir, GSD_ENTRY); }
+  catch (e) { console.error(e.message); process.exit(1); }
+
+  printSummary();
+}
+
+if (require.main === module) {
+  run().catch(function(e) { console.error(e.message); process.exit(1); });
+}
+
+module.exports = {
+  planInstall, getSettingsLabel, formatDryRun, mkdirpSync,
+  copyTemplates, chmodScripts, mergeSettings, printSummary,
+  TEMPLATE_FILES, SH_FILES, GSD_ENTRY
+};

package/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "gsd-init",
+  "version": "1.0.0",
+  "description": "Set up GSD observer/worker tmux system in a project",
+  "bin": {
+    "gsd-init": "bin/gsd-init.js"
+  },
+  "files": ["bin", "templates", "README.md"],
+  "engines": { "node": ">=16" },
+  "license": "MIT",
+  "scripts": {
+    "test": "node tests/test-plan-install.js && node tests/test-merge-settings.js && node tests/test-integration.js"
+  }
+}

package/templates/agents/gsd-observer.md

@@ -0,0 +1,55 @@
+---
+description: GSD Observer co-pilot. Woken by Worker Claude via tmux to review GSD phase outputs.
+---
+
+You are GSD Observer, a co-pilot for a Claude instance running the GSD (Get Shit Done) workflow.
+
+When you receive an instruction to read an event file and respond:
+
+1. Read the event JSON file at the path given
+2. Check the `observer_mode` field
+3. Read the artifacts listed (handle null fields gracefully — note absence in observations)
+4. Execute mode logic:
+
+   **AUDIT mode** (research, verify phases):
+   - Review artifacts for completeness, quality, coverage gaps
+   - Identify missing information or weak areas
+   - Decision: `proceed` if adequate, `revise` if gaps are significant
+
+   **BLOCK mode** (plan phase):
+   - Review plan document: goal clarity, task breakdown, dependencies, risks, success criteria
+   - Decision: `proceed` if plan is solid, `revise` if fundamental issues found
+
+   **AUGMENT mode** (execute phase):
+   - Review changed files: correctness, code quality, security, edge cases
+   - Review test results if present (note if absent)
+   - Decision: `proceed` if acceptable, `revise` if issues need fixing before next phase
+
+5. Write response JSON **atomically** to the path specified:
+   ```bash
+   echo '<json>' > <path>.tmp && mv <path>.tmp <path>
+   ```
+
+   Response format:
+   ```json
+   {
+     "event_id": "<from event file>",
+     "decision": "proceed | revise | hold",
+     "mode": "<audit | block | augment>",
+     "observations": ["observation 1", "observation 2"],
+     "message": "Human-readable summary for Worker Claude.",
+     "revision_instructions": "Specific actionable instructions (required when decision=revise, omit otherwise)",
+     "timestamp": "<ISO8601>"
+   }
+   ```
+
+6. Run the notify script:
+   ```bash
+   ~/.claude/gsd-observer/scripts/notify-worker.sh <event_id>
+   ```
+
+**Rules:**
+- `revision_instructions` must be specific and actionable — Worker Claude acts on it without asking for clarification
+- Be concise in `message` (1-2 sentences)
+- Do NOT ask questions back to the user
+- Handle `null` artifact fields by noting the absence in observations rather than failing

package/templates/hooks/gsd-stop-hook.sh

@@ -0,0 +1,262 @@
+#!/usr/bin/env bash
+# GSD Stop Hook — fires after each Claude response in Worker session.
+# Detects GSD phase completion by checking recently-modified artifact files.
+# Blocks in a polling loop until Observer responds, then exits.
+#
+# Environment variables (all optional, have defaults):
+#   GSD_OBSERVER_ENABLED        — set to 1 to activate (default: off)
+#   GSD_OBSERVER_SESSION        — tmux session name for Observer (default: gsd-observer)
+#   GSD_OBSERVER_PANE           — pane id for Observer (default: 0.0)
+#   GSD_ARTIFACT_WINDOW_SECS    — seconds window for artifact detection (default: 30)
+#   GSD_PROJECT_DIR             — project directory to scan (default: pwd)
+#   GSD_SENTINEL_FILE           — dedup sentinel file path (default: /tmp/gsd-last-event-phase)
+#   GSD_WORKER_SESSION          — worker tmux session (default: gsd-worker)
+#   GSD_WORKER_PANE             — worker pane id (default: 0.0)
+#   GSD_DRY_RUN                 — if set, skip tmux calls and write phase= to stderr
+
+set -euo pipefail
+
+# --- Configuration ---
+OBSERVER_ENABLED="${GSD_OBSERVER_ENABLED:-}"
+OBSERVER_SESSION="${GSD_OBSERVER_SESSION:-gsd-observer}"
+OBSERVER_PANE="${GSD_OBSERVER_PANE:-0.0}"
+WINDOW_SECS="${GSD_ARTIFACT_WINDOW_SECS:-30}"
+PROJECT_DIR="${GSD_PROJECT_DIR:-$(pwd)}"
+SENTINEL_FILE="${GSD_SENTINEL_FILE:-/tmp/gsd-last-event-phase}"
+WORKER_SESSION="${GSD_WORKER_SESSION:-gsd-worker}"
+WORKER_PANE="${GSD_WORKER_PANE:-0.0}"
+DRY_RUN="${GSD_DRY_RUN:-}"
+POLL_TIMEOUT=120
+HOLD_MAX=3
+SCRIPTS_DIR="$(dirname "$0")/../scripts"
+
+# --- Guard: disabled ---
+if [ -z "$OBSERVER_ENABLED" ]; then
+  exit 0
+fi
+
+log() { echo "[gsd-hook] $*" >&2; }
+
+# --- Phase detection ---
+detect_phase() {
+  local window="$WINDOW_SECS"
+  local proj="$PROJECT_DIR"
+  local now
+  now=$(date +%s)
+  local cutoff=$((now - window))
+
+  # Helper: file modified within window?
+  recent() {
+    local f="$1"
+    [ -f "$f" ] || return 1
+    local mtime
+    mtime=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0)
+    [ "$mtime" -ge "$cutoff" ]
+  }
+
+  # Find most recent planning artifact
+  local research_file plan_file verify_file
+  research_file=$(find "$proj/.planning" -name "RESEARCH.md" 2>/dev/null | head -1 || echo "")
+  plan_file=$(find "$proj/.planning" -name "PLAN.md" 2>/dev/null | head -1 || echo "")
+  verify_file=$(find "$proj/.planning" -name "VERIFICATION.md" 2>/dev/null | head -1 || echo "")
+
+  # Check for source files modified within the time window (outside .planning)
+  # Use a sentinel file touched at the cutoff time for portable -newer comparison
+  local src_modified=0
+  local cutoff_sentinel
+  cutoff_sentinel=$(mktemp)
+  # Set mtime to cutoff using python3 for portability
+  python3 -c "import os,time; os.utime('$cutoff_sentinel', (time.time()-${window}, time.time()-${window}))" 2>/dev/null || true
+  if find "$proj" -not -path "*/.planning/*" -not -path "*/.git/*" \
+      -newer "$cutoff_sentinel" \( \
+        -name "*.swift" -o -name "*.py" -o -name "*.ts" -o \
+        -name "*.js" -o -name "*.go" -o -name "*.rs" \
+      \) 2>/dev/null | grep -q .; then
+    src_modified=1
+  fi
+  rm -f "$cutoff_sentinel"
+
+  # Execute: PLAN.md recent + source files modified
+  if recent "$plan_file" && [ "$src_modified" -eq 1 ]; then
+    echo "execute $plan_file"
+    return
+  fi
+
+  # Verify: VERIFICATION.md recent
+  if recent "$verify_file"; then
+    echo "verify $verify_file"
+    return
+  fi
+
+  # Plan: PLAN.md recent (no source modifications)
+  if recent "$plan_file"; then
+    echo "plan $plan_file"
+    return
+  fi
+
+  # Research: RESEARCH.md recent
+  if recent "$research_file"; then
+    echo "research $research_file"
+    return
+  fi
+
+  # Nothing detected
+  echo ""
+}
+
+# --- Main ---
+
+detection=$(detect_phase)
+if [ -z "$detection" ]; then
+  exit 0
+fi
+
+phase=$(echo "$detection" | cut -d' ' -f1)
+artifact_file=$(echo "$detection" | cut -d' ' -f2-)
+
+log "phase=${phase} artifact=${artifact_file}"
+
+# --- Deduplication ---
+artifact_mtime=$(stat -f %m "$artifact_file" 2>/dev/null || stat -c %Y "$artifact_file" 2>/dev/null || echo 0)
+sentinel_key="${phase}:${artifact_mtime}"
+
+if [ -f "$SENTINEL_FILE" ]; then
+  last=$(cat "$SENTINEL_FILE")
+  if [ "$last" = "$sentinel_key" ]; then
+    log "dedup: skipping repeated event for $sentinel_key"
+    exit 0
+  fi
+  # Also check: if the sentinel's mtime component matches any recent artifact's mtime,
+  # the session was already processed (e.g. phase label changed but same artifact window).
+  last_mtime=$(echo "$last" | cut -d: -f2)
+  if [ -n "$last_mtime" ] && [ "$last_mtime" = "$artifact_mtime" ]; then
+    log "dedup: skipping repeated event for $sentinel_key (mtime match)"
+    exit 0
+  fi
+  # Also check all planning artifacts' mtimes against the sentinel's mtime
+  proj="$PROJECT_DIR"
+  while IFS= read -r -d '' f; do
+    fmtime=$(stat -f %m "$f" 2>/dev/null || stat -c %Y "$f" 2>/dev/null || echo 0)
+    if [ "$fmtime" = "$last_mtime" ]; then
+      log "dedup: skipping repeated event for $sentinel_key (artifact $f mtime match)"
+      exit 0
+    fi
+  done < <(find "$proj/.planning" \( -name "RESEARCH.md" -o -name "PLAN.md" -o -name "VERIFICATION.md" \) -print0 2>/dev/null)
+fi
+
+# Update sentinel
+echo "$sentinel_key" > "$SENTINEL_FILE"
+
+# --- Map phase to observer_mode ---
+case "$phase" in
+  research) observer_mode="audit" ;;
+  plan)     observer_mode="block" ;;
+  execute)  observer_mode="augment" ;;
+  verify)   observer_mode="audit" ;;
+  *)        observer_mode="audit" ;;
+esac
+
+# --- Generate event_id ---
+event_id=$(uuidgen 2>/dev/null || date +%s%N | md5sum | cut -c1-8)
+
+# --- Collect changed files ---
+changed_files="[]"
+if command -v git &>/dev/null && git -C "$PROJECT_DIR" rev-parse --git-dir &>/dev/null; then
+  cf=$(git -C "$PROJECT_DIR" diff --name-only HEAD 2>/dev/null | \
+    grep -v "^\.planning" | \
+    python3 -c "import sys,json; lines=[l.strip() for l in sys.stdin if l.strip()]; print(json.dumps(lines))" 2>/dev/null || echo "[]")
+  changed_files="$cf"
+fi
+
+# --- Find planning artifacts ---
+plan_path=$(find "$PROJECT_DIR/.planning" -name "PLAN.md" 2>/dev/null | head -1 || echo "null")
+research_path=$(find "$PROJECT_DIR/.planning" -name "RESEARCH.md" 2>/dev/null | head -1 || echo "null")
+
+[ -f "$plan_path" ] || plan_path="null"
+[ -f "$research_path" ] || research_path="null"
+
+# --- Write event JSON atomically ---
+event_file="/tmp/gsd-event-${event_id}.json"
+timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+cat > "${event_file}.tmp" <<EOF
+{
+  "event_id": "${event_id}",
+  "event_type": "phase_complete",
+  "gsd_phase": "${phase}",
+  "observer_mode": "${observer_mode}",
+  "context_summary": "${phase} phase detected: ${artifact_file}",
+  "artifacts": {
+    "plan": $([ "$plan_path" = "null" ] && echo "null" || echo "\"$plan_path\""),
+    "research": $([ "$research_path" = "null" ] && echo "null" || echo "\"$research_path\""),
+    "changed_files": ${changed_files},
+    "test_results": null
+  },
+  "worker_session": "${WORKER_SESSION}",
+  "worker_pane": "${WORKER_SESSION}:${WORKER_PANE}",
+  "project_dir": "${PROJECT_DIR}",
+  "timestamp": "${timestamp}"
+}
+EOF
+mv "${event_file}.tmp" "$event_file"
+log "Event written: $event_file"
+
+# --- Dry run: skip tmux and polling ---
+if [ -n "$DRY_RUN" ]; then
+  log "DRY_RUN: would wake observer and poll for response"
+  exit 0
+fi
+
+# --- Wake Observer ---
+"$SCRIPTS_DIR/wake-observer.sh" "$event_id" "$OBSERVER_SESSION" "$OBSERVER_PANE" || {
+  log "WARNING: wake-observer.sh failed — continuing without Observer"
+  exit 0
+}
+
+# --- Poll for response ---
+response_file="/tmp/gsd-response-${event_id}.json"
+hold_count=0
+elapsed=0
+
+log "Polling for Observer response (max ${POLL_TIMEOUT}s)..."
+
+while [ "$elapsed" -lt "$POLL_TIMEOUT" ]; do
+  if [ -f "$response_file" ]; then
+    # Validate event_id matches
+    resp_event_id=$(jq -r '.event_id // ""' "$response_file" 2>/dev/null || echo "")
+    if [ "$resp_event_id" != "$event_id" ]; then
+      # Mismatch — skip and keep polling
+      sleep 1
+      elapsed=$((elapsed+1))
+      continue
+    fi
+
+    decision=$(jq -r '.decision // "proceed"' "$response_file" 2>/dev/null || echo "proceed")
+    log "Observer decision: $decision"
+
+    if [ "$decision" = "hold" ]; then
+      hold_count=$((hold_count+1))
+      if [ "$hold_count" -ge "$HOLD_MAX" ]; then
+        log "Max hold cycles reached ($HOLD_MAX) — proceeding"
+        break
+      fi
+      log "Observer hold (cycle $hold_count/$HOLD_MAX) — resetting timer"
+      elapsed=0
+      # Remove response file so we detect the next overwrite
+      rm -f "$response_file"
+      continue
+    fi
+
+    # proceed or revise — done
+    break
+  fi
+
+  sleep 1
+  elapsed=$((elapsed+1))
+done
+
+if [ "$elapsed" -ge "$POLL_TIMEOUT" ]; then
+  log "WARNING: Observer did not respond in ${POLL_TIMEOUT}s — Worker continuing unblocked"
+fi
+
+exit 0

package/templates/schema/event.json

@@ -0,0 +1,18 @@
+{
+  "_comment": "Event written by gsd-stop-hook.sh. Named /tmp/gsd-event-<event_id>.json",
+  "event_id": "a3f9c1d2",
+  "event_type": "phase_complete",
+  "gsd_phase": "execute",
+  "observer_mode": "augment",
+  "context_summary": "Execute phase detected: src/auth/login.swift modified",
+  "artifacts": {
+    "plan": "/Users/user/project/.planning/phase-3/PLAN.md",
+    "research": "/Users/user/project/.planning/phase-3/RESEARCH.md",
+    "changed_files": ["src/auth/login.swift", "src/auth/session.swift"],
+    "test_results": "/tmp/gsd-test-results-a3f9c1d2.txt"
+  },
+  "worker_session": "gsd-worker",
+  "worker_pane": "gsd-worker:0.0",
+  "project_dir": "/Users/user/project",
+  "timestamp": "2026-03-16T10:00:00Z"
+}

package/templates/schema/response.json

@@ -0,0 +1,14 @@
+{
+  "_comment": "Response written by Observer Claude. Named /tmp/gsd-response-<event_id>.json",
+  "_decision_values": "proceed | revise | hold",
+  "event_id": "a3f9c1d2",
+  "decision": "revise",
+  "mode": "augment",
+  "observations": [
+    "Auth module missing input validation on login handler",
+    "Unit tests pass but no integration test for session expiry"
+  ],
+  "message": "Two issues found. Fix input validation before proceeding.",
+  "revision_instructions": "Add input validation to src/auth/login.swift login() function. Validate email format and non-empty password before calling authenticate().",
+  "timestamp": "2026-03-16T10:00:05Z"
+}

package/templates/scripts/notify-worker.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ $# -lt 1 ]; then
+  echo "Usage: notify-worker.sh <event_id>" >&2
+  exit 1
+fi
+
+event_id="$1"
+response_file="/tmp/gsd-response-${event_id}.json"
+event_file="/tmp/gsd-event-${event_id}.json"
+
+# Verify response file exists
+if [ ! -f "$response_file" ]; then
+  echo "[notify-worker] ERROR: response file missing: $response_file" >&2
+  exit 1
+fi
+
+# Read worker_pane from event file (not response file)
+if [ ! -f "$event_file" ]; then
+  echo "[notify-worker] ERROR: event file missing: $event_file" >&2
+  exit 1
+fi
+
+worker_pane=$(jq -r '.worker_pane // empty' "$event_file" 2>/dev/null)
+if [ -z "$worker_pane" ]; then
+  echo "[notify-worker] ERROR: worker_pane not found in event file" >&2
+  exit 1
+fi
+
+# Parse response fields
+decision=$(jq -r '.decision' "$response_file")
+message=$(jq -r '.message' "$response_file")
+revision=$(jq -r '.revision_instructions // ""' "$response_file")
+
+# Build injection message
+injection="[GSD Observer] Decision: ${decision}. ${message}"
+if [ -n "$revision" ] && [ "$revision" != "null" ]; then
+  injection="${injection} Instructions: ${revision}"
+fi
+
+# Inject into Worker pane
+# Worker Claude is blocked by the Stop hook polling loop.
+# This text queues in the terminal buffer and appears when the hook exits.
+tmux send-keys -t "$worker_pane" "$injection" Enter
+
+echo "[notify-worker] Response injected into Worker pane (${worker_pane})" >&2

package/templates/scripts/start-observer.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+SESSION="${GSD_OBSERVER_SESSION:-gsd-observer}"
+tmux kill-session -t "$SESSION" 2>/dev/null || true
+tmux new-session -d -s "$SESSION"
+tmux send-keys -t "${SESSION}:0.0" "claude --allowedTools 'Bash,Read,Write,Glob,Grep'" Enter
+echo "[gsd-observer] Waiting for Observer Claude to start..."
+for i in $(seq 1 30); do
+  pane=$(tmux capture-pane -pt "${SESSION}:0.0" -l 5 2>/dev/null || echo "")
+  if echo "$pane" | grep -qE '❯|>|\$|✓|claude>'; then
+    echo "[gsd-observer] Observer ready in session: $SESSION"
+    exit 0
+  fi
+  sleep 1
+done
+echo "[gsd-observer] WARNING: Observer may not be ready — prompt not detected after 30s"
+echo "[gsd-observer] Check: tmux attach -t $SESSION"

package/templates/scripts/start-worker.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+PROJECT_DIR="${1:-$(pwd)}"
+SESSION="${GSD_WORKER_SESSION:-gsd-worker}"
+if [ ! -d "$PROJECT_DIR" ]; then
+  echo "ERROR: project directory not found: $PROJECT_DIR" >&2
+  exit 1
+fi
+echo "[gsd-worker] Cleaning up stale temp files..."
+rm -f /tmp/gsd-event-*.json /tmp/gsd-response-*.json /tmp/gsd-last-event-phase
+tmux kill-session -t "$SESSION" 2>/dev/null || true
+tmux new-session -d -s "$SESSION"
+tmux send-keys -t "${SESSION}:0.0" "cd \"$PROJECT_DIR\" && GSD_OBSERVER_ENABLED=1 claude" Enter
+echo "[gsd-worker] Worker ready in session: $SESSION"
+echo "[gsd-worker] Project: $PROJECT_DIR"
+echo ""
+echo "Next steps:"
+echo "  1. Attach to worker:   tmux attach -t $SESSION"
+echo "  2. Attach to observer: tmux attach -t ${GSD_OBSERVER_SESSION:-gsd-observer}"
+echo "  3. Begin GSD workflow in the worker session"

package/templates/scripts/teardown.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+WORKER_SESSION="${GSD_WORKER_SESSION:-gsd-worker}"
+OBSERVER_SESSION="${GSD_OBSERVER_SESSION:-gsd-observer}"
+echo "[gsd-observer] Tearing down sessions..."
+tmux kill-session -t "$WORKER_SESSION" 2>/dev/null && echo "  Killed: $WORKER_SESSION" || echo "  Not running: $WORKER_SESSION"
+tmux kill-session -t "$OBSERVER_SESSION" 2>/dev/null && echo "  Killed: $OBSERVER_SESSION" || echo "  Not running: $OBSERVER_SESSION"
+echo "[gsd-observer] Cleaning up temp files..."
+rm -f /tmp/gsd-event-*.json /tmp/gsd-response-*.json /tmp/gsd-last-event-phase
+echo "  Done."

package/templates/scripts/verify.sh

@@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+WORKER_SESSION="${GSD_WORKER_SESSION:-gsd-worker}"
+OBSERVER_SESSION="${GSD_OBSERVER_SESSION:-gsd-observer}"
+PASS=0; FAIL=0
+
+check() {
+  local desc="$1"; shift
+  if "$@" &>/dev/null; then
+    echo "  OK: $desc"; PASS=$((PASS+1))
+  else
+    echo "  MISSING: $desc"; FAIL=$((FAIL+1))
+  fi
+}
+
+echo "=== GSD Observer System Check ==="
+echo ""
+echo "--- Prerequisites ---"
+check "jq installed" command -v jq
+check "tmux installed" command -v tmux
+check "claude CLI installed" command -v claude
+
+echo ""
+echo "--- Scripts ---"
+check "gsd-stop-hook.sh executable" test -x "$HOME/.claude/gsd-observer/hooks/gsd-stop-hook.sh"
+check "wake-observer.sh executable" test -x "$HOME/.claude/gsd-observer/scripts/wake-observer.sh"
+check "notify-worker.sh executable" test -x "$HOME/.claude/gsd-observer/scripts/notify-worker.sh"
+check "start-observer.sh executable" test -x "$HOME/.claude/gsd-observer/scripts/start-observer.sh"
+check "start-worker.sh executable" test -x "$HOME/.claude/gsd-observer/scripts/start-worker.sh"
+
+echo ""
+echo "--- Sessions ---"
+check "gsd-observer tmux session running" tmux has-session -t "$OBSERVER_SESSION"
+check "gsd-worker tmux session running" tmux has-session -t "$WORKER_SESSION"
+
+if tmux has-session -t "$OBSERVER_SESSION" 2>/dev/null; then
+  pane_content=$(tmux capture-pane -pt "${OBSERVER_SESSION}:0.0" -l 5 2>/dev/null || echo "")
+  if echo "$pane_content" | grep -qE '❯|>|\$|✓|claude>'; then
+    echo "  OK: Observer Claude at prompt"; PASS=$((PASS+1))
+  else
+    echo "  MISSING: Observer Claude not at prompt (may still be starting)"; FAIL=$((FAIL+1))
+  fi
+fi
+
+echo ""
+echo "--- Project hook (run from project dir) ---"
+if [ -f ".claude/settings.json" ]; then
+  hook_registered=$(python3 -c "
+import sys, json
+with open('.claude/settings.json') as f:
+    s = json.load(f)
+hooks = s.get('hooks', {}).get('Stop', [])
+print('yes' if hooks else 'no')
+" 2>/dev/null || echo "no")
+  check "Stop hook registered in .claude/settings.json" [ "$hook_registered" = "yes" ]
+else
+  echo "  MISSING: .claude/settings.json (copy from ~/.claude/gsd-observer/templates/settings.json)"
+  FAIL=$((FAIL+1))
+fi
+
+echo ""
+echo "Results: ${PASS} OK, ${FAIL} missing"
+[ "$FAIL" -eq 0 ]

package/templates/scripts/wake-observer.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [ $# -lt 3 ]; then
+  echo "Usage: wake-observer.sh <event_id> <observer_session> <observer_pane>" >&2
+  exit 1
+fi
+
+event_id="$1"
+observer_session="$2"
+observer_pane="$3"
+full_target="${observer_session}:${observer_pane}"
+event_path="/tmp/gsd-event-${event_id}.json"
+
+# Verify event file exists before waking Observer
+if [ ! -f "$event_path" ]; then
+  echo "[wake-observer] ERROR: event file not found: $event_path" >&2
+  exit 1
+fi
+
+# Wait up to 15s for Observer pane to be at prompt
+echo "[wake-observer] Waiting for Observer pane to be ready..." >&2
+ready=0
+for i in $(seq 1 15); do
+  pane_content=$(tmux capture-pane -pt "$full_target" -l 5 2>/dev/null || echo "")
+  if echo "$pane_content" | grep -qE '❯|>|\$|✓|claude'; then
+    ready=1
+    break
+  fi
+  sleep 1
+done
+
+if [ "$ready" -eq 0 ]; then
+  echo "[wake-observer] WARNING: Observer pane not at prompt after 15s — injecting anyway" >&2
+fi
+
+# Inject task into Observer pane
+tmux send-keys -t "$full_target" \
+  "Read ${event_path} and respond as GSD Observer. Write response to /tmp/gsd-response-${event_id}.json then run ~/.claude/gsd-observer/scripts/notify-worker.sh ${event_id}" \
+  Enter
+
+echo "[wake-observer] Observer woken for event ${event_id}" >&2