[FEATURE] Support Local Directory Deployment via local-dir / runtime Target for Agent-to-Agent Dependency Management

[tansm]

Problem Statement / Background

Currently, APM (Agent Package Manager) is primarily designed with a "Developer Tooling" mindset. The manifest (apm.yml) defines dependencies (prompts, skills, MCP servers), and adapters (like claude.py, cursor.py) distribute these assets into the user's global configuration directories or local IDE hidden folders (e.g., .claude/). In this paradigm, the consumer of the APM package is always an AI developer tool or IDE extension.

However, when developers are building an Enterprise AI Agent System or Agent Harness (e.g., server-side workflows), they often face a "Shared Library" problem. They want to decouple and reuse standard corporate skills or third-party tools maintained by other teams.

Currently, to bundle these shared skills into the runtime package of the Agent itself, developers have to manually copy files or clone git submodules into their project's skills/ or tools/ directory, which breaks the very dependency management value that APM provides.

Proposed Solution

We propose introducing a runtime (or local-path) deployment target in apm.yml.

This switches the consumer of the APM package from Dev Tooling to Application Runtime Assets. When running apm install, APM should be able to resolve these shared skills and copy/symlink them directly into a specified directory inside the current active project codebase, so they can be bundled and distributed together with the custom Agent application.

Detailed Design / Usage Example

1. Manifest Specification (apm.yml)

We can extend the targets schema to accept a local directory mapping, or introduce a dedicated runtime block:

name: core-enterprise-agent
version: 1.0.0
description: "An enterprise ERP agent harness"

# Define dependencies managed by separate teams or external repos
dependencies:
  apm:
    - [github.com/my-org/shared-erp-skills@v1.4.2](https://github.com/my-org/shared-erp-skills@v1.4.2)
    - [github.com/my-org/privacy-masking-tool@v0.9.0](https://github.com/my-org/privacy-masking-tool@v0.9.0)

# Proposed Enhancement: Target the codebase itself as the consumer
targets:
  - type: runtime
    output_dir: "./src/app/runtime_skills"
    clean: true # Optional: clean the target directory before copying

2. Adapter Layer Evolution

Similar to how src/apm_cli/adapters/client/claude.py maps files to .claude/tasks/, a new runtime or local adapter can be introduced.

• Behavior: Instead of searching for globally installed desktop apps or IDE states, this adapter reads the output_dir (resolved relative to the apm.yml root) and unpacks the target .json / .py / .ts skill definitions directly into that folder.
• Benefit: The codebase treats these files as read-only managed assets, making it fully compatible with local debugging, docker bundling, and CI/CD pipelines.

Alternative Approaches Considered

• Git Submodules: Hard to manage version constraints at scale and doesn't leverage APM’s capability to lock and validate policies (apm-policy.yml).
• Custom Build Scripts: Developers could write apm pack + custom bash scripts to move files, but standardizing this inside APM prevents everyone from reinventing the wheel for agent-to-agent dependency resolution.

Additional Context

This feature would bridge the gap between "AI-assisted coding" and "AI Agent Application Development", positioning APM as the definitive package manager not just for developers' local machines, but for autonomous production agent systems.

[github-actions]

Triage Panel Verdict

Decision: NEEDS DESIGN

Issue: [FEATURE] Support Local Directory Deployment via local-dir / runtime Target for Agent-to-Agent Dependency Management

---

Panel synthesis

DevX UX Expert
The user need is real: teams building server-side agent harnesses want to manage skill and tool file dependencies with a proper package manager instead of git submodules or hand-crafted scripts. However, the proposed design has several open UX questions:

• How does drift detection work for a runtime target versus managed AI tooling config?
• What is the user mental model when clean: true wipes a directory -- is this recoverable?
• Does this belong in apm.yml as a targets: entry, or as a separate deployment command?
• How does apm audit report state for this target type?

The concept is valid but the user journey needs a design brief before implementation.

Supply Chain Security Expert
CONCERN. The output_dir parameter allows APM to copy package artifacts to arbitrary project directories. With clean: true, APM would first delete everything in that directory, then replace it with package contents. Key risks:

1. A compromised APM package could write executable files (.py, .ts, .sh) directly into project source directories if output_dir is not restricted.
2. There is no mention of an allowlist of deployable file extensions or a blocklist of prohibited destination paths (e.g., prohibiting src/, bin/, or directories containing executables).
3. clean: true on an incorrectly typed output_dir could silently delete unrelated project files.

These are design gaps that must be resolved before implementation. The feature is not inherently unsafe, but requires explicit security constraints as part of the accepted design.

APM CEO (Strategic Arbiter)
The problem space is real and aligns with APM's long-term direction -- enterprise teams building production agent systems need dependency management for agent artifacts, not just for local developer tooling. However, this is a meaningful scope expansion: APM currently manages "configure AI tooling context"; this proposes managing "application runtime assets." That expansion needs deliberate positioning and a clear scope boundary so APM's mental model stays coherent. Marking status/needs-design is the right gate. The concept merits a design brief that addresses security constraints, scope boundary, and how this target type composes with existing APM audit and drift-detection flows.

Python Architect (conditional)
The proposed adapter layer (analogous to claude.py, cursor.py) is architecturally recognizable. However, existing adapters target fixed, known paths. A variable output_dir requires more general file materialization logic with path validation, symlink-vs-copy choice, and conflict handling. These are solvable, but the design needs to specify them before implementation starts.

---

Proposed label set

Dimension	Label
Type	type/feature (keep existing)
Theme	theme/portability
Area	area/distribution
Priority	priority/low
Status	status/needs-design, status/triaged

Suggested next action

Author and maintainers to collaborate on a design brief (as a follow-up comment or linked document) that addresses:

1. Security scope: allowed file extensions and prohibited destination paths for a runtime target
2. Semantics of clean: true and how drift detection works for this target type
3. How apm audit --ci reports state for runtime targets
4. Scope boundary: what kinds of files and packages are in-scope for a runtime target?

Once a design brief is accepted, this issue can be promoted to status/accepted for implementation.

---

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 · sonnet46 1.8M · ◷