@mootup/moot-templates 0.2.1 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mootup/moot-templates",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Canonical project templates (skills, teams, devcontainer, Claude hooks) for @mootup/moot-cli, synced from the mootup Python CLI source.",
   "license": "MIT",
   "repository": {

package/templates/claude/settings.json

@@ -1,6 +1,20 @@
 {
   "permissions": {
-    "defaultMode": "bypassPermissions"
+    "defaultMode": "bypassPermissions",
+    "allow": [
+      "Edit(.claude/**)",
+      "Write(.claude/**)",
+      "Edit(.worktrees/**/.claude/**)",
+      "Write(.worktrees/**/.claude/**)",
+      "Edit(CLAUDE.md)",
+      "Write(CLAUDE.md)",
+      "Edit(.worktrees/**/CLAUDE.md)",
+      "Write(.worktrees/**/CLAUDE.md)",
+      "Edit(docs/**/CLAUDE.md)",
+      "Write(docs/**/CLAUDE.md)",
+      "Edit(.worktrees/**/docs/**/CLAUDE.md)",
+      "Write(.worktrees/**/docs/**/CLAUDE.md)"
+    ]
   },
   "hooks": {
     "SessionStart": [

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

@@ -14,16 +14,32 @@ 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.
+#
+# SEC-2-C: env-driven Python via single-quoted heredoc — no shell-eval RCE.
 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)
+    OUT="$(
+        export _PR="$PROJECT_ROOT" _AF="$ACTORS_FILE" _ROLE="$ROLE"
+        python3 <<'PYEOF'
+import json, os, sys
+pr = os.environ['_PR']
+af = os.environ['_AF']
+role = os.environ['_ROLE']
+try:
+    with open(os.path.join(pr, af)) as f:
+        data = json.load(f)
+    entry = data.get('actors', {}).get(role, {})
+    print(entry.get('api_key', ''))
+    print(entry.get('actor_id', ''))
+    print(entry.get('display_name', role))
+except Exception:
+    print('', file=sys.stderr)
+    print('', file=sys.stderr)
+    print('', file=sys.stderr)
+PYEOF
+    )"
+    KEY="$(printf '%s\n' "$OUT" | sed -n '1p')"
+    AID="$(printf '%s\n' "$OUT" | sed -n '2p')"
+    ANAME="$(printf '%s\n' "$OUT" | sed -n '3p')"
     if [ -n "$KEY" ]; then
         export CONVO_API_KEY="$KEY"
     else
@@ -35,12 +51,15 @@ 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:
+    URL="$(
+        export _PR="$PROJECT_ROOT"
+        python3 <<'PYEOF'
+import os, tomllib
+with open(os.path.join(os.environ['_PR'], 'moot.toml'), 'rb') as f:
     data = tomllib.load(f)
 print(data.get('convo', {}).get('api_url', ''))
-" 2>/dev/null)
+PYEOF
+    )"
     if [ -n "$URL" ]; then
         export CONVO_API_URL="$URL"
     fi
@@ -48,12 +67,15 @@ 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:
+    SID="$(
+        export _PR="$PROJECT_ROOT"
+        python3 <<'PYEOF'
+import os, tomllib
+with open(os.path.join(os.environ['_PR'], 'moot.toml'), 'rb') as f:
     data = tomllib.load(f)
 print(data.get('convo', {}).get('space_id', ''))
-" 2>/dev/null)
+PYEOF
+    )"
     if [ -n "$SID" ]; then
         export CONVO_SPACE_ID="$SID"
     fi

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

@@ -18,16 +18,33 @@ done
 # "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).
+#
+# SEC-2-C: env-driven Python via single-quoted heredoc — no shell-eval RCE.
+# CONVO_ROLE / paths reach Python via os.environ, never via shell interpolation.
 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)
+    OUT="$(
+        export _PR="$PROJECT_ROOT" _AF="$ACTORS_FILE" _ROLE="$ROLE"
+        python3 <<'PYEOF'
+import json, os, sys
+pr = os.environ['_PR']
+af = os.environ['_AF']
+role = os.environ['_ROLE']
+try:
+    with open(os.path.join(pr, af)) as f:
+        data = json.load(f)
+    entry = data.get('actors', {}).get(role, {})
+    print(entry.get('api_key', ''))
+    print(entry.get('actor_id', ''))
+    print(entry.get('display_name', role))
+except Exception:
+    print('', file=sys.stderr)
+    print('', file=sys.stderr)
+    print('', file=sys.stderr)
+PYEOF
+    )"
+    KEY="$(printf '%s\n' "$OUT" | sed -n '1p')"
+    AID="$(printf '%s\n' "$OUT" | sed -n '2p')"
+    ANAME="$(printf '%s\n' "$OUT" | sed -n '3p')"
     if [ -n "$KEY" ]; then
         export CONVO_API_KEY="$KEY"
     else
@@ -39,12 +56,15 @@ 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:
+    URL="$(
+        export _PR="$PROJECT_ROOT"
+        python3 <<'PYEOF'
+import os, tomllib
+with open(os.path.join(os.environ['_PR'], 'moot.toml'), 'rb') as f:
     data = tomllib.load(f)
 print(data.get('convo', {}).get('api_url', ''))
-" 2>/dev/null)
+PYEOF
+    )"
     if [ -n "$URL" ]; then
         export CONVO_API_URL="$URL"
     fi
@@ -52,12 +72,15 @@ 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:
+    SID="$(
+        export _PR="$PROJECT_ROOT"
+        python3 <<'PYEOF'
+import os, tomllib
+with open(os.path.join(os.environ['_PR'], 'moot.toml'), 'rb') as f:
     data = tomllib.load(f)
 print(data.get('convo', {}).get('space_id', ''))
-" 2>/dev/null)
+PYEOF
+    )"
     if [ -n "$SID" ]; then
         export CONVO_SPACE_ID="$SID"
     fi

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

@@ -5,7 +5,32 @@ description: Curate repository documentation for agent use. Use when restructuri
 
 # Doc Curation
 
-Curate docs for fast agent retrieval and reliable human orientation.
+## Purpose
+
+Keep repository documentation optimized for fast agent retrieval and reliable human orientation. The failure class this skill addresses is **retrieval drift** — documentation accumulates organically, the same concept gets re-explained across many docs, canonical entry points fade, and agents burn tokens stitching together answers from fragmented sources. Left unaudited, doc trees decay into navigation mazes that cost more to read than they save.
+
+**Why it exists as a named skill:** curation is a judgment-heavy activity (when to split, when to merge, what's "canonical") that benefits from a shared stance rather than each author making ad-hoc calls. The skill captures the stance, the decision heuristics, and the common friction smells so curators at different times make consistent calls.
+
+## Preconditions
+
+- **Role:** any role that edits docs. Most commonly Librarian (who owns `docs/design/`, `docs/arch/`, READMEs) or Product (who owns `docs/product/`).
+- **Trigger:** restructuring docs, adding index pages, reducing repeated explanations, splitting or merging documents, or responding to a specific drift flag. Also fires preemptively during post-ship as-built passes when the curator notices duplication or weak entry points.
+- **Entry-point awareness:** the curator knows which existing docs currently serve as canonical entry points (`VISION.md`, `docs/architecture.md`, `docs/product/README.md`, `docs/specs/README.md`, etc.) so they can preserve or improve them rather than accidentally orphan.
+
+## Invariants
+
+- **Canonical entry points MUST be preserved.** Overview docs, spec indexes, and runbooks are load-bearing; curation improves or augments them, never demotes or replaces silently.
+- **One coherent subject per document.** A doc that answers two unrelated questions is a bad split target — re-partition rather than leaving it mixed.
+- **Don't orphan references.** When moving content out of doc A into doc B, update doc A to point at B (or remove A entirely with an index update). Dangling references are process-debt.
+- **No duplicate canonical content.** If two docs define the same concept, one MUST be canonical and the other MUST reference it. Both-canonical is the drift state this skill fights.
+
+## Postconditions
+
+- An agent asking a common question about the curated area can answer it from ≤2 reads.
+- Canonical entry points are intact or improved.
+- Duplicate prose is removed or reduced; cross-references point to canonical sources.
+- Where a second read is likely, the "read this next" pointer is explicit in the first doc.
+- Any doc moves or renames update the directory index (typically `README.md` in that directory).
 
 ## Default stance
 
@@ -15,66 +40,61 @@ Curate docs for fast agent retrieval and reliable human orientation.
 - 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:
+## Procedure
 
-- 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
+1. **Identify current entry points** — main overview, setup, spec index, runbook docs. Preserve or improve those before introducing new structure.
 
-## 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.
+2. **Map 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.
+3. **Check for agent-friction smells:**
+   - Same concept re-explained in many docs.
+   - A doc so broad that agents must scan the whole file to answer a narrow question.
+   - A concept fragmented across too many docs, forcing multiple reads to reconstruct one answer.
+   - No clear "read this first" path.
+   - References exist but don't 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.
+4. **Choose the retrieval unit.** Default: 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 that must be stitched.
 
-5. Edit for retrieval.
+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.
+   - Move repeated background into one canonical subject doc and reference it.
+   - Add explicit inter-document references ("For auth boundaries, read `docs/specs/auth-hardening.md`") when a second read is likely.
+   - Keep "See also" / "Related subjects" sections short and action-oriented.
 
-6. Verify the result.
+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
+## Practice
+
+**Good primary-doc size** is usually a few hundred to low-thousand tokens. Substantially smaller → probably too granular (merge candidate). Substantially larger → probably too broad (split candidate).
+
+**Good split:** "auth model" and "invite flow" are different subjects with different maintenance cadences.
 
-- 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.
+**Bad split:** one coherent subject scattered across several weakly differentiated docs. Symptom: every answer requires reading 3+ files.
+
+**One strong README/MOC per doc area > many weak index notes.** Prefer a single well-maintained entry point. Multiple competing indexes are drift.
+
+**For cross-cutting topics, one canonical subject doc + references from specs and overviews.** The canonical doc is the single source of truth; other docs reference it rather than re-defining.
 
 ## Output expectations
 
-When proposing or making changes, explain:
+When proposing or making changes, explain in the commit / PR body:
+- Which entry points were 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
+
+## Defined terms
+
+- **Canonical entry point** — a load-bearing doc (overview, index, runbook) that agents and humans find first. Curation preserves these.
+- **Retrieval unit** — the granularity at which a doc is expected to be read. Good retrieval units answer a common question in one read.
+- **Agent-friction smell** — a doc-structure pattern that forces unnecessary reads, duplication, or reconstruction effort.
 
-- 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

@@ -4,28 +4,67 @@ description: Post a structured handoff message to the next agent in the pipeline
 argument-hint: [summary of what was done]
 ---
 
-Post a structured handoff message to the next agent in the Moot channel.
+# Handoff
 
-## Pipeline Order
+## Purpose
 
-- **Product** hands off to **Spec**
-- **Spec** hands off to **Implementation**
-- **Implementation** hands off to **QA**
-- **QA** hands off to **Product** (verification complete)
+Transfer control of in-flight pipeline work from one agent to the next. The failure class this skill prevents is the **silent handoff** — agent A finishes work, updates status, and goes idle without notifying agent B, stalling the ring. Also prevents **misdirected handoff** (mentioning the wrong next agent for the current pipeline stage) and **unstructured handoff** (free-form text that omits the branch, the files changed, or the next-agent action items).
 
-## Steps
+**Why it exists as a named skill:** the pipeline order is fixed but the specific next-agent depends on *which stage you just completed*; each handoff format varies by stage (Spec → Impl, Impl → QA, QA → Leader, Leader → Product); and there are exceptions (Spec doc-only, QA verification-only) that the current agent must recognize. Capturing this once keeps handoff structure consistent across the pipeline.
 
-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:
-   ```
+## Preconditions
+
+- **Role:** caller is a pipeline agent (Spec / Implementation / QA / Leader / Product). Librarian is an observer role and does NOT hand off in the feature thread — if Librarian reaches this skill, it's a misfire.
+- **Branch committed:** all work is committed to the caller's branch (`<role>/<slug>`). Handing off uncommitted work is a protocol violation; Leader cannot merge what isn't on a branch.
+- **Feature thread known:** caller knows the current feature thread's `thread_id` (or an `event_id` within the thread that can be `reply_to`'d). Handoffs posted top-level fork the thread spine.
+- **Next-agent identified:** caller has determined the correct next agent based on the pipeline stage just completed. `whoami` + pipeline-order table in this skill, if unsure.
+
+## Invariants
+
+- **Thread discipline.** Handoff messages MUST be replies in the feature thread, not top-level posts. The feature thread is the spine; top-level posts fragment it.
+- **Mention-the-next-agent-only.** Per CLAUDE.md mention discipline, `mentions=` includes the next agent and NO ONE else. No broadcast mentions.
+- **Display names in text, IDs in `mentions`.** Message text uses "Implementation: pull the branch..."; the `mentions` parameter carries the `agt_*` ID. Mixing raw IDs into text is a readability violation.
+- **No acknowledgment after handing off.** Per CLAUDE.md, the caller MUST NOT wait for the next agent to ack. Post handoff, update status, stop.
+- **Librarian is never in handoff mentions.** Observer role. Even if Librarian contributed content, handoff mentions are pipeline-only.
+
+## Postconditions
+
+- A handoff reply exists in the feature thread, with `mentions=[<next-agent-id>]`.
+- For pipeline stages requiring a branch merge (Spec, Impl, QA with commits), a `message_type="git_request"` reply addressed to Leader has been posted in the feature thread.
+- Caller's `update_status` reflects the idle/awaiting state post-handoff.
+- Caller is idle — not polling, not re-checking, not acknowledging anything in reply.
+
+## Pipeline Order (reference, not a contract)
+
+```
+Pat → Product → Leader → Spec → Implementation → QA → Leader → Product
+```
+
+- **Product** composes the feature kickoff (`message_type="feature"`) mentioning **Leader**; Leader replies in-thread with the operational kickoff mentioning Spec/Impl/QA.
+- **Spec** hands off to **Implementation** via SPEC-READY reply in the feature thread (and a `message_type="git_request"` to Leader to merge `spec/<slug>` → `feat/<slug>`).
+- **Implementation** hands off to **QA** via a `message_type="git_request"` reply to Leader to merge `impl/<slug>` → `feat/<slug>`. QA picks up after Leader's merge ack.
+- **QA** hands off to **Leader** via a verification report that MUST mention Leader via the `mentions` parameter. Leader squash-merges `feat/<slug>` → `main` and posts the ship message.
+- **Leader** hands off to **Product** by posting the retros-in ping after all three retros land, mentioning Product. Product reads retros, synthesizes, requests merge of `product/run-<label>-synthesis`.
+
+## Procedure
+
+1. **Determine the next agent** from the pipeline order above (use `whoami` if unsure of current role).
+2. **Commit all work to the role branch** (`spec/<slug>`, `impl/<slug>`, `qa/<slug>`).
+3. **Capture branch state:**
+   ```bash
    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.
+4. **Post a `message_type="git_request"` reply in the feature thread asking Leader to merge.** Exceptions (no git-request needed):
+   - Spec doc-only changes MAY be committed directly to `feat/<slug>` per CLAUDE.md.
+   - QA MAY commit small unambiguous repairs directly to `feat/<slug>`.
+   - QA verification reports with no repairs need no git-request at all — the verification report itself is the handoff.
+5. **Post the handoff message as a reply in the feature thread.** Use `mentions=[<next-agent-id>]`; use display names in the text. For QA, the next agent is **Leader** (ship), not Product.
+6. **Update status and stop.** `update_status` ("idle, awaiting next feature" or equivalent). Do not poll, do not ack.
+
+## Practice
 
-## Message Format
+**Message format** (default; adjust for stage):
 
 ```
 Handing off to @NextAgent.
@@ -44,3 +83,12 @@ Handing off to @NextAgent.
 
 **Pointers:** [links to specs, docs, or specific line numbers]
 ```
+
+**QA verification-complete handoff** uses the gate-results table format from prior QA reports rather than the generic template — a concise gate table communicates pass/fail more clearly than free-form summary.
+
+## Defined terms
+
+- **Feature thread** — the thread rooted at Product's feature kickoff message. All pipeline handoffs for this feature run live as replies within it.
+- **Role branch** — per-feature branch owned by the current role: `spec/<slug>`, `impl/<slug>`, `qa/<slug>`, etc.
+- **Feature branch** — `feat/<slug>`, the integration branch Leader creates at kickoff and merges role branches into.
+