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

[danielmeppiel]

Thanks for the detailed proposal @sergio-sisternes-epam. We've been thinking about this deeply and will take a different architectural direction — one that treats APM's primitives as a language rather than config.

The core insight: .agent.md files are already class definitions — YAML frontmatter = attributes, markdown body = behavior. Overrides should live in the language, not the manifest. In the same way that npm customization happens through import + extends in code (not package.json), APM customization should happen through extends: in .agent.md files, not apm.yml.

An option is to add an extends: field in agent frontmatter for language-native inheritance. Below is just as an example and implementation end result will likely differ. This is to invite discussion.

# .apm/agents/developer.agent.md (local override)
---
extends: microsoft/developer-agents:developer
tools:
  inherit: true
  add: ['my-new-mcp/*', custom-tool]
  remove: [browser]
model: o4-mini
---
Also consider our internal API standards when making decisions.

apm install resolves the inheritance chain and deploys the fully-merged result. The engine (Copilot/Claude) never sees extends: — just the resolved agent, like a bundler strips import statements.

This would add:

• No manifest clutter — apm.yml stays clean (deps + metadata). All customization in .agent.md files.
• No separate apm build — apm install already IS the build. Inheritance resolution is added to the existing deploy step.
• Familiar pattern — same extends model as JS classes, Python inheritance, CSS cascade.
• Explicit per-agent — one override file per agent. Global mechanisms (apply to all) will come as Phase 2.

---

However that puts APM in language definition territory, where other players are still evolving their markdown frontmatters very quickly. I'd rather park this for some time and see how it evolves rather than having APM move out from package management into language definition too early.

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/package-authoring
area/docs-site
type/feature
status/needs-design

Milestone

null

Suggested next action

Open a design doc defining: (a) the overrides schema in the apm.yml manifest model, (b) the extension point in AgentIntegrator / BaseIntegrator for post-deploy transforms, and (c) how the overlay-file future direction relates to this schema without creating redundant surfaces.

Suggested issue comment

This is a real pain point -- customizations that survive `apm install --update` are a genuine gap, and the npm `overrides` / Helm `values.yaml` / Kustomize mental model is exactly the right analogy.

The direction is sound. Before code lands, we need a design doc to settle three questions:

1. **Schema structure**: how does the `overrides` block fit into the existing `apm.yml` manifest model? What validation rules apply?
2. **Extension point**: `AgentIntegrator` (and potentially `BaseIntegrator`) needs a post-deploy transform hook. What is the minimal interface that does not break other integrators?
3. **Overlay-file future**: the Kustomize-style overlay files you mention in "Future Enhancement" should be designed now so the initial `overrides` schema does not close off that evolution path.

Once those three questions have written answers linked here, the implementation is straightforward. If you want to drive the design doc, that would be a great next contribution.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The user task is clear: customize agent tool lists without forking the package or maintaining manual patches. The overrides API surface follows familiar patterns (npm, Helm, Kustomize) and the append/remove semantics are self-explanatory. The "overrides are re-applied on every install" guarantee is the right ergonomic contract. No UX concerns with the proposal itself; the risk is in implementation complexity leaking into the user surface.

Supply Chain Security Expert -- Risk-Surface Reviewer

Tool list overrides in agent frontmatter are capability declarations for the AI agent, not executable code in the traditional sense. No supply chain risk in the npm/PyPI sense. The schema validator for overrides should reject unknown fields and non-string tool names to prevent injection of unexpected values. No theme/security required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- author is an established collaborator filing a design-level feature request with no tone-tuning needed.

Python Architect -- Architecture Reviewer

This requires: (1) extending the manifest model (apm.yml parser/validator) with a new overrides schema, (2) a post-deploy transform step in AgentIntegrator that reads overrides and patches YAML frontmatter, (3) re-application on every install. The existing BaseIntegrator has no post-deploy hook pattern; adding one cleanly requires design. The frontmatter patching must handle edge cases (tool absent on remove, duplicate on append). The overlay-file direction mentioned in the issue needs to be scoped so the initial schema does not foreclose it. status/needs-design is the right call.

Doc Writer -- Documentation Reviewer

New user-facing schema block in apm.yml requires docs: a reference page or section on the overrides key, with examples of global and per-agent tool patching. area/docs-site secondary label is warranted. The implementation PR must include docs or it is incomplete by APM's Rule 1.

APM CEO -- Triage Arbiter

Sound direction, genuine user need, right mental model. The Python Architect correctly identifies that a post-deploy transform hook in BaseIntegrator is a non-trivial extension point that warrants a design doc before code lands. Setting status/needs-design and assigning no milestone keeps this off the sprint until design is complete. The "overlay files" future direction is explicitly in scope for the design doc -- it should not be a surprise refactor later.

{
  "decision": "needs-design",
  "decision_detail": "Requires design doc covering: overrides schema in apm.yml model, post-deploy transform extension point in BaseIntegrator/AgentIntegrator, and overlay-file future direction compatibility.",
  "theme": "theme/portability",
  "areas": ["area/package-authoring", "area/docs-site"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Open a design doc covering the overrides schema, the BaseIntegrator post-deploy transform extension point, and overlay-file future direction compatibility.",
  "comment_markdown": "This is a real pain point -- customizations that survive `apm install --update` are a genuine gap, and the npm `overrides` / Helm `values.yaml` / Kustomize mental model is exactly the right analogy.\n\nThe direction is sound. Before code lands, we need a design doc to settle three questions:\n\n1. **Schema structure**: how does the `overrides` block fit into the existing `apm.yml` manifest model? What validation rules apply?\n2. **Extension point**: `AgentIntegrator` (and potentially `BaseIntegrator`) needs a post-deploy transform hook. What is the minimal interface that does not break other integrators?\n3. **Overlay-file future**: the Kustomize-style overlay files you mention in \"Future Enhancement\" should be designed now so the initial `overrides` schema does not close off that evolution path.\n\nOnce those three questions have written answers linked here, the implementation is straightforward. If you want to drive the design doc, that would be a great next contribution."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 1.9M · ◷