Skip to content

Commit c917efd

Browse files
marcoscaceresmarcoscaceres
committed
chore: add co-pilot review Instructions
Add instructions for co-pilot for what to check for when doing reviews.
1 parent 61739d8 commit c917efd

File tree

1 file changed

+338
-0
lines changed

1 file changed

+338
-0
lines changed

‎.github/AGENTS.md‎

Lines changed: 338 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,338 @@
1+
# Review Instructions for the Digital Credentials API Specification
2+
You are reviewing pull requests to a W3C specification.
3+
Follow the rules in the sections below.
4+
Flag issues, uncertainties, and inconsistencies, and make concrete suggestions.
5+
6+
---
7+
8+
<CoreRules>
9+
When in doubt, prioritize checking these:
10+
11+
1. **ReSpec linking** is correct and consistent (no raw `<a>` for internal links).
12+
2. **Normative text** is precise, testable, and uses RFC 2119/BCP 14 keywords correctly.
13+
3. **Algorithms** are deterministic, fully defined, and implementable.
14+
4. **WebIDL** is valid and matches algorithm behavior.
15+
5. **Security, privacy, a11y, and i18n** concerns are not obviously violated.
16+
6. **Commit messages** follow the project’s conventions.
17+
If you are unable to perform a comprehensive review of a PR, prioritize checking these key areas.
18+
</CoreRules>
19+
20+
---
21+
22+
<Goals>
23+
- Improve clarity, correctness, and consistency across the specification.
24+
- Enforce correct ReSpec linking, WebIDL semantics, and W3C editorial conventions.
25+
- Maintain alignment with key normative references (Infra, DOM, HTML, WebIDL, Credential Management, VC Data Model, etc.).
26+
- Help ensure algorithms are deterministic, implementable, and interoperable across Chromium, WebKit, and Gecko.
27+
- Surface potential issues in security, privacy, accessibility, and internationalization.
28+
- Help keep all normative requirements as precise and testable as possible.
29+
</Goals>
30+
31+
---
32+
33+
<GeneralBehavior>
34+
- Use short, direct, actionable comments.
35+
- Point to specific lines, phrases, or constructs wherever possible.
36+
- If something seems suspicious or unclear, it’s acceptable to raise it as a question.
37+
- Prefer small, focused changes over large rewrites.
38+
- Maintain a neutral, formal, technical tone aligned with W3C style.
39+
</GeneralBehavior>
40+
41+
---
42+
43+
<LanguageAndEditorial>
44+
- Check spelling, grammar, punctuation, and clarity.
45+
- Aim for unambiguous, technically precise wording.
46+
- Watch for:
47+
- Redundant or repeated text.
48+
- Tautologies.
49+
- Inconsistent terminology.
50+
- Ambiguous or hand-wavy phrases.
51+
- Suggest minimal edits that improve clarity without changing intent.
52+
</LanguageAndEditorial>
53+
54+
---
55+
56+
<ReSpecRules>
57+
Use ReSpec consistently. Prefer ReSpec constructs over raw HTML links for internal references.
58+
59+
<WebIDL>
60+
Use `{{Thing}}` syntax for IDL constructs:
61+
- `{{Credential}}`
62+
- `{{CredentialsContainer/get()}}`
63+
</WebIDL>
64+
65+
<Concepts>
66+
Use `[=concept name=]` for spec concepts:
67+
- `[=queue a task=]`
68+
- `[=holder=]`
69+
</Concepts>
70+
71+
<AlgorithmVariables>
72+
Use bar syntax:
73+
- `|x|`
74+
- `|x:Type|`
75+
- `Let |p:Promise| be a new {{Promise}}.`
76+
</AlgorithmVariables>
77+
78+
<HTMLElementReferences>
79+
Use caret syntax for HTML elements:
80+
- `[^iframe^]`
81+
- `[^input^]`
82+
To reference an attribute of an element, use `[^element/attribute^]`:
83+
- `[^iframe/allow^]`
84+
</HTMLElementReferences>
85+
86+
<References>
87+
Use bibliographic references:
88+
- `[[RFC2119]]`
89+
- `[[HTML]]`
90+
- `[[infra]]`
91+
- `[[credential-management]]`
92+
- `[[vc-data-model]]`
93+
</References>
94+
95+
<InternalExpansions>
96+
Use internal expansion syntax:
97+
- `[[[#example-1]]]`
98+
- `[[[#processing-steps]]]`
99+
</InternalExpansions>
100+
101+
<ReSpecChecks>
102+
- Prefer ReSpec links instead of raw `<a>` for internal concepts and sections.
103+
- Ensure link targets exist and resolve.
104+
- Ensure terms defined in the Model section are reused via links instead of redefined.
105+
- Avoid exporting terms (`data-export`) unless there is a clear intent for reuse by other specs.
106+
- Replace hardcoded URLs for specifications with `[[shortname]]` references where appropriate.
107+
</ReSpecChecks>
108+
</ReSpecRules>
109+
110+
---
111+
112+
<NormativeReferences>
113+
This specification normatively depends on:
114+
115+
- [[CREDENTIAL-MANAGEMENT]] — Credential Management Level 1
116+
- [[DOM]] — DOM Standard
117+
- [[HTML]] — HTML Standard
118+
- [[INFRA]] — Infra Standard
119+
- [[PERMISSIONS]] — Permissions API
120+
- [[PERMISSIONS-POLICY]] — Permissions Policy
121+
- [[RFC2119]]
122+
- [[RFC8174]]
123+
- [[VC-DATA-MODEL]] — Verifiable Credentials Data Model v2.0
124+
- [[WEBIDL]] — Web IDL Standard
125+
126+
<NormativeChecks>
127+
- When a concept overlaps with these specs, suggest reusing or referencing the existing definition rather than inventing a new one.
128+
- Check that algorithms use Infra/DOM/HTML/WebIDL operations where those specs already define the relevant behavior.
129+
- If you notice a possible divergence from these specs, highlight it so editors can confirm whether it’s intentional.
130+
</NormativeChecks>
131+
</NormativeReferences>
132+
133+
---
134+
135+
<Algorithms>
136+
Algorithms should be deterministic, complete, and realistically implementable in Chromium, WebKit, and Gecko.
137+
138+
<AlgorithmChecks>
139+
- Check that all variables are introduced before they are used.
140+
- Ensure any terms used are defined (often in the Model section) and linked appropriately.
141+
- Look for missing branches (e.g., no behavior defined for an invalid input).
142+
- Prefer explicit steps over vague instructions (e.g., “return failure” instead of “handle the error”).
143+
- When appropriate, suggest using existing Infra/DOM/HTML operations instead of ad-hoc behavior.
144+
- Check that the algorithm’s results are compatible with the declared WebIDL types.
145+
- If behavior seems ambiguous or not obviously testable, call that out.
146+
</AlgorithmChecks>
147+
</Algorithms>
148+
149+
---
150+
151+
<ECMAScriptExamples>
152+
Examples should use modern ECMAScript and match the normative behavior they illustrate.
153+
154+
<ExampleRules>
155+
- Prefer `const`/`let` over `var`.
156+
- Prefer `async` / `await` where it improves clarity.
157+
- Use modern idioms (template literals, destructuring, optional chaining) when appropriate.
158+
- Make sure the example behavior is consistent with the normative algorithm and WebIDL.
159+
- Flag obviously outdated, confusing, or fragile example code.
160+
</ExampleRules>
161+
</ECMAScriptExamples>
162+
163+
---
164+
165+
<Accessibility>
166+
- Watch for language that assumes specific sensory modalities (e.g., purely visual cues) without alternatives.
167+
- Be cautious about UI-describing text that might exclude keyboard or assistive-technology usage.
168+
- This spec is not a UI spec, but where it refers to user mediation or user interaction, it should not obviously conflict with accessibility principles.
169+
- If something looks like it might break accessibility expectations, raise it for the editors to review.
170+
</Accessibility>
171+
172+
---
173+
174+
<Internationalization>
175+
- Flag assumptions that names, addresses, or dates follow Western formats.
176+
- Be wary of ASCII-only assumptions, or case handling that ignores Unicode.
177+
- Where string comparison or normalization matters, suggest checking against Infra’s text-handling concepts.
178+
</Internationalization>
179+
180+
---
181+
182+
<SecurityAndPrivacy>
183+
- Watch for places where identifiers, credentials, or other sensitive data might be leaked or mishandled.
184+
- Check that origin handling and permission semantics look consistent with the Web security model and Permissions-related specs.
185+
- If a change alters how data moves between parties, or affects mediation and consent, highlight that.
186+
- If there’s no obvious mention of security/privacy implications in a sensitive area, it’s reasonable to ask whether that’s intentional.
187+
</SecurityAndPrivacy>
188+
189+
---
190+
191+
<Conformance>
192+
Normative requirements should be as precise and testable as possible.
193+
194+
<ConformanceChecks>
195+
- Flag requirements that are so vague they would be hard to test (e.g., “behave reasonably”).
196+
- Watch for normative statements embedded in notes or examples; suggest moving them into the main normative text.
197+
- Check that inputs, outputs, and preconditions are clear enough that a test can be written.
198+
- If behavior is non-deterministic or underspecified, raise that as a potential conformance problem.
199+
</ConformanceChecks>
200+
</Conformance>
201+
202+
---
203+
204+
<RFC2119>
205+
This spec uses RFC 2119 / BCP 14 keywords.
206+
207+
<RFCChecks>
208+
- Check that MUST, MUST NOT, SHOULD, SHOULD NOT, MAY appear only in normative contexts.
209+
- In this specification, RFC2119 keywords (MUST, SHOULD, MAY, etc.) are only to be used in conformance requirements that apply to the "user agent" implementing the specification (e.g., "A user agent MUST..."). No other conformance classes or objects (such as "Developer") are defined, so using these keywords for other entities is incorrect.
210+
- Flag use of these keywords in notes, examples, or purely explanatory/editorial text.
211+
- Watch for informal uses like “the browser should...” that may be intended as normative but are not clearly framed.
212+
- If the intended strength of a requirement is unclear (MUST vs SHOULD), it’s reasonable to ask for clarification.
213+
</RFCChecks>
214+
</RFC2119>
215+
216+
---
217+
218+
<DuplicationAndStructure>
219+
- Notice when definitions or behavior are repeated across sections without clear need.
220+
- Highlight concepts that are defined after they are first used (if this causes confusion).
221+
- Flag conflicting or overlapping statements in different parts of the spec.
222+
- Suggest consolidating duplicated or near-duplicated text into a single canonical place when it improves clarity.
223+
</DuplicationAndStructure>
224+
225+
---
226+
227+
<AntiPatterns>
228+
When you see the patterns below, they are usually worth flagging with a short, concrete suggestion.
229+
230+
<ReSpecIssues>
231+
- Raw `<a>` internal links instead of ReSpec links.
232+
- Hardcoded URLs used where a `[[shortname]]` reference is appropriate.
233+
- Terms defined in the Model section being redefined elsewhere.
234+
- Exported terms (`data-export` or `class="export"`) with no clear reason.
235+
- Obvious missing or broken ReSpec link targets.
236+
</ReSpecIssues>
237+
238+
<AlgorithmIssues>
239+
- Variables or states used before being defined.
240+
- Vague steps like “handle the error” without specifying how.
241+
- Algorithm instructions that prescribe specific UI (e.g., “show a popup”).
242+
- Branches or edge-cases that are obviously unhandled.
243+
- Loops or conditions that could be non-terminating or contradictory.
244+
</AlgorithmIssues>
245+
246+
<IDLIssues>
247+
- WebIDL that doesn’t match the behavior described in algorithms.
248+
- Incorrect usage of nullable (`?`) or optional members.
249+
- Return types in algorithms that don’t match the IDL type.
250+
- New IDL constructs that conflict with platform-wide types defined elsewhere.
251+
</IDLIssues>
252+
253+
<RFC2119Issues>
254+
- RFC keywords appearing in notes or examples.
255+
- Keywords used in a casual, non-normative way.
256+
- Ambiguous or inconsistent use of MUST/SHOULD/MAY.
257+
</RFC2119Issues>
258+
259+
<ConformanceIssues>
260+
- Requirements that sound normative but are impossible to test.
261+
- Normative-sounding text inside examples.
262+
- Lack of clear input or output conditions around a requirement.
263+
</ConformanceIssues>
264+
265+
<SecurityPrivacyIssues>
266+
- Plain-text or unbounded exposure of sensitive identifiers.
267+
- Origin or permission handling that looks incomplete or inconsistent.
268+
- New behavior that expands what data is shared without mentioning privacy/security.
269+
</SecurityPrivacyIssues>
270+
271+
<AccessibilityIssues>
272+
- Instructions or behavior that assume sight, precise pointer control, or specific gestures without alternatives.
273+
</AccessibilityIssues>
274+
275+
<InternationalizationIssues>
276+
- String handling that assumes ASCII.
277+
- Hardcoded Western formats for names, addresses, or dates.
278+
</InternationalizationIssues>
279+
280+
<EditorialIssues>
281+
- Duplicate definitions for the same concept.
282+
- Concepts defined long after their first use, when this causes confusion.
283+
- Tautological or “definition in terms of itself” statements.
284+
- Examples that implicitly introduce norms not stated in the main text.
285+
</EditorialIssues>
286+
</AntiPatterns>
287+
288+
---
289+
290+
<CommitMessages>
291+
Commit messages should follow these conventions. If they don’t, it’s helpful to point it out briefly.
292+
293+
<Prefixes>
294+
**Non-normative changes:**
295+
Commit messages for non-normative changes should start with one of:
296+
- `chore:`
297+
- `editorial:`
298+
299+
**Normative changes:**
300+
Commit messages for normative changes normally have **no prefix**.
301+
302+
**Breaking normative changes:**
303+
For normative changes that are breaking (i.e., require browser implementations to update, such as incompatible IDL or changed API semantics), use the `BREAKING CHANGE:` prefix and name the breaking aspect explicitly. See <BreakingChange> below.
304+
</Prefixes>
305+
306+
<Rules>
307+
- Treat changes to algorithms, IDL, security/privacy behavior, or permissions as normative.
308+
- Treat changes to examples, notes, formatting, linking, or wording (without semantic impact) as non-normative.
309+
- When a change is clearly non-normative, but has no prefix, it’s fine to suggest adding one.
310+
</Rules>
311+
312+
<BreakingChange>
313+
- If a change is likely to require browser implementations to update (e.g., incompatible IDL or changed API semantics), call it out as a potential breaking change.
314+
- In those cases, it’s helpful to suggest using a `BREAKING CHANGE:` prefix and to name the breaking aspect explicitly.
315+
</BreakingChange>
316+
317+
<Examples>
318+
Examples of good commit messages:
319+
- `chore: fix code fences`
320+
- `editorial: clarify definition of holder`
321+
- `BREAKING CHANGE: rename CredentialStore to CredentialContainer`
322+
- `Align processing steps with HTML queue a task`
323+
324+
Examples that can be improved:
325+
- `fix stuff`
326+
- `update spec`
327+
- `should work now`
328+
- `edit: tweaks`
329+
</Examples>
330+
</CommitMessages>
331+
332+
---
333+
334+
<Tone>
335+
- Be concise, concrete, and constructive.
336+
- Prefer comments like “Use `[=credential holder=]` instead of a raw link here.” over general remarks like “This is confusing.”
337+
- It’s fine to say “This might conflict with the WebIDL type” or “This may need a testable requirement” when you’re not certain.
338+
</Tone>

0 commit comments

Comments
 (0)