Skip to content

Commit 666b203

Browse files
sokolivasokoliva
authored
ci: consolidate agent guidance in AGENTS.md and improve mistake-reflection workflow (#1059)
## Description Restructures the AI/agent guidance for this repo around three changes: 1. **Promotes `AGENTS.md` to the source of truth** for agent instructions; reduces `GEMINI.md` to a redirect stub. 2. **Adds a mistake-reflection workflow** — a cross-agent SKILL.md plus an `evidence_rules.md` for graduated learnings. 3. **Trims `mandatory_checks.md`** to use the existing `scripts/lint.sh` instead of restating its commands. ## Why move from GEMINI.md to AGENTS.md `AGENTS.md` is the cross-agent convention now supported by Gemini, Claude Code, OpenCode, Cursor, Codex CLI, etc. — a single file every modern agent auto-loads. `GEMINI.md` is Gemini-specific. ## Mistake reflection workflow When you notice the agent made a mistake: 1. Tell it. A simple "no, that's wrong" or "where do you see this?" should auto-trigger the mistake-reflection skill. If it doesn't, ask explicitly: "load the mistake-reflection skill." If you're using OpenCode (or a similar agent CLI that supports skills), you'll see mistake-reflection listed under /skills once the session has discovered it. 2. Review the new entry the agent appends to docs/ai/ai_learnings.md (gitignored, local-only). Make sure the root cause and proposed rule actually match the mistake. 3. If the rule is generally useful, ask the agent to promote it to docs/ai/evidence_rules.md (or another tracked file) so future sessions see it. Otherwise leave it in the journal — or delete it if it's a one-off.
1 parent 8a82061 commit 666b203

5 files changed

Lines changed: 187 additions & 71 deletions

File tree

‎.agents/skills/mistake-reflection/SKILL.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
name: mistake-reflection
3+
description: Use when you discover you made a mistake — caught by the user, by a tool result, by your own re-reading, or by a failed check. Appends a structured entry to docs/ai/ai_learnings.md and re-reads recent entries to avoid repeats.
4+
---
5+
6+
# Mistake Reflection
7+
8+
Implements the mistake-handling step of `AGENTS.md` §"Mandatory
9+
workflow".
10+
11+
## When to load this skill
12+
13+
Trigger on ANY of these, without waiting for the user to ask:
14+
15+
- The user corrects a factual claim, code change, or assumption.
16+
- A tool result contradicts something you just stated or did
17+
(lint failure, test failure, type-check failure, file not found,
18+
command exit non-zero on something you said would succeed).
19+
- You re-read a file or doc and realize a prior statement was wrong
20+
or unverified.
21+
- You realize mid-task that you skipped a required step
22+
(e.g. didn't read `docs/ai/coding_conventions.md`,
23+
`docs/ai/mandatory_checks.md`, or `docs/ai/evidence_rules.md` at
24+
task start).
25+
- You stated an inference as a fact without a `file:line` citation
26+
and later had to walk it back.
27+
28+
If unsure whether something counts: it counts. False positives are
29+
cheap; false negatives are how the same mistake recurs.
30+
31+
## Procedure
32+
33+
Do these in order. Do NOT defer to the end of the task.
34+
35+
1. **Acknowledge the mistake to the user explicitly** in the current
36+
response. One or two sentences. No hedging, no minimization.
37+
2. **Read recent entries** in `docs/ai/ai_learnings.md` (at minimum
38+
the last 5 entries, or the whole file if shorter). If the current
39+
mistake is a recurrence of an existing rule, say so explicitly and
40+
reference the prior entry's date — do not silently duplicate.
41+
3. **Append a new entry** to `docs/ai/ai_learnings.md` using the
42+
template below. Append; do not rewrite existing entries.
43+
4. **Continue the original task** only after steps 1–3 are done.
44+
45+
## Entry template
46+
47+
Copy this verbatim, fill in each field, append to the end of the file
48+
(after the existing `---` separator):
49+
50+
```markdown
51+
## YYYY-MM-DD — <one-line summary>
52+
53+
- **Mistake**: What went wrong. Be concrete. Quote the wrong claim or
54+
describe the wrong action. Include `file:line` references where
55+
applicable.
56+
- **Trigger**: How the mistake surfaced (user correction, tool output,
57+
self-review). Include the specific signal if it was a tool result.
58+
- **Root cause**: Why it happened. Distinguish between (a) missing
59+
knowledge, (b) skipped verification step, (c) false assumption from
60+
pattern-matching, (d) workflow gap. Avoid generic "I didn't think
61+
carefully" — name the specific failure mode.
62+
- **Recurrence of**: If this matches an existing rule, link to the
63+
prior entry's date. Otherwise write "new".
64+
- **Rule**: A concrete, checkable rule that would have prevented this.
65+
Phrase as an imperative ("Before X, do Y"). If the rule already
66+
exists and was violated, the rule should be about *enforcement*
67+
(e.g. a check to add to a skill, a step to add to AGENTS.md), not a
68+
restatement of the existing rule.
69+
```
70+
71+
## Anti-patterns to avoid
72+
73+
- **Don't restate the same lesson with new wording.** If
74+
you'd write essentially the same rule again, the real fix is to
75+
make the rule self-enforcing (update a skill or `AGENTS.md`), not
76+
to add a third entry.
77+
- **Don't let rules go stale.** When you read prior entries, flag stale
78+
tooling references and either update them or note the staleness in your
79+
new entry.
80+
- **Don't write rules that depend on you remembering to follow them.**
81+
If a rule is "remember to do X at the start of every task", it will
82+
be skipped. Prefer rules that bind to a tool, a skill trigger, or a
83+
CI check.
84+
- **Don't bury the acknowledgement.** Tell the user up front in the
85+
response that you got it wrong, before describing the fix.
86+
87+
## Cleanup ritual
88+
89+
Before appending, check the file's length:
90+
91+
- **≥ 10 entries**: pause and propose to the user that one or more
92+
entries be either (a) deleted (if obsolete or one-off), or (b)
93+
promoted into the workflow somewhere it will actually be read. If
94+
the candidate rule is about claims/citations/evidence specifically,
95+
`docs/ai/evidence_rules.md` is a natural target — otherwise leave
96+
the choice of destination to the user. Do this *before* adding the
97+
new entry, so the file doesn't grow monotonically and stop being read.
98+
99+
This ritual is the only mechanism preventing `ai_learnings.md` from
100+
becoming a write-only graveyard.
101+
102+
## Repo-specific notes
103+
104+
- `docs/ai/ai_learnings.md` is **gitignored**.
105+
Entries are local to the developer's checkout and will not be seen
106+
by other agents or in CI. The file is for the human developer to
107+
improve `AGENTS.md` / skills based on patterns.
108+
- The protocol source and trigger pointer both live in `AGENTS.md`
109+
§"Mandatory workflow". `GEMINI.md` is a deprecated stub.
110+
- Date format is `YYYY-MM-DD` to match existing entries.

‎AGENTS.md‎

Lines changed: 43 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,44 @@
1-
Always check @./GEMINI.md for the full instruction list.
1+
# AGENTS.md
2+
3+
Python SDK for the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/latest/specification/)
4+
(`a2a` module, `a2a-sdk` distribution). It handles complex messaging, task management,
5+
and communication across different transports (REST, gRPC, JSON-RPC).
6+
7+
## Technology Stack & Architecture
8+
9+
- **Language**: Python 3.10+
10+
- **Package Manager**: `uv`
11+
- **Lead Transports**: Starlette (REST/JSON-RPC), gRPC
12+
- **Data Layer**: SQLAlchemy (SQL), Pydantic (Logic/Legacy), Protobuf (Modern Messaging)
13+
- **Key Directories**:
14+
- `/src`: Core implementation logic.
15+
- `/tests`: Comprehensive test suite.
16+
- `/docs`: AI guides and migration documentation.
17+
18+
## Mandatory workflow
19+
20+
You MUST do all of the following:
21+
22+
1. **At the start of every task that touches files**, read
23+
`docs/ai/coding_conventions.md`, `docs/ai/mandatory_checks.md`,
24+
and `docs/ai/evidence_rules.md`.
25+
2. **Before declaring any task done**, run the full check sequence
26+
in `docs/ai/mandatory_checks.md` — including for
27+
markdown/comment/whitespace-only changes.
28+
3. **On any mistake**, load the `mistake-reflection` skill at
29+
`.agents/skills/mistake-reflection/SKILL.md` **before** continuing
30+
your response. The skill appends a structured entry to
31+
`docs/ai/ai_learnings.md` (gitignored local journal) so the user
32+
can use those findings to improve the workflow.
33+
34+
When unsure: load the skill. False positives are free; false
35+
negatives are how the same mistake recurs.
36+
37+
38+
## Optional extras
39+
40+
`pyproject.toml` defines extras (`grpc`, `telemetry`, `postgresql`,
41+
etc.). The dev group installs `a2a-sdk[all]`, so anything gated behind
42+
an extra must still **import lazily** at runtime — the install-smoke
43+
harness verifies this per profile.
244

3-
This file exists for compatibility with tools that look for AGENTS.md.

‎GEMINI.md‎

Lines changed: 0 additions & 48 deletions
This file was deleted.

‎docs/ai/evidence_rules.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Evidence Rules
2+
3+
Rules for what counts as adequate evidence when making claims about
4+
this codebase. These are graduated learnings — promoted from
5+
`docs/ai/ai_learnings.md` (local journal) once a rule has earned a
6+
permanent home.
7+
8+
When in doubt, the bar is: **a future agent reading your response
9+
should be able to verify the claim from the citations alone, without
10+
re-doing your investigation.**
11+
12+
## Claims about runtime behavior
13+
14+
Back any claim about how code behaves at runtime with a `file:line`
15+
reference from a tool call in the same response, or with a runnable
16+
demonstration.
17+
18+
The citation must support the specific claim. The *existence* of code
19+
is not evidence of its *behavior*: a function being defined doesn't
20+
mean it's called; an exception being raised doesn't mean it
21+
propagates; a parameter being declared doesn't mean it's honored; a
22+
config option existing doesn't mean it takes effect. Behavior claims
23+
require control-flow evidence (call chain, test output, log) — not
24+
just a definition site.

‎docs/ai/mandatory_checks.md‎

Lines changed: 10 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,25 +1,14 @@
1-
### Test and Fix Commands
1+
# Mandatory Checks
22

3-
Exact shell commands required to test the project and fix formatting issues.
3+
Run in this order before declaring any task done — including for
4+
markdown/comment/whitespace-only changes:
45

5-
1. **Formatting & Linting**:
6-
```bash
7-
uv run ruff check --fix
8-
uv run ruff format
9-
```
6+
```bash
7+
./scripts/lint.sh # ruff check --fix, ruff format, ty check
8+
uv run pytest
109

11-
2. **Type Checking**:
12-
```bash
13-
uv run ty check
14-
```
10+
# Only before commit, when src/ changed:
11+
uv run pytest --cov=src --cov-report=term-missing
12+
```
1513

16-
3. **Testing**:
17-
```bash
18-
uv run pytest
19-
```
20-
21-
4. **Coverage**:
22-
Only run this command after adding new source code and before committing.
23-
```bash
24-
uv run pytest --cov=src --cov-report=term-missing
25-
```
14+
CI enforces `--cov-fail-under=88` on the `a2a` package.

0 commit comments

Comments
 (0)