Add sub-agents frontmatter catalog sync#5
Merged
Conversation
scripts/sync-sub-agents.js reads sub-agents.md's `Supported frontmatter fields` table and writes catalog/sub-agents.json — 16 fields covering the YAML keys a custom subagent definition can carry. Recipe parallels sync-env-vars.js: pure parseRow / parseTable / buildRecords + a thin main(); 16 unit tests against fixture markdown. Wired through read_catalog as the snake-case `sub_agents` field (matching `env_vars`); no UI consumer yet, mirrors how env-vars and hooks are exposed-but-unused. catalog-drift cron now runs sync:sub-agents alongside the other three. Built-in subagent identities and the operational rules around tool restrictions and hooks remain a follow-up pass — they live in prose-heavy sections without a single canonical table.
The previous fixture asserted walk-up from `env.ANTHROPIC_MODEL` lands on `env`, but upstream now documents 145 `env.*` leaves directly — `env.ANTHROPIC_MODEL` is now an exact catalog entry, so byKey hits and the walk-up branch is never exercised. Switch to a genuinely user-only key (`env.MY_CUSTOM_DEBUG_VAR`) so the test still covers what it intends to. Pre-existing failure surfaced by my sub-agents PR's CI run; not caused by it.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Implements catalog synchronization for Claude Code sub-agents' supported frontmatter fields. Adds a new
sync-sub-agents.jsscript that fetches the sub-agents documentation page and extracts the frontmatter fields table intocatalog/sub-agents.json, following the same pattern as existing sync scripts for settings, environment variables, and hooks.Key Changes
New sync script (
scripts/sync-sub-agents.js): Fetcheshttps://code.claude.com/docs/en/sub-agents.md, parses the#### Supported frontmatter fieldstable (identified by header signature| Field | Required | Description |), and writes 16 frontmatter field definitions tocatalog/sub-agents.json. Includes pure functionsparseRow(),parseTable(), andbuildRecords()for testable parsing logic.Comprehensive test suite (
scripts/sync-sub-agents.test.js): 15 unit tests covering row parsing (backtick stripping, required normalization, edge cases), table parsing (header detection, alignment row skipping, table boundary detection, header disambiguation), and record building (sorting, description preservation).Generated catalog (
catalog/sub-agents.json): 16 frontmatter fields with metadata (name, required boolean, description). Fields include:name,description,tools,disallowedTools,model,permissionMode,maxTurns,skills,mcpServers,hooks,memory,background,effort,isolation,color,initialPrompt.Rust integration (
src-tauri/src/catalog.rs): Embeddedsub-agents.jsonviainclude_str!and exposed throughread_catalogassub_agents(snake_case on wire). Added tests to verify catalog parsing and presence of required anchor fields (nameanddescription).Build and test infrastructure: Added
npm run sync:sub-agentsscript, integrated into CI workflow (catalog-drift.yml), and wired into test setup (src/test-setup.ts).Documentation: Updated
spec/catalog-sync.mdwith implementation details andspec/roadmap.mdto mark sub-agents frontmatter pass as shipped.Implementation Details
Header disambiguation: The page contains multiple 3-column tables; the script identifies the frontmatter table by exact header signature to avoid confusion with the "Other" built-in subagents tab (
| Agent | Model | When Claude uses it |).Defensive parsing: Handles edge cases like stray pipes in descriptions by re-joining cells, preserves markdown links and inline code in descriptions verbatim, and validates that name and description are non-empty.
Idempotence: Records are sorted by name; re-running on unchanged upstream produces only a
fetchedAttimestamp diff.No UI consumer yet: The catalog is wired through
read_catalogbut no UI component consumes it yet, parallel to the env-vars and hooks catalogs.https://claude.ai/code/session_01XA9PUa9VD2ZNVJKHjD7TF8