create-egregore 0.20.2 → 0.21.0-runtime-mvp.2

package/runtime/claude/.claude/skills/emissary/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: emissary
+description: Compose, send, or run an Egregore emissary — portable handoff v1 artifacts with server-rendered HTML at egregore.xyz. Use for `/emissary`, "make/send/run an emissary", or when a user pastes an `egregore.xyz/emissary/e/<id>` link.
+---
+
+Topic: $ARGUMENTS
+
+## When to invoke
+
+User says: "/emissary", "make an emissary", "let's make an emissary", "send an emissary to <name>", "create an emissary", "run this emissary", or pastes an `egregore.xyz/emissary/e/<id>` link.
+
+Not this: user wants a **team session-handoff** (recap of what happened this session, addressed to a teammate, indexed in Neo4j, posted to Telegram) → that's `/handoff`. The two are siblings, not competitors: `/handoff` is the internal recap; `/emissary` is the portable, executable capsule.
+
+## Relationship to the framework skill
+
+The framework-level `egregore-emissary` skill (installed via `npx egregore-emissary install`, lives at `~/.claude/skills/egregore-emissary/SKILL.md`) owns the compose / publish / run flow end-to-end. This project skill is a **thin Egregore overlay** on top of it:
+
+1. **Delegate the compose/run** to the framework skill — its full procedure (interview via AskUserQuestion, shape decision, answers JSON, self-check, `npx egregore-emissary@latest new --answers ...`) is the source of truth. Do not duplicate it here. Follow it.
+2. **Add the Egregore overlay** — see Step 6 below — once the framework skill has produced a URL.
+
+If the framework skill is missing (path above does not exist), tell the user: "the `egregore-emissary` skill isn't installed — run `npx egregore-emissary@latest install`" and stop. Do not try to reconstruct it from memory.
+
+## Intent routing
+
+| Signal | Intent | Branch |
+|---|---|---|
+| Pasted `egregore.xyz/emissary/e/<id>` link, or "run this", "open this packet" | **run** | follow the framework skill's "Run an emissary" procedure. Stop after that — no Egregore overlay on runs. |
+| "make / create / compose an emissary", "let's make an emissary", "send an emissary to <name>", bare `/emissary` | **create** | follow the framework skill's "Create an emissary" procedure for steps 1–4, then do **Step 6** below. |
+| "enact my {name} emissary", "run my starred {name}", "list my stars", "what have I starred", or a pasted `@{handle}/{slug}` address | **enact starred** | the platform runtime-addressability verb (spec §2.5) — see "Enact a starred emissary" below. Stop after that — no overlay on runs. |
+
+## Enact a starred emissary (platform §2.5)
+
+Star on the web, enact in the terminal. The chain: starred list → resolve
+per star mode → fetch `/raw` → normal enactment.
+
+Base URL: `https://egregore.xyz` (override with `EMISSARY_WEB_ORIGIN` if
+set — smoke rigs point this at a local stub server).
+
+1. **Token.** Read the auth token from `~/.egregore/emissary-config.json`
+   (`.auth_token` via `jq -r`, or `EMISSARY_CONFIG_PATH` if set). Never
+   print it — it is a credential. If absent: "no emissary identity on
+   this machine — run `npx egregore-emissary@latest install`" and stop.
+
+2. **Star list.** `GET {base}/api/v1/platform/stars` with
+   `Authorization: Bearer <token>`. Cache the response to
+   `~/.egregore/platform/stars-cache.json` (best-effort) so "list my
+   stars" works offline; refresh the cache on every successful fetch.
+   On "list my stars" intent: render address · topic · mode · version
+   per star and stop.
+
+3. **Match by name.** Resolve the user's phrase against each star's
+   `slug`, `address`, and `topic` (case-insensitive substring is fine —
+   e.g. "deep research" matches `@cem/deep-research`). One match →
+   proceed. Several → AskUserQuestion with the candidate addresses.
+   None → show the starred addresses, stop.
+
+4. **Resolve per mode.** The endpoint already resolved for you:
+   - `mode: "pin"` → `resolved_id` is the exact version evaluated at
+     star time (supply-chain-safe default; never silently follow a
+     moved head).
+   - `mode: "follow"` → `resolved_id` is the current head. If
+     `updated_since_star` is true, STOP and re-consent before enacting:
+     "**@{owner}/{slug} has updated since you starred it** (you
+     evaluated v{evaluated}, head is now v{current}). Enact the new
+     version?" — AskUserQuestion: Enact new head / Show what changed
+     (`GET {base}/api/v1/platform/@{owner}/{slug}/versions`) / Cancel.
+     Only proceed on explicit yes.
+
+5. **Fetch + enact.** `GET {base}/emissary/e/{resolved_id}/raw` with the
+   bearer token. From here it is a normal run: follow the framework
+   skill's "Run an emissary" procedure with the fetched artifact (frame,
+   intake, confirm, execute, hand over, donate). No Egregore overlay.
+
+## Step 0: Identity
+
+Derive the lowercase author handle from `git config user.name` (first word, lowercased). Used for the memory pointer filename in Step 6.
+
+In connected mode, you may also need the display name — read `memory/people/<handle>.md` first line (`# Display Name`).
+
+## Steps 1–5: Framework skill
+
+Run the framework `egregore-emissary` skill's procedure for the chosen intent:
+
+- **run** → its "Run an emissary" section (fetch, frame, intake, confirm, execute, hand over, donate). Then **stop** — no overlay.
+- **create** → its "Create an emissary" section (interview → decide shape → compose answers JSON → self-check → `npx egregore-emissary@latest new --answers <file>`). Once you have the returned `egregore.xyz/emissary/e/<id>` link, continue to Step 6.
+
+The framework skill is comprehensive. Do not improvise around it.
+
+## Step 6: Egregore overlay (create flow only)
+
+After the framework skill returns the published URL, do two small things — both fire-and-forget, neither gates the user's experience.
+
+### 6a: Memory pointer
+
+Write a one-screen pointer file so the team can see this emissary on `/activity` and so memory carries a record without re-hosting the artifact.
+
+Path: `memory/handoffs/outbound/YYYY-MM-DD-<author>-<slug>.md`
+
+Slug rules: lowercase, alphanumeric and hyphens only, derived from the emissary `topic` field, truncated at 60 chars. If a file exists at that path, append `-2`, `-3`, etc.
+
+Body:
+
+```markdown
+# Emissary: <topic>
+
+**Date**: YYYY-MM-DD
+**Author**: <Display Name>
+**Kind**: <kind>
+**Distribution**: <public | person>
+**Recipients**: <comma-separated emails, or "public link">
+**URL**: <egregore.xyz/emissary/e/<id>>
+
+## Claim
+
+<one sentence — what running this produces>
+
+## Ask
+
+<one sentence, or omitted if no ask>
+
+## Summary
+
+<one paragraph from the artifact's summary field>
+```
+
+Omit any section that is empty.
+
+Then prepend a one-line entry to `memory/handoffs/index.md`:
+
+```
+- YYYY-MM-DD — <author>: emissary — <topic> → <url>
+```
+
+Commit and push:
+
+```bash
+cd memory && git add handoffs/outbound/ handoffs/index.md && \
+  git commit -m "emissary pointer: <topic>" >/dev/null 2>&1 && \
+  git pull --rebase --no-edit >/dev/null 2>&1 && \
+  git push >/dev/null 2>&1 &
+```
+
+Detached. Do not block the user on the push.
+
+### 6b: Neo4j index (connected mode only)
+
+Mode detection:
+
+```bash
+MODE=$(jq -r '.mode // "local"' egregore.json 2>/dev/null)
+```
+
+If `MODE == "connected"`, fire-and-forget a minimal index call:
+
+```bash
+SESSION_ID="$(cat .egregore-session-id 2>/dev/null)"
+bash bin/graph.sh query "
+  MERGE (e:Emissary {id: \$emissaryId})
+  ON CREATE SET e.created = datetime(), e.topic = \$topic, e.kind = \$kind, e.url = \$url
+  WITH e
+  MATCH (p:Person {github: \$author})
+  MERGE (p)-[:SENT_EMISSARY]->(e)
+  WITH e
+  OPTIONAL MATCH (s:Session {id: \$sessionId})
+  FOREACH (_ IN CASE WHEN s IS NOT NULL THEN [1] ELSE [] END |
+    MERGE (s)-[:PRODUCED]->(e))
+  RETURN e.id" >/dev/null 2>&1 &
+```
+
+Pass `emissaryId`, `topic`, `kind`, `url`, `author`, `sessionId` via the standard `bin/graph.sh` parameter mechanism (whatever the project uses for $-substituted Cypher; if unsure, read another graph-using script — `bin/index-handoff.sh` is the canonical example).
+
+If `bin/graph.sh` is unavailable, skip silently. Local mode skips entirely. This is best-effort; the artifact and the memory pointer are the source of truth.
+
+## Step 7: Render the receipt
+
+After the framework skill has handed back the URL and the overlay has fired, render one acknowledgment to the user. Same boundary style as `/handoff` — 72-char wide box, four line patterns:
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  ⇌ EMISSARY SENT                                  {Author} · {MMM DD}  │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  Topic: {topic}                                                      │
+│  Kind:  {kind}                                                       │
+│  To:    {recipient(s) or "public link"}                              │
+│                                                                      │
+│  {claim, wrapped at ~64 chars}                                       │
+│                                                                      │
+├──────────────────────────────────────────────────────────────────────┤
+│  ✓ published · pointer saved{ · graphed if connected}                │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+Below the box, one line:
+
+```markdown
+[open emissary →]({url})
+```
+
+Share the bare page link — not a `/raw` URL or a "Run this … packet" prompt. With the emissary skill installed, pasting the link is enough; this de-alarmed handover (see the data-room variant-A flow in `bin/build-sealed-dataroom.mjs`) avoids tripping a recipient agent's prompt-injection alarms.
+
+If natural, add one short sentence of sign-off — what the recipient should do next, or "shared publicly — anyone with the link can run it."
+
+## Edge cases
+
+| Scenario | Handling |
+|---|---|
+| Framework skill missing | Stop, tell the user to run `npx egregore-emissary@latest install`. Do not reimplement. |
+| User has no emissary identity (publish fails with auth error) | Stop, surface the framework skill's error verbatim. Do not run `emissary install` for them — it's their identity. |
+| `npx egregore-emissary` returns non-zero | Surface stderr, do not write the memory pointer (no URL = nothing to point at). |
+| Memory push fails in 6a | Stay silent. The file is on disk locally; next `/save` or `/handoff` pushes it. |
+| Connected-mode graph query fails | Silent. The pointer file is the source of truth. |
+| User wants to receive ↦ a link is in $ARGUMENTS | Skip Step 6 entirely. Runs don't get an overlay. |
+
+## Why this is two skills, not one merged with /handoff
+
+- `/handoff` is **team-internal session recap**: indexed Session node, Telegram team ping, addressed to a teammate or self, repo state captured, auto-PR'd memory. Receivers are inside the org.
+- `/emissary` is **portable executable capsule**: handoff/v1 JSON-LD artifact, server-rendered at egregore.xyz, optionally addressed to an external email, may or may not relate to a team session at all.
+
+A session-handoff that *also* needs to be sent externally → run `/handoff` first, then `/emissary` separately. Don't try to bundle them.

package/runtime/claude/.claude/skills/handoff/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: handoff
+description: "Create an internal Egregore team handoff to a teammate or future self. Use when the user says /handoff, asks to pass work or context, or wants an operational continuation record. Route external or executable capsules to /emissary, pending-work triage to /activity, and personal closure to /wrap."
+---
+
+# Internal team handoff
+
+Create one typed handoff in `memory/handoffs/`. Canonical Markdown and Git
+provenance are authoritative. Runtime owns authorization, stable identity,
+persistence, provenance, retrieval refresh, background embedding, and
+content-free telemetry.
+
+Use this only for internal handoffs. Route external capsules to `/emissary`,
+pending-work triage to `/activity`, and personal closure to `/wrap`.
+
+## When to invoke
+
+Create an internal Egregore team handoff to a teammate or future self. Use when the user says /handoff, asks to pass work or context, or wants an operational continuation record. Route external or executable capsules to /emissary, pending-work triage to /activity, and personal closure to /wrap.
+
+## Bounded capture
+
+A handoff records known context; it is not a research, audit, planning, or
+verification ritual.
+
+- Use the user's prompt, current conversation, and attached
+  `EGREGORE_ORG_CONTEXT_V1`. When that context is attached, do not repeat
+  organizational retrieval.
+- If no organizational context is attached and the requested handoff
+  semantically depends on prior organizational work that is absent from the
+  conversation, follow the actor context's one Runtime/QMD recall instruction.
+  This is the only allowed retrieval: use its returned evidence without a
+  second query or opening more sources.
+- Do not otherwise search, inspect Git, read repository files, query
+  migration/skill manifests, run status/tests, or spawn agents to improve the
+  handoff.
+- Include branches, files, decisions, tests, and remaining work only when
+  already known from those inputs. Label uncertainty briefly; if the handoff
+  cannot be drafted responsibly, ask one focused question instead of exploring.
+- “To myself” resolves to `Actor display name` in the attached
+  `EGREGORE_ACTOR_CONTEXT_V1`. Never infer it from the OS username, Git, or
+  GitHub. If that block is unavailable, ask for the handle rather than
+  guessing. Do not perform a people-directory lookup. Ask once only for a
+  genuinely ambiguous teammate.
+- Infer `intent`: `action`, `feedback`, or `fyi`.
+
+Before approval, use at most one optional Runtime/QMD recall command, followed
+by the preview command below.
+After approval, use exactly one shell command: writeback plus card rendering.
+Do not perform notification or publication work unless separately requested.
+
+## Canonical Markdown
+
+Use this envelope:
+
+```markdown
+---
+capture_schema: egregore-capture/v1
+capture_mode: addressed
+kind: addressed
+from: <actor handle>
+addressed_to: <recipient, if known>
+date: YYYY-MM-DD
+topic: <topic>
+intent: <action | feedback | fyi>
+content_mode: <supplied | generated>
+claim: <one-line current state>
+ask: <what the receiver should do>
+---
+
+<canonical handoff body>
+```
+
+Preserve supplied wording, order, headings, lists, code, and links. For
+generated content, use only the useful subset of Briefing, Current State, Open
+Threads, and Next Steps. Keep it operational and concise.
+
+## One-command preview
+
+Pipe the exact canonical Markdown once to the private preview bridge. It stores
+the approved bytes in an OS-private, short-lived record and returns an opaque
+`HANDOFF_PREVIEW_TOKEN`. Retain that token for the approval turn. Do not create
+checkout or draft files yourself. The bridge renders with `--verify-fidelity`.
+If the renderer reports that its local dependencies are missing, stop and
+report that prerequisite. Never install packages or repeat the full preview
+command inside the handoff workflow.
+
+```bash
+bash bin/handoff-preview.sh preview \
+  --author "$AUTHOR" --recipient "$RECIPIENT" --topic "$TOPIC" \
+  --intent "$INTENT" --content-mode "$CONTENT_MODE" <<'EGREGORE_HANDOFF'
+<exact canonical Markdown>
+EGREGORE_HANDOFF
+```
+
+Show the browser preview and wait for approval unless explicitly waived.
+Preview is not canonical writeback. Preview approval is not sharing consent.
+
+## One-command approval
+
+After approval, submit only the opaque token returned by preview. Never replay,
+regenerate, or include the canonical Markdown in the approval command. The
+bridge consumes the exact previewed bytes, performs one Runtime transaction,
+and renders the deterministic result card in the same invocation:
+
+```bash
+bash bin/handoff-preview.sh approve "<HANDOFF_PREVIEW_TOKEN>"
+```
+
+The token is private, expires after six hours, and is consumed after a
+successful canonical write. Do not add a cleanup trap or recursive deletion to
+the approved command; the bridge manages only its exact private records.
+
+Omit `--recipient` from the preview command only for an unaddressed
+continuation. Runtime performs authorize → canonical persist → Git provenance
+→ retrieval update → background embed → telemetry. The result card is the
+command's stdout and is already fully visible there, canonical `memory/...`
+path included — it must appear exactly once in the conversation. Never copy,
+re-render, summarize, or repeat it in your reply. Do not print raw JSON.
+Do not run a second save or manage Git, QMD, graph, publication, or
+notification.
+
+If writeback fails, report the concise error and stop. External sharing is a
+separate `SHARE` action requiring an explicit user request and exact
+destination/payload approval.