Question : How to avoid duplicated AI primitives when those are present in Git repo and install in dev local computer

[cgameiro-topcon]

What I'm trying to do

I distribute AI primitives (agents, skills, guardrails, standards) through APM. The same primitives live in their canonical Git repository and get installed onto individual developer machines when a developer runs apm install -g .

The problem

I end up with what looks like two copies of the same primitive — one in the Git source of truth, one materialized locally. When both are present, it's unclear how the user should is supposed to treat them.

Questions

What's the recommended pattern to avoid the duplication in the first place ?

[github-actions]

Triage decision

accept

Proposed labels

theme/portability
area/package-authoring
area/docs-site
type/docs
status/accepted
status/triaged

Milestone

null

No open milestones were detectable at triage time. This is a documentation gap; maintainer may target the next docs update cycle.

Suggested next action

Add a package-authoring guide page to docs/src/content/docs/ explaining the source-repo vs materialized .apm/ copy model and the recommended workflow for primitive authors who are also consumers of their own packages.

Suggested issue comment

Hello @cgameiro-topcon, and welcome to APM! This is a great question that reflects a real workflow gap in our documentation.

The short answer: the two copies are intentional by design, but we agree that this needs a clear guide page. Here is the recommended pattern:

You are the package author. Your canonical primitives live in the Git repository (the source of truth). When you run apm install -g <package>, APM materializes a copy into the local .apm/ directory -- this is the consumer's view of the package. As the author, you normally work directly in the Git repository source and do not apm install your own package into the same repo.

The recommended pattern for a split setup (source repo and a separate consumer project that depends on it):

1. Develop in the source Git repository.
2. In the consumer project, declare a git: dependency pointing to the source repo with the appropriate ref:.
3. Run apm install in the consumer project to materialize the .apm/ copy.
4. When you update the source repo, bump the ref: and re-run apm install in the consumer project.

If you want a dev-mode workflow (edit the source, see changes immediately in the consumer project without re-installing), that is a feature gap we do not yet cover -- a --link or dev-install mode analogous to npm link. If that is the workflow you need, please let us know and we can track it as a separate feature request.

We will add a guide page in docs/src/content/docs/ covering this pattern so future users find the answer directly.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

This is a package-authoring workflow confusion issue. The user has primitives in a canonical Git repository and wants to avoid duplication when they also consume those primitives locally. The "two copies" confusion is a known mental model gap for package authors in any package manager (similar to npm link or pip install -e . gaps). The answer involves explaining the intended workflow model (source repo vs materialized copy) and pointing to the git dependency + ref workflow. A --link / dev-install mode is the feature gap that would fully resolve the dev loop; that can be a follow-up feature request.

Supply Chain Security Expert -- Risk-Surface Reviewer

No risk-surface implication. This is a documentation and workflow question with no signing, lockfile, MCP config, or auth surface. No theme/security or theme/governance label required.

OSS Growth Hacker -- Contributor-Tone Reviewer

Activated: cgameiro-topcon is an external contributor (author_association: NONE) who is actively distributing AI primitives through APM -- exactly the target user persona for the package-authoring surface. The reply should be warm and welcoming, give a concrete and actionable answer, and explicitly invite a follow-up feature request for the dev-mode workflow if that is what they need. Do not assume they know the npm/cargo mental model; spell out the source-of-truth vs materialized copy distinction clearly.

Python Architect -- Architecture Reviewer

Not activated -- this is a documentation question, not an architecture issue. No cross-module or design impact.

Doc Writer -- Documentation Reviewer

Activated: clear docs gap. The package-authoring workflow (source repo, git dependency, ref-based install, and the eventual dev-mode gap) needs a dedicated guide page in docs/src/content/docs/. The suggested comment wording is grounded in the APM vocabulary (git dependency, ref:, apm install). The reply correctly names the missing feature (dev-install / --link mode) and invites a follow-up rather than closing the door.

APM CEO -- Triage Arbiter

This is a documentation gap on the package-authoring surface, which is a core APM value proposition. Triaging as type/docs + status/accepted is correct. The answer to the question is straightforward; the guide page is the concrete deliverable. If the user follows up with a dev-mode feature request, that would be a separate type/feature issue. Accept and prioritize as a docs item.

{
  "decision": "accept",
  "decision_detail": "",
  "theme": "theme/portability",
  "areas": ["area/package-authoring", "area/docs-site"],
  "type": "type/docs",
  "status": "status/accepted",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Add a package-authoring guide page explaining the source-repo vs materialized .apm/ copy model and the recommended workflow for primitive authors.",
  "comment_markdown": "See above."
}

---

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 · 150.3 AIC · ⌖ 7.64 AIC · ⊞ 9.2K · ◷