Skip to content

Adopt shared .agents/roles/ agent-roles layout from adcp#4500 #728

Description

@bokelley

Summary

Adopt the single-source-of-truth .agents/roles/ agent-roles layout established in adcontextprotocol/adcp#4500, as adcp-client did in adcontextprotocol/adcp-client#1735.

Context

Today this repo has no .agents/roles/. Claude Code agents are either absent or hand-maintained at .claude/agents/. The adcp-client adoption PR (#1735) is the reference implementation — copy that pattern.

What changes

  1. Add .agents/roles/ with the 28 source role files copied verbatim from adcontextprotocol/adcp:.agents/roles/
  2. Add scripts/import-claude-agents.mjs from the same source — generates .claude/agents/*.md (verbatim copies) and .codex/agents/*.toml (TOML form for Codex) from the source roles
  3. Add .github/workflows/validate-agent-roles-sync.yml — fails any PR where .claude/agents/ has drifted from .agents/roles/
  4. Add .claude/agents/README.md with the "generated — don't edit" warning
  5. Add .codex/ to .gitignore (Codex output is regenerated locally per contributor)
  6. Run the script once to regenerate .claude/agents/

Repo-specific note

This is a Python repo. The import-claude-agents.mjs script needs Node to run (just node ≥18 — no other deps). Two options:

  • Include the script (recommended): adds a one-line Node dependency for the validation workflow. CI runners have Node by default.
  • Skip the script and hand-maintain: simpler today but defeats the point of single source of truth. Phase 3 will introduce cross-repo sync from adcp, which would regenerate .claude/agents/ automatically — but Phase 3 doesn't exist yet.

Recommend including the script. If you disagree, comment why on this issue and a maintainer will decide.

Source files to copy

  • 28 files in adcontextprotocol/adcp:.agents/roles/*.md (10 short triage checkers + 9 -deep design advisors + 9 long-only specialty advisors)
  • adcontextprotocol/adcp:scripts/import-claude-agents.mjs
  • adcontextprotocol/adcp:.github/workflows/validate-agent-roles-sync.yml
  • adcontextprotocol/adcp:.claude/agents/README.md

Preserve

  • Any existing .claude/skills/ — repo-specific, don't touch
  • .agents/routines/, .agents/scripts/triage-local.sh if present — keep unchanged

🤖 Filed by Claude during Phase 2 of agent-roles-sync rollout (adcp → all 5 repos).

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions