@amg555/frameforge-mcp 0.0.0-stage → 2.3.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/.bob/artifacts/enterprise-ai-video-agent-platform-agnostic-implementation-guide.html +464 -0
  2. package/.claude-plugin/marketplace.json +45 -0
  3. package/.gitattributes +19 -0
  4. package/.mcp.json +45 -0
  5. package/CHANGELOG.md +447 -0
  6. package/CLAUDE.md +320 -0
  7. package/CONTRIBUTING.md +112 -0
  8. package/LICENSE +21 -0
  9. package/Procfile +1 -0
  10. package/README.md +377 -2
  11. package/SECURITY.md +71 -0
  12. package/START_HERE.md +200 -0
  13. package/assets/metadata/assets.json +5 -0
  14. package/assets/metadata/embeddings.json +5 -0
  15. package/install.sh +64 -0
  16. package/package.json +58 -4
  17. package/src/animation/animation-system.js +229 -0
  18. package/src/asset-library/README.md +188 -0
  19. package/src/asset-library/asset-library.js +639 -0
  20. package/src/audio-mixer/mixer.js +187 -0
  21. package/src/cli/doctor.js +173 -0
  22. package/src/cli/make.js +655 -0
  23. package/src/cli/setup-keys.js +392 -0
  24. package/src/config/load-config.js +72 -0
  25. package/src/fact-checker/checker.js +384 -0
  26. package/src/fact-checker/review-gate.js +306 -0
  27. package/src/fact-checker/validation-set.js +1078 -0
  28. package/src/mcp-server/server.js +1299 -0
  29. package/src/mcp-server/stdio.js +87 -0
  30. package/src/pipeline/artifact-manifest.js +323 -0
  31. package/src/pipeline/artifact-retention.js +189 -0
  32. package/src/pipeline/external-adapter.js +366 -0
  33. package/src/pipeline/providers.js +853 -0
  34. package/src/pipeline/retry-policy.js +134 -0
  35. package/src/pipeline/state-machine.js +297 -0
  36. package/src/pipeline/telemetry.js +162 -0
  37. package/src/quality-gate/gate.js +229 -0
  38. package/src/schema/scene.schema.json +101 -0
  39. package/src/shorts-extractor/extractor.js +343 -0
  40. package/src/utils/log-redaction.js +274 -0
  41. package/src/video-renderer/renderer.js +364 -0
  42. package/src/worker/server-render-free.js +420 -0
  43. package/src/worker/server.js +328 -0
  44. package/src/workflows/assets.js +131 -0
  45. package/src/workflows/ingest.js +299 -0
  46. package/src/workflows/packaging.js +156 -0
  47. package/src/workflows/publishing.js +206 -0
  48. package/src/workflows/render.js +102 -0
  49. package/src/workflows/research.js +151 -0
  50. package/src/workflows/script.js +210 -0
  51. package/src/workflows/shorts.js +113 -0
package/.bob/artifacts/enterprise-ai-video-agent-platform-agnostic-implementation-guide.html ADDED
@@ -0,0 +1,464 @@
1
+
2
+ <html lang="en">
3
+ <head>
4
+ <meta charset="UTF-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
6
+ <title>Enterprise AI Video Agent — Platform-Agnostic Implementation Guide</title>
7
+ <style>
8
+ *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
9
+ body { font-family: -apple-system, "Segoe UI", system-ui, sans-serif; font-size: 14px; line-height: 1.6; color: #1f2328; background: #ffffff; }
10
+ .wrapper { max-width: 760px; margin: 0 auto; padding: 32px 24px; }
11
+ h1 { font-size: 22px; font-weight: 700; color: #1f2328; margin-bottom: 6px; }
12
+ .subtitle { color: #57606a; font-size: 13px; margin-bottom: 28px; }
13
+ h2 { font-size: 16px; font-weight: 700; color: #1f2328; margin: 32px 0 10px; border-bottom: 1px solid #e5e7eb; padding-bottom: 6px; }
14
+ h3 { font-size: 14px; font-weight: 700; color: #1f2328; margin: 20px 0 6px; }
15
+ h4 { font-size: 13px; font-weight: 600; color: #57606a; margin: 14px 0 4px; text-transform: uppercase; letter-spacing: 0.04em; }
16
+ p { margin-bottom: 10px; }
17
+ ul, ol { margin: 8px 0 10px 20px; }
18
+ li { margin-bottom: 4px; }
19
+ code { font-family: "SFMono-Regular", "Consolas", "Menlo", monospace; font-size: 12px; background: #f7f8fa; border: 1px solid #e5e7eb; border-radius: 3px; padding: 1px 5px; color: #1f2328; }
20
+ pre { background: #f7f8fa; border: 1px solid #e5e7eb; border-radius: 6px; padding: 14px 16px; overflow-x: auto; margin: 12px 0; }
21
+ pre code { background: none; border: none; padding: 0; font-size: 12px; line-height: 1.5; }
22
+ .badge { display: inline-block; font-size: 11px; font-weight: 600; padding: 2px 8px; border-radius: 12px; margin-right: 4px; }
23
+ .badge-green { background: #dcfce7; color: #166534; }
24
+ .badge-blue { background: #dbeafe; color: #1e40af; }
25
+ .badge-orange { background: #fff7ed; color: #9a3412; }
26
+ .badge-purple { background: #ede9fe; color: #5b21b6; }
27
+ .badge-red { background: #fee2e2; color: #991b1b; }
28
+ .badge-gray { background: #f3f4f6; color: #374151; }
29
+ table { width: 100%; border-collapse: collapse; margin: 12px 0; font-size: 13px; }
30
+ th { background: #f7f8fa; font-weight: 600; text-align: left; padding: 8px 10px; border: 1px solid #e5e7eb; }
31
+ td { padding: 7px 10px; border: 1px solid #e5e7eb; vertical-align: top; }
32
+ tr:nth-child(even) td { background: #fafafa; }
33
+ .callout { background: #f7f8fa; border-left: 3px solid #3b82d4; padding: 12px 16px; margin: 14px 0; border-radius: 0 6px 6px 0; }
34
+ .callout-warn { border-left-color: #d97706; background: #fffbeb; }
35
+ .callout-critical { border-left-color: #dc2626; background: #fef2f2; }
36
+ .callout-success { border-left-color: #16a34a; background: #f0fdf4; }
37
+ .section-num { display: inline-block; background: #3b82d4; color: #fff; font-size: 11px; font-weight: 700; width: 22px; height: 22px; border-radius: 50%; text-align: center; line-height: 22px; margin-right: 8px; }
38
+ .arch-box { background: #f7f8fa; border: 1px solid #e5e7eb; border-radius: 8px; padding: 16px; margin: 14px 0; font-family: "SFMono-Regular", "Consolas", "Menlo", monospace; font-size: 12px; line-height: 1.7; color: #1f2328; white-space: pre; overflow-x: auto; }
39
+ .platform-card { border: 1px solid #e5e7eb; border-radius: 8px; padding: 14px 16px; margin: 10px 0; }
40
+ .platform-card h4 { text-transform: none; font-size: 14px; color: #1f2328; letter-spacing: 0; margin-top: 0; }
41
+ .row2 { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin: 12px 0; }
42
+ .col { background: #f7f8fa; border: 1px solid #e5e7eb; border-radius: 6px; padding: 12px 14px; }
43
+ .col h4 { text-transform: none; font-size: 13px; margin-top: 0; color: #1f2328; }
44
+ .priority-high { color: #dc2626; font-weight: 600; }
45
+ .priority-med { color: #d97706; font-weight: 600; }
46
+ .priority-low { color: #16a34a; font-weight: 600; }
47
+ .pipeline-step { display: flex; align-items: flex-start; margin-bottom: 10px; gap: 12px; }
48
+ .step-num { flex-shrink: 0; background: #1f2328; color: #fff; font-size: 11px; font-weight: 700; width: 22px; height: 22px; border-radius: 50%; text-align: center; line-height: 22px; }
49
+ .step-body { flex: 1; }
50
+ .step-title { font-weight: 600; font-size: 13px; }
51
+ .step-detail { font-size: 12px; color: #57606a; margin-top: 2px; }
52
+ footer { margin-top: 48px; padding-top: 16px; border-top: 1px solid #e5e7eb; text-align: center; font-size: 12px; color: #57606a; }
53
+ </style>
54
+ </head>
55
+ <body>
56
+ <div class="wrapper">
57
+
58
+ <h1>Enterprise AI Video Agent</h1>
59
+ <p class="subtitle">Production-ready implementation guide for IBM Bob, Kiro IDE, Cursor, Windsurf, and any agentic platform — based on deep analysis of programmatic video pipelines and the existing workspace implementation.</p>
60
+
61
+ <div class="callout">
62
+ <strong>What this covers:</strong> The PDF workflow (Farhan's Claude-overnight batch) + the n8n workflow.json (Groq + edge-tts + Pollinations + FFmpeg) are both single-agent, single-IDE pipelines locked to Claude Code + desktop. This guide maps every component to production-grade, IDE-agnostic, enterprise-deployable equivalents that work in IBM Bob, Kiro, Cursor, or any MCP-capable agentic IDE.
63
+ </div>
64
+
65
+ <h2><span class="section-num">1</span>What the Current System Actually Does</h2>
66
+
67
+ <p>The existing stack is a <strong>fully autonomous overnight video factory</strong>:</p>
68
+
69
+ <div class="arch-box">TRIGGER (cron 1AM)
70
+ → Pre-cleanup + music download
71
+ → Topic selection (hardcoded pool, random seed)
72
+ → Research prompt → Groq API (openai/gpt-oss-120b)
73
+ → Validate research JSON (5+ claims required)
74
+ → Script prompt → Groq API (55-scene, 1750-2550 words)
75
+ → Runtime check → expansion loop if too short
76
+ → Split scenes → SplitInBatches loop
77
+ → Per-scene: Generate doodle (Pollinations) + Voice (edge-tts) + Render (FFmpeg)
78
+ → Assemble master video (FFmpeg concat)
79
+ → Thumbnail + Shorts (vertical crop)
80
+ → QC check → Telegram delivery + YouTube upload
81
+ → Post-cleanup</div>
82
+
83
+ <p><strong>Current tech stack:</strong> n8n orchestration, Groq for LLM, Pollinations for image gen, edge-tts for TTS, FFmpeg for video, Telegram + YouTube for delivery.</p>
84
+
85
+ <h2><span class="section-num">2</span>The Core Problem: Platform Lock-In</h2>
86
+
87
+ <div class="callout callout-warn">
88
+ The PDF workflow is 100% locked to <strong>Claude desktop app + "Cowork mode"</strong>. The n8n workflow is locked to a specific Linux host with edge-tts + FFmpeg binaries. Neither is portable across agentic IDEs, team members, or cloud deployments.
89
+ </div>
90
+
91
+ <table>
92
+ <tr><th>Lock-in dimension</th><th>Current state</th><th>Enterprise target</th></tr>
93
+ <tr><td>IDE / agent runtime</td><td>Claude Code desktop only</td><td>Any MCP-compatible IDE (Bob, Kiro, Cursor)</td></tr>
94
+ <tr><td>LLM</td><td>Claude Opus / Groq only</td><td>Provider-agnostic via OpenAI-compatible API</td></tr>
95
+ <tr><td>TTS</td><td>edge-tts (local binary)</td><td>Pluggable: ElevenLabs, Azure, Kokoro, OpenAI TTS</td></tr>
96
+ <tr><td>Image gen</td><td>Pollinations (free, no SLA)</td><td>fal.ai, Replicate, DALL-E, Stability AI</td></tr>
97
+ <tr><td>Orchestration</td><td>n8n (self-hosted Pi)</td><td>IBM watsonx Orchestrate, Temporal, Prefect</td></tr>
98
+ <tr><td>Storage</td><td>Local filesystem</td><td>S3/GCS/Azure Blob + PostgreSQL state</td></tr>
99
+ <tr><td>Delivery</td><td>Telegram + YouTube</td><td>Multi-channel: Telegram, YouTube, LinkedIn, TikTok</td></tr>
100
+ </table>
101
+
102
+ <h2><span class="section-num">3</span>Enterprise Architecture: The Right Shape</h2>
103
+
104
+ <div class="arch-box"> ┌─────────────────────────────────────┐
105
+ │ AGENT LAYER │
106
+ │ │
107
+ IBM Bob │ Kiro IDE │ Cursor │ Windsurf │
108
+ (MCP tools) │ (MCP tools)│ (agents)│ (flows) │
109
+ └──────────────────┬──────────────────┘
110
+ │ MCP protocol
111
+ ▼
112
+ ┌─────────────────────────────────────┐
113
+ │ ORCHESTRATION LAYER │
114
+ │ │
115
+ │ IBM watsonx Orchestrate / │
116
+ │ Temporal.io / n8n (upgraded) │
117
+ └──────────────────┬──────────────────┘
118
+ │ job contracts
119
+ ┌─────────────────┴─────────────────┐
120
+ │ │
121
+ ┌──────▼──────┐ ┌───────▼──────┐
122
+ │ AI SERVICES │ │ MEDIA RENDER │
123
+ │ │ │ │
124
+ │ LLM Gateway │ │ FFmpeg │
125
+ │ (OpenAI API │ │ worker(s) │
126
+ │ compatible)│ │ + GPU opt. │
127
+ └──────┬───────┘ └───────┬──────┘
128
+ │ │
129
+ ▼ ▼
130
+ ┌─────────────────────────────────────────────┐
131
+ │ DATA LAYER │
132
+ │ │
133
+ │ PostgreSQL (state) │ S3 (artifacts) │
134
+ │ Redis (job queue) │ CDN (delivery) │
135
+ └─────────────────────────────────────────────┘</div>
136
+
137
+ <h2><span class="section-num">4</span>Platform-by-Platform Implementation</h2>
138
+
139
+ <div class="platform-card">
140
+ <h4>IBM Bob (Primary Target)</h4>
141
+ <span class="badge badge-green">Recommended</span> <span class="badge badge-blue">MCP-native</span>
142
+ <p style="margin-top:8px">IBM Bob runs on the MCP protocol natively. Every stage of the video pipeline maps directly to an MCP tool. The agent loop in Bob can call <code>research_topic</code>, <code>write_script</code>, <code>generate_scene_image</code>, <code>render_tts</code>, <code>assemble_video</code>, and <code>publish_video</code> as discrete tool calls with observable inputs/outputs, full retry logic, and structured state.</p>
143
+ <p><strong>Key implementation path:</strong> Build a custom MCP server (Node.js/TypeScript, use the <code>build-mcp-server</code> skill) that exposes each pipeline stage as a registered tool. Bob orchestrates the tool calls. The MCP server handles all external API calls, file I/O, and FFmpeg execution. State persists to PostgreSQL via the MCP server.</p>
144
+ <ul>
145
+ <li>Use Bob's <code>configure-hooks</code> skill to add a <code>session.stop</code> hook that saves pipeline state</li>
146
+ <li>Use Bob's <code>gstack-ship</code> / <code>gstack-qa</code> for CI/CD of the MCP server itself</li>
147
+ <li>IBM watsonx models (granite-3.3, granite-vision) replace Groq where data residency matters</li>
148
+ </ul>
149
+ </div>
150
+
151
+ <div class="platform-card">
152
+ <h4>Kiro IDE</h4>
153
+ <span class="badge badge-blue">MCP-native</span> <span class="badge badge-purple">Spec-driven</span>
154
+ <p style="margin-top:8px">Kiro has a native spec-driven development loop (<code>.kiro/specs/</code>) — already present in this workspace. The video pipeline maps perfectly to Kiro's requirements + design + tasks structure. Each pipeline stage becomes a Kiro "task" that the agent executes against the spec. Kiro's agent can call the same MCP server tools as Bob.</p>
155
+ <p><strong>Key difference from Bob:</strong> Kiro's spec system provides deterministic task sequencing. Use <code>.kiro/specs/video-pipeline/tasks.md</code> to define each stage as a checkable task. The agent executes them in order, writing results back to the spec state.</p>
156
+ </div>
157
+
158
+ <div class="platform-card">
159
+ <h4>Cursor / Windsurf</h4>
160
+ <span class="badge badge-gray">MCP-compatible</span>
161
+ <p style="margin-top:8px">Both IDEs support MCP server connections. The same MCP server built for Bob works here. The agent loop is less structured than Bob/Kiro, so add more explicit state checkpoints in the MCP tool responses. Use Cursor's <code>.cursorrules</code> or Windsurf's cascade system to inject the pipeline context.</p>
162
+ </div>
163
+
164
+ <h2><span class="section-num">5</span>The MCP Server: Core Design</h2>
165
+
166
+ <p>One TypeScript MCP server exposes the full pipeline as registered tools. Every IDE calls the same server.</p>
167
+
168
+ <pre><code>// server.ts — video-agent MCP server (OpenAI-compatible gateway pattern)
169
+
170
+ import { registerTool, registerResource } from '@modelcontextprotocol/sdk';
171
+
172
+ // Tool 1: Research
173
+ registerTool('research_topic', {
174
+ description: 'Research a topic with fact-checking. Returns verified claims.',
175
+ inputSchema: {
176
+ topic: { type: 'string' },
177
+ claimCount: { type: 'number', default: 8 },
178
+ model: { type: 'string', default: 'gpt-4o-mini' } // provider-agnostic
179
+ },
180
+ handler: async ({ topic, claimCount, model }) =&gt; {
181
+ const llm = getLLMClient(model); // routes to OpenAI / Groq / watsonx / Ollama
182
+ const claims = await llm.research(topic, claimCount);
183
+ await db.saveResearch(claims);
184
+ return { claims, productionId: claims.id };
185
+ }
186
+ });
187
+
188
+ // Tool 2: Script
189
+ registerTool('write_script', {
190
+ description: 'Write a scene-by-scene video script from research claims.',
191
+ inputSchema: { productionId: { type: 'string' }, style: { type: 'string' } },
192
+ handler: async ({ productionId, style }) =&gt; { ... }
193
+ });
194
+
195
+ // Tool 3: Generate scene image
196
+ registerTool('generate_scene_image', {
197
+ description: 'Generate a doodle/illustration for one scene.',
198
+ inputSchema: { sceneId: { type: 'string' }, visualAction: { type: 'string' } },
199
+ handler: async ({ sceneId, visualAction }) =&gt; {
200
+ const imageProvider = getImageProvider(); // fal.ai / Replicate / DALL-E
201
+ const url = await imageProvider.generate(visualAction);
202
+ return { sceneId, imageUrl: url };
203
+ }
204
+ });
205
+
206
+ // Tool 4: TTS
207
+ registerTool('render_tts', {
208
+ description: 'Convert narration text to audio.',
209
+ inputSchema: { sceneId: { type: 'string' }, text: { type: 'string' }, voice: { type: 'string' } },
210
+ handler: async ({ sceneId, text, voice }) =&gt; {
211
+ const ttsProvider = getTTSProvider(voice); // ElevenLabs / Azure / Kokoro / edge-tts
212
+ const audioPath = await ttsProvider.synthesize(text);
213
+ return { sceneId, audioPath };
214
+ }
215
+ });
216
+
217
+ // Tool 5: Render video
218
+ registerTool('assemble_video', {
219
+ description: 'Assemble all scenes into final MP4.',
220
+ inputSchema: { productionId: { type: 'string' } },
221
+ handler: async ({ productionId }) =&gt; {
222
+ const job = await renderQueue.enqueue(productionId);
223
+ return { jobId: job.id, estimatedMs: job.estimatedMs };
224
+ }
225
+ });
226
+
227
+ // Tool 6: Publish
228
+ registerTool('publish_video', {
229
+ description: 'Deliver finished video to configured channels.',
230
+ inputSchema: { productionId: { type: 'string' }, channels: { type: 'array' } },
231
+ handler: async ({ productionId, channels }) =&gt; {
232
+ const results = await publisherRouter.publish(productionId, channels);
233
+ return { results };
234
+ }
235
+ });</code></pre>
236
+
237
+ <h2><span class="section-num">6</span>Provider Abstraction Layer</h2>
238
+
239
+ <p>Every external service is behind a factory function. Swap providers without touching pipeline logic.</p>
240
+
241
+ <table>
242
+ <tr><th>Service</th><th>Current (locked)</th><th>Tier 1 (free/cheap)</th><th>Tier 2 (production)</th><th>IBM stack</th></tr>
243
+ <tr><td>LLM research</td><td>Groq openai/gpt-oss-120b</td><td>Groq llama-3.3-70b</td><td>OpenAI GPT-4o</td><td>watsonx granite-3.3</td></tr>
244
+ <tr><td>LLM script</td><td>Groq openai/gpt-oss-120b</td><td>Groq llama-3.1-70b</td><td>Claude claude-opus-4-5</td><td>watsonx granite-3.3</td></tr>
245
+ <tr><td>Image gen</td><td>Pollinations (free)</td><td>Replicate SDXL</td><td>fal.ai Flux Pro</td><td>watsonx.ai Image Gen</td></tr>
246
+ <tr><td>TTS</td><td>edge-tts (local)</td><td>Kokoro (local)</td><td>ElevenLabs / Azure TTS</td><td>IBM TTS (Watson)</td></tr>
247
+ <tr><td>Video render</td><td>FFmpeg (local)</td><td>FFmpeg (containerised)</td><td>AWS MediaConvert</td><td>IBM Cloud Media</td></tr>
248
+ <tr><td>Orchestration</td><td>n8n (Pi)</td><td>n8n (cloud) / Temporal</td><td>IBM watsonx Orchestrate</td><td>watsonx Orchestrate</td></tr>
249
+ <tr><td>State DB</td><td>n8n internal</td><td>SQLite / Turso</td><td>PostgreSQL (managed)</td><td>IBM Db2 / IBM Cloud DB</td></tr>
250
+ <tr><td>Artifact storage</td><td>Local filesystem</td><td>Cloudflare R2</td><td>AWS S3 / GCS</td><td>IBM Cloud Object Storage</td></tr>
251
+ </table>
252
+
253
+ <h2><span class="section-num">7</span>Enterprise Pipeline Stages (Production-Grade)</h2>
254
+
255
+ <div class="pipeline-step">
256
+ <div class="step-num">A</div>
257
+ <div class="step-body">
258
+ <div class="step-title">Research + Fact-Check</div>
259
+ <div class="step-detail">Multi-source verification with deterministic gates. Source independence score ≥2 required for NUMERICAL/CONTROVERSIAL claims. Claim cache (PostgreSQL) prevents re-validating the same normalized claim. Risk classification: TRIVIAL (1 source) / NUMERICAL (2+) / CONTROVERSIAL (3+). Output: <code>fact_check_report.json</code> with evidence_strength and source_independence per claim.</div>
260
+ </div>
261
+ </div>
262
+ <div class="pipeline-step">
263
+ <div class="step-num">B</div>
264
+ <div class="step-body">
265
+ <div class="step-title">Script Generation</div>
266
+ <div class="step-detail">Structured scene JSON: narration (15-35 words), caption (3-6 words UPPERCASE), visual_action with scene tag [CAMP/MODERN/COMPARE/REACTION/TIMELINE], camera movement. Runtime check: 1750-2550 words, 45-75 scenes. Honesty pass: rewrite claims stronger than source supports. Expansion loop if too short (max 2 attempts).</div>
267
+ </div>
268
+ </div>
269
+ <div class="pipeline-step">
270
+ <div class="step-num">C</div>
271
+ <div class="step-body">
272
+ <div class="step-title">Asset Library + Image Generation</div>
273
+ <div class="step-detail">Composable asset system: identity + pose + emotion layers. Metadata-first lookup (&lt;10ms), semantic fallback (embedding similarity &gt;0.85), then generation. Style consistency validated before storage. Asset registry in PostgreSQL. Pollinations/fal.ai/Replicate as pluggable backends. Scene-defined focal_point for vertical crop later.</div>
274
+ </div>
275
+ </div>
276
+ <div class="pipeline-step">
277
+ <div class="step-num">D</div>
278
+ <div class="step-body">
279
+ <div class="step-title">TTS + Audio Mixing</div>
280
+ <div class="step-detail">Per-scene TTS with retry (3 attempts). Audio processing: highpass 80Hz, bass boost 3dB@110Hz, dynaudnorm. Professional mixing: sidechaincompress ducking (ratio=20, attack=0.2ms, release=1s), final loudnorm I=-14 TP=-1. SNR diagnostic (informational). Pause detection for caption sync timestamps.</div>
281
+ </div>
282
+ </div>
283
+ <div class="pipeline-step">
284
+ <div class="step-num">E</div>
285
+ <div class="step-body">
286
+ <div class="step-title">Video Rendering</div>
287
+ <div class="step-detail">Scene-level: zoompan animation, caption drawtext with safe-zone enforcement (top 180px, bottom 400px, right 130px). Master assembly: FFmpeg concat demuxer with crossfade transitions. CRF-based encoding (CRF 23, libx264, yuv420p, 1080p30). Hash-based idempotency: skip re-render if input_hash matches cached output_hash. Stage timeout: 30 min.</div>
288
+ </div>
289
+ </div>
290
+ <div class="pipeline-step">
291
+ <div class="step-num">F</div>
292
+ <div class="step-body">
293
+ <div class="step-title">Shorts Extraction</div>
294
+ <div class="step-detail">Saliency-aware 9:16 crop using scene-defined focal_point. Content scoring: hook (0-1) + curiosity + payoff + standalone_context + information_density - repetition_penalty. Segment detection: silencedetect + scene change analysis. Final loudnorm -14 LUFS. Duration 30-90s per short.</div>
295
+ </div>
296
+ </div>
297
+ <div class="pipeline-step">
298
+ <div class="step-num">G</div>
299
+ <div class="step-body">
300
+ <div class="step-title">Quality Gate (Hard)</div>
301
+ <div class="step-detail">HARD GATES: stream validity, 1920x1080 resolution, h264 codec, yuv420p, 30fps, LUFS -14±1 LU, true peak ≤-1 dBTP, no black frames &gt;0.5s, no frozen frames &gt;0.5s, no ffprobe errors. SANITY CHECKS: bitrate ≥3 Mbps (warn, no block), duration within 5%. DIAGNOSTICS: SNR, file size for cost tracking.</div>
302
+ </div>
303
+ </div>
304
+ <div class="pipeline-step">
305
+ <div class="step-num">H</div>
306
+ <div class="step-body">
307
+ <div class="step-title">Package + Publish</div>
308
+ <div class="step-detail">Production package: master.mp4 + short_*.mp4 + thumbnail + metadata.json + SHA256 checksums. Multi-channel publish router: Telegram (Bot API), YouTube (Data API v3), LinkedIn (Video API), TikTok (Content API). Platform-specific format validation before upload. Dead-letter queue for failed deliveries.</div>
309
+ </div>
310
+ </div>
311
+
312
+ <h2><span class="section-num">8</span>Reliability Infrastructure</h2>
313
+
314
+ <div class="row2">
315
+ <div class="col">
316
+ <h4>Retry Policy</h4>
317
+ <ul>
318
+ <li><strong>RETRYABLE:</strong> HTTP 429, ECONNREFUSED, ETIMEDOUT, worker unavailable → exponential backoff (10s, 20s, 40s), max 3 attempts</li>
319
+ <li><strong>NON_RETRYABLE:</strong> JSON parse fail, schema validation, quality gate → dead-letter immediately</li>
320
+ <li><strong>FATAL:</strong> 401/403 auth failure → stop and alert</li>
321
+ </ul>
322
+ </div>
323
+ <div class="col">
324
+ <h4>Stage Timeouts</h4>
325
+ <ul>
326
+ <li>Research: 5 min</li>
327
+ <li>Script: 3 min</li>
328
+ <li>Asset generation: 10 min</li>
329
+ <li>Video rendering: 30 min</li>
330
+ <li>Shorts extraction: 10 min</li>
331
+ <li>Quality check: 2 min</li>
332
+ <li>Publishing: 5 min</li>
333
+ </ul>
334
+ </div>
335
+ </div>
336
+
337
+ <div class="callout">
338
+ <strong>State machine (PostgreSQL):</strong> Every production has an explicit status: QUEUED → RUNNING → SUCCEEDED / FAILED / WAITING_REVIEW / CANCELLED. Every stage: PENDING → RUNNING → SUCCEEDED / FAILED / SKIPPED. Never infer state from execution history. Hash-based idempotency: stages only re-run if input_hash changes or output_hash is invalid.
339
+ </div>
340
+
341
+ <h2><span class="section-num">9</span>Security Architecture (Enterprise Grade)</h2>
342
+
343
+ <table>
344
+ <tr><th>Concern</th><th>Implementation</th></tr>
345
+ <tr><td>Credential storage</td><td>Never in workflow JSON. Environment variables → secrets manager (IBM Secrets Manager, HashiCorp Vault, AWS Secrets Manager). MCP server reads from env at startup only.</td></tr>
346
+ <tr><td>Log redaction</td><td>Regex patterns covering gsk_*, AIza*, Telegram bot tokens, Bearer tokens applied at all log sinks. 10+ credential pattern classes.</td></tr>
347
+ <tr><td>API boundary validation</td><td>All LLM responses, image URLs, and TTS outputs validated against schemas before use. Third-party data is untrusted data (Hyrum's Law).</td></tr>
348
+ <tr><td>Rotation procedures</td><td>Documented per-service rotation: generate → update env → restart service → test auth → revoke old. Emergency rotation protocol documented.</td></tr>
349
+ <tr><td>MCP server auth</td><td>API key auth on MCP server endpoints. IDE → MCP connection over TLS. Key scoped to IDE session, not global.</td></tr>
350
+ <tr><td>Content safety</td><td>Fact-check gate: no claims stronger than source. Honesty pass rewrites misleading on-screen text. No real brand logos in video (verified in QC).</td></tr>
351
+ <tr><td>Voice cloning policy</td><td>Only clone own voice (ElevenLabs ToS). Policy check in pipeline metadata. Audit log of voice ID used per production.</td></tr>
352
+ </table>
353
+
354
+ <h2><span class="section-num">10</span>Observability + Cost Tracking</h2>
355
+
356
+ <p>PostgreSQL <code>usage_events</code> table tracks every API call: provider, operation, units (tokens/images/seconds), estimated cost. Enables per-video cost breakdown and provider cost comparison.</p>
357
+
358
+ <div class="row2">
359
+ <div class="col">
360
+ <h4>Production Metrics</h4>
361
+ <ul>
362
+ <li>Success rate per stage</li>
363
+ <li>P50/P95/P99 render time</li>
364
+ <li>Asset cache hit rate</li>
365
+ <li>Fact-check rejection rate</li>
366
+ <li>Quality gate pass rate</li>
367
+ </ul>
368
+ </div>
369
+ <div class="col">
370
+ <h4>Cost Metrics</h4>
371
+ <ul>
372
+ <li>Cost per video (total)</li>
373
+ <li>Cost by provider (LLM, image, TTS)</li>
374
+ <li>Cost by stage</li>
375
+ <li>Storage per video</li>
376
+ <li>Render CPU utilisation</li>
377
+ </ul>
378
+ </div>
379
+ </div>
380
+
381
+ <h2><span class="section-num">11</span>Key Upgrades Over Current Implementation</h2>
382
+
383
+ <table>
384
+ <tr><th>Current gap</th><th>Enterprise fix</th><th>Priority</th></tr>
385
+ <tr><td>Hardcoded topic pool in JS</td><td>Topic registry in DB with trending signal (YouTube API, Google Trends)</td><td class="priority-high">High</td></tr>
386
+ <tr><td>Pollinations (no SLA, free)</td><td>fal.ai or Replicate with retry + fallback chain</td><td class="priority-high">High</td></tr>
387
+ <tr><td>edge-tts only (local binary)</td><td>TTS provider abstraction: ElevenLabs primary, Azure fallback</td><td class="priority-high">High</td></tr>
388
+ <tr><td>No script versioning</td><td>SHA256 content hashes on every artifact, git-style lineage</td><td class="priority-high">High</td></tr>
389
+ <tr><td>Monolithic 1000+ line workflow</td><td>5 independent workflows (Research, Script, Assets, Render, Publish)</td><td class="priority-med">Medium</td></tr>
390
+ <tr><td>No horizontal scaling</td><td>Redis job queue + multiple render workers after baseline proves need</td><td class="priority-med">Medium</td></tr>
391
+ <tr><td>Telegram-only delivery</td><td>Multi-channel router: Telegram + YouTube + LinkedIn + TikTok</td><td class="priority-med">Medium</td></tr>
392
+ <tr><td>No human approval gate</td><td>WAITING_REVIEW status + approval webhook for fact-check failures</td><td class="priority-med">Medium</td></tr>
393
+ <tr><td>No asset library (fresh gen every time)</td><td>Composable asset library with metadata lookup + embedding fallback</td><td class="priority-low">Low</td></tr>
394
+ <tr><td>No Remotion/React animation</td><td>Remotion integration for motion graphics (follows PDF workflow pattern)</td><td class="priority-low">Low</td></tr>
395
+ </table>
396
+
397
+ <h2><span class="section-num">12</span>IBM Bob-Specific Integration Points</h2>
398
+
399
+ <div class="callout callout-success">
400
+ Bob's MCP ecosystem makes this the <strong>best platform</strong> for this pipeline. Every pipeline stage maps to a Bob skill or MCP tool call. The agent loop is observable, retryable, and resumable natively.
401
+ </div>
402
+
403
+ <table>
404
+ <tr><th>Bob capability</th><th>Video pipeline use</th></tr>
405
+ <tr><td><code>build-mcp-server</code> skill</td><td>Build the video-agent MCP server with all 6 tools registered</td></tr>
406
+ <tr><td><code>configure-hooks</code> skill</td><td>Add stop hook to save production state on session end</td></tr>
407
+ <tr><td><code>gstack-qa</code></td><td>QA the MCP server's tool responses before deploying</td></tr>
408
+ <tr><td><code>gstack-review</code></td><td>Pre-landing review of every pipeline stage change</td></tr>
409
+ <tr><td><code>gstack-ship</code></td><td>Version-bumped deploys of the MCP server with changelog</td></tr>
410
+ <tr><td><code>gstack-investigate</code></td><td>Root-cause analysis when a pipeline stage fails overnight</td></tr>
411
+ <tr><td><code>gstack-canary</code></td><td>Post-deploy monitoring of first production after MCP server update</td></tr>
412
+ <tr><td><code>observability-and-instrumentation</code> skill</td><td>Add structured logging + cost metrics to every tool handler</td></tr>
413
+ <tr><td>IBM watsonx models</td><td>Replace Groq for data-residency-sensitive deployments (EU, healthcare)</td></tr>
414
+ <tr><td>IBM Secrets Manager</td><td>Credential rotation without restarting the MCP server</td></tr>
415
+ </table>
416
+
417
+ <h2><span class="section-num">13</span>Migration Roadmap (12 Weeks)</h2>
418
+
419
+ <table>
420
+ <tr><th>Week</th><th>Milestone</th><th>What ships</th></tr>
421
+ <tr><td>1-2</td><td>MCP server scaffold</td><td>TypeScript MCP server with 6 registered tools, provider abstraction layer, PostgreSQL state machine, credential management</td></tr>
422
+ <tr><td>3-4</td><td>Provider parity</td><td>LLM gateway (Groq + OpenAI + watsonx), TTS abstraction (edge-tts + ElevenLabs), image gen abstraction (Pollinations + fal.ai)</td></tr>
423
+ <tr><td>5-6</td><td>Reliability</td><td>Retry + timeout policy, exponential backoff, dead-letter queue, stage idempotency (hash-based), QC hard gates</td></tr>
424
+ <tr><td>7-8</td><td>Asset library</td><td>Composable character system, metadata-first lookup, embedding fallback, style validation, PostgreSQL registry</td></tr>
425
+ <tr><td>9-10</td><td>Observability</td><td>usage_events cost tracking, stage metrics, Grafana dashboard, alert on P95 render time exceeding threshold</td></tr>
426
+ <tr><td>11-12</td><td>Multi-IDE verification</td><td>Verified working in Bob + Kiro + Cursor; automated overnight batch running in all three; docs + runbooks</td></tr>
427
+ </table>
428
+
429
+ <h2><span class="section-num">14</span>What NOT to Do (Lessons from Current Implementation)</h2>
430
+
431
+ <div class="callout callout-critical">
432
+ <strong>Critical anti-patterns found in workflow.json and the PDF workflow:</strong>
433
+ <ul style="margin-top:8px">
434
+ <li><strong>Hardcoded credentials</strong> in workflow JSON (found: Telegram tokens, Gemini keys) — already partially fixed, must be completed</li>
435
+ <li><strong>No state persistence</strong> — a crash loses all in-flight work; no resume-from-stage</li>
436
+ <li><strong>Polling with Wait nodes</strong> (90s wait for Groq TPM) — use proper exponential backoff with jitter</li>
437
+ <li><strong>Monolithic 1000-line workflow</strong> — impossible to test stages independently</li>
438
+ <li><strong>Platform-binary TTS</strong> (edge-tts local binary) — breaks in any containerised or cloud deployment</li>
439
+ <li><strong>No content safety layer</strong> — AI can generate misleading on-screen text (noted in PDF: "TARGET COMPROMISED" incident)</li>
440
+ <li><strong>Topic pool hardcoded in JS</strong> — no way to add trending topics without a deploy</li>
441
+ <li><strong>"I'm going to sleep" prompt pattern</strong> — giving the agent unlimited browser access overnight is a security risk at enterprise scale; use scoped permissions per session</li>
442
+ </ul>
443
+ </div>
444
+
445
+ <h2><span class="section-num">15</span>Bottom Line</h2>
446
+
447
+ <p>The video-agent-skill workflow is a working proof of concept. The architecture decision — <strong>AI proposes → deterministic systems execute → validators approve → orchestrator routes</strong> — is correct and should be preserved. What makes it enterprise-grade is:</p>
448
+
449
+ <ol>
450
+ <li><strong>Provider abstraction</strong> so any LLM, TTS, or image backend is swappable in one config change</li>
451
+ <li><strong>MCP server as the agent interface</strong> so any IDE (Bob, Kiro, Cursor) orchestrates the same tools</li>
452
+ <li><strong>PostgreSQL state machine</strong> with explicit status transitions and hash-based idempotency</li>
453
+ <li><strong>Hard quality gates</strong> (LUFS, codec, frame checks) before any delivery</li>
454
+ <li><strong>Observability + cost tracking</strong> from day one, not retrofitted later</li>
455
+ </ol>
456
+
457
+ <p>The existing n8n workflow.json is the best possible proof that this pipeline works. The MCP server approach makes it work everywhere — not just on one Linux box running n8n with a hardcoded Groq key.</p>
458
+
459
+ <footer>
460
+ <p>Made with IBM Bob — Analysis based on programmatic video architecture, AI video workflow guide, and workspace design specifications.</p>
461
+ </footer>
462
+ </div>
463
+ </body>
464
+ </html>
package/.claude-plugin/marketplace.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "name": "frameforge",
3
+ "displayName": "FrameForge — AI Video Production",
4
+ "description": "Full AI video production engine. Produce short-form reels (1080×1920), YouTube videos (1920×1080), or code-driven animated explainers — directly from your IDE. Playwright + FFmpeg renders every frame. 17 MCP tools.",
5
+ "version": "2.3.1",
6
+ "homepage": "https://github.com/AMG555/FrameForge",
7
+ "plugins": [
8
+ {
9
+ "name": "video-pipeline",
10
+ "path": "plugins/video-pipeline/.claude-plugin/plugin.json",
11
+ "skills": [
12
+ {
13
+ "name": "video-pipeline",
14
+ "displayName": "FrameForge Video Pipeline",
15
+ "description": "End-to-end video production: research → script → TTS → images → render → publish. Three paths: (1) IDE writes scenes (most common, no API key), (2) code-driven Playwright animation, (3) auto-research pipeline. 17 MCP tools.",
16
+ "triggerPhrases": [
17
+ "make a video about",
18
+ "produce a reel on",
19
+ "create a short",
20
+ "edit this into a reel",
21
+ "make an explainer",
22
+ "animated video",
23
+ "code-driven video",
24
+ "generate video",
25
+ "run the pipeline",
26
+ "publish video",
27
+ "overnight batch",
28
+ "queue videos"
29
+ ]
30
+ }
31
+ ]
32
+ }
33
+ ],
34
+ "mcpServer": {
35
+ "command": "npx",
36
+ "args": ["--yes", "--package=@amg555/frameforge-mcp", "frameforge-mcp"],
37
+ "description": "Runs the FrameForge MCP server via npx (no install needed). Requires ffmpeg and edge-tts on PATH."
38
+ },
39
+ "requirements": {
40
+ "node": ">=18.0.0",
41
+ "binaries": ["ffmpeg", "ffprobe"],
42
+ "optional": ["edge-tts", "python3"],
43
+ "notes": "edge-tts: pip install edge-tts. Playwright (for code-driven animation): npm install playwright && npx playwright install chromium (run once in project dir)."
44
+ }
45
+ }
package/.gitattributes ADDED
@@ -0,0 +1,19 @@
1
+ # Normalise line endings on commit; checkout as-is on Windows
2
+ * text=auto
3
+
4
+ # Shell scripts must be LF
5
+ *.sh text eol=lf
6
+
7
+ # JSON, Markdown, JS — normalise
8
+ *.json text eol=lf
9
+ *.md text eol=lf
10
+ *.js text eol=lf
11
+
12
+ # Binary files
13
+ *.mp4 binary
14
+ *.mp3 binary
15
+ *.m4a binary
16
+ *.wav binary
17
+ *.png binary
18
+ *.jpg binary
19
+ *.pdf binary
package/.mcp.json ADDED
@@ -0,0 +1,45 @@
1
+ {
2
+ "_comment": "MCP configuration for FrameForge — Claude Code, Cursor, Windsurf, Codex, opencode, and IBM Bob.",
3
+ "_modes": {
4
+ "stdio": "ZERO-PORT STDIO: Recommended for Cursor & Claude Code. Spawns node process directly via stdin/stdout.",
5
+ "local": "HTTP SERVER: Runs local server on port 3210. Good for web apps or multi-client sharing.",
6
+ "remote": "CLOUDFLARE REMOTE MCP: Connects via edge URL. Saves ~80% prompt context tokens in your IDE."
7
+ },
8
+ "_paths": {
9
+ "agent-first": "Path 1 — your IDE writes scenes, FrameForge renders. Only TTS + image keys needed. No LLM key.",
10
+ "auto-research": "Path 2 — FrameForge researches and scripts autonomously. Requires PROVIDER_LLM + its key."
11
+ },
12
+
13
+ "mcpServers": {
14
+
15
+ "frameforge": {
16
+ "_comment": "RECOMMENDED — Path 1 agent-first (no LLM key). Add PROVIDER_LLM + key only for research_topic/write_script/queue_full_pipeline.",
17
+ "command": "node",
18
+ "args": ["src/mcp-server/stdio.js"],
19
+ "env": {
20
+ "PROVIDER_TTS": "edge-tts",
21
+ "PROVIDER_IMAGE": "pollinations"
22
+ }
23
+ },
24
+
25
+ "frameforge-http": {
26
+ "_comment": "LOCAL HTTP on port 3210 — same Path 1 defaults. Add LLM vars only for auto-research path.",
27
+ "command": "node",
28
+ "args": ["src/mcp-server/server.js"],
29
+ "env": {
30
+ "PROVIDER_TTS": "edge-tts",
31
+ "PROVIDER_IMAGE": "pollinations",
32
+ "MCP_PORT": "3210"
33
+ }
34
+ },
35
+
36
+ "frameforge-remote": {
37
+ "_comment": "REMOTE EDGE: Connects via Cloudflare Worker. Deploy cloudflare-mcp/ to enable.",
38
+ "url": "https://frameforge.YOUR_SUBDOMAIN.workers.dev/mcp",
39
+ "headers": {
40
+ "Authorization": "Bearer YOUR_MCP_AUTH_TOKEN"
41
+ }
42
+ }
43
+
44
+ }
45
+ }