npm - @complexthings/superpowers-agent - Versions diffs - 10.0.3 → 11.0.0 - Mend

@complexthings/superpowers-agent 10.0.3 → 11.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (96) hide show

package/.agents/superpowers-agent +17 -222
package/.github/copilot-instructions.md +0 -9
package/AGENTS.md +19 -140
package/README.md +79 -507
package/package.json +1 -7
package/.agents/docs/SUPERPOWERS.md +0 -37
package/.agents/skills/.gitkeep +0 -0
package/.agents/skills/claude-handoff/SKILL.md +0 -18
package/.agents/skills/code-review/SKILL.md +0 -89
package/.agents/skills/codebase-design/DEEPENING.md +0 -37
package/.agents/skills/codebase-design/DESIGN-IT-TWICE.md +0 -44
package/.agents/skills/codebase-design/SKILL.md +0 -114
package/.agents/skills/design-an-interface/SKILL.md +0 -94
package/.agents/skills/diagnosing-bugs/SKILL.md +0 -134
package/.agents/skills/diagnosing-bugs/scripts/hitl-loop.template.sh +0 -41
package/.agents/skills/domain-modeling/ADR-FORMAT.md +0 -47
package/.agents/skills/domain-modeling/CONTEXT-FORMAT.md +0 -60
package/.agents/skills/domain-modeling/SKILL.md +0 -74
package/.agents/skills/fable-mode/SKILL.md +0 -95
package/.agents/skills/git-guardrails-claude-code/SKILL.md +0 -95
package/.agents/skills/git-guardrails-claude-code/scripts/block-dangerous-git.sh +0 -25
package/.agents/skills/grill-me/SKILL.md +0 -7
package/.agents/skills/grill-with-docs/SKILL.md +0 -7
package/.agents/skills/grilling/SKILL.md +0 -14
package/.agents/skills/handoff/SKILL.md +0 -16
package/.agents/skills/i-have-adhd/SKILL.md +0 -120
package/.agents/skills/implement/SKILL.md +0 -11
package/.agents/skills/improve-codebase-architecture/HTML-REPORT.md +0 -123
package/.agents/skills/improve-codebase-architecture/SKILL.md +0 -66
package/.agents/skills/loop-me/SKILL.md +0 -32
package/.agents/skills/prototype/LOGIC.md +0 -79
package/.agents/skills/prototype/SKILL.md +0 -30
package/.agents/skills/prototype/UI.md +0 -112
package/.agents/skills/qa/SKILL.md +0 -130
package/.agents/skills/request-refactor-plan/SKILL.md +0 -68
package/.agents/skills/research/SKILL.md +0 -12
package/.agents/skills/resolving-merge-conflicts/SKILL.md +0 -14
package/.agents/skills/scaffold-exercises/SKILL.md +0 -106
package/.agents/skills/setup-matt-pocock-skills/SKILL.md +0 -127
package/.agents/skills/setup-matt-pocock-skills/domain.md +0 -51
package/.agents/skills/setup-matt-pocock-skills/issue-tracker-github.md +0 -45
package/.agents/skills/setup-matt-pocock-skills/issue-tracker-gitlab.md +0 -46
package/.agents/skills/setup-matt-pocock-skills/issue-tracker-local.md +0 -30
package/.agents/skills/setup-matt-pocock-skills/triage-labels.md +0 -15
package/.agents/skills/skill-creator/LICENSE.txt +0 -202
package/.agents/skills/skill-creator/SKILL.md +0 -485
package/.agents/skills/skill-creator/agents/analyzer.md +0 -274
package/.agents/skills/skill-creator/agents/comparator.md +0 -202
package/.agents/skills/skill-creator/agents/grader.md +0 -223
package/.agents/skills/skill-creator/assets/eval_review.html +0 -146
package/.agents/skills/skill-creator/eval-viewer/generate_review.py +0 -471
package/.agents/skills/skill-creator/eval-viewer/viewer.html +0 -1325
package/.agents/skills/skill-creator/references/schemas.md +0 -430
package/.agents/skills/skill-creator/scripts/__init__.py +0 -0
package/.agents/skills/skill-creator/scripts/__pycache__/__init__.cpython-314.pyc +0 -0
package/.agents/skills/skill-creator/scripts/__pycache__/run_eval.cpython-314.pyc +0 -0
package/.agents/skills/skill-creator/scripts/__pycache__/utils.cpython-314.pyc +0 -0
package/.agents/skills/skill-creator/scripts/aggregate_benchmark.py +0 -401
package/.agents/skills/skill-creator/scripts/generate_report.py +0 -326
package/.agents/skills/skill-creator/scripts/improve_description.py +0 -247
package/.agents/skills/skill-creator/scripts/package_skill.py +0 -136
package/.agents/skills/skill-creator/scripts/quick_validate.py +0 -103
package/.agents/skills/skill-creator/scripts/run_eval.py +0 -310
package/.agents/skills/skill-creator/scripts/run_loop.py +0 -328
package/.agents/skills/skill-creator/scripts/utils.py +0 -47
package/.agents/skills/tdd/SKILL.md +0 -36
package/.agents/skills/tdd/mocking.md +0 -59
package/.agents/skills/tdd/tests.md +0 -77
package/.agents/skills/teach/GLOSSARY-FORMAT.md +0 -35
package/.agents/skills/teach/LEARNING-RECORD-FORMAT.md +0 -46
package/.agents/skills/teach/MISSION-FORMAT.md +0 -31
package/.agents/skills/teach/RESOURCES-FORMAT.md +0 -32
package/.agents/skills/teach/SKILL.md +0 -140
package/.agents/skills/to-spec/SKILL.md +0 -75
package/.agents/skills/to-tickets/SKILL.md +0 -114
package/.agents/skills/triage/AGENT-BRIEF.md +0 -207
package/.agents/skills/triage/OUT-OF-SCOPE.md +0 -105
package/.agents/skills/triage/SKILL.md +0 -112
package/.agents/skills/ubiquitous-language/SKILL.md +0 -93
package/.agents/skills/wayfinder/SKILL.md +0 -127
package/.agents/skills/writing-great-skills/GLOSSARY.md +0 -201
package/.agents/skills/writing-great-skills/SKILL.md +0 -83
package/.agents/templates/AGENTS.md.template +0 -27
package/.agents/templates/SUPERPOWERS.md.template +0 -37
package/skills/collaboration/brainstorming/SKILL.md +0 -66
package/skills/collaboration/brainstorming/skill.json +0 -9
package/skills/collaboration/leveraging-cli-tools/SKILL.md +0 -110
package/skills/collaboration/leveraging-cli-tools/references/copilot-instructions.md +0 -30
package/skills/collaboration/leveraging-cli-tools/scripts/setup-ponytail.sh +0 -185
package/skills/collaboration/leveraging-cli-tools/scripts/setup-rtk.sh +0 -217
package/skills/collaboration/leveraging-cli-tools/skill.json +0 -9
package/skills/meta/create-skill-json/SKILL.md +0 -370
package/skills/meta/create-skill-json/skill.json +0 -9
package/skills/meta/create-skill-json/test-scenarios.md +0 -29
package/skills/setup-skills/SKILL.md +0 -54
package/skills/setup-skills/skill.json +0 -8

package/.agents/skills/improve-codebase-architecture/HTML-REPORT.md DELETED Viewed

@@ -1,123 +0,0 @@
-# HTML Report Format
-The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
-## Scaffold
-```html
-<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
-    <title>Architecture review — {{repo name}}</title>
-    <script src="https://cdn.tailwindcss.com"></script>
-    <script type="module">
-      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
-      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
-    </script>
-    <style>
-      /* small custom layer for things Tailwind doesn't cover cleanly:
-         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
-      .seam { stroke-dasharray: 4 4; }
-      .leak { stroke: #dc2626; }
-      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
-    </style>
-  </head>
-  <body class="bg-stone-50 text-slate-900 font-sans">
-    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
-      <header>...</header>
-      <section id="candidates" class="space-y-10">...</section>
-      <section id="top-recommendation">...</section>
-    </main>
-  </body>
-</html>
-```
-## Header
-Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
-## Candidate card
-The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
-Each candidate is one `<article>`:
-- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
-- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
-- **Files** — monospaced list, `font-mono text-sm`.
-- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
-- **Problem** — one sentence. What hurts.
-- **Solution** — one sentence. What changes.
-- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
-- **ADR callout** (if applicable) — one line in an amber-tinted box.
-No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
-## Diagram patterns
-Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
-### Mermaid graph (the workhorse for dependencies / call flow)
-Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
-```html
-<div class="rounded-lg border border-slate-200 bg-white p-4">
-  <pre class="mermaid">
-    flowchart LR
-      A[OrderHandler] --> B[OrderValidator]
-      B --> C[OrderRepo]
-      C -.leak.-> D[PricingClient]
-      classDef leak stroke:#dc2626,stroke-width:2px;
-      class C,D leak
-  </pre>
-</div>
-```
-### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
-Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
-### Cross-section (good for layered shallowness)
-Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
-### Mass diagram (good for "interface as wide as implementation")
-Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
-### Call-graph collapse
-Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
-## Style guidance
-- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
-- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
-- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
-- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
-- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
-## Top recommendation section
-One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
-## Tone
-Plain English, concise — but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
-**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
-**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
-**Phrasings that fit the style:**
-- "Order intake module is shallow — interface nearly matches the implementation."
-- "Pricing leaks across the seam."
-- "Deepen: one interface, one place to test."
-- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
-**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
-No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.

package/.agents/skills/improve-codebase-architecture/SKILL.md DELETED Viewed

@@ -1,66 +0,0 @@
----
-name: improve-codebase-architecture
-description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
-disable-model-invocation: true
----
-# Improve Codebase Architecture
-Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
-This command is _informed_ by the project's domain model and built on a shared design vocabulary:
-- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
-- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
-## Process
-### 1. Explore
-Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
-Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
-- Where does understanding one concept require bouncing between many small modules?
-- Where are modules **shallow** — interface nearly as complex as the implementation?
-- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
-- Where do tightly-coupled modules leak across their seams?
-- Which parts of the codebase are untested, or hard to test through their current interface?
-Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
-### 2. Present candidates as an HTML report
-Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
-The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
-For each candidate, render a card with:
-- **Files** — which files/modules are involved
-- **Problem** — why the current architecture is causing friction
-- **Solution** — plain English description of what would change
-- **Benefits** — explained in terms of locality and leverage, and how tests would improve
-- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
-- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
-End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
-**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
-**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
-See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
-Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
-### 3. Grilling loop
-Once the user picks a candidate, run the `/grilling` skill to walk the design tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
-Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
-- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
-- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
-- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
-- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern.

package/.agents/skills/loop-me/SKILL.md DELETED Viewed

@@ -1,32 +0,0 @@
----
-name: loop-me
-description: Grill me about specs for the workflows I want to build, within this workspace.
-disable-model-invocation: true
-argument-hint: "A workflow to design, or nothing to go find one"
----
-Run a stateful `/grilling` session whose only output is **workflow** specs. Use the grilling discipline — relentless, one question at a time, a recommended answer attached to each — aimed at the vocabulary and goal below. Create, edit, and delete specs as the grilling resolves things.
-## The loop lens
-A **loop** is a recurring pattern in the user's life: their career, their week, their morning, a single repeated activity. Picturing a life as loops within loops reveals how predictable its activities really are — which is what makes them worth **delegating**. Use the lens to find loops worth specifying, and propose ones the user hasn't noticed.
-A **workflow** is the spec of one loop, made real. You run a workflow on a loop — the loop is its running instantiation. Workflows live in `workflows/*.md` and are the source of truth.
-## Vocabulary
-A shared language, reached for only when a workflow calls for it — never a checklist. **Mandate nothing structural**: a workflow needs no AI, no checkpoint, and no schedule unless the grilling shows it does.
-- **Trigger** — what fires each run: an **event** (a new email, a new issue) or a **schedule** (every morning). Event-triggering is usually the more efficient.
-- **Checkpoint** — a human-in-the-loop point where the user is asked to verify or decide. Some workflows have none and run autonomously; some use no AI at all.
-- **Push right** — defer the checkpoint as far as it will go. Do maximal work before involving the human, so they are asked once, late, with everything prepared.
-- **Brief** — what a checkpoint presents: a tight, decision-ready summary — what was produced, why, and a link down to the asset itself — never the raw output. The user reads a brief, not a draft. Speed of review is imperative.
-## Definition of done
-A workflow spec is done when an implementer agent could build it without asking a single question. Grill until then; nothing is done while a question remains.
-## The workspace
-- `workflows/*.md` — one spec per workflow.
-- `NOTES.md` — raw notes on the user's world: the tools they use, the channels they process, and their own terminology for both. When it is empty or thin, interview them about their world before specifying anything. Sharpen fuzzy terms into canonical ones as they surface, and record them here.

package/.agents/skills/prototype/LOGIC.md DELETED Viewed

@@ -1,79 +0,0 @@
-# Logic Prototype
-A tiny interactive terminal app that lets the user drive a state model by hand. 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.
-## 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 the user wants to **press buttons and watch state change**.
-If the question is "what should this look like" — 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, in the prototype's README or a comment at the top of the file. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning to it AFK.
-### 2. Pick the language
-Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask.
-Match the project's existing conventions for tooling — don't add a new package manager or runtime just for the prototype.
-### 3. Isolate the logic in a portable module
-Put the actual logic — the bit that's answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be.
-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 TUI. Keep it pure: no I/O, no terminal code, no `console.log` for control flow. The TUI imports it and calls into it; nothing flows the other direction.
-This is what makes the prototype useful past its own lifetime. When the question's been answered, the validated reducer / machine / function set can be lifted into the real module — the TUI shell gets deleted.
-### 4. Build the smallest TUI that exposes the state
-Build it as a **lightweight TUI** — on every tick, clear the screen (`console.clear()` / `print("\033[2J\033[H")` / equivalent) and re-render the whole frame. The user should always see one stable view, not an ever-growing scrollback.
-Each frame has two parts, in this order:
-1. **Current state**, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use **bold** for field names or section headers and **dim** for less important context (timestamps, IDs, derived values). Native ANSI escape codes are fine — `\x1b[1m` bold, `\x1b[2m` dim, `\x1b[0m` reset. No need to pull in a styling library unless one is already in the project.
-2. **Keyboard shortcuts**, listed at the bottom: `[a] add user  [d] delete user  [t] tick clock  [q] quit`. Bold the key, dim the description, or vice-versa — whatever reads cleanly.
-Behaviour:
-1. **Initialise state** — a single in-memory object/struct. Render the first frame on start.
-2. **Read one keystroke (or one line)** at a time, dispatch to a handler that mutates state.
-3. **Re-render** the full frame after every action — don't append, replace.
-4. **Loop until quit.**
-The whole frame should fit on one screen.
-### 5. Make it runnable in one command
-Add a script to the project's existing task runner (`package.json` scripts, `Makefile`, `justfile`, `pyproject.toml`). The user should run `pnpm run <prototype-name>` or equivalent — never need to remember a path.
-If the host project has no task runner, just put the command at the top of the prototype's README.
-### 6. Hand it over
-Give the user the run command. They'll drive it themselves; 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 added, add them. Prototypes evolve.
-### 7. Capture the answer
-When the prototype has done its job, the answer to the question is the only thing worth keeping. If the user is around, ask what it taught them. If not, leave a `NOTES.md` next to the prototype so the answer can be filled in (or filled in by you, if you've watched the session) before the prototype gets deleted.
-## 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 an in-memory store 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 TUI together.** If the reducer / state machine references `console.log`, prompts, or terminal escape codes, it's no longer portable. Keep the TUI as a thin shell over a pure module.
-- **Don't ship the TUI shell into production.** The shell is optimised for being driven by hand from a terminal. The logic module behind it is the bit worth keeping.

package/.agents/skills/prototype/SKILL.md DELETED Viewed

@@ -1,30 +0,0 @@
----
-name: prototype
-description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
----
-# Prototype
-A prototype is **throwaway code that answers a question**. The question decides the shape.
-## Pick a branch
-Identify which question is being answered — from 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). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
-- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.
-The two branches produce very different artifacts — 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. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.
-2. **One command to run.** Whatever the project's existing task runner supports — `pnpm <name>`, `python <path>`, `bun <path>`, etc. The user must be able to start it without thinking.
-3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.
-4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast and then delete it.
-5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.
-6. **Delete or absorb when done.** When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.
-## When done
-The _answer_ is the only thing worth keeping from a prototype. Capture it somewhere durable (commit message, ADR, issue, or a `NOTES.md` next to the prototype) along with the question it was answering. If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.

package/.agents/skills/prototype/UI.md DELETED Viewed

@@ -1,112 +0,0 @@
-# UI Prototype
-Generate **several radically different UI variations** on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, 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 — 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.
-## Two sub-shapes — strongly prefer sub-shape A
-A UI prototype is much easier to judge when it's **butting up against the rest of the app** — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants. Only reach for sub-shape B if the prototype genuinely has no nearby home.
-### Sub-shape A — adjustment to an existing page (preferred)
-The route already exists. Variants are rendered **on the same route**, gated by a `?variant=` URL search param. The existing data fetching, params, and auth all stay — only the rendering swaps. This is the default; pick it unless there's a specific reason not to.
-If the prototype is for something that doesn't yet have a page but *would naturally live inside one* (a new section of the dashboard, a new card on the settings screen, a new step in an existing flow) — that's still sub-shape A. Mount the variants inside the host page.
-### Sub-shape B — a new page (last resort)
-Only use this when the thing being prototyped genuinely has no existing page to live inside — e.g. an entirely new top-level surface, or a flow that can't be embedded anywhere sensible.
-Create a **throwaway route** following whatever routing convention the project already uses — don't invent a new top-level structure. Name it so it's obviously a prototype (e.g. include the word `prototype` in the path or filename). Same `?variant=` pattern.
-Before committing to sub-shape B, sanity-check: is there really no existing page this could be embedded in? An empty route hides design problems that a populated one would expose.
-In both sub-shapes the floating bottom bar is identical.
-## Process
-### 1. State the question and pick N
-Default to **3 variants**. More than 5 stops being radically different and starts being noise — cap there.
-Write down the plan in one line, in the prototype's location or a top-of-file comment:
-> "Three variants of the settings page, switchable via `?variant=`, on the existing `/settings` route."
-This works whether the user is here to push back or not.
-### 2. Generate radically different variants
-Draft each variant. Hold each one to:
-- The page's purpose and the data it has access to.
-- The project's component library / styling system (TailwindCSS, shadcn, MUI, plain CSS, whatever).
-- A clear exported component name, e.g. `VariantA`, `VariantB`, `VariantC`.
-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
-Create a single switcher component on the route:
-```tsx
-// pseudo-code — adapt to the project's framework
-const variant = searchParams.get('variant') ?? 'A';
-return (
-  <>
-    {variant === 'A' && <VariantA {...data} />}
-    {variant === 'B' && <VariantB {...data} />}
-    {variant === 'C' && <VariantC {...data} />}
-    <PrototypeSwitcher variants={['A','B','C']} current={variant} />
-  </>
-);
-```
-For sub-shape A (existing page): keep all the existing data fetching above the switcher; only the rendered subtree changes per variant.
-For sub-shape B (new page): the throwaway route under `/prototype/<name>` mounts the same switcher.
-### 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, if the variant exports a name, that name too. e.g. `B — Sidebar layout`.
-- **Right arrow** — cycles forward (wraps around).
-Behaviour:
-- Clicking an arrow updates the URL search param (use the framework's router — `router.replace` on Next, `navigate` on React Router, etc) 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.
-- Visually distinct from the page (e.g. high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
-- Hidden in production builds — gate on `process.env.NODE_ENV !== 'production'` or an equivalent check, so a stray prototype merge can't ship the bar to users.
-Put the switcher in a single shared component so both sub-shapes can reuse it. Locate it wherever shared UI lives in the project.
-### 5. Hand it over
-Surface the URL (and the `?variant=` keys). 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"** — that's the actual design they want.
-### 6. Capture the answer and clean up
-Once a variant has won, write down which one and why (commit message, ADR, issue, or a `NOTES.md` next to the prototype if running AFK and the user hasn't responded yet). Then:
-- **Sub-shape A** — delete the losing variants and the switcher; fold the winner into the existing page.
-- **Sub-shape B** — promote the winning variant to a real route, delete the throwaway route and the switcher.
-Don't leave variant components or the switcher lying around. They rot fast and confuse the next reader.
-## 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 code between variants.** A shared `<Header>` is fine; a shared `<Layout>` defeats the point. Each variant should be free to throw out the layout.
-- **Wiring variants to real mutations.** Read-only prototypes are fine. If a variant needs to mutate, point it at a stub — the question is "what should this look like", not "does the backend work".
-- **Promoting the prototype directly to production.** The variant code was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.

package/.agents/skills/qa/SKILL.md DELETED Viewed

@@ -1,130 +0,0 @@
----
-name: qa
-description: Interactive QA session where user reports bugs or issues conversationally, and the agent files GitHub issues. Explores the codebase in the background for context and domain language. Use when user wants to report bugs, do QA, file issues conversationally, or mentions "QA session".
----
-# QA Session
-Run an interactive QA session. The user describes problems they're encountering. You clarify, explore the codebase for context, and file GitHub issues that are durable, user-focused, and use the project's domain language.
-## For each issue the user raises
-### 1. Listen and lightly clarify
-Let the user describe the problem in their own words. Ask **at most 2-3 short clarifying questions** focused on:
-- What they expected vs what actually happened
-- Steps to reproduce (if not obvious)
-- Whether it's consistent or intermittent
-Do NOT over-interview. If the description is clear enough to file, move on.
-### 2. Explore the codebase in the background
-While talking to the user, kick off an Agent (subagent_type=Explore) in the background to understand the relevant area. The goal is NOT to find a fix — it's to:
-- Learn the domain language used in that area (check UBIQUITOUS_LANGUAGE.md)
-- Understand what the feature is supposed to do
-- Identify the user-facing behavior boundary
-This context helps you write a better issue — but the issue itself should NOT reference specific files, line numbers, or internal implementation details.
-### 3. Assess scope: single issue or breakdown?
-Before filing, decide whether this is a **single issue** or needs to be **broken down** into multiple issues.
-Break down when:
-- The fix spans multiple independent areas (e.g. "the form validation is wrong AND the success message is missing AND the redirect is broken")
-- There are clearly separable concerns that different people could work on in parallel
-- The user describes something that has multiple distinct failure modes or symptoms
-Keep as a single issue when:
-- It's one behavior that's wrong in one place
-- The symptoms are all caused by the same root behavior
-### 4. File the GitHub issue(s)
-Create issues with `gh issue create`. Do NOT ask the user to review first — just file and share URLs.
-Issues must be **durable** — they should still make sense after major refactors. Write from the user's perspective.
-#### For a single issue
-Use this template:
-```
-## What happened
-[Describe the actual behavior the user experienced, in plain language]
-## What I expected
-[Describe the expected behavior]
-## Steps to reproduce
-1. [Concrete, numbered steps a developer can follow]
-2. [Use domain terms from the codebase, not internal module names]
-3. [Include relevant inputs, flags, or configuration]
-## Additional context
-[Any extra observations from the user or from codebase exploration that help frame the issue — e.g. "this only happens when using the Docker layer, not the filesystem layer" — use domain language but don't cite files]
-```
-#### For a breakdown (multiple issues)
-Create issues in dependency order (blockers first) so you can reference real issue numbers.
-Use this template for each sub-issue:
-```
-## Parent issue
-#<parent-issue-number> (if you created a tracking issue) or "Reported during QA session"
-## What's wrong
-[Describe this specific behavior problem — just this slice, not the whole report]
-## What I expected
-[Expected behavior for this specific slice]
-## Steps to reproduce
-1. [Steps specific to THIS issue]
-## Blocked by
-- #<issue-number> (if this issue can't be fixed until another is resolved)
-Or "None — can start immediately" if no blockers.
-## Additional context
-[Any extra observations relevant to this slice]
-```
-When creating a breakdown:
-- **Prefer many thin issues over few thick ones** — each should be independently fixable and verifiable
-- **Mark blocking relationships honestly** — if issue B genuinely can't be tested until issue A is fixed, say so. If they're independent, mark both as "None — can start immediately"
-- **Create issues in dependency order** so you can reference real issue numbers in "Blocked by"
-- **Maximize parallelism** — the goal is that multiple people (or agents) can grab different issues simultaneously
-#### Rules for all issue bodies
-- **No file paths or line numbers** — these go stale
-- **Use the project's domain language** (check UBIQUITOUS_LANGUAGE.md if it exists)
-- **Describe behaviors, not code** — "the sync service fails to apply the patch" not "applyPatch() throws on line 42"
-- **Reproduction steps are mandatory** — if you can't determine them, ask the user
-- **Keep it concise** — a developer should be able to read the issue in 30 seconds
-After filing, print all issue URLs (with blocking relationships summarized) and ask: "Next issue, or are we done?"
-### 5. Continue the session
-Keep going until the user says they're done. Each issue is independent — don't batch them.

package/.agents/skills/request-refactor-plan/SKILL.md DELETED Viewed

@@ -1,68 +0,0 @@
----
-name: request-refactor-plan
-description: Create a detailed refactor plan with tiny commits via user interview, then file it as a GitHub issue. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.
----
-This skill will be invoked when the user wants to create a refactor request. You should go through the steps below. You may skip steps if you don't consider them necessary.
-1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
-2. Explore the repo to verify their assertions and understand the current state of the codebase.
-3. Ask whether they have considered other options, and present other options to them.
-4. Interview the user about the implementation. Be extremely detailed and thorough.
-5. Hammer out the exact scope of the implementation. Work out what you plan to change and what you plan not to change.
-6. Look in the codebase to check for test coverage of this area of the codebase. If there is insufficient test coverage, ask the user what their plans for testing are.
-7. Break the implementation into a plan of tiny commits. Remember Martin Fowler's advice to "make each refactoring step as small as possible, so that you can always see the program working."
-8. Create a GitHub issue with the refactor plan. Use the following template for the issue description:
-<refactor-plan-template>
-## Problem Statement
-The problem that the developer is facing, from the developer's perspective.
-## Solution
-The solution to the problem, from the developer's perspective.
-## Commits
-A LONG, detailed implementation plan. Write the plan in plain English, breaking down the implementation into the tiniest commits possible. Each commit should leave the codebase in a working state.
-## Decision Document
-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.
-## 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)
-- 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 refactor.
-## Further Notes (optional)
-Any further notes about the refactor.
-</refactor-plan-template>