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

package/runtime/claude/.claude/skills/visual-explain/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: visual-explain
+description: Explain concepts visually using ASCII diagrams, flow charts, tables, and structural maps. Use when asked to explain, compare, or show how something works.
+---
+
+# Visual Explain
+
+Explain concepts visually using ASCII diagrams, tables, flow charts, and structural maps. The visual IS the explanation — prose is secondary.
+
+## When to invoke
+
+Trigger phrases: "explain visually", "show me a diagram", "draw this out", "chart this", "map this", "visualize this", "show me how this works", "diagram this", "sketch this out".
+
+Also invoke when `/visual-explain` is used directly.
+
+## Visual vocabulary
+
+Use the right format for the right job:
+
+| Concept type | Visual format |
+|---|---|
+| Flows and pipelines | ASCII arrow diagrams (`→`, `↓`, `──▶`) |
+| Architecture / components | Box diagrams with labeled connections |
+| Comparisons and trade-offs | Tables with columns per option |
+| Hierarchies and containment | Tree structures or nested box diagrams |
+| Temporal sequences | ASCII sequence diagrams (actor columns + arrows) |
+| State changes | Before/after side-by-side diagrams |
+| Decision logic | Flowcharts with diamond decision nodes |
+
+## Rules
+
+1. **Lead with the visual.** Always produce the diagram or table FIRST. Prose comes after, if needed at all.
+
+2. **Minimal prose.** Keep explanatory text to 1-2 sentences per diagram. The visual carries the explanation — prose only clarifies what the visual cannot.
+
+3. **Prefer multiple small diagrams over one complex one.** Break a system into 2-3 focused visuals rather than cramming everything into a single diagram. Each diagram should have one clear point.
+
+4. **Consistent visual language:**
+   - `[ boxes ]` for components, modules, services
+   - `──▶` or `→` for data flow and control flow
+   - `───` for connections and relationships
+   - `< diamonds >` for decisions
+   - `( rounded )` for inputs/outputs
+   - `│` and `─` for structure lines
+
+5. **System explanations follow this order:**
+   - Structure first (what are the parts, how do they relate)
+   - Data flow second (what moves between them)
+   - State changes third (how things evolve over time)
+
+6. **Comparisons follow this order:**
+   - Table first (options as columns, criteria as rows)
+   - Annotate the recommended choice with a brief reason below the table
+
+7. **Keep diagrams under 40 lines tall and 72 characters wide.** If a diagram exceeds this, split it into multiple diagrams with clear labels.
+
+## Examples
+
+### Flow diagram
+```
+  [ User Request ]
+         │
+         ▼
+  [ Auth Middleware ] ──▶ [ 401 Unauthorized ]
+         │
+         ▼
+  [ Route Handler ]
+         │
+    ┌────┴────┐
+    ▼         ▼
+ [ Cache ] [ Database ]
+    │         │
+    └────┬────┘
+         ▼
+  [ Response ]
+```
+
+### Comparison table
+```
+                 Option A        Option B        Option C
+  ──────────────────────────────────────────────────────────
+  Speed          Fast            Medium          Slow
+  Cost           $$$             $$              $
+  Complexity     High            Medium          Low
+  Reliability    High            High            Medium
+  ──────────────────────────────────────────────────────────
+  ✓ Recommended: Option B — best balance of cost and speed.
+```
+
+### Sequence diagram
+```
+  Client          Server          Database
+    │                │                │
+    │── POST /api ──▶│                │
+    │                │── INSERT ─────▶│
+    │                │◀── OK ─────────│
+    │◀── 201 ────────│                │
+    │                │                │
+```
+
+### Hierarchy / tree
+```
+  egregore/
+  ├── bin/            Shell scripts (graph, notify, telemetry)
+  ├── skills/         Cognitive skill definitions
+  │   ├── harvest/
+  │   └── tui-design/
+  ├── memory/         Symlink → shared memory repo
+  │   ├── people/
+  │   ├── handoffs/
+  │   └── knowledge/
+  └── .claude/
+      ├── commands/   Slash command definitions
+      └── skills/     Claude Code skill files
+```
+
+### Before/after
+```
+  BEFORE                          AFTER
+  ┌──────────────────┐            ┌──────────────────┐
+  │ Monolith         │            │ API Gateway       │
+  │  ┌────────────┐  │            │                   │
+  │  │ Auth       │  │            └─────────┬─────────┘
+  │  │ API        │  │                      │
+  │  │ DB         │  │              ┌───────┼───────┐
+  │  │ Queue      │  │              ▼       ▼       ▼
+  │  └────────────┘  │           [ Auth ] [ API ] [ Worker ]
+  └──────────────────┘              │       │       │
+                                    └───┬───┘       │
+                                        ▼           ▼
+                                     [ DB ]     [ Queue ]
+```

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

@@ -0,0 +1,98 @@
+---
+name: wrap
+description: "Close the current Egregore session with a personal, canonical summary. Use for /wrap or when the user says they are done, wrapping up, or at a stopping point. Route work assigned to another person to /handoff and save-without-closing to /save."
+---
+
+# Personal session wrap
+
+Record what this actor finished, what was verified, and what remains. A wrap is
+personal session closure, not a handoff, notification, publication, or claim
+that an organizational obligation is complete.
+
+Canonical Markdown and Git provenance are authoritative. The Egregore Runtime
+owns authorization, stable ActorContext resolution, persistence, provenance,
+retrieval refresh, background embedding, and content-free telemetry through
+one writeback transaction.
+
+## When to invoke
+
+Close the current Egregore session with a personal, canonical summary. Use for /wrap or when the user says they are done, wrapping up, or at a stopping point. Route work assigned to another person to /handoff and save-without-closing to /save.
+
+## Prepare
+
+1. Reuse the current conversation and relevant `EGREGORE_ORG_CONTEXT_V1`
+   evidence. Do not search organizational memory again merely to summarize the
+   session.
+2. Derive a short topic, a two-to-four sentence summary, verified outcomes,
+   and concise open threads. Separate completed work from unverified work.
+3. If the proposed summary is materially ambiguous, show it once and ask for
+   correction. Skip confirmation when the user already supplied exact wrap
+   wording.
+4. If project changes need delivery, invoke `/save` once before the wrap. That
+   is a separate project-delivery action; do not reproduce Git commands in this
+   skill and do not run a second save after canonical wrap succeeds.
+
+Use this body shape, omitting empty sections:
+
+```markdown
+## Summary
+
+<what changed and the current state>
+
+## Completed
+
+- <completed outcome>
+
+## Verification
+
+- <test or check and its result>
+
+## Open Threads
+
+- [ ] <unfinished item or next step>
+```
+
+## Write once
+
+Pipe the body to the Runtime-neutral wrap adapter in one command — no
+temporary files, no multi-step assembly:
+
+```bash
+bash bin/agent.sh wrap \
+  --topic "$TOPIC" \
+  --summary "$SUMMARY" <<'EGREGORE_WRAP'
+<body markdown>
+EGREGORE_WRAP
+```
+
+Do not call `artifact-writeback.sh`, `capture-run.sh`, Git, QMD, graph,
+telemetry, publication, or notification mechanics directly. The adapter enters
+one personal canonical writeback transaction:
+
+`authorize → persist Markdown → Git provenance → retrieval update → background embed → telemetry`
+
+On success, report the returned `memory/wraps/...` path and the project save
+status. If the adapter fails, show the concise error and stop; never fall back
+to writing the file or updating projections directly.
+
+## Lifecycle boundary
+
+- A personal wrap never creates a recipient obligation; use `/handoff` for
+  work another person must receive or continue.
+- A wrap never silently completes, expires, or supersedes a handoff, quest,
+  todo, or thread. Age is not completion evidence.
+- The canonical wrap receipt may support a later, explicitly authorized
+  lifecycle transition. That lifecycle service must verify the target,
+  expected revision, actor membership, and typed evidence separately.
+- Keep open threads in the wrap even when they are also promoted through their
+  own quest/todo/thread Runtime action.
+
+## Output
+
+The adapter renders the wrap result card — actor, topic, summary,
+open-thread count, canonical path, and save/writeback status — as its
+stdout. The card is already fully visible there and must appear exactly once
+in the conversation. Never copy, re-render, summarize, or repeat it in your
+reply; add nothing beyond an answer to something the user separately asked.
+Do not claim `graphed`, `published`, `notified`, or `shared` unless a
+separate explicit action actually occurred.