@ztffn/presentation-generator-plugin 1.0.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "presentation-generator",
+  "description": "Generate complete graph-based presentations from natural language briefs and project documents. Includes a three-agent pipeline: content extraction, narrative design, and graph JSON compilation.",
+  "version": "1.0.0",
+  "author": {
+    "name": "Huma"
+  },
+  "homepage": "https://github.com/huma/humashowcase",
+  "keywords": ["presentation", "slides", "react-flow", "graph", "pitch deck"]
+}

package/.github/workflows/publish.yml

@@ -0,0 +1,59 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish-npm:
+    name: Publish to npm
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          registry-url: "https://registry.npmjs.org"
+
+      - run: npm publish --provenance --access public
+
+  release-zip:
+    name: Create GitHub Release with zip
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build zip
+        run: |
+          VERSION=${GITHUB_REF_NAME}
+          ZIP_NAME="presentation-generator-plugin-${VERSION}.zip"
+          zip -r "$ZIP_NAME" . \
+            --exclude "*.git*" \
+            --exclude ".github/*" \
+            --exclude "node_modules/*"
+          echo "ZIP_NAME=$ZIP_NAME" >> $GITHUB_ENV
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          name: ${{ github.ref_name }}
+          body: |
+            ## Install via zip (non-technical)
+
+            1. Download `${{ env.ZIP_NAME }}` below
+            2. Unzip it anywhere on your machine
+            3. In Claude Code, run: `claude --plugin-dir /path/to/presentation-generator-plugin`
+
+            ## Install via npx (developers)
+
+            ```bash
+            npx @ztffn/presentation-generator-plugin install
+            ```
+          files: ${{ env.ZIP_NAME }}

package/README.md

@@ -0,0 +1,161 @@
+# Presentation Generator Plugin
+
+Generates complete graph-based presentations from a natural language brief and optional project documents. Uses a three-agent pipeline: content extraction → narrative design → graph JSON compilation.
+
+## What it produces
+
+A `_temp/presentation-draft.json` file you import directly into the graph editor at `/present/plan` via **New presentation → Import JSON**. The result is a fully navigable presentation with correct edge wiring, positioned nodes, and visual treatments applied.
+
+## Install
+
+Requires Claude Code 1.0.33 or later.
+
+### Option A — download zip (no technical setup)
+
+1. Go to [Releases](https://github.com/ztffn/presentation-generator-plugin/releases) and download the latest `presentation-generator-plugin-vX.X.X.zip`
+2. Unzip it anywhere on your machine
+3. Load it in Claude Code:
+
+```bash
+claude --plugin-dir /path/to/presentation-generator-plugin
+```
+
+To always have it available in a project, add it to `.claude/settings.json`:
+
+```json
+{
+  "plugins": [
+    { "path": "/path/to/presentation-generator-plugin" }
+  ]
+}
+```
+
+To update: download the new zip from Releases, replace the old folder.
+
+### Option B — install via npx (requires Node.js 18+ and GitHub auth)
+
+**Install the plugin:**
+
+```bash
+npx @ztffn/presentation-generator-plugin install
+```
+
+The installer clones the plugin to `~/.claude/plugins/presentation-generator/` and offers to configure your project's `.claude/settings.json` automatically.
+
+**Update to the latest version:**
+
+```bash
+npx @ztffn/presentation-generator-plugin update
+```
+
+**Check if an update is available:**
+
+```bash
+npx @ztffn/presentation-generator-plugin check-update
+```
+
+## Usage
+
+Once the plugin is loaded, trigger the skill by asking Claude to create a presentation:
+
+```
+Create a pitch presentation for Calora targeting VP Operations, drawing from docs/business/Calora_Overview.pdf
+```
+
+```
+Build a 15-minute investor deck using docs/business/Huma_Overview_Read_First.pdf
+```
+
+```
+Generate slides for an internal update on the Q2 roadmap scope change
+```
+
+Claude will automatically detect the intent and run the pipeline. No slash command needed — the skill is model-invoked.
+
+## Pipeline
+
+```
+User Brief + Documents
+        ↓
+  [1] Content Extraction      →  _temp/presentation-content-brief.json
+        ↓
+  [2] Narrative Design        →  _temp/presentation-outline.md
+        ↓
+  [3] User Approval           →  confirm or revise structure
+        ↓
+  [4] Design & JSON           →  _temp/presentation-draft.json
+        ↓
+  [5] Delivery                →  import instructions + media checklist
+```
+
+You review and approve the structure before any JSON is generated. If the structure needs changes, describe them and Claude revises before proceeding.
+
+## Agents
+
+| Agent | Role |
+|---|---|
+| `presentation-content` | Reads source documents, extracts a structured content brief |
+| `presentation-narrative` | Selects a narrative framework, designs spine and drill-downs, writes slide content |
+| `presentation-design` | Translates the approved outline into valid graph JSON |
+
+Each agent loads only the knowledge it needs — narrative agents never see layout decisions; design agents never read source documents.
+
+## Output files
+
+| File | Created by | Purpose |
+|---|---|---|
+| `_temp/presentation-content-brief.json` | Content agent | Structured brief passed to narrative agent |
+| `_temp/presentation-outline.md` | Narrative agent | Human-readable structure for user approval |
+| `_temp/presentation-plan.md` | Orchestrator | Folder-tree view shown during approval step |
+| `_temp/presentation-draft.json` | Design agent | Final graph JSON for import |
+
+## After import
+
+1. Open `/present/plan` in the app
+2. Click **New presentation**
+3. Choose **Import JSON**
+4. Select `_temp/presentation-draft.json`
+
+If any slides require video backgrounds, Claude lists them in the delivery summary with upload instructions.
+
+## Releasing a new version
+
+When skill files are updated, bump the version in `package.json` and push a tag. The GitHub Actions workflow publishes to GitHub Packages automatically.
+
+```bash
+# Edit package.json version, then:
+git add -A
+git commit -m "Update narrative/frameworks.md: ..."
+git tag v1.1.0
+git push origin main && git push origin v1.1.0
+```
+
+Pushing the tag triggers the publish workflow. Team members get the update with `npx @ztffn/presentation-generator-plugin update`.
+
+## Plugin structure
+
+```
+presentation-generator/
+├── .claude-plugin/
+│   └── plugin.json
+├── agents/
+│   ├── presentation-content.md
+│   ├── presentation-narrative.md
+│   └── presentation-design.md
+└── skills/
+    └── presentation-generator/
+        ├── SKILL.md
+        ├── narrative/
+        │   ├── content-signals.md
+        │   ├── frameworks.md
+        │   ├── slide-content.md
+        │   └── graph-topology.md
+        ├── system/
+        │   ├── node-schema.md
+        │   ├── edge-conventions.md
+        │   ├── layout-templates.md
+        │   └── positioning.md
+        └── examples/
+            ├── pitch-reference.json
+            └── presentation-guide.md
+```

package/agents/presentation-content.md

@@ -0,0 +1,34 @@
+---
+name: presentation-content
+description: Extracts structured content briefs from project documents for presentation generation. Reads source files, identifies presentation-worthy content, and produces a canonical content brief JSON.
+tools:
+  - Read
+  - Glob
+skills:
+  - presentation-generator/narrative/content-signals
+---
+
+# Content Extraction Agent
+
+You are a content extraction specialist. Your job is to read source documents and produce a structured content brief that captures everything needed to build a compelling presentation.
+
+## Your Process
+
+1. Read all document paths provided to you
+2. Apply the content signal guidance from your pre-injected skill to identify what is presentation-worthy
+3. Populate every field of the content brief schema with specific, concrete entries
+4. Write the result to `_temp/presentation-content-brief.json`
+
+## Rules
+
+- Extract strong, specific entries for every field. Weak or vague entries (e.g. "saves money", "good technology") are unacceptable.
+- `keyMessages` must be declarative sentences with subject + verb + specific claim
+- `dataPoints` must contain at least one entry with a concrete number
+- `callToAction` must be a single sentence with an action verb
+- Never include layout, design, slide type, or visual treatment in the brief
+- Never invent data — only extract what the documents contain. If a field cannot be populated from the source material, note it as `"NOT FOUND IN SOURCE — ask user"`
+- When multiple documents conflict, prefer the most recent or most authoritative source
+
+## Output
+
+Write a single JSON file to `_temp/presentation-content-brief.json` conforming to the content brief schema defined in your content-signals skill.

package/agents/presentation-design.md

@@ -0,0 +1,56 @@
+---
+name: presentation-design
+description: Translates approved slide outlines into complete graph JSON with nodes, edges, positions, and visual treatments. Pure translation — never alters content or structure from the outline.
+tools:
+  - Read
+  - Write
+skills:
+  - presentation-generator/system/node-schema
+  - presentation-generator/system/edge-conventions
+  - presentation-generator/system/layout-templates
+  - presentation-generator/system/positioning
+  - presentation-generator/examples/pitch-reference
+---
+
+# Design & JSON Generation Agent
+
+You are a design and JSON generation specialist. Your job is to translate an approved slide outline into a complete, valid presentation graph JSON file.
+
+## Your Process
+
+1. Read the approved outline from `_temp/presentation-outline.md`
+2. For each slide in the outline, make three categories of decision:
+   a. **Slide type and layout**: Based on content signals, select `type`, `layout`, `centered`, and related fields using the layout-templates skill
+   b. **Visual treatment**: Set background media, `lightText`, branding flags, and chart configuration
+   c. **Positioning**: Place each node on the grid defined in the positioning skill
+3. Build all nodes with complete `data`, `style`, and `measured` objects
+4. Wire all edges with bidirectional pairs following the edge-conventions skill
+5. Run the edge validation checklist before finalizing
+6. Write the complete JSON to `_temp/presentation-draft.json`
+
+## Rules
+
+- **Translation only**: Do not alter content, order, or structure from the outline. Your role is visual treatment and JSON compilation.
+- Every node must have `type: "huma"`, `style: { width: 180, height: 70 }`, and `measured: { width: 180, height: 70 }`
+- Every node ID must be a kebab-case slug
+- Every forward edge must have a paired return edge
+- All handle IDs must be from the valid set of 8
+- For background images, use Unsplash URLs with `?w=1920&q=80`
+- For video, use placeholder strings: `"PLACEHOLDER: [description]"`
+- List all slides with video placeholders at the end of output
+
+## Output
+
+Write the JSON to `_temp/presentation-draft.json`:
+
+```json
+{
+  "nodes": [ ... ],
+  "edges": [ ... ]
+}
+```
+
+After writing, output a summary listing:
+- Total node count
+- Total edge count
+- Any slides with video placeholders requiring manual upload

package/agents/presentation-narrative.md

@@ -0,0 +1,62 @@
+---
+name: presentation-narrative
+description: Designs narrative structure and slide outlines for graph-based presentations. Selects story frameworks, designs spine and drill-down topology, and writes detailed slide content outlines.
+tools:
+  - Read
+  - Write
+skills:
+  - presentation-generator/narrative/frameworks
+  - presentation-generator/narrative/slide-content
+  - presentation-generator/narrative/graph-topology
+---
+
+# Narrative Design Agent
+
+You are a narrative design specialist. Your job is to take a structured content brief and design a compelling presentation structure with detailed slide content.
+
+## Your Process
+
+1. Read the content brief from `_temp/presentation-content-brief.json`
+2. Based on `goal` and `audience`, select the appropriate narrative framework from your pre-injected frameworks skill
+3. Design the spine (main horizontal flow) of 4-7 nodes
+4. Design drill-down branches where content warrants optional depth
+5. Write detailed content for each slide following the quality guidance in your slide-content skill
+6. Write the result to `_temp/presentation-outline.md`
+
+## Output Format
+
+Write a markdown file to `_temp/presentation-outline.md` with these sections:
+
+```markdown
+# Presentation Outline
+
+## Framework
+[Which framework was selected and why]
+
+## SPINE
+[Ordered list of main-flow slides with title and key message]
+
+## DRILL-DOWNS
+[Which spine nodes have drill-downs, with titles and content summaries]
+
+## CONTENT PER SLIDE
+
+### [Slide Title] (spine | drill-down under [parent])
+**Key message:** [one sentence]
+**Content:**
+[Detailed bullet points and text for this slide]
+**Speaker notes:**
+[What the presenter should say that isn't on screen]
+**Transition to next:**
+[How this slide connects to the next]
+```
+
+## Rules
+
+- Never mention slide types, layouts, colors, chart types, or JSON format
+- Never make design decisions — those belong to the design agent
+- Headlines must make claims, not label topics
+- One key message per slide
+- Speaker notes add context, not repetition
+- The spine alone must tell a complete story — drill-downs are optional depth
+- If the content brief has weak or missing fields, note them in the outline header so the orchestrator can ask the user

package/bin/index.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+
+const { execSync, spawnSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const REPO_URL =
+  "https://github.com/ztffn/presentation-generator-plugin.git";
+const PLUGIN_NAME = "presentation-generator";
+const INSTALL_DIR = path.join(os.homedir(), ".claude", "plugins", PLUGIN_NAME);
+const CURRENT_VERSION = require("../package.json").version;
+
+const command = process.argv[2] || "help";
+
+function run(cmd, opts = {}) {
+  return execSync(cmd, { stdio: "inherit", ...opts });
+}
+
+function runCapture(cmd) {
+  try {
+    return execSync(cmd, { encoding: "utf8", stderr: "pipe" }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function checkGitAuth() {
+  const result = spawnSync("gh", ["auth", "status"], { encoding: "utf8" });
+  if (result.status !== 0) {
+    console.error("\nGitHub authentication required.");
+    console.error("Run: gh auth login\n");
+    process.exit(1);
+  }
+}
+
+function getInstalledVersion() {
+  const pkgPath = path.join(INSTALL_DIR, "package.json");
+  if (!fs.existsSync(pkgPath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(pkgPath, "utf8")).version;
+  } catch {
+    return null;
+  }
+}
+
+function getLatestRemoteVersion() {
+  const result = runCapture(
+    `git ls-remote --tags ${REPO_URL} | grep -o 'v[0-9]*\\.[0-9]*\\.[0-9]*' | sort -V | tail -1`
+  );
+  return result ? result.replace(/^v/, "") : null;
+}
+
+function printSettingsHelp() {
+  const settingsPath = path.join(process.cwd(), ".claude", "settings.json");
+  const settingsExists = fs.existsSync(settingsPath);
+
+  console.log("\nAdd the plugin to your project:");
+  console.log(
+    `  File: ${path.join(process.cwd(), ".claude", "settings.json")}`
+  );
+
+  if (settingsExists) {
+    let settings;
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    } catch {
+      settings = {};
+    }
+    const plugins = settings.plugins || [];
+    const alreadyAdded = plugins.some((p) => p.path === INSTALL_DIR);
+    if (alreadyAdded) {
+      console.log("  Already configured in settings.json ✓");
+      return;
+    }
+  }
+
+  console.log(
+    `  Add: { "plugins": [{ "path": "${INSTALL_DIR}" }] }\n`
+  );
+
+  // Offer to auto-configure
+  try {
+    const readline = require("readline").createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+    readline.question(
+      "Auto-add to .claude/settings.json? [Y/n] ",
+      (answer) => {
+        readline.close();
+        if (answer.toLowerCase() !== "n") {
+          addToSettings(settingsPath);
+        }
+      }
+    );
+  } catch {
+    // non-interactive context
+  }
+}
+
+function addToSettings(settingsPath) {
+  const dir = path.dirname(settingsPath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    } catch {}
+  }
+
+  settings.plugins = settings.plugins || [];
+  const alreadyAdded = settings.plugins.some((p) => p.path === INSTALL_DIR);
+  if (!alreadyAdded) {
+    settings.plugins.push({ path: INSTALL_DIR });
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log("  settings.json updated ✓");
+  }
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+function install() {
+  checkGitAuth();
+
+  if (fs.existsSync(INSTALL_DIR)) {
+    const installed = getInstalledVersion();
+    const latest = getLatestRemoteVersion();
+
+    if (latest && installed && installed !== latest) {
+      console.log(`\nPlugin already installed (v${installed}).`);
+      console.log(`v${latest} is available — run: npx @huma/presentation-generator-plugin update\n`);
+    } else {
+      console.log(`\nPlugin already installed (v${installed || "unknown"}). Nothing to do.\n`);
+    }
+    printSettingsHelp();
+    return;
+  }
+
+  console.log(`\nInstalling presentation-generator plugin...`);
+  fs.mkdirSync(path.dirname(INSTALL_DIR), { recursive: true });
+  run(`git clone ${REPO_URL} "${INSTALL_DIR}"`);
+  console.log(`\nInstalled to: ${INSTALL_DIR}`);
+  printSettingsHelp();
+}
+
+function update() {
+  checkGitAuth();
+
+  if (!fs.existsSync(INSTALL_DIR)) {
+    console.log("\nPlugin not installed. Run install first:");
+    console.log("  npx @ztffn/presentation-generator-plugin install\n");
+    process.exit(1);
+  }
+
+  const before = getInstalledVersion();
+  console.log(`\nUpdating presentation-generator plugin (current: v${before || "unknown"})...`);
+  run(`git -C "${INSTALL_DIR}" pull`);
+
+  const after = getInstalledVersion();
+  if (before !== after) {
+    console.log(`\nUpdated v${before} → v${after} ✓\n`);
+  } else {
+    console.log(`\nAlready up to date (v${after}) ✓\n`);
+  }
+}
+
+function checkUpdate() {
+  if (!fs.existsSync(INSTALL_DIR)) {
+    console.log("\nPlugin not installed.");
+    return;
+  }
+
+  const installed = getInstalledVersion();
+  const latest = getLatestRemoteVersion();
+
+  if (!latest) {
+    console.log(`\nInstalled: v${installed || "unknown"} (could not reach remote)\n`);
+    return;
+  }
+
+  if (installed === latest) {
+    console.log(`\nUp to date: v${installed} ✓\n`);
+  } else {
+    console.log(`\nUpdate available: v${installed} → v${latest}`);
+    console.log(`Run: npx @ztffn/presentation-generator-plugin update\n`);
+  }
+}
+
+function uninstall() {
+  if (!fs.existsSync(INSTALL_DIR)) {
+    console.log("\nPlugin not installed.\n");
+    return;
+  }
+  fs.rmSync(INSTALL_DIR, { recursive: true, force: true });
+  console.log(`\nRemoved: ${INSTALL_DIR}`);
+  console.log("You may also want to remove the plugin entry from .claude/settings.json\n");
+}
+
+function help() {
+  console.log(`
+presentation-generator-plugin v${CURRENT_VERSION}
+
+Commands:
+  install       Clone plugin to ~/.claude/plugins/ and configure project
+  update        Pull latest changes from GitHub
+  check-update  Report whether an update is available
+  uninstall     Remove plugin from ~/.claude/plugins/
+
+Usage:
+  npx @ztffn/presentation-generator-plugin install
+  npx @ztffn/presentation-generator-plugin update
+  npx @ztffn/presentation-generator-plugin check-update
+
+Requires: gh auth login (GitHub authentication)
+`);
+}
+
+const commands = { install, update, "check-update": checkUpdate, uninstall, help };
+const fn = commands[command];
+
+if (!fn) {
+  console.error(`Unknown command: ${command}`);
+  help();
+  process.exit(1);
+}
+
+fn();

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@ztffn/presentation-generator-plugin",
+  "version": "1.0.0",
+  "description": "Claude Code plugin for generating graph-based presentations",
+  "bin": {
+    "presentation-generator-plugin": "bin/index.js"
+  },
+  "scripts": {
+    "postinstall": "echo 'Run: npx @ztffn/presentation-generator-plugin install'"
+  },
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "presentation",
+    "slides"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ztffn/presentation-generator-plugin.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}