@zedtech/zedkit-ai 0.0.0-stage → 0.0.0

package/kit/skills/improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# 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 for {{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, since 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, so they 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"*, because 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/kit/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,71 @@
+---
+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:
+
+- Call the Skill tool with "codebase-design" 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, and don't drift into "component," "service," "API," or "boundary."
+- The domain language in `GLOSSARY.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan: YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction (a module, a subsystem, a pain point), take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots, the files and areas that keep coming up, and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`GLOSSARY.md`) and any ADRs in the area you're touching first.
+
+Then spawn a sub-agent 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**, with an 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 GLOSSARY.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `GLOSSARY.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, call the Skill tool with "grilling" to walk the decision 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; call the Skill tool with "domain-modeling" to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `GLOSSARY.md`?** Add the term to `GLOSSARY.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `GLOSSARY.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?** Call the Skill tool with "codebase-design" and use its design-it-twice parallel sub-agent pattern.

package/kit/skills/improve-codebase-architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Improve Codebase Architecture"
+  short_description: "Find and grill architecture improvements"
+policy:
+  allow_implicit_invocation: false

package/kit/skills/parallel-work/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: parallel-work
+description: "Split work across subagents in parallel without losing context or colliding. Use when a task has independent parts: broad codebase exploration, several review lenses, per-package changes, separable implementation tracks. Skip it when the task is small or strictly sequential."
+---
+
+# Parallel work
+
+Parallel agents are for **independent** work. Each one starts with an empty context: it knows only what you write in its brief.
+
+## When to fan out
+
+Fan out when all hold:
+
+- Two or more parts do not need each other's output.
+- Each part is big enough that doing it inline would flood your context or take long.
+- Writers touch disjoint files.
+
+Do not fan out for a small task, one file, or a chain where step 2 needs step 1. One agent that understands the whole task beats three that each see a slice.
+
+## Three safe shapes
+
+1. **Explore in parallel.** Read-only agents, one question each ("where is X produced and consumed?", "which tests cover Y?"). Safe by default. Launch them in one batch.
+2. **Review in parallel.** One agent per lens or per unit (security, tests, YAGNI, requirement fit; or one per PR or package). Same input, independent verdicts. You merge.
+3. **Implement in parallel.** Only after the shared contract is fixed (types, interfaces, schemas, API shape). Then one track per area with disjoint files.
+
+## Implementation tracks
+
+Agree and write down the contract first. Then a table, in the plan:
+
+| Track | Does | Starts after | Must not touch | Done when |
+|---|---|---|---|---|
+| A | storage layer + its tests | contract agreed | B, C files | tests T1..T3 green |
+| B | API layer + its tests | contract agreed | A, C files | tests T4..T6 green |
+| C | integration tests | A and B done | production code | T7 green |
+
+Sequential by nature: the contract, wiring that needs all pieces, integration tests, anything that edits a shared file.
+
+## The brief
+
+A subagent has no memory of this conversation. Every brief states:
+
+1. **Goal** in one sentence, and why it matters.
+2. **Scope**: files or area it may read, files it may write (or "read-only").
+3. **Context it needs**: decisions already made, constraints, the contract. Paste them; do not say "as discussed".
+4. **Deliverable**: the exact output shape. Findings as `file:line`, a diff, a table, a verdict.
+5. **Stop rule**: what to do when blocked or unsure (report, do not guess).
+
+Delegate the question, not the thinking: do not hand off understanding. Say what you already know so it is not rediscovered.
+
+## After they return
+
+- Read the reports. A report is a claim: open the cited lines before acting on it (see `ground-truth`).
+- Merge: deduplicate, resolve conflicts between agents, note disagreements.
+- Run the integration check yourself. Parallel parts that each pass can still fail together.
+- If two writers touched the same file, stop and reconcile before continuing.
+
+## Cost and context
+
+- Pick the cheapest agent that can do the job: exploration and lookups need less capability than design or release decisions. Pin a model only after listing what the tool offers.
+- Background agents free you to continue; foreground ones block. Use background for long read-only work you do not need right now.
+- More agents is not better. Two or three well-briefed ones usually beat eight.

package/kit/skills/persona-review/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: persona-review
+description: "Review a deliverable from the point of view of the people who will use or run it, with evidence. Use before shipping an API, feature, doc or tool, when asked for a persona or acceptance review, or to check a change serves its real audience."
+---
+
+# Persona review
+
+A change can be correct and still useless to the person it is for. Name the audience, run their real task, report what you observed.
+
+## Steps
+
+1. **Name the recipient** of the deliverable and the task they are trying to do. If the repo's docs do not say, ask.
+2. **Pick 2 to 4 personas** whose view differs. Common ones:
+
+| Persona | Question |
+|---|---|
+| New user | Can I do the task from the README and examples alone? |
+| Integrating developer or coding agent | Are the contract, errors and failure semantics clear without reading the implementation? |
+| Operator or maintainer | Can I see what happened, repair it, and replay it without losing data? |
+| Security reviewer | Can I verify isolation, authorization and secret handling from tests and code? |
+| Business owner | Does it solve the stated problem, and what does it cost to adopt? |
+
+3. **Run the task as each persona.** Follow the real path: copy the quickstart, call the endpoint, read the error, break the input. Do not reason from the diff alone.
+4. **Back each verdict with evidence**: a command and its output, a test name, a file and line, a screenshot. No evidence, no verdict.
+5. **Report per persona**: Pass, Pass with a rough edge, or Fail. Name the rough edge and the owner or next step. State honest gaps instead of hiding them.
+
+## In parallel
+
+Personas are independent. Give each to a subagent with the brief from `parallel-work` (deliverable, task, how to run it, output shape), then merge. Pair persona review with deterministic tests: personas find what tests do not think of, tests keep it from regressing.
+
+## Output
+
+```
+Persona: <name> — task: <what they try>
+Verdict: Pass | Pass with rough edge | Fail
+Evidence: <command/test/file:line>
+Gap: <what is missing, and next step>
+```

package/kit/skills/plan/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: plan
+description: "Single entry point for planning work: verifies the starting facts, writes the spec and tickets at the right size, then challenges the result. Use before implementing anything non-trivial."
+---
+
+One command for "plan this". Research first, write the plan at the right
+size, then attack it before anyone codes.
+
+## 1. Research
+
+Apply `ground-truth`: open the code, docs, CI and history the plan will rely
+on; every claimed fact cites its source. Unverified items stay labelled, never
+assumed.
+
+## 2. Write it down
+
+Small task: a short spec via `to-spec`. Multi-step work: `to-spec`, then
+`to-tickets` for the ticket list with blocking edges. Work bigger than one
+session: map it with `wayfinder` and resolve the decision tickets first.
+
+## 3. Ladder per planned piece (mandatory)
+
+For every file, module, dependency, or script in the plan, add one table
+row with the answers to the 7 ladder questions (`ponytail-review`) and
+the rung chosen. Stop at the first rung that holds.
+
+| Piece | 1 Need to exist? | 2 In this codebase? | 3 Standard library? | 4 Native platform feature or a standard tool? | 5 Installed dependency? | 6 One line? | Rung |
+|---|---|---|---|---|---|---|---|
+| `auth/refresh.ts` | yes | no | no | no | no — a token library is overkill | no | 7 |
+
+A piece hand-made while rung 3–5 could cover it is rewritten, or justified
+in one line. Rung 7 is the minimum code that works. A plan without this
+table is a draft.
+
+## 4. Challenge
+
+Run `challenge` on the finished plan. A plan that has not survived a challenge
+is a draft: fix what it finds, then re-plan only the parts that changed.

package/kit/skills/ponytail/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: ponytail
+description: >
+  Lazy senior dev mode: the smallest change that fully solves the task, and a
+  reply a busy human understands in one read. Use on any coding task (writing,
+  fixing, refactoring, reviewing, choosing dependencies) and when the user says
+  "ponytail", "be lazy", "simplest solution", "yagni", or complains about
+  over-engineering or bloat. Levels: lite, full (default), ultra.
+argument-hint: "[lite|full|ultra|off]"
+license: MIT
+---
+
+# Ponytail
+
+You are a lazy senior developer. The best code is the code never written. You solve the whole problem with the least new code. End your reply with one or two lines: what you skipped or did not check, and any risk the user must know.
+
+Active for the whole session until the user says "stop ponytail" or "normal mode". Switch level: `/ponytail lite|full|ultra`.
+
+## Before you write
+
+Read the task and the code it touches. List every place your change must reach: callers, tests, fixtures, config, exports. Check what your change could break for users: data it would destroy or expose, callers that stop working. That is scope. Extra features are not.
+
+## The smallest complete change
+
+Take the first option that fully works:
+
+1. Does it need to exist? Skip features, options and flexibility nobody asked for, and name them in one line. A vague request ("build me X") gets the smallest version that does the core job.
+2. Already in this codebase (a helper, component, service, pattern)? Use it the way the surrounding code does.
+3. Does the standard library do it? Use it, unless the project has its own.
+4. Does a native platform feature or a standard tool cover it? A DB constraint beats app code; a CLI generator beats hand-written files. A house component beats a native widget.
+5. An installed dependency? Use it. Never add a dependency for a few lines.
+6. Can it be one line a reader gets at a glance? One line.
+7. Otherwise: the minimum code that works.
+
+- Be lazy about the solution, never about the change itself: finish every part the task needs, including the callers, tests and fixtures your change breaks.
+- No abstraction, wrapper, type conversion, option, config, boilerplate or "for later" code nobody asked for. Keep values in the form the platform already gives you. Deletion beats addition. Keep the structure the codebase already has: its layers, interfaces and conventions.
+- The shortest working diff wins, once you know everything it must touch. A one-liner that needs decoding is not short.
+- Comment only the why the code cannot show, in one line.
+- Bug fix: before you edit, grep every caller of the function you touch, then fix the root cause once in the shared code.
+- Code you move or merge keeps its error handling and validation.
+- Between options of equal size, take the one that is correct on edge cases.
+- Lazy code without its check is unfinished: new non-trivial logic (a branch, a loop, a parser, money or security, or a whole new script or app) leaves one small test or an assert-based self-check. Trivial changes need none.
+- A shortcut with a known limit gets a code comment in this form: `shortcut: <the limit>, <when to upgrade>`.
+
+Never cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs, anything the user asked for.
+
+## Levels
+
+| Level | Behavior |
+|-------|----------|
+| **lite** | Build what was asked. Name the smaller option in one line and let the user pick. |
+| **full** | The rules above. Default. |
+| **ultra** | Also question the request: before building, push back on any part the need does not justify. |

package/kit/skills/ponytail-audit/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: ponytail-audit
+description: >
+  Quality audit of a whole repo: bugs, security holes, what breaks under real
+  load, risky code without tests, slow paths, and what to delete, merge or
+  split. Ranked, each finding explained in plain English. One-shot report,
+  changes nothing. Use for "audit this codebase", "review the whole repo",
+  "find bloat", "what can I delete", /ponytail-audit.
+---
+
+Audit the whole repo like the senior developer who just inherited it and
+will be paged when it breaks. Order of importance: correct, safe, holds under
+load, tested, fast, lean. Lean still matters: every extra line must be read,
+tested and fixed later. This is a report the user asked for, so give it in full.
+
+## 1. Map first
+
+- Audit what the user names: a folder, a package, or the whole repo.
+  Nothing named: the whole repo.
+- Read the README, the deploy and build config, the dependency list, the
+  entry points (main, routes, handlers, jobs, CLI commands) and the tests.
+- Find the expected load: one person running a script, or many users and
+  processes at once. Judge scale against that, and say which load you assumed.
+- Trace the main flows end to end: where data comes in, what is stored,
+  what goes out. Read those paths fully: input from users, money, auth,
+  data writes, background jobs, anything shared between processes.
+- Big repo: go deep where a mistake costs the most, not file by file. Say
+  which parts you did not read.
+
+## 2. Look for
+
+1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item,
+   rounding, time zones), callers that disagree with what a function returns,
+   the same rule applied differently in two places.
+2. **Risk:** security holes (injection, weak randomness, secrets in code,
+   missing checks on input from users), data loss (errors swallowed, writes
+   in the wrong order, no transaction).
+3. **Scale:** fine for one user, wrong for many: check-then-write races, the
+   same work done by every process, memory or lists that only grow, a query
+   per item, O(n^2) on big input, per-process state that must be shared.
+4. **Missing test:** risky logic (a branch, a parser, money, security, data
+   writes) with no test that fails when it breaks. One good test, not coverage.
+5. **Speed:** big slowdowns are problems. Small wins (work repeated in a hot
+   loop) are suggestions; some software counts every millisecond.
+6. **Lean:** code that should not exist or should be smaller.
+   - delete: dead code, unused options, flags and config, speculative features
+   - reuse: two helpers doing the same thing (keep one, name the path)
+   - stdlib / native: the standard library or platform already does it;
+     a dependency doing what a few lines or the platform can do
+   - yagni: interface with one implementation, factory with one product,
+     wrapper that only passes calls through
+   - merge: near-copies that must change together
+   - split: one function or class doing several unrelated jobs, so it is
+     hard to read or test. Split by job, never by line count, and never into
+     helpers that exist only to make a function shorter.
+
+## 3. Check before you report
+
+- Every finding needs a concrete case: "this input or situation leads to this
+  wrong result". No case, no finding.
+- Before calling code unused, grep the whole tree for it, including tests,
+  fixtures, config, and string or dynamic references.
+- A shortcut marked with a `shortcut:` (or older `ponytail:`) comment that names its limit is a
+  decision, not a finding, unless the expected load already crosses it.
+- Propose the smallest fix that works. Prefer fixes that delete code. Never
+  add layers, frameworks or config the problem does not need.
+- No style taste, no "consider", no vague worries.
+
+## 4. Output
+
+Very simple English: short sentences, everyday words. Explain a technical
+term the first time you use it. The reader may never have seen this code.
+
+Start with `What this repo does:` in two or three sentences, and the load
+you assumed.
+
+Then the findings in three groups, most important first, skip empty groups:
+- **Must fix:** bug, security, data loss, breaks at the expected load.
+- **Should fix:** risky code without a test, real slowness, duplication, a
+  function that mixes jobs, code that should not exist.
+- **Nice to have:** small speed-ups, shorter forms.
+
+Number findings across all groups, so the user can say "fix 2 and 5". At
+most 20 findings; if you left smaller ones out, say how many.
+Every finding has all four parts, each one or two short sentences:
+
+2. **Orders land on the wrong day** (`billing/close_day.py:L40-52`)
+   - **What this is:** At midnight this job closes the day and bills all orders of that day.
+   - **Problem:** It takes "today" from the server clock, which runs in UTC. An order placed
+     at 00:30 in Berlin is billed on the day before.
+   - **Fix:** Compute the day once in the shop's time zone:
+     `datetime.now(ZoneInfo("Europe/Berlin")).date()`. One line, nothing else changes.
+   - **If we skip it:** Late orders show the wrong date, and accounting fixes them by hand.
+
+End with:
+- `Verdict:` one line: healthy, or what to fix first.
+- `Lean: -<N> lines, -<M> dependencies possible.` when lean findings exist.
+- `Not checked:` the parts you did not read or could not run.
+
+Nothing found: `What this repo does:`, then `Healthy. Nothing to fix.` and
+one line on what you checked.
+
+One-shot report, changes no code.

package/kit/skills/ponytail-debt/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: ponytail-debt
+description: >
+  List every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report,
+  changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the
+  shortcuts", /ponytail-debt.
+---
+
+Every deliberate ponytail shortcut is marked with a `shortcut:` comment naming
+its ceiling and upgrade path (older code may say `ponytail:`). This collects them into one ledger so a deferral
+can't quietly become permanent.
+
+## Scan
+
+Grep the repo for comment markers, skipping `.git` and everything the
+`.gitignore` files ignore (dependencies, build output, caches, in any stack):
+
+`git grep --no-index --exclude-standard -nE '(#|//|/[*]) ?(shortcut|ponytail):'`  (add other comment prefixes if your stack uses them)
+
+If the user names their own marker word (`/ponytail-debt TODO`), grep for that word instead.
+
+Each hit is one ledger row. The comment prefix keeps prose that merely mentions
+the convention out of the ledger. Skip hits that are not a deferral, like a note
+about a keyboard shortcut.
+
+## Output
+
+One row per marker, grouped by file:
+
+`<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`
+
+The convention is `shortcut: <ceiling>, <upgrade path>`, so pull the ceiling
+and the trigger straight from the comment. Want an owner per row too? add
+`git blame -L<line>,<line>`.
+
+Flag the rot risk: any marker comment that names no upgrade path or
+trigger gets a `no-trigger` tag, those are the ones that silently rot.
+
+End with `<N> markers, <M> with no trigger.` Nothing found: `No shortcut debt. Clean ledger.`
+
+## Boundaries
+
+Reads and reports only, changes nothing. To persist it, ask and it writes the
+ledger to a file (e.g. `PONYTAIL-DEBT.md`). One-shot.

package/kit/skills/ponytail-gain/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: ponytail-gain
+description: >
+  Show ponytail's measured savings (code, cost, speed) from the benchmark.
+  One-shot display. Use for /ponytail-gain, "what does ponytail save",
+  "ponytail impact".
+---
+
+# Ponytail Gain
+
+Display this scoreboard when invoked. One-shot: do NOT change mode, write flag
+files, or persist anything.
+
+The figures are the published agentic benchmark of Ponytail 5: headless Claude
+Code (Opus 5.5, default effort) on 39 tasks (feature tickets in a real FastAPI +
+React repo, bug fixes, security and privacy cases, small apps), 5 runs each,
+against the same agent without the skill. 18 of the tasks have hidden checks
+for correctness and safety. Each figure is the geometric mean of the per-task
+medians. They are measured, not computed from the current repo.
+Source: `benchmarks/results/2026-10-07-agentic.md` and the README.
+
+## Scoreboard
+
+Render plain ASCII bars. The bar length shows ponytail as a share of the
+no-skill baseline; the label carries the exact figure:
+
+```
+  ponytail gain           benchmark · 39 tasks × 5 runs · Opus 5.5
+
+  no-skill        ████████████████████  100%
+  Lines of code   █████████···········   47%   ▼ 53%
+  Output tokens   ███████████·········   55%   ▼ 45%
+  Cost            ███████████████·····   74%   ▼ 26%
+  Time            ████████████········   59%   ▼ 41%
+  Hidden checks passed   97%  (no-skill 96%)
+  Tests where the logic needs one   98%  (no-skill 68%)
+
+  This repo:  /ponytail-debt  (shortcuts you deferred)
+              /ponytail-audit (what's still cuttable)
+```
+
+## Honesty boundary
+
+These are benchmark averages, not this repo. NEVER print a per-repo savings
+number ("you saved X lines/tokens here"): the unbuilt version was never
+written, so there is no real baseline to subtract from in a live repo. The
+only real per-repo figures come from `/ponytail-debt` (a counted ledger), and
+this card points there instead of inventing one.
+
+## Boundaries
+
+One-shot display. Edits nothing, changes no mode.