@zedtech/zedkit-ai 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,76 @@
+---
+name: ponytail-help
+description: >
+  Quick reference for ponytail levels, skills and commands. One-shot display.
+  Use for /ponytail-help, "ponytail help", "how do I use ponytail".
+---
+
+# Ponytail Help
+
+Display this reference card when invoked. One-shot, do NOT change mode,
+write flag files, or persist anything.
+
+## Levels
+
+| Level | Trigger | What change |
+|-------|---------|-------------|
+| **Lite** | `/ponytail lite` | Build what was asked, name the smaller option in one line. |
+| **Full** | `/ponytail` | The smallest complete change, a check where the logic needs one, and a reply that names what was skipped and any risk. Default. |
+| **Ultra** | `/ponytail ultra` | Also questions the request and pushes back before building. |
+
+Level sticks until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it does |
+|-------|---------|--------------|
+| **ponytail** | `/ponytail` | Lazy mode itself: least new code, clear replies that name skipped work and risks. |
+| **ponytail-review** | `/ponytail-review` | Quality review of a diff: bugs, security, load, missing tests, speed, what to cut. Each finding says what goes wrong and how to fix it. |
+| **ponytail-audit** | `/ponytail-audit` | The same quality review for the whole repo, ranked. |
+| **ponytail-debt** | `/ponytail-debt` | Harvest `shortcut:` comments into a tracked ledger. |
+| **ponytail-gain** | `/ponytail-gain` | Measured-impact scoreboard: less code, less cost, more speed. |
+| **ponytail-help** | `/ponytail-help` | This card. |
+
+In Codex CLI and the IDE extension, invoke skills with `$ponytail:ponytail`,
+`$ponytail:ponytail-review`, or `$ponytail:ponytail-help`. Claude Code and OpenCode use the
+slash-command forms above (OpenCode ships all six as slash commands).
+
+## Deactivate
+
+Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
+`/ponytail off` also works.
+
+## Band (Claude Code)
+
+`/ponytail band` hides the band above the prompt, the same command brings it back.
+`/ponytail band on` and `/ponytail band off` set it directly. The level stays.
+`/ponytail band import` adds your past Claude Code sessions (cost, agent time, tokens) to the board.
+
+## Configure Default Mode
+
+Default mode = `full`, auto-active every session. Change it:
+
+**Environment variable** (highest priority):
+```bash
+export PONYTAIL_DEFAULT_MODE=ultra
+```
+
+**Config file** (`~/.config/ponytail/config.json`, Windows: `%APPDATA%\ponytail\config.json`):
+```json
+{ "defaultMode": "lite" }
+```
+
+Set `"off"` to disable auto-activation on session start, activate manually
+with `/ponytail` when wanted.
+
+Resolution: env var > config file > `full`.
+
+## Update
+
+Enable auto-update once: open `/plugin`, go to Marketplaces, pick ponytail, Enable auto-update. Claude Code then pulls new versions at startup (run `/reload-plugins` when it prompts). Manual refresh: `/plugin marketplace update ponytail` then `/reload-plugins`.
+
+If `/plugin` is not recognized, your Claude Code is out of date. Update it (`npm install -g @anthropic-ai/claude-code@latest`, or `brew upgrade claude-code`) and restart. Other hosts use their own update flow.
+
+## More
+
+Full docs + examples: https://github.com/DietrichGebert/ponytail

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

@@ -0,0 +1,119 @@
+---
+name: ponytail-review
+description: >
+  Quality review of a change: is the logic right, is it safe, does it hold
+  under real load, is risky code tested, is it fast enough, and is every line
+  needed. Reads the connected code, not only the diff. Each finding is
+  explained in plain English. Use for "review this", "code review", "review
+  the last commit", "review my PR", "is this over-engineered", /ponytail-review.
+---
+
+Review a change like the senior developer who 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. The ladder: does this code deserve to exist?
+
+For every piece of new code, new file, or new dependency in the diff,
+climb down and stop at the first rung that holds. Name the rung.
+A piece that skipped a higher rung is a finding.
+
+1. Does this need to exist at all? Skip what nobody asked for; say so in
+   one line.
+2. Already in this codebase? Reuse the helper, component, service, pattern.
+3. Does the standard library do it? Use it.
+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.
+5. Does an already-installed dependency solve it? Never add one for a few
+   lines.
+6. Can it be one line a reader gets at a glance? One line.
+7. Only then: the minimum code that works.
+
+## 2. Understand first
+
+- Review what the user names: uncommitted or staged changes, a branch, a PR
+  link, or files. Nothing named: the uncommitted changes, or the last commit
+  if there are none.
+- Read the diff, then the code it touches: callers of every changed function,
+  the functions it calls, the tests, the README.
+- Trace the real flow: where data comes in, what is stored, what goes out.
+- A change can break code it does not touch. When a signature, return value
+  or behavior changes, grep every caller.
+- Find the expected load in the repo (README, deploy config): one person
+  running a script, or many users and processes at once. Judge scale against
+  that, and say which load you assumed.
+
+## 3. Look for
+
+1. **Bug:** wrong result, crash, missed edge case (empty, zero, last item,
+   rounding, time zones), a caller broken by the change, a fix applied in one
+   caller while the shared function stays broken.
+2. **Risk:** security holes (injection, weak randomness, secrets, 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 new logic (a branch, a parser, money, security,
+   data writes, a bug fix) 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. Climb the
+   ladder in section 1 first and name the first rung that holds.
+   - delete: dead code, unused options, speculative features
+   - reuse: the repo already has this helper (name the path)
+   - stdlib / native: the standard library or platform already does it; a
+     new dependency for a few lines
+   - yagni: abstraction with one implementation, config nobody sets
+   - merge: near-copies that must change together
+   - split: one function 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.
+
+## 4. Check before you report
+
+- Every finding needs a concrete case: "this input or situation leads to this
+  wrong result". No case, no finding.
+- Re-read the lines and confirm: the caller exists, the value can really be
+  empty, the code really is unused.
+- 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.
+
+## 5. 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 change does:` in two or three sentences.
+
+Then the findings in three groups, 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".
+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: Ship.` or `Verdict: fix 1 and 3 first.`
+- `Lean: -<N> lines possible.` when lean findings exist.
+- `Not checked:` one line, if something mattered and you could not check it.
+
+Nothing found: `What this change does:`, then `Looks good. Ship.` and one line
+on what you checked.
+
+Lists findings, changes no code.

package/kit/skills/pr/CREDITS.md

@@ -0,0 +1,3 @@
+# Credits
+
+The **Summary** section's menu of visuals (pseudocode, call trees, component trees, file trees, Mermaid, diffs) and its placement guidance come from [Dex Horthy](https://github.com/dexhorthy)'s [`show-me`](https://github.com/humanlayer/humanlayer) skill, reproduced almost word for word and aimed at a diff instead of a live conversation. `pr` does not depend on `show-me` as a skill (it isn't part of this repo, and a hard dependency would break standalone installs), so the content is copied in rather than pointed at; this file is the attribution a dependency would otherwise have carried.

package/kit/skills/pr/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: pr
+description: "Use when writing a PR body."
+metadata:
+  credits:
+    skill: show-me
+    author: Dex Horthy
+    organisation: Humanlayer
+    url: "https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md"
+---
+
+Use this template for writing the PR body:
+
+```markdown
+## Summary
+
+<diagram, diff-sketch, or tree>
+
+## Evidence
+
+- **Before:** <screenshot/output/failing test run>
+  **After:** <screenshot/output/passing test run>
+
+## Merge Danger
+
+**Door:** <one-way or two-way>
+
+<optional: description>
+
+**Blast Radius:** <one-word description>
+
+<optional: potential ramifications of merge>
+```
+
+## Sections
+
+Skip all preambles and keep prose brief. Use the user's domain language from `GLOSSARY.md`.
+
+### Summary
+
+Pick the smallest view that makes the key point clear.
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```text
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+For a file-layout change:
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+For a call-tree or call-stack change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+For a state or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1);
+  return `use the ${skillName} skill`;
+}
+```
+
+#### Guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.
+
+### Evidence
+
+Concrete evidence that the change works. Show a before and after.
+
+Screenshots are S-tier - when the environment is set up for it and the change is visual.
+
+Execution-based evidence is A-tier. Test results, console output. Show the exact test that now fails and passes, using pseudocode.
+
+### Merge Danger
+
+Describe whether it's a one-way or two-way door. You can walk back through two-way doors, but not one-way doors. A PR that is cheap to roll back is lower risk. Changes that involve destructive actions or hard-to-reverse decisions are one-way doors.
+
+The blast radius is the potential impact or scope of the changes introduced by this PR. Consider all possibilities. Examples are layout shift, breakages for consumers, mobile responsiveness, etc.

package/kit/skills/pr/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "PR"
+  short_description: "Write a PR body that's fast to review"

package/kit/skills/research/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: research
+description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.
+---
+
+Spin up a **background agent** to do the research, so you keep working while it reads.
+
+Its job:
+
+1. Investigate the question against **primary sources** (official docs, source code, specs, first-party APIs), not a secondary write-up of them. Follow every claim back to the source that owns it.
+2. Write the findings to a single Markdown file, citing each claim's source.
+3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.

package/kit/skills/research/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Research"
+  short_description: "Research from high-trust sources"

package/kit/skills/retro/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: retro
+description: "Conduct a retrospective on a coding session."
+disable-model-invocation: true
+---
+
+The user has asked for a **retrospective**. You are suggesting improvements to the coding agent's **environment** to improve future runs.
+
+## Steps
+
+1. Call the Skill tool with `writing-for-agents` for the writing style guide.
+
+2. Read the primary sources for the session the user specifies. This may mean searching through session logs on this machine. If the user doesn't specify a session, default to the current one.
+
+3. Look for candidates for improvement in these categories.
+
+- **Navigation**: how easy was it for the agent to find the right files? Are there hidden dependencies between files? Would a **navigation pointer** make it easier? _Use when_ the session took a long time to find a piece of information.
+- **Automated checks**: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? Read the repo's own check command first (its `package.json`/build-tool `lint`/`check` scripts, its CI workflow), so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. A repo with no **guardrail** (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding: an un-linted repo is a standing missed opportunity, not a neutral default. _Use when_ the agent made a mistake an automated check could have caught, or the repo has no guardrail at all.
+- **Coding standards**: should the **reviewer agent** be given a new rule to enforce? Should an existing rule be removed or clarified? Classify the violation first: a **mechanical** one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop: a custom rule in the repo's own linter, a new pre-commit hook, or a new CI job, whichever the repo's language and existing guardrail make cheapest. Default to building the check over writing the rule. Reserve `CODING_STANDARDS.md` for genuine **judgement calls** (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). _Use when_ the reviewer agent failed to catch a mistake.
+- **Global AGENTS.md**: are there any steering instructions that should be moved to coding standards (or automated checks) instead? _Use when_ the AGENTS.md file is particularly large - in the repo OR the user's global scope.
+- **Tool economy**: did the agent make expensive tool calls that could be streamlined? Is there any custom tooling (CLI's, MCP's) that is particularly token-inefficient? _Use when_ the agent made an expensive tool call.
+- **No-ops**: look for instructions in steering files that don't modify the agent's behavior. _Use when_ the steering files are large and unwieldy.
+- **Information access**: look for opportunities to increase the agent's access to information. Teeing dev server logs, readonly access to third-party services. _Use when_ a crucial piece of information was not available to the agent.
+
+4. Present these candidates to the user, in order of severity.
+
+## Reference
+
+### Implementation vs Review
+
+Remember that all work goes through two stages: implementation and review. The implementation agent has the most **context pressure**. They are responsible for exploration, writing code, and debugging failures.
+
+The review agent has the least context pressure - it receives a diff, so no exploration needed. It often does not need to write code or debug.
+
+This means that the review agent should be responsible for imposing coding standards, not the implementation agent.
+
+### Files
+
+You have access to several files in the repo:
+
+- `CLAUDE.md`/`AGENTS.md`: these files are pushed to the context window of any agent working in this repo. They should be used incredibly sparingly, usually only for **navigation pointers** to other files.
+- `CODING_STANDARDS.md`: this file is read during review, not implementation. Add **navigation pointers** to docs folders if the standards file gets more than 1,000 lines long.
+- Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones.
+- Skills: use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the `writing-for-agents` skill.

package/kit/skills/retro/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Retro"
+  short_description: "Conduct a retrospective on a coding session."
+policy:
+  allow_implicit_invocation: false

package/kit/skills/review/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: review
+description: "Single entry point for reviewing a change: pins the diff once, runs the right review lenses in parallel subagents, dedupes and returns one verdict. Use when asked to review a branch, PR, commit range or work-in-progress."
+---
+
+One command for "review this". It picks the lenses, pins the diff once, fans
+out, then merges everything into a single report with one verdict.
+
+## 1. Pin the diff
+
+Resolve the fixed point the user gave (commit, branch, tag, `HEAD~N`; ask when
+missing) and capture it once: `git diff <fixed-point>...HEAD` plus
+`git log <fixed-point>..HEAD --oneline`. Fail fast here on a bad ref or an
+empty diff — never inside the subagents.
+
+## 2. Pick the lenses
+
+Always: `code-review` (its Standards and Spec axes; Standards applies
+`ponytail-review`, never ad-hoc smells) and `persona-review` (does the change
+serve its real audience). Add `adversarial-tests` when logic, handlers or
+endpoints changed; add the `security-reviewer` subagent when auth, secrets,
+tenancy, user data or external calls are touched.
+
+## 3. Fan out
+
+One subagent per lens, all in parallel (see `parallel-work` for the pattern;
+skip the fan-out and run inline when the diff is a few lines). Every brief is
+self-contained: the diff command, the lens skill to apply, and the evidence
+rule from `ground-truth` — every finding cites `file:line`, or it is not a
+finding. When the change implements a plan with a ladder table, brief
+`code-review` to verify the table against the diff.
+
+## 4. Merge
+
+Dedupe across lenses (same location and issue keep the strongest wording),
+rank by severity, and end with exactly one verdict: ship, fix-then-ship (list
+the blockers), or rework. One report, no per-lens sections.

package/kit/skills/rules-upkeep/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: rules-upkeep
+description: "Keep AGENTS.md, skills and subagents in sync with decisions made in a session, and in valid format. Use at the end of a coding task when a decision, correction or convention came up, and whenever creating or editing agent instructions."
+---
+
+# Rules upkeep
+
+The AI setup (`AGENTS.md`, `.agents/skills`, `.agents/agents`) is code: it drifts unless you maintain it. Future sessions only know what is written there.
+
+## When to run
+
+At the end of any coding task, and when one of these happened:
+
+- A design choice was settled or clarified: where a boundary sits, which pattern wins, which exception is allowed.
+- A review showed that the current rules **allow** a bad pattern.
+- You were corrected twice on the same thing.
+- A new convention was adopted (naming, testing, wiring).
+- A shortcut with a stated limit was left in code and will recur.
+
+## What to do
+
+1. Locate the gap: which file says nothing, is out of date, or disagrees with the decision?
+2. Make the **smallest additive edit** in the same turn, in the natural home. Do not ask first. Do not create a new file when an existing one fits.
+3. Change every file the decision touches, and no more. Link to the canonical text instead of copying it.
+4. Removing a rule needs the user's confirmation.
+5. Finish with one line: `Rules: none` or `Rules: <file> — <what changed>`.
+
+## Where things go
+
+| Content | Home |
+|---|---|
+| Non-negotiables for the whole repo, commands, map | root `AGENTS.md`, short (it is always loaded) |
+| Rules for one folder | `AGENTS.md` in that folder (read when working there) |
+| A repeatable workflow with steps | a skill |
+| A persona with a narrow job and fresh context | a subagent |
+
+Do not write down what the code already shows (file lists, signatures). Write only what a reader cannot get from the code: the why, the limits, the traps.
+
+## Formats that fail silently
+
+| Artifact | Required | Otherwise |
+|---|---|---|
+| Skill | folder `<name>/SKILL.md`, `name` equals the folder | may never be loaded |
+| Subagent | file `<name>.md`, `description` on a single line | a folded or block description can be shown as `>` and the agent cannot decide when to be used |
+| Any file | LF line endings | a trailing `\r` breaks YAML values |
+| Subagent `model` | omit it, or `inherit` | an unknown model id can fall back silently; list the models the tool accepts before pinning one |
+
+Run `zedkit-ai validate` (package `@zedtech/zedkit-ai`, or the repo's equivalent) after editing. It checks these.
+
+## Writing for agents
+
+- Imperative, concrete, short. One rule per bullet. Examples beat adjectives.
+- Put the trigger in the skill `description`: "Use when ...". That line decides whether it is ever loaded.
+- Large reference material goes in a sibling file, linked from the skill, not in `SKILL.md`.
+- Never put secrets, customer names or internal URLs in instructions.