@bendyline/gilde 0.1.37 → 0.1.39

package/data/craftbook-templates/yo/youtube-chapters-seo/versions/1.0.2/craftbook.json

@@ -0,0 +1,146 @@
+{
+  "id": "youtube-chapters-seo",
+  "name": "YouTube Chapters & SEO Metadata",
+  "description": "Turn a video (or its transcript) into a complete, paste-ready YouTube publishing kit — SEO title options, an optimized description with timestamped chapters, tags/keywords, and thumbnail text ideas — so an upload ranks and is navigable. Scopes the target keyword and metadata limits FIRST, analyzes the transcript for chapter boundaries, then writes the SEO-optimized metadata kit. Doing keyword research and pulling real chapter timestamps before writing is what makes the description both discoverable and accurate, instead of clickbait that doesn't match the video.\n\nA gallery craftbook generated from an archetype spec. It runs\n`phase → (per-phase gate) → … → evaluate → (loop) → finish`. Each build\nphase that produces a checkable artifact is followed by a **runtime\ngate-checkpoint** — the runtime verifies the artifact and routes with no\nmodel turn, looping back to redo the phase on a miss. The final `evaluate`\nstep holds a static deliverable gate plus a reviewer QA pass. What it adds\nover the generic `build-loop`: a specialist role per phase, a\ndomain-correct ordering, and a concrete per-phase quality bar.\n\nDeliverables marked \"artifact\" land in the project's artifacts drawer (`write_artifact` / `read_artifact`), not the shipped workspace — review output is not product source.\n\nPhases:\n\n1. SEO & metadata scope (planner) — target keyword, limits, sections, chapter format → gated on artifact `{{workPath}}/scope.md` (markdown-notes)\n2. Find chapters & keywords (data-analyst) — topic-shift timestamps + keyword extraction → gated on artifact `{{workPath}}/analysis.json` (json)\n3. Write the metadata kit (copywriter) — title options, description+chapters, tags, thumbnail text → gated on `youtube-metadata.md` (markdown-doc)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "scope",
+  "triggers": [
+    "youtube description and chapters",
+    "seo title for my video",
+    "youtube metadata",
+    "optimize my video description",
+    "video tags and chapters"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "SEO & metadata scope",
+      "description": "target keyword, limits, sections, chapter format",
+      "prompt": "Lock the SEO plan BEFORE writing. Step 1: record the video (title intent, transcript path, duration) and the primary target keyword/phrase plus 2-3 secondary ones the audience would search. Step 2: capture the platform limits as hard rules: title ≤ 100 chars (front-load the keyword), description first ~150 chars are the visible/snippet zone, chapters need ≥3 markers with the FIRST at `00:00`, tags within the char budget. Step 3: define the description structure (hook line with keyword -> 2-3 sentence summary -> CHAPTERS list -> links/CTA -> hashtags). Step 4: define thumbnail-text guidance (≤4 punchy words). Write an acceptance-criteria checklist (title ≤100 chars with keyword up front, description opens with the keyword in the first line, ≥3 chapters with first at 00:00 and monotonic timestamps within duration, tag list present, 3 title options, thumbnail text ideas) and decisions to `{{workPath}}/scope.md` via write_task_note AND the produces path.\n\nThe deliverable `{{workPath}}/scope.md` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "planner",
+      "advanceWhen": {
+        "file": "{{workPath}}/scope.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/scope.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/scope.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "scope",
+        "maxAttempts": 3
+      },
+      "next": "analyze"
+    },
+    {
+      "id": "analyze",
+      "name": "Find chapters & keywords",
+      "description": "topic-shift timestamps + keyword extraction",
+      "prompt": "Mine the transcript for structure and terms. Step 1: read the transcript with timestamps and detect topic boundaries where the subject clearly shifts. Step 2: for each boundary record a `MM:SS`/`HH:MM:SS` timestamp and a short keyword-aware title; force the first to `00:00`. Step 3: enforce ≥3 chapters, monotonic timestamps within the duration, and reasonable spacing. Step 4: extract the recurring topics/terms the video actually covers (frequency + relevance) to inform tags and ensure the title/description match the content. Step 5: write the chapters and a candidate keyword/tag list to `{{workPath}}/analysis.json` via write_task_note AND the produces path. On a loop-back, adjust only the flagged chapters/terms.\n\nThe deliverable `{{workPath}}/analysis.json` lands in the project's artifacts drawer — write it with `write_artifact` and read it back with `read_artifact`; the shipped workspace stays untouched.",
+      "suggestedRole": "data-analyst",
+      "advanceWhen": {
+        "file": "{{workPath}}/analysis.json",
+        "minBytes": 1,
+        "sniff": "json-valid",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/analysis.json",
+            "bytes": 2,
+            "artifact": true
+          }
+        ],
+        "onReject": "analyze",
+        "maxAttempts": 3
+      },
+      "next": "write"
+    },
+    {
+      "id": "write",
+      "name": "Write the metadata kit",
+      "description": "title options, description+chapters, tags, thumbnail text",
+      "prompt": "Assemble the paste-ready kit from the analysis. Step 1: write 3 title options, each ≤100 chars with the primary keyword front-loaded; mark a recommended one. Step 2: write the description: a hook FIRST line containing the keyword (this is the search snippet), a 2-3 sentence summary, then the CHAPTERS block as plain `00:00 Title` lines (first line `00:00`) pasted from the analysis, then a links/CTA section, then 3-5 hashtags. Step 3: write a comma-separated tags line from the keyword analysis within the budget. Step 4: give 2-3 thumbnail text ideas (≤4 words each). Step 5: assemble everything into `youtube-metadata.md` under clear headers. Keep claims accurate to the video — no clickbait that the content does not deliver. write_task_note the path and chapter count. On a loop-back, fix only the flagged sections.",
+      "suggestedRole": "copywriter",
+      "advanceWhen": {
+        "file": "youtube-metadata.md",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "youtube-metadata.md",
+            "bytes": 500
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkContains",
+            "scope": "standard",
+            "inputs": {
+              "file": "youtube-metadata.md",
+              "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+              "flags": "i"
+            }
+          }
+        ],
+        "onReject": "write",
+        "maxAttempts": 4
+      },
+      "next": "evaluate"
+    },
+    {
+      "id": "evaluate",
+      "name": "Evaluate",
+      "description": "Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.",
+      "prompt": "Validate the kit against platform rules. Step 1: confirm `youtube-metadata.md` has all sections (3 titles, description, chapters, tags, thumbnail text) — PASS/FAIL. Step 2: confirm each title is ≤100 chars with the keyword front-loaded, and the description's FIRST line contains the keyword. Step 3: confirm the chapters block has ≥3 markers, the first is `00:00`, timestamps are monotonic and within the video duration. Step 4: spot-check 2 chapter timestamps against the transcript — real topic shifts? Step 5: confirm tags fit the budget and titles/description honestly match the content (no clickbait). Write PASS/FAIL per criterion.\n\nThen route — this is the whole point of the loop:\n\n- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: \"evaluate\", next: \"finish\" })`.\n- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: \"evaluate\", next: \"write\" })` to loop back. The builder fixes exactly those gaps.\n\nNever route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.",
+      "suggestedRole": "reviewer",
+      "consumes": [
+        {
+          "file": "youtube-metadata.md"
+        }
+      ],
+      "next": "write"
+    },
+    {
+      "id": "finish",
+      "name": "Finish",
+      "description": "All acceptance criteria met. Stamp a short summary and report DONE.",
+      "prompt": "Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.",
+      "suggestedRole": "developer",
+      "terminal": true
+    }
+  ],
+  "version": "1.0.2",
+  "releasedAt": "2026-08-21T00:00:00Z",
+  "paramSchema": {
+    "type": "object",
+    "properties": {
+      "workPath": {
+        "type": "string",
+        "title": "Working folder",
+        "description": "Per-task working folder in the artifacts drawer. Defaults to this task's own folder so runs never collide; override with a stable name when you deliberately want runs to share files.",
+        "default": "{{task.dir}}"
+      }
+    }
+  },
+  "minGezelVersion": "1.26233"
+}

package/data/craftbook-templates/yo/youtube-chapters-seo/versions/1.0.2/test.json

@@ -0,0 +1,106 @@
+{
+  "schemaVersion": 1,
+  "title": "YouTube Chapters & SEO Metadata smoke eval",
+  "objective": "Self-contained smoke eval for the YouTube Chapters & SEO Metadata craftbook using the media generic harness.",
+  "tags": [
+    "media"
+  ],
+  "prompt": "Our media files are all listd in source/media-index.csv. Can you put together the production plan for them as media-plan.json?",
+  "setup": {
+    "projectName": "YouTube Chapters & SEO Metadata Eval",
+    "about": "Self-contained eval project for youtube-chapters-seo. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/media-plan.json.",
+    "missionObjectives": "Use the YouTube Chapters & SEO Metadata craftbook/template, read the seeded local fixtures, and write media-plan.json without network calls, real credentials, or live services.",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# YouTube Chapters & SEO Metadata Eval Brief\n\nClient: Boreal Desk, a home-office accessories company.\nAudience: operations leads who need an artifact they can use this week.\n\nFixed source facts for grounding:\n- The returns desk pilot covered 18 SKUs.\n- Median first response improved from 18 hours to 6 hours.\n- Preventable refund leakage fell from 14.2% to 8.9%.\n- The top unresolved complaint is status silence after photo submission.\n- Required next actions are automated status emails, barcode-exception training, and a weekly Finance exception export.\n\nUse these facts when the task asks for prose, analysis, copy, UI content, or test data. Do not use live web services, real credentials, or current outside data.\n\nCraftbook under test: youtube-chapters-seo - YouTube Chapters & SEO Metadata.\n"
+      },
+      {
+        "path": "source/media-index.csv",
+        "content": "filename,type,duration_or_size,notes\npilot-interview.wav,audio,00:02:15,mentions response time and status silence\nreturns-desk.png,image,1600x900,shows intake form and photo evidence step\nlaunch-clip.mp4,video,00:01:05,shows barcode exception handling\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "role": "Producer"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "media-plan.json is a valid JSON media-production manifest grounded in seeded fixture metadata.",
+    "deliverables": [
+      {
+        "path": "media-plan.json",
+        "kind": "json",
+        "minBytes": 700,
+        "checks": [
+          {
+            "kind": "sniff",
+            "file": "media-plan.json",
+            "sniff": "json-valid"
+          },
+          {
+            "kind": "contains",
+            "file": "media-plan.json",
+            "pattern": "pilot-interview\\.wav|returns-desk\\.png|launch-clip\\.mp4",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "media-plan.json",
+            "pattern": "outputs|assets|steps|cues|verification",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "media-plan.json",
+            "pattern": "accessibility|alt|caption|transcript|metadata",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "media-plan.json",
+      "kind": "json"
+    },
+    "axes": [
+      {
+        "name": "completeness",
+        "description": "The manifest covers sources, outputs, and processing steps end to end."
+      },
+      {
+        "name": "grounding",
+        "description": "Only seeded media fixtures are referenced, with faithful metadata."
+      },
+      {
+        "name": "accessibility",
+        "description": "Alt text, captions, or transcripts are planned wherever the class requires."
+      },
+      {
+        "name": "precision",
+        "description": "Timestamps, crops, and cues are specific enough to execute."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "media fixture handling",
+    "structured manifest",
+    "verification metadata"
+  ],
+  "extensions": {
+    "legacySimulators": [
+      {
+        "id": "youtube-chapters-seo-media-fixtures",
+        "kind": "data-source",
+        "status": "implemented",
+        "description": "Seeded local media index replacing real audio, video, image generation, and external media metadata services."
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bendyline/gilde",
-  "version": "0.1.37",
+  "version": "0.1.39",
   "description": "The gilde catalog: model manifests, toolsets, craftbooks, roles, and project types for gezel.",
   "license": "MIT",
   "private": false,

package/schemas/craftbook-doc.schema.json

@@ -430,7 +430,8 @@
                     "artifacts",
                     "project-memory",
                     "gezel-memory",
-                    "shared"
+                    "shared",
+                    "knowledge"
                   ]
                 }
               }
@@ -3364,7 +3365,8 @@
                         "artifacts",
                         "project-memory",
                         "gezel-memory",
-                        "shared"
+                        "shared",
+                        "knowledge"
                       ]
                     }
                   }

package/schemas/craftbook-template-version.schema.json

@@ -83,7 +83,8 @@
                     "artifacts",
                     "project-memory",
                     "gezel-memory",
-                    "shared"
+                    "shared",
+                    "knowledge"
                   ]
                 }
               }
@@ -3011,7 +3012,8 @@
                         "artifacts",
                         "project-memory",
                         "gezel-memory",
-                        "shared"
+                        "shared",
+                        "knowledge"
                       ]
                     }
                   }