agentsmesh 0.2.4 → 0.2.6

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.
Files changed (3) hide show
  1. package/CHANGELOG.md +12 -0
  2. package/README.md +83 -172
  3. package/package.json +1 -1
package/CHANGELOG.md CHANGED
@@ -1,5 +1,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.2.6
4
+
5
+ ### Patch Changes
6
+
7
+ - d011602: Add a Starlight documentation site published to GitHub Pages; shorten the npm README and link to the hosted docs for full guides and CLI reference.
8
+
9
+ ## 0.2.5
10
+
11
+ ### Patch Changes
12
+
13
+ - f7a4afd: Expand the project README, add `ROADMAP.md`, and fix the sample Claude Code PostToolUse hook to use `type: prompt` with a `prompt` field instead of an invalid command-style hook after reads.
14
+
3
15
  ## 0.2.4
4
16
 
5
17
  ### Patch Changes
package/README.md CHANGED
@@ -1,222 +1,133 @@
1
- # AgentsMesh
1
+ <h1 align="center">AgentsMesh</h1>
2
2
 
3
- [![CI](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml/badge.svg)](https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml)
4
- [![npm version](https://img.shields.io/npm/v/agentsmesh.svg)](https://www.npmjs.com/package/agentsmesh)
5
- [![Coverage](https://codecov.io/gh/sampleXbro/agentsmesh/branch/master/graph/badge.svg)](https://codecov.io/gh/sampleXbro/agentsmesh)
6
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
7
- [![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue.svg)](https://www.typescriptlang.org/)
8
- [![Node.js](https://img.shields.io/node/v/agentsmesh.svg)](https://nodejs.org/)
9
- [![npm downloads](https://img.shields.io/npm/dm/agentsmesh.svg)](https://www.npmjs.com/package/agentsmesh)
3
+ <p align="center">
4
+ <a href="https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml"><img src="https://github.com/sampleXbro/agentsmesh/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
5
+ <a href="https://www.npmjs.com/package/agentsmesh"><img src="https://img.shields.io/npm/v/agentsmesh.svg" alt="npm version"></a>
6
+ <a href="https://codecov.io/gh/sampleXbro/agentsmesh"><img src="https://codecov.io/gh/sampleXbro/agentsmesh/branch/master/graph/badge.svg" alt="Coverage"></a>
7
+ <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
8
+ <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-blue.svg" alt="TypeScript"></a>
9
+ <a href="https://nodejs.org/"><img src="https://img.shields.io/node/v/agentsmesh.svg" alt="Node.js"></a>
10
+ <a href="https://www.npmjs.com/package/agentsmesh"><img src="https://img.shields.io/npm/dm/agentsmesh.svg" alt="npm downloads"></a>
11
+ <a href="https://samplexbro.github.io/agentsmesh"><img src="https://img.shields.io/badge/docs-website-brightgreen.svg" alt="Docs"></a>
12
+ <a href="https://github.com/sampleXbro/agentsmesh/pulls"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>
13
+ </p>
10
14
 
11
- AgentsMesh gives you one canonical AI config in `.agentsmesh/` and syncs it to the tools your team actually uses: Claude Code, Cursor, Copilot, Continue, Junie, Gemini CLI, Cline, Codex CLI, and Windsurf.
15
+ AgentsMesh maintains a single canonical configuration in `.agentsmesh/` and syncs it bidirectionally to Claude Code, Cursor, Copilot, Continue, Junie, Gemini CLI, Cline, Codex CLI, and Windsurf. Rules, commands, agents, skills, MCP servers, hooks, ignore patterns, and permissions -- all from one source of truth.
12
16
 
13
- The point is simple: keep one source of truth for rules, commands, agents, skills, MCP, hooks, ignore patterns, and permissions, then generate the right format for each tool without hand-editing nine different config layouts.
17
+ > **Full documentation: [samplexbro.github.io/agentsmesh](https://samplexbro.github.io/agentsmesh)**
14
18
 
15
- ## Why it is useful
19
+ ---
16
20
 
17
- - One canonical config instead of tool-by-tool drift
18
- - Import existing configs before you standardize anything
19
- - Generate back out to multiple tools from the same source
20
- - Keep team changes safe with lock files, drift checks, and merge recovery
21
- - See support clearly with a built-in compatibility matrix
22
- - Share base configs across repos with `extends`
23
- - Keep personal preferences local with `agentsmesh.local.yaml`
24
- - Preserve links and supporting files when content moves between targets
21
+ ## Why AgentsMesh
25
22
 
26
- ## What ships today
23
+ - **One source of truth** -- edit `.agentsmesh/`, generate everywhere. No more copy-pasting rules between tool directories.
24
+ - **Bidirectional sync** -- import existing configs into canonical form and generate back out. No data loss, no manual reformatting.
25
+ - **Team-safe collaboration** -- lock files track generated state, `check` catches drift in CI, `merge` resolves conflicts after `git merge`.
26
+ - **Lossless feature projection** -- when a tool lacks native support for a feature, AgentsMesh projects it as an embedded skill with enough metadata to round-trip on re-import.
27
27
 
28
- AgentsMesh already covers the pieces most teams care about in practice:
28
+ ---
29
29
 
30
- - Rules, commands, agents, skills, MCP servers, hooks, ignore patterns, and permissions
31
- - Bidirectional import/generate flow across 9 supported targets
32
- - `diff`, `lint`, `watch`, `check`, `merge`, and `matrix` commands
33
- - Local overrides with `agentsmesh.local.yaml`
34
- - Remote and local `extends` support
35
- - Lock file based collaboration for generated state
36
- - Link rebasing so internal file references still make sense after generation
37
- - Target-specific conversions where native support does not exist
30
+ ## Installation
38
31
 
39
- The strongest parts of the library right now are the operational pieces competitors usually skip: permissions syncing, lock file handling, diffing, linting, watch mode, local overrides, link rebasing, and the compatibility matrix.
32
+ Requires **Node.js 20** or later.
40
33
 
41
- ## Supported tools
42
-
43
- | Tool | Current support |
44
- | --- | --- |
45
- | Claude Code | Native rules, commands, agents, skills, MCP, hooks, ignore, permissions |
46
- | Cursor | Native rules, commands, agents, skills, MCP, hooks, ignore; partial permissions |
47
- | Copilot | Native rules, commands, agents, skills; partial hooks |
48
- | Continue | Native rules and MCP; commands via embedded invokable prompt rules; skills via embedded skill directories |
49
- | Junie | Partial rules via a single project guidelines file; embedded skills; native MCP and ignore |
50
- | Gemini CLI | Native rules, commands, skills, MCP, ignore; partial hooks; agents via projected skills |
51
- | Cline | Native rules, workflows-from-commands, skills, MCP, ignore; agents via projected skills |
52
- | Codex CLI | Native rules, skills, MCP; commands and agents via projected skills |
53
- | Windsurf | Native rules, workflows-from-commands, skills, ignore; agents via projected skills |
34
+ ```bash
35
+ # npm
36
+ npm install -D agentsmesh
54
37
 
55
- Embedded support is deliberate, not a hacky one-way export. For example, Codex commands are round-tripped through reserved skills, and projected agent-skills keep enough metadata for `import --from ...` to restore canonical agents instead of flattening them into plain skills.
38
+ # pnpm
39
+ pnpm add -D agentsmesh
56
40
 
57
- ## Install
41
+ # yarn
42
+ yarn add -D agentsmesh
58
43
 
59
- ```bash
60
- pnpm add -D agentsmesh
61
- # or
62
- npm install -D agentsmesh
44
+ # or run directly
45
+ npx agentsmesh --help
63
46
  ```
64
47
 
65
- Requires Node.js 20+. The CLI is available as `agentsmesh` and `agbr`.
48
+ The CLI is available as both `agentsmesh` and `amsh`.
49
+
50
+ ---
51
+
52
+ ## Quick Start
66
53
 
67
- ## Quick start
54
+ ### New project
68
55
 
69
56
  ```bash
70
- # create the canonical scaffold
57
+ # Scaffold the canonical config directory
71
58
  agentsmesh init
72
59
 
73
- # sync .agentsmesh/ to the configured targets
60
+ # Edit your root rule
61
+ # vi .agentsmesh/rules/_root.md
62
+
63
+ # Generate configs for all enabled targets
74
64
  agentsmesh generate
75
65
  ```
76
66
 
77
- If the repo already has tool-specific config, import it first:
67
+ ### Existing project with tool configs already in place
78
68
 
79
69
  ```bash
70
+ # Import your existing Cursor config (or any supported tool)
80
71
  agentsmesh import --from cursor
72
+
73
+ # Generate output for all configured targets
81
74
  agentsmesh generate
82
75
  ```
83
76
 
84
- ## Canonical layout
85
-
86
- ```text
87
- .agentsmesh/
88
- rules/_root.md
89
- rules/*.md
90
- commands/*.md
91
- agents/*.md
92
- skills/{name}/SKILL.md
93
- mcp.json
94
- permissions.yaml
95
- hooks.yaml
96
- ignore
97
- agentsmesh.yaml
98
- agentsmesh.local.yaml
99
- ```
77
+ That's it. Your `.agentsmesh/` directory is now the single source of truth, and the generated files for each tool stay in sync with it.
100
78
 
101
- What each part does:
102
-
103
- - `rules/`: shared instructions, including the required root rule, target scoping, globs, and optional trigger modes
104
- - `commands/`: reusable slash-command style prompts
105
- - `agents/`: custom subagents with tools, model, hooks, MCP, skills, and memory
106
- - `skills/`: skills plus supporting files
107
- - `mcp.json`: MCP server definitions
108
- - `permissions.yaml`: allow/deny lists
109
- - `hooks.yaml`: lifecycle hooks
110
- - `ignore`: shared ignore patterns
111
- - `agentsmesh.local.yaml`: local-only overrides that should not be committed
112
-
113
- ## CLI commands
114
-
115
- Global flags:
116
-
117
- - `--help`
118
- - `--version`
119
- - `--verbose`
120
-
121
- | Command | What it does | Supported flags |
122
- | --- | --- | --- |
123
- | `init` | Create `agentsmesh.yaml`, `.agentsmesh/`, `agentsmesh.local.yaml`, and update `.gitignore` | `--yes` |
124
- | `generate` | Generate target files from `.agentsmesh/` | `--targets`, `--dry-run`, `--check`, `--force`, `--refresh-cache`, `--no-cache` |
125
- | `import` | Import an existing tool config into `.agentsmesh/` | `--from` |
126
- | `install` | Install resources from a local/remote source and materialize them as packs or extends | `--sync`, `--dry-run`, `--force`, `--path`, `--target`, `--as`, `--name`, `--extends` |
127
- | `diff` | Show what the next `generate` would change without writing files | `--targets` |
128
- | `lint` | Validate canonical files against target constraints | `--targets` |
129
- | `watch` | Watch canonical files and regenerate on change | `--targets` |
130
- | `check` | Verify the canonical state still matches the lock file | none |
131
- | `merge` | Resolve `.agentsmesh/.lock` merge conflicts | none |
132
- | `matrix` | Show feature support for the current config | `--targets`, `--verbose` |
133
- | `help` | Show command help | n/a (also via global `--help`) |
134
- | `version` | Show CLI/library version | n/a (also via global `--version`) |
135
-
136
- Examples:
79
+ ---
137
80
 
138
- ```bash
139
- agentsmesh init --yes
140
- agentsmesh generate --targets cursor,claude-code
141
- agentsmesh generate --dry-run
142
- agentsmesh generate --check
143
- agentsmesh generate --refresh-cache
144
- agentsmesh import --from codex-cli
145
- agentsmesh install github:org/repo@main --path skills --as skills
146
- agentsmesh diff --targets windsurf
147
- agentsmesh lint
148
- agentsmesh watch
149
- agentsmesh check
150
- agentsmesh merge
151
- agentsmesh matrix --verbose
152
- agentsmesh --help
153
- agentsmesh --version
154
- ```
81
+ ## Supported Tools
155
82
 
156
- ## Features worth knowing about
157
-
158
- - `extends` can pull shared config from a local folder, GitHub release, GitLab repo, or generic git remote
159
- - `agentsmesh.local.yaml` lets one developer narrow targets or disable conversions without changing the shared project config
160
- - Conversion controls let you turn off projected command-to-skill or agent-to-skill mappings per target
161
- - `watch` ignores its own lock-file writes, so generation does not loop on itself
162
- - `check` and `merge` are built for team workflows, not just solo local use
163
-
164
- Example `extends` config:
165
-
166
- ```yaml
167
- extends:
168
- - source: ../shared-ai-config
169
- features: [rules, commands]
170
- - source: github:my-org/ai-config@v1.0.0
171
- features: [rules, permissions]
172
- - source: gitlab:team/platform/ai-config@v2.3.1
173
- features: [rules]
174
- - source: git+ssh://git@git.example.com/platform/ai-config.git#main
175
- features: [rules, commands, permissions]
176
- ```
83
+ | Feature | Claude Code | Cursor | Copilot | Gemini CLI | Cline | Codex CLI | Windsurf | Continue | Junie |
84
+ |---------------|:-----------:|:-------:|:-------:|:----------:|:-------:|:---------:|:--------:|:--------:|:--------:|
85
+ | Rules | Native | Native | Native | Native | Native | Native | Native | Native | Native |
86
+ | Commands | Native | Native | Native | Native | Native | Embedded | Native | Embedded | Embedded |
87
+ | Agents | Native | Native | Native | Native | Embedded| Native | Embedded | -- | Embedded |
88
+ | Skills | Native | Native | Native | Native | Native | Native | Native | Embedded | Embedded |
89
+ | MCP Servers | Native | Native | -- | Native | Native | Native | Partial | Native | Native |
90
+ | Hooks | Native | Native | Partial | Partial | -- | -- | Native | -- | -- |
91
+ | Ignore | Native | Native | -- | Native | Native | -- | Native | -- | Native |
92
+ | Permissions | Native | Partial | -- | Partial | -- | -- | -- | -- | -- |
177
93
 
178
- ## Roadmap
94
+ See the [full feature matrix docs](https://samplexbro.github.io/agentsmesh/reference/supported-tools/) for details on native vs. embedded support.
179
95
 
180
- This section is planned work, not current functionality.
96
+ ---
181
97
 
182
- ### Tier 1
98
+ ## Documentation
183
99
 
184
- - Global mode for user-level config outside a single repo
185
- - Programmatic API for `generate`, `lint`, and `diff`
186
- - More targets: Roo Code, Kilo Code, Goose, Kiro, OpenCode, Factory Droid, Google Antigravity
187
- - Homebrew distribution and a single binary build
188
- - `--json` output on command results
189
- - Dedicated `.gitignore` command
190
- - MCP server so agents can inspect and manage their own config
100
+ The documentation site covers everything in detail:
191
101
 
192
- ### Tier 2
102
+ - **[Getting Started](https://samplexbro.github.io/agentsmesh/getting-started/installation/)** -- installation, quick start
103
+ - **[Canonical Config](https://samplexbro.github.io/agentsmesh/canonical-config/)** -- rules, commands, agents, skills, MCP, hooks, ignore, permissions
104
+ - **[CLI Reference](https://samplexbro.github.io/agentsmesh/cli/)** -- all commands: init, generate, import, install, diff, lint, watch, check, merge, matrix
105
+ - **[Configuration](https://samplexbro.github.io/agentsmesh/configuration/agentsmesh-yaml/)** -- agentsmesh.yaml, local overrides, extends, collaboration, conversions
106
+ - **[Guides](https://samplexbro.github.io/agentsmesh/guides/existing-project/)** -- adopting in existing projects, multi-tool teams, sharing config, CI drift detection, community packs
107
+ - **[Reference](https://samplexbro.github.io/agentsmesh/reference/generation-pipeline/)** -- how the generation pipeline works
193
108
 
194
- - `.gitattributes` auto-generation for generated files
195
- - `convert` for direct tool-to-tool conversion
196
- - Ephemeral generation mode (`--stdout`, temp output)
197
- - Plugin system for custom targets
198
- - JSON Schema for `agentsmesh.yaml`
109
+ ---
199
110
 
200
- ### Tier 3
111
+ ## Roadmap
201
112
 
202
- - Community registry for shared rule sets and configs
203
- - `migrate --from <tool>` for zero-friction imports from other AI config tools
204
- - IDE extension for VS Code and JetBrains
113
+ See [ROADMAP.md](ROADMAP.md) for planned features and release timeline.
205
114
 
206
- ## Development commands
115
+ ---
116
+
117
+ ## Contributing
118
+
119
+ Contributions are welcome. Keep changes small, test them, and prefer editing canonical `.agentsmesh/` sources over generated files.
207
120
 
208
121
  ```bash
122
+ pnpm install
209
123
  pnpm build
210
124
  pnpm test
211
- pnpm test:watch
212
- pnpm test:coverage
213
- pnpm test:e2e
214
125
  pnpm lint
215
126
  pnpm typecheck
216
- pnpm format
217
- pnpm format:check
218
127
  ```
219
128
 
220
- ## Contributing
129
+ ---
130
+
131
+ ## License
221
132
 
222
- Keep changes small, verify them, and prefer updating the canonical `.agentsmesh/` source over editing generated target files by hand.
133
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agentsmesh",
3
- "version": "0.2.4",
3
+ "version": "0.2.6",
4
4
  "description": "One canonical source for AI coding agent rules, commands, skills, MCP, hooks, and permissions — synced across Claude Code, Cursor, Copilot, Continue, Junie, Gemini CLI, Cline, Codex CLI, and Windsurf.",
5
5
  "type": "module",
6
6
  "main": "./dist/cli.js",