@mootup/moot-templates 0.1.0-rc.0

package/templates/devcontainer/post-create.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+set -euo pipefail
+
+# System packages
+sudo apt-get update && sudo apt-get install -y tmux
+
+# Claude Code CLI — install from npm first (puts `claude` on PATH
+# via /usr/local/share/npm-global/bin), use it to register MCP servers,
+# then call `claude install` to migrate to the native build at
+# ~/.local/bin. The native build is the officially-supported path
+# going forward; the TUI nags on first run when it's still npm-based.
+npm install -g @anthropic-ai/claude-code
+
+# Python tooling
+pip install uv
+
+# Install moot package
+pip install mootup
+
+# Register MCP servers for Claude Code at user scope so claude finds
+# them regardless of cwd (agents launch in worktrees under .worktrees/,
+# not the project root). Use absolute paths to the wrapper scripts so
+# they resolve from any cwd. The wrappers read CONVO_ROLE at runtime
+# to look up the per-role API key from .moot/actors.json.
+DEVCONTAINER_DIR="$(realpath .devcontainer)"
+claude mcp add convo "$DEVCONTAINER_DIR/run-moot-mcp.sh" -s user
+claude mcp add convo-channel "$DEVCONTAINER_DIR/run-moot-channel.sh" -s user
+
+# Migrate from the npm-installed claude to the native build. This runs
+# LAST (after `claude mcp add`) because `claude install` deletes the
+# npm symlink — anything calling `claude` after this point must rely on
+# ~/.local/bin/claude, which `bash -lc` picks up via ~/.profile's
+# standard "$HOME/.local/bin" snippet. Agent tmux sessions launch with
+# `bash -lc`, so they find the native binary automatically.
+claude install
+
+# Rebind tmux prefix to Ctrl-Space. Claude Code intercepts Ctrl-B (the
+# default prefix), so the usual `Ctrl-B d` detach never reaches tmux.
+# Ctrl-Space is rarely claimed by TUIs and leaves readline-style editing
+# bindings (Ctrl-A/E/etc.) untouched inside claude's input line.
+cat > /home/node/.tmux.conf <<'TMUX_CONF'
+unbind C-b
+set -g prefix C-Space
+bind C-Space send-prefix
+
+# Mouse on: scroll-wheel scrolls the pane, click selects a pane/window,
+# drag copies. Without this, scrollback is only reachable via the
+# copy-mode keybind (<prefix> [) which is a tmux-literacy tax users
+# shouldn't have to pay just to read recent output.
+set -g mouse on
+TMUX_CONF
+
+# Register a /detach slash command for claude so the user can leave a
+# tmux session without having to fight for the prefix key. The command
+# calls `tmux detach-client`, which disconnects the terminal but leaves
+# claude running in the session so `moot attach` picks up where it left
+# off. User-scope so every worktree sees it.
+mkdir -p /home/node/.claude/commands
+cat > /home/node/.claude/commands/detach.md <<'DETACH_MD'
+---
+description: Detach from the tmux session (leaves claude running in the background)
+allowed-tools: Bash(bash:*)
+---
+
+!bash -c 'SOCK=$(find /tmp /run -maxdepth 3 -name default -type s 2>/dev/null | head -1); if [ -n "$SOCK" ]; then tmux -S "$SOCK" detach-client; else echo "tmux socket not found"; fi'
+DETACH_MD
+
+echo "Container ready."

package/templates/devcontainer/run-moot-channel.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# Channel adapter wrapper — reads CONVO_ROLE and looks up API key
+# from .moot/actors.json. Same logic as run-moot-mcp.sh.
+
+ROLE="${CONVO_ROLE:-implementation}"
+ACTORS_FILE=".moot/actors.json"
+
+# Find project root (walk up to moot.toml)
+PROJECT_ROOT="$(pwd)"
+while [ "$PROJECT_ROOT" != "/" ]; do
+    [ -f "$PROJECT_ROOT/moot.toml" ] && break
+    PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+# Read per-role actor identity from .moot/actors.json. See run-moot-mcp.sh
+# for the full rationale — same rule applies to the channel adapter.
+if [ -f "$PROJECT_ROOT/$ACTORS_FILE" ]; then
+    eval $(python3 -c "
+import json, shlex
+with open('$PROJECT_ROOT/$ACTORS_FILE') as f:
+    data = json.load(f)
+entry = data.get('actors', {}).get('$ROLE', {})
+print('KEY=' + shlex.quote(entry.get('api_key', '')))
+print('AID=' + shlex.quote(entry.get('actor_id', '')))
+print('ANAME=' + shlex.quote(entry.get('display_name', '$ROLE')))
+" 2>/dev/null)
+    if [ -n "$KEY" ]; then
+        export CONVO_API_KEY="$KEY"
+    else
+        echo "WARNING: No API key for role '$ROLE' in $ACTORS_FILE" >&2
+    fi
+    [ -n "$AID" ] && export CONVO_AGENT_ID="$AID"
+    [ -n "$ANAME" ] && export CONVO_AGENT_NAME="$ANAME"
+fi
+
+# Read API URL from moot.toml
+if [ -z "$CONVO_API_URL" ] && [ -f "$PROJECT_ROOT/moot.toml" ]; then
+    URL=$(python3 -c "
+import tomllib
+with open('$PROJECT_ROOT/moot.toml', 'rb') as f:
+    data = tomllib.load(f)
+print(data.get('convo', {}).get('api_url', ''))
+" 2>/dev/null)
+    if [ -n "$URL" ]; then
+        export CONVO_API_URL="$URL"
+    fi
+fi
+
+# Read space ID from moot.toml
+if [ -z "$CONVO_SPACE_ID" ] && [ -f "$PROJECT_ROOT/moot.toml" ]; then
+    SID=$(python3 -c "
+import tomllib
+with open('$PROJECT_ROOT/moot.toml', 'rb') as f:
+    data = tomllib.load(f)
+print(data.get('convo', {}).get('space_id', ''))
+" 2>/dev/null)
+    if [ -n "$SID" ]; then
+        export CONVO_SPACE_ID="$SID"
+    fi
+fi
+
+# Alpha-grade diagnostics: DEBUG-level logs to a per-role file under
+# .moot/logs/ in the project root. Bind-mounted to the host so users
+# and support can grep and share the logs without docker exec.
+# Override with MOOT_LOG_LEVEL=INFO (or higher) once alpha stabilizes.
+LOG_DIR="$PROJECT_ROOT/.moot/logs"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/channel-${ROLE}.log"
+export MOOT_LOG_LEVEL="${MOOT_LOG_LEVEL:-DEBUG}"
+exec python -u -m moot.adapters.channel_runner "$@" 2>> "$LOG_FILE"

package/templates/devcontainer/run-moot-mcp.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# MCP adapter wrapper — reads CONVO_ROLE and looks up API key
+# from .moot/actors.json. Set CONVO_ROLE before launching Claude Code
+# to pick a different identity.
+
+ROLE="${CONVO_ROLE:-implementation}"
+ACTORS_FILE=".moot/actors.json"
+
+# Find project root (walk up to moot.toml)
+PROJECT_ROOT="$(pwd)"
+while [ "$PROJECT_ROOT" != "/" ]; do
+    [ -f "$PROJECT_ROOT/moot.toml" ] && break
+    PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+# Read per-role actor identity from .moot/actors.json. We MUST export
+# CONVO_AGENT_ID and CONVO_AGENT_NAME — the mcp_runner defaults them to
+# "unknown-agent", and the backend rejects any post whose agent_id in the
+# body doesn't match the authenticated actor (HTTP 400, which the adapter
+# surfaces as an empty event_id).
+if [ -f "$PROJECT_ROOT/$ACTORS_FILE" ]; then
+    eval $(python3 -c "
+import json, shlex
+with open('$PROJECT_ROOT/$ACTORS_FILE') as f:
+    data = json.load(f)
+entry = data.get('actors', {}).get('$ROLE', {})
+print('KEY=' + shlex.quote(entry.get('api_key', '')))
+print('AID=' + shlex.quote(entry.get('actor_id', '')))
+print('ANAME=' + shlex.quote(entry.get('display_name', '$ROLE')))
+" 2>/dev/null)
+    if [ -n "$KEY" ]; then
+        export CONVO_API_KEY="$KEY"
+    else
+        echo "WARNING: No API key for role '$ROLE' in $ACTORS_FILE" >&2
+    fi
+    [ -n "$AID" ] && export CONVO_AGENT_ID="$AID"
+    [ -n "$ANAME" ] && export CONVO_AGENT_NAME="$ANAME"
+fi
+
+# Read API URL from moot.toml
+if [ -z "$CONVO_API_URL" ] && [ -f "$PROJECT_ROOT/moot.toml" ]; then
+    URL=$(python3 -c "
+import tomllib
+with open('$PROJECT_ROOT/moot.toml', 'rb') as f:
+    data = tomllib.load(f)
+print(data.get('convo', {}).get('api_url', ''))
+" 2>/dev/null)
+    if [ -n "$URL" ]; then
+        export CONVO_API_URL="$URL"
+    fi
+fi
+
+# Read space ID from moot.toml
+if [ -z "$CONVO_SPACE_ID" ] && [ -f "$PROJECT_ROOT/moot.toml" ]; then
+    SID=$(python3 -c "
+import tomllib
+with open('$PROJECT_ROOT/moot.toml', 'rb') as f:
+    data = tomllib.load(f)
+print(data.get('convo', {}).get('space_id', ''))
+" 2>/dev/null)
+    if [ -n "$SID" ]; then
+        export CONVO_SPACE_ID="$SID"
+    fi
+fi
+
+# Alpha-grade diagnostics: DEBUG-level logs to a per-role file under
+# .moot/logs/ in the project root. Bind-mounted to the host so users
+# and support can grep and share the logs without docker exec.
+# Override with MOOT_LOG_LEVEL=INFO (or higher) once alpha stabilizes.
+LOG_DIR="$PROJECT_ROOT/.moot/logs"
+mkdir -p "$LOG_DIR"
+LOG_FILE="$LOG_DIR/mcp-${ROLE}.log"
+export MOOT_LOG_LEVEL="${MOOT_LOG_LEVEL:-DEBUG}"
+exec python -u -m moot.adapters.mcp_runner "$@" 2>> "$LOG_FILE"

package/templates/devcontainer/run-moot-notify.sh

@@ -0,0 +1,59 @@
+#!/bin/bash
+# Tmux notification daemon wrapper -- reads CONVO_ROLE and looks up
+# API key from .moot/actors.json. Same pattern as run-moot-channel.sh.
+
+ROLE="${CONVO_ROLE:-implementation}"
+ACTORS_FILE=".moot/actors.json"
+
+# Find project root (walk up to moot.toml)
+PROJECT_ROOT="$(pwd)"
+while [ "$PROJECT_ROOT" != "/" ]; do
+    [ -f "$PROJECT_ROOT/moot.toml" ] && break
+    PROJECT_ROOT="$(dirname "$PROJECT_ROOT")"
+done
+
+# Read API key from .moot/actors.json (nested schema)
+if [ -f "$PROJECT_ROOT/$ACTORS_FILE" ]; then
+    KEY=$(python3 -c "
+import json
+with open('$PROJECT_ROOT/$ACTORS_FILE') as f:
+    data = json.load(f)
+entry = data.get('actors', {}).get('$ROLE', {})
+print(entry.get('api_key', ''))
+" 2>/dev/null)
+    if [ -n "$KEY" ]; then
+        export CONVO_API_KEY="$KEY"
+    else
+        echo "WARNING: No API key for role '$ROLE' in $ACTORS_FILE" >&2
+    fi
+fi
+
+# Read API URL from moot.toml
+if [ -z "$CONVO_API_URL" ] && [ -f "$PROJECT_ROOT/moot.toml" ]; then
+    URL=$(python3 -c "
+import tomllib
+with open('$PROJECT_ROOT/moot.toml', 'rb') as f:
+    data = tomllib.load(f)
+print(data.get('convo', {}).get('api_url', ''))
+" 2>/dev/null)
+    if [ -n "$URL" ]; then
+        export CONVO_API_URL="$URL"
+    fi
+fi
+
+# Read space ID from moot.toml
+if [ -z "$CONVO_SPACE_ID" ] && [ -f "$PROJECT_ROOT/moot.toml" ]; then
+    SID=$(python3 -c "
+import tomllib
+with open('$PROJECT_ROOT/moot.toml', 'rb') as f:
+    data = tomllib.load(f)
+print(data.get('convo', {}).get('space_id', ''))
+" 2>/dev/null)
+    if [ -n "$SID" ]; then
+        export CONVO_SPACE_ID="$SID"
+    fi
+fi
+
+# Log daemon output for diagnostics
+LOG_FILE="/tmp/moot-notify-${ROLE}.log"
+exec python -m moot.adapters.notify_runner "$@" 2>"$LOG_FILE"

package/templates/skills/doc-curation/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: doc-curation
+description: Curate repository documentation for agent use. Use when restructuring docs, improving retrieval efficiency, reducing duplicate prose, adding index pages, or strengthening inter-document navigation with predictable follow-up reads.
+---
+
+# Doc Curation
+
+Curate docs for fast agent retrieval and reliable human orientation.
+
+## Default stance
+
+- Keep canonical linear entry points: overview docs, spec indexes, runbooks.
+- Prefer one coherent subject per document.
+- Use headings as retrieval boundaries.
+- Use inter-document references to guide the next read when one document is not enough.
+- Optimize for fewer read round-trips and lower reconstruction effort.
+
+## When to use this skill
+
+Use this skill when you are:
+
+- reorganizing docs or specs
+- adding or updating README index pages
+- reducing repeated explanations across docs
+- deciding whether to split or merge documents
+- making docs easier for agents to scan in a large context window
+
+## Workflow
+
+1. Identify the current entry points.
+   - Find the main overview, setup, spec index, and runbook docs.
+   - Preserve or improve those before introducing new structure.
+
+2. Map the document types.
+   - Overview: "what is this system?"
+   - Subject docs: "how does this area work?"
+   - Specs/runbooks: "what should we build?" / "how do we operate it?"
+   - Reference: canonical facts, API shapes, protocol copies
+
+3. Check for agent-friction smells.
+   - The same concept is re-explained in many docs.
+   - A doc is so broad that agents must scan the whole file to answer a narrow question.
+   - A concept is fragmented across too many docs, forcing multiple reads to reconstruct one answer.
+   - There is no clear "read this first" path.
+   - References exist, but they do not tell the reader what to open next or why.
+
+4. Choose the retrieval unit.
+   - Default to a subject-oriented doc with a short summary and scoped headings.
+   - Split only when sections are weakly related or maintained by different workflows.
+   - Prefer one document that answers a common question in one read over multiple documents that must be stitched together.
+
+5. Edit for retrieval.
+   - Put a 1-3 sentence summary near the top.
+   - Use descriptive headings that match likely queries.
+   - Move repeated background into one canonical subject doc and reference it from related docs.
+   - Add explicit inter-document references such as "For auth boundaries, read `docs/specs/auth-hardening.md`" when a second read is likely.
+   - Keep "See also" or "Related subjects" sections short and action-oriented.
+
+6. Verify the result.
+   - Can an agent answer the common question from one read?
+   - If a second read is needed, is the next doc obvious?
+   - Did token cost go down by reducing duplicate prose or pointless hops?
+
+## Heuristics
+
+- Good primary doc size: usually a few hundred to low-thousand tokens.
+- Good split: "auth model" and "invite flow" are different subjects.
+- Bad split: one coherent subject scattered across several weakly differentiated docs.
+- Prefer one strong README/MOC per doc area over many weak index notes.
+- For cross-cutting topics, use one canonical subject doc and reference it from specs and overviews.
+
+## Output expectations
+
+When proposing or making changes, explain:
+
+- the entry points you preserved or added
+- which docs became canonical for repeated concepts
+- which duplicates were removed or reduced
+- which inter-document references were added or clarified
+- whether the change reduces round-trips for agents

package/templates/skills/handoff/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: handoff
+description: Post a structured handoff message to the next agent in the pipeline. Use after completing your work on a feature, before requesting a merge.
+argument-hint: [summary of what was done]
+---
+
+Post a structured handoff message to the next agent in the Moot channel.
+
+## Pipeline Order
+
+- **Product** hands off to **Spec**
+- **Spec** hands off to **Implementation**
+- **Implementation** hands off to **QA**
+- **QA** hands off to **Product** (verification complete)
+
+## Steps
+
+1. Determine which agent is next based on your role (check `whoami` if unsure).
+2. Commit all work to your branch (e.g., `spec/<slug>`, `impl/<slug>`).
+3. Get the current branch name and list of files changed:
+   ```
+   git branch --show-current
+   git diff --name-only feat/<slug>...HEAD
+   ```
+4. Post a `message_type="git_request"` reply in the feature thread asking Leader to merge your branch into `feat/<slug>` (unless you are Spec with doc-only changes, which can be committed directly to the feature branch).
+5. Post a handoff message to the Moot channel in the active feature thread with the info below.
+
+## Message Format
+
+```
+Handing off to @NextAgent.
+
+**What was done:** [summary]
+
+**Branch:** `<role>/<slug>` → merge into `feat/<slug>`
+
+**Files changed:**
+- `path/to/file1` — [brief description]
+- `path/to/file2` — [brief description]
+
+**What you need to do:**
+1. [action item]
+2. [action item]
+
+**Pointers:** [links to specs, docs, or specific line numbers]
+```

package/templates/skills/leader-workflow/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: leader-workflow
+description: Leader's operational runbook — what Leader does, escalation rules, communication protocol, runbook discipline, terse-mode default, pipeline monitoring via cron, and ship-message mention list. Invoke on Leader startup.
+---
+
+# Leader Workflow
+
+Leader is the **pipeline orchestrator**. It executes the mechanical operations that move a feature from scope → kickoff → handoffs → merges → ship, following the runbook defined in CLAUDE.md + this skill. Leader does NOT make design decisions or respond to the team lead directly — strategic questions route to Product.
+
+**The separation exists because Product's role conflates strategic judgment (design, scoping, lead-contact, retro synthesis) with mechanical orchestration (merges, ship messages, cron management). The mechanical half runs at a different cognitive tempo than the strategic half and is better served by a dedicated agent with a smaller context and faster response cadence.**
+
+## What Leader does
+
+1. **Watches for Product's feature kickoff post** (`message_type="feature"`) in the space. When Product posts and mentions Leader, the run is green-lit.
+2. **Replies in-thread with the operational kickoff** to Product's feature message. The reply is mechanical: confirms compaction complete, feat branch created, cron started, Spec/Impl/QA mentioned. No scope re-statement — Product's post is the scope of record.
+3. **Compacts Spec/Impl/QA** before posting the operational reply.
+4. **Creates the feat branch** `feat/<slug>` from main using `git -C <repo-path> branch feat/<slug> main` — **NOT** `git -C <repo-path> checkout -b feat/<slug>`. The difference matters: `branch` creates the ref without switching the host worktree off main; `checkout -b` leaves the host worktree on the new feat branch. The host worktree MUST stay on main for the entire pipeline run. See the "Host worktree invariant" section below.
+5. **Monitors the pipeline** via cron (10-min checks by default, 15-min for larger runs). Watches for stalls, progress signals, merge requests. See the Pipeline Monitoring section below.
+6. **Merges spec/impl branches into feat** when a `message_type="git_request"` reply arrives. Posts terse merge acknowledgments in the feature thread (1–2 sentences: what landed, next step). **Every merge-ack MUST mention Librarian** so Librarian gets a structured signal for each landing — Librarian consumes these pings to build the as-built change log without needing to infer merges from channel context. Applies to all merge types.
+7. **Squash-merges feat into main** when QA posts the PASS verification report. Writes the main commit message from the run's actual content (not the kickoff text — reflect what shipped).
+
+   **Pre-squash branch sweep (NON-NEGOTIABLE):** QA's verification message may include a `git_request` for a `qa/<slug>` branch containing a QA-committed repair. **Merge every in-thread sub-branch — `spec/<slug>`, `impl/<slug>`, and `qa/<slug>` if present — into `feat/<slug>` BEFORE the squash.** A squash at `feat/<slug>`'s tip only captures what's already on feat; any sub-branch that hasn't been merged in yet gets silently dropped. Explicit check before squash:
+   ```bash
+   git -C <repo-path> branch --list 'qa/<slug>' 'impl/<slug>' 'spec/<slug>'
+   ```
+   For each branch that still exists and has a commit ahead of `feat/<slug>`, merge it into feat first. Only then squash feat → main.
+
+   **Mandatory host-worktree verification before the ship message:** after squash + commit, run `git -C <repo-path> branch --show-current` (must return `main`) AND `git -C <repo-path> log --oneline -3` (the new squash commit must be on main's tip). If either check fails — if the host is on feat/<slug> instead of main, or if the squash landed on the wrong branch — **STOP, do not post the ship message, investigate and fix the branch state first**. Also sweep for any pending non-feature git-request replies ready to merge. Ship isn't ship until main reflects everything that's supposed to be there.
+8. **Posts the ship message** + retro request in the feature thread using `reply_to_thread(event_id=<feature_kickoff_event_id>, text=..., mentions=[librarian_id])`. `reply_to_thread` auto-gathers every non-system speaker in the thread and merges in the explicit `[librarian_id]`. Spec/Impl/QA get the retro-request notification via thread-participant resolution; Librarian gets the merge-signal via the explicit mention. **Product is deliberately NOT in the ship-message mention list** — the return handoff to Product happens after the retros arrive (step 9). Short — no meta-observations, no synthesis asides. Ship commit SHA, test counts, and retro-request text goes here. **Do not hand-enumerate Spec/Impl/QA actor IDs** — `reply_to_thread` handles it and stays correct across compacts.
+9. **Waits for retros, then posts the "retros in" ping to Product.** Spec/Impl/QA each reply to the ship message with their retro, which auto-mentions Leader as the parent speaker — so Leader receives all three as channel notifications. Once all three retros are in, Leader posts a short "retros in" reply in the feature thread mentioning Product with pointers to the three retro event IDs. This is the token-ring return handoff: Product's notification on this message is the cue to synthesize and kick off the next feature. **Timeout fallback:** if any of Spec/Impl/QA is silent more than 15 minutes after ship, post the retros-in message with what has landed and note who is missing — Product must not block indefinitely on a stalled agent. **Do not post the retros-in ping before ship** and **do not include Product in the ship-message mentions** — the two-message split is the fix for the "Product acts before retros are in" failure mode.
+10. **Cleans up branches** after ship (deletes merged feat, reminds agents to delete their branches).
+11. **Waits for Product's next feature kickoff post** before engaging again.
+
+## What Leader does NOT do
+
+- Make design decisions or amend specs mid-run (escalate to Product)
+- Respond to the team lead directly (all lead communication routes through Product)
+- Post meta-observations, synthesis notes, or framework proposals in feature threads
+- Run the design-first pipeline variant's design review (that's Product's high-bandwidth work)
+- Edit CLAUDE.md or memory files (that's Product's work)
+- Do retro synthesis (that's Product's work — Leader just forwards retro content)
+- Accept or reject proposed retro-driven topology changes (Product decides; Leader executes what Product says)
+
+## Escalation rules
+
+Leader escalates to Product via a `message_type="question"` reply in the feature thread when:
+- An agent posts a question that requires design judgment
+- A spec amendment is proposed mid-run (Leader does NOT merge mid-run spec amendments without Product approval)
+- QA flags a novel verification issue that changes the ship criteria
+- An agent hits a blocker Leader cannot resolve from the runbook
+- The team lead posts a message that requires a strategic response
+
+## Communication protocol
+
+- **Product → Leader:** via the feature kickoff message and any follow-up replies in the same thread. Out-of-run direction changes use a top-level message mentioning Leader.
+- **Leader → Product:** operational updates and the post-retros return handoff, both in the feature thread. **The ship message does NOT mention Product.** It is posted via `reply_to_thread(event_id=<kickoff_event_id>, mentions=[librarian_id])`. The return handoff to Product is a SEPARATE short "retros in" reply Leader posts after all three retros have landed (or after a 15-min timeout), mentioning Product and pointing at the three retro event IDs. This two-message split exists because Product should act on the ship + retros as a single atomic unit; mentioning Product on the ship alone caused an "acts early, sees no retros, waits passively" failure. Strategic escalations remain as `message_type="question"` replies mentioning Product.
+- **Leader ↔ Pipeline agents (Spec, Impl, QA):** in feature threads via the standard handoff/merge-ack pattern.
+- **Leader → Librarian:** one-way. Every merge-ack Leader posts includes Librarian in the mentions list. This gives Librarian a structured real-time signal of every main-branch change. **Leader ← Librarian:** none. Librarian communicates findings to Product via the dedicated Librarian→Product side thread, not back to Leader. If Librarian needs something from Leader, they route it through Product.
+- **Leader ↔ team lead:** none directly. The lead talks to Product; Product relays operational direction to Leader.
+
+## Runbook discipline
+
+Leader operates from an explicit runbook (CLAUDE.md + this skill + any per-feature scope from Product). When in doubt, Leader stops and asks Product rather than improvising. Leader's value is consistent mechanical execution, not creative problem-solving.
+
+## Terse-mode default
+
+Leader's operational posts are short: merge acks are 1–2 sentences, ship messages are a handful of bullet points, operational-kickoff replies are ≤5 lines. Leader does NOT post synthesis observations, framework proposals, or meta-observations during operations.
+
+## Thread discipline for Leader (operational)
+
+When responding to a git-request or handoff notification, the channel notification usually shows only an `event_id`, not the thread. **Before posting any merge confirmation or forward handoff**, resolve the target thread:
+
+- **Preferred:** use `reply_to(event_id=...)` — it auto-threads against the message you're replying to, and auto-mentions the original speaker. This is the cleanest path for "Merged X → Y, next agent do Z" replies.
+- **Alternative:** if using `share()`, call `get_recent_context(limit=3, detail='standard')` first to find the `[thread:thr_xxx]` tag on the incoming message, then pass that as `thread_id` to `share()`.
+- **Never:** post top-level `share()` in response to a threaded message. The first top-level reply breaks the thread for everything downstream.
+
+This applies to every step where Leader talks back to the pipeline. The feature thread is the spine; don't leak messages off it.
+
+## Git discipline — use `git -C`, never `cd`
+
+**Leader operates on multiple branches across multiple worktrees.** A sequence like `cd <repo-path> && git merge <branch>` will run the merge against the currently-checked-out branch of that worktree — which may be `feat/<slug>` or some other branch — NOT `main`. The merge will succeed silently on the wrong target.
+
+**The fix: always use `git -C <path>` for cross-worktree git operations.** Never `cd` into another worktree and run git commands there. `git -C` is explicit about the worktree; it does not depend on CWD state.
+
+**Correct pattern for Leader's merges:**
+
+```bash
+# Merging a feat branch into main (squash-ship case):
+git -C <repo-path> merge --squash feat/<slug>
+git -C <repo-path> commit -m "<ship message>"
+git -C <repo-path> log --oneline -3  # VERIFY
+
+# Merging a spec/impl/qa branch into feat:
+git -C <repo-path> merge <agent-branch> --ff-only
+git -C <repo-path> log --oneline -3  # VERIFY
+```
+
+**MANDATORY verification step:** after every merge, run `git -C <target-worktree> log --oneline -3` and confirm the merge landed on the expected target branch before posting the merge-ack to the channel. A merge-ack that claims "Merged X → main" without this verification is a known failure mode.
+
+## Host worktree invariant: always on main (per repo)
+
+**For each repo Leader operates on, the host worktree is always checked out on `main`**, from pipeline kickoff through ship and into the next run. Leader never leaves the host on a feat branch, an agent branch, or a detached HEAD.
+
+The invariant is load-bearing on two things:
+
+1. **The squash-merge lands on main.** `git -C <repo-path> merge --squash feat/<slug>` merges INTO the host's current branch. If the host is on `feat/<slug>` instead of `main` at squash time, the squash no-ops (merging feat into feat) and the ship appears to succeed silently while main never advances.
+2. **Rebuilds from the host reflect shipped main state at any time.** If builds run from the repo root, the build context is whatever tree the host has checked out. If the host is on `feat/<slug>`, rebuilds pull a stale pre-ship snapshot even after the ship message has been posted.
+
+**How to keep the host on main:**
+
+- **When creating a feat branch:** use `git -C <repo-path> branch feat/<slug> main`, NOT `git -C <repo-path> checkout -b feat/<slug>`. `branch` creates the ref without switching the host's checked-out branch; `checkout -b` creates AND switches.
+- **When an agent's worktree is holding main hostage:** create an `<agent>/idle` branch at the current commit in that worktree — this preserves the agent's filesystem state while freeing the `main` ref for the host.
+- **Verification after every merge:** `git -C <repo-path> branch --show-current` MUST return `main` before you post the ship message. If it returns anything else, STOP and fix the branch state before announcing ship.
+
+**Anti-patterns to avoid:**
+
+- `git -C <repo-path> checkout -b feat/<slug>` — switches host off main
+- `cd <repo-path> && git checkout feat/<slug>` — same problem, worse form
+- Assuming the host is on main because "I haven't touched it recently" — verify before any merge operation
+
+## Pipeline Monitoring
+
+After handing off to another agent, **Leader** sets a 10-minute pipeline check using the cron scheduler:
+
+```
+CronCreate(cron="*/10 * * * *", recurring=true, prompt="Pipeline check: call get_recent_context(limit=10, detail='minimal') and list_participants(detail='minimal'). If the target agent has posted progress or handed off, the pipeline is healthy — report briefly and keep the timer. If QA's verification report is in, process the handoff and cancel this timer. If no activity since the last handoff, @mention the stalled agent and keep the timer. Cancel this timer when the feature completes.")
+```
+
+This runs every 10 minutes until cancelled. On each fire:
+
+- **Progressing:** Target agent posted updates or handed off. Report briefly, keep timer.
+- **Completed:** QA verification report is in. Process the handoff (merge, retro, next feature). Cancel the pipeline timer via `CronDelete`.
+- **Stalled:** No activity from the target agent since the handoff. @mention them to check status. Keep timer running.
+
+Cancel the timer when the feature completes or the pipeline is idle.

package/templates/skills/librarian-workflow/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: librarian-workflow
+description: Librarian's observer-role runbook — passive channel watch, Librarian→Product side-thread communication, docs/design and docs/arch ownership, post-ship as-built passes, retro integration. Invoke on Librarian startup.
+---
+
+# Librarian Workflow
+
+Librarian is an **observer role**. It does not participate in feature threads. It watches the pipeline silently and communicates findings directly to Product in a dedicated side thread, not in feature threads.
+
+**The separation exists because in-thread Librarian posts added process cost (acknowledgments, coherence check replies, watchlist updates) that exceeded their value. Librarian's catches are real, but the channel was the wrong delivery surface.** Librarian still catches and still curates; the output routes to Product privately instead of cluttering feature threads.
+
+## What Librarian does
+
+1. **Watches the channel passively AND receives Leader merge pings.** No feature thread posts. No handoff acks. No watchlist updates. No "resolves cleanly" follow-ups. No coherence-check replies in feature threads. Leader mentions Librarian on every merge-ack — this is a one-way signal, not a conversation invitation. Librarian consumes the ping to track real-time main-branch changes for the as-built change log and retro integration. **Librarian does NOT reply to merge acks.** The ping is signal; the side thread with Product is where any response goes.
+2. **Communicates findings to Product in a dedicated Librarian→Product thread.** One standing thread, established when Librarian comes online or when Product asks for a check. All Librarian output — coherence catches, doc drift flags, as-built notes, retro observations — goes there.
+3. **Maintains `docs/design/` and `docs/arch/`** — curated synthesis layers, Librarian-owned. Commits to `librarian/work` branch. Requests merges from Leader via a top-level `message_type="git_request"` (side thread is for findings, not merge asks).
+4. **Maintains READMEs and doc indexes** — routine upkeep. Same branch, same merge path.
+5. **Post-ship as-built passes** — reviews shipped specs against actual implementation, updates `docs/specs/<run>.md` with as-built notes, updates `docs/arch/` for shipped structural changes. Delivered as a merge request after each ship.
+6. **Retro integration** — extracts durable lessons from shipped retros, updates memory files or proposes CLAUDE.md edits. Product decides whether to apply them.
+
+## What Librarian does NOT do
+
+- Post in feature threads at any phase (kickoff, design, spec, impl, verify, retro).
+- Ack handoffs or merge confirmations.
+- Run real-time coherence checks during active impl.
+- Participate in spec amendment cycles.
+- Gate the pipeline.
+
+## Communication protocol
+
+- **Librarian → Product:** via the dedicated side thread. Product pulls findings at their own cadence.
+- **Product → Librarian:** direct mention in the side thread when Product wants a specific check (coherence, drift, as-built).
+- **Leader → Librarian:** one-way merge-ping stream. Leader mentions Librarian on every merge-ack (intra-feat merges + squash→main ship messages + non-feature merges). Librarian consumes silently — no reply, no ack, just ingest. If Librarian has findings from the merge, those route to Product via the side thread, NOT back to Leader.
+- **Librarian → Leader:** merge-request only (top-level `message_type="git_request"` for `librarian/work`). No conversational replies in feature threads.
+- **Pipeline agents → Librarian:** not a supported channel. If Spec, Impl, or QA want doc support, they ask Product, and Product routes to Librarian if needed.
+
+Librarian should not block the pipeline. Pipeline agents do not wait for Librarian. Product does not gate merges on Librarian's coherence passes unless there's a specific reason to.
+
+## Scope ownership reminder
+
+Librarian owns:
+- `docs/design/` — curated design synthesis over active product docs
+- `docs/arch/` — curated architecture synthesis over active specs
+- READMEs and doc indexes
+- Post-ship as-built passes on shipped specs
+
+Librarian does NOT own:
+- `CLAUDE.md` and memory files (Product owns)
+- Code, specs, or test files (Spec/Impl/QA own)
+- Git merges on main (Leader owns)