@ztffn/presentation-generator-plugin 1.3.6 → 1.3.8

package/.claude-plugin/plugin.json

@@ -1,11 +1,10 @@
 {
   "name": "presentation-generator",
   "description": "Generate complete graph-based presentations from natural language briefs and project documents. Pipeline: content extraction, narrative design, deterministic graph generation, and visual styling.",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "author": {
     "name": "Huma"
   },
   "homepage": "https://github.com/huma/humashowcase",
-  "keywords": ["presentation", "slides", "react-flow", "graph", "pitch deck"],
-  "hooks": "./hooks/hooks.json"
+  "keywords": ["presentation", "slides", "react-flow", "graph", "pitch deck"]
 }

package/agents/presentation-content.md

@@ -1,7 +1,7 @@
 ---
 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
+tools: Read, Glob, Write
 skills:
   - presentation-generator:content-signals
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ztffn/presentation-generator-plugin",
-  "version": "1.3.6",
+  "version": "1.3.8",
   "description": "Claude Code plugin for generating graph-based presentations",
   "bin": {
     "presentation-generator-plugin": "bin/index.js"

package/skills/presentation-generator/SKILL.md

@@ -7,290 +7,180 @@ description: >
   "presentation for", "slide deck about".
 ---
 
-# Presentation Generator
+# Presentation Generator — Orchestrator Instructions
 
-Orchestrates a two-agent + script pipeline to produce a complete, navigable presentation graph JSON from a user brief and optional source documents.
+You are an orchestrator. Execute these 7 phases in order. Do not skip phases. Do not read source documents yourself — delegates do that.
 
-## Pipeline Overview
-
-```
-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] Graph Generation      →  presentations/{slug}/{slug}.json  (script)
-        ↓
-  [5] Visual Styling        →  styled JSON  (agent)
-        ↓
-  [6] Delivery              →  import instructions + media checklist
-```
+---
 
-## Phase 0 — Locate Plugin Root
+## Phase 1 — Setup
 
-Before any other phase, resolve the plugin root directory. Check the local project path first, then the global path:
+Run this bash command to find the plugin:
 
 ```bash
 if [ -f ".claude/plugins/presentation-generator/scripts/outline_to_graph.py" ]; then
-  PLUGIN_ROOT=".claude/plugins/presentation-generator"
+  echo "PLUGIN_ROOT=.claude/plugins/presentation-generator"
 elif [ -f "$HOME/.claude/plugins/presentation-generator/scripts/outline_to_graph.py" ]; then
-  PLUGIN_ROOT="$HOME/.claude/plugins/presentation-generator"
+  echo "PLUGIN_ROOT=$HOME/.claude/plugins/presentation-generator"
 else
-  echo "ERROR: presentation-generator-plugin not found" && exit 1
+  echo "ERROR: plugin not found"
 fi
-echo "Plugin root: $PLUGIN_ROOT"
 ```
 
-Store `PLUGIN_ROOT` for all subsequent phases. All skill files, scripts, and agent references use this path.
-
-## Phase 1 — Context Gathering
+Save the PLUGIN_ROOT value. You need it for every later phase.
 
-Parse the user's request to extract these four fields. Do NOT read or open any files — just note the paths as strings:
+Then extract from the user's message:
+- **TOPIC**: what is being presented
+- **AUDIENCE**: who it is for
+- **GOAL**: pitch / demo / update / internal / exploratory
+- **DOCS**: file paths (just note them as strings, do NOT read them)
+- **SLUG**: lowercase-kebab-case name for the deck
 
-1. **What** is being presented (product, project, topic)
-2. **To whom** (audience type, their background, what they care about)
-3. **For what goal** (`pitch`, `demo`, `update`, `internal`, `exploratory`)
-4. **Source documents** — file paths mentioned in the request (pass these to the content agent in Phase 2, do not read them yourself)
+If AUDIENCE or GOAL is unclear, ask the user. Then proceed.
 
-If no documents are provided, skip Phase 2 and construct a minimal content brief directly from the prompt. Ask the user for any missing critical information:
-- If audience is unclear, ask who the presentation is for
-- If goal is unclear, ask what outcome they want
+---
 
 ## Phase 2 — Content Extraction
-Announce to the user that you are **Executing Phase 2 — Subagent: Content Extraction**
 
-Delegate content extraction to the specialist agent using the Task tool:
+Say: **"Phase 2 — Extracting content from documents"**
 
-```
-Task tool:
-  subagent_type: "presentation-content"
-  description: "Extract content brief"
-  prompt: |
-    Step 1: Load your skill file. Read this file:
-    {PLUGIN_ROOT}/skills/content-signals/SKILL.md
-    — it defines the content brief schema, signal priorities, and validation rules.
+Call the Task tool with exactly these parameters:
 
-    Step 2: Read these source documents and extract a structured content brief:
+- subagent_type: `presentation-content`
+- description: `Extract content brief`
+- prompt: (copy this template, fill in the bracketed values)
 
-    Documents:
-    - [list each file path from Phase 1]
+```
+Read this skill file first: {PLUGIN_ROOT}/skills/content-signals/SKILL.md
 
-    Audience: [audience identified in Phase 1]
-    Goal: [goal identified in Phase 1]
+Then read these documents:
+- {DOC_PATH_1}
+- {DOC_PATH_2}
 
-    Step 3: Write the result as JSON to _temp/presentation-content-brief.json
+Audience: {AUDIENCE}
+Goal: {GOAL}
 
-    Step 4: Report back with the number of key messages, data points,
-    and any fields marked "NOT FOUND IN SOURCE".
+Write a JSON content brief to _temp/presentation-content-brief.json
+Report back what you extracted.
 ```
 
-The content agent reads all source documents and writes a structured content brief.
-
-### Brief Quality Gate
-
-After the content brief is written, read `_temp/presentation-content-brief.json` and verify:
+When the agent finishes, move to Phase 3.
 
-1. **`keyMessages`** contains 3-5 declarative claims (subject + verb + specific claim), not topic labels
-   - BAD: "Our technology"
-   - GOOD: "Calora reduces industrial heat costs by 40% with no infrastructure replacement"
+If no documents were provided, write _temp/presentation-content-brief.json yourself from the user's prompt, then move to Phase 3.
 
-2. **`dataPoints`** contains at least one entry with a specific number in `value`
-   - BAD: `{ "value": "significant" }`
-   - GOOD: `{ "value": "40%", "source": "Field trial, Oslo 2024" }`
+---
 
-3. **`callToAction`** is a single actionable sentence with an action verb
-   - BAD: "Let's continue the conversation"
-   - GOOD: "Agree to a structured 3-month pilot at the Stavanger facility starting Q2"
+## Phase 3 — Narrative Design
 
-If any check fails, ask the user ONE targeted question to fill the gap. Do not pass a weak brief to the narrative agent.
+Say: **"Phase 3 — Designing narrative structure"**
 
-## Phase 3 — Narrative Design
-Announce to the user that you are **Executing Phase 3 — Subagent: Narrative Design**
+Call the Task tool with exactly these parameters:
 
-Delegate narrative design to the specialist agent using the Task tool:
+- subagent_type: `presentation-narrative`
+- description: `Design narrative outline`
+- prompt: (copy this template, fill in the bracketed values)
 
 ```
-Task tool:
-  subagent_type: "presentation-narrative"
-  description: "Design narrative outline"
-  prompt: |
-    Step 1: Load your skill files. Read these three files:
-    - {PLUGIN_ROOT}/skills/frameworks/SKILL.md
-    - {PLUGIN_ROOT}/skills/slide-content/SKILL.md
-    - {PLUGIN_ROOT}/skills/graph-topology/SKILL.md
+Read these skill files first:
+- {PLUGIN_ROOT}/skills/frameworks/SKILL.md
+- {PLUGIN_ROOT}/skills/slide-content/SKILL.md
+- {PLUGIN_ROOT}/skills/graph-topology/SKILL.md
 
-    Step 2: Read the content brief at _temp/presentation-content-brief.json
+Read the content brief at _temp/presentation-content-brief.json
 
-    Step 3: Design the narrative structure for this presentation.
-    Audience: [audience from Phase 1]
-    Goal: [goal from Phase 1]
+Audience: {AUDIENCE}
+Goal: {GOAL}
 
-    Step 4: Write the result as MARKDOWN to _temp/presentation-outline.md
-
-    Step 5: Report back with framework selected, spine node count,
-    drill-down node count, and any content brief gaps.
+Write the outline as MARKDOWN to _temp/presentation-outline.md
+Report back: framework chosen, spine count, drill-down count.
 ```
 
-The narrative agent selects a story framework, designs the spine and drill-down structure, and writes a detailed slide outline.
+When the agent finishes, move to Phase 4.
+
+---
 
 ## Phase 4 — User Approval
-Announce to the user that you are **Executing Phase 4 — Getting User Approval**
 
-Read `_temp/presentation-outline.md` and render it as a folder tree for the user:
+Say: **"Phase 4 — Review the structure"**
+
+Read `_temp/presentation-outline.md` and show the user a tree:
 
 ```
-Cover: [headline]
-Problem: [headline]
-  └─ Detail: [headline]
-  └─ Root Cause: [headline]
-Solution: [headline]
-  └─ How It Works: [headline]
-Value: [headline]
-  └─ Case Study: [headline]
-Call to Action: [headline]
+Cover: [title]
+Spine: [title]
+  └─ Drill-down: [title]
+Spine: [title]
+  └─ Drill-down: [title]
+CTA: [title]
 ```
 
-**Rules:**
-- Top-level items are spine nodes (horizontal navigation)
-- Indented items with `└─` are drill-down children (vertical navigation)
-- Siblings at the same indent level are horizontal peers within their branch
+Ask the user to approve or request changes. Wait for approval before continuing.
 
-Write the tree to `_temp/presentation-plan.md` and present it in the chat.
-
-Wait for the user to respond:
-- **"approved"** or similar → derive the slug (lowercase kebab-case of the deck title, e.g. `calora-investor-pitch`) and proceed to Phase 5
-- **change requests** → update the outline, re-render the tree, wait again
-- **"start over"** → return to Phase 1
+---
 
-This loop continues until the user explicitly approves.
+## Phase 5 — Graph Generation (script)
 
-## Phase 5A — Graph Generation (script)
-Announce to the user that you are **Executing Phase 5A — Generating Graph JSON from Outline**
+Say: **"Phase 5 — Generating graph JSON"**
 
-Run the deterministic outline-to-graph converter directly via Bash:
+Run this bash command:
 
 ```bash
-python3 "$PLUGIN_ROOT/scripts/outline_to_graph.py" _temp/presentation-outline.md -o presentations/{slug}/{slug}.json
+python3 "{PLUGIN_ROOT}/scripts/outline_to_graph.py" _temp/presentation-outline.md -o "presentations/{SLUG}/{SLUG}.json"
 ```
 
-The script:
-- Parses the outline markdown
-- Generates all nodes with correct wrappers, positions, and data fields
-- Wires all edges with bidirectional pairs
-- Runs the validator internally
-- Exits 0 if valid, 1 with errors
+If exit code is 0, move to Phase 6. If non-zero, show the errors.
 
-If exit non-zero, review the errors and fix the outline. If zero, proceed to Phase 5B.
+---
 
-## Phase 5B — Visual Styling (agent)
-Announce to the user that you are **Executing Phase 5B — Subagent: Visual Styling**
+## Phase 6 — Visual Styling
 
-Delegate visual styling to the specialist agent using the Task tool:
+Say: **"Phase 6 — Applying visual styling"**
 
-```
-Task tool:
-  subagent_type: "presentation-style"
-  description: "Apply visual treatments"
-  prompt: |
-    Step 1: Load your skill files. Read these two files:
-    - {PLUGIN_ROOT}/skills/slide-recipes/SKILL.md
-    - {PLUGIN_ROOT}/skills/graph-json-spec/SKILL.md
+Call the Task tool with exactly these parameters:
 
-    Step 2: Read the structurally valid presentation JSON at
-    presentations/{slug}/{slug}.json
+- subagent_type: `presentation-style`
+- description: `Apply visual treatments`
+- prompt: (copy this template, fill in the bracketed values)
 
-    Step 3: Read the outline at _temp/presentation-outline.md for context
-    on each slide's purpose and visual intent.
+```
+Read these skill files first:
+- {PLUGIN_ROOT}/skills/slide-recipes/SKILL.md
+- {PLUGIN_ROOT}/skills/graph-json-spec/SKILL.md
 
-    Step 4: Apply visual treatments to each slide based on the slide-recipes
-    Visual Intent Mapping. Edit only data fields using the Edit tool.
-    Never modify node wrappers, edges, or positions.
+Read the presentation JSON at presentations/{SLUG}/{SLUG}.json
+Read the outline at _temp/presentation-outline.md for context.
 
-    Step 5: Run the validator script and fix any errors:
-    python3 "{PLUGIN_ROOT}/scripts/validate_draft.py" presentations/{slug}/{slug}.json
+Apply visual treatments to each slide. Edit only data fields using the Edit tool.
+Never modify node wrappers (id, type, position, style, measured), edges, or positions.
 
-    Step 6: Report back with the exact validator terminal output,
-    number of slides styled, and any video/image placeholders.
+After all edits, run the validator:
+python3 "{PLUGIN_ROOT}/scripts/validate_draft.py" "presentations/{SLUG}/{SLUG}.json"
+
+Fix errors until it prints "OK". Include the validator output in your report.
 ```
 
-The styling agent reads the valid JSON and applies visual treatments (two-column layouts, centered slides, background images, charts) by editing only `data` fields. It cannot break structure.
+When the agent finishes, move to Phase 7.
 
-## Phase 6 — Delivery
-Announce to the user that you are **Executing Phase 6 — Packaging Presentation**
+---
 
-After `presentations/{slug}/{slug}.json` is written:
+## Phase 7 — Delivery
 
-1. Copy the three intermediate files into the presentation folder so everything is self-contained:
-   - `_temp/presentation-content-brief.json` → `presentations/{slug}/content-brief.json`
-   - `_temp/presentation-outline.md` → `presentations/{slug}/outline.md`
-   - `_temp/presentation-plan.md` → `presentations/{slug}/plan.md`
+Say: **"Phase 7 — Done"**
 
-2. Confirm the output path and provide import instructions:
+Copy intermediate files:
 
-```
-Import your presentation:
-1. Open the graph editor at https://humagreenfield.netlify.app/present/plan
-2. Click "New presentation"
-3. Choose "Import JSON"
-4. Select presentations/{slug}/{slug}.json
-5. Click "Create presentation"
-6. Make final adjustments and manual uploads.
+```bash
+cp _temp/presentation-content-brief.json "presentations/{SLUG}/content-brief.json"
+cp _temp/presentation-outline.md "presentations/{SLUG}/outline.md"
 ```
 
-3. If any slides have video placeholders, list them:
+Then tell the user:
 
 ```
-Slides requiring manual video upload:
-- "[Slide Title]" — [description of needed video]
+Your presentation is at: presentations/{SLUG}/{SLUG}.json
 
-Upload path: POST /api/slide-images/upload
-Accepted: image/*, video/mp4, video/webm, video/quicktime (max 50MB)
-Replace the PLACEHOLDER string with the returned URL after upload.
+To import:
+1. Open https://humagreenfield.netlify.app/present/plan
+2. New presentation → Import JSON
+3. Select the file above
 ```
-
-## Sub-Agent Reference
-
-| Agent | Skills Loaded | Purpose |
-|---|---|---|
-| `presentation-content` | `content-signals` | Extract structured brief from documents |
-| `presentation-narrative` | `frameworks`, `slide-content`, `graph-topology` | Design story structure and slide content |
-| `presentation-style` | `graph-json-spec`, `slide-recipes` | Apply visual treatments to valid graph JSON |
-
-Note: Graph structure (nodes, edges, positions) is generated deterministically by `scripts/outline_to_graph.py` in Phase 5A. The `presentation-style` agent in Phase 5B only modifies visual `data` fields.
-
-## Working Without Documents
-
-When the user provides only a verbal brief (no document paths):
-
-1. Skip Phase 2 entirely
-2. Construct the content brief yourself from the user's prompt:
-   - Ask clarifying questions for missing fields
-   - Populate what you can from the conversation
-   - Write the brief to `_temp/presentation-content-brief.json`
-3. Proceed to Phase 3 as normal
-
-## Large Document Sets
-
-If the user provides many documents that may exceed a single agent's context:
-
-1. Split the document list into groups of 3-5 files
-2. Invoke `presentation-content` multiple times, each with a subset
-3. Merge the partial briefs into a single content brief
-4. Run the quality gate on the merged brief
-
-## File Manifest
-
-All intermediate and output files:
-
-| File | Created By | Read By |
-|---|---|---|
-| `_temp/presentation-content-brief.json` | Content agent or orchestrator | Narrative agent |
-| `_temp/presentation-outline.md` | Narrative agent | Script + styling agent, orchestrator |
-| `_temp/presentation-plan.md` | Orchestrator | User (approval) |
-| `presentations/{slug}/{slug}.json` | Script (structure) + styling agent (visuals) | User (import) |
-| `presentations/{slug}/content-brief.json` | Orchestrator (Phase 6) | Reference |
-| `presentations/{slug}/outline.md` | Orchestrator (Phase 6) | Reference |
-| `presentations/{slug}/plan.md` | Orchestrator (Phase 6) | Reference |