Support tool overrides for installed agent packages

[sergio-sisternes-epam]

Problem

When consuming agent packages via apm install, the .agent.md files deployed to .github/agents/ include a tools: list in their YAML frontmatter. For example, the developer agent ships with:

tools: [vscode, execute, read, edit, search, web, browser, 'github/*', 'microsoft-learn/*', 'pylance-mcp-server/*', todo]

As users add new capabilities (e.g., additional MCP servers from other packages), they need to grant agents access to those tools. Today the only option is to manually edit the deployed .agent.md files — but running apm install --update overwrites those files with fresh copies from the package, discarding the customizations.

There is currently no mechanism to declare tool overrides that survive package updates.

Proposed Solution

Add an overrides section to the consumer's apm.yml that declares tool-level patches, applied by APM during install/update.

# apm.yml (consumer project)
overrides:
  tools:
    append: ['my-new-mcp/*']          # Injected into ALL agents
  agents:
    developer:
      tools:
        append: ['custom-tool']        # Added to developer only
        remove: ['browser']            # Removed from developer only
    tech-lead:
      tools:
        append: ['my-new-mcp/*']

Semantics:

• overrides.tools.append / overrides.tools.remove — applied to every deployed agent
• overrides.agents.<name>.tools.append / .remove — applied to a specific agent (by matching the name field in frontmatter)
• Per-agent overrides are applied after global overrides
• append adds tools not already present; remove strips tools that exist
• Overrides are re-applied on every apm install, so --update is safe

Where it runs: After AgentIntegrator copies the .agent.md file from apm_modules/ to .github/agents/, a post-deploy step reads the overrides section, patches the YAML frontmatter tools: list, and writes the final file.

Design Principles

• Packages own the base, consumers own the overrides — same pattern as npm overrides, Helm values.yaml, Kustomize patches
• Declarative & single source of truth — all customization lives in apm.yml, not scattered in deployed files
• Start simple, evolve later — append/remove on tool lists covers the primary use case; richer override capabilities (model, description, body) can be added incrementally

Future Enhancement: Overlay Files

A natural evolution of this feature would be overlay files (Kustomize-style). Users would place partial override files in a convention directory:

.apm/overrides/agents/developer.agent.md

Containing only the frontmatter fields to merge:

---
tools: [vscode, execute, read, edit, search, web, 'github/*', 'my-new-mcp/*']
---

During install, APM would deep-merge the overlay on top of the package version before deploying to .github/agents/. This would allow overriding any frontmatter field (tools, model, description) and potentially appending instructions to the agent body. This is out of scope for the initial implementation but the overrides schema should be designed with this evolution in mind.

Scope

• Add overrides schema to apm.yml manifest model
• Implement tool-list patching in AgentIntegrator post-deploy
• Validate override targets (warn if an agent name doesn't match any deployed agent)
• Update manifest-schema.md documentation
• Add tests for global overrides, per-agent overrides, and combined scenarios