@ketecode/loom 0.1.0 → 0.2.0

package/skills/slide-decks/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: slide-decks
+description: Builds presentation decks end to end - a storyline of one idea per slide with action titles, then layouts, charts and speaker notes - as reveal.js or hand-written HTML/CSS slides, or as PowerPoint files generated with python-pptx or pandoc, edited from an existing .pptx or brand template, and exported to PDF with reveal.js print-pdf, decktape or LibreOffice. Use when someone needs a talk, team update, conference or training deck made, an outline turned into slides, an existing deck converted between HTML and PowerPoint, or slides exported to a shareable PDF.
+license: MIT
+compatibility: Any Agent Skills host. HTML decks need a browser and a local static server; PowerPoint output needs Python with python-pptx or pandoc; PDF export uses Chrome or Chromium, decktape (Node) or LibreOffice.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Slide decks
+
+A deck is an argument the audience follows one step at a time. Get the storyline right in text first, then make each slide carry exactly one point, then pick the format. Most bad decks are bad outlines with nice templates.
+
+For fundraising decks, use `investor-materials` for the content and this skill for the build. For long documents, use `technical-writing`.
+
+## 0. Brief
+
+Get these before writing anything; **ask** for what is missing:
+
+1. **Audience** and what they already know.
+2. **The one thing** they should believe or do afterwards.
+3. **Setting**: presented live, sent to read alone, or both. A sent deck needs fuller sentences; a live one needs fewer words and real speaker notes.
+4. **Length**: minutes or slide count. Roughly one slide per 1-2 minutes for a talk.
+5. **Format**: HTML (reveal.js or plain), PowerPoint (`.pptx`), or "whatever, plus PDF". Check for a required brand template or an existing deck to follow.
+6. **Source material**: data, docs, screenshots. Do not invent numbers, quotes or logos; mark gaps as `[TODO: figure]`.
+
+## 1. Storyline first
+
+Write the outline as action titles, one per slide, before any layout. Read only the titles in order: they should tell the whole story.
+
+```
+1. Checkout failures cost us 4% of orders last quarter            (situation)
+2. 70% of failures come from one payment provider timeout          (complication)
+3. Retrying with an idempotency key recovers most of them         (resolution)
+4. A two-week fix, no new vendor                                   (plan)
+5. Decision needed: approve the sprint by Friday                   (ask)
+```
+
+Rules:
+
+- **Action titles**: a full sentence stating the point ("Churn halved after onboarding change"), not a topic label ("Churn").
+- **One idea per slide.** If a slide needs "and" in its title, split it.
+- Structure options: situation-complication-resolution for decisions; problem-solution-demo-next steps for product talks; a story arc for keynotes. Agenda slides only for talks over ~20 minutes.
+- Put the answer early for executive audiences; build up for teaching.
+- End on the ask or the one takeaway, not "Questions?".
+
+Show the outline to the user and **get agreement before building** if the deck is longer than ~8 slides.
+
+## 2. Slide rules
+
+- Body text at least 24pt equivalent on a 16:9 canvas; no more than ~30 words on a presented slide. Detail goes in speaker notes or an appendix.
+- One focal element per slide: a chart, an image, a big number, a short list (max 3-5 items) or a diagram.
+- Charts: one message per chart, stated in the title; label lines directly instead of a legend; remove gridlines and 3D; highlight the one bar that matters.
+- Consistent grid, margins and type scale across slides; use the template's layouts, never ad-hoc text boxes when a placeholder exists.
+- Contrast at least 4.5:1 for text; do not rely on colour alone; add alt text to images in PowerPoint and `alt` in HTML.
+- Speaker notes on every presented slide: what to say, in 2-5 sentences, plus the transition to the next slide.
+
+Layout patterns and a slide-type cheat sheet are in `references/layouts.md`.
+
+## 3. Build: pick the format
+
+| Want | Use | Reference |
+|---|---|---|
+| Web-native, code samples, live demos, versioned in git | reveal.js | `references/html-decks.md` |
+| A few slides, full design control, no dependency | plain HTML/CSS, one `<section>` per slide, print CSS for PDF | `references/html-decks.md` |
+| Recipient edits in PowerPoint / Keynote / Google Slides | `.pptx` with python-pptx or pandoc | `references/pptx.md` |
+| Must match a corporate template | open the template `.pptx` with python-pptx and fill its layouts | `references/pptx.md` |
+| Text outline to editable deck fast | pandoc Markdown to `.pptx` with `--reference-doc` | `references/pptx.md` |
+
+Steps for any format:
+
+1. Create the deck from the outline: titles first, then content, then notes.
+2. Render it and look at every slide (screenshots or the PDF). Check for overflowing text, orphaned bullets, low-contrast text and images that failed to load.
+3. Fix, re-render, look again.
+
+## 4. Converting an existing deck
+
+- **pptx to HTML**: extract text, notes and images with python-pptx (walk `slide.shapes`, `shape.has_text_frame`, `slide.notes_slide`), then rebuild with the HTML structure; do not try to reproduce absolute positions.
+- **HTML to pptx**: map each slide to a layout (title, title+content, two content, picture), put text in placeholders and notes in the notes pane. Charts become images unless the user needs editable charts.
+- Expect to lose animations and custom fonts. List what did not convert.
+
+## 5. Export to PDF
+
+- reveal.js: open with `?print-pdf`, print to PDF in Chrome or Chromium (landscape, no margins, background graphics on), or run decktape headless. Details in `references/html-decks.md`.
+- `.pptx`: `soffice --headless --convert-to pdf deck.pptx` (LibreOffice), then check fonts were embedded or substituted acceptably.
+- Open the PDF and check every page: page count equals slide count (fragments can multiply pages), nothing cut off, notes included only if asked.
+
+## Never
+
+- Never fabricate data, quotes, customer logos or screenshots. Placeholders are fine and must be visible.
+- Never paste paragraphs from a document onto a slide; rewrite as the point plus notes.
+- Never use a company's brand template, logo or fonts for a deck that is not for that company.
+- Never hand over a deck you have not rendered and looked at.
+
+## Report back
+
+```
+## Deck: <title>
+Format: <reveal.js | HTML | pptx> + <PDF?>   Slides: <n> (+ <n> appendix)
+Files: <paths>
+Storyline: <the action titles, numbered>
+Open items: <[TODO]s, missing data, unverified claims>
+Checked: <rendered and reviewed every slide: yes/no; issues fixed>
+```

package/skills/slide-decks/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Turn these meeting notes into a 10-slide reveal.js presentation with speaker notes",
+    "Make a PowerPoint deck from our corporate template.pptx for the quarterly engineering review",
+    "I have a 45 minute conference talk on Postgres indexing, help me structure the slides so each one makes one point",
+    "Convert this HTML slide deck into an editable .pptx my manager can open",
+    "Export my reveal.js slides to a PDF without every fragment becoming its own page",
+    "Generate a training deck with python-pptx that pulls the charts from our CSV results"
+  ],
+  "should_not_trigger": [
+    "Outline our seed round pitch deck and the metrics investors will expect",
+    "Write a README and getting-started guide for our CLI",
+    "Make a 20-second animated product video from React components",
+    "Extract the tables from this PDF invoice into a spreadsheet",
+    "Write the monthly progress update email to our investors",
+    "Pick a type scale and colour tokens for our web app's settings screens"
+  ]
+}

package/skills/slide-decks/references/html-decks.md

@@ -0,0 +1,86 @@
+# HTML decks
+
+## reveal.js
+
+Install from npm (`npm i reveal.js`) or load from a CDN with a pinned version. Check the current major on revealjs.com before pinning.
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Checkout reliability</title>
+  <link rel="stylesheet" href="node_modules/reveal.js/dist/reveal.css">
+  <link rel="stylesheet" href="node_modules/reveal.js/dist/theme/white.css">
+  <link rel="stylesheet" href="deck.css">
+</head>
+<body>
+  <div class="reveal"><div class="slides">
+    <section>
+      <h1>Checkout failures cost us 4% of orders</h1>
+      <p>Q3 review, Payments team</p>
+      <aside class="notes">Open with the cost, then say we found one main cause.</aside>
+    </section>
+    <section data-auto-animate>
+      <h2>70% come from one provider timeout</h2>
+      <ul>
+        <li class="fragment">Timeouts after 10s</li>
+        <li class="fragment">No retry on our side</li>
+      </ul>
+    </section>
+  </div></div>
+  <script src="node_modules/reveal.js/dist/reveal.js"></script>
+  <script src="node_modules/reveal.js/dist/plugin/notes.js"></script>
+  <script src="node_modules/reveal.js/dist/plugin/highlight.js"></script>
+  <script>
+    Reveal.initialize({ hash: true, plugins: [RevealNotes, RevealHighlight] });
+  </script>
+</body>
+</html>
+```
+
+These are the paths the current revealjs.com plugin docs give (`dist/plugin/*.js`, with `.mjs` ES modules alongside). Older 4.x packages used `plugin/notes/notes.js` and `plugin/highlight/highlight.js`; check the installed package's folders.
+
+Key features:
+
+- Speaker notes: `<aside class="notes">` inside a `<section>`, or `data-notes="..."`. Press `S` for the speaker view; it needs the deck served over HTTP (`npx serve .` or `python3 -m http.server`), not opened from `file://`.
+- Vertical slides: nest `<section>` inside `<section>`; use for optional depth, not the main path.
+- Fragments: `class="fragment"` reveals items step by step. Use sparingly.
+- Auto-animate: `data-auto-animate` on consecutive slides animates matching elements.
+- Code: `<pre><code data-line-numbers="3-5|8" class="language-js">` with the highlight plugin steps through highlighted lines.
+- Size: default canvas 960x700, scaled to fit. For 16:9 set `width: 1280, height: 720` (or 1920x1080) in `Reveal.initialize`.
+- Markdown slides: the markdown plugin with `<section data-markdown>`, `---` between slides, `Note:` for notes.
+- Pandoc can also write reveal.js: `pandoc -s -t revealjs slides.md -o slides.html`.
+
+## Plain HTML/CSS deck
+
+For a handful of slides with no dependency:
+
+```html
+<main class="deck">
+  <section class="slide"><h1>...</h1></section>
+  <section class="slide"><h2>...</h2></section>
+</main>
+```
+
+```css
+.slide { width: 100vw; height: 100vh; display: grid; place-content: center;
+         padding: 6vh 7vw; box-sizing: border-box; scroll-snap-align: start; }
+.deck { height: 100vh; overflow-y: auto; scroll-snap-type: y mandatory; }
+@page { size: 1920px 1080px; margin: 0; }
+@media print {
+  .deck { height: auto; overflow: visible; }
+  .slide { width: 1920px; height: 1080px; break-after: page; }
+}
+```
+
+Add arrow-key navigation with a few lines of script (`scrollIntoView` on the next `.slide`) if needed. Notes can live in `<aside class="notes" hidden>` and be printed separately.
+
+## PDF export
+
+- reveal.js in the browser: open `http://localhost:8000/?print-pdf`, print, destination Save as PDF, landscape, margins None, background graphics on. Chrome or Chromium only.
+  - `showNotes: true` (overlay) or `showNotes: 'separate-page'` prints notes.
+  - `pdfSeparateFragments: false` prints each slide once with all fragments shown.
+  - `pdfMaxPagesPerSlide: 1` stops tall slides spilling onto extra pages.
+- Headless: `npx decktape reveal http://localhost:8000 slides.pdf` (decktape also supports other HTML frameworks and a generic mode; add `--size 1920x1080` to set the page size).
+- Plain HTML: headless Chrome, e.g. `chrome --headless --print-to-pdf=slides.pdf http://localhost:8000/` (binary name varies: `google-chrome`, `chromium`, or the full app path on macOS), using the print CSS above.

package/skills/slide-decks/references/layouts.md

@@ -0,0 +1,45 @@
+# Slide types and layouts
+
+16:9 canvas. Work on a 12-column grid with generous outer margins (about 5-7% of width).
+
+| Slide type | Layout | Content rule |
+|---|---|---|
+| Title | Centered or left-aligned title, subtitle, presenter and date | Title states the talk's promise, not just the topic |
+| Section divider | Large section title, optional progress marker | Use only in long decks |
+| Big number | One number very large, one line of context below | "4.1% of orders failed" + source |
+| Statement | One sentence, large, left-aligned | The takeaway of a section |
+| Chart | Action title, chart filling most of the slide, source line | One highlighted series |
+| Comparison | Two columns, same structure each side | Before/after, option A/B |
+| Image + text | Image 50-60% width, 1-3 short lines | Screenshot with callouts beats raw screenshot |
+| Process | 3-5 steps left to right or top to bottom | Verbs, numbered |
+| Code | Monospace, 12-20 lines max, highlight the lines that matter | Reveal.js `data-line-numbers="3-5"` |
+| Quote | Quote, name, role | Only real, attributed quotes |
+| Ask / next steps | The decision or action, owner, date | Last content slide |
+| Appendix | Dense tables, methodology | Not presented; for readers |
+
+## Type sizes (presented, 1920x1080 or 13.33x7.5 in)
+
+| Element | Size |
+|---|---|
+| Action title | 32-44pt |
+| Body | 24-28pt |
+| Labels, sources | 14-18pt (sources only; never body text this small) |
+| Big number | 96-160pt |
+
+For a read-alone deck, body can drop to 16-20pt with more words, but keep one idea per slide.
+
+## Charts
+
+- Bar for comparing categories, line for change over time, scatter for relationships; avoid pie charts with more than 3 slices.
+- Start bar axes at zero.
+- Grey for everything, accent colour for the point the title makes.
+- Write the takeaway in the title, and the source and date in a small line underneath.
+
+## Speaker notes template
+
+```
+Point: <the one thing this slide says>
+Say: <2-5 sentences, conversational>
+Evidence: <where the number comes from>
+Transition: <the sentence that leads to the next slide>
+```

package/skills/slide-decks/references/pptx.md

@@ -0,0 +1,87 @@
+# PowerPoint decks
+
+## pandoc: Markdown to .pptx
+
+```markdown
+---
+title: Checkout reliability
+author: Payments team
+---
+
+# Checkout failures cost us 4% of orders
+
+- 1,240 failed orders in Q3
+- Mostly at the payment step
+
+::: notes
+Open with the cost, then say we found one main cause.
+:::
+
+# 70% come from one provider timeout
+
+![Failures by cause](failures.png)
+```
+
+```bash
+pandoc slides.md -o slides.pptx --slide-level=1 --reference-doc=template.pptx
+```
+
+- `--slide-level` picks which heading level starts a slide (here `#`).
+- `--reference-doc` takes a template whose layouts are named Title Slide, Title and Content, Section Header, Two Content, Comparison, Content with Caption and Blank; missing layouts fall back to pandoc's default with a warning.
+- Get pandoc's default template to edit: `pandoc -o custom-reference.pptx --print-default-data-file reference.pptx`.
+- Two columns: `:::::: {.columns}` with two `::: {.column}` blocks.
+- Speaker notes: `::: notes` blocks.
+
+## python-pptx: generate or fill a template
+
+`pip install python-pptx`.
+
+```python
+from pptx import Presentation
+from pptx.util import Inches, Pt
+
+prs = Presentation("template.pptx")          # or Presentation() for a blank 4:3 default
+# Blank default is 4:3; for 16:9:
+# prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)
+
+for i, layout in enumerate(prs.slide_layouts):          # find layout names first
+    print(i, layout.name, [p.placeholder_format.idx for p in layout.placeholders])
+
+slide = prs.slides.add_slide(prs.slide_layouts[1])      # Title and Content in most templates
+slide.shapes.title.text = "70% of failures come from one provider timeout"
+body = slide.placeholders[1].text_frame
+body.text = "Timeouts after 10 seconds"
+p = body.add_paragraph(); p.text = "No retry on our side"; p.level = 0
+slide.notes_slide.notes_text_frame.text = "Explain the timeout, then move to the fix."
+
+pic = slide.shapes.add_picture("chart.png", Inches(1), Inches(2), width=Inches(8))
+# alt text: python-pptx has no direct API; set the descr attribute on the cNvPr element
+pic._element.nvPicPr.cNvPr.set("descr", "Bar chart: provider timeouts are 70% of failures")
+
+prs.save("deck.pptx")
+```
+
+Rules:
+
+- Fill **placeholders** from the template's layouts; do not add free text boxes over them, or the template's styling and accessibility reading order break.
+- Print the layouts and placeholder indexes first (loop above); indexes differ between templates.
+- Native charts: `slide.shapes.add_chart(XL_CHART_TYPE.BAR_CLUSTERED, x, y, cx, cy, chart_data)` with `CategoryChartData` keeps them editable; use an image only if the user does not need to edit.
+- Fonts render with whatever is installed on the viewer's machine; stick to the template's fonts.
+- Deleting slides and reordering need XML manipulation in python-pptx; for heavy edits of an existing deck, consider asking the user to do structural changes in PowerPoint and automate only the content.
+
+## Reading an existing .pptx
+
+```python
+for n, slide in enumerate(prs.slides, 1):
+    texts = [s.text_frame.text for s in slide.shapes if s.has_text_frame]
+    notes = slide.notes_slide.notes_text_frame.text if slide.has_notes_slide else ""
+    print(n, slide.slide_layout.name, texts, notes)
+```
+
+## PDF from .pptx
+
+```bash
+soffice --headless --convert-to pdf --outdir out deck.pptx
+```
+
+LibreOffice substitutes missing fonts; check the PDF. For pixel-exact output, export from PowerPoint or Keynote itself.

package/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: subagent-driven-development
+description: Carries out a written implementation plan one task at a time, handing each task to a fresh implementer subagent with the full task text and context pasted in, answering its questions before work begins, and requiring a self-review and report. Every task then passes a spec-compliance check by the spec-reviewer agent and only afterwards a code-quality check by the code-reviewer agent, looping fix and re-review until both pass, with a progress ledger and a whole-branch review at the end. Falls back to inline execution on hosts without subagents. Use when a plan file exists and the user wants it executed task by task with independent review gates between tasks.
+license: MIT
+compatibility: Best on hosts with subagents; has an inline fallback. Needs git and the project's test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Subagent-driven development
+
+You are the controller. You don't write the code; you brief a fresh implementer for each task, gate its work through two reviews, and keep the record. Fresh context per task keeps each worker focused and keeps your own context for coordination.
+
+Input: a plan with self-contained tasks, normally written with `implementation-plans` (or by the `planner` agent). No plan yet: write one first. For independent jobs that can truly run at the same time, use `parallel-agent-orchestration` instead; for unattended long runs, `autonomous-loops`.
+
+## 0. Set up
+
+1. Read the whole plan and its source design or spec once. Note project-wide constraints (versions, naming, limits) that every task must respect.
+2. Raise problems before starting: tasks that contradict the code, missing dependencies, tasks too big to review (split them). **Stop and ask the user** about anything that would change scope.
+3. Work on a feature branch or separate worktree, never on `main` without explicit consent. Record the base commit SHA.
+4. Run the test suite once. If it's red, report and ask before going on.
+5. Create a ledger (a short Markdown file outside the tracked tree, or in your notes):
+
+```
+| # | Task | Status | Commit | Spec review | Quality review | Notes |
+|---|------|--------|--------|-------------|----------------|-------|
+| 1 | ...  | todo   |        |             |                |       |
+```
+
+## 1. Per task: brief the implementer
+
+Start a **fresh** subagent for the task: the `task-implementer` agent when it is installed, otherwise a general-purpose subagent with edit and shell tools. Build the brief from `references/implementer-brief.md` (the `task-implementer` agent already knows the working rules and report format, so for it the task text and context are enough):
+
+- Paste the **full task text** from the plan. Never tell the implementer to go read the plan file; it would read other tasks and drift.
+- Add the context it can't infer: where the task fits, the interfaces earlier tasks produced (names and signatures), the global constraints, the working directory and branch, the test command.
+- Tell it to ask questions before starting, to follow the task's test-first steps, to commit, to self-review its diff, and to report in the fixed format with a status.
+
+If it comes back with questions, answer them (from the plan, the design or the code; ask the user only when none of those decide it) and send it on. Don't let it start on assumptions.
+
+## 2. Handle the report
+
+| Status | Action |
+|---|---|
+| `DONE` | Go to the reviews. |
+| `DONE_WITH_CONCERNS` | Read the concerns. Correctness or scope worries: resolve them before review. Observations ("this file is getting long"): note them in the ledger and review. |
+| `NEEDS_CONTEXT` | Supply the missing context and resume the same implementer, or re-brief a fresh one. |
+| `BLOCKED` | Decide: more context, split the task, or a more capable model. If the plan itself is wrong, **stop and ask the user**. Never re-send the same brief unchanged. |
+
+## 3. Review gate 1: spec compliance
+
+Run the `spec-reviewer` agent with the task text, the implementer's report, and the commit range (`<sha before task>..<sha after>`). Brief template in `references/reviewer-briefs.md`. It reads the actual code, not the report, and returns PASS or a list of gaps (missing, partial, extra, misread).
+
+On gaps: send the list back to the implementer (same one if it's still available, otherwise a fresh one with the task text plus the gap list), then re-run the spec review on the new range. Repeat until PASS. Extra, unrequested work counts as a gap: have it removed.
+
+## 4. Review gate 2: code quality
+
+Only after spec PASS. Run the `code-reviewer` agent (or the language reviewer, such as `typescript-reviewer` or `python-reviewer`) on the same range. Fix findings rated critical or high, and medium ones that are in the task's files; log the rest in the ledger as follow-ups. Re-review after fixes. If a quality fix changes behaviour, run the spec review again.
+
+Running quality before spec wastes effort polishing code that may be wrong or unwanted, so keep the order.
+
+## 5. Record and continue
+
+Mark the task done in the ledger with its commit and both review results, tick its box in the plan, and move to the next task. Continue without pausing for the user unless:
+
+- a decision would change scope, a public API, data or security,
+- an action is irreversible or reaches outside the repository (deploys, migrations on shared databases, pushing),
+- the same task has failed review three times, or
+- the user asked for checkpoints.
+
+## 6. Finish
+
+1. Run the full check set (`verification-loop`).
+2. Run one whole-branch review on `<base>..HEAD`: `code-reviewer` for cross-task problems (duplicated helpers, inconsistent names, dead code), and `spec-reviewer` against the whole design for anything no single task covered.
+3. Fix what they find with the same loop.
+4. Report, then offer the branch options (open a pull request, merge locally, keep). Don't push or merge without the user asking.
+
+## Inline fallback (host without subagents)
+
+Do each role yourself, in sequence, and keep the roles separate:
+
+1. Implement the task from its text alone, following its steps, and commit.
+2. Spec pass: re-read the task text line by line, then read the diff (`git diff <before>..<after>`), and list each requirement with the file:line that meets it. Anything without a line is a gap.
+3. Quality pass: read the diff again for correctness, error paths, naming and tests, as the `code-reviewer` checklist would.
+4. Fix and repeat. Say in the final report that reviews were done inline, not independently.
+
+## Never
+
+- Never run two implementers at the same time on tasks that touch the same files. Run independent tasks in parallel only if their file sets are disjoint and each has its own worktree.
+- Never skip either review, or accept "close enough" on the spec review.
+- Never trust an implementer's report as evidence; reviewers read the code.
+- Never let implementers or reviewers start their own subagents.
+- Never fix a task's code yourself mid-loop without saying so in the ledger; the reviewers must see the final diff.
+
+## Final report
+
+```
+## Executed: <plan path>
+Branch: <name>, base <sha>, head <sha>
+Tasks: <done>/<total>
+| # | Task | Commit | Spec | Quality | Review rounds |
+Branch review: <findings fixed / open>
+Verification: <commands> -> <results>
+Rulings made: <decisions you took without the user, and why>
+Follow-ups: <logged quality items, concerns>
+```

package/skills/subagent-driven-development/evals/behavior.json

@@ -0,0 +1,53 @@
+{
+  "scenarios": [
+    {
+      "name": "tell implementer to read the plan",
+      "prompt": "Execute docs/plans/2026-10-02-coupons.md with subagents. To save time, just tell each implementer 'read the plan and do task N'.",
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Pastes the full task text into each implementer's brief instead of pointing at the plan file",
+        "Adds context the implementer cannot infer (interfaces from earlier tasks, constraints, branch, test command)",
+        "Runs the spec-reviewer before the code-reviewer for each task",
+        "Mentions keeping a progress ledger"
+      ],
+      "forbid": [
+        "Briefs implementers with only 'read the plan and do task N'",
+        "Skips either review gate"
+      ]
+    },
+    {
+      "name": "skip spec review, implementer says done",
+      "prompt": "The implementer for task 3 reported DONE and all tests are green. Skip the spec review and go straight to code quality, or better, just move on to task 4.",
+      "pressure": [
+        "time"
+      ],
+      "expect": [
+        "Refuses to treat the implementer's report or green tests as evidence",
+        "Runs the spec-reviewer on the task commit range before the code-reviewer",
+        "Loops fixes and re-review until spec PASS before moving to task 4"
+      ],
+      "forbid": [
+        "Moves to task 4 without spec and quality review",
+        "Runs code-quality review before spec review"
+      ]
+    },
+    {
+      "name": "blocked implementer",
+      "prompt": "Task 5's implementer came back BLOCKED: the plan says to call `PricingService.applyCoupon` but that method doesn't exist. Just re-send it the same brief, maybe it'll figure it out.",
+      "pressure": [
+        "exhaustion"
+      ],
+      "expect": [
+        "Does not re-send the same brief unchanged",
+        "Recognises the plan may be wrong and stops to ask the user if so",
+        "Considers supplying more context or splitting the task"
+      ],
+      "forbid": [
+        "Re-sends the identical brief",
+        "Writes applyCoupon itself without noting it in the ledger"
+      ]
+    }
+  ]
+}

package/skills/subagent-driven-development/evals/triggers.json

@@ -0,0 +1,15 @@
+{
+  "should_trigger": [
+    "Execute docs/plans/2025-06-10-export.md using a fresh subagent for each task, with a spec review and then a code review after every one",
+    "Run my implementation plan task by task with separate implementer and reviewer agents, and keep a ledger of progress",
+    "I want each plan task handed to its own subagent and checked against the task text before the next one starts",
+    "Drive this 12-task plan with subagents: brief each implementer with the full task, review it, loop fixes until it passes, then review the whole branch"
+  ],
+  "should_not_trigger": [
+    "Fan out eight agents to migrate every package to ESM simultaneously and merge the results",
+    "Write a plan file for the export feature with exact paths, failing tests and commit messages",
+    "Does commit 9f3e1c2 cover every acceptance criterion in the coupon ticket? Just tell me what's missing",
+    "Loop the agent unattended overnight until the flaky tests are fixed, with a spend cap",
+    "Review the diff on this branch for correctness bugs before I open a pull request"
+  ]
+}

package/skills/subagent-driven-development/references/implementer-brief.md

@@ -0,0 +1,60 @@
+# Implementer brief template
+
+Fill every `<...>` and send the whole text as the subagent's instructions. Paste the task; never point at the plan file.
+
+```
+You are implementing one task of a larger plan: Task <N>, "<title>".
+
+## The task (complete text)
+<paste the task exactly as written in the plan, including files, steps, commands and expected outputs>
+
+## Context
+- Project: <one or two lines on what the system does>
+- Where this fits: <what earlier tasks built, what later tasks will rely on>
+- Interfaces available from earlier tasks: <exact names and signatures>
+- Constraints that apply to every task: <versions, naming, limits, copy rules>
+- Working directory: <path>   Branch: <name>
+- Test command for this task: <command>   Full suite: <command>
+
+## Before you start
+If anything about the requirements, the approach or the dependencies is unclear, reply with your questions now and do not start. Asking costs little; guessing costs a review round.
+
+## How to work
+1. Do exactly what the task says. Nothing extra: no refactors, renames, new options or files outside the task's list.
+2. Follow the task's test-first steps: write the test, run it, confirm it fails for the stated reason, implement, run it again.
+3. While working, run the focused test. Run the full suite once before committing.
+4. Follow the patterns in the surrounding code.
+5. Commit with the message given in the task (or `<type>(<area>): <what>`).
+6. Do all the work yourself. Do not start subagents, and do not ask another agent to review your work; review happens after you report.
+
+## Stop and report instead of pushing on when
+- the task needs a design decision it doesn't make,
+- the code doesn't match what the task assumes (a file, function or API is missing or different),
+- a test fails twice after a fix and you don't know why,
+- finishing would require touching files outside the task.
+
+## Self-review before reporting
+Read your own diff once and check:
+- every requirement in the task is implemented, and nothing else;
+- the tests check behaviour, not mocks, and the output is clean (no stray warnings);
+- names say what things do; no debug output or commented-out code is left.
+Fix what you find, then report.
+
+## Report in exactly this format
+Status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
+Commits: <sha> <message>
+Files changed: <path: what>
+Tests: <command> -> <pass/fail counts>; red step seen: <yes, with the failure message | no, why>
+Self-review: <what you checked, what you fixed>
+Concerns or questions: <or "none">
+```
+
+## Re-brief after review findings
+
+When a reviewer returns gaps or findings, send the same implementer (or a fresh one, with the task text pasted again):
+
+```
+Review of Task <N> found the following. Fix exactly these, nothing else, then commit and report in the same format.
+<paste the reviewer's list verbatim, with file:line>
+Commit range reviewed: <base>..<head>
+```

package/skills/subagent-driven-development/references/reviewer-briefs.md

@@ -0,0 +1,52 @@
+# Reviewer brief templates
+
+Reviewers are read-only. Give them the requirement text and the commit range; never ask them to fix anything.
+
+## Spec compliance (send to the `spec-reviewer` agent)
+
+```
+Check whether this implementation does what its task asked: no more, no less.
+
+## Requirement (complete text)
+<paste the task text from the plan>
+
+## Constraints that apply to every task
+<versions, naming, limits, copy rules from the design>
+
+## What the implementer says it did (unverified)
+<paste the implementer's report>
+
+## Change to review
+Commit range: <base sha>..<head sha>   Working directory: <path>
+Read the diff and the changed files. Treat the report as claims to check, not evidence.
+
+Return PASS, or a ranked list of gaps (missing, partial, extra, misread), each with file:line evidence.
+Do not comment on style or code quality.
+```
+
+If the `spec-reviewer` agent isn't installed, send the same text to a general read-only subagent, adding: "Do not edit files. Do not run commands that change the working tree, index or branches."
+
+## Code quality (send to the `code-reviewer` agent, or the language reviewer)
+
+Only after the spec review returns PASS.
+
+```
+Review this change for correctness and quality. The spec check has already passed; do not re-litigate scope.
+
+Task: <title> (one line on what it does)
+Commit range: <base sha>..<head sha>   Working directory: <path>
+Test command: <command>
+
+Focus: correctness bugs, unhandled error paths, broken callers, tests that don't prove the behaviour, names and structure that will confuse the next reader.
+Return findings ranked by severity (critical, high, medium, low) with file:line and the smallest fix. Do not edit files.
+```
+
+## Whole-branch review (end of the plan)
+
+```
+Review the whole branch <base sha>..HEAD, built task by task from <plan path> and <design path>.
+Look for problems no single-task review could see: duplicated helpers across tasks, inconsistent names or error handling, dead code left by earlier tasks, requirements of the design that no task covered, and integration gaps between components.
+Return findings ranked by severity with file:line. Do not edit files.
+```
+
+Send it to `code-reviewer` for quality, and to `spec-reviewer` with the design doc as the requirement for coverage.