Skip to content

[Feat]: Add a task-state-invariants agent skill for sibling-surface propagation #1413

Description

@Linux2010

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:

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:

  1. the invariant set, each claim anchored to current main (terminal states
    need a timestamp; stamp the event before CopyFrom; CopyFrom inherits
    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);
  2. a sibling-surface checklist to run before declaring such a change done
    (persisted store, streaming subscribers, push notification, cluster
    task_events table, both compat mappers);
  3. a test map naming the existing file per surface, so coverage lands where
    the surface is;
  4. 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 how mistake-reflection is structured.
    Happy to have both if maintainers prefer the rule text to live in docs/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

Activity

  1. Linux2010 commented on Nov 2, 2026

    @Linux2010
    ContributorAuthor

    Draft PR with the concrete proposal is up: #1414

    It is intentionally a draft — I did not find precedent for an externally contributed entry in .agents/skills/ (mistake-reflection was introduced internally in #1059), so I would rather confirm appetite here than have a PR land on the review queue uninvited.

    Two decisions I would like input on before marking it ready:

    1. Should the invariant text live in the skill (as drafted) or in docs/ai/ with the skill kept as a thin pointer? The repo currently uses both shapes — docs/ai/evidence_rules.md calls itself "graduated learnings promoted from ai_learnings.md once a rule has earned a permanent home", so docs/ai/ is a legitimate home for the rule set too.
    2. Is the added numbered item in AGENTS.md welcome, or should the router stay three steps and rely on docs/ai/ for discovery?

    The skill body itself is ready either way — reshaping it is a copy edit, not a rewrite.

  2. Linux2010 commented on Nov 2, 2026

    @Linux2010
    ContributorAuthor

    One scoping note: this pass actually surfaced a second skill candidate, which I deliberately did not bundle in.

    .agents/skills/ covers the reactive step of the mandatory workflow (mistakes) and this PR adds the missing domain invariant step, but the CI-enforced gate itself (docs/ai/mandatory_checks.md) still has no procedure for the part that costs contributors the most time: telling pre-existing diagnostics from newly introduced ones, and telling a real regression from an environment artifact. Two concrete examples from work in this area:

    • a per-file coverage report flagged -25% on a refactored module, which looked like a regression but was unreachable dead code introduced by the refactor itself;
    • tests/integration/cross_version/... intermittently errors with Server ... HTTP failed to start in sandboxes that cannot bind the subprocess server — indistinguishable from a real failure unless you re-run against a stashed clean main.

    Both have a cheap, deterministic answer (stash-baseline diff for diagnostics; standalone re-run plus clean-checkout comparison for suite errors). If there is appetite for a second skill along those lines, I would rather land it as its own PR after this one is shaped, since it is the same rule layer and I do not want to make this review carry two decisions.

  3. added theissue type on Nov 2, 2026
  4. added
    component: toolingIssues related to scripts for type generation, code formatting, and managing development workflows.
    on Nov 2, 2026
  5. rohityan commented on Nov 2, 2026

    @rohityan

    Hi @Linux2010, thanks for this proposal.

    Regarding your design questions:

    1. Rule location: Hosting the invariant rules directly inside .agents/skills/task-state-invariants/SKILL.md is the cleanest approach. It keeps initial agent context indexing lightweight while loading the full domain checklist on-demand.
    2. Routing in AGENTS.md: Adding the explicit numbered step to AGENTS.md is welcome and preferred; passive discovery via docs/ai/ risks agents bypassing the checklist when modifying task mutations.
    3. Purpose of EventQueue: In a2aproject/a2a-python, EventQueue serves as the bounded, asynchronous buffer decoupling event publishers (TaskManager.save_task_event) from downstream consumers (ActiveTask, push notifications, and persistence) to ensure non-blocking dispatch and serialized updates.

    Draft PR #1414 looks architecturally sound. Please feel free to mark it ready for review. Assigning this issue to you till the PR gets reviewed.

  6. Linux2010 commented on Nov 12, 2026

    @Linux2010
    ContributorAuthor

    Thanks @rohityan — all three answers confirmed the implementation as-is, so I've marked #1414 ready for review.

    Before flipping it, I rebased onto current main (13 commits, including #1345/#1346 — which this skill's invariants literally document) and re-verified all eight file:line anchors against the live code; four had drifted (the cancel-path CopyFrom, the inline push send, the get_task wait, and the copy-on-yield caveat) and were corrected. Claim 5 now notes the caller-side guard merged via #1345.

    One clarification absorbed from your point 3: the skill's EventQueue reference stays descriptive of the publish/consume boundary, not a task-mutation surface.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

component: toolingIssues related to scripts for type generation, code formatting, and managing development workflows.status:awaiting response

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions