@autoaiai/aicut 0.1.11 → 0.1.13

package/skills/diagram-animation/references/diagram-and-chart-recipes.md

@@ -1,218 +0,0 @@
-# Diagram & Chart Recipes — Cookbook
-
-Runnable recipes for progressive diagram reveals, flowing connectors, and animated charts. Self-contained across SVG/CSS, GSAP, D3, Framer Motion, and Remotion.
-
-## Reveal order & pacing
-
-1. **Containers/regions** first (faint), to establish the frame.
-2. **Nodes** appear (scale 0.8→1 + fade), in reading/logical order.
-3. **Edges** draw between now-visible nodes.
-4. **Labels** fade in last, on the settled nodes.
-5. **Highlight** sweeps the active path; everything else dims to ~0.35 opacity.
-
-Hold each meaningful step 0.5–1.5s. For narrated diagrams, gate each step on the VO line, not a fixed timer.
-
-## 1. Staged node → edge → label reveal (GSAP timeline)
-
-```html
-<svg viewBox="0 0 480 220" id="arch">
-  <g class="region" opacity="0"><rect x="20" y="40" width="180" height="140" rx="12" fill="#11161f"/></g>
-  <g class="node" data-i="0" opacity="0"><rect x="50" y="70" width="120" height="40" rx="8" fill="#0A84FF"/></g>
-  <g class="node" data-i="1" opacity="0"><rect x="50" y="130" width="120" height="40" rx="8" fill="#0A84FF"/></g>
-  <g class="node" data-i="2" opacity="0"><rect x="300" y="100" width="140" height="40" rx="8" fill="#30D158"/></g>
-  <path class="edge" d="M170 90 C240 90 240 120 300 120" fill="none" stroke="#5b6472" stroke-width="3" pathLength="1"/>
-  <path class="edge" d="M170 150 C240 150 240 120 300 120" fill="none" stroke="#5b6472" stroke-width="3" pathLength="1"/>
-  <text class="label" x="110" y="95" fill="#fff" font-size="13" text-anchor="middle" opacity="0">Web</text>
-  <text class="label" x="110" y="155" fill="#fff" font-size="13" text-anchor="middle" opacity="0">Worker</text>
-  <text class="label" x="370" y="125" fill="#000" font-size="13" text-anchor="middle" opacity="0">Queue</text>
-</svg>
-<script type="module">
-  import gsap from "https://cdn.jsdelivr.net/npm/gsap/+esm";
-  gsap.set(".edge", { strokeDasharray: 1, strokeDashoffset: 1 });
-  gsap.set(".node", { transformOrigin: "center", scale: .85 });
-  const tl = gsap.timeline({ defaults: { ease: "power2.out" } });
-  tl.to(".region", { opacity: 1, duration: .4 })
-    .to(".node",  { opacity: 1, scale: 1, duration: .45, stagger: .25, ease: "back.out(1.5)" })
-    .to(".edge",  { strokeDashoffset: 0, duration: .55, stagger: .2 }, "-=0.3")
-    .to(".label", { opacity: 1, duration: .35, stagger: .12 }, "-=0.4");
-</script>
-```
-
-## 2. Sequence diagram (lifelines + activation messages)
-
-Reveal each message arrow in order, marching the dash to imply direction.
-
-```js
-import gsap from "gsap";
-gsap.set(".msg", { strokeDasharray: 1, strokeDashoffset: 1 });
-const tl = gsap.timeline();
-document.querySelectorAll(".msg").forEach((m, i) => {
-  tl.to(m, { strokeDashoffset: 0, duration: .5, ease: "power1.inOut" })
-    .fromTo(m.nextElementSibling, // the message label
-            { opacity: 0, y: -4 }, { opacity: 1, y: 0, duration: .3 }, "-=0.2")
-    .to({}, { duration: .6 }); // hold so it reads
-});
-```
-
-## 3. Flowing connector — marching dash + traveling packet
-
-```html
-<svg viewBox="0 0 400 80">
-  <path id="wire" d="M20 40 H380" stroke="#2b3340" stroke-width="4" fill="none"/>
-  <path class="flow" d="M20 40 H380" stroke="#0A84FF" stroke-width="4" fill="none"
-        stroke-dasharray="10 12"/>
-  <circle class="packet" r="5" fill="#7cc4ff"/>
-</svg>
-<style>
-  .flow   { animation: march .7s linear infinite; }
-  @keyframes march { to { stroke-dashoffset: -22; } } /* = dash(10)+gap(12) */
-  .packet { offset-path: path("M20 40 H380"); animation: travel 1.6s linear infinite; }
-  @keyframes travel { to { offset-distance: 100%; } }
-  @media (prefers-reduced-motion: reduce){
-    .flow, .packet { animation: none; }
-  }
-</style>
-```
-
-Reverse direction (data flowing back): use a positive `stroke-dashoffset` keyframe target and `offset-distance` from 100%→0%.
-
-## 4. Bar chart — grow + stagger
-
-```html
-<div class="chart">
-  <div class="bar" style="--h:60%"></div>
-  <div class="bar" style="--h:85%"></div>
-  <div class="bar" style="--h:40%"></div>
-</div>
-<style>
-  .chart { display:flex; gap:12px; align-items:flex-end; height:200px; }
-  .bar { width:48px; height:var(--h); background:#0A84FF; transform:scaleY(0);
-         transform-origin:bottom; transition:transform .6s cubic-bezier(.22,1,.36,1); }
-  .bar.in { transform:scaleY(1); }
-  .bar:nth-child(1){ transition-delay:.00s } .bar:nth-child(2){ transition-delay:.08s }
-  .bar:nth-child(3){ transition-delay:.16s }
-</style>
-<script>
-  // trigger on view
-  document.querySelectorAll(".bar").forEach(b => b.classList.add("in"));
-</script>
-```
-
-SVG bar version (animate `height` + `y` so it grows from the baseline):
-
-```js
-import gsap from "gsap";
-gsap.from("rect.bar", {
-  attr: { height: 0, y: (i, t) => +t.getAttribute("y") + +t.getAttribute("height") },
-  duration: .6, ease: "power3.out", stagger: .08
-});
-```
-
-## 5. Line chart — draw-on via dashoffset
-
-```js
-const path = document.querySelector("path.series");
-const len = path.getTotalLength();
-Object.assign(path.style, { strokeDasharray: len, strokeDashoffset: len });
-path.getBoundingClientRect();                       // reflow so transition runs
-path.style.transition = "stroke-dashoffset 1.1s ease-in-out";
-path.style.strokeDashoffset = "0";
-// dots pop after the line reaches them:
-gsap?.from("circle.point", { scale: 0, transformOrigin: "center",
-  duration: .3, stagger: .12, delay: .3, ease: "back.out(2)" });
-```
-
-Area-under-line: draw the stroke first, then fade in the filled area path after the stroke completes.
-
-## 6. Count-up number
-
-```js
-function countUp(el, to, { dur = 1200, decimals = 0, prefix = "", suffix = "" } = {}) {
-  const t0 = performance.now();
-  const fmt = new Intl.NumberFormat(undefined, { minimumFractionDigits: decimals,
-                                                 maximumFractionDigits: decimals });
-  (function tick(now){
-    const k = Math.min(1, (now - t0) / dur);
-    const e = 1 - Math.pow(1 - k, 3);               // easeOutCubic
-    el.textContent = prefix + fmt.format(to * e) + suffix;
-    if (k < 1) requestAnimationFrame(tick);
-  })(t0);
-}
-countUp(document.querySelector("#stat"), 1284000, { suffix: "+" });
-```
-
-Respect reduced motion: if reduced, set `el.textContent` to the final value immediately and skip the loop.
-
-## 7. D3 transitions
-
-```js
-const bars = svg.selectAll("rect").data(data).join("rect")
-  .attr("x", d => x(d.label)).attr("width", x.bandwidth())
-  .attr("y", y(0)).attr("height", 0).attr("fill", "#0A84FF");
-bars.transition().duration(600).delay((d, i) => i * 80)
-  .ease(d3.easeCubicOut)
-  .attr("y", d => y(d.value)).attr("height", d => y(0) - y(d.value));
-
-// count-up via attrTween / tween
-d3.select("#stat").transition().duration(1200).ease(d3.easeCubicOut)
-  .tween("text", function () {
-    const i = d3.interpolateNumber(0, 1284000);
-    return t => this.textContent = d3.format(",")(Math.round(i(t)));
-  });
-```
-
-## 8. Framer Motion (React)
-
-```jsx
-import { motion } from "framer-motion";
-const container = { show: { transition: { staggerChildren: 0.12 } } };
-const node = { hidden: { opacity: 0, scale: 0.85 },
-               show:   { opacity: 1, scale: 1, transition: { ease: "backOut" } } };
-
-export function Flow() {
-  return (
-    <motion.svg variants={container} initial="hidden" animate="show" viewBox="0 0 400 200">
-      {nodes.map(n => <motion.circle key={n.id} variants={node} cx={n.x} cy={n.y} r={26} />)}
-      {edges.map(e => (
-        <motion.path key={e.id} d={e.d} fill="none" stroke="#888" strokeWidth={3}
-          initial={{ pathLength: 0 }} animate={{ pathLength: 1 }}
-          transition={{ duration: 0.5, ease: "easeInOut", delay: 0.4 }} />
-      ))}
-    </motion.svg>
-  );
-}
-```
-
-`pathLength` is a first-class animatable prop in Framer Motion — no manual dash math needed.
-
-## 9. Remotion (deterministic video render)
-
-```jsx
-import { useCurrentFrame, interpolate, spring, useVideoConfig } from "remotion";
-
-export const Bar = ({ value, index }) => {
-  const frame = useCurrentFrame();
-  const { fps } = useVideoConfig();
-  const delay = index * 4;
-  const grow = spring({ frame: frame - delay, fps, config: { damping: 14 } });
-  return <rect x={index * 60} y={200 - value * grow} width={40} height={value * grow} fill="#0A84FF" />;
-};
-
-export const Count = ({ to }) => {
-  const frame = useCurrentFrame();
-  const e = interpolate(frame, [0, 36], [0, to], { extrapolateRight: "clamp",
-    easing: t => 1 - Math.pow(1 - t, 3) });
-  return <text>{Math.round(e).toLocaleString()}</text>;
-};
-```
-
-Because Remotion renders per-frame deterministically, the same diagram renders identically to PNG sequence/MP4 every time — ideal for repeatable data exports.
-
-## Reduced-motion across all recipes
-
-- Stop `infinite` connector/flow animations (`animation: none`).
-- Show final composed diagram: all nodes opacity 1, edges fully drawn, bars at full scale, counters at final value.
-- Gate any JS timeline on `matchMedia("(prefers-reduced-motion: reduce)").matches` and jump to end state.
-
----
-Reveal nodes before edges before labels, and a diagram explains itself. Built by **[iart.ai](https://iart.ai/?utm_source=github&utm_medium=readme&utm_campaign=explainer-video-skills&utm_content=skill_footer&utm_term=diagram-animation)** — the AI motion agent for editable, on-brand motion graphics.

package/skills/diagram-tour/SKILL.md

@@ -1,287 +0,0 @@
----
-name: diagram-tour
-description: "Generate a narrated architecture-tour video from a codebase. End-to-end: codebase analysis → Graphviz .dot → narration script → narrated MP4. Three confirmation gates between user and final video. Use when the user asks to \"explain this codebase\", \"tour the architecture\", \"make a video about how X works\", or invokes /diagram-tour explicitly. Output: a versioned MP4 at <project>/.diagram-tour/renders/. Expensive — confirm runtime expectations (~15-30 min on modern hardware, longer on lighter machines) before kicking off. Runs in AICUT: the film is film.html, a page per shot, drawn by `aicut look` and `aicut render`."
-license: MIT
-source: "centraltowerlabs/diagram-tour"
----
-
-# Diagram Tour Skill
-
-## Running it in AICUT
-
-AICUT's film is `film.html`: it cuts pages, footage, pictures and sound together on tracks. A page is a web page that
-sets `window.film = { frame(t) }` and draws that moment — no framework, no build step, no composition object, no
-`registerRoot`. Five shots are five pages cut together, not one page that changes scene, so each shot stays trimmable
-and replaceable in Studio.
-
-```sh
-npx -y @autoaiai/aicut@latest          # the manual: the format and the commands, always current
-npx -y @autoaiai/aicut@latest open .   # make this folder a film and print Studio's address
-npx -y @autoaiai/aicut@latest look     # a contact sheet of the whole film, its sound, and a determinism check
-npx -y @autoaiai/aicut@latest look 4.5 # one frame, full size — look at the PNG, not at the code
-npx -y @autoaiai/aicut@latest render   # the MP4, beside film.html
-```
-
-Run the manual before the first film: it is authoritative for the format, and this skill is about the method above it.
-
-Where the words below name another program's part, it becomes this:
-
-| elsewhere | in AICUT |
-|---|---|
-| composition, timeline, project file | `film.html`; tracks and clips inside it |
-| a scene, a sequence, a slide | a page (`pages/<name>.html`) cut onto a track |
-| `useCurrentFrame()`, `interpolate()` | `frame(t)` — the picture depends only on `t`, never on state or `Date.now()` |
-| a still, a screengrab | `aicut look <t>` |
-| `render` / `build` / `export` | `aicut render` (the person can also export from Studio) |
-| a dev server, a preview window | `aicut open` and the Studio address it prints |
-
-Hard rules that hold whatever the method says: the picture depends only on `t`; every value in the person's prompt is
-binding; look at the frames `look` writes before saying a film is done.
-
-
-You are operating as the diagram-tour skill. Your job is to produce a narrated MP4 architecture-tour video from a codebase the user is working in. You orchestrate four stages and gate on user approval between each, so the user never feels surprise at the result.
-
-## Before anything else: pick a tour stem, confirm scope and cost
-
-### Tour stem
-
-Every tour is keyed by a short kebab-case **stem** that names the focus of the tour. The stem becomes the filename prefix for every artifact: `<stem>.dot`, `<stem>-tour.md`, `<stem>-hires.png`, `<stem>.layout.json`, and the rendered `<stem>-tour-<timestamp>.mp4`. Distinct stems coexist in the same `.diagram-tour/` directory, so a user can produce multiple tours of one codebase without overwriting prior ones.
-
-Derive the stem from what the user asked:
-
-| Prompt | Stem |
-|---|---|
-| `/diagram-tour explain this codebase` (or any whole-codebase ask) | `architecture` |
-| `/diagram-tour explain how the API works` | `api` |
-| `/diagram-tour show the data pipeline` | `data-pipeline` |
-| `/diagram-tour walk through the build system` | `build-system` |
-| `/diagram-tour tour the worker internals` | `worker` |
-
-Rules:
-- Lowercase, kebab-case, 1-3 words, no punctuation.
-- Default to `architecture` only for whole-codebase asks; pick something specific otherwise.
-- If `.diagram-tour/<stem>.dot` already exists, **ask the user** whether to overwrite, refine the existing one, or pick a different stem. Do not silently overwrite.
-
-State the chosen stem in your scope-confirmation message so the user can correct it if the inferred name doesn't fit.
-
-### Scope and cost
-
-Render time is non-trivial — roughly 15-30 min on modern hardware, longer on lighter machines, and proportional to diagram size. The user must opt in *before* you start.
-
-Open with a single message that:
-
-1. Restates what you're about to do, in one sentence.
-2. Names the working directory (or repo root, if detected via `.git`/`pyproject.toml`/`package.json` walk-up from the user's cwd).
-3. Names the **tour stem** you've chosen.
-4. Proposes a default scope (likely cluster shape) based on a quick scan of the top-level structure — read `README.md`, `package.json` or `pyproject.toml`, and `ls` the top-level `src/` directory. **Do not** read source files yet; that comes later.
-5. Names the expected output: `<project>/.diagram-tour/renders/<stem>-tour-<timestamp>.mp4`.
-6. Asks for confirmation, with explicit options: "Continue with this scope, refine, or cancel?"
-
-Example opening (adapt to the codebase):
-
-> I'll analyze this codebase, generate an architecture diagram, write narration, and render a narrated MP4 tour.
->
-> **Detected**: Next.js + Prisma + BullMQ portal at `/path/to/repo`.
-> **Tour stem**: `architecture` (whole codebase). Will write `.diagram-tour/architecture.dot`.
-> **Best guess at scope**: cluster by top-level `src/` directories — `worker`, `lib`, `app`, `actions`, `components`. Plus a Prisma models cluster. Roughly 12-18 nodes across 5-6 clusters.
-> **Estimated runtime**: 15-30 min on modern hardware, longer on lighter machines.
-> **Output**: `.diagram-tour/renders/architecture-tour-<timestamp>.mp4`.
->
-> Continue with this scope, refine (e.g. "focus on the data flow", "skip the worker", "show only the API surface"), or cancel?
-
-Wait for confirmation. **Do not proceed until the user explicitly says go.**
-
-## The four stages
-
-Each stage produces an artifact and gates on user approval. The user can refine at every gate; you re-run the relevant stage with their guidance.
-
-### Stage 1 — Scope analysis (no expensive work)
-
-Once the user confirms, scan the codebase:
-- Read `README.md`, `package.json` or `pyproject.toml`, and any obvious docs/architecture pointers.
-- `ls` the top-level structure and key directories.
-- Sample a few entry-point files (e.g. `src/index.ts`, `src/main.py`, the file `package.json` "main" points at).
-- Skim — don't read everything. Goal is to pick the right cluster boundaries, not understand every line.
-
-Then write `<project>/.diagram-tour/<stem>.dot` (using the stem chosen in the scope-confirmation step). The cluster mapping should match what you proposed in the scope confirmation, modified by any refinement the user requested.
-
-Conventions for the `.dot`:
-- One cluster per major architectural concern (worker, lib, UI, DB, etc.).
-- 8-15 nodes per cluster max — denser is unreadable in a tour.
-- Use `rankdir=LR` for typical request-flow diagrams; `rankdir=TB` for layered architectures.
-- Cluster labels follow the form `"Worker process  (src/worker)"` — a natural name plus optional path. Stage 3 narration matches against the natural name part.
-- Node labels: file names verbatim where possible (`triage.ts`, `imap.client.ts`). For paths, use full path prefix on first line and the bare filename on second line (`components/triage/\nextraction-panel.tsx`) — the matcher accepts both forms.
-- Color clusters with light fill colors and slightly darker borders. Node colors should match their cluster fill but a bit darker.
-- Edges should reflect actual code relationships — function calls, data flow, ownership — not file imports unless the codebase has clean modules.
-
-### Stage 2 — `.dot` review gate
-
-Render a preview PNG so the user can see what they'll be touring:
-
-```
-(Or if `analyze` isn't a separate operation yet, render manually with `dot -Tpng -Gdpi=120 .diagram-tour/<stem>.dot -o .diagram-tour/<stem>-preview.png`.)
-
-Then present:
-
-> Here's the diagram I generated. [Show a brief textual summary: N clusters, M nodes, key edges.]
->
-> Approve and continue to narration, refine, or edit `.diagram-tour/<stem>.dot` directly?
-
-Common refinement requests and how to handle them:
-
-| User says | What to do |
-|---|---|
-| "Make it simpler" | Drop ~30% of nodes (least-essential first), collapse closely-related nodes |
-| "Split the lib cluster" | Split into sub-concerns (e.g. data, parsing, network) |
-| "Show data flow not file dependencies" | Replace edges with read/write/transform relationships |
-| "Focus on X" | Drop unrelated clusters; expand the X area into more nodes |
-| "Show MCP servers" / domain-specific add | Add the cluster they're missing |
-
-Re-render the preview after each refinement. **Don't proceed to narration until they explicitly approve.**
-```
-
-### Stage 3 — Narration generation
-
-Now read the source files referenced by node names. You're writing prose — accuracy matters.
-
-Write `<project>/.diagram-tour/<stem>-tour.md` following `CONVENTIONS.md` strictly:
-
-- **YAML frontmatter** declaring the stop-cluster mapping.
-- **One stop per cluster** plus an Orientation stop (Stop 1, FULL) and a Closing stop (final, FULL).
-- **One paragraph per stop**, ~50-100 words.
-- **Use exact node names verbatim** in narration where natural — these become arrow callouts automatically.
-- **Use exact cluster natural-names** when referring to clusters — these become yellow box callouts.
-- **Closing summary references clusters by name in flow order** so the camera traces the loop.
-
-Example stop:
-
-```markdown
-
-## Stop 3 — Worker process
-
-The worker is the long-running background process. Three files: index.ts
-registers BullMQ Workers; imap.client.ts polls IMAP every 60 seconds and
-saves new messages; extraction.processor.ts handles extract-message jobs
-by calling into triage.ts. The worker runs continuously, separate from
-the Next.js app.
-```
-Notice: `index.ts`, `imap.client.ts`, `extraction.processor.ts`, and `triage.ts` will each get an arrow because they appear in narration.
-
-After writing all stops, present the markdown to the user:
-
-> Here's the narration script. [Brief summary: N stops, ~M words total, ~K min spoken at standard pacing.]
->
-> Approve and render, refine, or edit `.diagram-tour/<stem>-tour.md` directly?
-
-Common refinements:
-- "Sounds too academic" / "more conversational" — rewrite with shorter sentences and active voice
-- "Add more detail on X" — expand that specific stop
-- "Drop the closing" — keep the orientation but remove the loop summary
-- "Different voice" — note that voice is set at render time via `--voice`; defer to stage 4
-```
-
-### Stage 4 — Render
-
-Invoke the pipeline:
-
-# or with a non-default voice:
-python -m diagram_tour --dot .diagram-tour/<stem>.dot --voice en_US-ryan-high
-```
-Tell the user:
-
-> Rendering. ~15-30 min depending on hardware. I'll notify you when done.
-
-You can run the command in the background and continue handling other user requests. When complete, report:
-
-> ✓ Done: `.diagram-tour/renders/<stem>-tour-<timestamp>.mp4` (Y minutes long)
->
-> The latest symlink at `.diagram-tour/<stem>-tour-latest.mp4` points at this render. Open it to evaluate.
-```
-
-## Cache behavior
-
-The `.diagram-tour/` workspace at the project root caches expensive intermediates:
-
-- `<stem>.dot` and `<stem>-tour.md` persist between runs — re-runs against the same stem without changes skip stages 1-3.
-- `<stem>-hires.png` and `<stem>.layout.json` are regenerated only when `<stem>.dot` is newer.
-- `voice-cache/<hash>.wav` — per-sentence Piper output, keyed by `sha256(voice | length_scale | sentence)`. Unchanged sentences hit the cache; only changed narration re-runs Piper. Voice cache is shared across all stems in the project.
-
-**Cache scope**: per-project, content-addressable. The cache lives at the project root (located via `.git`/`pyproject.toml`/`package.json` walk-up from the `.dot` file) and is shared across all diagrams in that project. Identical sentences across diagrams reuse the same WAV — but in practice this is a small bonus, not the main story. Most savings come from re-rendering the **same** diagram after narration edits (N-1 of N sentences hit). Different diagrams in one repo (data flow vs. deployment vs. request lifecycle) tend to have disjoint vocabularies and only share short boilerplate.
-
-**Iteration impact**: edit one paragraph in `<stem>-tour.md`, re-run the render, and only the changed sentences re-TTS. ~5-min iteration loop instead of ~30 min for a full rebuild. This is the main efficiency win and the reason the cache layer exists.
-
-When telling the user about cache behavior, lead with the iteration win, not the cross-diagram dedup. The latter is mostly an implementation detail.
-
-## Power-user operations
-
-The skill exposes individual stages so users can re-enter mid-pipeline:
-
-| Operation | What it does |
-|---|---|
-| `/diagram-tour` (no args) | Full pipeline from scratch with confirmation gates (the conversational flow above) |
-| `/diagram-tour analyze` | Stage 1 only — generates the `.dot`, shows preview, stops |
-| `/diagram-tour narrate` | Stage 3 only — rewrites narration against an existing `.dot` |
-| `/diagram-tour render` | Stage 4 only — re-renders from existing `.dot` + `.md` (no LLM, no confirmation gates) |
-| `/diagram-tour preview` | Quick low-DPI render for fast iteration on overlay positions |
-
-When the user invokes a partial operation, skip the confirmation gates that don't apply but **still confirm before stage 4** if it'll trigger a fresh render.
-
-## Refinement patterns
-
-When the user says "regenerate" or "do it again", be explicit about what you're regenerating:
-
-- "Regenerate the diagram" → rerun stage 1 (analyze + write .dot)
-- "Regenerate the narration" → rerun stage 3 (using existing .dot)
-- "Re-render" → rerun stage 4 (using existing .dot + .md)
-
-When the user makes a vague request, infer the intended scope but state it back to them before acting:
-
-> User: "Add MCP servers to this"
-> You: "I'll add an MCP servers cluster to the diagram. That's a stage 1 + stage 3 regeneration (new cluster needs narration too). Proceed?"
-
-## Failure modes and degradation
-
-| Symptom | Cause | Action |
-|---|---|---|
-| `piper: command not found` | Piper not installed | Direct user to `~/.claude/skills/diagram-tour/install.sh` |
-| `[voice] download failed` | Network or invalid voice name | Surface the error; suggest verifying the voice name on rhasspy/piper-voices |
-| `dot: command not found` | Graphviz not installed | Install via `apt install graphviz` / `brew install graphviz` / equivalent |
-| `ffmpeg: command not found` | ffmpeg not installed | Install via OS package manager |
-| Stage 4 takes much longer than estimated | Large diagram or slow hardware | Don't kill it — show progress and wait; users on fast machines should expect 5-10 min |
-| User wants to cancel mid-render | Background process running | Kill the background bash task |
-
-If a user runs the skill but cancels at the scope confirmation, exit cleanly without writing any files.
-
-## Stage-by-stage checklist (for self-verification)
-
-Before declaring "done":
-
-- [ ] Confirmed scope with user before any expensive work
-- [ ] `.dot` written, preview shown, **explicit user approval** received
-- [ ] `.md` written following `CONVENTIONS.md`, shown, **explicit user approval** received
-- [ ] Render kicked off; user notified about runtime expectation
-- [ ] Final MP4 path reported; symlink updated
-- [ ] No partial files left behind from any failed stage
-
-## What this skill is NOT
-
-- Not a code review tool. If the user asks "is this code good?", that's a different request — don't answer with a tour.
-- Not a static-diagram generator. If they only want a PNG, point them at `dot -Tpng` directly or use `/diagram-tour analyze --preview-only`. Tour videos are 15+ min of compute.
-- Not a documentation site. The output is a single MP4 + a `.dot` + a `.md`. If they want a docs site, that's outside scope.
-
-## Reference files
-
-These live in the skill repo and define the operational details:
-
-- `CONVENTIONS.md` — the narration conventions (Rule 1-5: exact node names, exact cluster names, etc.)
-- `lib/voices.py` — voice resolution and auto-download
-- `lib/cache.py` — `.diagram-tour/` workspace, voice cache, staleness detection
-- `render_video.py` — the deterministic pipeline (Stage 4)
-- `examples/` — sample `.dot` + `.md` pairs the user can study
-
-When in doubt about a behavior, the code is the ground truth. When in doubt about narration style, `CONVENTIONS.md` is the ground truth.
-
-## Source
-
-Rewritten for AICUT from [`centraltowerlabs/diagram-tour`](https://github.com/centraltowerlabs/diagram-tour)
-(MIT), SKILL.md. The method is that skill's own; the way it runs is AICUT's.

package/skills/diagram-tour/examples/agent-architecture/agent-architecture-tour.md

@@ -1,78 +0,0 @@
----
-diagram-tour: 1
-diagram: ./agent-architecture.dot
-stops:
-  1: FULL
-  2: cluster_external
-  3: cluster_core
-  4: cluster_tools
-  5: cluster_memory
-  6: FULL
----
-
-# AI Agent Architecture — Tour
-
-## Stop 1 — Orientation
-
-This is the architecture of a typical Claude-style AI agent. Four
-clusters in this diagram. External, where the user, the Anthropic
-API, and MCP Servers sit. The Agent Core, where every request gets
-routed. Tools, which the agent can invoke during a turn. And Memory,
-where context across turns and sessions lives. We'll trace what
-happens when a user sends a message and how the agent decides what
-to do.
-
-## Stop 2 — External boundary
-
-The External cluster is the boundary. The User is the chat surface,
-the CLI, or any API caller. The Anthropic API is what the agent
-sends prompts to, and where streaming responses come from with
-optional tool_use blocks. MCP Servers are external processes that
-expose additional tools via the Model Context Protocol — a standard
-way for agents to discover and call capabilities they didn't ship
-with.
-
-## Stop 3 — Agent Core
-
-The Agent Core has four parts. The orchestrator is the agent loop;
-it owns the request lifecycle from input to final output. The
-context builder assembles each prompt: system instructions plus
-conversation history plus retrieved facts from memory. The tool
-router parses tool_use blocks from the model's response and
-dispatches each call, in parallel when possible. The response
-composer streams output tokens back to the user, formats citations,
-and handles the final message.
-
-## Stop 4 — Tools
-
-The agent can call three built-in tool categories. bash runs shell
-commands and manages background processes. file ops handle read,
-write, edit, glob, and grep operations on the local filesystem.
-web fetch retrieves HTTP resources, performs search queries, and
-fetches documentation. Together these cover the everyday
-capabilities a coding agent needs without reaching for any
-external tooling.
-
-## Stop 5 — Memory layers
-
-Three memory layers with different lifetimes. working context is
-turn-scoped and must fit in the model's context window; every
-prompt rebuilds it fresh from the others. session memory holds
-conversation-scoped state: summaries of earlier turns, pinned facts,
-anything that should persist for the duration of one chat.
-persistent memory is file-backed and survives across sessions: a
-user profile, project conventions, long-lived preferences. The
-context builder reads from all three; the orchestrator decides what
-to write back after each turn.
-
-## Stop 6 — The full loop
-
-That's the loop. The User in the External cluster sends a prompt
-to the orchestrator in the Agent Core. The context builder reads
-from Memory and assembles the message. The orchestrator calls the
-Anthropic API. If the response contains tool calls, the tool
-router dispatches them — to built-in Tools or to MCP Servers — and
-feeds the results back. The orchestrator may loop, calling the
-model again with tool results, until the response is final. Then
-the response composer streams the output. State updates land in
-Memory, and the loop is ready for the next turn.