@toolmesh/agent-deck 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Julien La Vinh
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,434 @@
1
- # Temporary Holding Version
1
+ # agent-deck
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ [![npm](https://img.shields.io/npm/v/@toolmesh/agent-deck)](https://www.npmjs.com/package/@toolmesh/agent-deck)
4
+ [![CI](https://github.com/tilap/agent-deck/actions/workflows/ci.yml/badge.svg)](https://github.com/tilap/agent-deck/actions/workflows/ci.yml)
5
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
6
+
7
+ A package manager for AI agent capabilities. It installs skills, agents, commands, rules,
8
+ hooks and MCP servers into a project for **Claude Code** and **Cursor**, pins them in a
9
+ lockfile, and reinstalls exactly the same thing later: on another machine, in CI, or for
10
+ an agent runner.
11
+
12
+ ## Why
13
+
14
+ Skills, agent prompts and MCP configuration are usually copied by hand from project to
15
+ project, or buried in the application code. They drift, nobody knows which version a
16
+ project runs, and a fix in one place never reaches the others.
17
+
18
+ agent-deck moves the agent side out of your code:
19
+
20
+ - **Capabilities live in plugin marketplaces**, as ordinary git repositories, npm
21
+ packages, archives or local folders, versioned and reviewed on their own.
22
+ - **A project only states what it wants** in `ai-plugin.json`, the way `package.json`
23
+ lists dependencies.
24
+ - **A lockfile pins what it got**: commit, version, content digest. `--frozen` refuses
25
+ anything that does not match, so CI and teammates run the same agents.
26
+ - **Both hosts get the same plugins.** One request, installed natively in Claude Code and
27
+ copied into `.cursor/` for Cursor.
28
+ - **Roles are profiles.** A builder, a tester and a reviewer each get their own prompt and
29
+ plugins on top of a shared base.
30
+
31
+ ## Install
32
+
33
+ Requires Node.js 22.14 or later and `git`.
34
+
35
+ ```bash
36
+ npm i -g @toolmesh/agent-deck
37
+ # or run it without installing
38
+ npx @toolmesh/agent-deck --help
39
+ ```
40
+
41
+ ## Quick start
42
+
43
+ ```bash
44
+ agent-deck init
45
+ agent-deck add owner/marketplace-repo@plugin-name --ref v0.1.0
46
+ agent-deck add anthropics/skills --skill pdf
47
+ agent-deck add ./plugins/my-plugin
48
+ ```
49
+
50
+ `init` wires `.gitignore`, `AGENTS.md` and `CLAUDE.md`. `add` writes the request to
51
+ `ai-plugin.json`, pins it in `ai-plugin.lock.json` and installs it for Claude Code and
52
+ Cursor. Commit both files; `.ai/installed/` stays on the machine and comes back with
53
+ `agent-deck install`.
54
+
55
+ On another machine, or in CI:
56
+
57
+ ```bash
58
+ agent-deck install --frozen
59
+ ```
60
+
61
+ While editing a plugin in a local checkout, install that working tree and leave the
62
+ committed request as it is:
63
+
64
+ ```bash
65
+ agent-deck link /path/to/marketplace@plugin-name
66
+ ```
67
+
68
+ Each profile is an agent role (builder, tester, reviewer) with its own prompt and plugins,
69
+ installed on top of the base:
70
+
71
+ ```bash
72
+ agent-deck profile new builder
73
+ agent-deck add anthropics/skills --skill pdf --profile builder
74
+ agent-deck profile use builder
75
+ ```
76
+
77
+ `profile use` installs the base plus that profile, points Claude at the profile prompt and
78
+ writes the Cursor rule from the same file. Open a new Claude session, or reload Cursor, to
79
+ pick it up. See [Profiles](#profiles).
80
+
81
+ ## How it maps to npm
82
+
83
+ | npm | agent-deck | Commit |
84
+ | ------------------- | ------------------------------------------------------------------- | ------ |
85
+ | `package.json` | `ai-plugin.json` — what you ask for | yes |
86
+ | `package-lock.json` | `ai-plugin.lock.json` — commits, versions, digests, contents | yes |
87
+ | `node_modules/` | `.ai/installed/plugins/<id>/` — each plugin, normalized | no |
88
+ | — | `.ai/installed/state.json` — what agent-deck wrote on this machine | no |
89
+ | — | `.ai/profiles/<name>/` — agent profiles (see [Profiles](#profiles)) | yes |
90
+ | — | `ai-plugin.local.json` — links to working trees | no |
91
+
92
+ ## Commands
93
+
94
+ ```
95
+ agent-deck init [--commit-copies]
96
+ agent-deck add <source> [--skill <name>]… [--ref <ref>] [--profile <name>]
97
+ agent-deck remove <id> [--profile <name>]
98
+ agent-deck install [--frozen]
99
+ agent-deck update [<id>…] [--profile <name>]
100
+ agent-deck status
101
+ agent-deck outdated
102
+ agent-deck link <folder>[@<plugin>] [--skill <name>]…
103
+ agent-deck unlink <id>
104
+ agent-deck profile new|use|off|list [<name>]
105
+ agent-deck materialize --out <dir> [--profile <name>] [--json]
106
+ ```
107
+
108
+ | Command | Effect |
109
+ | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
110
+ | `init` | Wire agent-deck into the project: see [Set up a project](#set-up-a-project) |
111
+ | `add` | Resolve, install, and lock. The request is written only if that succeeds. Creates `ai-plugin.json` if needed |
112
+ | `remove` | Drop the request, its normalized tree, its installed files, and its lock entry |
113
+ | `install` | Make the project match the base and the active profile, pinned by the locks. `--frozen` for CI |
114
+ | `update` | Resolve refs again (all, or the ids given) and rewrite the lock |
115
+ | `status` | Active profile, every request (`[base]`, `[profile x]`, `[link]`) and its lock pin, and every mismatch between request, lock, `.ai/installed/`, hosts, and `.gitignore`. Never touches the network. Exit 1 on errors |
116
+ | `outdated` | Lock pins vs what each ref or range points to now, and newer release tags. Exit 1 when behind |
117
+ | `link` | Install a local folder (a git checkout, uncommitted files included, or any folder of skills). Not locked |
118
+ | `unlink` | Drop the link; reinstall the committed request if there is one |
119
+ | `profile` | Agent profiles: see [Profiles](#profiles) |
120
+ | `materialize` | Build the base and one profile into a folder, for a tool that launches agents: see [Materialize](#materialize) |
121
+
122
+ Every command takes `-C <dir>` (`--project`), `--force` (let copy mode replace a file agent-deck
123
+ did not write), and `--help`. An option a command does not take is refused.
124
+
125
+ Advanced options: `add --id <id> --path <dir in source> --sha256 <hex> --no-install`,
126
+ `remove --keep-files` and `unlink --keep-files`, `link --id <id> --path <dir> --no-install`.
127
+
128
+ ## Set up a project
129
+
130
+ ```bash
131
+ agent-deck init # once per project; safe to run again
132
+ agent-deck init --commit-copies # same, but commit the copies in .claude/ and .cursor/
133
+ ```
134
+
135
+ | File | `agent-deck init` | Afterwards |
136
+ | ---------------- | -------------------------------------------------------- | --------------------------------------------------------------------- |
137
+ | `ai-plugin.json` | Created when missing | `agent-deck add` / `remove` |
138
+ | `.gitignore` | Created when missing; agent-deck's managed block written | `agent-deck install` rewrites the block |
139
+ | `AGENTS.md` | Created when missing | `agent-deck install` rewrites its `## Skills` block |
140
+ | `CLAUDE.md` | Created when missing, or given an `@AGENTS.md` line | `agent-deck profile use` / `off` add or drop `@.ai/current/prompt.md` |
141
+
142
+ `CLAUDE.md` imports `AGENTS.md`, so Claude Code reads what Cursor reads: write project
143
+ instructions once, in `AGENTS.md`.
144
+
145
+ agent-deck's block in `.gitignore` sits between two markers and is rewritten whole; lines
146
+ outside it are never touched:
147
+
148
+ ```
149
+ # >>> @toolmesh/agent-deck (managed: rewritten by agent-deck install)
150
+ .ai/installed/
151
+ .ai/current
152
+ ai-plugin.local.json
153
+ .cursor/rules/agent-deck-profile.mdc
154
+ /.cursor/skills/commit
155
+ …
156
+ # <<< @toolmesh/agent-deck
157
+ ```
158
+
159
+ Besides the local files, it lists every path copy mode writes in `.claude/` and `.cursor/`
160
+ for every plugin the base **or any profile** pins, read from the committed locks, for every
161
+ host that is not `off`: like `node_modules`, they come back with `agent-deck install`, so the
162
+ repository holds only the intent (`ai-plugin.json`, locks, profiles). The block does not
163
+ depend on the active profile or on which CLIs a machine has: `agent-deck profile use` never
164
+ changes `.gitignore`, and adding to or removing from a profile that is not active updates it. `agent-deck init --commit-copies` sets
165
+ `"gitignoreCopies": false` in `ai-plugin.json`: the copies stay out of the block and get
166
+ committed, so a fresh clone works in Cursor before `agent-deck install`. Shared files agent-deck edits
167
+ (`.mcp.json`, `.cursor/mcp.json`, `AGENTS.md`, `CLAUDE.md`) are never ignored.
168
+
169
+ `agent-deck install` never creates `.gitignore`; `agent-deck status` warns when the block is missing.
170
+
171
+ ## Profiles
172
+
173
+ A profile is an agent role — builder, tester, reviewer — with its own prompt and plugins,
174
+ on top of the base every profile gets:
175
+
176
+ ```
177
+ ai-plugin.json, ai-plugin.lock.json the base (committed)
178
+ .ai/profiles/builder/prompt.md the builder's prompt (committed)
179
+ .ai/profiles/builder/ai-plugin.json, …lock.json the builder's plugins (committed)
180
+ .ai/current → profiles/builder the active profile (local)
181
+ .ai/installed/ installed plugins and state (local)
182
+ ```
183
+
184
+ ```bash
185
+ agent-deck profile new builder # .ai/profiles/builder/ with prompt.md and an empty request
186
+ agent-deck add anthropics/skills --skill pdf --profile builder
187
+ agent-deck profile use builder # base + builder installed; then a new Claude session / reload Cursor
188
+ agent-deck profile use tester # builder's plugins leave, tester's arrive, the base is untouched
189
+ agent-deck profile off
190
+ agent-deck profile list # * marks the active one
191
+ ```
192
+
193
+ `agent-deck add --profile x` on a profile that is not active resolves and locks the plugin in
194
+ `.ai/profiles/x/` without installing it. A plugin id belongs to the base or to a profile, not both.
195
+
196
+ The prompt follows `.ai/current`: `profile use` adds `@.ai/current/prompt.md` to
197
+ `CLAUDE.md` once, and writes `.cursor/rules/agent-deck-profile.mdc` (`alwaysApply`) from the
198
+ profile's `prompt.md`. `profile off` removes both. `.ai/current` and the Cursor rule are
199
+ in agent-deck's `.gitignore` block.
200
+
201
+ ## Materialize
202
+
203
+ `agent-deck materialize` builds what an agent needs to run, without installing anything in the
204
+ project: the base and one profile (or the base alone), as pinned by their locks, each
205
+ plugin in `<out>/<id>/` with its Claude Code and Cursor manifests.
206
+
207
+ ```bash
208
+ agent-deck materialize --profile builder --out /tmp/agents/builder --json
209
+ ```
210
+
211
+ ```json
212
+ {
213
+ "profile": "builder",
214
+ "prompt": "/path/to/project/.ai/profiles/builder/prompt.md",
215
+ "out": "/tmp/agents/builder",
216
+ "plugins": [
217
+ {
218
+ "id": "git-workflow",
219
+ "path": "/tmp/agents/builder/git-workflow",
220
+ "integrity": "sha256-…",
221
+ "components": { "skills": ["commit", "…"], "…": [] }
222
+ }
223
+ ]
224
+ }
225
+ ```
226
+
227
+ - Always frozen: a request a lock does not pin, or content that differs from its
228
+ integrity, is refused.
229
+ - `--profile` names the profile; `.ai/current` is not read, so several profiles can be
230
+ built side by side. Local links are ignored: the output is what is committed.
231
+ - Writes only in `--out`: nothing in `.claude/`, `.cursor/`, the locks, `.ai/installed/`,
232
+ `.gitignore`, or `AGENTS.md`. A plugin already in `--out` with the locked integrity is
233
+ kept; a folder of a plugin no longer requested is removed.
234
+
235
+ Load the result with `claude --plugin-dir <out>` (Claude loads every plugin in the folder)
236
+ or one `cursor-agent --plugin-dir <out>/<id>` per plugin, and pass `prompt` as the
237
+ agent's instructions.
238
+
239
+ ## Sources
240
+
241
+ | You type | Request |
242
+ | ----------------------------------- | ------------------------------------------------------------- |
243
+ | `owner/repo@plugin` | `{ "source": "github:owner/repo", "plugin": "plugin" }` |
244
+ | `owner/repo` | a single-plugin repository, or a repository of skills |
245
+ | `owner/repo --skill a --skill b` | only those skills |
246
+ | `https://github.com/owner/repo` | same as `owner/repo` |
247
+ | `git+https://gitlab.com/t/r.git#v1` | `{ "source": "git:https://gitlab.com/t/r.git", "ref": "v1" }` |
248
+ | `git@host:team/repo.git` | any git host over SSH |
249
+ | `npm:@scope/pkg@^2` | `{ "source": "npm:@scope/pkg", "version": "^2" }` |
250
+ | `https://…/kit.zip` (or `.tar.gz`) | `{ "source": "archive:https://…/kit.zip" }` |
251
+ | `./plugins/name` | `{ "source": "path:plugins/name" }` |
252
+ | `./plugins@name` | `{ "source": "path:plugins", "plugin": "name" }` |
253
+
254
+ The id defaults to the plugin name (or the repository name); `--id` overrides it.
255
+ Without `--ref`, agent-deck takes the default branch and locks the commit it found.
256
+
257
+ `./path` is a directory inside the project. The request stores `path:<relative>` (no leading
258
+ `./`) and the lock stores that path plus the integrity of the normalized tree. `agent-deck install`
259
+ re-reads the directory; `--frozen` refuses when the files no longer match the lock. A path
260
+ without `./` is a GitHub `owner/repo`. A folder outside the project is `agent-deck link`.
261
+
262
+ Inside a fetched source, agent-deck finds the plugin the way Claude Code and Cursor do:
263
+
264
+ - `.claude-plugin/marketplace.json` or `.cursor-plugin/marketplace.json`, with every
265
+ Claude Code plugin source: relative path (and `metadata.pluginRoot` bare names),
266
+ `github`, `url`, `git-subdir`, `npm`, and `archive`. A source object is fetched in turn
267
+ and its own commit is locked as `nested`. `command` sources are refused.
268
+ - `strict` semantics: an entry without `plugin.json` is the manifest (e.g. the skill
269
+ lists of `anthropics/skills`); a `strict: false` entry that declares components next
270
+ to a `plugin.json` is a conflict.
271
+ - Custom component paths in `.claude-plugin/plugin.json` or `.cursor-plugin/plugin.json`
272
+ (`skills`, `agents`, `commands`, `rules`, `hooks`, `mcpServers`).
273
+ - No marketplace: `plugins/<name>/`, a plugin at the root, a `skills/*/SKILL.md`
274
+ repository, or a single `SKILL.md` at the root.
275
+
276
+ ## What gets installed
277
+
278
+ Every plugin is first normalized under `.ai/installed/plugins/<id>/`: `skills/`, `agents/`,
279
+ `commands/`, `rules/`, `hooks/hooks.json`, `mcp.json`, its support files, and generated
280
+ `.claude-plugin/plugin.json`, `.cursor-plugin/plugin.json`, and root `plugin.json`. That
281
+ tree loads as is with `claude --plugin-dir` and `cursor-agent --plugin-dir`.
282
+ `.ai/installed/.claude-plugin/marketplace.json` lists every installed plugin as a local
283
+ marketplace.
284
+
285
+ Then each host is activated. `ai-plugin.json` can set a mode per host:
286
+
287
+ ```json
288
+ { "plugins": [], "hosts": { "claude": "native", "cursor": "copy" } }
289
+ ```
290
+
291
+ | Mode | Claude Code | Cursor |
292
+ | -------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
293
+ | `native` | default — `.ai/installed/` is a local marketplace; each plugin is installed from it | not supported, falls back to `copy` |
294
+ | `copy` | vendor components into `.claude/`, `.mcp.json` | default — vendor into `.cursor/` |
295
+ | `off` | nothing for that host | nothing for that host |
296
+
297
+ **Native (Claude Code).** agent-deck runs `claude plugin marketplace add <project>/.ai/installed --scope
298
+ local`, then `claude plugin install <id>@agent-deck --scope local` for each plugin (and
299
+ `plugin uninstall` when it goes). An installed plugin needs no further call: Claude reads
300
+ its tree, so hooks, commands, agents, MCP servers, and `${CLAUDE_PLUGIN_ROOT}` work as the plugin
301
+ author intended, and skills are namespaced (`impeccable:impeccable`). The registration is
302
+ recorded in `.claude/settings.local.json` and in the user's plugin registry, so every
303
+ machine runs `agent-deck install` once. Without the `claude` CLI on `PATH` (or
304
+ `AGENT_DECK_CLAUDE_BIN`), agent-deck falls back to copy mode and says so. The `agent-deck` marketplace is
305
+ removed when no plugin is installed from it.
306
+
307
+ **Cursor.** `cursor-agent` ignores plugin paths returned by a `workspaceOpen` hook, so Cursor uses copy mode. Agent runners can still pass
308
+ `.ai/installed/plugins/<id>` to `cursor-agent --plugin-dir`.
309
+
310
+ Copy mode writes:
311
+
312
+ | Component | Claude Code | Cursor |
313
+ | --------------------------------------- | ------------------------ | ------------------------ |
314
+ | Skills | `.claude/skills/<name>/` | `.cursor/skills/<name>/` |
315
+ | Agents (nested folders kept) | `.claude/agents/` | `.cursor/agents/` |
316
+ | Commands | `.claude/commands/<id>/` | `.cursor/commands/<id>/` |
317
+ | Rules | — | `.cursor/rules/<id>/` |
318
+ | Support files | `.claude/plugins/<id>/` | `.cursor/plugins/<id>/` |
319
+ | MCP (keys `agent-deck__<id>__<server>`) | `.mcp.json` | `.cursor/mcp.json` |
320
+
321
+ Relative links from a skill to a support file are rewritten to the per-plugin directory.
322
+ `${CLAUDE_PLUGIN_ROOT}`, `${CURSOR_PLUGIN_ROOT}`, and `${PLUGIN_ROOT}` are replaced with
323
+ that directory in skills and MCP servers. Hooks are not active in copy mode; agent-deck and
324
+ `agent-deck status` say so. Copy mode refuses to write a path another plugin owns, or one agent-deck did not write
325
+ (`--force` replaces the latter).
326
+
327
+ Optional `skills/<name>/DEFAULT_USAGE.md` is not copied. Its body is stored in the lock
328
+ as `agentsSnippets` and, when `AGENTS.md` exists and `writeAgentsMd` is true, written to
329
+ a marked `## Skills` block. `agent-deck install` never creates `AGENTS.md`; `agent-deck init` does.
330
+
331
+ ## ai-plugin.json
332
+
333
+ Settings: `"hosts"` (see above), `"agentsMd": false` to leave `AGENTS.md` alone (the
334
+ lock mirrors it as `writeAgentsMd`), and `"gitignoreCopies": false` to commit the copies
335
+ (see [Set up a project](#set-up-a-project)).
336
+
337
+ ```json
338
+ {
339
+ "plugins": [
340
+ {
341
+ "id": "impeccable",
342
+ "source": "github:pbakaus/impeccable",
343
+ "plugin": "impeccable",
344
+ "ref": "v4.5.2"
345
+ },
346
+ {
347
+ "id": "doc-skills",
348
+ "source": "github:anthropics/skills",
349
+ "plugin": "document-skills"
350
+ },
351
+ { "id": "fmt", "source": "npm:@acme/formatter", "version": "^2" }
352
+ ]
353
+ }
354
+ ```
355
+
356
+ ## ai-plugin.lock.json
357
+
358
+ Format 1, committed. One entry per id: the request, what it resolved to, the integrity of
359
+ the normalized tree, its components, and its `AGENTS.md` snippets. Nothing in it depends
360
+ on the machine.
361
+
362
+ ```json
363
+ {
364
+ "lockfileVersion": 3,
365
+ "writeAgentsMd": true,
366
+ "plugins": [
367
+ {
368
+ "id": "impeccable",
369
+ "request": {
370
+ "id": "impeccable",
371
+ "source": "github:pbakaus/impeccable",
372
+ "plugin": "impeccable"
373
+ },
374
+ "resolved": {
375
+ "type": "git",
376
+ "url": "https://github.com/pbakaus/impeccable.git",
377
+ "sha": "c63b8dd7…"
378
+ },
379
+ "integrity": "sha256-…",
380
+ "components": {
381
+ "skills": ["impeccable"],
382
+ "agents": ["…"],
383
+ "commands": [],
384
+ "rules": [],
385
+ "hooks": true,
386
+ "mcp": []
387
+ },
388
+ "agentsSnippets": []
389
+ }
390
+ ]
391
+ }
392
+ ```
393
+
394
+ `install` keeps each pin while the request is unchanged; `update` moves it. A plugin
395
+ whose pin, normalized tree, host modes, and installed files all match what is on disk is
396
+ skipped (`up to date`): no fetch, no copy, no `claude` call. Fetches are cached under
397
+ `~/.cache/agent-deck/` by commit, by exact npm version, and by archive digest, so a
398
+ pinned source is downloaded once per machine.
399
+ `install --frozen` refuses a request the lock does not pin, a lock entry nothing
400
+ requests, and a normalized tree whose integrity differs — use it in CI.
401
+
402
+ `.gitignore`: see [Set up a project](#set-up-a-project).
403
+
404
+ ## Developing a plugin
405
+
406
+ `link` installs a local folder — a git checkout (uncommitted files included, `.gitignore`
407
+ respected) or any directory of skills — without touching `ai-plugin.json` or the lock. The link lives in `ai-plugin.local.json` and replaces a
408
+ committed request with the same id.
409
+
410
+ ```bash
411
+ agent-deck link /path/to/my-plugins@my-plugin --project /path/to/app
412
+ # edit the skill, then pick up the working tree again:
413
+ agent-deck install --project /path/to/app
414
+ agent-deck unlink my-plugin --project /path/to/app
415
+ ```
416
+
417
+ Caches live under `~/.cache/agent-deck/` (override with `AGENT_DECK_CACHE`).
418
+ `AGENT_DECK_LOCAL_<owner>__<repo>` points a GitHub source at a local checkout for scripts and
419
+ integration tests: the current branch and `HEAD` use the working tree, any other ref is
420
+ checked out from a local clone.
421
+
422
+ ## Auth
423
+
424
+ Uses the machine’s existing `git` access (SSH agent, `gh`, credential helper) and npm
425
+ configuration. No tokens are stored by this CLI. npm packages are packed with
426
+ `--ignore-scripts`.
427
+
428
+ ## Contributing
429
+
430
+ See [CONTRIBUTING.md](CONTRIBUTING.md). Security reports: [SECURITY.md](SECURITY.md).
431
+
432
+ ## License
433
+
434
+ [MIT](LICENSE) © 2026 Julien La Vinh
@@ -0,0 +1,2 @@
1
+ #!/usr/bin/env node
2
+ import "../src/cli.mjs";
package/package.json CHANGED
@@ -1,6 +1,44 @@
1
1
  {
2
2
  "name": "@toolmesh/agent-deck",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "Install and sync Claude Code and Cursor plugins, skills, agents and MCP servers into a project from a lockfile.",
5
+ "type": "module",
6
+ "author": "Julien La Vinh",
7
+ "license": "MIT",
8
+ "engines": {
9
+ "node": ">=22.14"
10
+ },
11
+ "bin": {
12
+ "agent-deck": "bin/agent-deck.js"
13
+ },
14
+ "files": [
15
+ "bin/**",
16
+ "src/**/*.mjs",
17
+ "!src/**/*.test.mjs",
18
+ "!src/testkit.mjs"
19
+ ],
20
+ "scripts": {
21
+ "test": "node --test src/*.test.mjs"
22
+ },
23
+ "publishConfig": {
24
+ "access": "public"
25
+ },
26
+ "repository": {
27
+ "type": "git",
28
+ "url": "git+https://github.com/tilap/agent-deck.git"
29
+ },
30
+ "bugs": {
31
+ "url": "https://github.com/tilap/agent-deck/issues"
32
+ },
33
+ "homepage": "https://github.com/tilap/agent-deck#readme",
34
+ "keywords": [
35
+ "claude-code",
36
+ "cursor",
37
+ "agents",
38
+ "skills",
39
+ "plugins",
40
+ "mcp",
41
+ "marketplace",
42
+ "lockfile"
43
+ ]
44
+ }
package/src/agents.mjs ADDED
@@ -0,0 +1,87 @@
1
+ import fs from "node:fs";
2
+ import path from "node:path";
3
+
4
+ export const AGENTS_FILE = "AGENTS.md";
5
+ export const SKILLS_START = "<!-- agent-deck:skills:start -->";
6
+ export const SKILLS_END = "<!-- agent-deck:skills:end -->";
7
+
8
+ /**
9
+ * Collect DEFAULT_USAGE.md bodies from locked plugins, in lock order then skill name.
10
+ * @param {{ plugins?: Array<{ agentsSnippets?: Array<{ skill: string, body: string }> }> }} lock
11
+ */
12
+ export function collectAgentsSnippets(lock) {
13
+ const snippets = [];
14
+ for (const record of lock?.plugins || []) {
15
+ const items = [...(record.agentsSnippets || [])].sort((a, b) =>
16
+ a.skill.localeCompare(b.skill),
17
+ );
18
+ for (const item of items) {
19
+ if (!item?.body?.trim()) continue;
20
+ snippets.push(item.body.trimEnd());
21
+ }
22
+ }
23
+ return snippets;
24
+ }
25
+
26
+ function buildSkillsBlock(snippets) {
27
+ return [
28
+ SKILLS_START,
29
+ "## Skills",
30
+ "",
31
+ ...snippets,
32
+ "",
33
+ SKILLS_END,
34
+ ].join("\n");
35
+ }
36
+
37
+ /**
38
+ * Rewrite the agent-deck skills block in AGENTS.md from the lock.
39
+ * Does nothing when AGENTS.md is missing.
40
+ * When writeAgentsMd is false or there are no snippets, removes an existing marked block.
41
+ */
42
+ export function rewriteAgentsMd(projectRoot, lock) {
43
+ const file = path.join(projectRoot, AGENTS_FILE);
44
+ if (!fs.existsSync(file)) return { wrote: false, reason: "missing" };
45
+
46
+ const enabled = lock?.writeAgentsMd !== false;
47
+ const snippets = enabled ? collectAgentsSnippets(lock) : [];
48
+ const original = fs.readFileSync(file, "utf8");
49
+ const start = original.indexOf(SKILLS_START);
50
+ const end = original.indexOf(SKILLS_END);
51
+
52
+ let next;
53
+ if (snippets.length === 0) {
54
+ if (start === -1 || end === -1 || end < start) {
55
+ return {
56
+ wrote: false,
57
+ reason: enabled ? "no-snippets" : "disabled",
58
+ };
59
+ }
60
+ const before = original.slice(0, start).replace(/\n+$/, "");
61
+ const after = original.slice(end + SKILLS_END.length).replace(/^\n+/, "\n");
62
+ next = `${before}${after === "\n" || after === "" ? "\n" : after}`;
63
+ if (!next.endsWith("\n")) next += "\n";
64
+ } else {
65
+ const block = buildSkillsBlock(snippets);
66
+ if (start !== -1 && end !== -1 && end > start) {
67
+ const before = original.slice(0, start).replace(/\n+$/, "\n\n");
68
+ const after = original.slice(end + SKILLS_END.length).replace(/^\n*/, "\n");
69
+ next = `${before}${block}${after.startsWith("\n") ? after : `\n${after}`}`;
70
+ } else {
71
+ const body = original.replace(/\n*$/, "\n\n");
72
+ next = `${body}${block}\n`;
73
+ }
74
+ }
75
+
76
+ if (next === original) return { wrote: false, reason: "unchanged" };
77
+ fs.writeFileSync(file, next, "utf8");
78
+ return { wrote: true, snippets: snippets.length, enabled };
79
+ }
80
+
81
+ /** Read optional DEFAULT_USAGE.md next to a skill; empty or missing → null. */
82
+ export function readDefaultUsage(pluginDir, skillName) {
83
+ const file = path.join(pluginDir, "skills", skillName, "DEFAULT_USAGE.md");
84
+ if (!fs.existsSync(file)) return null;
85
+ const body = fs.readFileSync(file, "utf8").trimEnd();
86
+ return body ? { skill: skillName, body } : null;
87
+ }