@igorlau/dotagents 1.0.21 → 1.0.22
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 +65 -65
- package/THIRD_PARTY_NOTICES.md +101 -6
- package/dist/build-info.json +1 -1
- package/dist/catalog.js +3 -3
- package/dist/cli.js +1 -1
- package/dist/commands.js +7 -5
- package/dist/manifest.js +8 -1
- package/dist/paths.js +0 -4
- package/dist/targets.js +3 -9
- package/dist/wizard.js +1 -1
- package/package.json +5 -3
- package/{plugin/rules → rules}/comments.upstream.json +1 -1
- package/{plugin/rules → rules}/ponytail.md +1 -1
- package/{plugin/rules → rules}/ponytail.upstream.json +1 -1
- package/{plugin/rules → rules}/writing.md +1 -2
- package/{plugin/rules → rules}/writing.upstream.json +1 -1
- package/{plugin/scaffold → scaffold}/AGENTS.md.tmpl +1 -1
- package/{plugin/skills → skills}/dot-code-review/SKILL.md +2 -0
- package/{plugin/skills → skills}/dot-code-review/UPSTREAM.json +1 -1
- package/skills/dot-code-review/references/finding-classes.md +33 -0
- package/{plugin/skills → skills}/dot-comments/UPSTREAM.json +1 -1
- package/{plugin/skills → skills}/dot-commit/SKILL.md +0 -2
- package/skills/dot-correct/UPSTREAM.json +8 -0
- package/{plugin/skills → skills}/dot-debug/UPSTREAM.json +1 -1
- package/{plugin/skills → skills}/dot-grilling/UPSTREAM.json +2 -2
- package/{plugin/skills → skills}/dot-handoff/UPSTREAM.json +1 -1
- package/{plugin/skills → skills}/dot-implement/SKILL.md +2 -2
- package/{plugin/skills → skills}/dot-plan/SKILL.md +3 -1
- package/{plugin/skills → skills}/dot-roadmap/SKILL.md +7 -4
- package/skills/dot-security-audit/SKILL.md +87 -0
- package/skills/dot-security-audit/UPSTREAM.json +8 -0
- package/skills/dot-security-audit/references/AI-AND-LLM.md +83 -0
- package/skills/dot-security-audit/references/ATTACK-CLASSES.md +130 -0
- package/skills/dot-security-audit/references/CLIENT-SIDE.md +83 -0
- package/skills/dot-security-audit/references/CLOUD-AND-DEPLOYMENT.md +86 -0
- package/skills/dot-security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md +84 -0
- package/skills/dot-security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -0
- package/skills/dot-security-audit/references/MEMORY-SAFETY-AND-BINARY.md +101 -0
- package/skills/dot-security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md +81 -0
- package/skills/dot-security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -0
- package/skills/dot-security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md +73 -0
- package/skills/dot-security-audit/references/WEB-PROTOCOL-AND-AUTH.md +105 -0
- package/skills/dot-security-changes/SKILL.md +68 -0
- package/{plugin/skills → skills}/dot-testing/UPSTREAM.json +1 -1
- package/skills/dot-ui-review/SKILL.md +79 -0
- package/skills/dot-ui-review/UPSTREAM.json +8 -0
- package/skills/dot-ux-review/SKILL.md +50 -0
- package/skills/dot-ux-review/UPSTREAM.json +8 -0
- package/skills/dot-ux-review/references/web-interface-guidelines.md +191 -0
- package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/SKILL.md +9 -30
- package/skills/dot-walkthrough-branch/references/layers.md +38 -0
- package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/scripts/page.mjs +39 -10
- package/skills/dot-walkthrough-changes/SKILL.md +62 -0
- package/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
- package/plugin/.claude-plugin/plugin.json +0 -10
- package/plugin/agents/dot-implementer.md +0 -27
- package/plugin/agents/dot-reviewer.md +0 -44
- package/plugin/agents/dot-tester.md +0 -25
- package/plugin/hooks/check.mjs +0 -118
- package/plugin/hooks/hooks.json +0 -54
- package/plugin/hooks/rules.mjs +0 -27
- package/plugin/skills/dot-correct/UPSTREAM.json +0 -8
- package/plugin/skills/dot-correct/agents/openai.yaml +0 -5
- package/plugin/skills/dot-debug/agents/openai.yaml +0 -3
- package/plugin/skills/dot-flow/SKILL.md +0 -105
- package/plugin/skills/dot-flow/agents/openai.yaml +0 -5
- package/plugin/skills/dot-flow/references/fix-round.md +0 -64
- package/plugin/skills/dot-flow/references/inline.md +0 -9
- package/plugin/skills/dot-grilling/agents/openai.yaml +0 -3
- package/plugin/skills/dot-handoff/agents/openai.yaml +0 -5
- package/plugin/skills/dot-roadmap/agents/openai.yaml +0 -5
- package/plugin/skills/dot-stack-review/agents/openai.yaml +0 -5
- package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
- package/plugin/skills/dot-writing-for-agents/agents/openai.yaml +0 -3
- /package/{plugin/rules → rules}/code-style.md +0 -0
- /package/{plugin/rules → rules}/comments.md +0 -0
- /package/{plugin/rules → rules}/core.md +0 -0
- /package/{plugin/scaffold → scaffold}/.claude/settings.json.tmpl +0 -0
- /package/{plugin/scaffold → scaffold}/.editorconfig.tmpl +0 -0
- /package/{plugin/scaffold → scaffold}/.gitattributes.tmpl +0 -0
- /package/{plugin/scaffold → scaffold}/CLAUDE.md.tmpl +0 -0
- /package/{plugin/skills → skills}/dot-code-review/references/maintainability.md +0 -0
- /package/{plugin/skills → skills}/dot-comments/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-correct/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-debug/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-debug/references/loops.md +0 -0
- /package/{plugin/skills → skills}/dot-debug/scripts/hitl-loop.template.sh +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/references/formatting.md +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/references/global-and-accessible.md +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/references/word-list.md +0 -0
- /package/{plugin/skills → skills}/dot-grilling/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-handoff/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-implement/UPSTREAM.json +0 -0
- /package/{plugin/skills → skills}/dot-implement/references/typescript.md +0 -0
- /package/{plugin/skills → skills}/dot-plan/UPSTREAM.json +0 -0
- /package/{plugin/skills → skills}/dot-plan/references/entity-schemas.md +0 -0
- /package/{plugin/skills → skills}/dot-roadmap/UPSTREAM.json +0 -0
- /package/{plugin/skills → skills}/dot-roadmap/references/wide-refactor.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/after-implement.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/http.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/shared-state.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/typescript.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/references/pointers.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/references/skill-mechanics.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/references/steps.md +0 -0
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# HTTP-Protocol and Authentication Hunting
|
|
2
|
+
|
|
3
|
+
#### When to use this file
|
|
4
|
+
|
|
5
|
+
Reach for this file when the target speaks HTTP at a parsing, caching, browser-authentication, or identity boundary: web applications, APIs, reverse proxies, CDNs, gateways, custom HTTP servers, and services implementing sessions, JWT, OAuth/OIDC, SAML, password recovery, MFA, passkeys, API keys, or mTLS. Use this with `ATTACK-CLASSES.md`: access-control review asks whether a principal may perform an operation; this file asks whether the HTTP or identity layer can confuse which principal, request, assurance level, or token the operation belongs to.
|
|
6
|
+
|
|
7
|
+
Pick classes from the map step. Split a large target into request framing and cache policy, browser authentication, federated identity, strong authentication and recovery, service credentials, and session lifecycle. A single server behind an unobserved managed proxy has little source-confirmable smuggling surface; a proxy or custom parser has much more.
|
|
8
|
+
|
|
9
|
+
## Core discipline (include in every agent prompt for this domain)
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
- Framing and cache findings require two interpretations of the same request, response, or key. Name both components and the exact normalized value on each side.
|
|
13
|
+
- For every credential, find the signature or secret verification and every binding required for its role: issuer, audience, origin, RP, client, session, principal, resource, assurance, expiry, and one-time state.
|
|
14
|
+
- Host, Forwarded, X-Forwarded-*, Origin, Referer, redirect targets, callback state, and request-derived URLs are trust decisions. Trace each to the affected identity or response.
|
|
15
|
+
- A missing header, cookie attribute, MFA prompt, or rate limit is not a finding alone. Require an accepted invalid request, cross-principal impact, assurance downgrade, or credential disclosure.
|
|
16
|
+
- Classify `confirmed` only from complete source evidence and bounded local request/token tests. Use `needs_validation` when proxy, IdP, browser, certificate, secret, or deployed configuration is required but not visible.
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## HTTP framing and cache attack classes
|
|
20
|
+
|
|
21
|
+
**Request framing and desynchronization**
|
|
22
|
+
Front end and back end disagree on request length or header normalization. Review multiple `Content-Length` values, `Transfer-Encoding`, HTTP/2 or HTTP/3 downgrade, header-name normalization, forbidden connection headers, and CR/LF conversion. Confirm which bytes one component assigns to a request and which bytes its peer assigns to the next request.
|
|
23
|
+
|
|
24
|
+
**Web cache poisoning through unkeyed input**
|
|
25
|
+
A request value changes cached content or security-relevant headers but is absent from the cache key. Compare cache key construction with every response variant, including forwarded host/scheme, selected cookies, query normalization, language/device headers, and authorization state.
|
|
26
|
+
|
|
27
|
+
**Cache deception and private-response caching**
|
|
28
|
+
Cache routing treats a private dynamic path as a public static asset, or caches a response whose identity and authorization inputs are missing from policy. Compare edge cacheability with application route parsing, suffix/path-parameter normalization, and response cache directives.
|
|
29
|
+
|
|
30
|
+
**Host and forwarded-header trust**
|
|
31
|
+
Untrusted host/proxy metadata determines absolute URLs, tenant routing, callbacks, reset links, cache keys, or the client address used by authorization. Confirm who can supply the header and whether trusted ingress removes client-provided copies.
|
|
32
|
+
|
|
33
|
+
**Response-header injection**
|
|
34
|
+
Untrusted data reaches `Location`, `Set-Cookie`, CSP, or another response header with unsafe control characters or normalization. Verify framework rejection before reporting and require a security-relevant response change.
|
|
35
|
+
|
|
36
|
+
## Browser-session attack classes
|
|
37
|
+
|
|
38
|
+
**Ordinary CSRF**
|
|
39
|
+
A browser sends ambient credentials to a state-changing endpoint that accepts a cross-site request without an effective anti-CSRF token, same-site request binding, or strict Origin/Referer validation. Inventory every cookie-authenticated mutation, including form, JSON-like, multipart, method-override, and legacy routes. SameSite is effective only for the cookie and browser contexts actually used; login CSRF and cross-site subresource requests can have different requirements.
|
|
40
|
+
|
|
41
|
+
**Session fixation and invalidation**
|
|
42
|
+
Session identifiers are not rotated on login, account switch, MFA completion, impersonation, or other privilege changes, or remain valid after logout, password change, revocation, and account disable. Check server sessions, refresh tokens, signed cookies, websocket state, cache copies, and fallback endpoints.
|
|
43
|
+
|
|
44
|
+
**Cookie scope and transport**
|
|
45
|
+
A sensitive cookie has an over-broad `Domain` or `Path`, can cross an insecure transport, or conflicts with a sibling cookie that another component selects differently. Bare missing flags remain hardening notes unless a realistic less-trusted origin, network position, or browser path can gain or replace the credential.
|
|
46
|
+
|
|
47
|
+
## Federated-identity attack classes
|
|
48
|
+
|
|
49
|
+
First establish role. Authorization-server controls such as redirect allowlisting and code issuance do not belong to a relying-party client. Verification and binding defects belong to the component consuming the artifact.
|
|
50
|
+
|
|
51
|
+
**JWT verification and claim binding**
|
|
52
|
+
Check signature verification, server-pinned algorithm and key source, then `exp`, `nbf`, `aud`, and `iss`. Review `kid`, `jku`, and `x5u` as untrusted key selectors, duplicate/header normalization, and decode-without-verify paths. A valid token for another service is invalid here even when signed by a trusted issuer.
|
|
53
|
+
|
|
54
|
+
**OAuth/OIDC request and callback binding**
|
|
55
|
+
Validate exact `redirect_uri` ownership where the target is the authorization server; session-bound `state`; PKCE and authorization-code binding where applicable; ID-token issuer/audience/signature/nonce; and selected-IdP binding in multi-provider flows. Compare initial callback, retry, mobile/deep-link, and account-link routes.
|
|
56
|
+
|
|
57
|
+
**SAML signed-object and assertion binding**
|
|
58
|
+
Ensure the element whose signature is validated is the element used as identity. Review unsigned/fallback paths, safe XML parser configuration, canonicalization differences, and freshness/binding fields such as validity windows, audience/recipient, request correlation, and replay state.
|
|
59
|
+
|
|
60
|
+
## MFA, passkey, and account-transition attack classes
|
|
61
|
+
|
|
62
|
+
**MFA enrollment and assurance downgrade**
|
|
63
|
+
Enrollment, replacement, disablement, recovery-code generation, trusted-device creation, and fallback login require the intended prior assurance. Check that a valid first factor cannot enroll or replace the second factor without policy-required fresh authentication, and that disabled or stale factors stop authorizing sessions.
|
|
64
|
+
|
|
65
|
+
**Step-up binding and bypass**
|
|
66
|
+
A successful challenge upgrades the wrong session, account, tenant, action, or API request, or an alternate route omits the assurance check. Bind the challenge to principal, current session, assurance target, operation or resource when required, expiry, and one-time completion. Compare UI, API, batch, recovery, and resumed-flow paths.
|
|
67
|
+
|
|
68
|
+
**WebAuthn and passkey verification**
|
|
69
|
+
At registration, bind challenge, RP ID, expected origin, credential, user/userHandle, algorithm, and policy-required user verification to the initiating session. At authentication, verify challenge, RP/origin, credential membership, signature, and intended user presence/verification. Check account-discovery and linking flows for userHandle or credential-to-account confusion. Signature-counter handling is meaningful only when the product treats regressions as a clone signal.
|
|
70
|
+
|
|
71
|
+
**Account linking and identity collision**
|
|
72
|
+
Adding an IdP, passkey, email, phone, device, or external account to an existing account must require a current authenticated session, verified ownership of the new identity, policy-required step-up, and callback state bound to the account that initiated linking. Review unlink/relink and invite-acceptance paths for verified-identifier or tenant collisions.
|
|
73
|
+
|
|
74
|
+
**Password reset and broader recovery**
|
|
75
|
+
Recovery tokens, support/admin recovery, backup codes, device migration, and email or phone change often become the weakest authentication path. Verify token randomness, user/action binding, expiry, one-time state, rate/accounting controls, delivery URL trust, and invalidation of prior tokens and sessions. Different responses that only reveal public account existence are not automatically security findings.
|
|
76
|
+
|
|
77
|
+
## API-key and mTLS attack classes
|
|
78
|
+
|
|
79
|
+
**API-key scope and resource binding**
|
|
80
|
+
A key authenticates to broader tenants, resources, actions, or environments than its server-side record grants, or request parameters override those bindings. Review key lookup, prefix/full-secret verification, type confusion between publishable and secret keys, scope checks, rotation, revocation caches, and bulk endpoints.
|
|
81
|
+
|
|
82
|
+
**API-key exposure and unsafe transport**
|
|
83
|
+
Keys appear in client bundles, URLs, redirects, logs, error paths, build artifacts, or responses accessible to a lower-trust principal. A public identifier called a key is not a secret. Confirm key type and the authority gained by disclosure.
|
|
84
|
+
|
|
85
|
+
**mTLS peer and application-identity confusion**
|
|
86
|
+
A process trusts client-certificate identity headers from any network peer, verifies a chain but maps attacker-influenceable subject text to an account incorrectly, or accepts a certificate for the wrong trust domain, extended usage, audience, or validity policy. Where a trusted proxy terminates mTLS, verify only that proxy can connect, it removes incoming identity headers, and the backend binds the sanitized identity to the request.
|
|
87
|
+
|
|
88
|
+
**Certificate lifecycle fallback**
|
|
89
|
+
Expired, revoked, missing, or renewal-failed certificates cause silent fallback to bearer-only or anonymous operation, or long-lived pooled connections retain authorization after revocation. Missing deployment revocation data makes the result `needs_validation`; an in-repo fail-open branch is source-confirmable.
|
|
90
|
+
|
|
91
|
+
## Universal moves (apply across the above)
|
|
92
|
+
|
|
93
|
+
- Walk the steps issue, store, transmit, consume, refresh, and revoke for every credential and challenge. Compare normal, error, retry, migration, legacy, and account-switch paths.
|
|
94
|
+
- Enumerate every door to the same identity and every route to the same sensitive operation. The effective policy is the weakest parallel path, not the most polished UI.
|
|
95
|
+
- Diff parser, proxy, router, cache, and application normalization side by side. For local validation, feed identical bounded request fixtures into each component rather than sending traffic to a live deployment.
|
|
96
|
+
- For recovery and linking, draw the account before/after graph. Each edge must name the current principal, proof of the new identity, required assurance, callback/session binding, and revocation effect.
|
|
97
|
+
|
|
98
|
+
## Validation rules (apply before reporting ANY finding here)
|
|
99
|
+
|
|
100
|
+
1. Apply a source-visibility gate. Proxy chains, edge cache keys, IdP policy, certificate trust, browser cookie behavior, secrets, and deployed auth modes may be outside the repository. Record a precise `needs_validation` candidate instead of asserting missing infrastructure behavior.
|
|
101
|
+
2. For framing and cache findings, name both components and the divergent parse/key. Confirm cross-request, cross-user, or private-response impact with bounded local fixtures.
|
|
102
|
+
3. For token, MFA, passkey, account-link, recovery, API-key, and mTLS findings, cite the verification line and missing principal/session/resource/origin/audience/action/assurance binding. Prove the server accepts the invalid transition or credential.
|
|
103
|
+
4. For CSRF, name the ambient credential, state-changing route, accepted cross-site request shape, browser cookie policy, and missing effective check. Read-only actions and routes requiring a non-ambient bearer token do not qualify.
|
|
104
|
+
5. Verify framework and library defaults. If version or configuration is unknown, use `needs_validation`; do not turn an unverified critical claim into a lower-severity confirmed finding.
|
|
105
|
+
6. Return `confirmed` only with a complete source trace and observable unauthorized identity, state, or disclosure. For `needs_validation`, name the missing fact and safe local or owner-observed check that resolves it.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dot-security-changes
|
|
3
|
+
description: Check the uncommitted changes of the working tree, or the changes between two trees, for security problems. Use when the user or an agent asks for a security check of the current changes before a commit.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Security check of changes
|
|
7
|
+
|
|
8
|
+
Find vulnerabilities that the diff adds or exposes. This skill uses the rules of [`dot-security-audit`](../dot-security-audit/SKILL.md) for a boundary, a status, and a severity. It differs in the target, the references, and the report. For a whole codebase, use `dot-security-audit` instead.
|
|
9
|
+
|
|
10
|
+
## 1. Pick the target
|
|
11
|
+
|
|
12
|
+
- **Working tree** (default): the working tree against `HEAD`. The diff is `git diff HEAD`, and each untracked file that `git status --porcelain` lists is a new file. Git ignores the files that `.gitignore` names, so they stay out.
|
|
13
|
+
- **Tree range**: `<old-tree> <new-tree>`, when the caller gives one. The diff is `git diff <old-tree> <new-tree>`.
|
|
14
|
+
|
|
15
|
+
Read each changed file from the working tree, or with `git show <tree>:<path>` for a tree range. For a deleted file, read it from `HEAD` or from the old tree.
|
|
16
|
+
|
|
17
|
+
State the target in one line: `working tree vs HEAD (<short sha>)`, or `<old-tree> .. <new-tree>`.
|
|
18
|
+
|
|
19
|
+
Done when you have the list of changed files. When there are none, stop and tell the user.
|
|
20
|
+
|
|
21
|
+
## 2. Map the topics
|
|
22
|
+
|
|
23
|
+
For each changed hunk, name the topics that it touches. Read the reference of a topic only when a hunk touches that topic. Read no other reference.
|
|
24
|
+
|
|
25
|
+
| Topic of the diff | Read |
|
|
26
|
+
| ----------------- | ---- |
|
|
27
|
+
| SQL or shell strings, templates, file paths, redirects, URL fetches, deserialization, archives, input parsing, permission checks, secrets, tokens, randomness, or crypto | [`ATTACK-CLASSES.md`](../dot-security-audit/references/ATTACK-CLASSES.md) |
|
|
28
|
+
| HTTP handlers, middleware, sessions, cookies, CSRF, JWT, OAuth, SAML, MFA, passkeys, API keys, or mTLS | [`WEB-PROTOCOL-AND-AUTH.md`](../dot-security-audit/references/WEB-PROTOCOL-AND-AUTH.md) |
|
|
29
|
+
| Browser code, DOM rendering, a webview, a browser extension, a service worker, CORS, or WebSockets | [`CLIENT-SIDE.md`](../dot-security-audit/references/CLIENT-SIDE.md) |
|
|
30
|
+
| Prompts, retrieval, agent memory, tool calls, or an MCP server or client | [`AI-AND-LLM.md`](../dot-security-audit/references/AI-AND-LLM.md) |
|
|
31
|
+
| C, C++, or unsafe Rust, parsers of binary data, FFI, or loaders | [`MEMORY-SAFETY-AND-BINARY.md`](../dot-security-audit/references/MEMORY-SAFETY-AND-BINARY.md) |
|
|
32
|
+
| Dependency files, CI workflows, signing, release scripts, updates, or plugins | [`SUPPLY-CHAIN-AND-RELEASE.md`](../dot-security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md) |
|
|
33
|
+
| IAM, infrastructure as code, containers, Kubernetes, serverless, or ingress | [`CLOUD-AND-DEPLOYMENT.md`](../dot-security-audit/references/CLOUD-AND-DEPLOYMENT.md) |
|
|
34
|
+
| gRPC, GraphQL, custom protocols, queues, brokers, or webhooks | [`PROTOCOLS-RPC-AND-MESSAGING.md`](../dot-security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md) |
|
|
35
|
+
| Loops, uploads, queries, or jobs that run untrusted work on shared CPU, memory, disk, workers, or spend | [`RESOURCE-EXHAUSTION-AND-AVAILABILITY.md`](../dot-security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md) |
|
|
36
|
+
| Tenant scoping, caches, search, exports, backups, migrations, or deletion | [`DATA-ISOLATION-AND-LIFECYCLE.md`](../dot-security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md) |
|
|
37
|
+
| Native apps, deep links, webview bridges, local daemons, or sockets | [`DESKTOP-MOBILE-AND-LOCAL-IPC.md`](../dot-security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md) |
|
|
38
|
+
|
|
39
|
+
When a hunk touches no topic, read no reference. Tell the user which references you read.
|
|
40
|
+
|
|
41
|
+
## 3. Hunt
|
|
42
|
+
|
|
43
|
+
For each changed hunk, trace untrusted input to the dangerous sink, and check that each changed control checks the right permission on the right resource. Read the whole function and its callers: a hunk that looks safe can break a control elsewhere. Also check the code that the diff deletes. A removed check, validation, or escape is a candidate.
|
|
44
|
+
|
|
45
|
+
Write each candidate as a boundary hypothesis. Then apply the rules of "Rules for every finding" in [`dot-security-audit`](../dot-security-audit/SKILL.md#rules-for-every-finding), and drop each candidate that fails them. Do not report a problem in code that the diff does not change or expose. Run no target code unless the sandbox rules of `dot-security-audit` hold.
|
|
46
|
+
|
|
47
|
+
Done when you re-read the source of each candidate, searched for a control that stops it, and set its status.
|
|
48
|
+
|
|
49
|
+
## 4. Report
|
|
50
|
+
|
|
51
|
+
Give the findings from most to least severe, in the format of [`dot-code-review`](../dot-code-review/SKILL.md#5-report), which accepts only `high`, `medium`, and `low`. Use the **Scenario** line for the boundary: the principal, the input, and the result. Use the severity anchors of `dot-security-audit`, and give only a `confirmed` finding a severity. Map `critical` to `high` and `informational` to `low`. Put a `needs_validation` finding after the `confirmed` findings, and give it its missing fact and a safe check in place of a severity. Add the smallest fix, and a regression test idea.
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
### <high | medium | low> <one-line summary>
|
|
55
|
+
`path/to/file.ts:42` (security)
|
|
56
|
+
**Scenario:** <principal and input>, then <result>
|
|
57
|
+
**Fix:** <smallest change that enforces the invariant at the last trusted decision point>
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
```markdown
|
|
61
|
+
### Needs validation: <one-line summary>
|
|
62
|
+
`path/to/file.ts:42` (security)
|
|
63
|
+
**Scenario:** <principal and input>, then <result>
|
|
64
|
+
**Missing fact:** <the one fact that blocks the proof>
|
|
65
|
+
**Check:** <safe way for the owner to check it>
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
If you find nothing, say that the check found no security problems, and list the topics that you checked. Edit no file.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"repository": "https://github.com/cursor/plugins",
|
|
3
3
|
"path": "pstack/skills/principle-test-behavior-not-implementation/SKILL.md",
|
|
4
|
-
"commit": "
|
|
4
|
+
"commit": "e58dd043600587dbaf58ba315e7f2b38373eeb43",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"modified": true,
|
|
7
7
|
"notes": "Condensed the principle into one clause of the assertion bullet in Test principles. The rest of the skill is original and is not from pstack."
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dot-ui-review
|
|
3
|
+
description: Review UI changes visually in a browser, against a live preview of the app, for interaction, responsive layout, visual polish, accessibility, and robustness. Use when the user or an agent asks for a UI or design review of front-end changes. Do not use it for a correctness review of the code: use `dot-code-review`. The review skips when the app cannot start or no browser tool exists.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# UI review
|
|
7
|
+
|
|
8
|
+
Review the UI changes in a running app, in a browser, as a user sees them. Assess the live experience first, and read the code second. For a review that reads code only, use `dot-ux-review`.
|
|
9
|
+
|
|
10
|
+
Report findings as problems and their effect on the user. Assume that the author meant well. Change no code.
|
|
11
|
+
|
|
12
|
+
## 1. Check the preconditions
|
|
13
|
+
|
|
14
|
+
The review needs both of these:
|
|
15
|
+
|
|
16
|
+
- **An app command.** Use the command that the caller gives. Otherwise use the `dev` script, then the `start` script, in `package.json` or in the build file of the project.
|
|
17
|
+
- **A browser tool.** Use the browser tool of the session: Playwright MCP or Claude in Chrome. Load its tools if they are deferred.
|
|
18
|
+
|
|
19
|
+
When one is missing, stop. Make no change and start nothing. Report this line with the reasons, and nothing else:
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
UI review: skipped. <reason>
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Use one of these reasons. Step 2 uses the last two:
|
|
26
|
+
|
|
27
|
+
- `no app command: the caller gave none, and the project has no dev or start script`
|
|
28
|
+
- `no browser tool: the session has neither Playwright MCP nor Claude in Chrome`
|
|
29
|
+
- `the app did not start: <the command and its last error line>`
|
|
30
|
+
- `no UI changes: the target has no file that renders a UI`
|
|
31
|
+
|
|
32
|
+
Done when you have the app command and a browser tool, or you reported the skip line.
|
|
33
|
+
|
|
34
|
+
## 2. Prepare
|
|
35
|
+
|
|
36
|
+
1. Pick the target: the working tree against `HEAD` (`git diff HEAD`, plus the untracked files that `git status --porcelain` lists), or the tree range `<old-tree> <new-tree>` that the caller gives. Read the description of the work, the pull request, or the roadmap task if there is one, for the motivation and the test notes.
|
|
37
|
+
2. Read the diff. List the components, the routes, and the states that it changes. If the files render no UI, report the skip line with the reason `no UI changes`.
|
|
38
|
+
3. Start the app command in the background. Do not install dependencies. Read its output for the local URL, and wait until the URL answers. If the app does not answer within 60 seconds, stop it, and report the skip line with the reason `the app did not start`.
|
|
39
|
+
4. Open the URL in the browser. Set the desktop viewport to 1440 by 900.
|
|
40
|
+
5. Run `git check-ignore -q .tmp/`. When Git ignores `.tmp`, save each screenshot in `.tmp/ui-review/`. Otherwise take no screenshot to disk, and report each visual finding without a path.
|
|
41
|
+
|
|
42
|
+
Use only the local app. Use dummy data in each form, and do not open a link to a deployed or shared service.
|
|
43
|
+
|
|
44
|
+
## 3. Review in phases
|
|
45
|
+
|
|
46
|
+
Run the phases in order. In each phase, visit the pages and the states that the diff changes. Take a screenshot as evidence of each visual finding. Skip a phase check that the change does not touch.
|
|
47
|
+
|
|
48
|
+
1. **Interaction and user flow.** Run the main flow of the change, following the test notes. Test the hover, active, focus, and disabled states. Check that a destructive action asks for confirmation. Judge how fast the interface answers.
|
|
49
|
+
2. **Responsiveness.** Test the desktop viewport (1440 px), the tablet viewport (768 px), and the mobile viewport (375 px). Capture a screenshot of each. Check that the layout adapts, that touch targets are large enough, and that nothing scrolls sideways or overlaps.
|
|
50
|
+
3. **Visual polish.** Check the alignment and the spacing, the typography hierarchy and the legibility, the colors and the image quality, and whether the visual hierarchy guides the eye.
|
|
51
|
+
4. **Accessibility (WCAG 2.1 AA).** Tab through the whole change and check the order. Check a visible focus state on each interactive element, Enter and Space activation, semantic HTML, form labels, image alt text, and a contrast ratio of 4.5:1 or more for text.
|
|
52
|
+
5. **Robustness.** Submit invalid input to each form. Test long text and large content for overflow. Check the loading, empty, and error states, and other edge cases.
|
|
53
|
+
6. **Code health.** Read the changed code. Check that it reuses existing components, uses the design tokens of the project and not magic numbers, and follows the patterns of the project.
|
|
54
|
+
7. **Content and console.** Check the grammar and the clarity of each text. Read the browser console for errors and warnings.
|
|
55
|
+
|
|
56
|
+
Done when each phase has run, or you wrote down why it did not apply.
|
|
57
|
+
|
|
58
|
+
## 4. Clean up
|
|
59
|
+
|
|
60
|
+
Stop the app process that you started. Close the browser tabs that you opened.
|
|
61
|
+
|
|
62
|
+
## 5. Report
|
|
63
|
+
|
|
64
|
+
Start with one or two sentences on what works well and on the overall quality. Then give the findings in the `dot-code-review` format, from most to least severe:
|
|
65
|
+
|
|
66
|
+
```markdown
|
|
67
|
+
### <high | medium | low> <one-line summary>
|
|
68
|
+
`path/to/Component.tsx:42` (ui)
|
|
69
|
+
**Cost:** <what the user pays, and the viewport or state where it shows>
|
|
70
|
+
**Screenshot:** `.tmp/ui-review/<name>.png`
|
|
71
|
+
**Fix:** <smallest change that removes the problem>
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
- Use `file:line` of the component that renders the problem. When you cannot find the component, use the route.
|
|
75
|
+
- Use `high` for a failure that blocks the flow or an accessibility barrier, `medium` for a significant problem to fix before merge, and `low` for polish.
|
|
76
|
+
- Describe the problem and its effect. Name a fix only when it is small and clear.
|
|
77
|
+
- Omit the **Screenshot** line when the finding has no screenshot.
|
|
78
|
+
|
|
79
|
+
When you find nothing, say that the review found no UI problems, and list the viewports and the states that you checked.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
{
|
|
2
|
+
"repository": "https://github.com/OneRedOak/claude-code-workflows",
|
|
3
|
+
"path": "design-review",
|
|
4
|
+
"commit": "29a34c725313c7621f426f838ed31cf482473fb4",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"modified": true,
|
|
7
|
+
"notes": "Rewrote design-review-agent.md and design-review-slash-command.md as one SKILL.md under rules/writing.md, and renamed the skill with the dot- prefix. Kept the review phases 1 to 7 and the Live Environment First principle, and folded Phase 0 into a prepare step. Replaced the Playwright tool names with the browser tool of the session (Playwright MCP or Claude in Chrome). Added a precondition step that stops with the line \"UI review: skipped\" and a reason when the app command or the browser tool is missing. Replaced the triage matrix and the report structure with the dot-code-review finding format, with file:line and a screenshot path. Dropped the pull request diff injection, the tool list, the model and color settings, the context7 tools, design-principles-example.md, design-review-claude-md-snippet.md, and README.md."
|
|
8
|
+
}
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dot-ux-review
|
|
3
|
+
description: Review UI code for UX, accessibility, and interface rules by reading the code, against the Vercel web interface guidelines. Use when the user or an agent asks for a UX review of the current changes, or of a path, before a commit. Do not use it for a correctness review of the code: use `dot-code-review`.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# UX review
|
|
7
|
+
|
|
8
|
+
Review UI code against the rules in [`web-interface-guidelines.md`](references/web-interface-guidelines.md). This skill reads code only. It starts no app and no browser. For a visual review in a browser, use `dot-ui-review`.
|
|
9
|
+
|
|
10
|
+
## 1. Pick the target
|
|
11
|
+
|
|
12
|
+
- **Working tree** (default): the working tree against `HEAD`. The diff is `git diff HEAD`, and each untracked file that `git status --porcelain` lists is a new file. Git ignores the files that `.gitignore` names, so they stay out.
|
|
13
|
+
- **Tree range**: `<old-tree> <new-tree>`, when the caller gives one. The diff is `git diff <old-tree> <new-tree>`.
|
|
14
|
+
- **Path**: a file or a directory that the user names. Review the whole file.
|
|
15
|
+
|
|
16
|
+
Keep only the files that end in `.tsx`, `.jsx`, `.vue`, `.svelte`, `.html`, or `.css`. Read each one from the working tree, or with `git show <tree>:<path>` for a tree range. Skip a deleted file.
|
|
17
|
+
|
|
18
|
+
State the target in one line: `working tree vs HEAD (<short sha>)`, `<old-tree> .. <new-tree>`, or the path.
|
|
19
|
+
|
|
20
|
+
Done when you have the list of UI files. When there are none, stop and tell the user: `UX review: no UI files changed`.
|
|
21
|
+
|
|
22
|
+
## 2. Read the rules
|
|
23
|
+
|
|
24
|
+
Read [`web-interface-guidelines.md`](references/web-interface-guidelines.md). Use its "Rules" and "Anti-patterns" sections. Ignore its frontmatter, its `$ARGUMENTS` line, and its "Output Format" section: step 4 sets the format.
|
|
25
|
+
|
|
26
|
+
## 3. Check each file
|
|
27
|
+
|
|
28
|
+
For each UI file, read the whole file, not only the changed hunks. Check it against every section of the rules. A rule that does not apply to the file is not a finding, such as a form rule in a file with no form.
|
|
29
|
+
|
|
30
|
+
- With a diff target, report a finding only on a line that the diff adds or changes, or on a line whose result the change alters.
|
|
31
|
+
- Report a rule break that you can point to in the code. Do not guess at runtime behavior that the code does not show.
|
|
32
|
+
- When the repository has its own design system or component library, a component of it can meet a rule for you. Read the component before you report the rule as broken.
|
|
33
|
+
- Where the repository's own convention differs from a rule, follow the repository, and say so in one line at the end of the report. The rules use Title Case for headings and buttons, for example. A repository can use sentence case.
|
|
34
|
+
|
|
35
|
+
Done when you checked each UI file against each section of the rules.
|
|
36
|
+
|
|
37
|
+
## 4. Report
|
|
38
|
+
|
|
39
|
+
Give the findings in the `dot-code-review` format, from most to least severe. Use `high` for an accessibility barrier or an anti-pattern from the rules, `medium` for another rule break that users meet, and `low` for polish:
|
|
40
|
+
|
|
41
|
+
```markdown
|
|
42
|
+
### <high | medium | low> <one-line summary>
|
|
43
|
+
`path/to/file.tsx:42` (ux)
|
|
44
|
+
**Cost:** <what the user or the next change pays>
|
|
45
|
+
**Fix:** <smallest change that removes the problem>
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Name the rule in the summary, such as "icon button has no `aria-label`". Group repeated breaks of one rule in one finding with the list of lines.
|
|
49
|
+
|
|
50
|
+
When you find nothing, say that the review found no UX problems, and list the files that you checked. Change code only when the user asks for fixes.
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
{
|
|
2
|
+
"repository": "https://github.com/vercel-labs/web-interface-guidelines",
|
|
3
|
+
"path": "command.md",
|
|
4
|
+
"commit": "434b7f91364665f2f733b310ec54809bf8f37937",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"modified": true,
|
|
7
|
+
"notes": "Copied command.md as references/web-interface-guidelines.md. Replaced 7 em dashes and the contraction \"don't\" so that the file passes the writing lint. Changed no rule. The own SKILL.md ignores the frontmatter, the $ARGUMENTS line, and the Output Format section of the file."
|
|
8
|
+
}
|
|
@@ -0,0 +1,191 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Review UI code for Vercel Web Interface Guidelines compliance
|
|
3
|
+
argument-hint: <file-or-pattern>
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Web Interface Guidelines
|
|
7
|
+
|
|
8
|
+
Review these files for compliance: $ARGUMENTS
|
|
9
|
+
|
|
10
|
+
Read files, check against rules below. Output concise but comprehensive. Sacrifice grammar for brevity. High signal-to-noise.
|
|
11
|
+
|
|
12
|
+
## Rules
|
|
13
|
+
|
|
14
|
+
### Accessibility
|
|
15
|
+
|
|
16
|
+
- Icon-only buttons need `aria-label`
|
|
17
|
+
- Form controls need `<label>` or `aria-label`
|
|
18
|
+
- Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
|
|
19
|
+
- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
|
|
20
|
+
- Images need `alt` (or `alt=""` if decorative)
|
|
21
|
+
- Decorative icons need `aria-hidden="true"`
|
|
22
|
+
- Async updates (toasts, validation) need `aria-live="polite"`
|
|
23
|
+
- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
|
|
24
|
+
- Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
|
|
25
|
+
- `scroll-margin-top` on heading anchors
|
|
26
|
+
- Meaningful media needs captions, transcripts, or descriptions as applicable
|
|
27
|
+
- Media controls need keyboard support; decorative media needs assistive-tech hiding
|
|
28
|
+
|
|
29
|
+
### Focus States
|
|
30
|
+
|
|
31
|
+
- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
|
|
32
|
+
- Never `outline-none` / `outline: none` without focus replacement
|
|
33
|
+
- Use `:focus-visible` over `:focus` (avoid focus ring on click)
|
|
34
|
+
- Group focus with `:focus-within` for compound controls
|
|
35
|
+
- Sticky headers/footers/overlays must not cover the focused element
|
|
36
|
+
|
|
37
|
+
### Forms
|
|
38
|
+
|
|
39
|
+
- Inputs need `autocomplete` and meaningful `name`
|
|
40
|
+
- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
|
|
41
|
+
- Never block paste (`onPaste` + `preventDefault`)
|
|
42
|
+
- Labels clickable (`htmlFor` or wrapping control)
|
|
43
|
+
- Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
|
|
44
|
+
- Checkboxes/radios: label + control share single hit target (no dead zones)
|
|
45
|
+
- Submit button stays enabled until request starts; spinner during request
|
|
46
|
+
- Errors inline next to fields; focus first error on submit
|
|
47
|
+
- Placeholders end with `…` and show example pattern
|
|
48
|
+
- `autocomplete="off"` on non-auth fields to avoid password manager triggers
|
|
49
|
+
- Warn before navigation with unsaved changes (`beforeunload` or router guard)
|
|
50
|
+
|
|
51
|
+
### Animation
|
|
52
|
+
|
|
53
|
+
- Honor `prefers-reduced-motion` (provide reduced variant or disable)
|
|
54
|
+
- Animate `transform`/`opacity` only (compositor-friendly)
|
|
55
|
+
- Never `transition: all`: list properties explicitly
|
|
56
|
+
- Set correct `transform-origin`
|
|
57
|
+
- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
|
|
58
|
+
- Animations interruptible: respond to user input mid-animation
|
|
59
|
+
- Autoplay motion >5 seconds alongside other content needs pause, stop, or hide controls
|
|
60
|
+
- Muted decorative loops must stop under `prefers-reduced-motion`
|
|
61
|
+
|
|
62
|
+
### Typography
|
|
63
|
+
|
|
64
|
+
- `…` not `...`
|
|
65
|
+
- Curly quotes `“` `”` not straight `"`
|
|
66
|
+
- Non-breaking spaces: `10 MB`, `⌘ K`, brand names
|
|
67
|
+
- Loading states end with `…`: `"Loading…"`, `"Saving…"`
|
|
68
|
+
- `font-variant-numeric: tabular-nums` for number columns/comparisons
|
|
69
|
+
- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
|
|
70
|
+
|
|
71
|
+
### Content Handling
|
|
72
|
+
|
|
73
|
+
- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
|
|
74
|
+
- Flex children need `min-w-0` to allow text truncation
|
|
75
|
+
- Handle empty states: do not render broken UI for empty strings/arrays
|
|
76
|
+
- User-generated content: anticipate short, average, and very long inputs
|
|
77
|
+
|
|
78
|
+
### Images
|
|
79
|
+
|
|
80
|
+
- `<img>` needs explicit `width` and `height` (prevents CLS)
|
|
81
|
+
- Below-fold images: `loading="lazy"`
|
|
82
|
+
- Above-fold critical images: `priority` or `fetchpriority="high"`
|
|
83
|
+
|
|
84
|
+
### Performance
|
|
85
|
+
|
|
86
|
+
- Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
|
|
87
|
+
- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
|
|
88
|
+
- Batch DOM reads/writes; avoid interleaving
|
|
89
|
+
- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
|
|
90
|
+
- Add `<link rel="preconnect">` for CDN/asset domains
|
|
91
|
+
- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
|
|
92
|
+
- Prefer `<video autoplay muted loop playsinline>` over animated GIF; provide a still alternative
|
|
93
|
+
- Short non-essential loops: Safari H.264 MP4 `<picture>` source, `prefers-reduced-motion` media condition, and still fallback
|
|
94
|
+
|
|
95
|
+
### Navigation & State
|
|
96
|
+
|
|
97
|
+
- URL reflects state: filters, tabs, pagination, expanded panels in query params
|
|
98
|
+
- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
|
|
99
|
+
- Deep-link all stateful UI (if uses `useState`, consider URL sync via nuqs or similar)
|
|
100
|
+
- Destructive actions need confirmation modal or undo window, never immediate
|
|
101
|
+
|
|
102
|
+
### Touch & Interaction
|
|
103
|
+
|
|
104
|
+
- `touch-action: manipulation` (prevents double-tap zoom delay)
|
|
105
|
+
- `-webkit-tap-highlight-color` set intentionally
|
|
106
|
+
- `overscroll-behavior: contain` in modals/drawers/sheets
|
|
107
|
+
- Page rubber-band suppression: `overscroll-behavior: none` on `<html>` inside `@media (pointer: fine)`; keep coarse-pointer page defaults for pull-to-refresh. Test hybrid touch devices: `pointer` describes the primary input, and `none` also disables scroll chaining and native swipe navigation
|
|
108
|
+
- During drag: disable text selection, `inert` on dragged elements
|
|
109
|
+
- Drag/swipe/pinch/path gestures need tap/click and keyboard alternatives unless essential
|
|
110
|
+
- `autoFocus` sparingly: desktop only, single primary input; avoid on mobile
|
|
111
|
+
|
|
112
|
+
### Safe Areas & Layout
|
|
113
|
+
|
|
114
|
+
- Full-bleed layouts need `env(safe-area-inset-*)` for notches
|
|
115
|
+
- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
|
|
116
|
+
- Flex/grid over JS measurement for layout
|
|
117
|
+
|
|
118
|
+
### Dark Mode & Theming
|
|
119
|
+
|
|
120
|
+
- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
|
|
121
|
+
- `<meta name="theme-color">` matches page background
|
|
122
|
+
- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
|
|
123
|
+
|
|
124
|
+
### Locale & i18n
|
|
125
|
+
|
|
126
|
+
- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
|
|
127
|
+
- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
|
|
128
|
+
- Detect language via `Accept-Language` / `navigator.languages`, not IP
|
|
129
|
+
- Brand names, code tokens, identifiers: wrap with `translate="no"` to prevent garbled auto-translation
|
|
130
|
+
|
|
131
|
+
### Hydration Safety
|
|
132
|
+
|
|
133
|
+
- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
|
|
134
|
+
- Date/time rendering: guard against hydration mismatch (server vs client)
|
|
135
|
+
- `suppressHydrationWarning` only where truly needed
|
|
136
|
+
|
|
137
|
+
### Hover & Interactive States
|
|
138
|
+
|
|
139
|
+
- Buttons/links need `hover:` state (visual feedback)
|
|
140
|
+
- Interactive states increase contrast: hover/active/focus more prominent than rest
|
|
141
|
+
|
|
142
|
+
### Content & Copy
|
|
143
|
+
|
|
144
|
+
- Active voice: "Install the CLI" not "The CLI will be installed"
|
|
145
|
+
- Title Case for headings/buttons (Chicago style)
|
|
146
|
+
- Numerals for counts: "8 deployments" not "eight"
|
|
147
|
+
- Specific button labels: "Save API Key" not "Continue"
|
|
148
|
+
- Error messages include fix/next step, not just problem
|
|
149
|
+
- Second person; avoid first person
|
|
150
|
+
- `&` over "and" where space-constrained
|
|
151
|
+
|
|
152
|
+
### Anti-patterns (flag these)
|
|
153
|
+
|
|
154
|
+
- `user-scalable=no` or `maximum-scale=1` disabling zoom
|
|
155
|
+
- `onPaste` with `preventDefault`
|
|
156
|
+
- `transition: all`
|
|
157
|
+
- `outline-none` without focus-visible replacement
|
|
158
|
+
- Inline `onClick` navigation without `<a>`
|
|
159
|
+
- `<div>` or `<span>` with click handlers (should be `<button>`)
|
|
160
|
+
- Images without dimensions
|
|
161
|
+
- Large arrays `.map()` without virtualization
|
|
162
|
+
- Form inputs without labels
|
|
163
|
+
- Icon buttons without `aria-label`
|
|
164
|
+
- Hardcoded date/number formats (use `Intl.*`)
|
|
165
|
+
- `autoFocus` without clear justification
|
|
166
|
+
- Animated GIF when compressed video is suitable
|
|
167
|
+
- Gesture-only action without tap/click and keyboard alternative
|
|
168
|
+
|
|
169
|
+
## Output Format
|
|
170
|
+
|
|
171
|
+
Group by file. Use `file:line` format (VS Code clickable). Terse findings.
|
|
172
|
+
|
|
173
|
+
```text
|
|
174
|
+
## src/Button.tsx
|
|
175
|
+
|
|
176
|
+
src/Button.tsx:42 - icon button missing aria-label
|
|
177
|
+
src/Button.tsx:18 - input lacks label
|
|
178
|
+
src/Button.tsx:55 - animation missing prefers-reduced-motion
|
|
179
|
+
src/Button.tsx:67 - transition: all → list properties
|
|
180
|
+
|
|
181
|
+
## src/Modal.tsx
|
|
182
|
+
|
|
183
|
+
src/Modal.tsx:12 - missing overscroll-behavior: contain
|
|
184
|
+
src/Modal.tsx:34 - "..." → "…"
|
|
185
|
+
|
|
186
|
+
## src/Card.tsx
|
|
187
|
+
|
|
188
|
+
✓ pass
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
State issue + location. Skip explanation unless fix non-obvious. No preamble.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
|
-
name: dot-
|
|
2
|
+
name: dot-walkthrough-branch
|
|
3
3
|
description: Review the commits of a branch as an ordered stack of dependency layers, and report each layer with its findings.
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
#
|
|
7
|
+
# Branch walkthrough
|
|
8
8
|
|
|
9
9
|
Review the committed changes of a branch as a **stack**: layers of files in dependency order. A reader understands layer 1 on its own, and each later layer from the layers above it. The `dot-code-review` skill gives the review. This skill gives the layers and the report.
|
|
10
10
|
|
|
@@ -24,13 +24,7 @@ Done when you have the merge base and the list of changed files.
|
|
|
24
24
|
|
|
25
25
|
## 2. Group the layers
|
|
26
26
|
|
|
27
|
-
Group the changed files into layers
|
|
28
|
-
|
|
29
|
-
- Derive each dependency from the imports and the diff. File A depends on file B when A imports, calls, links, or names something that the diff adds or changes in B. A folder name is a hint only.
|
|
30
|
-
- A layer holds whole files. Split a file into hunks only when it holds changes for 2 layers. List the file in both layers, each with its own hunks.
|
|
31
|
-
- Order the layers in the order that a reader must understand them. Each layer depends only on layers with a lower number. Merge 2 layers that depend on each other.
|
|
32
|
-
|
|
33
|
-
Show the layer map, one line per layer: the number, the name, and the files. Then continue to step 3. The user can ask for new layers after the report.
|
|
27
|
+
Group the changed files of step 1 into layers with the rules of [`references/layers.md`](references/layers.md). Then continue to step 3. The user can ask for new layers after the report.
|
|
34
28
|
|
|
35
29
|
Done when each changed hunk is in exactly one layer, and no layer depends on a layer below it.
|
|
36
30
|
|
|
@@ -82,35 +76,20 @@ Done when the report has every layer of step 2 and every finding of step 3.
|
|
|
82
76
|
|
|
83
77
|
Write a self-contained HTML page of the stack, with the diff of each file and its findings.
|
|
84
78
|
|
|
85
|
-
1. Run `git check-ignore -q .tmp
|
|
86
|
-
2. Write the layers of step 2 and the findings of step 3 to `.tmp/
|
|
79
|
+
1. Run `git check-ignore -q .tmp/` at the repository root. When it exits with a non-zero code, stop, and tell the user that Git does not ignore `.tmp`, so the page could reach a commit.
|
|
80
|
+
2. Write the layers of step 2 and the findings of step 3 to `.tmp/walkthrough/<branch-slug>.json`. `<branch-slug>` is head with each character other than a letter, a digit, `.`, `_`, or `-` replaced by `-`, such as `feat-flow-fix-loop`. Sort the keys.
|
|
87
81
|
|
|
88
82
|
```json
|
|
89
83
|
{
|
|
90
84
|
"base": "main",
|
|
91
85
|
"head": "feat/my-change",
|
|
92
|
-
"layers": [
|
|
93
|
-
{
|
|
94
|
-
"dependsOn": [],
|
|
95
|
-
"files": ["src/types.ts"],
|
|
96
|
-
"findings": [
|
|
97
|
-
{
|
|
98
|
-
"body": "**Scenario:** ...\n**Fix:** ...",
|
|
99
|
-
"file": "src/types.ts",
|
|
100
|
-
"kind": "correctness",
|
|
101
|
-
"line": 42,
|
|
102
|
-
"severity": "high",
|
|
103
|
-
"summary": "One-line summary"
|
|
104
|
-
}
|
|
105
|
-
],
|
|
106
|
-
"name": "Contracts",
|
|
107
|
-
"purpose": "One line"
|
|
108
|
-
}
|
|
109
|
-
]
|
|
86
|
+
"layers": []
|
|
110
87
|
}
|
|
111
88
|
```
|
|
112
89
|
|
|
113
|
-
|
|
90
|
+
`layers` has the layer objects of the layers JSON in [`references/layers.md`](references/layers.md).
|
|
91
|
+
|
|
92
|
+
3. Run the script of this skill directory from the repository root: `node <skill directory>/scripts/page.mjs .tmp/walkthrough/<branch-slug>.json`. It runs `git merge-base` and `git diff` itself, and prints the path of the page.
|
|
114
93
|
4. When the script exits with a non-zero code, fix the field that its message names, and run it again.
|
|
115
94
|
|
|
116
95
|
Done when the user has the path of the page.
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# Layers
|
|
2
|
+
|
|
3
|
+
Group the changed files of a diff into layers by dependency, such as types and contracts, core logic, callers, tests, then docs and config. A reader understands layer 1 on its own, and each later layer from the layers above it.
|
|
4
|
+
|
|
5
|
+
## Group the layers
|
|
6
|
+
|
|
7
|
+
- Derive each dependency from the imports and the diff. File A depends on file B when A imports, calls, links, or names something that the diff adds or changes in B. A folder name is a hint only.
|
|
8
|
+
- A layer holds whole files. Split a file into hunks only when it holds changes for 2 layers. List the file in both layers, each with its own hunks.
|
|
9
|
+
- Order the layers in the order that a reader must understand them. Each layer depends only on layers with a lower number. Merge 2 layers that depend on each other.
|
|
10
|
+
|
|
11
|
+
Show the layer map, one line per layer: the number, the name, and the files.
|
|
12
|
+
|
|
13
|
+
A grouping is done when each changed hunk is in exactly one layer, and no layer depends on a layer below it.
|
|
14
|
+
|
|
15
|
+
## Layers JSON
|
|
16
|
+
|
|
17
|
+
The `layers` array of a layers file has one object per layer, in layer order. Sort the keys. `dependsOn` has the 1-based numbers of the layers that a layer needs. Each finding names a file of its layer.
|
|
18
|
+
|
|
19
|
+
```json
|
|
20
|
+
[
|
|
21
|
+
{
|
|
22
|
+
"dependsOn": [],
|
|
23
|
+
"files": ["src/types.ts"],
|
|
24
|
+
"findings": [
|
|
25
|
+
{
|
|
26
|
+
"body": "**Scenario:** ...\n**Fix:** ...",
|
|
27
|
+
"file": "src/types.ts",
|
|
28
|
+
"kind": "correctness",
|
|
29
|
+
"line": 42,
|
|
30
|
+
"severity": "high",
|
|
31
|
+
"summary": "One-line summary"
|
|
32
|
+
}
|
|
33
|
+
],
|
|
34
|
+
"name": "Contracts",
|
|
35
|
+
"purpose": "One line"
|
|
36
|
+
}
|
|
37
|
+
]
|
|
38
|
+
```
|