Skip to content

docs: complete the CLAUDE.md applies_to tables for every scope - #76

Open
bradAGI wants to merge 1 commit into
trustabl:mainfrom
bradAGI:docs/claude-md-applies-to-tables
Open

bradAGI wants to merge 1 commit into
trustabl:mainfrom
bradAGI:docs/claude-md-applies-to-tables

Conversation

@bradAGI

@bradAGI bradAGI commented Aug 24, 2026

Copy link
Copy Markdown
Contributor

The per-scope applies_to tables listed 20 of the engine's 43 tokens. Every value belonging to the six newer packs was absent — so CLAUDE.md, which the file itself presents as the authoritative rule-authoring contract, gave an author no way to write a LangChain, CrewAI, AutoGen, Pydantic AI, Vercel AI, or Claude-skill rule without going and reading the engine's loader.go. I hit this writing the rule PRs in this series, which is what prompted the fix.

What's added:

  • tool scopelangchain_tool, crewai_tool, pydantic_ai_tool, vercel_ai_tool, autogen_tool, unknown
  • agent scope — the eleven missing classes (LangChain's three, crewai_agent, pydantic_ai_agent, vercel_ai_agent, AutoGen's five)
  • repo scopelangchain, crewai, pydantic_ai, vercel_ai, autogen
  • scope: skill — missing entirely, along with the skill_* predicate family the CSKILL-* rules are built on. The section notes skills carry no language: field, same as subagents.

Two stale notes refreshed while in there: the subagent paragraph claimed one shipped rule where there are now three (CSDK-110/111/112), and the applies_to vs repo_has_sdk_in_code namespace warning now says which tokens agree across the two namespaces, so Claude's mismatch doesn't read as the general case.

Verification. Not checked by eye — a script parses appliesToByScope out of the engine's loader.go and diffs it against the tables scope by scope, then separately asserts every applies_to value used by a shipped rule in this repo appears in them:

ok  scope=agent     all 20 tokens match the engine loader
ok  scope=repo      all 10 tokens match the engine loader
ok  scope=skill     all 1 tokens match the engine loader
ok  scope=subagent  all 1 tokens match the engine loader
ok  scope=tool      all 11 tokens match the engine loader
ok  all 35 applies_to values used by shipped rules are documented
$ trustabl rules validate .
OK: 85 rule pack(s), 206 rule(s) valid under rule schema version 14

Same offer as on #75: happy to contribute this as a CI check so the tables can't drift from the loader again.

Docs only — no rule changes, so it doesn't conflict with the rule PRs I have open.

The per-scope applies_to tables listed 20 of the engine's 43 tokens. Every
value belonging to the six newer packs was absent, so CLAUDE.md — which
the file itself presents as the authoritative rule-authoring contract —
gave an author no way to write a LangChain, CrewAI, AutoGen, Pydantic AI,
Vercel AI, or Claude-skill rule without reading the engine's loader.go.

Adds the missing tool-scope kinds (langchain_tool, crewai_tool,
pydantic_ai_tool, vercel_ai_tool, autogen_tool, unknown), the eleven
missing agent classes, the five missing repo tokens, and a scope: skill
section, which was missing entirely along with the skill_* predicate
family the CSKILL-* rules are built on.

Also refreshes two notes that had gone stale: the subagent paragraph
claimed one shipped rule where there are now three (CSDK-110/111/112),
and the applies_to vs repo_has_sdk_in_code namespace note now says which
tokens agree across the two namespaces rather than leaving Claude's
mismatch to look like the general case.

Verified mechanically rather than by eye — a script parses
appliesToByScope out of the engine's loader.go and diffs it against the
tables, and separately asserts that every applies_to value used by a
shipped rule in this repo appears in them.
@jhumel-code

Copy link
Copy Markdown
Collaborator

Thanks @bradAGI, this is a real gap and you have most of it right. I walked every token against appliesToByScope in internal/rules/loader.go on main: the tool, agent, and repo tables now match the loader exactly, the new scope: skill section is correct, and CSDK-110/111/112 is the right subagent count.

Two things I want fixed first. autogen_code_executor_agent is described as an AutoGen agent configured with a code executor, but agentKindMatches only matches Class == "CodeExecutorAgent". A ConversableAgent carrying code_execution_config will not match that token, and an author reading the table would write a rule expecting it to, so please describe it as the constructor.

Second, the skill_* list omits seven predicates that shipped rules use: skill_dynamic_exec_touches_network_or_secrets, skill_description_tool_mismatch, skill_is_agent_specific, skill_has_duplicate_tool_refs, plus skill_body_has_text, skill_name_has_text and skill_description_has_text. Those last three are the whole basis of claude_skill/skill_quality_text.yaml, so leaving them out reproduces the gap this PR exists to close.

Two smaller ones, take or leave: autogen_group_chat_manager also matches GroupChat(...), and vercel_ai_agent gates on the SDK stamp alone, so it covers generateObject and streamObject too. And yes, please send the drift check as a follow-up.

Happy to take this once those two are corrected.

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.

2 participants