@bendyline/gilde 0.1.37 → 0.1.39

package/data/craftbook-templates/to/topic-explainer/versions/1.0.2/craftbook.json

@@ -0,0 +1,152 @@
+{
+  "id": "topic-explainer",
+  "name": "Topic Explainer",
+  "description": "Explain a complex topic clearly for a defined audience: a planner pins the audience, their assumed prior knowledge, and the concepts that must be taught, a researcher gathers accurate facts and good analogies with sources, and a copywriter writes a progressively-structured explainer that builds from fundamentals to the full picture. The ordering matters because an explainer written without a fixed audience either condescends or loses people, and one written without a concept map skips a prerequisite; locking the audience and a concept dependency order first guarantees the explanation actually lands. Use this for 'explain X like I'm a beginner/expert', concept explainers, how-it-works guides, ELI5/ELI-expert pieces, and turning a hard topic into an accessible read.\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. Scope the explainer (planner) — audience, assumed knowledge, and concept dependency order → gated on artifact `{{workPath}}/scope.md` (markdown-notes)\n2. Gather facts & analogies (researcher) — accurate facts, examples, and analogies with sources → gated on artifact `{{workPath}}/facts.md` (markdown-notes)\n3. Write the explainer (copywriter) — progressive explainer from fundamentals to full picture → gated on `explainer.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": [
+    "explain this topic",
+    "how does X work",
+    "explain like I'm a beginner",
+    "make this concept accessible",
+    "write an explainer on"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the explainer",
+      "description": "audience, assumed knowledge, and concept dependency order",
+      "prompt": "1. Pin the target audience and their assumed prior knowledge in one sentence (e.g. 'curious non-technical adult, no math'), and the target length. 2. List the concepts that MUST be understood, then order them by dependency (what must be taught before what) — this is the explainer's spine. 3. Decide the structure: a one-line 'what it is', then fundamentals, then the mechanism, then implications/examples, then a recap; flag where an analogy or a worked example is needed. 4. Write an acceptance-criteria checklist (e.g. 'no concept is used before it is introduced', 'jargon is defined on first use', 'at least 2 concrete examples or analogies', 'a reader at the assumed level could follow it', 'every factual claim is accurate and cited where non-obvious'). 5. Record decisions. Call write_task_note with the audience, concept order, structure, and checklist; write the same to {{workPath}}/scope.md.\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": "research"
+    },
+    {
+      "id": "research",
+      "name": "Gather facts & analogies",
+      "description": "accurate facts, examples, and analogies with sources",
+      "prompt": "1. For each concept in the dependency order, gather accurate facts into {{workPath}}/facts.md with sources [n] for any non-obvious or quantitative claim, prioritizing authoritative explanations. 2. Find or craft at least two concrete examples and one strong analogy per hard concept, and sanity-check that each analogy does not mislead (note where it breaks down). 3. Note common misconceptions about the topic so the explainer can pre-empt them. 4. Verify any figure or mechanism against a reliable source; mark uncertain points UNVERIFIED. Good looks like a fact file where every concept has accurate grounding plus a teaching device. Do not write the explainer yet.\n\nThe deliverable `{{workPath}}/facts.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": "researcher",
+      "advanceWhen": {
+        "file": "{{workPath}}/facts.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/facts.md",
+            "bytes": 120,
+            "artifact": true
+          },
+          {
+            "kind": "sniff",
+            "file": "{{workPath}}/facts.md",
+            "sniff": "nonempty",
+            "artifact": true
+          }
+        ],
+        "onReject": "research",
+        "maxAttempts": 3
+      },
+      "next": "write"
+    },
+    {
+      "id": "write",
+      "name": "Write the explainer",
+      "description": "progressive explainer from fundamentals to full picture",
+      "prompt": "1. Write explainer.md following the locked concept order: a crisp one-line 'what it is', then build up concept by concept so nothing is referenced before it is introduced. 2. Define every term on first use, and use the gathered examples/analogies to make hard concepts concrete (note where an analogy breaks down). 3. Pre-empt the common misconceptions. 4. Match the assumed-knowledge level exactly — neither condescend nor assume away prerequisites. 5. Cite non-obvious facts [n] and end with a short recap of the key takeaways. 6. On a loop-back, fix only the named gaps. 7. Call write_task_note with the explainer path and which criteria now pass.",
+      "suggestedRole": "copywriter",
+      "advanceWhen": {
+        "file": "explainer.md",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "explainer.md",
+            "bytes": 500
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkContains",
+            "scope": "standard",
+            "inputs": {
+              "file": "explainer.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": "Open explainer.md and check EACH criterion PASS/FAIL: (1) no concept is used before it is introduced (trace the dependency order from {{workPath}}/scope.md); (2) every jargon term is defined on first use; (3) at least two concrete examples or analogies appear and any analogy notes where it breaks down; (4) it matches the assumed-knowledge level — readable by the target audience without condescension; (5) non-obvious facts are cited and accurate (spot-check 2 against {{workPath}}/facts.md); (6) a recap of takeaways closes it. An explainer that drops a prerequisite, leaves jargon undefined, or misstates a fact FAILS.\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": "explainer.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/to/topic-explainer/versions/1.0.2/test.json

@@ -0,0 +1,113 @@
+{
+  "schemaVersion": 1,
+  "title": "Topic Explainer smoke eval",
+  "objective": "Self-contained smoke eval for the Topic Explainer craftbook using the corpus generic harness.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "We need a topic explainer for the returns-desk work. The backgound info is in source/brief.md — have a look and write it up in report.md.",
+  "setup": {
+    "projectName": "Topic Explainer Eval",
+    "about": "Self-contained eval project for topic-explainer. Seeded inputs are under workspace/source or workspace/fixtures; final deliverable is workspace/report.md.",
+    "missionObjectives": "Use the Topic Explainer craftbook/template, read the seeded local fixtures, and write report.md without network calls, real credentials, or live services.",
+    "files": [
+      {
+        "path": "source/brief.md",
+        "content": "# Topic Explainer 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: topic-explainer - Topic Explainer.\n"
+      }
+    ],
+    "worker": {
+      "name": "Jules",
+      "role": "Writer"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "report.md is a source-grounded markdown artifact with required facts and actions.",
+    "deliverables": [
+      {
+        "path": "report.md",
+        "kind": "markdown-report",
+        "minBytes": 1000,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "source/brief\\.md|Brief",
+            "flags": "i",
+            "label": "cite or name the seeded source"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "18\\b[\\s\\S]{0,30}\\bSKUs",
+            "flags": "i",
+            "label": "include the 18-SKU pilot scope"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "18\\s*hours|6\\s*hours",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "14\\.2%|8\\.9%",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "status silence|photo submission",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "report.md",
+            "pattern": "automated status emails|barcode|Finance",
+            "flags": "i"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "report.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "grounding",
+        "description": "Seeded facts appear faithfully and the source is cited."
+      },
+      {
+        "name": "structure",
+        "description": "Sections progress logically for the artifact class."
+      },
+      {
+        "name": "completeness",
+        "description": "Required elements (risks, next actions, scope) are all present."
+      },
+      {
+        "name": "tone",
+        "description": "The register fits the audience and artifact class."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "source-grounded prose",
+    "section structure",
+    "next-action clarity"
+  ]
+}

package/data/craftbook-templates/tr/transcribe-and-shownotes/versions/1.0.2/craftbook.json

@@ -0,0 +1,127 @@
+{
+  "id": "transcribe-and-shownotes",
+  "name": "Transcript to Shownotes",
+  "description": "Take a finished recording from raw transcript to publishable shownotes: a clean transcript on file, timestamped chapters, a summary listeners actually read, and the links mentioned — the per-episode ritual that turns audio into an archive. Locks the shownotes checklist FIRST (chapters timestamped, every link captured, names spelled right), then gets the transcript on file, then writes the shownotes from it. Use for episode shownotes, transcribing an episode, chapter timestamps, and 'turn this recording into shownotes'.\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. Scope the shownotes (planner) — locate the recording or transcript, lock the shownotes checklist → gated on artifact `{{workPath}}/scope.md` (markdown-notes)\n2. Get the transcript on file (transcriber) — clean, speaker-labeled, timestamped transcript under transcripts/\n3. Write the shownotes (copywriter) — summary, timestamped chapters, links and mentions, pull quotes → gated on artifact `{{workPath}}/report.md` (markdown-report)\n\nThe gates never advance with an unmet criterion, and loop back to the\nowning phase to fix named gaps.\n",
+  "entryStepId": "scope",
+  "triggers": [
+    "turn the recording into shownotes",
+    "shownotes for the episode",
+    "transcribe the episode",
+    "episode chapters and shownotes",
+    "write the shownotes"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the shownotes",
+      "description": "locate the recording or transcript, lock the shownotes checklist",
+      "prompt": "Define the job before touching the audio. Step 1: find the episode's recording or transcript — check the recordings folder and episodes.json for which episode is being shipped and what already exists on file. Step 2: confirm with the owner anything the transcript alone won't give you — guest name spellings, links they promised listeners, and where the shownotes get published. Step 3: write an acceptance-criteria checklist ('a clean, complete transcript is on file under transcripts/', 'every chapter has a timestamp that exists in the transcript', 'every link mentioned in the episode is captured', 'names spelled right throughout', 'the summary reads like the episode, not a form'). Call write_task_note with the episode + checklist and write {{workPath}}/scope.md.\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": "transcript"
+    },
+    {
+      "id": "transcript",
+      "name": "Get the transcript on file",
+      "description": "clean, speaker-labeled, timestamped transcript under transcripts/",
+      "prompt": "Get the transcript on file. Step 1: if a transcript already exists (a provided file in the recordings folder), start from that; otherwise produce one from the recording through the project's transcription capabilities. Step 2: clean it — fix obvious mis-hearings, label the speakers, keep the timestamps. Step 3: save the cleaned transcript in the transcripts/ folder named for the episode (for example transcripts/ep12.md). A real transcript is substantial — never a stub or a summary. Step 4: call write_task_note with the transcript path and an approximate word count.",
+      "suggestedRole": "transcriber",
+      "next": "shownotes"
+    },
+    {
+      "id": "shownotes",
+      "name": "Write the shownotes",
+      "description": "summary, timestamped chapters, links and mentions, pull quotes",
+      "prompt": "Write the shownotes from the transcript. Step 1: a short summary a listener actually reads — what the episode is about and why it's worth their hour, in the show's voice. Step 2: the chapter list — timestamped, one line per chapter, every timestamp taken from the transcript, never invented. Step 3: links and mentions — everything referenced in the episode, with where each one points. Step 4: two or three pull quotes worth sharing, verbatim from the transcript with their speaker. Step 5: write {{workPath}}/report.md and call write_task_note with the chapter count and the link count.\n\nThe deliverable `{{workPath}}/report.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": "copywriter",
+      "advanceWhen": {
+        "file": "{{workPath}}/report.md",
+        "minBytes": 1,
+        "sniff": "nonempty",
+        "artifact": true
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "{{workPath}}/report.md",
+            "bytes": 1500,
+            "artifact": true
+          },
+          {
+            "kind": "contains",
+            "file": "{{workPath}}/report.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i",
+            "label": "at least one markdown heading",
+            "artifact": true
+          }
+        ],
+        "onReject": "shownotes",
+        "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": "Open {{workPath}}/report.md and the transcript under transcripts/ and verify every criterion from {{workPath}}/scope.md: the transcript on file is complete and speaker-labeled, every chapter timestamp appears in the transcript (spot-check each one — a chapter that points at nothing is fabrication), every link mentioned in the episode is captured, names are spelled the way the owner confirmed, and the pull quotes are verbatim. Write PASS/FAIL per criterion; on any failure, name the gap and loop back to shownotes.\n\nThe deliverable lives in the project's artifacts drawer — open `{{workPath}}/report.md` with `read_artifact`, not `read_file`.\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: \"shownotes\" })` 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": "{{workPath}}/report.md",
+          "artifact": true
+        }
+      ],
+      "next": "shownotes"
+    },
+    {
+      "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/tr/transcribe-and-shownotes/versions/1.0.2/test.json

@@ -0,0 +1,101 @@
+{
+  "schemaVersion": 1,
+  "title": "Transcript to Shownotes — episode 12",
+  "objective": "Measure whether the transcribe-and-shownotes craftbook files a clean transcript and produces shownotes whose chapter timestamps, links, and quotes all trace to the transcript.",
+  "tags": [
+    "corpus"
+  ],
+  "prompt": "weve got the raw transcript for episode 12 in recordings/ep12-transcript.txt — can you turn it into shownotes with chapters? tasks/eval/report.md is fine",
+  "setup": {
+    "projectName": "Shelf Life Podcast",
+    "about": "Podcast studio project for Shelf Life, a weekly show about books and the people who make them. Raw recordings and transcripts land under workspace/recordings; the episode store is workspace/episodes.json.",
+    "missionObjectives": "Turn shipped episodes into a publishable archive: clean transcript on file, timestamped chapters, links captured. Grounded in the seeded transcript — no live services, no real credentials.",
+    "files": [
+      {
+        "path": "recordings/ep12-transcript.txt",
+        "content": "Shelf Life — Episode 12 raw transcript (auto-generated, unedited)\nRecorded 2026-07-09. Host: Noor. Guests: Marta Velde (bookbinder), Daan Pols (apprentice).\n\n[00:00] NOOR: Welcome back to Shelf Life. Today we are in an actual bindery, which smells like glue and paper dust and, honestly, like heaven.\n[00:42] NOOR: Marta Velde has been binding books by hand for thirty-one years. Marta, welcome.\n[01:15] MARTA: Thank you. You are the first person to bring a microphone in here. Usually they bring broken books.\n[02:30] NOOR: Let's start there. What arrives on your bench in an average week?\n[03:48] MARTA: Family bibles, mostly. And cookbooks. People cry over cookbooks more than bibles, if you want the truth. The stains are the memories.\n[05:10] NOOR: How did you learn the trade?\n[06:55] MARTA: My teacher took me on in 1995. Four years sweeping floors before he let me sew a spine. I tell people that and they think it is cruelty. It was patience.\n[08:20] NOOR: And now you have an apprentice of your own. Daan, you are twenty-three. Why this trade?\n[09:45] DAAN: I was studying logistics and I hated every minute of it. I saw Marta repair a 1911 atlas on a video and I emailed her that night.\n[11:02] MARTA: He emailed me eleven times.\n[12:30] NOOR: Persistence is the trade, from what I am hearing. Marta, walk me through the atlas repair. What does a book like that need?\n[14:05] MARTA: First you take it apart completely. People are shocked by that. To save a book you must be willing to reduce it to sheets and thread.\n[15:40] MARTA: The spine linings come off with wheat starch paste and a bone folder. Slow. If you rush the paste you tear the paper and then you are not a binder, you are a butcher.\n[17:12] NOOR: How long does a full rebind take?\n[18:50] MARTA: Twenty hours for a simple case binding. The atlas took ninety. We charge less than the hours, always. Nobody pays what the hours cost. You do it because the book deserves it.\n[20:15] NOOR: Daan, what is the hardest skill so far?\n[21:48] DAAN: Sewing headbands. Marta makes it look like knitting. Mine look like a fishing accident.\n[23:30] NOOR: For listeners who want to try this — where do they start?\n[25:05] MARTA: We teach beginner classes at the bindery, first Saturday of every month. The schedule is at bindery-lane.example.com/classes.\n[26:40] NOOR: I will put that in the shownotes. What about materials? People always ask where to buy proper paper.\n[28:15] DAAN: Paper Road. It is a small mill shop, they ship everywhere. paperroad.example.org. Their 90-gram laid paper is what we sew practice blocks with.\n[29:50] NOOR: And if someone has a family book that needs repair but you are booked out?\n[31:20] MARTA: The guild keeps a directory of certified binders by region — guild-of-binders.example.net/directory. Anyone listed there will treat your book honestly.\n[33:00] NOOR: What is a book you refused to repair?\n[34:35] MARTA: A first edition someone wanted rebound in neon leather. I sent them away. Restoration is listening to the book, not shouting over it.\n[36:10] NOOR: Daan, where do you want to be in ten years?\n[37:45] DAAN: Running my own bench. Maybe here. Marta says the bindery outlives the binder, and I want that to be true.\n[39:20] MARTA: It is true. This bench was my teacher's bench. The scars in the wood are his.\n[40:55] NOOR: That gave me chills. Before we close — the mailbag question. A listener asks: are e-readers killing your trade?\n[42:30] MARTA: The opposite. The rarer the physical book becomes, the more the surviving ones matter. My waiting list has never been longer.\n[44:05] NOOR: Marta Velde, Daan Pols, thank you both. Come back with the apprentice's first solo binding.\n[45:40] DAAN: Deal. Give me a year.\n[46:52] NOOR: Shelf Life is back Monday. Bring us your broken cookbooks.\n[47:30] END OF RECORDING\n"
+      },
+      {
+        "path": "episodes.json",
+        "content": "{\n  \"show\": \"Shelf Life\",\n  \"cadence\": \"weekly — records Thursday, publishes Monday\",\n  \"targetMinutes\": 45,\n  \"episodes\": [\n    {\n      \"number\": 10,\n      \"title\": \"The Library Cart Economy\",\n      \"publishedAt\": \"2026-06-29\"\n    },\n    {\n      \"number\": 11,\n      \"title\": \"Why Paperbacks Survive\",\n      \"publishedAt\": \"2026-07-06\"\n    },\n    {\n      \"number\": 12,\n      \"title\": \"Interview: The Last Bookbinder\",\n      \"publishedAt\": \"2026-07-13\",\n      \"guests\": [\"Marta Velde\", \"Daan Pols\"]\n    }\n  ]\n}\n"
+      }
+    ],
+    "worker": {
+      "name": "Sanne",
+      "role": "Copywriter"
+    },
+    "craftbookParams": {
+      "workPath": "tasks/eval"
+    }
+  },
+  "mocks": [],
+  "success": {
+    "summary": "tasks/eval/report.md is publishable shownotes — summary, timestamped chapters, links, pull quotes — and every timestamp in it exists in the seeded transcript (no fabricated chapters).",
+    "deliverables": [
+      {
+        "path": "tasks/eval/report.md",
+        "kind": "markdown-report",
+        "minBytes": 1500,
+        "checks": [
+          {
+            "kind": "contains",
+            "file": "tasks/eval/report.md",
+            "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+            "flags": "i"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/report.md",
+            "pattern": "\\d{1,2}:\\d{2}",
+            "label": "timestamped chapters"
+          },
+          {
+            "kind": "contains",
+            "file": "tasks/eval/report.md",
+            "pattern": "chapter",
+            "flags": "i"
+          },
+          {
+            "kind": "valuesSubsetOf",
+            "file": "tasks/eval/report.md",
+            "sourceFiles": [
+              "recordings/*.txt"
+            ],
+            "pattern": "(\\d{1,2}:\\d{2})",
+            "minMatches": 4,
+            "label": "every timestamp traces to the transcript"
+          }
+        ]
+      }
+    ]
+  },
+  "rubric": {
+    "artifact": {
+      "path": "tasks/eval/report.md",
+      "kind": "markdown"
+    },
+    "axes": [
+      {
+        "name": "fidelity",
+        "description": "Chapters, links, names, and quotes come from the transcript — nothing invented, names spelled as recorded."
+      },
+      {
+        "name": "chapter quality",
+        "description": "Chapter breaks land where the conversation actually turns, with titles that tell a listener what they will hear."
+      },
+      {
+        "name": "scannability",
+        "description": "A listener can skim the summary, chapters, and links in under a minute and decide to hit play."
+      },
+      {
+        "name": "tone",
+        "description": "The summary reads like the show's voice, not a form letter."
+      }
+    ]
+  },
+  "qualityFocus": [
+    "timestamp fidelity",
+    "link capture",
+    "chapter craft"
+  ]
+}

package/data/craftbook-templates/tr/transcribe-audio/versions/1.0.2/craftbook.json

@@ -0,0 +1,119 @@
+{
+  "id": "transcribe-audio",
+  "name": "Transcribe Audio or Video",
+  "description": "Convert an audio or video recording into an accurate, readable transcript using speech-to-text, with speaker labels and timestamps. Scopes the output format, speaker-labeling, and timestamp granularity FIRST so the transcript is usable downstream (search, subtitles, minutes), then transcribes the full recording end-to-end, then verifies coverage against the recording's duration and checks for dropped segments. The scope-first ordering matters because deciding timestamp cadence and speaker handling up front is what separates a clean, searchable transcript from a wall of unattributed text.\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. Scope the transcript (planner) — format, speaker labels, timestamp cadence, glossary → gated on artifact `{{workPath}}/scope.md` (markdown-notes)\n2. Transcribe the recording (developer) — run STT over the full file, label speakers, timestamp → gated on `transcript.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": [
+    "transcribe this audio",
+    "transcribe a video",
+    "speech to text",
+    "get a transcript",
+    "convert recording to text"
+  ],
+  "steps": [
+    {
+      "id": "scope",
+      "name": "Scope the transcript",
+      "description": "format, speaker labels, timestamp cadence, glossary",
+      "prompt": "Define what a good transcript looks like BEFORE transcribing. Step 1: record the source file (path, format, duration in seconds). Step 2: pick the output format (plain markdown, or timestamped blocks like `[00:01:23] Speaker 1: ...`) and the timestamp cadence (per-utterance, every N seconds, or per-paragraph). Step 3: decide speaker handling (diarize into Speaker 1/2…, or single-speaker) and how to label them. Step 4: build a small glossary of names/terms/acronyms likely in the audio so they transcribe correctly. Step 5: decide cleanup level (verbatim with ums, or lightly edited for readability). Write an acceptance-criteria checklist (transcript spans the full duration with a final timestamp near the end, every block is timestamped, speakers are labeled consistently, glossary terms spelled correctly, output parses as the chosen format) and decisions to `{{workPath}}/scope.md` via write_task_note AND to 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": "transcribe"
+    },
+    {
+      "id": "transcribe",
+      "name": "Transcribe the recording",
+      "description": "run STT over the full file, label speakers, timestamp",
+      "prompt": "Produce the transcript to the locked format. Step 1: run the speech-to-text capability over the WHOLE file (chunk long files on silence boundaries and stitch, keeping running timestamps so they stay monotonic across chunks). Step 2: apply speaker labels and the chosen timestamp cadence. Step 3: apply the glossary — correct names/terms the recognizer got wrong. Step 4: apply the chosen cleanup level. Step 5: write the result to `transcript.md` in the locked format and confirm it parses. write_task_note the transcript path, its final timestamp, and the recording duration so coverage is checkable. On a loop-back, fix only the flagged gaps (missing tail, mislabeled speakers, glossary misspellings).",
+      "suggestedRole": "developer",
+      "advanceWhen": {
+        "file": "transcript.md",
+        "minBytes": 1,
+        "sniff": "nonempty"
+      },
+      "gate": {
+        "at": "completion",
+        "checks": [
+          {
+            "kind": "minBytes",
+            "file": "transcript.md",
+            "bytes": 500
+          }
+        ],
+        "scripts": [
+          {
+            "name": "checkContains",
+            "scope": "standard",
+            "inputs": {
+              "file": "transcript.md",
+              "pattern": "(?:^|\\n)#{1,3}\\s+\\S",
+              "flags": "i"
+            }
+          }
+        ],
+        "onReject": "transcribe",
+        "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": "Check accuracy and coverage. Step 1: confirm the LAST timestamp is within a small margin of the recording's duration (no dropped tail) — PASS/FAIL coverage. Step 2: confirm every block is timestamped and speakers are labeled consistently throughout. Step 3: spot-check 3 timestamps against the audio (if an audio capability exists) — does the text match what is said there? Step 4: confirm glossary terms/names are spelled correctly. Step 5: confirm the file parses as the chosen format. 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: \"transcribe\" })` 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": "transcript.md"
+        }
+      ],
+      "next": "transcribe"
+    },
+    {
+      "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"
+}