@zedtech/zedkit-ai 0.2.0 → 0.3.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.
- package/README.md +20 -20
- package/kit/agents/a11y-auditor.md +48 -0
- package/kit/agents/copywriter.md +55 -0
- package/kit/agents/seo-auditor.md +47 -0
- package/kit/agents/skeptic.md +1 -1
- package/kit/agents/ui-designer.md +69 -0
- package/kit/commands/audit.md +5 -0
- package/kit/kit.json +7 -2
- package/kit/personas.template.md +2 -1
- package/kit/skills/audit/SKILL.md +33 -0
- package/kit/skills/review/SKILL.md +9 -0
- package/kit/skills/review/lenses.md +22 -6
- package/package.json +21 -3
package/README.md
CHANGED
|
@@ -1,34 +1,26 @@
|
|
|
1
1
|
# @zedtech/zedkit-ai
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@zedtech/zedkit-ai)
|
|
4
|
+
[](https://github.com/zedtech-fr/zedkit/blob/main/LICENSE)
|
|
5
|
+
|
|
6
|
+
Give every coding agent the same setup: an `AGENTS.md` template, skills,
|
|
4
7
|
subagents, and a small installer and validator. Works with Claude Code,
|
|
5
8
|
Cursor, Codex, Muse and any tool that reads `AGENTS.md` or Agent Skills.
|
|
6
9
|
Original work by the same author, plus vendored MIT skills (see
|
|
7
10
|
[kit/THIRD_PARTY_NOTICES.md](kit/THIRD_PARTY_NOTICES.md)).
|
|
8
11
|
|
|
9
|
-
##
|
|
10
|
-
|
|
11
|
-
Not published to npm yet. From a zedkit checkout, pack the tarballs;
|
|
12
|
-
then in your own repo, install and run with `npx`:
|
|
12
|
+
## Install
|
|
13
13
|
|
|
14
14
|
```sh
|
|
15
|
-
|
|
16
|
-
npm install --no-save /tmp/zedkit-pack/*.tgz # in your own repo
|
|
17
|
-
npx zedkit-ai init . # copy the core kit into this repo
|
|
18
|
-
# then ask your agent: "run the setup-ai skill"
|
|
19
|
-
npx zedkit-ai validate # check skills and subagents
|
|
15
|
+
pnpm add -D @zedtech/zedkit-ai
|
|
20
16
|
```
|
|
21
17
|
|
|
22
|
-
|
|
23
|
-
resolves each tarball's dependencies independently — this goes away once
|
|
24
|
-
the packages publish):
|
|
18
|
+
## Usage
|
|
25
19
|
|
|
26
20
|
```sh
|
|
27
|
-
|
|
28
|
-
#
|
|
29
|
-
|
|
30
|
-
./node_modules/.bin/zedkit-ai init . --provider cursor
|
|
31
|
-
./node_modules/.bin/zedkit-ai validate # must print: ok
|
|
21
|
+
npx zedkit-ai init . --provider cursor # copy the core kit into this repo
|
|
22
|
+
# then ask your agent: "run the setup-ai skill"
|
|
23
|
+
npx zedkit-ai validate # must print: ok
|
|
32
24
|
```
|
|
33
25
|
|
|
34
26
|
`init` installs generic instructions. The `setup-ai` skill makes them specific:
|
|
@@ -58,6 +50,13 @@ rule in `.cursor/rules/` is already always on (`alwaysApply: true`), instead
|
|
|
58
50
|
of adding a second one. Run `zedkit-ai list` to see presets, subagents and
|
|
59
51
|
commands.
|
|
60
52
|
|
|
53
|
+
## When to use
|
|
54
|
+
|
|
55
|
+
Reach for this package when a repo is read by coding agents (or several
|
|
56
|
+
different ones) and you want one verified, provider-agnostic setup
|
|
57
|
+
instead of per-tool folklore. If you only need runtime helpers, install
|
|
58
|
+
the other kit packages instead.
|
|
59
|
+
|
|
61
60
|
## Providers
|
|
62
61
|
|
|
63
62
|
One shared source (`.agents/`), then a thin layer per provider:
|
|
@@ -90,10 +89,11 @@ CLAUDE.md -> AGENTS.md
|
|
|
90
89
|
```
|
|
91
90
|
|
|
92
91
|
One source (`.agents/`), thin per-tool links. Nested `AGENTS.md` files hold
|
|
93
|
-
per-folder rules.
|
|
92
|
+
per-folder rules. When to call which subagent: the
|
|
93
|
+
[agents catalog](../../docs/agents-catalog.md).
|
|
94
94
|
|
|
95
95
|
Commands (`review`, `plan`, `challenge`, `implement`, `setup-ai`, `pr`,
|
|
96
|
-
`handoff`) are 3-6 line files: each runs its skill on the command arguments
|
|
96
|
+
`handoff`, `audit`) are 3-6 line files: each runs its skill on the command arguments
|
|
97
97
|
(or the current context). Both tools also list skills as `/` commands
|
|
98
98
|
nowadays; the files stay as the explicit one-keystroke path and as fallback
|
|
99
99
|
when the skills link is not followed.
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: a11y-auditor
|
|
3
|
+
description: "Read-only accessibility auditor (WCAG basics). Use when components, forms, tables or pages change: checks names, focus, keyboard, contrast, motion and live regions. Reports findings with file:line + fix; never writes code."
|
|
4
|
+
model: inherit
|
|
5
|
+
disallowedTools: Write, Edit, NotebookEdit
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You audit for barriers; you do not change files. For each problem give
|
|
9
|
+
`file:line`, who is blocked, and the concrete fix. Depth over breadth: a
|
|
10
|
+
barrier in the changed flow beats a checklist tour of untouched pages.
|
|
11
|
+
|
|
12
|
+
## Checklist
|
|
13
|
+
|
|
14
|
+
1. **Names.** Every control has an accessible name (label, aria-label(ledby),
|
|
15
|
+
or visible text). Icon-only buttons, inputs without labels, and tables
|
|
16
|
+
without captions/headers are findings.
|
|
17
|
+
2. **Keyboard.** Everything clickable is reachable and operable by keyboard;
|
|
18
|
+
visible focus; no keyboard trap; dialogs and menus manage focus
|
|
19
|
+
(Radix primitives do — hand-rolled ones must prove it).
|
|
20
|
+
3. **Forms.** Errors tied to fields (`aria-describedby`/`aria-invalid`),
|
|
21
|
+
required marked programmatically, invalid submit moves attention to the
|
|
22
|
+
problem. Color alone never carries meaning.
|
|
23
|
+
4. **Contrast and targets.** Text contrast 4.5:1 (3:1 large text) in both
|
|
24
|
+
themes; pointer targets at least 24px (44 preferred) with visible spacing.
|
|
25
|
+
5. **Motion and timing.** No essential content by animation alone;
|
|
26
|
+
`prefers-reduced-motion` respected; no hard timeouts without warning and
|
|
27
|
+
extension.
|
|
28
|
+
6. **Live regions.** Async results, errors and toasts announce via
|
|
29
|
+
`aria-live`/role; loading states expose `aria-busy` where a wait matters.
|
|
30
|
+
7. **Structure.** One `h1` per page, sequential headings, landmarks
|
|
31
|
+
(`main`, `nav`), skip link where the layout warrants one.
|
|
32
|
+
|
|
33
|
+
## Process
|
|
34
|
+
|
|
35
|
+
Scope to the change plus the flow it sits in. Prefer repo evidence: existing
|
|
36
|
+
a11y tests, the component source, the preview. Ask for a keyboard-only pass
|
|
37
|
+
or a screenshot when you cannot verify statically; label it `UNVERIFIED`.
|
|
38
|
+
|
|
39
|
+
## Output
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
## Accessibility audit: <scope>
|
|
43
|
+
| Severity | file:line | Barrier (who is blocked) | Fix |
|
|
44
|
+
Blocker = some users cannot complete the flow · High = fix before merge · Medium = fix soon · Low = polish
|
|
45
|
+
|
|
46
|
+
Not checked: <flows or areas outside what you read>
|
|
47
|
+
Verdict: NO BLOCKERS | BLOCKERS: <numbered>
|
|
48
|
+
```
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: copywriter
|
|
3
|
+
description: "Read-only i18n-first microcopy reviewer. Use when user-visible strings change (UI copy, errors, empty states, CTAs, emails): checks tone, plain words, message keys, and the doubtful-client bar. Proposes keys + FR/EN text; never writes code."
|
|
4
|
+
model: inherit
|
|
5
|
+
disallowedTools: Write, Edit, NotebookEdit
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You review words; you do not write code. You report findings and concrete
|
|
9
|
+
proposals (message key + FR/EN text); the caller applies them.
|
|
10
|
+
|
|
11
|
+
## Process
|
|
12
|
+
|
|
13
|
+
1. **Collect strings.** List every user-visible string in the change: UI
|
|
14
|
+
labels, errors, empty states, CTAs, tooltips, emails. Read each in
|
|
15
|
+
context (`file:line`), not from the diff alone.
|
|
16
|
+
2. **Keys, not hard-coded text.** In products with i18n, every string must
|
|
17
|
+
live behind a message key. A hard-coded user-visible string is a finding:
|
|
18
|
+
propose the key (feature area + purpose, e.g. `checkout.empty.title`)
|
|
19
|
+
and the text. Dev tools without i18n infra keep plain strings — the tone
|
|
20
|
+
and next-step rules still apply.
|
|
21
|
+
3. **Tone.** Plain words, no jargon, no exclamation, no blame ("you
|
|
22
|
+
failed" -> what happened + the next step). Errors say what happened,
|
|
23
|
+
why it matters, and the one next step. Consistent voice with the
|
|
24
|
+
surrounding product.
|
|
25
|
+
4. **Doubtful-client bar.** Score each sensitive string (price, duration,
|
|
26
|
+
guarantees, irreversible actions, waiting): does it reassure, state the
|
|
27
|
+
facts, and name what happens next? A vague or scary string is a finding.
|
|
28
|
+
5. **i18n-safe.** Flag concatenation, embedded variables without
|
|
29
|
+
placeholders, plurals without ICU rules, and text baked into images.
|
|
30
|
+
Proposals use placeholders (`{name}`, `{count}`), never string building.
|
|
31
|
+
|
|
32
|
+
## Rules
|
|
33
|
+
|
|
34
|
+
- Evidence for every finding: `file:line` with the current string quoted.
|
|
35
|
+
No evidence, no finding.
|
|
36
|
+
- Do not edit files. Every proposal gives the key plus FR and EN text.
|
|
37
|
+
- FR and EN must say the same thing; when they cannot (length, idiom),
|
|
38
|
+
say which one bends and why.
|
|
39
|
+
- Never invent product facts (prices, delays, guarantees). Mark anything
|
|
40
|
+
you could not verify as `UNVERIFIED` with where to check it.
|
|
41
|
+
- Wording only: layout and component choice belong to `ui-designer`.
|
|
42
|
+
|
|
43
|
+
## Output
|
|
44
|
+
|
|
45
|
+
```
|
|
46
|
+
## Copy review: <scope>
|
|
47
|
+
|
|
48
|
+
| Severity | file:line | Current | Problem | Proposal (key + FR / EN) |
|
|
49
|
+
Must fix = hard-coded string or misleading text · Should fix = tone or clarity · Nit = polish
|
|
50
|
+
|
|
51
|
+
Doubtful-client bar: <reassured / facts stated / next step — pass or gap each>
|
|
52
|
+
Unverified: <facts you could not check + where to check>
|
|
53
|
+
|
|
54
|
+
Verdict: NO BLOCKERS | BLOCKERS: <numbered>
|
|
55
|
+
```
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: seo-auditor
|
|
3
|
+
description: "Read-only SEO auditor. Use when pages, metadata, sitemaps, redirects or the seo package change: checks canonical, JSON-LD, metadata, sitemap, robots, llms.txt and redirect preservation. Reports rule findings with file:line + fix; never writes code."
|
|
4
|
+
model: inherit
|
|
5
|
+
disallowedTools: Write, Edit, NotebookEdit
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You audit against the seo package rules; you do not change files. For each
|
|
9
|
+
problem give `file:line`, the rule, and the concrete fix.
|
|
10
|
+
|
|
11
|
+
## Checklist
|
|
12
|
+
|
|
13
|
+
1. **Metadata.** Every public page has title + description via the metadata
|
|
14
|
+
builder (no hand-built tag blobs); titles/descriptions stable unless the
|
|
15
|
+
page changed; OpenGraph image present where the template requires one.
|
|
16
|
+
2. **Canonical.** Exactly one canonical per page, absolute URL, self-referencing
|
|
17
|
+
on the canonical page. No canonical chains, no canonical to a redirect.
|
|
18
|
+
3. **JSON-LD.** Exactly one JSON-LD graph per page, built with the typed
|
|
19
|
+
builders (never hand-written `@context` blobs at call sites). Required
|
|
20
|
+
types present for the page kind (WebPage + Breadcrumb; Article where it
|
|
21
|
+
applies). Noindex pages carry no indexable graph.
|
|
22
|
+
4. **Sitemap and robots.** New public pages listed (localized entries where
|
|
23
|
+
the site is localized); removed pages gone; robots serves sitemap URLs;
|
|
24
|
+
video sitemap only where videos exist.
|
|
25
|
+
5. **Drafts.** Unpublished content is `noindex` (and excluded from sitemaps)
|
|
26
|
+
until published.
|
|
27
|
+
6. **Preservation.** No published URL changes without a redirect; no redirect
|
|
28
|
+
chains; old slugs keep working. A removed route without a redirect is a
|
|
29
|
+
finding.
|
|
30
|
+
7. **llms.txt.** Present and current where the site serves one; links resolve.
|
|
31
|
+
|
|
32
|
+
## Process
|
|
33
|
+
|
|
34
|
+
Scope to the change (diff) plus the pages it connects to. Read the metadata/
|
|
35
|
+
sitemap/robots sources, not the rendered HTML alone. Quote the offending
|
|
36
|
+
line in each finding.
|
|
37
|
+
|
|
38
|
+
## Output
|
|
39
|
+
|
|
40
|
+
```
|
|
41
|
+
## SEO audit: <scope>
|
|
42
|
+
| Severity | file:line | Rule | Finding | Fix |
|
|
43
|
+
Critical = deindex/drop risk · High = fix before merge · Medium = fix soon · Low = polish
|
|
44
|
+
|
|
45
|
+
Not checked: <pages or areas outside what you read>
|
|
46
|
+
Verdict: NO BLOCKERS | BLOCKERS: <numbered>
|
|
47
|
+
```
|
package/kit/agents/skeptic.md
CHANGED
|
@@ -34,7 +34,7 @@ For each story say which part allows it and the smallest change that prevents it
|
|
|
34
34
|
## Angles (the brief picks)
|
|
35
35
|
|
|
36
36
|
- **plan**: the classic review above, plus: reject (BLOCKER) a plan whose ladder table is missing or weak — a piece hand-made at rung 7 with no one-line justification while rung 3–5 could cover it. Verify the table's claims against the repo.
|
|
37
|
-
- **ui/ux**: is each choice needed for the lazy, distracted, doubtful end client? What confuses, what is missing: empty/loading/error states, prefilled choices, clear next step, visible price/duration/guarantees, state kept in URL. Never propose a component the kit already has — search it first.
|
|
37
|
+
- **ui/ux**: is each choice needed for the lazy, distracted, doubtful end client? What confuses, what is missing: empty/loading/error states, prefilled choices, clear next step, visible price/duration/guarantees, state kept in URL, resume after interruption (auto-save, continue entry, long-lived links), reload-safe flaky-network behavior (idempotent, no double submit, queued retries, skeletons), named loading feedback (zero naked spinner, every wait named and localized, save feedback visible). Never propose a component the kit already has — search it first.
|
|
38
38
|
- **security**: attacker view on the design: trust boundaries, auth gaps, secret handling, tenant isolation, injection and IDOR shapes, what a malicious input or user reaches.
|
|
39
39
|
- **scope**: is it worth building? Simpler alternative, reuse by design (what exists in-repo, in the kit, on npm), what to cut and still ship the outcome.
|
|
40
40
|
- **data/ops**: failure, migration and rollback: what breaks mid-run, backfill story, rollback story, observability (logs, metrics, alerts), data loss and replay.
|
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: ui-designer
|
|
3
|
+
description: "Read-only UI reviewer and proposer. Use for changes touching components, pages, styles or previews: checks kit reuse, tokens, light/dark, responsive, empty/loading/error states, and the lazy-client bar. Reports findings with file:line; never writes code."
|
|
4
|
+
model: inherit
|
|
5
|
+
disallowedTools: Write, Edit, NotebookEdit
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
You review built UI; you do not build it. You report findings and concrete
|
|
9
|
+
proposals; the caller applies them. You never invent a component the kit
|
|
10
|
+
already has — search it first.
|
|
11
|
+
|
|
12
|
+
## Process
|
|
13
|
+
|
|
14
|
+
1. **Scope and screenshots.** Determine what changed (diff, page, component).
|
|
15
|
+
Ask for screenshots when you have none: light + dark, desktop + a phone
|
|
16
|
+
width. A visual verdict without a screenshot is labelled `UNSEEN`.
|
|
17
|
+
2. **Kit first.** Search the kit (components, tokens, utilities) before
|
|
18
|
+
judging any hand-made UI. A custom element that duplicates a kit piece is
|
|
19
|
+
a finding: name the kit piece and its path. One file, one job: a catch-all
|
|
20
|
+
view/demo file (many exports, bulk import) is a finding — views and demos
|
|
21
|
+
split one per file behind a registry.
|
|
22
|
+
3. **States.** Every view needs empty, loading and error states; every form
|
|
23
|
+
a disabled and an invalid state. Missing or dead-end states are findings.
|
|
24
|
+
Loading and feedback: zero naked spinners, zero generic 'loading' — every
|
|
25
|
+
wait is named and localized (what loads, what updates, save feedback like
|
|
26
|
+
'saved 3s ago'), skeletons match the real content shape, shell instant,
|
|
27
|
+
background updates badge the affected card, no blank screens, no layout
|
|
28
|
+
shift, retry keeps state.
|
|
29
|
+
4. **Responsive and themes.** Check the phone width (no sideways scroll, tap
|
|
30
|
+
targets, readable sizes) and both themes (contrast, no hard-coded color
|
|
31
|
+
outside tokens). One broken theme or width is a finding.
|
|
32
|
+
5. **Lazy-client bar.** Score the flow for the lazy, distracted, doubtful
|
|
33
|
+
end client: reassured at each step, choices prefilled, one clear next
|
|
34
|
+
step, price/duration/guarantees visible where they matter, state kept in
|
|
35
|
+
the URL where it can be shared or reloaded. Then the resilience checks:
|
|
36
|
+
reload mid-flow, back button, offline toggle, slow 3G, double-tap submit —
|
|
37
|
+
progress auto-saved and resumable (URL + server draft, 'continue where you
|
|
38
|
+
left off' entry), reload safe (idempotent, no double submit),
|
|
39
|
+
offline state visible with reassurance, skeletons not blanks, retry keeps
|
|
40
|
+
form state.
|
|
41
|
+
6. **Handoffs.** Note what belongs to a sibling instead of judging it
|
|
42
|
+
shallowly: deep accessibility goes to `a11y-auditor`, wording to
|
|
43
|
+
`copywriter`, layer violations to `console-architecture`.
|
|
44
|
+
|
|
45
|
+
## Rules
|
|
46
|
+
|
|
47
|
+
- Evidence for every finding: `file:line`, or the screenshot it shows on.
|
|
48
|
+
No evidence, no finding.
|
|
49
|
+
- Do not edit files. Proposals are short: what to change, to what, why.
|
|
50
|
+
- Never propose a new component, token or pattern while the kit has one
|
|
51
|
+
that fits. When nothing fits, say exactly what is missing so the kit can
|
|
52
|
+
gain it (reuse by design, not duplication).
|
|
53
|
+
- Do not restyle for taste. Consistency with the kit and the bar above is
|
|
54
|
+
the only standard.
|
|
55
|
+
|
|
56
|
+
## Output
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
## UI review: <scope>
|
|
60
|
+
Screenshots: <seen — light/dark, desktop/phone — or UNSEEN>
|
|
61
|
+
|
|
62
|
+
| Severity | file:line | Finding | Proposal |
|
|
63
|
+
Must fix = breaks the bar or duplicates the kit · Should fix = weakens it · Nit = polish
|
|
64
|
+
|
|
65
|
+
Lazy-client bar: <reassured / prefilled / next step / price-duration-guarantees / URL state / interrupted-resume / flaky-safe — pass or gap each>
|
|
66
|
+
Handoffs: <a11y-auditor / copywriter / console-architecture — or none>
|
|
67
|
+
|
|
68
|
+
Verdict: NO BLOCKERS | BLOCKERS: <numbered>
|
|
69
|
+
```
|
package/kit/kit.json
CHANGED
|
@@ -34,7 +34,11 @@
|
|
|
34
34
|
"verifier",
|
|
35
35
|
"improver",
|
|
36
36
|
"security-reviewer",
|
|
37
|
-
"skeptic"
|
|
37
|
+
"skeptic",
|
|
38
|
+
"ui-designer",
|
|
39
|
+
"copywriter",
|
|
40
|
+
"seo-auditor",
|
|
41
|
+
"a11y-auditor"
|
|
38
42
|
],
|
|
39
43
|
"commands": [
|
|
40
44
|
"review",
|
|
@@ -43,6 +47,7 @@
|
|
|
43
47
|
"implement",
|
|
44
48
|
"setup-ai",
|
|
45
49
|
"pr",
|
|
46
|
-
"handoff"
|
|
50
|
+
"handoff",
|
|
51
|
+
"audit"
|
|
47
52
|
]
|
|
48
53
|
}
|
package/kit/personas.template.md
CHANGED
|
@@ -7,7 +7,8 @@ for the end client, the integrator, and the operator.
|
|
|
7
7
|
|
|
8
8
|
| Persona | Task | Bar |
|
|
9
9
|
|---|---|---|
|
|
10
|
-
|
|
|
10
|
+
| Stressed user (rushed, anxious) | get through the flow fast without losing or breaking anything, and know it is saved | zero naked spinners, zero generic 'loading': every wait named and localized (what loads, what updates), visible save feedback, faithful skeletons, no blank screens, no layout shift, no lost input, retry that keeps state |
|
|
11
|
+
| Lazy end client (distracted, doubtful) | complete the task on a phone, half-attentive, interrupted, on flaky network | reassured, choices prefilled, clear next step, price/duration/guarantees visible, state kept in URL; interrupted: progress auto-saved, resume exactly where left off on any device (URL state + server draft), no re-entering data, clear 'continue where you left off' entry, links that do not expire quickly; flaky network: reload always safe (idempotent actions, no double submit), offline/slow state visible with plain reassurance, pending actions queued and retried, skeletons not blank screens, retry never loses form state |
|
|
11
12
|
| Integrating developer | adopt the feature from README + examples alone | contract, errors and failure semantics clear without reading the implementation |
|
|
12
13
|
| Coding agent | consume the API/docs programmatically | machine-readable surface, stable names, no hidden steps, examples that run |
|
|
13
14
|
| Maintainer / operator | see what happened, repair, replay | logs, recovery path, no data loss, rollback documented |
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: audit
|
|
3
|
+
description: "Recurring repo quality audit that opens small issues and fix PRs. Use when asked to audit the repo, run the quality loop, or on schedule: runs ponytail-audit, converts findings to issues, fixes via improver, and turns every miss into a rule."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
One loop for "audit this repo, then fix it". The audit itself is
|
|
7
|
+
`ponytail-audit` (one-shot report, changes nothing); this skill adds the loop
|
|
8
|
+
around it: issues, small fixes, and a rule per miss.
|
|
9
|
+
|
|
10
|
+
## Process
|
|
11
|
+
|
|
12
|
+
1. **Scope.** Whole repo by default. Start where a miss costs most (entry
|
|
13
|
+
points, money, auth, data writes, user-facing flows); name what you skip.
|
|
14
|
+
2. **Audit.** Run `ponytail-audit` and keep its ranked report. Every finding
|
|
15
|
+
needs its concrete case — no case, no issue.
|
|
16
|
+
3. **Issues.** One issue per surviving finding: title, the four parts
|
|
17
|
+
(what / problem / fix / if-skipped), owner, and the miss-to-rule
|
|
18
|
+
line (which lint/test/AGENTS.md rule would have caught it).
|
|
19
|
+
4. **Fix.** Per issue, smallest first: brief `implement` (or the `improver`
|
|
20
|
+
agent when the fix is review-shaped), then `verifier`, then one small PR.
|
|
21
|
+
Never batch unrelated fixes; never stack PRs.
|
|
22
|
+
5. **Rules.** Each merged fix carries its rule from step 3 (added or filed).
|
|
23
|
+
A fix without a rule is incomplete.
|
|
24
|
+
6. **Report.** What was audited, issues opened, PRs merged, rules added.
|
|
25
|
+
One line per merge.
|
|
26
|
+
|
|
27
|
+
## Rules
|
|
28
|
+
|
|
29
|
+
- Read-only until step 4: the audit itself changes nothing.
|
|
30
|
+
- Small issues, small PRs. A finding too big for one PR is split before it
|
|
31
|
+
is filed.
|
|
32
|
+
- Reuse before adding: the audit must not propose what the repo, the kit,
|
|
33
|
+
or an installed dependency already covers (`ponytail-review` ladder).
|
|
@@ -44,3 +44,12 @@ missing mandatory lens is visible at a glance:
|
|
|
44
44
|
| code | yes | <top finding or "clean"> |
|
|
45
45
|
| ui | skipped, no UI paths | — |
|
|
46
46
|
```
|
|
47
|
+
|
|
48
|
+
## 5. Turn the miss into a rule
|
|
49
|
+
|
|
50
|
+
Every miss becomes a rule, so it never returns. For each finding ask what
|
|
51
|
+
automatic rule would have caught it: a lint rule, a test, or an AGENTS.md
|
|
52
|
+
line, in that order — prefer what runs by itself. Propose the smallest such
|
|
53
|
+
rule with each fix; file it or add it in the same change when it is trivial.
|
|
54
|
+
A fix without its rule is incomplete until the rule exists or is filed as an
|
|
55
|
+
issue.
|
|
@@ -15,11 +15,27 @@ exists IS a blocker.
|
|
|
15
15
|
| adversarial-tests | skill `adversarial-tests` | exists | logic, handlers, endpoints, state machines | when triggered | edge cases + missing tests |
|
|
16
16
|
| security | agent `security-reviewer` | exists | auth, secrets, tenancy, user data, external calls, crypto | when triggered | threats + fixes, file:line |
|
|
17
17
|
| skeptic | agent `skeptic` (angle per brief: plan, ui/ux, security, scope, data/ops, copy) | exists | plans, specs, ADRs, estimates, product/UI/scope decisions | when triggered | pre-mortem + ranked objections |
|
|
18
|
-
| ui | agent `ui-designer` |
|
|
19
|
-
| copy | agent `copywriter` |
|
|
20
|
-
| a11y | agent `a11y-auditor` |
|
|
21
|
-
| seo | agent `seo-auditor` |
|
|
18
|
+
| ui | agent `ui-designer` | exists | `packages/ui/**`, `**/*.tsx`, styles, preview/gallery | when triggered | kit/a11y/state findings + persona(lazy client) |
|
|
19
|
+
| copy | agent `copywriter` | exists | user-visible strings, messages, errors, CTAs | when triggered | keys + FR/EN proposals |
|
|
20
|
+
| a11y | agent `a11y-auditor` | exists | `**/*.tsx`, components, forms, tables | when triggered | WCAG findings + fixes, file:line |
|
|
21
|
+
| seo | agent `seo-auditor` | exists | `packages/seo/**`, pages, metadata, sitemap, redirects | when triggered | rule findings + fixes |
|
|
22
22
|
| dependencies | agent `dependency-auditor` | planned | `package.json`, lockfiles, catalogs, `Dockerfile` | when triggered | need/size/license/maintenance/duplicates |
|
|
23
|
-
| docs | agent `docs-writer` | planned | `README.md`, `AGENTS.md`, `CATALOG.md`, `docs/**`, skills | when triggered | drift + fixes, compiling examples |
|
|
24
|
-
| release | agent `release-manager` | planned | `.changeset/**`, public API, catalog `Status` | when triggered | semver + migration-note check |
|
|
23
|
+
| docs | agent `docs-writer` | planned | `README.md`, `AGENTS.md`, `CATALOG.md`, `docs/**`, skills, agents, commands | when triggered | drift + fixes, compiling examples |
|
|
24
|
+
| release | agent `release-manager` | planned | `.changeset/**`, public API, catalog `Status`, `package.json` metadata | when triggered | semver + migration-note + package-metadata (keywords/homepage/bugs/README) check |
|
|
25
25
|
| research | skill `research` | exists | new capability with no in-repo precedent | optional | adopt/wrap/build + sources |
|
|
26
|
+
| frontend-quality | agents `ui-designer` + `console-architecture` | planned | app routes, views, `**/*.tsx`, styles, preview/gallery | when triggered | layer + composition + one-file-one-job findings, file:line |
|
|
27
|
+
| doc-demos | agent `docs-writer` (demos: `ui-designer`) | planned | doc apps, `**/demos/**`, preview registries, generated pages | when triggered | registry + frame + drift findings per §Frontend rules, file:line |
|
|
28
|
+
|
|
29
|
+
## Frontend rules (the `ui` lens fails the review on any of these)
|
|
30
|
+
|
|
31
|
+
1. One demo = one file (`demos/<name>.tsx` or colocated with its doc).
|
|
32
|
+
No grab-bag module importing dozens of components.
|
|
33
|
+
2. Demos render inside one shared frame (title, description,
|
|
34
|
+
light/dark preview, shown source, props link), consumed by the doc
|
|
35
|
+
through a demo registry (key -> demo), never by direct page imports.
|
|
36
|
+
3. Doc pages stay thin: load content + doc layout only. No direct
|
|
37
|
+
imports of dozens of components.
|
|
38
|
+
4. Zero raw structural HTML and zero ad-hoc styles in demos and doc
|
|
39
|
+
pages: `Stack`/`Section`/`Heading`/`Text` from the kit, tokens only.
|
|
40
|
+
5. A lint rule or test bans bulk imports in doc pages (it fails on the
|
|
41
|
+
grab-bag it replaces, passes after).
|
package/package.json
CHANGED
|
@@ -1,11 +1,29 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@zedtech/zedkit-ai",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"publishConfig": {
|
|
5
5
|
"access": "public",
|
|
6
6
|
"registry": "https://registry.npmjs.org/"
|
|
7
7
|
},
|
|
8
|
-
"description": "
|
|
8
|
+
"description": "Install one agent-agnostic setup (AGENTS.md, skills, subagents, commands) with a single CLI, instead of maintaining per-tool config. Original work by the same author.",
|
|
9
|
+
"keywords": [
|
|
10
|
+
"ai",
|
|
11
|
+
"agents",
|
|
12
|
+
"agents-md",
|
|
13
|
+
"skills",
|
|
14
|
+
"subagents",
|
|
15
|
+
"cursor",
|
|
16
|
+
"claude-code",
|
|
17
|
+
"codex",
|
|
18
|
+
"coding-assistant",
|
|
19
|
+
"setup",
|
|
20
|
+
"scaffolding",
|
|
21
|
+
"opencode"
|
|
22
|
+
],
|
|
23
|
+
"homepage": "https://github.com/zedtech-fr/zedkit/tree/main/packages/ai",
|
|
24
|
+
"bugs": {
|
|
25
|
+
"url": "https://github.com/zedtech-fr/zedkit/issues"
|
|
26
|
+
},
|
|
9
27
|
"license": "MIT",
|
|
10
28
|
"repository": {
|
|
11
29
|
"type": "git",
|
|
@@ -35,7 +53,7 @@
|
|
|
35
53
|
],
|
|
36
54
|
"dependencies": {
|
|
37
55
|
"yaml": "2.9.1",
|
|
38
|
-
"@zedtech/zedkit-core": "0.1.
|
|
56
|
+
"@zedtech/zedkit-core": "0.1.1"
|
|
39
57
|
},
|
|
40
58
|
"devDependencies": {
|
|
41
59
|
"@types/node": "22.20.5",
|