[Feat]: Add a task-state-invariants agent skill for sibling-surface propagation
Maintainers usually reply within 2 days
Assessment
This issue has not been assessed yet.
Description
Is your feature request related to a problem? Please describe
The agent rule layer in this repo is good at three things: code style
(docs/ai/coding_conventions.md), the pre-done gate
(docs/ai/mandatory_checks.md), and post-mortem capture
(.agents/skills/mistake-reflection). What none of them state is which
surfaces a task-state write has to reach. That gap keeps producing the same
class of defect: a value that is correct on one surface and missing or stale
on another.
Recent instances, all in this class:
- #1276 (closed):
status.timestampwas mapped by
src/a2a/compat/v0_3/conversions.py(JSON-RPC/REST compat) but not by
src/a2a/compat/v0_3/proto_utils.py(gRPC compat) — the same field appeared
or disappeared depending on transport. - #1331 (open): a framework-written
FAILEDstatus carried no
status.timestamp, andsrc/a2a/server/tasks/database_task_store.py:152-157
deriveslast_updatedfrom it, so the row persistedNULLand dropped out
ofListTasksordering. - #1188 (open) / #1409 (open): the handler resumes or returns from a snapshot
that disagrees with what later reaches the store and the stream. - #1206 (closed as stale) → #1411 (open):
contextIdinference makes events
disagree with the storedTask. - Review findings on #1346: stamping the local copy after
task.status.CopyFrom(event.status)leaves the published event unstamped
(src/a2a/server/tasks/task_manager.py:285), and theCANCELEDpaths at
src/a2a/server/agent_execution/active_task.py:971-973keep the previous
state's timestamp. These were caught by review, not by any documented rule.
The same confusion shows up in the discussion forum, where it has no issue
tracker to land in: #248 ("Should Message events terminate…", 6 comments),
#435, #40 ("What's the purpose of EventQueue?"), and the multi-replica thread
#1224 / #336.
Describe the solution you'd like
A new skill, .agents/skills/task-state-invariants/SKILL.md, in the same
shape as mistake-reflection (trigger list → procedure → anti-patterns),
covering:
- the invariant set, each claim anchored to current
main(terminal states
need a timestamp; stamp the event beforeCopyFrom;CopyFrominherits
the old timestamp; push delivery is best-effort; zero events means a hung
caller; store and stream must agree; v0.3 compat has two independent
mappers; continuation identity is inferred per spec §3.4.3); - a sibling-surface checklist to run before declaring such a change done
(persisted store, streaming subscribers, push notification, cluster
task_eventstable, both compat mappers); - a test map naming the existing file per surface, so coverage lands where
the surface is; - the evidence a PR in this area should carry, consistent with
docs/ai/evidence_rules.md.
Plus a one-line pointer in AGENTS.md "Mandatory workflow". That pointer
matters: AGENTS.md is the only file in the repo that routes to
.agents/skills/, so a skill without a route is never loaded.
Describe alternatives you considered
- A
docs/ai/rules page. Rejected as the primary form:docs/ai/*is
read at task start, while this knowledge is only useful at the moment you
touch a status write — which is howmistake-reflectionis structured.
Happy to have both if maintainers prefer the rule text to live indocs/ai
with the skill as a thin pointer. - Encoding it only in tests. Partially useful, but tests cannot tell a
change agent which sibling surface they forgot. - Fixing each bug as it arrives. Six-plus in about six weeks suggests the
per-bug loop is not converging.
Additional context
Scouting the rule layer, .agents/skills/ has exactly one skill today and it
was introduced internally by #1059 — I found no precedent for an externally
contributed skill, so raising this first rather than assuming. A draft
implementation (skill + the one-line router pointer, markdown-only, no
runtime code) is ready and filed as a PR linked to this issue. Easy to trim:
drop the AGENTS.md line, or scope the skill to the compat-mapper and
timestamp rules only.
Code of Conduct
- I agree to follow this project's Code of Conduct
- Dominant language
- Python
- Stars
- 2.2k
- Forks
- 540
- Avg merge
- 2d 9h
- Merged PRs (30d)
- 56
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from a2aproject/a2a-python
-
[Bug]: `A2A-Version` validation ignores minor versions and the query parameterPossibly taken @rohityan claimed this 82 days ago. Opencomponent: server status:awaiting response status:stale
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
a2aproject/a2a-python#1204 · 4 comments · 1 assignee ·
Maintainers usually reply within 2 days
-
[Bug]: REST task/request id sanitizationMay be free again A pull request for this issue was closed without being merged. Openmaintainers-only
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
a2aproject/a2a-python#805 · 1 comment ·
Maintainers usually reply within 2 days
-
[Bug]: JSON-RPC client ignores the JSON-RPC error body when the HTTP status is not 2xxPossibly taken @rohityan claimed this today. Open
a2aproject/a2a-python#1475 · 2 assignees ·
Maintainers usually reply within 2 days
-
[Feat]: validate_input_modes: match media ranges such as image/* declared in the agent cardPossibly taken @rohityan claimed this 2 days ago. Open
a2aproject/a2a-python#1468 · 2 assignees ·
Maintainers usually reply within 2 days
-
Required extensions aren't enforced, so ExtensionSupportRequiredError is never raisedPossibly taken @rohityan claimed this 2 days ago. Opencomponent: server status:awaiting response
a2aproject/a2a-python#1467 · 1 comment · 1 assignee ·
Maintainers usually reply within 2 days
All issues in a2aproject/a2a-python
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 1 day
-
documentation
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Maintainers usually reply within 1 day
-
Install the skills as a Claude Code pluginPossibly taken @ruban-24 claimed this today. Open
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
Maintainers usually reply within 6 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
FAIRmat-NFDI/pynxtools#874 ·
-
Eval: PublicationOpendata
Difficulty 2/5 1-3 hours Newbie friendliness 66/100