AGENTS.md

1# Requirement Keywords
2 
3Requirement keywords are used in `AGENTS.md` files to indicate instruction strength.
4 
5The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are to be interpreted as described in RFC 2119 and
6RFC 8174
7when, and only when, they appear in uppercase.
8 
9- MUST means an absolute requirement.
10- MUST NOT means an absolute prohibition.
11- SHOULD means a strong default; deviation requires a concrete reason, and the agent MUST state that reason.
12- SHOULD NOT means a strong prohibition by default; deviation requires a concrete reason, and the agent MUST state that
13  reason.
14- MAY means an item is optional.
15 
16# Response Format
17 
18- Agents MUST display summaries at the top of responses, when applicable.
19 
20# Working Principles
21 
22Working principles govern how agents should decide whether to make changes.
23 
241. Agents MUST treat inaction as a potentially valid path to success.
252. Agents MUST ask questions when the request is ambiguous within the current context.
263. Agents MUST NOT make changes unless they are required by the requested outcome or reasonably necessary, within the
27   requested scope, for correctness or adherence to best practices.
28 
29# Working Methodologies
30 
31Working methodologies govern how agents should make changes.
32 
33For non‑trivial tasks, agents MUST operate in reviewable passes. Combined or omitted passes are allowed only for small,
34low‑risk, or explicitly constrained tasks, and agents MUST preserve incremental delivery, clear review boundaries, and
35agreed scope.
36 
37A pass is a bounded iteration toward a stated outcome. Before each pass, agents MUST state the chosen mode, scope,
38intended outcome, expected impact, and any deferred changes. On completion, agents MUST summarise what was changed,
39verified, and deferred, plus any risks or open questions, and MUST NOT proceed to another pass without explicit
40instruction.
41 
42Tracer bullet passes validate direction by implementing the smallest end‑to‑end slice when a solution is uncertain or
43crosses boundaries. Elephant carpaccio passes slice work into small, valuable increments; each slice MUST leave the
44system working and closer to the requested outcome. Future slices are out of scope until agreed; agents MUST NOT add
45speculative features or abstractions.
46 
47Each pass MUST use one of three modes:
48 
491. Feature mode emphasises additive delivery:
50    - implement the smallest useful slice of the requested behaviour;
51    - start with a tracer bullet when the solution shape is uncertain;
52    - proceed via small increments;
53    - use existing architecture unless changes are required for correctness;
54    - avoid speculative features and broad configuration.
55 
562. Fix mode emphasises underlying problems and security:
57    - identify and understand the failure before changing code;
58    - fix the root cause rather than symptoms;
59    - prefer the smallest correct change fitting the current design;
60    - include dedicated error handling when validation or external systems are involved;
61    - verify the behaviour is corrected before finishing;
62    - avoid unrelated refactoring unless required by the fix.
63 
643. Refactor mode emphasises structure and naming:
65    - preserve external behaviour unless change is required or requested;
66    - declare the structural intent of the pass before making changes;
67    - rename and reorganise code when names or boundaries hinder clarity or cohesion;
68    - update all affected references, tests, and documentation;
69    - avoid mixing unrelated cleanup.
70 
71Agents SHOULD perform refinement passes to improve readability, naming, structure, tests, or integration after initial
72slices. Agents MUST finish each feature, fix, or refactor sequence with a security review pass, reviewing for unsafe
73inputs, trust‑boundary issues, secret exposure, and dependency risk, and MUST address in‑scope security issues before
74completion.
75