[aditeyabaral]

📌 Description

Makes the ten agent roles (planner, implementer, reviewer, ...) available as GitHub Copilot custom agents, in the agent picker on GitHub.com and in VS Code.

Copilot lists custom agents only from real .github/agents/<name>.agent.md files on the default branch, and GitHub does not read files through the .agents/pesudev-skills submodule, so the roles were invisible to it. This adds a generated wrapper per role. Each wrapper holds the role's frontmatter, copied verbatim, and a short body telling the agent to read the role file. The role file in pesu-dev/skills stays the only definition.

• scripts/sync_agents.py (standard library only) generates .github/agents/ from .agents/pesudev-skills/auth/agents/. --check writes nothing and fails on missing, extra or stale wrappers. If the submodule isn't checked out, it fails with git submodule update --init instead of deleting every wrapper.
• .github/agents/*.agent.md: the ten generated wrappers. The four read-only roles carry tools: ["read", "search", "execute", "github/*"], so Copilot gives them no edit tools.
• .pre-commit-config.yaml:
  • a sync-agents hook with always_run: true, because a submodule bump changes no tracked file;
  • mdformat-frontmatter, without which mdformat rewrites the wrappers' frontmatter as Markdown and Copilot stops recognising them.
• .github/workflows/pre-commit.yaml: checkout with submodules: true, so CI can run the check.
• .github/workflows/copilot-setup-steps.yml (new): the environment Copilot's cloud agent starts in: the submodule, Python 3.14 and uv sync --all-groups. It has contents: read and no TEST_* secrets, because live tests share one PESU session.
• Submodule bumped to pesu-dev/skills 6862d1f, covering chore: use only provider-neutral paths in project repos skills#2 and feat: expose auth's roles as GitHub Copilot custom agents skills#3. That commit documents all of the above, adds the tools field, and records the profile logging as deliberate.
• CONTRIBUTING:
  • using the agents;
  • regenerating them after a submodule update;
  • running Copilot's cloud agent on your fork, because it opens its PR from a branch in the repo it runs in, which source.yaml rejects here.
• pyproject.toml: the ruff-exclude comment now says it's the Lint workflow that checks out without submodules. Version bumped to 4.11.0, and uv lock run.

ℹ️ Fixes / Related Issues
Related: pesu-dev/skills#3

🧱 Type of Change

• ✨ New feature – Adds functionality without breaking existing APIs
• 📝 Documentation update – README, docstrings, OpenAPI tags, etc.
• 🧪 Test suite change – Adds/updates unit, functional, or integration tests
• ⚙️ CI/CD pipeline update – Modifies GitHub Actions, pre-commit, or Docker build
• 🔧 Developer tooling – Scripts, benchmarks, local testing improvements

🧪 How Has This Been Tested?

• Unit Tests (tests/unit/): 12 new tests in tests/unit/test_sync_agents.py. They cover generation, idempotence, stale/extra wrappers being rewritten or removed, --check failing without writing, a missing submodule, malformed frontmatter, the CLI, and the committed .github/agents/ matching the real submodule.
• Functional Tests (tests/functional/)
• Integration Tests (tests/integration/)
• Manual Testing: changed a role's description in the submodule, and --check failed naming the stale wrapper. After a restore it passed.

⚙️ Test Configuration:

• OS: Linux
• Python: 3.14 via uv
• Docker build tested (not run: nothing here reaches the image)

Full uv run pre-commit run --all-files on this commit, with credentials, so the live tests ran: 288 passed, 0 deselected, 100.00% coverage. The generated files are unchanged by the hooks.

✅ Checklist

• My code follows the CONTRIBUTING.md guidelines
• I've performed a self-review of my changes
• I've added/updated necessary comments and docstrings
• I've updated relevant docs (README or endpoint docs)
• No new warnings introduced
• I've added tests to cover my changes
• All tests pass locally (scripts/run_tests.py)
• I've run linting and formatting (pre-commit run --all-files)
• Changes are backwards compatible (if applicable)

🛠️ Affected API Behaviour

No API behaviour changes.

🐳 DevOps & Config

• .github/workflows/*.yaml – CI/CD pipeline or deployment updates
• pyproject.toml / requirements.txt – Dependency version changes (version bump only)
• .pre-commit-config.yaml – Linting or formatting hook changes

🧠 Additional Notes (if applicable)

• Supersedes Dependabot's bump to 6862d1f. A plain bump would fail sync-agents, because .github/agents/ doesn't exist without this PR. If Dependabot opens that PR, it can be closed; Dependabot should also close it once dev has the commit.
• Later role changes: a Dependabot bump that changes a role's frontmatter will fail sync-agents. Either a maintainer pushes the regenerated agents to its branch, or someone supersedes it from a fork. See "Dependabot submodule bumps" in .agents/pesudev-skills/auth/docs/ci-cd.md.
• Not verified yet:
  • the agents appearing in Copilot's picker on GitHub.com, which only reads the default branch, so it can only be checked after merge;
  • copilot-setup-steps running green as Copilot's own setup job;
  • Copilot's default firewall blocking pesuacademy.com, which the docs assume. The cloud agent's test runs are documented as partial for that reason.

🤖 Generated with Claude Code