@ztffn/presentation-generator-plugin 1.3.1 → 1.3.3

package/agents/presentation-content.md

@@ -10,23 +10,47 @@ skills:
 
 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
+## Process — follow these steps in order
 
-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`
+### Step 1 — Load your skill files
 
-## Rules
+Read this file before doing anything else:
+- Find and read the file matching `**/presentation-generator/skills/content-signals/SKILL.md`
 
-- Extract strong, specific entries for every field. Weak or vague entries (e.g. "saves money", "good technology") are unacceptable.
+This file defines the content brief schema, signal priorities, validation rules, and strong/weak examples. You must follow it exactly.
+
+### Step 2 — Read all source documents
+
+Read every document path provided in the prompt. Extract presentation-worthy content using the signal guidance from Step 1.
+
+### Step 3 — Populate the content brief
+
+Build a JSON object conforming to the content brief schema from your content-signals skill. Every field must have specific, concrete entries.
+
+Rules:
 - `keyMessages` must be declarative sentences with subject + verb + specific claim
-- `dataPoints` must contain at least one entry with a concrete number
+- `dataPoints` must contain at least one entry with a concrete number in `value`
 - `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
+### Step 4 — Validate the brief
+
+Before writing, verify:
+1. `keyMessages` contains 3-5 declarative claims (not topic labels)
+2. `dataPoints` has at least one entry with a specific number
+3. `callToAction` is a single actionable sentence
+4. No field contains layout, design, or slide-type references
+
+### Step 5 — Write output
+
+Write the JSON to `_temp/presentation-content-brief.json`.
+
+### Step 6 — Report to orchestrator
 
-Write a single JSON file to `_temp/presentation-content-brief.json` conforming to the content brief schema defined in your content-signals skill.
+Return a summary listing:
+- Number of key messages extracted
+- Number of data points extracted
+- Any fields marked as `"NOT FOUND IN SOURCE — ask user"`
+- Any gaps or weak areas the orchestrator should address before proceeding

package/agents/presentation-design.md

@@ -10,17 +10,52 @@ skills:
 
 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 per the graph-json-spec skill
-   b. **Visual treatment**: Set background media, `lightText`, branding flags, and chart configuration
-   c. **Positioning**: Place each node on the 240px/150px grid
-3. Build all nodes with complete `data`, `style`, and `measured` objects
-4. Wire all edges with bidirectional pairs per the edge wiring rules
-5. Run the edge validation checklist before finalizing
-6. Write the complete JSON to `_temp/presentation-draft.json`
+## Process — follow these steps in order
+
+### Step 1 — Load your skill file
+
+Read this file before doing anything else:
+- Find and read the file matching `**/presentation-generator/skills/graph-json-spec/SKILL.md`
+
+This file defines the complete JSON schema — node structure, allowed data fields, banned field names, edge wiring with handle IDs, positioning grid, visual intent mapping, and slide recipes. You must follow it exactly.
+
+### Step 2 — Read the approved outline
+
+Read `_temp/presentation-outline.md`. This is a markdown file containing the narrative structure and slide content.
+
+### Step 3 — Build the presentation JSON
+
+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 per the graph-json-spec skill
+  b. **Visual treatment**: Set background media, `lightText`, branding flags, and chart configuration
+  c. **Positioning**: Place each node on the 240px/150px grid
+
+Build all nodes with complete `data`, `style`, and `measured` objects. Wire all edges with bidirectional pairs per the edge wiring rules.
+
+### Step 4 — Write the JSON
+
+1. Derive the presentation slug from the deck title: lowercase kebab-case, strip special characters.
+2. Create the directory `presentations/{slug}/` if it does not exist.
+3. Write the JSON to `presentations/{slug}/{slug}.json`.
+
+### Step 5 — Run the validator
+
+Run the validator script using Bash — do not skip this step:
+
+```bash
+VALIDATE=$(find -L .claude ~/.claude -path "*/presentation-generator/scripts/validate_draft.py" 2>/dev/null | head -1)
+python3 "$VALIDATE" presentations/{slug}/{slug}.json
+```
+
+If there are any `ERROR` lines, fix every error in the JSON file and run the validator again. Repeat until the script prints `OK  Presentation JSON is valid`.
+
+### Step 6 — Report to orchestrator
+
+Your completion message must include:
+- The exact terminal output of the validator script (a Read of the JSON file does not count as validation)
+- Output path
+- Total node count and edge count
+- Any slides with video placeholders requiring manual upload
 
 ## Field Mapping
 

package/agents/presentation-narrative.md

@@ -12,14 +12,35 @@ skills:
 
 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`
+## Process — follow these steps in order
+
+### Step 1 — Load your skill files
+
+Read these three files before doing anything else:
+- Find and read the file matching `**/presentation-generator/skills/frameworks/SKILL.md`
+- Find and read the file matching `**/presentation-generator/skills/slide-content/SKILL.md`
+- Find and read the file matching `**/presentation-generator/skills/graph-topology/SKILL.md`
+
+These files define framework selection logic, slide content quality rules, visual intent annotations, and topology patterns. You must follow them exactly.
+
+### Step 2 — Read the content brief
+
+Read `_temp/presentation-content-brief.json`. Note any weak or missing fields.
+
+### Step 3 — Select framework, design structure, write slide content
+
+Based on `goal` and `audience`, select the appropriate narrative framework from your frameworks skill. Then:
+1. Design the spine (main horizontal flow) of 4-7 nodes
+2. Design drill-down branches where content warrants optional depth
+3. Write detailed content for each slide following the quality guidance in your slide-content skill
+
+### Step 4 — Write output as MARKDOWN
+
+Write the result to `_temp/presentation-outline.md` — this must be a markdown file, NOT JSON.
+
+### Step 5 — Report to orchestrator
+
+Return a summary: framework selected, spine node count, drill-down node count, and any content brief gaps that need user input.
 
 ## Output Format
 

package/bin/index.js

@@ -127,14 +127,6 @@ function promptChoice(title, choices) {
 async function resolveInstallTarget() {
   const projectClaudeDir = path.join(process.cwd(), ".claude");
 
-  if (!fs.existsSync(projectClaudeDir)) {
-    return {
-      installDir: GLOBAL_INSTALL_DIR,
-      settingsPath: path.join(os.homedir(), ".claude", "settings.json"),
-      scope: "global",
-    };
-  }
-
   const idx = await promptChoice("Installation scope", [
     {
       label: "Global",
@@ -147,6 +139,9 @@ async function resolveInstallTarget() {
   ]);
 
   if (idx === 1) {
+    if (!fs.existsSync(projectClaudeDir)) {
+      fs.mkdirSync(projectClaudeDir, { recursive: true });
+    }
     return {
       installDir: PROJECT_INSTALL_DIR,
       settingsPath: path.join(projectClaudeDir, "settings.json"),

package/package.json

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

package/skills/presentation-generator/SKILL.md

@@ -49,7 +49,11 @@ Task tool:
   subagent_type: "presentation-content"
   description: "Extract content brief"
   prompt: |
-    Read these source documents and extract a structured content brief:
+    Step 1: Load your skill file. Find and read the file matching
+    **/presentation-generator/skills/content-signals/SKILL.md
+    — it defines the content brief schema, signal priorities, and validation rules.
+
+    Step 2: Read these source documents and extract a structured content brief:
 
     Documents:
     - [list each file path from Phase 1]
@@ -57,7 +61,10 @@ Task tool:
     Audience: [audience identified in Phase 1]
     Goal: [goal identified in Phase 1]
 
-    Write the result to _temp/presentation-content-brief.json
+    Step 3: Write the result as JSON to _temp/presentation-content-brief.json
+
+    Step 4: Report back with the number of key messages, data points,
+    and any fields marked "NOT FOUND IN SOURCE".
 ```
 
 The content agent reads all source documents and writes a structured content brief.
@@ -89,13 +96,21 @@ Task tool:
   subagent_type: "presentation-narrative"
   description: "Design narrative outline"
   prompt: |
-    Read the content brief at _temp/presentation-content-brief.json and design
-    the narrative structure for this presentation.
+    Step 1: Load your skill files. Find and read these three files:
+    - **/presentation-generator/skills/frameworks/SKILL.md
+    - **/presentation-generator/skills/slide-content/SKILL.md
+    - **/presentation-generator/skills/graph-topology/SKILL.md
 
+    Step 2: 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]
 
-    Write the result to _temp/presentation-outline.md
+    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.
 ```
 
 The narrative agent selects a story framework, designs the spine and drill-down structure, and writes a detailed slide outline.
@@ -139,14 +154,24 @@ Task tool:
   subagent_type: "presentation-design"
   description: "Generate presentation JSON"
   prompt: |
-    Read the approved outline at _temp/presentation-outline.md and translate it
-    into a complete presentation graph JSON.
+    Step 1: Load your skill file. Find and read the file matching
+    **/presentation-generator/skills/graph-json-spec/SKILL.md
+    — it defines the complete JSON schema, allowed fields, banned fields,
+    edge wiring, handle IDs, and positioning grid.
 
+    Step 2: Read the approved outline at _temp/presentation-outline.md
+
+    Step 3: Translate the outline into a complete presentation graph JSON.
     Presentation slug: {slug}
-    Output path: presentations/{slug}/{slug}.json
 
-    After writing the JSON, run the validator script and fix any errors until
-    it passes. Include the validator terminal output in your completion message.
+    Step 4: Write the JSON to presentations/{slug}/{slug}.json
+
+    Step 5: Run the validator script and fix any errors until it passes:
+    VALIDATE=$(find -L .claude ~/.claude -path "*/presentation-generator/scripts/validate_draft.py" 2>/dev/null | head -1)
+    python3 "$VALIDATE" presentations/{slug}/{slug}.json
+
+    Step 6: Report back with the exact validator terminal output,
+    output path, node count, edge count, and any video placeholders.
 ```
 
 The design agent translates each slide into a fully specified graph node, wires all edges with bidirectional pairs, and validates the result.