[FEATURE] Support package namespaces

[natoverse]

Is your feature request related to a problem? Please describe.
As an example, I have a project that looks something like this

• project, with skills
• apm dependency 1
• apm dependency 2
  • transitive dependency 1
  • transitive dependency 2

After apm install, the skills folder flattens everything, e.g.,

• project skills
• apm dependency 1
• apm dependency 2
• transitive dependecy 1
• transitive dependency 2

This is of course not APM's fault, it's the design of the .github folder. However, it leads to two distinct problems:

1. It quickly becomes very difficult to understand where various skills came from, particularly differentiating project skills from installed dep skills
2. Whilst developing a project, it's easy for the agent to update the installed skills because they are part of the "codebase" rather than a gitignored dep

Describe the solution you'd like
Using namespaces could at least help solve problem #1. If the package manifest defined a namespace that was applied (presumably sometihng like namespace.skillname/SKILL.md) then it would be clear where each skill originated. This would also allow for easier copilot instructions indicating not to edit non-project skill prompts unless expressly asked to do so.

A secondary/related solution could be to have apm install add the individual dep skill folders to .gitignore along with apm_modules. This may not be desirable in all cases though, so would likely need to be optional.

Describe alternatives you've considered
Hand-adding a namespace to my skill names is how I'm handling multiple skill repositories in our org, but that doesn't work with third-party skills.

Additional context
Add any other context or screenshots about the feature request here.

[shreejaykurhade]

I would love to work on this.
Will submit a small implementation.
/assign

[shreejaykurhade]

@natoverse please take a look. guide me how do go from here

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/package-authoring
area/multi-target
type/feature
status/needs-design
status/triaged

Milestone

null

Suggested next action

Design the namespace scheme: separator character, backward compatibility with existing flat skill references, how agent runtimes (Copilot, Claude Code, Codex) discover namespaced skills by name, and the lockfile schema change required.

Suggested issue comment

Thanks for the detailed write-up -- you have identified two distinct problems that are easy to conflate:

1. **Provenance opacity**: it is hard to tell which skill came from which package in a flat directory.
2. **Developer mutability**: agents can accidentally overwrite installed skills because they share the same flat directory as project skills.

Both are real and acknowledged. However, namespacing is a non-trivial design change because it touches how agent runtimes *discover* skills by name. Copilot, Claude Code, and Codex all use a flat skills/ directory today -- a namespace separator (e.g., `pkg-a/skill-name`) would change how agents reference skills, which is a breaking change for existing packages.

Before code lands, the design needs to address:

- **Namespace separator and path format**: must be valid across all target runtimes and file systems.
- **Backward compatibility**: existing packages use flat names; how do they opt in or out?
- **lockfile schema**: how is namespace recorded as part of a skill identity in apm.lock.yaml?
- **Protection mechanism**: would namespace directories be write-protected from agents, or is a separate mechanism (e.g., a `.apm-managed` marker, read-only file bits) needed?
- **Path security**: namespace strings must be validated through `validate_path_segments` to prevent traversal.

If you would like to contribute, the best next step is a design comment here proposing answers to those questions. We can move to status/accepted once the design is agreed.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

Both identified problems (provenance confusion and accidental overwrites) are real pain points that emerge at scale. The flat design is deliberate -- it matches runtime discovery -- but it does hurt in larger monorepos with many transitive dependencies. The namespace approach is the right direction but the design has multiple viable solutions: namespacing, protected directories, manifest-based tracking. Any implementation must preserve how agents reference skills by name in their prompts.

Supply Chain Security Expert -- Risk-Surface Reviewer

Namespace separators in deployment paths are a potential path traversal vector if not validated at parse time. The existing validate_path_segments in src/apm_cli/utils/path_security.py must be extended to handle namespace components (including backslash normalization on Windows) before any PR lands. Not a blocker for the design phase, but the security review checklist for the implementing PR must explicitly cover namespace string validation.

OSS Growth Hacker -- Contributor-Tone Reviewer

Activated. natoverse is NONE association. The issue is thoughtful and demonstrates real project use at scale. The reply should be warm, validate both problems identified (not just say "it is complicated"), and clearly explain why this is needs-design rather than a quick fix -- so the contributor understands the tradeoffs, not just the outcome.

Python Architect -- Architecture Reviewer

Activated. Namespacing requires changes to: skill deployment in BaseIntegrator and per-target integrators, collision detection logic, the lockfile schema (namespace as part of skill identity), and potentially how target-specific integrators resolve skill references. The cross-runtime discovery impact is the hardest part: if namespace directories are transparent to the runtime, they degrade to the current flat experience; if they are opaque, agents need to know the namespace to reference the skill. Recommend status/needs-design with a required design doc before any PR is accepted.

Doc Writer -- Documentation Reviewer

Activated. Any namespacing feature will need documentation: how to reference namespaced skills in agent prompts, lockfile format changes, upgrade guide for existing packages. area/multi-target added as a secondary label because the design must account for all supported runtimes. Doc work is premature until the design is settled.

APM CEO -- Triage Arbiter

Valid direction that addresses a real user pain point in larger repos. The flat design was intentional but the tradeoffs are emerging as usage scales. Pushing to needs-design because the runtime discovery impact is a potential breaking-change surface that must be designed carefully. The protection mechanism (preventing agent overwrites of installed skills) could potentially be addressed independently as a smaller, non-breaking improvement while the namespacing design matures. No milestone until design is agreed.

{
  "decision": "needs-design",
  "decision_detail": "Namespace separator, backward compatibility with flat references, runtime discovery impact across all targets, lockfile schema change, and path security validation must be designed before implementation.",
  "theme": "theme/portability",
  "areas": ["area/package-authoring", "area/multi-target"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Post a design comment proposing: namespace separator format, backward compatibility path, lockfile schema change, and how agent runtimes discover namespaced skills.",
  "comment_markdown": "Both provenance opacity and developer mutability are real. Namespacing is the right direction but needs design before code: separator format, backward compat, runtime discovery impact, and lockfile schema change must be agreed first."
}

---

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 · ● 3.3M · ◷