@mootup/moot-templates 0.1.0-rc.0

package/README.md

@@ -0,0 +1,42 @@
+# @mootup/moot-templates
+
+Canonical project templates for [`@mootup/moot-cli`](https://www.npmjs.com/package/@mootup/moot-cli) — skills, team layouts, devcontainer scaffolding, and Claude Code hooks.
+
+The templates are the single source of truth for `moot init` scaffolding on both the Python and JavaScript sides of the mootup toolchain. The canonical tree lives in [`mootup-io/moot`](https://github.com/mootup-io/moot) at `src/moot/templates/`; this package vendors a byte-identical copy for JS consumers.
+
+## Install
+
+```bash
+npm install @mootup/moot-templates
+```
+
+## Usage
+
+```js
+import { getTemplatesDir, BUNDLED_SKILLS } from '@mootup/moot-templates';
+
+console.log(getTemplatesDir());
+// /absolute/path/to/node_modules/@mootup/moot-templates/templates
+
+console.log(BUNDLED_SKILLS);
+// ['product-workflow', 'spec-checklist', ...]
+```
+
+## What's bundled
+
+- `templates/CLAUDE.md` — default CLAUDE.md for new projects
+- `templates/claude/` — Claude Code settings + hooks
+- `templates/devcontainer/` — devcontainer.json + runner scripts
+- `templates/skills/` — 8 bundled agent-workflow skills
+- `templates/teams/` — 5 team topologies (loop-3, loop-4, loop-4-observer, loop-4-parallel, loop-4-split-leader)
+
+## Maintenance
+
+Contributors: templates live canonically in `mootup-io/moot/src/moot/templates/`. Edits land there. To refresh this package's vendored copy:
+
+```bash
+# From the mootup-io/moot-cli-js monorepo root:
+npm run -w @mootup/moot-templates sync:templates
+```
+
+The parity test (`test/parity.test.ts`) enforces byte-identical equality between the vendored copy and the canonical source on every CI run.

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Absolute path to the bundled templates root.
+ *
+ * After `npm install`, the package layout on consumers' disk is:
+ *   node_modules/@mootup/moot-templates/
+ *     dist/index.js          <- this module after build
+ *     templates/             <- vendored template tree
+ *
+ * `dirname(import.meta.url)` resolves to .../dist; `../templates` reaches
+ * the sibling directory. Works identically in the source layout during
+ * development (src/index.ts is under packages/moot-templates/src, and
+ * templates/ is the sibling — but production always runs from dist/).
+ */
+export declare function getTemplatesDir(): string;
+/**
+ * Mirror of Python's `moot.scaffold.BUNDLED_SKILLS`. Names must stay in
+ * lock-step; the parity test enforces that every name listed here has a
+ * corresponding directory under `templates/skills/`.
+ */
+export declare const BUNDLED_SKILLS: readonly string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAGxC;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EASlC,CAAC"}

package/dist/index.js

@@ -0,0 +1,35 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+/**
+ * Absolute path to the bundled templates root.
+ *
+ * After `npm install`, the package layout on consumers' disk is:
+ *   node_modules/@mootup/moot-templates/
+ *     dist/index.js          <- this module after build
+ *     templates/             <- vendored template tree
+ *
+ * `dirname(import.meta.url)` resolves to .../dist; `../templates` reaches
+ * the sibling directory. Works identically in the source layout during
+ * development (src/index.ts is under packages/moot-templates/src, and
+ * templates/ is the sibling — but production always runs from dist/).
+ */
+export function getTemplatesDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', 'templates');
+}
+/**
+ * Mirror of Python's `moot.scaffold.BUNDLED_SKILLS`. Names must stay in
+ * lock-step; the parity test enforces that every name listed here has a
+ * corresponding directory under `templates/skills/`.
+ */
+export const BUNDLED_SKILLS = [
+    'product-workflow',
+    'spec-checklist',
+    'leader-workflow',
+    'librarian-workflow',
+    'handoff',
+    'verify',
+    'doc-curation',
+    'memory-audit',
+];
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,eAAe;IAC7B,MAAM,IAAI,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACrD,OAAO,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;AACvC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,cAAc,GAAsB;IAC/C,kBAAkB;IAClB,gBAAgB;IAChB,iBAAiB;IACjB,oBAAoB;IACpB,SAAS;IACT,QAAQ;IACR,cAAc;IACd,cAAc;CACN,CAAC"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@mootup/moot-templates",
+  "version": "0.1.0-rc.0",
+  "description": "Canonical project templates (skills, teams, devcontainer, Claude hooks) for @mootup/moot-cli, synced from the mootup Python CLI source.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "sync:templates": "node scripts/sync-templates.mjs",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/templates/CLAUDE.md

@@ -0,0 +1,233 @@
+# {project_name}
+
+> This file is the entry point your AI coding agents read when they connect to your project. It describes how the team works, what each role does, and the disciplines that keep the work coherent. Edit the sections marked `TODO:` to describe your specific project. The Agent Workflow section below is generic across all projects using Moot — leave it as-is unless you want to customize the team topology.
+>
+> Generated by `moot init` from the bundled mootup template. Maintained at `https://mootup.io/docs`.
+
+## Status
+
+TODO: A short paragraph about what this project is and what state it's in. One to three sentences.
+
+## Tech stack
+
+TODO: Bullet list of the major dependencies and tooling. Example:
+
+- **Python 3.11+**, async throughout, Pydantic models
+- **Node 22**, TypeScript
+- **PostgreSQL 17**
+- **Docker Compose** for local dev
+
+## Running components
+
+TODO: Describe how to start the project locally. The default `moot init` flow assumes you have a Docker-based dev stack and a Claude Code coding agent on your laptop, but adjust to your setup.
+
+```bash
+# Example
+docker compose up -d
+```
+
+## Code conventions
+
+TODO: Defaults below — adjust to your project. The agents will follow whatever you put here.
+
+- Type-checked end to end
+- Async everywhere where the runtime supports it
+- Tests live alongside the code they exercise
+- Verbose logging in active development; structured logging in production
+
+## Agent Workflow
+
+This project uses Moot to coordinate a team of AI coding agents working in parallel on the same codebase. The agents communicate via a shared Convo space (the channel), share a git repository via per-agent worktrees, and follow a fixed pipeline topology that has been refined across many projects.
+
+### Roles
+
+- **Product** — Strategic direction, feature scoping, design decisions. Primary point of contact with the human team lead. Owns CLAUDE.md edits, memory file curation, and retro synthesis. Composes feature kickoffs (`message_type="feature"`) and hands off to Leader for operational execution. Does NOT run the pipeline cron, post operational merge acks, or handle mechanical merges day-to-day. Full runbook in the `product-workflow` skill.
+- **Leader** — Pipeline orchestration. Replies to Product's kickoff with the operational setup (feat branch, compaction, cron), merges sub-branches into feat, squash-merges to main at ship time. Day-to-day owner of git operations on main and feat branches. Does NOT make design decisions, amend specs mid-run, or respond to the team lead directly — escalates to Product via `message_type="question"` in the feature thread. Full runbook in the `leader-workflow` skill.
+- **Spec** — Design docs, specifications, test plans, architecture review. Each spec includes a "Security considerations" section: auth requirements, input validation boundaries, data isolation, secrets handling. Spec-drafting discipline in the `spec-checklist` skill.
+- **Implementation** — Code implementation based on specs. Writes common-case behavioral tests before handoff.
+- **QA** — Test strategy, test implementation, feature verification. Owns the local test stack. Extends test coverage beyond spec requirements based on own analysis. Includes security verification: auth bypass attempts, input validation on user-controlled fields, XSS surface, tenant isolation. May commit small repairs directly when the intended behavior is unambiguous.
+- **Librarian** — Observer role. Owns documentation directories (`docs/design/`, `docs/arch/`, `docs/site/`, READMEs), post-ship as-built passes, and retro integration. Does NOT post in feature threads; communicates doc findings to Product via a dedicated Librarian→Product side thread. Full runbook in the `librarian-workflow` skill.
+
+### Resource Ownership
+
+Shared resources have a single owner to avoid contention. Other agents must request operations via the Convo channel.
+
+| Resource | Owner | Others request via |
+|----------|-------|--------------------|
+| Git: main branch, feature branches, merges | Leader | `message_type="git_request"` reply |
+| Test stack (rebuild, restart) | QA | `message_type="stack_request"` reply |
+| CLAUDE.md, memory files, retro synthesis | Product | Leader reports; Product edits |
+| `docs/design/`, `docs/arch/`, as-built passes | Librarian | Product requests via side thread |
+
+### Git Workflow
+
+Each agent works in a **git worktree** at `<repo>/.worktrees/<role>/` to avoid filesystem contention. The host worktree (the repo's root path) stays on `main` and is owned by the host.
+
+**Branch naming:**
+- `feat/<slug>` — integration branch, Leader creates from main at feature start
+- `spec/<slug>` — Spec's work branch for a feature
+- `impl/<slug>` — Implementation's work branch
+- `qa/<slug>` — QA's work branch (tests, verification fixes)
+- `librarian/work` — Librarian's persistent work branch (doc updates)
+- `product/<slug>` — Product's branches for CLAUDE.md edits, memory files, retro synthesis docs
+
+**Branch hygiene:** Create a fresh branch per feature. Do not reuse branches from previous features.
+
+**What Spec / Impl / QA / Librarian do per feature:** create your branch from `feat/<slug>`, commit your work, request merge from Leader with `message_type="git_request"` as a reply in the feature thread. Pull `feat/<slug>` into your worktree before starting if another agent has committed ahead of you. Everything downstream (branch creation, cron monitoring, squash-merging to main, posting the ship message, retros-in handoff) is Leader's job and lives in the `leader-workflow` skill.
+
+**Non-feature commits** (small bug fixes, doc updates, config changes) that aren't part of an active feature branch can be committed individually or grouped — no squash required. Use judgment: related fixes can share a commit, unrelated ones should be separate.
+
+### Startup
+
+On connecting to the Convo space (including restarts and resumes), every agent must:
+1. Pull main into their worktree: `git rebase main` (avoids stash dances from stale branches)
+2. Join the Convo space and subscribe to the channel (space ID in `CONVO_SPACE_ID` from `.env.local` or equivalent)
+3. Run `whoami` to verify identity is correctly configured
+4. Catch up: call `get_context_with_summary` (for long spaces) or `get_activity(detail="minimal")` (for recent changes) to understand what happened while away
+5. Post a `status_update` confirming identity and readiness
+6. **Load your role workflow skill** if your role has one. Invoke via the Skill tool:
+   - **Product** → `product-workflow`
+   - **Leader** → `leader-workflow`
+   - **Librarian** → `librarian-workflow`
+   - Spec/Implementation/QA have role-specific guidance in this document plus memory files; no dedicated workflow skill yet.
+
+### MCP Response Profiles
+
+Use the `detail` parameter on read-heavy MCP tools to reduce token consumption:
+
+| Context | Detail level | Why |
+|---------|-------------|-----|
+| Polling / timer checks | `minimal` | Timestamps + speakers only — enough to detect activity |
+| Catch-up after idle | `standard` (default) | Full text needed to understand what happened |
+| Debugging / deep inspection | `full` | Metadata, mentions, refs for troubleshooting |
+
+Tools that support `detail`: `get_recent_context`, `get_mentions`, `list_participants`, `get_activity`, `get_context_with_summary`, `get_space_status`.
+
+**Rule of thumb:** If you're checking *whether* something happened, use `minimal`. If you need to understand *what* happened, use `standard`. If you need to know *everything*, use `full`.
+
+### Work Pipeline
+
+Work flows through agents in sequence, one feature at a time:
+
+```
+Lead ──direction──> Product ──scope──> Leader ──kickoff──> Spec ──design──> Implementation ──build──> QA ──verify──> Leader ──ship──> Product ──retro/memory──> next run
+```
+
+**Two layers of coordination:**
+
+- **Strategic layer (Product, lead-facing):** the team lead talks to Product about what to build. Product makes design decisions, writes feature scope, negotiates clarifying questions with Spec during design-first runs, synthesizes retros into CLAUDE.md / memory / skills. Composes and posts the feature kickoff message (`message_type="feature"`) once the direction is locked, mentioning Leader to hand off operational execution.
+- **Operational layer (Leader, pipeline-facing):** Leader takes over from Product's feature kickoff by replying in-thread with the operational kickoff and runs the run through the Spec/Impl/QA pipeline. Manages the cron, merges branches, squash-merges to main, posts ship messages.
+
+**Comms test:** Before beginning work on a feature, Leader (in the operational kickoff reply) mentions Spec/Impl/QA and waits for acknowledgment. Work does not begin until every agent has confirmed they are listening. Librarian is NOT in the mention list (observer role).
+
+Each handoff uses the `mentions` parameter on `share()` or `reply_to()` to notify the next agent by participant_id. **Use display names in message text** (e.g., "Implementation: pull the branch..."), not raw IDs. The `mentions` parameter handles notification delivery; the message text is for human readability. Without an explicit mention, the next agent never receives a channel notification and the pipeline stalls (token-ring failure).
+
+**Status updates on handoff:** Every agent must call `update_status` when receiving or completing a handoff. This keeps the participant list and web UI status indicators accurate.
+
+**After handing off: stop.** Post the handoff message, update your status, and wait for the next channel notification. Do NOT poll for the next agent's response. Do NOT acknowledge the prior agent's handoff — only post a status update. Polling burns tokens and produces no value.
+
+**Thread discipline:** During pipeline runs, all messages go in the feature thread. Do not post top-level messages for handoffs, acks, or status updates — reply in the thread. Leader-specific thread routing (how to resolve a thread from an `event_id`-only notification) lives in the `leader-workflow` skill.
+
+**No handoff acknowledgments.** When you receive a handoff, do NOT reply to the prior agent saying "acknowledged." Instead, update your status and start working. The prior agent should already be idle.
+
+### Pipeline Variants
+
+- **Standard pipeline:** Product compacts Leader → posts feature kickoff (`message_type="feature"`) → Leader replies with operational kickoff → Spec → Impl → QA → Leader ships → Product reads retros.
+- **Design-first pipeline:** adds a Product↔Spec `message_type="question"` design review before the kickoff, for features with semantic decisions or multiple open questions. Triage: mechanical lifts use standard pipeline; semantic work uses design-first.
+- **Kickoff ownership:** Product composes kickoff content (scope, baseline, ship criteria, retro carryover); Leader adds operational details in the in-thread reply (feat branch, compact confirmation, cron, agent mentions).
+
+### Message Types
+
+Messages carry a structured `message_type` metadata field, set via the `message_type` parameter on `share()`, `reply_to()`, `reply_to_thread()`, and `post_response()`. The frontend renders it as a colored pill on the message card and (for thread roots) on the thread sidebar entry.
+
+**Taxonomy** (10 values):
+
+| Value | When to use |
+|---|---|
+| `feature` | Product's kickoff message that opens a feature pipeline run |
+| `question` | An agent needs clarification from another agent |
+| `git_request` | Asking Leader to merge a branch |
+| `stack_request` | Asking QA to rebuild / restart the test stack |
+| `review_request` | Asking another agent for a code / doc / design review |
+| `code_share` | Sharing a code snippet or diff for reference |
+| `status_update` | Programmatic status update (set automatically by `update_status`) |
+| `decision_propagated` | Cross-space decision propagation |
+| `retro` | Retrospective message after ship |
+| `bug` | Bug report (usually to Product or the owning agent) |
+
+**Usage:** pass `message_type=` on the message call. Do NOT include a `[TYPE]` bracket prefix in the text body — the first line of the message renders as the thread title and should be natural prose.
+
+```python
+share(
+    text="merge `impl/xxx` → `feat/xxx`\n\n...",
+    message_type="git_request",
+    thread_id=feature_thread_id,
+)
+```
+
+### Channel Threading Protocol
+
+The space has three kinds of threads, identified by the root message's `message_type`:
+
+1. **Feature threads** (`message_type="feature"`) — Product creates when kicking off a feature. All handoffs, status updates, completion notices, retros, and clarification questions for that feature go in this thread. This is the spine of the work.
+2. **Question threads** (`message_type="question"`) — Any agent creates when they need clarification from another agent. Mention the target agent. Answer in-thread, then the asker resumes work.
+3. **Git-request / stack-request threads** (`message_type="git_request"` or `"stack_request"`) — Created when an agent needs a resource owner (Leader, QA) to act. Owner replies with the result in-thread. During a feature run, a `git_request` typically lives as a reply inside the feature thread rather than a new top-level thread.
+
+### Clarification Flow
+
+When an agent is blocked and needs input:
+- Spec asks Product for requirements clarification (high-bandwidth design questions go through Product directly)
+- Implementation asks Spec for design clarification via `message_type="question"` in the feature thread
+- QA asks Spec for acceptance criteria clarification via `message_type="question"` in the feature thread
+- Librarian asks Product via the Librarian→Product side thread (not feature threads)
+- Leader escalates judgment calls to Product via a `message_type="question"` reply in the feature thread
+
+### Tracking Decisions
+
+Use `propose_decision` for choices that involve tradeoffs, creativity, judgment, or non-obvious analysis — decisions where a different reasonable person might choose differently. These are moments that prune or expand the space of possible futures.
+
+**When to track:**
+- Architectural choices during spec work
+- Process changes from retros
+- Moments during debugging where a pre-implementation assumption turned out to be fundamentally wrong
+- Design tradeoffs with non-obvious consequences
+
+**When NOT to track:** Mechanical or purely deductive decisions — things obvious from the facts at hand.
+
+**Value:** Future agents can query `list_decisions` to understand *why* things are the way they are.
+
+### Retrospective
+
+After QA verifies and Leader confirms a feature has shipped, Spec/Impl/QA each post one short retro message in the feature thread with `message_type="retro"`. Each retro is a `reply_to` against Leader's ship message, which auto-mentions Leader so the retros-in handoff is reliable. Keep retros short — bullets, not paragraphs.
+
+**Topology invariance principle:** retros may change how individual agents perform their work but must NOT change the team interaction topology. The pipeline topology (Lead → Product → Leader → Spec → Impl → QA → Leader → Product) is invariant. Retros optimize the work at each node, not the connections between nodes.
+
+### Test Access
+
+TODO: Document how each agent runs tests against their environment. Example:
+
+```bash
+# Adjust to your test stack
+docker exec project-backend-1 pytest -n auto
+```
+
+### Platform instability
+
+Transient API/backend errors (502, 504, connection reset, timeout) are a normal failure mode of containerized services, not anomalies worth investigating. Default response:
+
+1. **Retry the call immediately** (one retry). Most blips clear within a second.
+2. **If the retry fails, call `wait_for_health`** if available, otherwise wait 30s. Do not poll.
+3. **If still failing**, post a single status update ("backend unreachable, pausing work") and stop. Do not descend into diagnostic commands unless the outage persists past 2–3 minutes AND it's blocking something time-sensitive.
+
+**What NOT to do:**
+- Run diagnostics on a single failed call. One 502 is not an incident.
+- Poll in a loop waiting for the backend to come back. One check, then wait for notification.
+- Assume "can't reach channel" means "pipeline has stalled." If you're mid-work, keep working locally; post accumulated results when the channel recovers.
+
+## Doc conventions
+
+- TODO: Where does your project's design documentation live?
+- TODO: Where do specs live?
+- TODO: Where do operational runbooks live?
+- Reference don't repeat: link to source files rather than copying content
+- Local environment files are gitignored; use `.env.example` as a template

package/templates/claude/hooks/auto-orient.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# SessionStart hook — emits additionalContext instructing the agent to
+# call orientation + list_participants as its first action. Covers
+# fresh sessions, /resume, /compact continuations (source field varies
+# but the instruction is the same).
+set -euo pipefail
+
+# Read stdin JSON (we don't branch on source — the instruction is
+# source-agnostic — but we parse it so a future change is a 1-line
+# edit).
+INPUT=$(cat)
+SOURCE=$(echo "$INPUT" | jq -r '.source // "startup"')
+
+cat <<JSON
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "Before your first substantive action this session: call mcp__convo__orientation() to pick up your identity, focus space, and recent context, then call mcp__convo__list_participants(detail='full') to see who else is online. Post a status_update confirming you are ready. Skip this if you have already oriented in the current turn. (Injected by SessionStart hook, source=$SOURCE.)"
+  }
+}
+JSON

package/templates/claude/hooks/git-guard.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# PreToolUse hook — blocks mutating git commands when the current
+# working directory does not match $CONVO_WORKTREE.
+#
+# Read-only subcommands fall through (exit 0 with no stdout = allow).
+# Mutating subcommands emit a deny decision with the exact mismatch.
+set -euo pipefail
+
+INPUT=$(cat)
+CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# Not a Bash tool call, or no command — allow.
+[ -z "$CMD" ] && exit 0
+
+# Only care about git invocations. Match `git ` at word start (handles
+# leading env overrides like `GIT_PAGER=cat git ...`). Grep is enough;
+# we don't need a full parser.
+if ! echo "$CMD" | grep -qE '(^|\s|;|&&|\|\|)git(\s|$)'; then
+    exit 0
+fi
+
+# Denylist of mutating subcommands. Fail-closed: unknown subcommands
+# fall through (allow), but matched mutating ones are checked.
+MUTATING='commit|merge|reset|rebase|cherry-pick|push|tag|clean\s+-[fd]|stash\s+drop|worktree\s+remove|branch\s+-[dD]|checkout\s+-[bB]'
+
+if ! echo "$CMD" | grep -qE "\\bgit\\s+($MUTATING)\\b"; then
+    exit 0
+fi
+
+# Mutating command detected. Verify worktree match.
+EXPECTED="${CONVO_WORKTREE:-}"
+if [ -z "$EXPECTED" ]; then
+    # No worktree expectation set — allow (hook can't guard what it
+    # doesn't know). This is the case for host-clone sessions outside
+    # the agent launchers.
+    exit 0
+fi
+
+ACTUAL=$(git rev-parse --show-toplevel 2>/dev/null || echo "")
+EXPECTED_CANON=$(realpath "$EXPECTED" 2>/dev/null || echo "$EXPECTED")
+ACTUAL_CANON=$(realpath "$ACTUAL" 2>/dev/null || echo "$ACTUAL")
+
+if [ "$EXPECTED_CANON" = "$ACTUAL_CANON" ]; then
+    exit 0
+fi
+
+# Mismatch — block.
+REASON="Cross-worktree git mutation blocked: CWD resolves to '$ACTUAL_CANON' but CONVO_WORKTREE is '$EXPECTED_CANON'. Change directory to the expected worktree before running mutating git commands, or unset CONVO_WORKTREE if this is a deliberate host-clone operation."
+
+jq -n --arg reason "$REASON" '{
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "deny",
+    permissionDecisionReason: $reason
+  }
+}'

package/templates/claude/hooks/grep-baseline-diff.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# PostToolUse hook — caches Grep results keyed by (pattern, path) and
+# warns when an identical grep returns a different count within the
+# same session. Non-blocking.
+set -euo pipefail
+
+INPUT=$(cat)
+SESSION=$(echo "$INPUT" | jq -r '.session_id // empty')
+PATTERN=$(echo "$INPUT" | jq -r '.tool_input.pattern // empty')
+SEARCH_PATH=$(echo "$INPUT" | jq -r '.tool_input.path // "."')
+RESPONSE=$(echo "$INPUT" | jq -r '.tool_response // empty')
+
+[ -z "$SESSION" ] || [ -z "$PATTERN" ] && exit 0
+
+CACHE=/tmp/convo-grep-cache-"$SESSION".json
+KEY=$(echo "${PATTERN}|${SEARCH_PATH}" | sha256sum | cut -d' ' -f1)
+
+# Count matches in this response — the Grep tool's output format
+# varies by output_mode; use line count as a cheap proxy.
+COUNT=$(echo "$RESPONSE" | wc -l)
+
+# Read prior count if cached.
+PRIOR=""
+if [ -f "$CACHE" ]; then
+    PRIOR=$(jq -r --arg k "$KEY" '.[$k] // empty' "$CACHE" 2>/dev/null || echo "")
+fi
+
+# Write current count back to cache.
+mkdir -p "$(dirname "$CACHE")"
+if [ -f "$CACHE" ]; then
+    jq --arg k "$KEY" --argjson v "$COUNT" '.[$k] = $v' "$CACHE" > "$CACHE.tmp" && mv "$CACHE.tmp" "$CACHE"
+else
+    jq -n --arg k "$KEY" --argjson v "$COUNT" '{($k): $v}' > "$CACHE"
+fi
+
+# Warn if count drifted.
+if [ -n "$PRIOR" ] && [ "$PRIOR" != "$COUNT" ]; then
+    echo "NOTICE: grep baseline drift — pattern='$PATTERN' path='$SEARCH_PATH' prior=$PRIOR current=$COUNT. A baseline measured earlier this session no longer matches; if you are mid-spec, re-ground before treating the current count as the new baseline." >&2
+fi
+
+exit 0

package/templates/claude/hooks/handoff-status-check.sh

@@ -0,0 +1,40 @@
+#!/bin/bash
+# Stop hook — warns when the turn posts an mcp__convo__share (with
+# mentions) but does not also call mcp__convo__update_status. Does
+# NOT block; emits a system reminder for the next turn via stderr.
+set -euo pipefail
+
+INPUT=$(cat)
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // empty')
+[ -z "$TRANSCRIPT" ] || [ ! -f "$TRANSCRIPT" ] && exit 0
+
+# Find the last user-turn boundary: scan backward for the last line
+# where type=user and the content is NOT a tool_result or system
+# reminder. Everything after that is the current assistant turn.
+LAST_USER_LINE=$(awk -v target='"type":"user"' '
+    $0 ~ target && $0 !~ /"tool_use_id"/ && $0 !~ /system-reminder/ { last=NR }
+    END { print last }
+' "$TRANSCRIPT")
+
+[ -z "$LAST_USER_LINE" ] && exit 0
+
+# Slice the turn's assistant entries.
+TURN=$(awk -v start="$LAST_USER_LINE" 'NR > start' "$TRANSCRIPT")
+
+# Detect handoff signal: mcp__convo__share or mcp__convo__reply_to
+# with a non-empty mentions array.
+HANDOFF=$(echo "$TURN" | grep -cE '"name":"mcp__convo__(share|reply_to|reply_to_thread)"' || true)
+STATUS=$(echo "$TURN" | grep -cE '"name":"mcp__convo__update_status"' || true)
+
+# Only fire when handoff present AND status_update absent AND the
+# share/reply had mentions. Last check: grep the turn for a non-empty
+# mentions array on any convo post.
+MENTIONS=$(echo "$TURN" | grep -cE '"mentions":\["[^"]' || true)
+
+if [ "$HANDOFF" -gt 0 ] && [ "$MENTIONS" -gt 0 ] && [ "$STATUS" -eq 0 ]; then
+    echo "WARNING: handoff message with mentions detected, but no mcp__convo__update_status call this turn. Pipeline handoffs must update status (CLAUDE.md § Status updates on handoff). Next turn should call update_status before returning to idle." >&2
+    # Exit 0 — non-blocking warning. stderr lands in the transcript
+    # for the operator and is injected as system context next turn.
+fi
+
+exit 0

package/templates/claude/settings.json

@@ -0,0 +1,51 @@
+{
+  "permissions": {
+    "defaultMode": "bypassPermissions"
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-orient.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/git-guard.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/grep-baseline-diff.sh"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/handoff-status-check.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/devcontainer/devcontainer.json

@@ -0,0 +1,25 @@
+{
+  "name": "moot-agent-team",
+  "image": "mcr.microsoft.com/devcontainers/javascript-node:22",
+  "features": {
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {
+      "moby": false
+    },
+    "ghcr.io/devcontainers/features/python:1": {
+      "version": "3.11"
+    }
+  },
+  "postCreateCommand": "bash .devcontainer/post-create.sh",
+  "runArgs": [
+    "--name", "moot-${localWorkspaceFolderBasename}"
+  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-pyright.pyright"
+      ]
+    }
+  },
+  "remoteUser": "node"
+}