Skip to content

feat(install): -g should compile instructions into user-scope root context file #1485

@vlsi

Description

@vlsi

Summary

apm install -g <pkg> deploys per-target primitives into user-scope directories (~/.claude/skills/, ...) and writes metadata under ~/.apm/. For instructions this is not enough: the harness loads them only through a root context file (CLAUDE.md, AGENTS.md, GEMINI.md) that apm compile generates, and apm compile has no user-scope mode.

Net effect: apm install -g silently installs instructions that no harness ever picks up.

Repro

Real-world example: Netcracker/qubership-ai-packages/agent-packages/apm-authoring ships both .apm/skills/ and .apm/instructions/.

apm install -g Netcracker/qubership-ai-packages --target claude
# skills land under ~/.claude/skills/                         -> picked up by Claude Code
# instructions land under ~/.apm/apm_modules/.../instructions/ -> never reach ~/.claude/CLAUDE.md
ls ~/.claude/CLAUDE.md   # missing

apm compile has no --global / -g flag (see src/apm_cli/commands/compile/cli.py). The obvious workaround cd ~/.apm && apm compile --target claude writes to ~/.apm/CLAUDE.md, which Claude Code does not read.

Proposal

  1. When apm install -g finishes and at least one installed package carries instructions, run the compile pipeline with scope=USER so it reads ~/.apm/apm_modules/ and writes into each active target's user-scope root context path (~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md, ...).
  2. Add a symmetric --global / -g flag to apm compile.
  3. Honour CLAUDE_CONFIG_DIR and the equivalent env vars that TargetProfile.for_scope(user_scope=True) already handles.
  4. Reuse the <!-- Generated by APM CLI from .apm/ primitives --> marker rule so a hand-authored root context file is never overwritten without consent.

Packages that contain only skills, agents, commands, hooks, or MCP already work correctly under -g -- compile is not on the path for those primitives.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions