Multi-agent repo setup

Research Question

What are the best practices for setting up a GitHub repository so that it can be worked on effectively by multiple Artificial Intelligence (AI) agents, specifically: (1) Claude via the iOS Claude app, (2) Claude via GitHub Issues assigned to Claude, (3) Copilot via Copilot Spaces, and (4) Copilot via GitHub Issues assigned to the Copilot coding agent, with consistent instruction loading, environment setup, and quality outcomes across all four surfaces?

Findings

Executive Summary

The repository currently serves the Copilot coding agent only partially: .github/copilot-instructions.md loads correctly, but the agent starts without Python dependencies and without the .github/skills/ submodule because no copilot-setup-steps.yml exists. Three additions cover all currently-reachable surfaces: copilot-setup-steps.yml (fixes the Copilot coding agent environment), CLAUDE.md at root (enables Claude Code on iOS and pre-positions for Claude Code GitHub Actions when credentials are added), and AGENTS.md at root (restores cross-vendor compatibility). The Claude-via-GitHub-Issues surface is currently blocked by missing credentials (ANTHROPIC_API_KEY and a GitHub App) and cannot be enabled within the current constraint of no new credentials. Copilot Spaces can launch coding agent tasks that respect repo configuration; Claude Code on iOS is a full coding agent that can discover and use instruction files during execution.

Key Findings

1. The Copilot coding agent reads both .github/copilot-instructions.md and AGENTS.md when both are present at the repository root; both files are combined additively, giving complete instruction coverage from either file independently.
2. The absence of .github/workflows/copilot-setup-steps.yml means the Copilot coding agent starts in a bare Ubuntu environment without Python dependencies, without the virtual environment, and without the .github/skills/ submodule, this is a silent failure that prevents the agent from running make check or make test as required by the existing instructions.
3. Claude Code GitHub Actions (anthropics/claude-code-action) reads CLAUDE.md via Claude Code's normal file-discovery walk; it does not read .github/copilot-instructions.md, meaning the current single-file approach leaves Claude Code without any project instructions.
4. The Claude-via-GitHub-Issues surface requires ANTHROPIC_API_KEY (or equivalent Bedrock/Vertex credentials) and a GitHub App (APP_ID, APP_PRIVATE_KEY); none are in this repo's credential table, so this surface is blocked under the current no-new-credentials constraint.
5. Copilot Spaces can launch Copilot coding agent tasks that write code and create pull requests; Spaces itself is a Q&A tool that does not auto-read per-repo instruction files, but when it launches a coding agent task, that agent respects the repository's configuration files.
6. Claude Code on iOS is a full coding agent that can write code, create commits, and open pull requests in cloud-based sandboxed environments; it does not auto-load instruction files at session start but can discover and use CLAUDE.md and other files during execution.
7. AGENTS.md is a Linux Foundation-stewarded open standard supported by over 20 tools (including GitHub Copilot, OpenAI Codex, Cursor, and Claude Code) and present in over 60,000 repositories; adding a thin pointer file at the root costs nothing and restores coverage for all AGENTS.md-native agents.
8. ADR-0006's consolidation to .github/copilot-instructions.md was correct for Copilot-only usage; adding AGENTS.md (as a pointer) and CLAUDE.md extends coverage to Claude Code surfaces without contradicting ADR-0006's intent of a single canonical instruction file.
9. Submodule checkout inside copilot-setup-steps.yml should use COPILOT_GITHUB_TOKEN rather than the default GITHUB_TOKEN because the Copilot coding agent's auto-provided token is scoped to the current repository and may not have read access to the private davidamitchell/Skills submodule.

Assumptions

• Assumption: The iOS Claude app's "code feature" refers to Claude Code running on iOS, which launched in October 2025 as a full coding agent. Justification: Multiple sources confirm Anthropic expanded Claude Code to iOS and web in October 2025 with full coding capabilities. The inaccessible support article (10166833) likely describes this feature, while article 10167454 describes the broader GitHub connector that provides repository access.
• Assumption: The davidamitchell/Skills submodule requires COPILOT_GITHUB_TOKEN rather than the default GITHUB_TOKEN for checkout by the Copilot coding agent. Justification: GitHub Actions GITHUB_TOKEN is auto-scoped to the triggering repository; cross-repo read access for private repositories requires a PAT with the appropriate scope.

Analysis

The four surfaces split into different categories. Code-writing agents: Copilot coding agent (auto-loads .github/copilot-instructions.md and AGENTS.md), Claude Code on iOS (can discover CLAUDE.md during execution), and Claude Code GitHub Actions (reads CLAUDE.md). Context/launch tools: Copilot Spaces (can launch Copilot coding agents). Each code-writing agent has different instruction-loading behavior; the minimum viable configuration must accommodate all patterns.

For code-writing agents, the priority order is: (1) fix the environment gap (copilot-setup-steps.yml) because a misconfigured environment causes test failures even with perfect instructions; (2) enable Claude Code surfaces (CLAUDE.md) for iOS sessions and future GitHub Actions; (3) restore cross-vendor compatibility (AGENTS.md). The credential constraint is a hard blocker on Claude Code GitHub Actions, it cannot be resolved by file additions alone.

The "thin pointer" pattern for AGENTS.md (pointing to .github/copilot-instructions.md) and CLAUDE.md (importing or summarising the same instructions) preserves ADR-0006's intent of a single canonical instruction source while allowing each agent's native discovery mechanism to locate relevant content. Full duplication across files risks drift; a pointer or import pattern avoids it.

Risks, Gaps, and Uncertainties

• The Skills submodule checkout in copilot-setup-steps.yml requires testing with COPILOT_GITHUB_TOKEN to confirm the token has cross-repo read access. If it does not, the Copilot coding agent will silently work without skills files.
• The AGENTS.md cross-compatibility claim for Claude Code is sourced from a community site (agentsmd.online). The reliable instruction mechanism for Claude Code is CLAUDE.md; AGENTS.md should be considered a bonus for Claude Code, not a primary path.
• The CLAUDE.md content strategy (pointer vs. summary vs. full copy) is unresolved. A full copy of .github/copilot-instructions.md into CLAUDE.md gives Claude Code the highest context fidelity but introduces a drift risk. A minimal pointer with a <!-- See .github/copilot-instructions.md --> comment is DRY but may not be sufficient for Claude Code's context needs in automated workflows.

Open Questions

• Can COPILOT_GITHUB_TOKEN be used in copilot-setup-steps.yml for submodule checkout? If yes, submodule init is straightforward. If no, the skills submodule remains inaccessible to the Copilot coding agent. This warrants a separate implementation test.
• Is there a Claude GitHub App available on the GitHub Marketplace that would simplify the GitHub Issues → Claude surface (analogous to Copilot's native assignment) without requiring the full anthropics/claude-code-action workflow and credential setup?
• What should CLAUDE.md contain? A full mirror of .github/copilot-instructions.md maximises Claude Code context but creates a maintenance burden. A structured summary (key rules only) may be better for automated CI workflows where token budget matters.

sources

Starting points, papers, articles, videos, repos, docs.

• [x] GitHub Copilot coding agent documentation — : entry point for coding agent behaviour and configuration
• [x] GitHub Copilot custom instructions (.github/copilot-instructions.md) — : what the file covers and which surfaces load it
• [x] copilot-setup-steps documentation — : schema and when it runs
• [x] Copilot Spaces documentation — : what Spaces are and how they use repo config
• [x] AGENTS.md specification / agentsmd.online — : cross-vendor standard for agent instruction files
• [x] Anthropic Claude iOS app GitHub integration — : how Claude iOS interacts with repositories via connector
• [x] Claude Code GitHub Actions documentation — : how GitHub Issues can be assigned to Claude via anthropics/claude-code-action
• [x] Claude Code memory / CLAUDE.md documentation — : what files Claude Code auto-loads
• [x] docs-adr/0006-standardise-agent-instructions.md, local ADR documenting the decision to delete AGENTS.md
• [x] Research/completed/2026-03-08-ai-coding-harnesses-agent-philosophy.md, prior research on AGENTS.md as cross-vendor standard
• [x] Research/completed/2026-03-22-using-awesome-copilot-across-repos.md, prior research noting AGENTS.md is read by GitHub web