Coexist with APM

Keep mdsmith and APM (Microsoft’s Agent Package Manager) from stepping on each other: ignore APM-deployed files so mdsmith fix never breaks a content hash, and validate your .apm/ source tree with the APM kind pack.

APM (Microsoft’s Agent Package Manager) deploys Markdown into committed paths and pins a SHA-256 per file in apm.lock.yaml. Running mdsmith fix on those files breaks the hash and trips apm audit --ci. The same deployed files follow the source package’s conventions, not the consumer’s, so mdsmith check may flag content the team cannot edit.

The .apm/ source tree is the opposite case: it is the author’s own Markdown, with contractual frontmatter APM’s docs state but never enforce. mdsmith kind files are the right checker for it.

One command sets up both sides:

mdsmith init --apm

# What --apm writes

--apm has two effects:

1. Kind pack: scaffolds four .mdsmith/kinds/apm-*.yaml files that validate .apm/ source files against APM’s frontmatter contracts and size limits.

2. Coexistence posture: appends an ignore: block to .mdsmith.yml (on a fresh repo) that scopes mdsmith fix away from APM-deployed and APM-compiled files. On an existing config it prints the block to merge by hand.

The --apm flag detects which harness directories are present (.github/, .claude/, .agents/, .windsurf/, .kiro/, .cursor/) and names only those in the ignore: list. A repo that only uses GitHub Copilot gets .github/prompts/** and .github/instructions/**; a Claude Code repo also gets .claude/rules/**.

# Which tool owns what

# The kind pack

The four kinds validate APM’s frontmatter contracts at edit time:

Optional frontmatter fields are allowed on each kind:

• apm-prompt: input, allowed-tools, model, argument-hint
• apm-instruction: applyTo
• apm-agent: model, color

The apm-prompt kind also opts all content rules into the apm-input-token placeholder, so ${input:name} parameter references in prompt bodies are treated as opaque rather than flagged as prose violations.

# Quick start

Run on a fresh repo or an existing project:

mdsmith init --apm

On a fresh repo, a new .mdsmith.yml is created with the ignore: posture and the four kind files are scaffolded beside it. On an existing project, the kind files are added and the posture block is printed to stderr for you to paste in.

Combine with other packs or starters:

# APM kind pack plus the curated no-llm-tells word-lists
mdsmith init --apm --add wordlists

# APM kind pack on top of an OKF starter
mdsmith init --starter okf --apm

--apm does not touch apm.yml, apm.lock.yaml, or any APM subcommand. It writes mdsmith config only.

# CI ordering

Run apm audit --ci before mdsmith check so the integrity gate catches a hash drift before the content gate reports style issues:

- name: apm audit
  run: apm audit --ci

- name: mdsmith check
  run: mdsmith check .

Both jobs can run in parallel if the repo has no deployed files that mdsmith check must see (because they are in ignore:).

# Adding harness dirs later

If you later add a new harness (for example, you start using Kiro and .kiro/ appears), re-run mdsmith init --apm with an existing config to get the updated merge hint for the new ignore: entries.

# See also

• File kinds — how path-pattern assigns files to kinds.
• Metrics trade-offs — tuning the 500-line and 5000-token caps for skill files.
• APM research — the full analysis of mdsmith and APM workflows.
• Init reference — all mdsmith init flags.