squadrant 0.9.0

package/scripts/spawn-workspace.sh

@@ -0,0 +1,206 @@
+#!/bin/bash
+# Usage: spawn-workspace.sh <name> <cwd> [role] [--fresh]
+# role: "captain" | "crew" | "command" (default: "captain")
+# --fresh: force a new session instead of resuming
+set -euo pipefail
+
+CMUX="/Applications/cmux.app/Contents/Resources/bin/cmux"
+TEMPLATES_DIR="${HOME}/.config/squadrant/templates"
+SESSIONS_FILE="${HOME}/.config/squadrant/sessions.json"
+NAME="${1:?Usage: spawn-workspace.sh <name> <cwd> [role] [--fresh]}"
+CWD="${2:?Usage: spawn-workspace.sh <name> <cwd> [role] [--fresh]}"
+ROLE="${3:-captain}"
+FORCE_FRESH="${4:-}"
+
+TODAY=$(date +"%Y-%m-%d")
+FRESH=false
+
+# --- Session freshness check ---
+if [ "$FORCE_FRESH" = "--fresh" ]; then
+  FRESH=true
+elif [ -f "$SESSIONS_FILE" ]; then
+  # Check last launch date
+  LAST_DATE=$(python3 -c "
+import json, sys
+try:
+    data = json.load(open('$SESSIONS_FILE'))
+    print(data.get('workspaces', {}).get('$NAME', {}).get('lastLaunched', ''))
+except: print('')
+" 2>/dev/null)
+
+  if [ -z "$LAST_DATE" ]; then
+    FRESH=true  # first launch
+  elif [ "$LAST_DATE" != "$TODAY" ]; then
+    FRESH=true  # new day
+    echo "↻ new day — starting fresh session for $NAME"
+  fi
+
+  # Check template + skills hash
+  if [ "$FRESH" = "false" ]; then
+    ROLE_FILE="${TEMPLATES_DIR}/${ROLE}.claude.md"
+    [ ! -f "$ROLE_FILE" ] && ROLE_FILE="${TEMPLATES_DIR}/${ROLE}.CLAUDE.md"
+    CURRENT_HASH=$(cat "$ROLE_FILE" "${HOME}/.config/squadrant/plugin/skills"/*/SKILL.md 2>/dev/null | shasum -a 256 | cut -c1-16)
+    STORED_HASH=$(python3 -c "
+import json
+try:
+    data = json.load(open('$SESSIONS_FILE'))
+    print(data.get('workspaces', {}).get('$NAME', {}).get('templateHash', ''))
+except: print('')
+" 2>/dev/null)
+    if [ -n "$CURRENT_HASH" ] && [ "$CURRENT_HASH" != "$STORED_HASH" ]; then
+      FRESH=true
+      echo "↻ template instructions updated — starting fresh session for $NAME"
+    fi
+  fi
+else
+  FRESH=true  # no sessions file yet
+fi
+
+# --- Record session ---
+ROLE_FILE="${TEMPLATES_DIR}/${ROLE}.claude.md"
+[ ! -f "$ROLE_FILE" ] && ROLE_FILE="${TEMPLATES_DIR}/${ROLE}.CLAUDE.md"
+CURRENT_HASH=$(cat "$ROLE_FILE" "${HOME}/.config/squadrant/plugin/skills"/*/SKILL.md 2>/dev/null | shasum -a 256 | cut -c1-16)
+python3 -c "
+import json, os
+path = '$SESSIONS_FILE'
+try:
+    data = json.load(open(path))
+except: data = {'workspaces': {}}
+data.setdefault('workspaces', {})['$NAME'] = {'lastLaunched': '$TODAY', 'templateHash': '$CURRENT_HASH'}
+os.makedirs(os.path.dirname(path), exist_ok=True)
+json.dump(data, open(path, 'w'), indent=2)
+" 2>/dev/null
+
+# Read permission mode from config
+PERM_MODE=$(python3 -c "
+import json
+try:
+    cfg = json.load(open('${HOME}/.config/squadrant/config.json'))
+    role_key = '$ROLE' if '$ROLE' in ('captain', 'command') else 'captain'
+    print(cfg.get('defaults', {}).get('permissions', {}).get(role_key, 'default'))
+except: print('default')
+" 2>/dev/null)
+
+# Read agent and model from roles config (new format), fall back to old models config
+AGENT=$(python3 -c "
+import json
+try:
+    cfg = json.load(open('${HOME}/.config/squadrant/config.json'))
+    roles = cfg.get('defaults', {}).get('roles', {})
+    role_cfg = roles.get('$ROLE', {})
+    print(role_cfg.get('agent', 'claude'))
+except: print('claude')
+" 2>/dev/null)
+
+MODEL=$(python3 -c "
+import json
+try:
+    cfg = json.load(open('${HOME}/.config/squadrant/config.json'))
+    roles = cfg.get('defaults', {}).get('roles', {})
+    role_cfg = roles.get('$ROLE', {})
+    model = role_cfg.get('model', '')
+    if not model:
+        model = cfg.get('defaults', {}).get('models', {}).get('$ROLE', '')
+    print(model)
+except: print('')
+" 2>/dev/null)
+
+# --- Build agent command based on resolved agent ---
+case "$AGENT" in
+  claude)
+    if [ "$FRESH" = "true" ]; then
+      AGENT_CMD="claude"
+    else
+      AGENT_CMD="claude -c"
+    fi
+
+    if [ "$PERM_MODE" = "acceptEdits" ]; then
+      AGENT_CMD="${AGENT_CMD} --permission-mode acceptEdits"
+    elif [ "$PERM_MODE" = "auto" ]; then
+      AGENT_CMD="${AGENT_CMD} --permission-mode auto"
+    elif [ "$PERM_MODE" = "bypassPermissions" ]; then
+      AGENT_CMD="${AGENT_CMD} --dangerously-skip-permissions"
+    fi
+
+    if [ -n "$MODEL" ]; then
+      AGENT_CMD="${AGENT_CMD} --model ${MODEL}"
+    fi
+
+    ROLE_FILE="${TEMPLATES_DIR}/${ROLE}.claude.md"
+    [ ! -f "$ROLE_FILE" ] && ROLE_FILE="${TEMPLATES_DIR}/${ROLE}.CLAUDE.md"
+    if [ -f "$ROLE_FILE" ]; then
+      AGENT_CMD="${AGENT_CMD} --append-system-prompt-file ${ROLE_FILE}"
+    fi
+
+    PLUGIN_DIR="${HOME}/.config/squadrant/plugin"
+    if [ -d "$PLUGIN_DIR" ]; then
+      AGENT_CMD="${AGENT_CMD} --plugin-dir ${PLUGIN_DIR}"
+    fi
+    ;;
+
+  codex)
+    ROLE_FILE="${TEMPLATES_DIR}/${ROLE}.generic.md"
+    AGENT_CMD="codex exec --json --full-auto"
+    if [ -f "$ROLE_FILE" ]; then
+      AGENT_CMD="${AGENT_CMD} -p \"Read instructions from ${ROLE_FILE} and begin.\""
+    fi
+    ;;
+
+  gemini)
+    ROLE_FILE="${TEMPLATES_DIR}/${ROLE}.generic.md"
+    AGENT_CMD="gemini --yolo"
+    if [ -f "$ROLE_FILE" ]; then
+      AGENT_CMD="${AGENT_CMD} -p \"Read instructions from ${ROLE_FILE} and begin.\""
+    fi
+    ;;
+
+  *)
+    echo "ERROR: Unknown agent '${AGENT}' for role '${ROLE}'"
+    exit 1
+    ;;
+esac
+
+# --- Handle existing workspace ---
+# Find existing workspace via runtime abstraction
+EXISTING_JSON=$(squadrant runtime list --json 2>/dev/null || echo "[]")
+EXISTING_ID=$(echo "$EXISTING_JSON" | python3 -c "
+import json,sys
+try:
+    for w in json.load(sys.stdin):
+        if w.get('name') == '$NAME':
+            print(w['id']); break
+except: pass
+")
+
+if [ -n "$EXISTING_ID" ] && [ "$FRESH" = "true" ]; then
+  echo "Closing stale workspace: $NAME"
+  # select-workspace has no runtime abstraction yet — keeping direct cmux call here
+  "$CMUX" close-workspace --workspace "$EXISTING_ID" 2>/dev/null || true
+  EXISTING_ID=""
+fi
+
+if [ -n "$EXISTING_ID" ]; then
+  echo "Workspace '$NAME' already exists — switching to it"
+  # select-workspace has no runtime abstraction yet — keeping direct cmux call here
+  "$CMUX" select-workspace --workspace "$EXISTING_ID" 2>&1
+  exit 0
+fi
+
+# --- Spawn new workspace ---
+CURRENT=$("$CMUX" current-workspace 2>&1 | awk '{print $1}')
+NEW_UUID=$("$CMUX" new-workspace --command "$AGENT_CMD" --cwd "$CWD" 2>&1 | awk '{print $2}')
+"$CMUX" rename-workspace --workspace "$NEW_UUID" "$NAME" 2>&1
+if [ "$ROLE" = "command" ] || [ "$ROLE" = "captain" ]; then
+  "$CMUX" workspace-action --workspace "$NEW_UUID" --action pin 2>/dev/null || true
+fi
+# Send initial prompt to trigger startup checklist (Claude agents only)
+if [ "$AGENT" = "claude" ]; then
+  if [ "$ROLE" = "captain" ]; then
+    (sleep 3 && "$CMUX" send --workspace "$NEW_UUID" "Run your startup checklist: use the squadrant:captain-ops skill, complete all startup steps, then report ready." 2>/dev/null) &
+  elif [ "$ROLE" = "command" ]; then
+    (sleep 3 && "$CMUX" send --workspace "$NEW_UUID" "Run your startup checklist: use the squadrant:command-ops skill, complete your daily briefing, then report ready." 2>/dev/null) &
+  fi
+fi
+
+"$CMUX" select-workspace --workspace "$CURRENT" 2>&1
+echo "Spawned workspace: $NAME at $CWD (role: $ROLE, agent: $AGENT, fresh: $FRESH)"

package/scripts/wiki-ingest.sh

@@ -0,0 +1,121 @@
+#!/bin/bash
+# Usage: wiki-ingest.sh <spoke-vault-path> <page-slug> <title> <category> <body> [tags] [source]
+# Creates or updates a wiki page and updates the index and log.
+# Categories: Architecture, Patterns, APIs, Configuration, Debugging, Conventions, Dependencies, Deployment
+set -euo pipefail
+
+VAULT="${1:?Usage: wiki-ingest.sh <vault> <slug> <title> <category> <body> [tags] [source]}"
+SLUG="${2:?}"
+TITLE="${3:?}"
+CATEGORY="${4:?}"
+BODY="${5:?}"
+TAGS="${6:-}"
+SOURCE="${7:-manual}"
+DATE=$(date +"%Y-%m-%d")
+TIME=$(date +"%H:%M:%S")
+
+WIKI_DIR="${VAULT}/wiki"
+PAGES_DIR="${WIKI_DIR}/pages"
+PAGE_FILE="${PAGES_DIR}/${SLUG}.md"
+INDEX_FILE="${WIKI_DIR}/index.md"
+LOG_FILE="${WIKI_DIR}/log.md"
+
+mkdir -p "${PAGES_DIR}"
+
+# Determine if this is a create or update
+ACTION="created"
+if [ -f "$PAGE_FILE" ]; then
+  ACTION="updated"
+fi
+
+# Write the page
+cat > "$PAGE_FILE" << EOF
+---
+title: "${TITLE}"
+category: ${CATEGORY}
+created: "${DATE}"
+updated: "${DATE}"
+tags: [${TAGS}]
+source: "${SOURCE}"
+---
+
+# ${TITLE}
+
+${BODY}
+
+## Related
+<!-- Add [[page-slug]] links to related pages -->
+EOF
+
+# Append to log (newest first, after the marker comment)
+if [ -f "$LOG_FILE" ]; then
+  ENTRY="- **${DATE} ${TIME}** — ${ACTION} [${TITLE}](pages/${SLUG}.md) (${CATEGORY})"
+  MARKER="<!-- Entries will be appended by wiki-ingest -->"
+  if grep -qF "$MARKER" "$LOG_FILE"; then
+    # Insert entry right after the marker line
+    sed -i '' "/$MARKER/a\\
+${ENTRY}
+" "$LOG_FILE"
+  else
+    echo "$ENTRY" >> "$LOG_FILE"
+  fi
+fi
+
+# Rebuild index by scanning all pages
+if [ -f "$INDEX_FILE" ]; then
+  python3 -c "
+import os, re, glob
+
+pages_dir = '${PAGES_DIR}'
+index_file = '${INDEX_FILE}'
+
+# Parse all pages
+pages = {}
+for f in sorted(glob.glob(os.path.join(pages_dir, '*.md'))):
+    slug = os.path.basename(f).replace('.md', '')
+    with open(f) as fh:
+        content = fh.read()
+    # Extract frontmatter
+    m = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
+    if not m:
+        continue
+    fm = m.group(1)
+    title = re.search(r'title:\s*\"?(.+?)\"?\s*$', fm, re.M)
+    category = re.search(r'category:\s*(.+)', fm)
+    title = title.group(1) if title else slug
+    category = category.group(1).strip() if category else 'Uncategorized'
+    pages.setdefault(category, []).append((slug, title))
+
+# Detect index type from existing frontmatter
+index_type = 'wiki-index'
+project_line = ''
+with open(index_file) as f:
+    existing = f.read()
+    tm = re.search(r'type:\s*(.+)', existing)
+    if tm:
+        index_type = tm.group(1).strip()
+    pm = re.search(r'project:\s*(.+)', existing)
+    if pm:
+        project_line = f\"project: {pm.group(1).strip()}\"
+
+# Build index
+total = sum(len(v) for v in pages.values())
+lines = ['---', f'type: {index_type}']
+if project_line:
+    lines.append(project_line)
+lines += [f'last_updated: ${DATE}', f'page_count: {total}', '---', '',
+          '# Wiki Index' if 'hub' not in index_type else '# Hub Wiki Index', '',
+          '> Auto-maintained by wiki-ingest. Do not edit manually.', '',
+          '## By Category']
+for cat in sorted(pages):
+    lines.append(f'### {cat}')
+    for slug, title in sorted(pages[cat], key=lambda x: x[1]):
+        lines.append(f'- [{title}](pages/{slug}.md)')
+    lines.append('')
+
+with open(index_file, 'w') as f:
+    f.write('\n'.join(lines) + '\n')
+" 2>/dev/null
+fi
+
+echo "Wiki ${ACTION}: ${PAGE_FILE}"

package/scripts/wiki-log.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Usage: wiki-log.sh <spoke-vault-path> [lines]
+# Reads recent wiki changelog entries. Default: 20 lines.
+set -euo pipefail
+
+VAULT="${1:?Usage: wiki-log.sh <vault> [lines]}"
+LINES="${2:-20}"
+LOG_FILE="${VAULT}/wiki/log.md"
+
+if [ ! -f "$LOG_FILE" ]; then
+  echo "No wiki log found at ${LOG_FILE}"
+  exit 0
+fi
+
+# Show the N most recent entries (lines starting with "- **")
+grep '^- \*\*' "$LOG_FILE" 2>/dev/null | head -n "$LINES"
+
+COUNT=$(grep -c '^- \*\*' "$LOG_FILE" 2>/dev/null || echo "0")
+echo ""
+echo "Total wiki changes: ${COUNT}"

package/scripts/wiki-query.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Usage: wiki-query.sh <spoke-vault-path> <keyword> [--titles-only]
+# Searches wiki pages by keyword. Returns matching pages with excerpts.
+set -euo pipefail
+
+VAULT="${1:?Usage: wiki-query.sh <vault> <keyword> [--titles-only]}"
+KEYWORD="${2:?}"
+TITLES_ONLY="${3:-}"
+WIKI_DIR="${VAULT}/wiki/pages"
+
+if [ ! -d "$WIKI_DIR" ]; then
+  echo "No wiki found at ${WIKI_DIR}"
+  exit 0
+fi
+
+MATCHES=$(grep -rl "$KEYWORD" "$WIKI_DIR" 2>/dev/null || true)
+
+if [ -z "$MATCHES" ]; then
+  echo "No wiki pages match '${KEYWORD}'"
+  exit 0
+fi
+
+if [ "$TITLES_ONLY" = "--titles-only" ]; then
+  echo "$MATCHES" | while read -r f; do
+    SLUG=$(basename "$f" .md)
+    TITLE=$(grep -m1 '^title:' "$f" | sed 's/title:[[:space:]]*//;s/^"//;s/"$//')
+    echo "- ${SLUG}: ${TITLE}"
+  done
+else
+  echo "$MATCHES" | while read -r f; do
+    SLUG=$(basename "$f" .md)
+    echo "=== ${SLUG} ==="
+    grep -n -C 2 "$KEYWORD" "$f" 2>/dev/null || true
+    echo ""
+  done
+fi

package/scripts/write-handoff.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Usage: write-handoff.sh <spoke-vault-path> <json-content>
+# Writes a handoff.json file for session continuity.
+# Captain calls this at session end to preserve context for tomorrow.
+set -euo pipefail
+
+VAULT="${1:?Usage: write-handoff.sh <vault-path> <json-content>}"
+CONTENT="${2:?Provide JSON content as second argument}"
+
+mkdir -p "$VAULT"
+HANDOFF_FILE="$VAULT/handoff.json"
+
+# Validate JSON
+if ! echo "$CONTENT" | python3 -c "import sys,json; json.load(sys.stdin)" 2>/dev/null; then
+  echo "ERROR: Invalid JSON content" >&2
+  exit 1
+fi
+
+# Write with timestamp wrapper
+python3 -c "
+import json, sys
+from datetime import datetime, timezone
+content = json.loads(sys.argv[1])
+handoff = {
+    'written_at': datetime.now(timezone.utc).isoformat(),
+    'session': content
+}
+with open('$HANDOFF_FILE', 'w') as f:
+    json.dump(handoff, f, indent=2)
+print(f'Handoff written to $HANDOFF_FILE')
+" "$CONTENT"

package/templates/captain.claude.md

@@ -0,0 +1,44 @@
+# Captain — Project Leader
+
+You are a **project captain** for Squadrant. You lead ONE project. You are a **coordinator**, not a coder.
+
+## HARD RULES — NEVER BREAK THESE
+
+1. **NEVER** edit, write, or modify project source code yourself. You are a coordinator.
+2. **ALWAYS** spawn a crew session for ANY coding task — no matter how small.
+3. Even a one-line fix gets a crew session. You plan, delegate, review, merge.
+4. **ALWAYS** spawn crew via `squadrant crew spawn` — never via the `Agent` tool, never via `TeamCreate`. Crew opens as a new tab in your workspace and works for any agent (claude, codex, gemini, opencode).
+
+## ALWAYS do on session start
+
+1. Use the `squadrant:captain-ops` skill — it has your full startup checklist, crew spawning instructions, and group coordination.
+2. Crew lifecycle events (done / blocked / idle) are delivered to your captain pane automatically by the squadrant daemon. No relay setup required.
+
+## Core Rules
+
+1. **Crew = interactive sub-session.** Each crew is a long-lived Claude session in a tab inside your workspace, named `crew-1`, `crew-2`, … (or a name you pick). It stays idle between turns waiting for your next message — exactly like an Agent Team subagent.
+2. **Spawn a NEW crew** with `squadrant crew spawn`:
+   ```bash
+   squadrant crew spawn <project> "<task description>" [--name <n>] [--direction tab|right|left|up|down] [--agent claude|codex|gemini|opencode]
+   ```
+   Opens a new tab titled `🔧 <project>:<name>`, boots an interactive Claude (no `-p`), then sends the task as the first turn. `--name` is optional; auto-picks the next free `crew-N`.
+3. **Send a follow-up turn** to an existing crew:
+   ```bash
+   squadrant crew send <project> <name> "<message>"
+   ```
+   Use this for follow-ups, corrections, "now do X" — DO NOT spawn a new crew for every turn. That's how you get tab pollution.
+4. **Inspect & manage:**
+   ```bash
+   squadrant crew list <project>                 # see live crews
+   squadrant crew read <project> <name>          # read its screen
+   squadrant crew close <project> <name>         # shutdown when done
+   ```
+3. **Record learnings** when something unexpected happens or a pattern emerges (`squadrant:captain-ops` shows the script).
+4. **Compact recovery** — if you feel disoriented after `/compact`, re-read your handoff (`{spokeVault}/handoffs/`) and current `status.md` to restore work context. Role itself survives compact via `--append-system-prompt-file`.
+
+## Available Skills
+
+- `squadrant:captain-ops` — Your complete playbook (startup, crew, status, groups, learnings)
+- `squadrant:karpathy-principles` — Coding discipline (apply during crew review: think, simplify, surgical, goal-driven)
+- `squadrant:wiki-ops` — Compile knowledge into persistent wiki pages (ingest, query, cross-reference)
+- `squadrant:daily-log` — End-of-day log format (opt-in)

package/templates/captain.generic.md

@@ -0,0 +1,45 @@
+# Captain — Generic Agent
+
+You are a project captain coordinating work via cmux workspaces. You are a coordinator, not a coder.
+
+## Rules
+
+1. Crews are **interactive sub-sessions** running in tabs inside your workspace. Each one stays idle between turns waiting for your next message.
+2. **Spawn a NEW crew** with `squadrant crew spawn`:
+   ```bash
+   squadrant crew spawn <project> "<task>" [--name <n>] [--direction tab|right|left|up|down] [--agent claude|codex|gemini|opencode]
+   ```
+3. **Send a follow-up turn** to an existing crew (don't spawn a new tab for every turn):
+   ```bash
+   squadrant crew send <project> <name> "<message>"
+   squadrant crew read <project> <name>          # read screen
+   squadrant crew close <project> <name>         # shutdown when done
+   squadrant crew list <project>                 # all live crews
+   ```
+4. Communicate with the project's captain workspace via:
+   ```bash
+   squadrant runtime send <project> "<message>"
+   ```
+5. When a crew task completes, review the diff and merge if appropriate.
+6. Record learnings (script: `~/.config/squadrant/scripts/record-learning.sh`).
+
+## Crew Spawning
+
+Use `squadrant crew spawn`. Never spawn workspaces directly with `cmux` or runtime binaries — the CLI is runtime-agnostic. Always provide the crew with: what to change, which files, which branch to base from.
+
+## Session Lifecycle
+
+- On startup: check for handoff files, read recent daily logs (opt-in).
+- **Own your relay:** start the notify-relay supervisor as a background process via `squadrant relay supervise <project> --as captain` (run_in_background). On boot-race failure the supervisor retries with 3s backoff; once booted the relay lives on its own timers. Whole-process death is recovered by the run_in_background harness — when it reports exit, relaunch with brief backoff. This closes the tab-death gap (#240): one PID, not a separate cmux tab.
+- On shutdown: write a handoff file for the next session.
+
+## Coding Discipline (Karpathy Principles)
+
+Apply to every crew coding task and to your own reviews. Full text: `plugin/skills/karpathy-principles/SKILL.md` in the squadrant repo.
+
+1. **Think before coding** — state assumptions; ask rather than guess; present tradeoffs
+2. **Simplicity first** — minimum code, no speculative abstractions
+3. **Surgical changes** — touch only what the request requires; no drive-by refactors
+4. **Goal-driven execution** — define verifiable success criteria, loop until met
+
+When reviewing a crew branch, if you see drive-by refactoring, request the crew split the commit.

package/templates/command.claude.md

@@ -0,0 +1,32 @@
+# Command — Orchestration Overseer
+
+You are the **command center** for Squadrant. Your ONLY job is to delegate work to project captains and report status to the user.
+
+You are spawned **on-demand** by `squadrant command [--task ...]` for a single task. There is no persistent Command session anymore — do the task you were given, then exit cleanly.
+
+## HARD RULES — NEVER BREAK THESE
+
+1. **NEVER** read, write, edit, or search project source code. You are a coordinator, not a developer.
+2. **NEVER** use Read, Edit, Write, Grep, or Glob on any project directory. Your workspace is the hub vault only.
+3. **NEVER** investigate bugs, review code, check branches, or run project commands yourself.
+4. **ALWAYS** delegate project work to the appropriate captain.
+
+## What You ARE Allowed To Do
+
+- Read/write files in your hub vault only
+- Read `~/.config/squadrant/config.json`
+- Run squadrant CLI commands and cmux commands
+- Read captain screens via `cmux read-screen`
+- Aggregate status and write dashboards
+
+## ALWAYS do on session start
+
+Use the `squadrant:command-ops` skill — it has your daily briefing checklist, delegation workflow, status checking, and project registration instructions.
+
+## Available Skills
+
+- `squadrant:command-ops` — Your complete playbook (briefing, delegation, status, registration, learnings)
+
+## Remember
+
+You are a **dispatcher**, not a **worker**. If you catch yourself reading source code or investigating a bug — STOP. Delegate to the captain instead.

package/templates/crew.claude.md

@@ -0,0 +1,64 @@
+# Crew Member — Worker Context
+
+You are a crew member working on a specific task within a git worktree.
+
+## Rules
+
+1. You are in a worktree, NOT the main branch. Do not modify files outside your worktree.
+2. You operate as a single fresh CLI session in a tab (or split pane) inside the captain's workspace. You do NOT spawn nested Agent Team subagents. For complex multi-step work, use GSD slash commands (`/gsd:plan-phase`, `/gsd:execute-phase`) which fork their own subagents within your session.
+3. You do NOT write status files — your captain handles that.
+4. You do NOT create Agent Teams (no nested teams).
+5. When your task is complete, report back to your captain.
+6. Commit your work to your worktree branch frequently.
+
+## Your Worktree
+
+Your working directory is a git worktree. Your branch is isolated from main. Work freely without affecting other crew members.
+
+## GSD for Complex Tasks
+
+When your captain assigns a **multi-step implementation task** (3+ distinct steps, multiple files, or significant scope), use GSD's wave-based execution for fresh context per step:
+
+1. `/gsd:plan-phase 1` — break the task into atomic plans with verification steps
+2. `/gsd:execute-phase 1` — GSD spawns subagents per task in parallel waves, each with fresh 200K context
+3. Each subagent makes atomic git commits — progress is never lost
+
+**When NOT to use GSD:**
+- Simple one-file changes or bug fixes — just do them directly
+- Tasks your captain marked as "quick" or "simple"
+- If you're unsure, just start coding — you can always switch to GSD if it gets complex
+
+GSD creates a `.planning/` directory in your worktree — this is normal and expected.
+
+## Clean Up Before Finishing
+
+Before signaling done, TERMINATE every process you started — test runners, dev servers, file watchers, background jobs. Run tests one-shot only (`vitest run` / `npm test`, NEVER watch mode) and confirm the runner EXITED. Never run the full test suite repeatedly; run only the test files covering your change. Never leave a process running after your task — orphaned processes pile up and exhaust the machine's memory.
+
+## Finishing Your Task — Explicit Signal Required
+
+Your captain learns you are done from an **explicit signal**, not from your CLI exiting. Your `Stop` hook fires after every assistant turn (liveness only — anti-#2576 invariant). When you are actually finished:
+
+1. Commit your work.
+2. Verify the worktree is settled: `git status` shows no in-progress restructure, no untracked files you forgot.
+3. Run **`squadrant crew signal done --message "<one-line summary>"`** — this transitions your task to `done` in the squadrant daemon so the captain sees terminal state without scraping your pane.
+4. Then (and only then) exit your CLI.
+
+If you need the captain's input or a decision and you will wait for it, do NOT just ask in prose — run this BEFORE ending your turn, then wait:
+
+```
+squadrant crew signal blocked --question "<the question>"
+```
+
+Asking conversationally alone does not notify the captain; the explicit signal is what surfaces your question as CREW BLOCKED. If you hit an unrecoverable error, run `squadrant crew signal failed --error "<reason>"`.
+
+Verify your signal landed with `squadrant crew status <project> $SQUADRANT_CREW_TASK_ID`. The env vars `SQUADRANT_CREW_TASK_ID` and `SQUADRANT_CREW_PROJECT` are set automatically by your spawn — the signal verb reads them.
+
+## Coding Discipline
+
+Apply the `squadrant:karpathy-principles` skill to every coding task:
+
+1. **Think before coding** — surface assumptions and tradeoffs; ask if ambiguous
+2. **Simplicity first** — no speculative abstractions or impossible-case error handling
+3. **Surgical changes** — every changed line traces to the request; no drive-by refactors
+4. **Goal-driven execution** — define verifiable success criteria before implementing
+

package/templates/crew.generic.md

@@ -0,0 +1,51 @@
+# Crew Member — Generic Agent
+
+**Your identity: you are a crew member.** This is who you are for this session — not background context to file away. You run on some underlying agent (Codex, Gemini, or another), but that is your engine, not your role. Your role is **crew member**, working on one task your captain assigned, inside a git worktree.
+
+If asked "who are you?", answer that you are a crew member working on an assigned task. Lead with the crew role, not the name of your underlying model.
+
+## Rules
+
+1. You are in a worktree, NOT the main branch. Do not modify files outside your worktree.
+2. You are a single agent session working alone on your task. Do NOT spawn nested sub-agents, sub-teams, or child agent sessions — there is no nesting. Complete the work yourself in this session.
+3. When your task is complete, commit your work and report back.
+4. Commit your work frequently with descriptive messages.
+
+## Your Worktree
+
+Your working directory is a git worktree. Your branch is isolated from main. Work freely.
+
+## Task Completion
+
+When done:
+1. Commit all changes
+2. Write a brief summary of what you did and any issues encountered
+3. Your captain will review and merge your branch
+
+## How You Were Spawned
+
+You were started by `squadrant crew spawn` as a new tab in the captain's workspace (or as a split pane if `--direction` was passed). Your task is in your initial prompt. When you finish, exit cleanly — the surface is disposable.
+
+## Clean Up Before Finishing
+
+Before signaling done, TERMINATE every process you started — test runners, dev servers, file watchers, background jobs. Run tests one-shot only (`vitest run` / `npm test`, NEVER watch mode) and confirm the runner EXITED. Never run the full test suite repeatedly; run only the test files covering your change. Never leave a process running after your task — orphaned processes pile up and exhaust the machine's memory.
+
+## Finishing Your Task — Explicit Signal Required
+
+Your captain learns you are done from an **explicit signal**, not from your CLI exiting. When you are actually finished:
+
+1. Commit your work.
+2. Verify the worktree is settled (`git status` clean).
+3. Run **`squadrant crew signal done --message "<one-line summary>"`** — this transitions your task to `done` in the squadrant daemon so the captain sees terminal state without scraping your pane.
+4. Then (and only then) exit your CLI.
+
+If you need the captain's input or a decision and you will wait for it, do NOT just ask in prose — run `squadrant crew signal blocked --question "<the question>"` BEFORE ending your turn, then wait. Asking conversationally alone does not notify the captain; the explicit signal is what surfaces your question as CREW BLOCKED. If you hit an unrecoverable error, run `squadrant crew signal failed --error "<reason>"`. The signal verb reads `SQUADRANT_CREW_TASK_ID` and `SQUADRANT_CREW_PROJECT` from your environment — both are set automatically by your spawn.
+
+## Coding Discipline (Karpathy Principles)
+
+Full text: `plugin/skills/karpathy-principles/SKILL.md` in the squadrant repo. Apply to every coding task:
+
+1. **Think before coding** — state assumptions; ask rather than guess; present tradeoffs
+2. **Simplicity first** — minimum code, no speculative abstractions, no impossible-case error handling
+3. **Surgical changes** — every changed line traces to the request; no drive-by refactors
+4. **Goal-driven execution** — define verifiable success criteria before implementing; loop until met