[aditeyabaral]

Why

GitHub Copilot, on GitHub.com and in VS Code, lists custom agents only from real
.github/agents/<name>.agent.md files on a repo's default branch. GitHub does not read files
through a submodule, so auth's ten roles in this repo never show up in Copilot's agent picker.

What

• .github/agents/ becomes the one tool-specific path in project repos (README: "Roles as
  Copilot custom agents"). A project keeps a thin wrapper per role there: the role's frontmatter,
  copied verbatim, and a short body telling the agent to read the role file here, which stays the
  only definition. The wrappers are generated and drift-checked in the project repo, so this
  repo still has no scripts and nothing generated.

• tools on the four read-only roles (planner, reviewer, security-auditor,
  incident-investigator): ["read", "search", "execute", "github/*"], using Copilot's aliases.
  Their custom agents get no edit tools; the shell stays, because they run tests, git diff and
  curl /metrics. The README says plainly that this is not a sandbox. Other tools ignore the field.

• auth docs: AGENTS.md (the "never edit" rule, the repo map and the roles section),
  autonomous-workflow ("Using roles"), ci-cd (the pre-commit row, and a new copilot-setup-steps.yml
  row), and fix-ci (a row for a failing sync-agents check, which is what a Dependabot bump that
  changes a role will hit).

• The fork-only policy, applied to the new moving parts:

  • A Dependabot bump that changes a role's frontmatter fails sync-agents, and nobody but a
    maintainer can push to Dependabot's branch. ci-cd.md ("Dependabot submodule bumps") gives
    both routes (a maintainer pushes the regenerated agents, or anyone supersedes the PR from a
    fork). fix-ci and the README point at it, and the README tells skills contributors when to
    expect it.
  • Copilot's cloud agent opens its PR from a branch in the repo it runs in, which source.yaml
    rejects in pesu-dev/auth. autonomous-workflow.md says to run it on a fork, and that its
    default firewall blocks PESU Academy, so its test runs are partial. AGENTS.md points there.

• Reference docs: architecture, conventions (mdformat-frontmatter), testing, security (no
  TEST_* in the copilot environment, plus a security-review check for it), update-dependencies
  (copilot-setup-steps.yml pins Python too), navigate-codebase, and common/AGENTS.md
  (generated files are not hand-edited either).

• Profile logging is deliberate: pesu-auth logs the scraped profile and the auth result at INFO
  so a login can be traced. security.md, conventions.md, the security-review checklist and
  known-issues.md called that a defect; they now describe it as a design choice, and AGENTS.md's
  logging rule says so. The CSRF-token entry stays in known-issues.

Follow-up

The pesu-dev/auth side is ready locally: scripts/sync_agents.py with tests, the ten wrappers, the
sync-agents hook, submodules: true on the pre-commit checkout, and copilot-setup-steps.yml. It
was verified against this branch: pre-commit is green, including the full test suite with live
tests, and editing a role's description makes --check fail. I'll open it once this merges, pinned
to the merge commit.

Checks

uvx pre-commit run --all-files passes locally, and mdformat keeps the new tools lines intact.

🤖 Generated with Claude Code