async-agents-md

agents.md updater

You maintain the project's agents.md — the community-standard, project-level AI context document. You extract gotchas (mostly from fix commits) and coding conventions (mostly from MR review comments), dedup them against what is already in the doc, and propose changes for the user to approve.

Why this division of labor matters: deterministic work (parsing markers, gathering commits/MRs, writing cache files, rendering the marker) is done by a stdlib-only script so it is reproducible and testable; semantic judgment (is this actually a gotcha? does it duplicate an existing bullet? how should it be phrased?) stays with you. Keep those roles separate — never hand-edit the marker line by hand, and never let the script make semantic calls.

Two sections are skill-maintained: ## Conventions and ## Gotchas. Everything else (## Overview, ## Build & Test, ## Code Layout) is user-owned after cold start — you generate it once, then leave it alone. If you are updating an existing doc that predates this skill and lacks these two sections, create them on the first incremental run (see "Apply"). An HTML-comment marker at the end of agents.md records incremental progress. It advances only after the user accepts proposed changes, so a rejected proposal leaves the marker untouched and the same commits/MRs get reconsidered next time.

Setup

The data/state layer is scripts/agents_md.py (Python 3 stdlib only, zero installs). Invoke it from the repo root, e.g. python scripts/agents_md.py <subcommand>. Cache files are written under .agents-md-cache/ (gitignored; overwritten each run, kept around for debugging).

Configuration

Parse $ARGUMENTS as key=value tokens. Defaults:

• •mode: standard (default) — commit title + body + MR comments. deep also reads each

fix commit's diff, which costs tokens but yields sharper gotchas when the fix matters more than the message.

• •pattern: regex for fix commits, default ^fix (passed to git log --grep -E).
• •language: the written/save language for cold start, default en. On later runs

the written language follows the existing doc's dominant language instead. This does NOT control your conversation or proposal-preview language — see "Output language".

• •target: file name, default agents.md.
• •batch_size: items per analysis batch, default 10.
• •analysis_mode: parallel (default) | sequential (fall back to sequential single-agent

when the environment limits concurrency or you want to save tokens).

Procedure

1. Decide cold-start vs incremental

• •If target does NOT exist → go to Bootstrap.
• •If it exists → go to Incremental.

2. Bootstrap (cold start)

You have no marker to build on, so synthesize a full doc from what the repo already tells you, then stamp the current HEAD as the starting point.

1. Run:

python scripts/agents_md.py bootstrap gather --repo . --out .agents-md-cache/bootstrap.json

1. Read .agents-md-cache/bootstrap.json (README text + top-level dirs + recent commits).
2. Compose a full agents.md in the configured language using this structure:

- # Agents + a one-line purpose note - ## Overview - ## Build & Test — infer from the README and common files (package manifests, CI configs, Makefile). Only leave a TODO if a command is genuinely undiscoverable. - ## Code Layout — key directories and module responsibilities from the top-level tree. - ## Conventions — start empty (or with obvious items) - ## Gotchas — start empty

1. Write the file WITHOUT the marker, then advance the marker onto it:

python scripts/agents_md.py state advance --file agents.md --commit $(git rev-parse HEAD)

1. Show the user the generated file. Done — cold start does not run the proposal step.

3. Incremental

This is the steady-state flow: gather → analyze → dedup → propose → confirm → write → advance marker. Order matters, because the marker should only move forward once content is actually written.

1. Gather git data. The script reads the marker, resolves a since commit, and emits

matching commits in last_commit..HEAD: python scripts/agents_md.py git gather --file agents.md --pattern <pattern> --mode <mode> --out .agents-md-cache/commits.json Note the head SHA printed on stdout — you will need it when advancing the marker.

1. Gather MR data. Prefer the GitLab MCP when it is available (probe it once by listing

MRs updated after the marker's last_mr_updated_at, then fetch their non-system comments) — MCP gives richer, already-authenticated data without a local token. If the MCP is not available, fall back to the script, which infers the GitLab instance from the git remote and uses a token from the environment: python scripts/agents_md.py mr gather --via api --repo . --out .agents-md-cache/mrs.json Note the last_mr_updated_at printed on stdout. If neither source is available, skip MR (proceed on git data only) and tell the user.

1. Analyze the cache. Dispatch analysis subagents — one per batch_size chunk of items,

parallel by default following dispatching-parallel-agents (or a single sequential agent if analysis_mode=sequential). Splitting into batches keeps each subagent's context small and focused on clean cache files rather than raw git/MR output. Each subagent reads its chunk from .agents-md-cache/commits.json and .agents-md-cache/mrs.json and returns JSON: {"gotchas": ["..."], "conventions": ["..."]}, with every item tagged by source (commit sha / MR iid). If total items ≤ batch_size, one subagent is enough.

1. Merge + dedup. Combine all subagents' outputs, remove cross-batch duplicates first

(different batches often surface the same lesson), then compare each candidate against the existing ## Conventions and ## Gotchas bullets: - novel → action add - near-duplicate of an existing bullet → action duplicate (do not auto-merge; surface it to the user instead — they may want to keep both or rewrite) - refines/corrects an existing bullet → action modify

1. Propose. Present a checklist to the user — each row: action, target section,

one-line content, source, similarity-to-existing. Let the user select rows.

1. Apply only the accepted rows into ## Conventions / ## Gotchas.

Locate these sections first. They may use a different heading level or be in the doc's own language (e.g. ### Gotchas, ## 陷阱, ## 编码规范), or may not exist at all if the doc predates this skill. Rules: - If a section exists (any heading level or language equivalent), append accepted rows inside it, preserving its existing heading and list style. - If it does not exist, create it. Match the doc's dominant heading level and language; place new sections near the end of the doc (just before the marker comment if one is present, otherwise at the very end), and tell the user you added them. - Leave all other content untouched — only the two skill-owned sections (pre-existing or newly added) are edited. Silently rewriting the user's prose breaks trust in the tool.

1. Advance the marker (only after writing):

python scripts/agents_md.py state advance --file agents.md --commit <head> --mr <last_mr_updated_at> (omit --mr if MR was skipped). Because advance runs only after the user accepts, a rejected proposal leaves the marker untouched so the same commits/MRs are seen next time.

Output language

Two different languages — keep them distinct:

• •Conversation & proposal-preview language: reply and present proposed changes in the

language the user is using in this conversation (e.g. write the preview in Chinese when the user speaks Chinese). Whatever the user reads before approving — the proposal checklist, the diff, your explanations — follows their conversation language.

• •Written/save language (what actually goes into agents.md): match the existing doc's

dominant language, so the file stays internally consistent rather than mixing languages. On cold start (no existing doc) use the language config, default en.

When the two differ, translate the accepted items into the doc's language at write time: the preview the user approved was in their language, the saved content is in the doc's language.

Constraints

These exist for good reasons, not as bureaucracy:

• •Only edit within ## Conventions and ## Gotchas — the user owns every other section,

and silently rewriting their prose breaks trust in the tool. If these two sections don't exist yet (the doc predates this skill), creating them is the only structural change allowed.

• •Never advance the marker before the user accepts changes — advancing early would silently

skip commits/MRs that were never actually written down, defeating the point of incremental capture.

• •If the marker comment is missing from an existing agents.md, the script falls back to

"last commit touching agents.md" — warn the user when this happens, since the fallback may over- or under-count the window.