shellmates 0.1.0

package/templates/AGENTS.md

@@ -0,0 +1,109 @@
+# AGENTS.md
+
+This file provides guidance to AI coding agents (Codex, Warp, Gemini CLI, etc.) operating in this repository.
+
+> **Setup:** Replace `[BRACKETED]` sections with your project details.
+> Ask Claude: *"Read the codebase and fill out AGENTS.md."*
+
+---
+
+## Project Overview
+
+[2-3 sentences on what this project does.]
+
+**Stack:** [e.g., Python/FastAPI + Next.js + PostgreSQL]
+**Current milestone:** [e.g., v1.0 — MVP]
+
+---
+
+## Build & Run Commands
+
+```bash
+# Backend
+[start command]
+
+# Frontend
+[start command]
+
+# Tests
+[test command]
+
+# Lint
+[lint command]
+```
+
+---
+
+## Key Files
+
+```
+[List your most important files]
+
+Example:
+backend/app/main.py        — FastAPI entry point
+backend/app/services/      — Business logic
+frontend/app/              — Next.js pages
+.planning/STATE.md         — Current project state
+.planning/ROADMAP.md       — Phase roadmap
+```
+
+---
+
+## Multi-Agent Protocol
+
+**You are a sub-agent.** Claude Code is the orchestrator at pane `orchestra:0.1`.
+
+### Completion signal — REQUIRED
+
+After every task (code done, tests run, committed), output:
+
+```
+PHASE_COMPLETE: Phase N — <one-line summary>
+```
+
+Then output:
+```
+AWAITING_INSTRUCTIONS
+```
+
+### Pinging Claude directly
+
+When asked:
+```bash
+tmux send-keys -t orchestra:0.1 "AGENT_PING: [task] complete. Files: [list]. Issues: [any]. Tests: [pass/fail]. — AWAITING_INSTRUCTIONS" Enter
+```
+
+### Rules
+
+- Use non-interactive flags: `--yes`, `-y`, `--force`
+- Always commit before PHASE_COMPLETE
+- Run `git status --short` after committing
+- Read `.planning/phases/N-slug/PLAN.md` before executing any phase
+- Never start servers that block the terminal
+
+---
+
+## Code Conventions
+
+[Your conventions here]
+
+---
+
+## Codex Multi-Agent Roles
+
+This project includes `.codex/config.toml` with the following specialized roles:
+
+| Role | Use for |
+|------|---------|
+| `planner` | Producing PLAN.md from a task description |
+| `researcher` | Discovering constraints before planning |
+| `executor` | Implementing an approved plan |
+| `verifier` | Independent testing and UAT verification |
+| `reviewer` | Code review for regressions and security |
+| `explorer` | Read-only codebase mapping |
+
+To invoke a role pattern:
+```
+Run a [researcher] + [planner] + [executor] workflow for:
+[task description]
+```

package/templates/CLAUDE.md

@@ -0,0 +1,50 @@
+## shellmates — Multi-Agent Orchestration
+
+This project uses shellmates for multi-agent orchestration via tmux.
+Full operating instructions: `ORCHESTRATOR.md` — read it before any orchestration session.
+
+### Dispatching tasks
+
+Always use shellmates to dispatch — never raw `tmux send-keys` directly:
+
+```bash
+# One-liner (spawns session + dispatches):
+shellmates spawn --task-file /tmp/task.txt --project /path/to/project --watch
+
+# Or via script directly:
+bash scripts/spawn-team.sh --task-file /tmp/task.txt --project /path/to/project
+```
+
+### CRITICAL — Do not poll
+
+After dispatching, **stop working and end your turn**.
+
+- Do NOT run `tmux capture-pane` in a loop
+- Do NOT sleep and re-check
+- Do NOT monitor panes second by second
+
+The agent will notify you when it finishes. The notification looks like:
+
+```
+AGENT_PING: job-XXXXX complete. STATUS: complete. RESULT: ...
+```
+
+This appears directly in your terminal when the background watcher detects the result.
+Read it, then decide next steps.
+
+### If you need to check manually (once only)
+
+```bash
+# Check inbox for latest result:
+shellmates status
+
+# Or read a specific result:
+cat ~/.shellmates/inbox/<job-id>.txt
+```
+
+### Session management
+
+```bash
+shellmates status      # active sessions + inbox
+shellmates teardown    # clean up when done
+```

package/templates/GEMINI.md

@@ -0,0 +1,136 @@
+# Workspace Overview: [YOUR PROJECT NAME]
+
+> **Setup instructions:** Replace every `[BRACKETED]` section below with your project's details.
+> Ask Claude Code to fill this out for you: *"Read the codebase and fill out GEMINI.md."*
+
+---
+
+## What This Project Is
+
+[2-3 sentences describing what the project does and what problem it solves.]
+
+**Current goal:** [What you're working on right now — e.g., "v1.0 MVP", "Phase 3 — user auth"]
+
+---
+
+## Tech Stack
+
+- **Backend:** [e.g., Python 3.11 / FastAPI]
+- **Frontend:** [e.g., Next.js 14 / TypeScript / Tailwind]
+- **Database:** [e.g., PostgreSQL 15]
+- **AI/LLM:** [e.g., Gemini 2.0 Flash]
+- **Tests:** [e.g., pytest / Jest]
+- **Deploy:** [e.g., Docker / GCP Cloud Run]
+
+---
+
+## Project Layout
+
+```
+[Paste your project tree here — just the key directories, not node_modules]
+
+Example:
+my-project/
+├── backend/
+│   ├── app/
+│   │   ├── main.py          # FastAPI entry point
+│   │   ├── routers/         # Route handlers
+│   │   └── services/        # Business logic
+│   └── tests/
+├── frontend/
+│   ├── app/                 # Next.js App Router pages
+│   └── components/
+└── .planning/               # GSD plans and state
+    ├── ROADMAP.md
+    └── STATE.md
+```
+
+---
+
+## Key Commands
+
+```bash
+# Start backend
+[your backend start command]
+
+# Run tests
+[your test command]
+
+# Lint
+[your lint command]
+
+# Build
+[your build command]
+```
+
+---
+
+## Code Conventions
+
+[List your project's conventions. Examples:]
+- Use `snake_case` for Python, `camelCase` for TypeScript
+- All API endpoints require `X-API-Key` header
+- Database queries go in `services/database.py`, not inline in routes
+- Commit format: `type(scope): description` (e.g., `feat(auth): add login endpoint`)
+- Never commit secrets or `.env` files
+
+---
+
+## Multi-Agent Protocol
+
+**You are a sub-agent.** Claude Code is the orchestrator running in pane `orchestra:0.1`.
+It sends you tasks via tmux and monitors your output. Follow these rules exactly.
+
+### How you receive tasks
+
+Claude types tasks directly into your terminal via `tmux send-keys`. When you see a task appear, treat it as a new prompt and start working.
+
+### Completion signal — REQUIRED
+
+After finishing every task (code written, tests passing, committed), output this exact line as your **final message**:
+
+```
+PHASE_COMPLETE: Phase N — <one-line summary of what was done>
+```
+
+Example:
+```
+PHASE_COMPLETE: Phase 3 — POST /users endpoint added, validation + tests, all passing
+```
+
+Then output:
+```
+AWAITING_INSTRUCTIONS
+```
+
+**This is how Claude knows you're done.** It polls your pane looking for `PHASE_COMPLETE`. If you don't output this, Claude will keep waiting.
+
+### Notifying Claude directly (when asked)
+
+If Claude explicitly asks you to ping it, run this bash command — it types the message into Claude's terminal:
+
+```bash
+tmux send-keys -t orchestra:0.1 "AGENT_PING: [task] complete. Files changed: [list]. Issues: [any deviations or problems]. Tests: [pass/fail + counts]. — AWAITING_INSTRUCTIONS" Enter
+```
+
+### Rules — read these carefully
+
+1. **Never start the next task until Claude sends it.** After PHASE_COMPLETE, wait.
+2. **Always use non-interactive flags.** `npm install --yes`, `apt install -y`, `npx --yes`. Never run a command that pauses for y/n — Claude can't respond to interactive sub-shells.
+3. **Always commit before signaling PHASE_COMPLETE.** Uncommitted work doesn't count.
+4. **Run `git status --short` after committing** to confirm a clean tree.
+5. **One task at a time.** Don't batch multiple phases into one response.
+6. **Don't start the backend server** (`uvicorn`, `gunicorn`, etc.) unless explicitly told to — it will block your terminal and you won't be able to run further commands.
+7. **Read the plan file first.** When told to execute a phase, read `.planning/phases/N-slug/PLAN.md` before writing any code.
+
+---
+
+## Planning Files Location
+
+All GSD plans live in `.planning/phases/`. When told to execute a phase, the plan will be at:
+
+```
+.planning/phases/N-phase-name/PLAN.md
+```
+
+Read the entire PLAN.md before starting. It contains the task list, file list, and verification steps.

package/templates/config.json

@@ -0,0 +1,10 @@
+{
+  "permission_mode": "default",
+  "default_agent": "gemini",
+  "orchestrator": "claude",
+  "_docs": {
+    "permission_mode": "default | bypass — bypass starts agents in auto-approve mode (no confirmation prompts). gemini uses --yolo, codex uses --full-auto.",
+    "default_agent": "gemini | codex | ask — which CLI to use for worker tasks. 'ask' prompts you each time.",
+    "orchestrator": "claude | gemini | codex — which CLI acts as orchestrator. Determines which pane reads ORCHESTRATOR.md."
+  }
+}

package/templates/gitignore-additions.txt

@@ -0,0 +1,2 @@
+# Shellmates — add these to your project .gitignore
+.shellmates/tasks/

package/templates/hooks/settings-addition.json

@@ -0,0 +1,20 @@
+{
+  "_comment": "Merge this into ~/.claude/settings.json (or ~/.claude/settings.local.json).",
+  "_comment2": "This hook fires after every Bash tool call. If it was a shellmates dispatch,",
+  "_comment3": "it waits for the inbox result and notifies Claude natively via asyncRewake.",
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "~/.claude/hooks/shellmates-notify.sh",
+            "async": true,
+            "asyncRewake": true
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/hooks/shellmates-notify.sh

@@ -0,0 +1,77 @@
+#!/usr/bin/env bash
+# shellmates-notify.sh — Claude Code PostToolUse hook
+#
+# Fires after every Bash tool call. If the command was a shellmates dispatch,
+# waits for the inbox result and exits with code 2 (asyncRewake) so Claude
+# Code delivers the result as a native notification — no polling needed.
+#
+# Install:
+#   cp templates/hooks/shellmates-notify.sh ~/.claude/hooks/
+#   chmod +x ~/.claude/hooks/shellmates-notify.sh
+#   Merge templates/hooks/settings-addition.json into ~/.claude/settings.json
+
+set -euo pipefail
+
+INBOX_DIR="${HOME}/.shellmates/inbox"
+TIMEOUT="${SHELLMATES_TIMEOUT:-300}"
+
+# Hook receives { tool_name, tool_input, tool_response } as JSON on stdin
+INPUT=$(cat)
+
+# Only act on Bash tool calls that used shellmates
+COMMAND=$(echo "$INPUT" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+cmd = data.get('tool_input', {}).get('command', '')
+print(cmd)
+" 2>/dev/null || echo "")
+
+if ! echo "$COMMAND" | grep -qE "shellmates spawn|spawn-team\.sh|dispatch\.sh"; then
+  exit 0  # Not a shellmates dispatch — do nothing
+fi
+
+# Extract job ID from tool output (dispatch.sh prints "Job ID: job-XXXX")
+TOOL_OUTPUT=$(echo "$INPUT" | python3 -c "
+import json, sys
+data = json.load(sys.stdin)
+print(data.get('tool_response', {}).get('output', ''))
+" 2>/dev/null || echo "")
+
+JOB_ID=$(echo "$TOOL_OUTPUT" | grep -oE 'job-[0-9]+-[0-9]+' | head -1)
+
+mkdir -p "$INBOX_DIR"
+
+# Snapshot files before waiting
+BEFORE=$(ls "$INBOX_DIR" 2>/dev/null | sort)
+
+elapsed=0
+while [[ $elapsed -lt $TIMEOUT ]]; do
+  sleep 2
+  elapsed=$((elapsed + 2))
+
+  AFTER=$(ls "$INBOX_DIR" 2>/dev/null | sort)
+  NEW=$(comm -13 <(echo "$BEFORE") <(echo "$AFTER") | grep '\.txt$' | head -1)
+
+  # If we have a specific job ID, wait for that file; otherwise take any new file
+  if [[ -n "$JOB_ID" ]]; then
+    TARGET="${INBOX_DIR}/${JOB_ID}.txt"
+    [[ -f "$TARGET" ]] && NEW="${JOB_ID}.txt"
+  fi
+
+  if [[ -n "$NEW" ]]; then
+    RESULT_FILE="${INBOX_DIR}/${NEW}"
+    CONTENT=$(cat "$RESULT_FILE" 2>/dev/null || echo "result file unreadable")
+    STATUS=$(echo "$CONTENT" | grep '^STATUS:' | cut -d: -f2- | xargs)
+    RESULT=$(echo "$CONTENT" | grep '^RESULT:' | cut -d: -f2- | xargs)
+    AGENT=$(echo "$CONTENT" | grep '^AGENT:' | cut -d: -f2- | xargs)
+
+    # Print notification — Claude Code will surface this when asyncRewake fires
+    echo "AGENT_PING: ${AGENT:-agent} finished. STATUS: ${STATUS:-complete}. RESULT: ${RESULT:-see inbox}. File: ${NEW}"
+
+    # Exit code 2 = asyncRewake — Claude Code re-enqueues this as a task notification
+    exit 2
+  fi
+done
+
+echo "AGENT_PING: timeout after ${TIMEOUT}s — check ~/.shellmates/inbox/ manually"
+exit 2

package/templates/task-header.txt

@@ -0,0 +1,10 @@
+## AGENT COMMUNICATION PROTOCOL
+You are a sub-agent. Respond like an API, not a human.
+- NO greetings, preamble, or sign-offs
+- NO markdown headers or decorative formatting
+- Output ONLY: results, file paths changed, errors, decisions
+- Status updates: ≤2 lines
+- Task results: ≤10 lines unless detail is explicitly required
+- Use key:value pairs over prose wherever possible
+- When writing completion files: structured data only, no narrative
+