@jesdi/skills 0.0.13 → 0.0.14

package/README.md

@@ -20,6 +20,24 @@ directory.
 npx @jesdi/skills-cli sync
 ```
 
+It looks like this:
+
+```json
+{
+  "schemaVersion": 1,
+  "agents": ["claude", "opencode"],
+  "skills": {
+    "crap-gate": { "version": "1.2.0", "package": "1.4.0" },
+    "backlog":   { "version": "0.3.0", "package": "1.4.0", "agents": ["claude"] }
+  }
+}
+```
+
+The top-level `agents` is the default for every skill; a skill's own `agents`
+overrides it. `install <skill>` inherits the default (the first interactive
+install asks once and stores it), while `install --agent ...` writes a
+per-skill override. In scripts, pass `--agent` or commit the top-level default.
+
 ## Commands
 
 ```
@@ -35,11 +53,12 @@ npx @jesdi/skills-cli uninstall <skill> [--global]
 
 Skills authored by other people are **not** copied into this repo — they keep
 their own authors, upstreams, and licenses. `external-skills.json` records
-which ones are part of the standard setup and where they come from. Install
-them from upstream with the [skills.sh](https://skills.sh/) CLI:
+which ones are part of the standard setup, where they come from, and (under
+`pins`) the upstream commit the box set is taken from. Install them from
+upstream with the [skills.sh](https://skills.sh/) CLI:
 
 ```bash
-npx skills add mattpocock/skills          # grill-me, grill-with-docs, improve-codebase-architecture
+npx skills add mattpocock/skills          # grill-me, grill-with-docs, grilling, improve-codebase-architecture, to-questionnaire, tdd, code-review, codebase-design, diagnosing-bugs, resolving-merge-conflicts
 npx skills add JuliusBrussee/caveman      # caveman suite
 npx skills add vercel-labs/skills         # find-skills
 npx skills add vercel-labs/agent-skills   # vercel-react-best-practices
@@ -49,6 +68,23 @@ npx skills add anthropics/skills          # frontend-design (skip if using the C
 The skills.sh lockfile (`~/.agents/.skill-lock.json`) tracks installed
 versions; `npx skills update` refreshes them.
 
+### Forks (the one exception)
+
+`to-spec`, `to-tickets`, `prototype` and `wizard` are modified copies of the
+mattpocock/skills originals, vendored under `skills/<name>/` with the upstream
+MIT `LICENSE` and a header naming the upstream commit. They keep their upstream
+names on purpose, so **never install the upstream copies of those four names
+alongside them** (`npx skills add mattpocock/skills` installs the whole set —
+deselect those four, or uninstall them afterwards). `external-skills.json`
+lists them under `forks`.
+
+### The box set
+
+`external-skills.json` → `sets.box` names the skills the agent-ops box
+receives: `own` from this package, `external` from the pinned upstream.
+agent-ops vendors that set into its claude-home seed with its own refresh
+command; this repo's job is to publish the set and keep the pins resolvable.
+
 ## Authoring skills
 
 Add `skills/<name>/SKILL.md` (frontmatter `name` must match the directory,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/backlog/SKILL.md

@@ -71,16 +71,19 @@ these labels (`setup` provisions them all) — never invent new ones.
 | `testing` | Test coverage, test infrastructure, flaky tests |
 | `dependencies` | Upgrading or managing third-party dependencies |
 
-**Pipeline — at most one, orthogonal to Type and Area:**
+**Pipeline — orthogonal to Type and Area:**
 
-Whether an issue is ready for an unattended agent to pick up. Leave both off
+Whether an issue is ready for an unattended agent to pick up, and what it
+carries. `auto` and `human-required` are mutually exclusive; leave both off
 when it is genuinely unclear — an unlabelled issue is simply not routed, which
-is the safe default. Dispatchers filter on `auto`; nothing else reads these.
+is the safe default. `spec-ready` may sit alongside `auto`. Dispatchers filter
+on `auto` and read `spec-ready`; nothing else reads these.
 
 | Label | Apply when |
 |-------|-----------|
 | `auto` | Trivial, or close enough to previously automated work — suitable for the unattended agents pipeline |
 | `human-required` | Substantial fog of war remains; needs heavy human interaction before an agent can take it |
+| `spec-ready` | The issue body already carries a settled design (Problem, Solution, Implementation and Testing Decisions), typically written by `to-spec` after a grilling session — the pipeline skips its own interview and reconciles the design against current code |
 
 ## `setup` — create the board once (idempotent)
 
@@ -92,7 +95,7 @@ dir.
 1. Ensure the `project` scope: `gh auth status`; if Projects calls 403, run
    `gh auth refresh -s project`.
 2. Follow `references/graphql.md` → **Setup**: create the Project, link the repo,
-   add the six fields, create the `inbox` label plus the 14 taxonomy labels
+   add the six fields, create the `inbox` label plus the 15 taxonomy labels
    (idempotent — `--force` reconciles color/description on re-runs). On a
    brand-new board the `Area`
    single-select is created with the generic default options
@@ -171,7 +174,9 @@ Reuse the **dedup discipline** from the `file-bug-issue` skill, but take the
 3. Otherwise infer labels from the idea text per the **Label taxonomy** above,
    then create it (see `references/graphql.md` → Capture): `--label inbox` plus
    one `--label` per inferred label, body = the idea as-is (one loose sentence
-   is fine; no required structure).
+   is fine; no required structure). Add `spec-ready` only when the body being
+   filed is a settled design (the `to-spec` skill does this itself); a one-line
+   idea is never spec-ready.
 4. Report the new issue URL and the labels applied. If mid-task, treat as a
    side-quest and return.
 
@@ -182,7 +187,8 @@ Reuse the **dedup discipline** from the `file-bug-issue` skill, but take the
    (skip = leave in inbox). Offer label corrections per the **Label taxonomy**
    above; apply via `gh issue edit N --add-label … --remove-label …`
    (graphql.md → Triage). Labels stay independent of the board `Area` gathered
-   next.
+   next. If the issue carries `spec-ready`, confirm the body really is a
+   settled design with its sections intact; remove the label when it is not.
 3. For a promoted issue, gather `Impact` (1–5), `Effort` (1–5), `Area` (**pick one
    from the options present in `.backlog/project-meta.json`** → `fields.Area.options`),
    and optional blockers.

package/skills/backlog/references/graphql.md

@@ -47,9 +47,10 @@ gh label create security --repo <repo> --description "Vulnerabilities, auth, per
 gh label create performance --repo <repo> --description "Speed, memory, efficiency, scalability" --color f9d0c4 --force
 gh label create testing --repo <repo> --description "Test coverage, test infrastructure, flaky tests" --color 0e8a16 --force
 gh label create dependencies --repo <repo> --description "Upgrading or managing third-party dependencies" --color 0366d6 --force
-# Pipeline labels (at most one per issue; read by dispatchers)
+# Pipeline labels (auto/human-required mutually exclusive; spec-ready may co-exist; read by dispatchers)
 gh label create auto --repo <repo> --description "Suitable for the unattended agents pipeline" --color 5319E7 --force
 gh label create human-required --repo <repo> --description "Needs heavy human interaction before automation" --color B60205 --force
+gh label create spec-ready --repo <repo> --description "Issue body carries a settled design; the pipeline skips its interview" --color 006B75 --force
 
 # 5. Discover IDs to build .backlog/project-meta.json
 gh project view <projectNumber> --owner <owner> --format json   # -> id (projectId)

package/skills/prototype/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/prototype/LOGIC.md

@@ -0,0 +1,67 @@
+# Logic Prototype
+
+A single, self-contained HTML file (a **shareable demo**) that lets anyone drive a state model by clicking buttons. Use this when the question is about **business logic, state transitions, or data shape**: the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.
+
+Because it's one file with nothing to install, you can hand it to a non-developer (a designer, a PM, a domain expert) and let them feel the model for themselves. So it speaks their language, not the code's.
+
+## When this is the right shape
+
+- "I'm not sure if this state machine handles the edge case where X then Y."
+- "Does this data model actually let me represent the case where..."
+- "I want to feel out what the API should look like before writing it."
+- Anything where someone wants to **press buttons and watch state change**.
+
+If the question is "what should this look like," this is the wrong branch. Use [UI.md](UI.md).
+
+## Process
+
+### 1. State the question
+
+Before writing code, write down what state model and what question you're prototyping. One paragraph, at the top of the demo (in a visible intro, not just a comment). A logic prototype that answers the wrong question is pure waste, so make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
+
+### 2. Isolate the logic in a portable module
+
+Put the actual logic (the bit that's answering the question) in a single `<script>` block written as a small, pure module that could be lifted out and dropped into the real codebase later. The page around it is throwaway; this module isn't.
+
+The right shape depends on the question:
+
+- **A pure reducer**: `(state, action) => state`. Good when actions are discrete events and state is a single value.
+- **A state machine**: explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
+- **A small set of pure functions** over a plain data type. Good when there's no implicit current state, just transformations.
+- **A class or module with a clear method surface** when the logic genuinely owns ongoing internal state.
+
+Pick whichever shape best fits the question being asked, *not* whichever is easiest to wire to a page. Keep it pure: no DOM, no `document`, no button handlers reaching inside it. The page calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime: once the question's answered, the validated reducer / machine / function set lifts into the real module on its own.
+
+### 3. Build the shareable HTML file
+
+One file, plain HTML/CSS/JS: no framework, no bundler, no server, everything inline so it opens by double-click and survives being emailed around. Anyone should be able to run it by opening it. Write it to the path the invoking prompt names (see [SKILL.md](SKILL.md) rule 1).
+
+Write it for a non-developer. Every label is in **domain language**, not code: buttons and state read like the business, not the reducer. Explain in plain words what's happening.
+
+Lay it out with a clean hierarchy, top to bottom:
+
+1. **Title and one-line explanation** of what this demo lets you explore (the question from step 1).
+2. **Current state**: the full relevant state, rendered as a readable panel (labelled fields, not a raw JSON dump), re-rendered after every click so the change is visible. Where it helps a non-developer follow, call out what just changed.
+3. **Free-play buttons**: one button per action, always available, so anyone can poke at the model in any order. Each click dispatches its action and re-renders the state.
+4. **Guided walkthroughs**: a set of **scenarios**, one per tab. Each tab holds a short plain-language description of the scenario (the situation it sets up and what to watch for) and underneath it, the ordered **buttons to press** for that scenario. Each step is a real button: clicking it performs that action and moves to the next step. Starting a walkthrough resets to a known initial state so the scenario runs the same way every time.
+
+Choose scenarios that demonstrate the awkward cases, the ones hard to reason about on paper: the happy path, a tricky edge case, an attempt at something that should be illegal.
+
+Keep it beautiful but restrained: clean typography, generous spacing, one accent colour. No animations, no gimmicks: nothing that competes with the state and the buttons. It must read well on a phone: a single column, buttons at least 44px tall.
+
+### 4. Hand it over
+
+Send them the file, or open it for them. They'll click through the walkthroughs and free-play whenever they get to it; the interesting moments are when they say "wait, that shouldn't be possible" or "huh, I assumed X would be different"; those are the bugs in the _idea_, which is the whole point. If they want new actions or a new scenario, add them. Prototypes evolve.
+
+### 5. Capture the answer
+
+Once the prototype has answered its question, capture the verdict the way [SKILL.md](SKILL.md) rule 6 describes (an issue comment when there is an issue). The validated reducer / machine / function set lifts into the real module; the HTML shell is thrown away.
+
+## Anti-patterns
+
+- **Don't add tests.** A prototype that needs tests is no longer a prototype.
+- **Don't wire it to the real database.** Use in-memory state unless the question is specifically about persistence.
+- **Don't generalise.** No "what if we wanted to support X later." The prototype answers one question.
+- **Don't blur the logic and the page together.** If the pure module references the DOM, `document`, or button handlers, it's no longer liftable. Keep the page as a thin shell over a pure module.
+- **Don't reach for a framework, bundler, or server.** One file the recipient double-clicks; a React app or a dev server defeats "shareable".
+- **Don't ship the HTML shell into production.** The page is optimised for being clicked through by hand. The logic module behind it is the bit worth keeping.

package/skills/prototype/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: prototype
+description: Build a throwaway prototype to answer a design question, delivered as one self-contained HTML file. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
+---
+
+<!--
+Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/prototype
+(mattpocock-skills v1.2.3). Copyright (c) 2026 Matt Pocock, MIT — see LICENSE.
+Changes: the UI branch produces one self-contained HTML file holding every
+variation (no routes, no dev server) instead of routes in the running app; the
+file is written to the path the invoking prompt names; the verdict is captured as
+an issue comment instead of a throwaway branch.
+-->
+
+# Prototype
+
+A prototype is **throwaway code that answers a question**. The question decides the shape, but the delivery is always the same: **one self-contained HTML file** that opens by double-click, with no build step and no server. That is what lets a machine with no browser serve it as a file and a person open it on a phone.
+
+## Pick a branch
+
+Identify which question is being answered, using the user's prompt, the surrounding code, or by asking if the user is around:
+
+- **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Free-play buttons plus tabbed guided walkthroughs that push the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.
+- **"What should this look like?"** → [UI.md](UI.md). Several radically different UI variations in one page, switchable inside the page from a floating bottom bar.
+
+The two branches produce very different pages, so getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.
+
+## Rules that apply to both
+
+1. **One file, clearly a prototype.** Everything inline: HTML, CSS, JS, sample data. No framework, no bundler, no server, no network requests. Write it to the path the invoking prompt names; with no path given, put it next to the module or page it prototypes for, named `<name>.prototype.html`, so a casual reader sees it is a prototype and not production.
+2. **Trivial to run.** Opening the file is the whole procedure. No thinking required to start it.
+3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on.
+4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.
+5. **Surface the state.** After every action (logic) or on every variant switch (UI), render the full relevant state so the user can see what changed.
+6. **Capture the verdict where the next reader looks.** When the work has a GitHub issue, post the verdict as a comment on it: the question, the answer (which variant, which model, or "none of these"), and the reason. The next stage is often a fresh session that reads the issue thread and has never seen the file. With no issue, tell the user the verdict and where the file is. Fold any validated decision into the real code (a validated reducer lifts into the real module; a winning layout is rebuilt properly, not copied). The prototype file itself never lands on `main`: leave it uncommitted, or delete it once the verdict is recorded.
+
+```bash
+gh issue comment <number> --repo <owner/repo> --body-file /tmp/verdict.md
+```

package/skills/prototype/UI.md

@@ -0,0 +1,99 @@
+# UI Prototype
+
+Generate **several radically different UI variations** inside one self-contained HTML file, switchable from a floating bottom bar. The user flips between variants in the page, picks one (or steals bits from each), then throws the rest away.
+
+If the question is about logic/state rather than what something looks like, this is the wrong branch. Use [LOGIC.md](LOGIC.md).
+
+## When this is the right shape
+
+- "What should this page look like?"
+- "I want to see a few options for this dashboard before committing."
+- "Try a different layout for the settings screen."
+- Any time the user would otherwise spend a day picking between three vague mockups in their head.
+
+## Why one file and not routes in the app
+
+A prototype mounted in the running application is easier to judge because it sits among the real header, sidebar and data, but it needs a dev server and a browser on the machine that built it. The reviewer here may be looking at a file served from a machine with neither, on a phone. So the page recreates enough of the surrounding app to judge the variant against (a header strip, a sidebar outline, realistic density of sample data) and nothing more. Every variant lives in the same file, so what is being compared is the structure, not the chrome.
+
+## Process
+
+### 1. State the question and pick N
+
+Default to **3 variants**. More than 5 stops being radically different and starts being noise, so cap there.
+
+Write down the plan in one line at the top of the file, visible on the page:
+
+> "Three variants of the settings page. Use the bar at the bottom or ←/→ to switch."
+
+### 2. Generate radically different variants
+
+Draft each variant. Hold each one to:
+
+- The page's purpose and the data it has access to. Inline realistic sample data once and let every variant render it.
+- The project's look: copy its colours, fonts, spacing and border radii into the page's `<style>` so a variant does not look foreign. Do not import the real component library; approximate it in plain CSS.
+- A clear name, e.g. `A (Sidebar layout)`, `B (Cards)`, `C (Single column)`.
+
+Variants must be **structurally different**: different layout, different information hierarchy, different primary affordance, not just different colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.
+
+### 3. Wire them together
+
+Each variant is one `<section data-variant="A">` (B, C, …) in the file. Only the section for the current variant is displayed. The current variant is stored in the URL hash (`#variant=B`) so a specific one can be linked and survives reload:
+
+```html
+<!-- pseudo-code, adapt freely -->
+<section data-variant="A"> … </section>
+<section data-variant="B"> … </section>
+<section data-variant="C"> … </section>
+<div id="switcher"><button data-dir="-1">←</button><span id="label"></span><button data-dir="1">→</button></div>
+<script>
+  const variants = [...document.querySelectorAll('[data-variant]')];
+  const names = { A: 'Sidebar layout', B: 'Cards', C: 'Single column' };
+  function current() { return (location.hash.match(/variant=(\w)/) || [, variants[0].dataset.variant])[1]; }
+  function show(key) {
+    variants.forEach(s => s.hidden = s.dataset.variant !== key);
+    label.textContent = `${key} (${names[key]})`;
+    if (current() !== key) location.hash = `variant=${key}`;
+  }
+  function cycle(dir) {
+    const keys = variants.map(s => s.dataset.variant);
+    show(keys[(keys.indexOf(current()) + dir + keys.length) % keys.length]);
+  }
+  document.querySelectorAll('#switcher button').forEach(b => b.onclick = () => cycle(+b.dataset.dir));
+  addEventListener('keydown', e => {
+    if (e.target.matches('input, textarea, [contenteditable]')) return;
+    if (e.key === 'ArrowLeft') cycle(-1); if (e.key === 'ArrowRight') cycle(1);
+  });
+  addEventListener('hashchange', () => show(current()));
+  show(current());
+</script>
+```
+
+### 4. Build the floating switcher
+
+A small fixed-position bar at the bottom-centre of the screen with three pieces:
+
+- **Left arrow**: cycles to the previous variant (wraps around).
+- **Variant label**: shows the current variant key and its name, e.g. `B (Cards)`.
+- **Right arrow**: cycles forward (wraps around).
+
+Behaviour:
+
+- Clicking an arrow updates the URL hash so the variant is shareable and reload-stable.
+- Keyboard: `←` and `→` arrow keys also cycle. Don't intercept arrow keys when an `<input>`, `<textarea>`, or `[contenteditable]` is focused.
+- Touch: the arrows are at least 44px tall so the bar works on a phone.
+- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
+
+### 5. Hand it over
+
+Say where the file is and list the variant keys with their `#variant=` links. The user will flip through whenever they get to it. The interesting feedback is usually **"I want the header from B with the sidebar from C"**, which is the actual design they want.
+
+### 6. Capture the answer and clean up
+
+Once a variant has won, record the verdict the way [SKILL.md](SKILL.md) rule 6 describes: an issue comment naming the winner and why, and any parts borrowed from the others. Rebuild the winner properly in the real code with the project's real components; nothing is copied out of the prototype file. The file itself never lands on `main`.
+
+## Anti-patterns
+
+- **Variants that differ only in colour or copy.** That's a tweak, not a prototype. Real variants disagree about structure.
+- **Sharing too much markup between variants.** A shared header strip is fine; a shared layout defeats the point. Each variant should be free to throw out the layout.
+- **Loading anything from the network.** No CDN scripts, no web fonts, no images by URL. The file must render from disk with no connection.
+- **Promoting the prototype directly to production.** The variant markup was written under prototype constraints (no components, no tests, no accessibility pass). Rebuild it properly when you fold it in.

package/skills/to-spec/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/to-spec/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: to-spec
+description: "Turn the current conversation into a design spec and write it where the next stage reads it: a GitHub issue body labelled spec-ready (after a grilling session), or a dated design file on the current branch (an unattended spec stage). No interview, just synthesis of what you've already discussed."
+---
+
+<!--
+Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/to-spec
+(mattpocock-skills v1.2.3). Copyright (c) 2026 Matt Pocock, MIT — see LICENSE.
+Changes: publishes to an issue body or a design file instead of an issue tracker;
+seams are stated rather than confirmed when unattended; the document must pass the
+agent-ops mechanical spec check; Testing Decisions must name the seams; the
+`ready-for-agent` label became `spec-ready`; model invocation is allowed.
+-->
+
+This skill takes the current conversation context and codebase understanding and produces a spec. Do NOT interview the user; just synthesize what you already know.
+
+## Destination
+
+Decide where the spec goes before writing it. There are exactly two destinations:
+
+- **Issue body.** Use this when a human settled the design with you interactively (a grilling session) and the unattended pipeline will pick the work up later. Create a GitHub issue in the current repo whose body is the spec, labelled `spec-ready`. If the conversation started from an existing issue, replace that issue's body and add the label instead of creating a new issue. The spec's H1 becomes the issue title and is omitted from the body.
+- **Design file.** Use this when the invoking prompt names a file path, or when you are running unattended on a task branch. Write the spec to that path; with no path given, use `docs/specs/<YYYY-MM-DD>-<slug>-design.md`. Keep the H1 as the first line. Commit it to the current branch with a `docs:` message.
+
+If neither is clear, ask once: "Issue body or design file?". Never publish anywhere else.
+
+## Process
+
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Use the project's domain glossary vocabulary throughout the spec, and respect any ADRs in the area you're touching.
+
+2. Sketch out the seams at which you're going to test the feature. Existing seams should be preferred to new ones. Use the highest seam possible. If new seams are needed, propose them at the highest point you can. The fewer seams across the codebase, the better - the ideal number is one.
+
+   With a human present, check that these seams match their expectations. Unattended, state your choice in the Testing Decisions section instead: a later implement session treats that section as the seams already agreed and cannot stop to ask.
+
+3. Write the spec using the template below, then deliver it to the destination.
+
+## Mechanical requirements
+
+The unattended pipeline rejects a spec that fails a format check, so every spec must have:
+
+- One `# <title>` H1 as the first line (file destination) or as the issue title (issue destination).
+- At least two `## ` sections. Use every section of the template; write "None." rather than dropping one.
+- A **Testing Decisions** section that names each seam explicitly: the module, function, command or endpoint the tests drive through, and whether it exists today or is new.
+
+## Delivery commands
+
+```bash
+# Issue body (new issue). Write the body to a temp file first.
+gh issue create --repo <owner/repo> --title "<H1 text>" --label spec-ready --body-file /tmp/spec.md
+
+# Issue body (existing issue)
+gh issue edit <number> --repo <owner/repo> --body-file /tmp/spec.md --add-label spec-ready
+
+# If the label does not exist yet (the backlog skill's setup normally provisions it)
+gh label create spec-ready --repo <owner/repo> --description "Issue body carries a settled design; the pipeline skips its interview" --color 006B75 --force
+
+# Design file
+git add docs/specs/<date>-<slug>-design.md && git commit -m "docs: spec for <slug>"
+```
+
+Read `<owner/repo>` from `gh repo view --json nameWithOwner -q .nameWithOwner`.
+
+<spec-template>
+
+# <Feature title>
+
+## Problem Statement
+
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+
+The solution to the problem, from the user's perspective.
+
+## User Stories
+
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+
+A list of implementation decisions that were made. This can include:
+
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it within the relevant decision and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.
+
+## Testing Decisions
+
+A list of testing decisions that were made. Include:
+
+- A description of what makes a good test (only test external behavior, not implementation details)
+- **The seams**: every interface the tests drive through, named (module, function, command or endpoint), each marked existing or new. This list is the agreement a later implement session works from.
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+
+A description of the things that are out of scope for this spec.
+
+## Further Notes
+
+Any further notes about the feature.
+
+</spec-template>

package/skills/to-tickets/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/to-tickets/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: to-tickets
+description: Break a spec, plan, or the current conversation into numbered tracer-bullet ticket files under .agent/tickets/, each declaring its blocking edges and acceptance criteria phrased as observable behavior. Use after a spec is approved and before implementation starts.
+---
+
+<!--
+Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/to-tickets
+(mattpocock-skills v1.2.3). Copyright (c) 2026 Matt Pocock, MIT — see LICENSE.
+Changes: tickets always go to `.agent/tickets/<NN>-<slug>.md` (no tracker path);
+numbering is contiguous from 01 in dependency order; acceptance criteria must state
+observable behavior; the approval quiz is skipped when unattended; model
+invocation is allowed.
+-->
+
+# To Tickets
+
+Break a plan, spec, or conversation into a set of **tickets**: tracer-bullet vertical slices, each declaring the tickets that **block** it.
+
+## Process
+
+### 1. Gather context
+
+Work from whatever is already in the conversation context. If the user passes a reference (a spec path, an issue number or URL) as an argument, fetch it and read its full body and comments.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code. Ticket titles and descriptions should use the project's domain glossary vocabulary, and respect ADRs in the area you're touching.
+
+Look for opportunities to prefactor the code to make the implementation easier. "Make the change easy, then make the easy change."
+
+### 3. Draft vertical slices
+
+Break the work into **tracer bullet** tickets.
+
+<vertical-slice-rules>
+
+- Each slice cuts a narrow but COMPLETE path through every layer (schema, API, UI, tests): vertical, NOT a horizontal slice of one layer
+- A completed slice is demoable or verifiable on its own
+- Each slice is sized to fit in a single fresh context window
+- Any prefactoring should be done first
+
+</vertical-slice-rules>
+
+Give each ticket its **blocking edges**: the other tickets that must complete before it can start. A ticket with no blockers can start immediately.
+
+**Wide refactors are the exception to vertical slicing.** A **wide refactor** is one mechanical change (rename a column, retype a shared symbol) whose **blast radius** fans across the whole codebase, so a single edit breaks thousands of call sites at once and no vertical slice can land green. Don't force it into a tracer bullet; sequence it as **expand–contract**. First expand: add the new form beside the old so nothing breaks. Then migrate the call sites over in batches sized by blast radius (per package, per directory), each batch its own ticket blocked by the expand, keeping CI green batch to batch because the old form still exists. Finally contract: delete the old form once no caller remains, in a ticket blocked by every migrate batch. When even the batches can't stay green alone, keep the sequence but let them share an integration branch that all block a final integrate-and-verify ticket; green is promised only there.
+
+### 4. Quiz the user (attended only)
+
+When a human is in the loop, present the proposed breakdown as a numbered list. For each ticket, show:
+
+- **Title**: short descriptive name
+- **Blocked by**: which other tickets (if any) must complete first
+- **What it delivers**: the end-to-end behaviour this ticket makes work
+
+Ask the user:
+
+- Does the granularity feel right? (too coarse / too fine)
+- Are the blocking edges correct: does each ticket only depend on tickets that genuinely gate it?
+- Should any tickets be merged or split further?
+
+Iterate until the user approves the breakdown.
+
+Running unattended (no human to answer), skip this step: the approved spec and the plan stage's own reviewers are the checkpoints. Write the tickets directly.
+
+### 5. Write the ticket files
+
+Write one file per ticket under `.agent/tickets/<NN>-<slug>.md`. `NN` is a two-digit number starting at `01`, assigned in dependency order (blockers first) with no gaps and no duplicates: a reader executes them in numeric order and the sequence must never stop early. Delete any stale files in that directory first so the set is exactly the tickets you drafted. Use the template below: one ticket per file, never a single combined file.
+
+`.agent/` is working state, not source. It is never committed; check it is gitignored before committing anything else.
+
+Work the **frontier**: any ticket whose blockers are all done. For a purely linear chain that means top to bottom.
+
+Do NOT close or modify any parent issue.
+
+<ticket-template>
+
+# <NN>: <Ticket title>
+
+**What to build:** the end-to-end behaviour this ticket makes work, from the user's perspective, not a layer-by-layer implementation list.
+
+**Blocked by:** the numbers/titles of the tickets that gate this one, or "None (can start immediately)".
+
+- [ ] Acceptance criterion 1
+- [ ] Acceptance criterion 2
+
+</ticket-template>
+
+<acceptance-criteria-rule>
+
+Every acceptance criterion states **observable behavior**: something a reviewer can check by running the product, a command, or a test, without reading the implementation. "Running `make test` passes with the new endpoint covered" and "A user with an expired token sees the login page" are criteria. "Add a `TokenExpiry` class" and "Refactor the auth module" are implementation steps and do not belong here.
+
+</acceptance-criteria-rule>
+
+Avoid specific file paths or code snippets: they go stale fast. Exception: if a prototype produced a snippet that encodes a decision more precisely than prose can (state machine, reducer, schema, type shape), inline it and note briefly that it came from a prototype. Trim to the decision-rich parts, not a working demo, just the important bits.

package/skills/wizard/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/wizard/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: wizard
+description: Generate an interactive bash wizard that walks a human through steps only they can perform, and that says for every captured value whether it ends up in CI, on the agent-ops box (1Password), or local only. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself.
+---
+
+<!--
+Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/wizard
+(mattpocock-skills v1.2.3). Copyright (c) 2026 Matt Pocock, MIT — see LICENSE.
+Changes: every captured value declares a destination (ci, box, local); box values
+are recorded with `box_ref` and the closing summary prints the exact 1Password
+reference lines for the box's env template plus the not-live-until-converged
+warning.
+-->
+
+# Wizard
+
+A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (`.env`, GitHub secrets, 1Password for the box), confirms at every stage, and shows how many stages are left. It might configure third-party services, run a one-off migration, or move the project from one state to another.
+
+The delightful UX is already solved by [template.sh](template.sh): stage-by-stage progress, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, box credential references, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point: never hand-edit it.
+
+A wizard is ephemeral by default: built for one run, saved to a scratch or `scripts/` path, deleted when the job's done. Commit it only when the user wants a repeatable setup path that should live in the repo.
+
+## Destinations
+
+Every captured value has exactly one of three destinations, decided in step 1 and visible in the script:
+
+| Destination | Meaning | Helper |
+|---|---|---|
+| `ci` | GitHub Actions reads it | `set_secret` / `set_var` |
+| `box` | The agent-ops box reads it from 1Password through its env template | `box_ref KEY "op://agent-ops/<item>/<FIELD>"` after the human stores it |
+| `local` | Only this machine's `.env` needs it | `write_env` alone |
+
+A value can also be written to `.env` for local development on top of `ci` or `box`. The box is the one that silently fails: a wizard that captures a value the box needs but stops at the laptop finishes green while the box still cannot see it. `box_ref` is what makes that visible.
+
+## Process
+
+### 1. Scope the procedure
+
+Work out every manual step the human must take and every value that gets captured along the way. Read the repo first, don't ask cold:
+
+- For setup: `.env`, `.env.example`, `.env.*`, `README`, `docker-compose*`, framework config, and `.github/workflows/*` (every `secrets.*` / `vars.*` reference is a value the wizard must produce). For anything the box runs, also the env template in agent-ops (`provision/op.env.tpl`): every key there is a `box` value.
+- For a migration or transition: the current state, the target state, and the irreversible actions between them.
+
+Then show the user the ordered list of stages and the values each produces, and confirm: they may add, drop, or reorder.
+
+**Done when:** every stage is named in order, and for each captured value you know (a) where the human gets it, (b) its destination (`ci`, `box` or `local`) plus whether `.env` also gets it, and (c) whether it's secret (hidden entry) or public.
+
+### 2. Map each stage's journey
+
+For each stage, write the precise path a human follows: which URL to open, what to do there, where a value is shown, which variable it fills: e.g. "Dashboard → Developers → API keys → Reveal test key → copy". For a `box` value the journey continues into 1Password: which vault, item and field the human stores it under, which is exactly the `op://` reference the box will read. Where you don't actually know the current UI or the exact command, say so and ask the user or check the docs: never invent steps that may not exist.
+
+**Done when:** every stage traces to concrete instructions a stranger could follow.
+
+### 3. Author the wizard
+
+Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers: `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `box_ref`, `pause`/`confirm`. Set `TOTAL_STAGES` to the number of stages you wrote.
+
+Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every value local development needs, `set_secret` only the values CI actually needs, `box_ref` every value the box needs (after a `step` telling the human where to store it in 1Password and a `pause`), and `confirm` before any irreversible action. Each `stage` clears the screen so only the current step is visible: keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker.
+
+### 4. Verify and hand off
+
+- `bash -n <script>`; run `shellcheck` if available.
+- `chmod +x <script>`.
+- Don't run it end-to-end yourself: it opens browsers and blocks on human input. Trace it statically instead: every value from step 1 is captured and lands where step 1 said, every `set_secret` name exactly matches a `secrets.*` reference in CI, and every `box_ref` key matches a key the box's env template has or will get.
+- Tell the user how to run it, and repeat what the closing summary will say: box values are not live until the env template change is merged in agent-ops and the box has converged. If it's a repeatable setup path, commit it and link it from the README so the next person runs the script instead of asking an AI.

package/skills/wizard/template.sh

@@ -0,0 +1,229 @@
+#!/usr/bin/env bash
+#
+# A wizard walks a human through a manual procedure, step by step.
+# Generated by the /wizard skill.
+#
+# Modified copy of mattpocock/skills skills/engineering/wizard/template.sh
+# @ 3cca18b (v1.2.3). Copyright (c) 2026 Matt Pocock, MIT. Change: box_ref
+# records values the agent-ops box reads from 1Password, and finish prints
+# the template lines that make them visible to it.
+#
+# Everything above the "STAGES" marker is the wizard library: do not hand-edit
+# it. Author the per-step stages below the marker.
+
+set -euo pipefail
+
+# ──────────────────────────────────────────────────────────────────────────
+# Wizard library: delightful, consistent UX, identical across every wizard.
+# ──────────────────────────────────────────────────────────────────────────
+
+if [[ -t 1 ]] && command -v tput >/dev/null 2>&1 && [[ "$(tput colors 2>/dev/null || echo 0)" -ge 8 ]]; then
+  BOLD=$(tput bold); DIM=$(tput dim); RESET=$(tput sgr0)
+  BLUE=$(tput setaf 4); GREEN=$(tput setaf 2); YELLOW=$(tput setaf 3); RED=$(tput setaf 1)
+else
+  BOLD=""; DIM=""; RESET=""; BLUE=""; GREEN=""; YELLOW=""; RED=""
+fi
+
+# Author sets this at the top of the stages section.
+TOTAL_STAGES=0
+
+_STAGE_INDEX=0
+ENV_FILE="${ENV_FILE:-.env}"
+BOX_ENV_TEMPLATE="${BOX_ENV_TEMPLATE:-provision/op.env.tpl}"  # in agent-ops
+WRITTEN_ENV=()    # KEYs written to ENV_FILE this run
+WRITTEN_SECRET=() # secret NAMEs set this run
+BOX_REFS=()       # "KEY=op://vault/item/FIELD" lines the box's env template needs
+SKIPPED=()        # things we couldn't do (e.g. gh missing)
+
+# _clear wipes the terminal so only the current step is on screen. No-op when
+# output isn't a terminal, so piped logs stay readable.
+_clear() {
+  [[ -t 1 ]] || return 0
+  if command -v tput >/dev/null 2>&1; then tput clear; else printf '\033[2J\033[3J\033[H'; fi
+}
+
+# banner "Title" shows the opening frame: what this wizard does.
+banner() {
+  _clear
+  printf '\n%s%s  %s%s\n' "$BOLD" "$BLUE" "$1" "$RESET"
+  printf '%s  %s stages%s\n\n' "$DIM" "$TOTAL_STAGES" "$RESET"
+  printf '%s  You drive the browser; this wizard tells you exactly what to do and\n' "$DIM"
+  printf '  captures the values you copy back. Stop any time with Ctrl-C and re-run\n'
+  printf '  later, since it remembers values already saved.%s\n' "$RESET"
+  pause "Ready to start?"
+}
+
+# stage "Name" clears the screen, then announces a stage and shows progress.
+# Clearing keeps only the current step on screen.
+stage() {
+  _clear
+  _STAGE_INDEX=$((_STAGE_INDEX + 1))
+  printf '\n%s%s▸ Stage %s/%s · %s%s\n' \
+    "$BOLD" "$BLUE" "$_STAGE_INDEX" "$TOTAL_STAGES" "$1" "$RESET"
+}
+
+# say "..." prints a plain instruction line.
+say()  { printf '  %s\n' "$1"; }
+# step "..." is a numbered-feeling action the human takes in the browser.
+step() { printf '  %s•%s %s\n' "$BLUE" "$RESET" "$1"; }
+note() { printf '  %s%s%s\n' "$DIM" "$1" "$RESET"; }
+warn() { printf '  %s⚠ %s%s\n' "$YELLOW" "$1" "$RESET"; }
+
+# open_url URL opens it in the human's browser, cross-platform incl. WSL.
+open_url() {
+  local url="$1"
+  printf '  %s↗ opening%s %s\n' "$GREEN" "$RESET" "$url"
+  { if   command -v wslview     >/dev/null 2>&1; then wslview "$url"
+    elif command -v explorer.exe >/dev/null 2>&1; then explorer.exe "$url"
+    elif command -v xdg-open    >/dev/null 2>&1; then xdg-open "$url"
+    elif command -v open        >/dev/null 2>&1; then open "$url"
+    else warn "couldn't open a browser; visit it manually: $url"; fi
+  } >/dev/null 2>&1 || warn "couldn't open a browser, so visit it manually: $url"
+}
+
+# pause "msg" waits for the human to confirm they've done the manual part.
+pause() {
+  printf '  %s%s%s ' "$DIM" "${1:-Press Enter to continue}" "$RESET"
+  read -r _ || true
+}
+
+# confirm "question" is a y/N gate; returns success on yes.
+confirm() {
+  local reply=""
+  printf '  %s? %s [y/N] ' "$YELLOW" "$1"
+  read -r reply || true
+  [[ "$reply" =~ ^[Yy] ]]
+}
+
+# _existing KEY: current value of KEY in ENV_FILE, if any.
+_existing() {
+  [[ -f "$ENV_FILE" ]] || return 1
+  local line; line=$(grep -E "^${1}=" "$ENV_FILE" | tail -n1) || return 1
+  printf '%s' "${line#*=}"
+}
+
+# ask KEY "Prompt" reads a value into $KEY. Offers the existing .env value as
+# a default on re-runs (Enter keeps it). Visible input (non-secret).
+ask() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -r input || true
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# ask_secret KEY "Prompt" is like ask, but input is hidden.
+ask_secret() {
+  local key="$1" prompt="$2" current input
+  current=$(_existing "$key" || true)
+  if [[ -n "$current" ]]; then
+    printf '  %s%s%s %s[Enter keeps current]%s ' "$BOLD" "$prompt" "$RESET" "$DIM" "$RESET"
+  else
+    printf '  %s%s%s ' "$BOLD" "$prompt" "$RESET"
+  fi
+  read -rs input || true
+  printf '\n'
+  [[ -z "$input" && -n "$current" ]] && input="$current"
+  printf -v "$key" '%s' "$input"
+}
+
+# write_env KEY VALUE upserts KEY=VALUE into ENV_FILE (creates it; replaces
+# any existing line). Idempotent.
+write_env() {
+  local key="$1" value="$2" tmp
+  touch "$ENV_FILE"
+  tmp=$(mktemp)
+  grep -vE "^${key}=" "$ENV_FILE" > "$tmp" || true
+  printf '%s=%s\n' "$key" "$value" >> "$tmp"
+  mv "$tmp" "$ENV_FILE"
+  WRITTEN_ENV+=("$key")
+  printf '  %s✓ wrote%s %s → %s\n' "$GREEN" "$RESET" "$key" "$ENV_FILE"
+}
+
+# set_secret NAME VALUE sets a GitHub Actions repo secret via gh. Falls back
+# to a warning (and records it) if gh is unavailable or unauthenticated.
+set_secret() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if printf '%s' "$value" | gh secret set "$name" >/dev/null 2>&1; then
+      WRITTEN_SECRET+=("$name")
+      printf '  %s✓ set%s GitHub secret %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub secret $name (set it manually: gh secret set $name)")
+  warn "skipped GitHub secret $name: gh not ready; set it later"
+}
+
+# set_var NAME VALUE sets a GitHub Actions repo variable (non-secret).
+set_var() {
+  local name="$1" value="$2"
+  if command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1; then
+    if gh variable set "$name" --body "$value" >/dev/null 2>&1; then
+      printf '  %s✓ set%s GitHub variable %s\n' "$GREEN" "$RESET" "$name"
+      return
+    fi
+  fi
+  SKIPPED+=("GitHub variable $name")
+  warn "skipped GitHub variable $name, gh not ready; set it later"
+}
+
+# box_ref KEY "op://vault/item/FIELD" records that the agent-ops box must read
+# KEY from that 1Password reference. The wizard never writes to 1Password; the
+# stage tells the human to store the value there, and finish prints the exact
+# line the box's env template needs.
+box_ref() {
+  BOX_REFS+=("$1=$2")
+  printf '  %s✓ box%s %s → %s\n' "$GREEN" "$RESET" "$1" "$2"
+}
+
+# finish clears, then shows a closing summary of everything configured.
+finish() {
+  _clear
+  printf '\n%s%s  ✓ Setup complete%s\n' "$BOLD" "$GREEN" "$RESET"
+  (( ${#WRITTEN_ENV[@]} ))    && note "wrote ${#WRITTEN_ENV[@]} value(s) to $ENV_FILE: ${WRITTEN_ENV[*]}"
+  (( ${#WRITTEN_SECRET[@]} )) && note "set ${#WRITTEN_SECRET[@]} GitHub secret(s): ${WRITTEN_SECRET[*]}"
+  if (( ${#BOX_REFS[@]} )); then
+    printf '\n'; warn "box credentials: add these lines to $BOX_ENV_TEMPLATE in agent-ops"
+    for r in "${BOX_REFS[@]}"; do printf '    %s\n' "$r"; done
+    note "Each value must exist in 1Password at the reference shown."
+    note "The box cannot see these until that change is merged and the box has converged."
+  fi
+  if (( ${#SKIPPED[@]} )); then
+    printf '\n'; warn "still to do by hand:"
+    for s in "${SKIPPED[@]}"; do note "  - $s"; done
+  fi
+  printf '\n'
+}
+
+# ──────────────────────────────────────────────────────────────────────────
+# STAGES: author this section. One stage() per step the human takes.
+# Replace the example below. Set TOTAL_STAGES to match the stages you write.
+# ──────────────────────────────────────────────────────────────────────────
+
+TOTAL_STAGES=1
+
+banner "Stripe setup"
+
+# ── Example stage: replace with your real steps ───────────────────────────
+stage "Stripe: API keys"
+say "We'll grab your Stripe test keys and store them for local dev, CI and the box."
+open_url "https://dashboard.stripe.com/test/apikeys"
+step "On the API keys page, copy the Publishable key (starts pk_test_)."
+ask STRIPE_PUBLISHABLE_KEY "Paste the publishable key:"
+step "Click 'Reveal test key' on the Secret key row, then copy it."
+ask_secret STRIPE_SECRET_KEY "Paste the secret key:"
+write_env STRIPE_PUBLISHABLE_KEY "$STRIPE_PUBLISHABLE_KEY"   # local only
+write_env STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"
+set_secret STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"            # CI needs this one
+step "In 1Password, vault agent-ops, item agent-ops-stripe: add field STRIPE_SECRET_KEY with the same value."
+pause "Stored in 1Password?"
+box_ref STRIPE_SECRET_KEY "op://agent-ops/agent-ops-stripe/STRIPE_SECRET_KEY"   # the box needs this one
+# ──────────────────────────────────────────────────────────────────────────
+
+finish

package/skills-manifest.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-03T09:39:52.864Z",
+  "generatedAt": "2026-09-07T15:08:46.060Z",
   "skills": [
     {
       "name": "backlog",
-      "version": "0.1.6",
-      "hash": "sha256-89423260dd0d35ceb16f536c1c3bd0e5fc43a30f36861e301a7a807351645582",
+      "version": "0.1.7",
+      "hash": "sha256-652964aebeadbd2a4ecafd5a588f0bd0c31b90442f3133f64d7d663893a1f7a0",
       "description": "Manage a GitHub-Issues-backed backlog and a Projects-v2 work graph via five verbs. Use when the user wants to CAPTURE an idea/research thread (\"add to backlog\", \"capture this\", \"note this idea\", \"log a task\"), TRIAGE the inbox (\"triage the backlog\", \"score the inbox\"), see what to work on NEXT (\"what's next\", \"what should I work on\", \"ranked backlog\", \"next actionable task\"), LAND a finished item (\"mark done\", \"close out #N\"), or SETUP the board the first time. Ranks open issues by impact÷effort, respecting `Blocked by:` edges, so only actionable work surfaces."
     },
     {
@@ -49,6 +49,30 @@
       "version": "0.1.0",
       "hash": "sha256-4e386dd175a34e55e89e0e29e37f5d0afd927560b7e3ba4c5f3ef482fb73f722",
       "description": "Capture before/after screenshots of UI views with Playwright and embed them in a PR. Use this skill whenever creating or preparing a pull request that touches frontend code (components, views, styles, layout, Tailwind classes) — even if the user just says \"open a PR\" or \"create the PR\" after UI work, and especially if they mention screenshots, visual diff, before/after, or \"show what changed\". Also use when the user asks to add screenshots to an existing PR."
+    },
+    {
+      "name": "prototype",
+      "version": "0.1.0",
+      "hash": "sha256-211e0e116ff6efbc4589ea7264835855b9495ba535f242733af913903fe7707d",
+      "description": "Build a throwaway prototype to answer a design question, delivered as one self-contained HTML file. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like."
+    },
+    {
+      "name": "to-spec",
+      "version": "0.1.0",
+      "hash": "sha256-146048bc0d698b92c330e860dc5c052b4645e1ba69f5b094270632daec82e40b",
+      "description": "Turn the current conversation into a design spec and write it where the next stage reads it: a GitHub issue body labelled spec-ready (after a grilling session), or a dated design file on the current branch (an unattended spec stage). No interview, just synthesis of what you've already discussed."
+    },
+    {
+      "name": "to-tickets",
+      "version": "0.1.0",
+      "hash": "sha256-23e1381b40dd4ffa151a2f89dcb82462464ea424228b45a31e6656406d34fedc",
+      "description": "Break a spec, plan, or the current conversation into numbered tracer-bullet ticket files under .agent/tickets/, each declaring its blocking edges and acceptance criteria phrased as observable behavior. Use after a spec is approved and before implementation starts."
+    },
+    {
+      "name": "wizard",
+      "version": "0.1.0",
+      "hash": "sha256-ebcd06573861f575707717ef65218b52436256c33a8cb1da12484c5b58ce9294",
+      "description": "Generate an interactive bash wizard that walks a human through steps only they can perform, and that says for every captured value whether it ends up in CI, on the agent-ops box (1Password), or local only. Use when provisioning infrastructure, setting up credentials or CI secrets, walking an unfamiliar third-party dashboard, or running a one-off migration or cutover. Don't invoke this for steps the agent can perform itself."
     }
   ]
 }