@linnify/asd
v1.4.0
Published
Set up Linnify ASD in a project: start it from the Linnify starter, pull the knowledge of the chosen packs, generate .asd/AGENTS.md, install the packs' skills and MCP servers, and install the asd Claude plugin.
Keywords
Readme
@linnify/asd
The ASD CLI. Run it in a project to pull what the project's packs ask for from the private linnify/asd repository:
- the packs' knowledge →
.asd/knowledge/ .asd/AGENTS.md→ the default project instructions followed by the list of pulled knowledge- the packs' skills → installed with
npx skills(project scope, Claude Code only) - the packs' MCP servers → added with
claude mcp add-json --scope project(.mcp.json) - the
asdClaude plugin → installed from theasdmarketplace at project scope (.claude/settings.json)
It also starts new projects from the Linnify starter — starter/ in
linnify/asd — and adds the starter's apps to them.
Plain Node ESM, no build step, no runtime dependencies.
Quick start
npx @linnify/asd init core web auth # writes .asd/config.json
npx @linnify/asd # pulls everythingCommit .asd/config.json, AGENTS.md, CLAUDE.md, .mcp.json, .claude/settings.json,
.claude/skills/, skills-lock.json and the .gitignore change. Run it again whenever
you want the latest ASD — it is idempotent.
To bring only the knowledge up to date — .asd/knowledge/ and .asd/AGENTS.md, without
touching the skills, MCP servers or plugin:
npx @linnify/asd --only-knowledgeStart a project
mkdir acme && cd acme && git init -b main
npx @linnify/asd apps # the app types the starter offers
npx @linnify/asd new --app web --app web:admin --app apiasd new [dir] sparse-clones linnify/asd at --ref (default main), copies the
starter's root — tooling, packages/, infra/, .github/ — into dir (default: the
current folder, which must be empty or hold only .git), and copies each --app into
apps/. --app web is the web app in apps/web; --app web:admin is a second copy of
it in apps/admin, whose package name (@app/admin) and Dockerfile paths follow the
folder. Apps you don't pick stay behind. Then it runs pnpm install (--skip-install
to skip). Only the files git tracks under starter/ are copied.
asd add --app web:admin adds apps to a project that already has its root, from the
starter at the project's ref — it never touches the root and refuses a folder that
already exists.
.asd/config.json
{
"packs": ["core", "web", "auth", "database"],
"ref": "main"
}packs(required): pack names — files underpacks/in linnify/asd.npx @linnify/asd packslists them.ref(optional, defaultmain): the branch or tag of linnify/asd to pull — also the starterasd addandasd appsread.
What a pull does
- Reads
.asd/config.jsonand sparse-clones linnify/asd atref(SSH, then HTTPS). - Merges the packs, removing duplicates: knowledge ids, skill sources (a source wanted whole by any pack installs whole), MCP servers (the same name defined differently by two packs is an error).
- Replaces
.asd/knowledge/with exactly the merged knowledge. - Writes
.asd/AGENTS.md:instructions/INSTRUCTIONS.md+ a Development Knowledge section linking each knowledge'sKNOWLEDGE.md. - Makes
@.asd/AGENTS.mdthe first line of the rootAGENTS.md(unless it is already there) and createsCLAUDE.mdwith@AGENTS.mdwhen the project has none. - Ignores
.asd/*in.gitignoreexceptconfig.jsonandcontext.md(the plugin'ssetupskill writes the committedcontext.md), replacing earlier ASD entries. - Installs skills:
npx -y skills add <source> --agent claude-code --skill <names|*> -y. - Adds MCP servers:
claude mcp add-json <name> '<json>' --scope project— unchanged ones are skipped, changed ones re-added. - Installs the plugin:
claude plugin marketplace add linnify/asd --scope projectandclaude plugin install asd@asd --scope project(orupdatewhen already installed). - Writes
.asd/manifest.json: the commit pulled and what was installed. The next pull uses it to remove skills and MCP servers that no pack asks for any more — never the ones the project added itself.
Steps 7–9 report failures at the end (exit code 1) without stopping the others.
--only-knowledge skips steps 7–9 and keeps what the last pull installed in the manifest.
Commands
asd [pull] Pull the packs in .asd/config.json (default)
asd init <pack...> Create .asd/config.json
asd packs List the packs ASD offers
asd new [dir] Start a project from the starter with the --app apps
asd add Add the --app apps to this project from the starter
asd apps List the app types the starter offers
asd validate [dir] Validate an ASD checkout (used by linnify/asd CI)
--source <dir> Use a local ASD checkout instead of cloning (also: ASD_SOURCE)
--ref <ref> Override the config's ref
--app <type>[:<folder>] An app for new or add, repeatable
--skip-install Don't run pnpm install after new or add
--skip-skills | --skip-mcp | --skip-plugin
--only-knowledge Pull only the knowledge and .asd/AGENTS.md (steps 1–6): no skills,
MCP servers or plugin
--no-project-files Don't touch the root AGENTS.md, CLAUDE.md or .gitignore (steps 5–6)
--if-stale Pull only when there is something new (below)--if-stale compares the commit in .asd/manifest.json with the one ref is at now
(git ls-remote, no clone) and does nothing when they match — unless the config's packs
changed or .asd/AGENTS.md is missing. When linnify/asd can't be reached it keeps what is
there.
The knowledge stays current on its own
Nobody has to remember to pull the knowledge: the asd plugin has a SessionStart hook
(plugin/hooks/) that runs, when a Claude Code session starts in a
project with an .asd/config.json:
npx -y @linnify/asd@latest --if-stale --skip-skills --skip-mcp --skip-plugin --no-project-filesIt writes only the ignored files under .asd/, so it also fills a fresh clone or git
worktree, and it never fails a session. ASD_AUTO_PULL=0 turns it off. Skills and MCP
servers still come from a pull you run yourself.
A knowledge-only pull — what the Software Factory's sandbox image build runs in a
throwaway clone of the project — writes .asd/ and nothing else:
npx @linnify/asd --skip-skills --skip-mcp --skip-plugin --no-project-filesASD_REPO overrides the clone URL.
Requirements
- Node 20+,
git, and read access to linnify/asd (the package is public, the content is not). - The
claudeCLI for MCP servers and the plugin. pnpmfornewandadd; the starter itself needs Node 24+.
Develop
cli/ is a member of the repo's root pnpm workspace, but it has no dependencies: the tests
and the CLI run with plain node, no install needed.
cd cli
node --test # unit tests (from the root: pnpm --filter @linnify/asd test)
node bin/asd.mjs validate .. # validate packs + knowledge (from the root: pnpm validate)
cd ../../some-project && node ../asd/cli/bin/asd.mjs --source ../asd # try a local change
node ../asd/cli/bin/asd.mjs new ../acme --source ../asd --app web # try a starter changeKeep it that way — no dependencies, and files limits the published package to
bin/asd.mjs and src/*.mjs.
Release
Publishing is version-gated: bump version in cli/package.json in the same commit as
the change (patch: fix, minor: new option or step, major: breaking config or behavior).
The push to main publishes it through .github/workflows/publish-cli.yml (npm trusted
publishing — no token) and tags cli-v<version>. An unchanged version is a no-op.
