asdm-cli

⚙️ ASDM — Agentic Software Delivery Model

Write Once, Emit Many. One source of truth for all your AI coding assistant configurations.

⚡ Quick Start

# 1. Install globally (or use npx for zero-install)
npm install -g asdm-cli

# Project Setup (per repository)
asdm init           # creates .asdm.json
asdm sync           # installs to project-local provider dirs

# Machine Setup (no project needed)
asdm init --global  # creates ~/.config/asdm/config.json
asdm sync --global  # installs to global provider config dirs

That's it. ASDM will download your team's canonical AI assistant configurations and emit them into the correct locations for every provider your project uses — OpenCode, Claude Code, and GitHub Copilot — all from a single command.

What is ASDM?

ASDM solves a real problem: every AI coding assistant speaks a different dialect.

• OpenCode stores agents in .opencode/agents/, config in opencode.jsonc
• Claude Code uses .claude/agents/, skills in .claude/skills/, and CLAUDE.md
• GitHub Copilot expects .github/agents/*.agent.md and copilot-instructions.md

When your team upgrades a code-reviewer agent, that change needs to reach every developer in every format. Doing this manually doesn't scale. Doing it wrong breeds configuration drift — and configuration drift means inconsistent AI behavior across your codebase.

The "Write Once, Emit Many" Model

ASDM introduces a canonical format — .asdm.md files with YAML frontmatter — that serves as the single source of truth for every agent, skill, and command. A publish step converts this format into every provider's native layout simultaneously:

asdm-registry (GitHub)
    └── agents/code-reviewer.asdm.md  ← single source
           │
           ├──▶  .opencode/agents/code-reviewer.md        (OpenCode)
           ├──▶  .claude/agents/code-reviewer.md          (Claude Code)
           └──▶  .github/agents/code-reviewer.agent.md    (GitHub Copilot)

Corporate Governance Built In

ASDM is designed for teams. The registry includes a corporate policy that travels with every release:

• Allowed profiles — developers can only use profiles the platform team approves
• Locked fields — telemetry, hook installation, and auto-verify cannot be disabled locally
• Integrity verification — SHA-256 checksums prevent silent tampering of managed files
• Git hooks — pre-commit hooks block commits if managed files have been modified

Installation

Global install (recommended)

npm install -g asdm-cli
asdm --help

Zero-install via npx

npx asdm-cli sync

Requirements

• Node.js ≥ 18.0.0
• Git (for hook installation)
• A GitHub token with read access to your registry repo (set as GITHUB_TOKEN or ASDM_GITHUB_TOKEN)

Commands Reference

Core Commands

asdm init [profile]

Initialize .asdm.json in the current project.

asdm init                                                  # profile: base
asdm init fullstack-engineer                               # specify profile positionally
asdm init --profile data-analytics --registry github://acme/asdm-registry
asdm init --force                                          # overwrite existing config
asdm init --gitignore                                      # also update .gitignore
asdm init --global                                         # write to ~/.config/asdm/config.json

Option	Description
--registry <url>	Registry URL in github://org/repo format
--force	Overwrite existing config
--gitignore	Add ASDM output dirs to .gitignore automatically (local only)
--global	Write to ~/.config/asdm/config.json instead of .asdm.json

asdm sync

Download agents, skills, and commands from the registry and emit them for all configured providers. This is the primary command you run daily.

asdm sync                            # full sync for all providers
asdm sync --global                   # install to global provider config directories
asdm sync --provider opencode        # sync only OpenCode files
asdm sync --force                    # re-download everything (ignore cache)
asdm sync --dry-run                  # preview changes without writing files
asdm sync --verbose                  # detailed output

Option	Description
--global	Install to global provider config dirs (~/.config/opencode/, ~/.claude/, etc.) instead of project-local folders
--provider <name>	Sync only for opencode, claude-code, or copilot
--force	Re-download all assets, bypassing the local cache
--dry-run	Show what would change without writing anything
--verbose	Print each emitted file

Incremental sync: ASDM compares the registry manifest against your local lockfile and only downloads assets that have changed. On a warm cache, unchanged projects sync in under 1 second.

asdm verify

Check that all managed files match their SHA-256 checksums in the lockfile.

asdm verify                  # print all violations
asdm verify --strict         # exit 1 on any violation (used by pre-commit hook)
asdm verify --quiet          # suppress output, just set exit code

Exit codes:

Code	Meaning
0	All managed files are intact
1	One or more files have been modified
2	Lockfile is missing — run asdm sync
3	Registry has a newer version available

asdm status

Show the diff between your local files and what the registry would emit.

asdm status
asdm status --verbose

asdm use <profile>

Switch to a different profile. Writes the override to .asdm.local.json (gitignored) and re-runs sync automatically.

asdm use mobile
asdm use fullstack-engineer
asdm use data-analytics

The profile must be in the allowed_profiles list from corporate policy. .asdm.local.json is gitignored so each developer can maintain their own profile override without affecting the committed project config.

Informational Commands

asdm profiles

List all profiles available in the registry, along with their agent/skill/command counts.

asdm profiles

asdm agents

List all agents in the active profile.

asdm agents

asdm skills

List all skills in the active profile.

asdm skills

asdm commands

List all slash commands in the active profile.

asdm commands

asdm version

Print CLI version, Node.js version, and OS details.

asdm version

Maintenance Commands

asdm doctor

Run a full health check on the ASDM setup. Checks:

• .asdm.json present
• Registry reachable
• Lockfile present
• Managed files unmodified
• All managed files on disk
• Overlay references valid
• .gitignore contains ASDM block
• Local manifest version vs. registry

asdm doctor

Exits 0 if all checks pass, 1 if any fail.

asdm clean

Remove all ASDM-managed files. Use before a full reinstall or when switching to a new profile and starting fresh.

asdm clean                             # remove all managed files + lockfile
asdm clean --target opencode           # only clean OpenCode files
asdm clean --target claude-code        # only clean Claude Code files
asdm clean --dry-run                   # preview what would be removed
asdm clean --global                    # remove all globally managed files
asdm clean --global --target opencode  # only clean OpenCode global files

When run interactively (TTY), you will be prompted to confirm before any files are deleted. After cleaning, a summary shows how many files were removed and how much disk space was freed.

Option	Description
--dry-run	Preview what would be removed without deleting
--target <provider>	Only clean files for a specific provider
--global	Clean globally managed files (reads ~/.config/asdm/global-lock.json)

asdm hooks install

Install git hooks that automatically verify integrity before commits and sync after merges.

asdm hooks install                     # install both hooks (default)
asdm hooks install --hook pre-commit   # only install pre-commit hook
asdm hooks install --hook post-merge   # only install post-merge hook
asdm hooks uninstall                   # remove both hooks
asdm hooks uninstall --hook pre-commit # remove only pre-commit hook

pre-commit hook — Runs asdm verify --strict --quiet before every commit. Blocks the commit if any managed file has been tampered with.

post-merge hook — Runs asdm sync automatically after git pull or git merge when .asdm.json is present in the project root.

Option	Description
--hook <type>	pre-commit | post-merge | all (default: all)

asdm gitignore

Add ASDM-generated output directories to .gitignore. Managed files should not be committed — they are regenerated by asdm sync.

asdm gitignore

Adds a clearly-marked ASDM block to .gitignore that covers:

• .opencode/agents/, .opencode/skills/, .opencode/commands/
• .claude/agents/, .claude/skills/
• .github/agents/, .github/skills/
• .asdm.local.json (developer profile override)

asdm telemetry show

Print recent local telemetry events from .asdm-telemetry.jsonl.

asdm telemetry show             # last 20 events
asdm telemetry show --limit 50  # last 50 events
asdm telemetry show --json      # raw JSON output
asdm telemetry clear --force    # delete the telemetry log

Configuration

.asdm.json — Project config (committed to git)

Created by asdm init. This file defines the registry source, default profile, and active providers for the project.

{
  "$schema": "https://asdm.dev/schemas/config.schema.json",
  "registry": "github://your-org/asdm-registry",
  "profile": "fullstack-engineer",
  "providers": ["opencode", "claude-code", "copilot"]
}

Field	Type	Required	Description
registry	string	✅	Registry URL in github://org/repo format
profile	string	✅	Default profile for this project
providers	string[]	—	Active providers (default: ["opencode"])
$schema	string	—	JSON Schema reference for editor validation

.asdm.local.json — Developer override (gitignored)

Created automatically by asdm use <profile>. Never edit this manually.

{
  "profile": "mobile"
}

~/.config/asdm/config.json — Global config

Created by asdm init --global. Stores registry, profile, and provider settings for machine-wide installation. Uses the same schema as .asdm.json.

{
  "$schema": "https://asdm.dev/schemas/config.schema.json",
  "registry": "github://lennonalvesdias/asdm",
  "profile": "base",
  "providers": ["opencode"]
}

Note: This file is the fallback config source when running asdm sync --global or asdm verify --global outside of a project directory.

.asdm-lock.json — Lockfile (committed to git)

Generated by asdm sync. Records the exact SHA-256 of every emitted file and the manifest version. Enables:

• Offline integrity checks — asdm verify works without network access
• Incremental sync — only re-download changed assets
• Audit trail — full history via git blame

In global mode (asdm sync --global), the lockfile is stored at ~/.config/asdm/global-lock.json.

Configuration Layers

Config is resolved in three layers (highest precedence wins for non-locked fields):

Corporate Policy (manifest)    → locked fields cannot be overridden
      ↓
  .asdm.json (project)        → default profile, providers, registry
      ↓
.asdm.local.json (user)       → profile override via `asdm use`

Locked fields — set by the platform team in policy.yaml and embedded in every registry release:

• telemetry — cannot be disabled by developers
• install_hooks — enforced by policy
• auto_verify — enforced by policy

Registry Structure

A registry is a Git repository with the following layout:

asdm-registry/
├── profiles/
│   ├── base/
│   │   └── profile.yaml               # Agents and skills common to all
│   ├── fullstack-engineer/
│   │   └── profile.yaml               # Extends base
│   ├── data-analytics/
│   │   └── profile.yaml               # Extends base
│   └── mobile/
│       └── profile.yaml               # Extends base
│
├── agents/
│   ├── code-reviewer.asdm.md          # Canonical agent definition
│   ├── tdd-guide.asdm.md
│   └── architect.asdm.md
│
├── skills/
│   ├── react-best-practices/
│   │   └── SKILL.asdm.md
│   └── api-design/
│       └── SKILL.asdm.md
│
├── commands/
│   ├── review.asdm.md
│   └── test.asdm.md
│
├── policy.yaml                        # Corporate policy (locked fields)
└── manifest.json                      # Generated by CI — contains SHA-256 checksums

Canonical Format — Agents

Each agent is an .asdm.md file with YAML frontmatter followed by the agent's instruction body:

---
name: code-reviewer
type: agent
description: "Reviews PRs for security, performance, and clean code"
version: 1.3.0
tags: [review, security, quality]

providers:
  opencode:
    model: anthropic/claude-sonnet-4
    permissions: [read, write]
    tools: [bash, glob]
  claude-code:
    model: claude-sonnet-4-20250514
    allowedTools: [Read, Write, Bash]
  copilot:
    on: pull_request
    permissions:
      pull-requests: write
---

# Code Reviewer

You are a senior code reviewer with expertise in security and design patterns.

## Rules

- NEVER approve code without proper error handling
- ALWAYS check that secrets are not hardcoded

Canonical Format — Skills

---
name: react-best-practices
type: skill
description: "React component patterns and best practices"
version: 2.0.0
trigger: "When the developer asks about React components"

providers:
  opencode:
    location: skills/react-best-practices/
  claude-code:
    location: skills/react-best-practices/
  copilot:
    applyTo: "**/*.tsx,**/*.jsx"
---

# React Best Practices

## Component Structure

- Use functional components with hooks exclusively
- Prefer composition over inheritance

Profile Inheritance

Profiles support extends for layered inheritance. The base profile defines a minimum set of agents/skills that all developers share; specializations add on top:

# profiles/fullstack-engineer/profile.yaml
name: fullstack-engineer
extends:
  - base

agents:
  - code-reviewer
  - tdd-guide
  - architect

skills:
  - react-best-practices
  - api-design

commands:
  - review
  - test

providers:
  - opencode
  - claude-code
  - copilot

Publishing New Releases

The registry uses GitHub Actions to publish:

# .github/workflows/publish.yml (on merge to main)
- scripts/build-manifest.ts  generates manifest.json with SHA-256 per asset
- gh release create vX.Y.Z   uploads manifest + all assets as release artifacts

ASDM fetches releases/latest to determine if a sync is needed, then downloads only changed assets.

Providers

ASDM emits files in each provider's native format. You never write provider-specific files manually — they are all generated from the canonical .asdm.md sources.

OpenCode

Asset Type	Output Location
Agent	.opencode/agents/{name}.md
Skill	.opencode/skills/{name}/SKILL.md
Command	.opencode/commands/{name}.md
Root instructions	AGENTS.md
Config	.opencode/opencode.jsonc

Claude Code

Asset Type	Output Location
Agent	.claude/agents/{name}.md
Skill	.claude/skills/{name}/SKILL.md
Command	.claude/commands/{name}.md
Root instructions	CLAUDE.md
Settings	.claude/settings.json

GitHub Copilot

Asset Type	Output Location
Agent	.github/agents/{name}.agent.md (with YAML frontmatter)
Skill	.github/skills/{name}/SKILL.md
Command	.github/skills/{name}/SKILL.md (invocable as /command-name in Copilot CLI)
Root instructions	.github/copilot-instructions.md

Global Installation

Use asdm sync --global to install agents, skills, and commands into the global config directories of each provider. This makes your AI assistant configuration available in every project without per-project setup.

# First-time machine setup (no project needed):
asdm init --global   # creates ~/.config/asdm/config.json
asdm sync --global   # installs to global provider dirs
asdm verify --global # verify global installation
asdm clean --global  # remove global installation (when needed)

Global config directories

Provider	macOS / Linux	Windows
OpenCode	~/.config/opencode/	%APPDATA%\opencode\
Claude Code	~/.claude/	%APPDATA%\Claude\
GitHub Copilot	~/.config/github-copilot/	%APPDATA%\GitHub Copilot\

How it works

In global mode, ASDM strips the provider-specific prefix from each file path and writes directly to the provider's global config directory:

.opencode/agents/code-reviewer.md  →  ~/.config/opencode/agents/code-reviewer.md
.claude/agents/code-reviewer.md    →  ~/.claude/agents/code-reviewer.md

Project-root files (AGENTS.md, CLAUDE.md) are skipped in global mode — they have no meaningful global equivalent.

The global lockfile is stored at ~/.config/asdm/global-lock.json, separate from any project's .asdm-lock.json.

Config resolution

The --global flag controls where files are written (global provider dirs vs project-local). The config source for sync and verify with --global is resolved in this order:

• Local .asdm.json in the current directory (if present)
• ~/.config/asdm/config.json (fallback — created by asdm init --global)
• Error: "No config found. Run asdm init (project) or asdm init --global (machine-wide setup)."

This means you can run asdm sync --global from any directory — it will use the project config if you're inside a project, or fall back to your global config automatically.

Integrity & Governance

How Integrity Works

Every sync writes a SHA-256 checksum for each emitted file into .asdm-lock.json. Verification compares the current state of every managed file against this lockfile.

asdm verify
# ✓ .opencode/agents/code-reviewer.md       ok
# ✗ .opencode/agents/tdd-guide.md           MODIFIED (sha256 mismatch)
# ✓ .claude/agents/code-reviewer.md         ok

If a managed file has been edited manually, asdm verify reports it as a violation and (with --strict) exits with code 1.

Git Hooks

Install hooks to enforce governance automatically:

asdm hooks install

pre-commit — Blocks commits when managed files are tampered:

#!/usr/bin/env sh
# ASDM — managed pre-commit hook
npx asdm verify --strict --quiet

post-merge — Auto-syncs after git pull:

#!/usr/bin/env sh
# ASDM MANAGED — post-merge hook
if [ -f ".asdm.json" ]; then
  echo "🔄 ASDM: syncing after merge..."
  npx asdm sync
fi

Corporate Policy

The registry's policy.yaml is embedded in every manifest release. It defines what developers can and cannot override:

policy:
  locked_fields: [registry, telemetry, install_hooks]
  telemetry: true
  auto_verify: true
  install_hooks: true
  allowed_profiles:
    - base
    - fullstack-engineer
    - data-analytics
    - mobile
  allowed_providers:
    - opencode
    - claude-code
    - copilot
  min_cli_version: "1.0.0"

If a developer tries to use a profile or provider not in the allowed lists, ASDM exits with a clear policy violation error.

Overlay System

The overlay system lets developers add personal agents or skills on top of the managed set — without modifying any managed files and without triggering integrity violations.

Create .asdm-overlay.json in your project root:

{
  "additional_skills": [
    {
      "name": "my-custom-workflow",
      "source": "local",
      "path": "./my-skills/workflow/SKILL.md"
    },
    {
      "name": "community-skill",
      "source": "github",
      "repo": "someone/awesome-skills",
      "path": "skills/something"
    }
  ],
  "additional_agents": [],
  "provider_overrides": {
    "opencode": {
      "mcp_servers": [
        {
          "name": "local-db",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-sqlite", "./dev.db"]
        }
      ]
    }
  }
}

Rules for overlays:

• Overlays are strictly additive — they cannot modify or replace managed assets
• Overlay files are tracked separately in the lockfile (managed: false)
• asdm verify checks overlay files are still present but does not enforce their content (since you own them)
• asdm doctor validates that overlay references point to valid agents

Telemetry

ASDM uses local-only telemetry by default. No data leaves your machine unless you set up a telemetry endpoint in your registry.

What's collected

Events are written to .asdm-telemetry.jsonl in the project root:

{
  "event": "sync.completed",
  "timestamp": "2026-03-31T14:22:00Z",
  "machineId": "a3f9d2b1e4c0",
  "version": "0.1.0",
  "profile": "fullstack-engineer",
  "providers": ["opencode", "claude-code"],
  "assetCount": 24,
  "durationMs": 1230
}

Field	Description
machineId	Truncated SHA-256 of hostname+username — cannot identify a person
event	One of: sync.completed, sync.failed, verify.passed, verify.failed, init.completed, use.completed, doctor.ran
version	CLI version
profile	Active profile name

Viewing and clearing telemetry

asdm telemetry show           # print recent events
asdm telemetry show --json    # raw JSON
asdm telemetry clear --force  # delete the log

Disabling telemetry

If the corporate policy allows it (the telemetry field is not locked), you can disable telemetry locally:

{
  "registry": "github://your-org/asdm-registry",
  "profile": "fullstack-engineer",
  "telemetry": false
}

Note: If the platform team has locked telemetry: true in policy, this field will be ignored.

Contributing

Adding a new agent or skill to the registry

• Fork the registry repo and create a branch
• Add your .asdm.md file under agents/, skills/, or commands/
• Add the asset to the appropriate profile.yaml files
• Run npm run validate:registry to validate your schema
• Open a PR — CI will run schema validation and a dry-run manifest build
• On merge to main, CI publishes a new GitHub Release automatically

Canonical format schema

All .asdm.md files are validated against JSON Schemas at schemas/ in the registry. The frontmatter must conform to:

• schemas/agent.schema.json for agents
• schemas/skill.schema.json for skills
• schemas/command.schema.json for commands
• schemas/profile.schema.json for profiles

SPEC.md

The full technical specification is in specs/0001/SPEC.md. It documents the architecture, security model, telemetry schema, and the full roadmap.

Adding a new provider adapter

• Create src/adapters/{provider}.ts implementing the EmitAdapter interface from src/adapters/base.ts
• Register the adapter in src/core/syncer.ts in the loadAdapters switch
• Add the provider name to the union type in src/core/config.ts
• Write tests in tests/unit/adapters/{provider}.test.ts

License

MIT © ASDM Contributors

See LICENSE for the full text.

Architecture overview

DEV MACHINES
  │
  │  npx asdm sync
  ▼
ASDM CLI
  ├── Syncer       (diff, fetch, cache)
  ├── Verifier     (sha256, lockfile)
  ├── Emitters     (opencode, claude-code, copilot)
  └── Telemetry    (local JSONL)
  │
  │  HTTPS (GitHub API)
  ▼
GIT-BASED REGISTRY (GitHub Releases)
  ├── manifest.json     (SHA-256 checksums + corporate policy)
  └── assets/           (agents, skills, commands as .asdm.md)