Skip to content

docs: complete the README layout tree for all ten packs - #75

Merged
sairenchristianbuerano merged 1 commit into
trustabl:mainfrom
bradAGI:docs/readme-layout-all-packs
Sep 21, 2026
Merged

sairenchristianbuerano merged 1 commit into
trustabl:mainfrom
bradAGI:docs/readme-layout-all-packs

Conversation

@bradAGI

@bradAGI bradAGI commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

The layout tree documented four of the ten packs and carried a note asking readers to browse the directory listing "until this section catches up." This catches it up: claude_skill/, langchain/, crewai/, autogen/, pydantic_ai/, and vercel_ai/ are added and the note is dropped.

Checking the existing entries against the packs turned up six that had gone stale as rules shipped. None of these appeared in the tree:

file missing from the tree
claude_sdk/agent_safety.yaml CSDK-121..124 (the 120/130/131 shorthand also hid the real set)
claude_sdk/repo.yaml CSDK-204
claude_sdk/subagent_safety.yaml CSDK-112
claude_sdk/tool_definition.yaml CSDK-017, CSDK-018
openai_sdk/agent_safety.yaml OAI-112
mcp/tool_definition.yaml MCP-015..022 — the whole go/csharp/php/rust set

Those are corrected here too. The MCP one seemed worth calling out: multi-language MCP coverage is a genuinely notable capability and the README gave no sign it existed.

Also added a line where the ID convention is stated, noting the two packs that don't follow it — autogen/ numbers its agent rules AG2-001..006 in the tool range, and claude_skill/ groups CSKILL-NNN by topic rather than scope. Both currently read as violations of the documented scheme.

Verification. Not checked by eye — I wrote a script that parses the tree out of the README, expands the A-001..005 range notation, and diffs the claimed IDs against every - id: in every file, asserting both directions plus "no rule file left undocumented":

OK: 85 rule files documented, every rule ID matches the tree
$ trustabl rules validate .
OK: 85 rule pack(s), 206 rule(s) valid under rule schema version 14

Happy to contribute that script as a CI check if you'd want the tree kept honest automatically — it's ~40 lines of stdlib Python and would have caught all six drifts at the commit that introduced them. Say the word and I'll open a separate PR.

Deliberately documents only what's on main today, so it doesn't conflict with the rule PRs I have open.

The tree documented four of the ten packs and carried a note asking
readers to browse the directory listing until it caught up. This adds
claude_skill, langchain, crewai, autogen, pydantic_ai, and vercel_ai and
drops the note.

Checking the existing entries against the packs turned up six that had
gone stale as rules shipped: CSDK-121..124 and CSDK-130/131, CSDK-204,
CSDK-112, CSDK-017/018, OAI-112, and the eight go/csharp/php/rust MCP
rules MCP-015..022 — none of which appeared in the tree. Those are
corrected here too.

Also notes where the ID convention does not hold: autogen numbers its
agent rules AG2-001..006 in the tool range, and claude_skill groups
CSKILL-NNN by topic rather than scope.

Verified mechanically rather than by eye — a script parses the tree,
expands the range notation, and diffs the claimed IDs against `- id:`
in every file, asserting both directions and that no rule file is left
undocumented.
@jhumel-code

Copy link
Copy Markdown
Collaborator

Thanks @bradAGI, this is careful work. I walked the whole tree against origin/main and everything you added or corrected checks out: the six drifts are real, the MCP-015..022 multi-language set and CSDK-121..124 were genuinely invisible, and nothing in the new tree names a rule that does not exist. Dropping the stale note is the right call.

Two things before I take it. ADK-111 (MCPToolset with no tool_filter) landed in google_adk/agent_safety.yaml after you branched, and that line still reads ADK-101..108, ADK-110. A rebase and a re-run of your checker should pick it up.

The ID convention sentence is not quite right. It is not two packs: CSDK-107 and CSDK-108 are tool scope sitting in the 1NN range, CREW-108 likewise, and ADK-008, VAI-006..009 and VAI-012 sit in the tool range at agent and repo scope. That is fourteen rules across five packs, plus claude_skill/. I would rather the line said the numbering is advisory and that a number of rules predate it, than name two packs and leave the rest reading as compliant. While you are in there, please rewrap that paragraph; the inserted sentence runs well past the file's wrap width.

No engine-side pair is needed for this one, scripts/check-rules-sync.sh deliberately excludes docs from the comparison. And yes, please do open the checker as its own PR.

Happy to take this once ADK-111 and the convention sentence are sorted.

@sairenchristianbuerano
sairenchristianbuerano merged commit 7bf3a35 into trustabl:main Sep 21, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants