diff --git a/AGENTS.md b/AGENTS.md index 424a418..f35ec8e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,14 +15,17 @@ See `specs/SPEC.md` for the full design. ``` src/ ├── index.ts # Library entry point +├── scope.ts # Project/user scope resolution ├── cli/ │ ├── index.ts # CLI entry point, command routing -│ └── commands/ # init, install, add, remove, update, sync, list +│ └── commands/ # init, install, add, remove, update, sync, list, mcp +├── agents/ # Agent definitions, MCP/hook config writers ├── config/ # agents.toml schema, loader, writer ├── lockfile/ # agents.lock schema, loader, writer ├── skills/ # SKILL.md loader, discovery, resolver ├── sources/ # git.ts, local.ts, cache.ts ├── symlinks/ # Symlink creation/management +├── trust/ # Trust policy validation ├── gitignore/ # .agents/.gitignore generation └── utils/ # exec.ts, hash.ts, fs.ts ``` @@ -53,6 +56,10 @@ New functionality requires tests, but only tests that are functionally additive. - Add regression tests for bugs - Mock external services, use real-world fixtures +## Documentation + +When changes affect CLI behavior, command interfaces, or user-facing semantics (flags, error messages, default behavior), update the relevant documentation: `README.md`, `specs/SPEC.md`, `docs/public/llms.txt`, and `--help` output. Code and docs ship together. + ## Verifying Changes ```bash diff --git a/README.md b/README.md index 483fa17..a932d9b 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ A package manager for `.agents` directories. Declare agent skill dependencies in **Shareable.** Skills are just directories with a `SKILL.md`. Host them in any git repo, discover them automatically, install with one command. -**Multi-agent.** Configure Claude, Cursor, Codex, VS Code, and OpenCode from a single `agents.toml` -- skills, MCP servers, and hooks. +**Multi-agent.** Configure Claude, Cursor, Codex, VS Code, OpenCode, and Pi from a single `agents.toml` -- skills, MCP servers, and hooks. ## Quick Start @@ -19,7 +19,10 @@ A package manager for `.agents` directories. Declare agent skill dependencies in npx @sentry/dotagents init # Add a skill from a GitHub repo -npx @sentry/dotagents add getsentry/skills --name find-bugs +npx @sentry/dotagents add getsentry/skills find-bugs + +# Add multiple skills at once +npx @sentry/dotagents add getsentry/skills find-bugs code-review commit # Or add all skills from a repo npx @sentry/dotagents add getsentry/skills --all @@ -47,12 +50,13 @@ And a lockfile (`agents.lock`) pinning the exact commit and integrity hash. | Command | Description | |---------|-------------| | `init` | Create `agents.toml` and `.agents/skills/` | -| `add ` | Add a skill dependency | +| `add [skills...]` | Add skill dependencies | | `remove ` | Remove a skill | | `install` | Install all dependencies from `agents.toml` | | `update [name]` | Update skills to latest versions | | `list` | Show installed skills and their status | | `sync` | Reconcile gitignore, symlinks, and verify state | +| `mcp` | Manage MCP server declarations | All commands accept `--user` to operate on user scope (`~/.agents/`) instead of the current project. @@ -75,10 +79,31 @@ Use `--frozen` in CI to fail if the lockfile is missing or out of sync. Use `--f ### add ```bash -dotagents add [--name ] [--ref ] [--all] +dotagents add [...] [--skill ...] [--ref ] [--all] +``` + +Add one or more skills and install them. Specify skill names as positional arguments or with `--skill` flags. + +```bash +# Add a single skill +dotagents add getsentry/skills find-bugs + +# Add multiple skills +dotagents add getsentry/skills find-bugs code-review commit + +# Equivalent using --skill flags +dotagents add getsentry/skills --skill find-bugs --skill code-review + +# Pin to a ref +dotagents add getsentry/skills find-bugs --ref v1.0.0 + +# Add all skills as a wildcard entry +dotagents add getsentry/skills --all ``` -Add a skill and install it. When a repo has one skill, it's added automatically. When multiple are found, use `--name` to pick one or `--all` to add them all as a wildcard entry. +When a repo has one skill, it's added automatically. When multiple are found and no names are given, interactive mode shows a picker. + +When adding multiple skills, any that already exist in `agents.toml` are skipped with a warning. The rest are added normally. ### remove @@ -112,6 +137,24 @@ dotagents sync Adopts orphaned skills, regenerates gitignore, verifies integrity, repairs symlinks and configs. +### mcp + +Manage MCP server declarations from the CLI. + +```bash +# Add a stdio server +dotagents mcp add github --command npx --args -y @modelcontextprotocol/server-github --env GITHUB_TOKEN + +# Add an HTTP server +dotagents mcp add remote-api --url https://mcp.example.com/sse + +# Remove a server +dotagents mcp remove github + +# List declared servers +dotagents mcp list [--json] +``` + ## Source Formats ```toml @@ -163,16 +206,7 @@ agents = ["claude", "cursor"] ### Pi -[Pi](https://github.com/badlogic/pi-mono) discovers skills from `.pi/skills/`. It is not listed as an `agents` target, so instead add a symlink target to your `agents.toml`: - -```toml -[symlinks] -targets = [".pi"] -``` - -After running `dotagents install`, Pi will read skills from `.pi/skills/ -> .agents/skills/`. - -Pi does not use dotagents for MCP configuration. If you use an MCP extension with Pi, configure it separately via `.pi/mcp.json`. +[Pi](https://github.com/badlogic/pi-mono) reads `.agents/skills/` natively. No agent target or symlink configuration is needed -- install skills with dotagents and Pi picks them up automatically. ## MCP Servers @@ -186,7 +220,7 @@ command = "npx" args = ["-y", "@modelcontextprotocol/server-github"] env = ["GITHUB_TOKEN"] -# HTTP transport (OAuth) +# HTTP transport [[mcp]] name = "remote-api" url = "https://mcp.example.com/sse" @@ -194,6 +228,8 @@ url = "https://mcp.example.com/sse" Each server uses either `command` (stdio) or `url` (HTTP), not both. +You can also manage MCP servers from the CLI with `dotagents mcp add` and `dotagents mcp remove`. + ## Hooks Declare hooks once and dotagents writes the correct hook config for each agent that supports them (Claude, Cursor, VS Code). diff --git a/docs/public/llms.txt b/docs/public/llms.txt index 3091aa3..d0ff2dd 100644 --- a/docs/public/llms.txt +++ b/docs/public/llms.txt @@ -14,7 +14,10 @@ Run without installing: `npx @sentry/dotagents ` npx @sentry/dotagents init # Add a single skill from GitHub -npx @sentry/dotagents add getsentry/skills --name find-bugs +npx @sentry/dotagents add getsentry/skills find-bugs + +# Add multiple skills at once +npx @sentry/dotagents add getsentry/skills find-bugs code-review commit # Add all skills from a repo npx @sentry/dotagents add getsentry/skills --all @@ -247,18 +250,21 @@ Install all dependencies from `agents.toml`. Resolves sources, copies skills, wr ### add ``` -dotagents add [--name ] [--ref ] [--all] +dotagents add [...] [--skill ...] [--ref ] [--all] ``` -Add a skill dependency and install it. Auto-discovers skills in the repo. +Add one or more skill dependencies and install them. Specify skill names as positional arguments or with `--skill` flags. | Flag | Description | |------|-------------| -| `--name ` | Specify which skill to add (alias: `--skill`) | +| `...` | Positional skill names to add | +| `--skill ` | Specify which skill(s) to add (repeatable, alias: `--name`) | | `--ref ` | Pin to a specific tag, branch, or commit | | `--all` | Add all skills from the source as a wildcard entry (`name = "*"`) | -When a repo has one skill, it is added automatically. When multiple skills are found without `--name` or `--all`, they are listed with instructions to pick one. +When a repo has one skill, it is added automatically. When multiple skills are found without names or `--all`, interactive mode shows a picker (TTY) or lists them (non-TTY). + +When adding multiple skills, any that already exist in `agents.toml` are skipped with a warning. The command only fails if all specified skills already exist. Positional names and `--skill` flags cannot be mixed. ### remove @@ -344,7 +350,9 @@ Skills from wildcard entries are marked with a wildcard indicator. | `vscode` | VS Code Copilot | `.vscode` | (reads `.agents/skills/` natively) | `.vscode/mcp.json` | `.claude/settings.json` | | `opencode` | OpenCode | `.claude` | (reads `.agents/skills/` natively) | `opencode.json` | Not supported | -Claude and Cursor use symlinks from their config directory to `.agents/skills/`. Codex, VS Code, and OpenCode read `.agents/skills/` directly. +Claude and Cursor use symlinks from their config directory to `.agents/skills/`. Codex, VS Code, OpenCode, and Pi read `.agents/skills/` directly. + +[Pi](https://github.com/badlogic/pi-mono) reads `.agents/skills/` natively. No agent target or symlink configuration needed. ## Scopes diff --git a/specs/SPEC.md b/specs/SPEC.md index 01c3884..982e7fb 100644 --- a/specs/SPEC.md +++ b/specs/SPEC.md @@ -149,6 +149,16 @@ MCP server declarations. Each entry defines an MCP server that dotagents will co A server must have either `command` (stdio) or `url` (HTTP), but not both. +#### `[[hooks]]` + +Hook declarations. Each entry defines a hook that dotagents will configure for agents that support hooks (Claude, Cursor, VS Code). + +| Field | Required | Description | +|-------|----------|-------------| +| `event` | Yes | Hook event: `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, or `Stop`. | +| `matcher` | No | Tool name to match (e.g. `Bash`). Only for `PreToolUse` and `PostToolUse`. | +| `command` | Yes | Shell command to execute when the hook fires. | + #### Supported Agents | ID | Tool | Config Dir | MCP File | MCP Format | @@ -344,34 +354,43 @@ dotagents install [--frozen] [--force] ### `dotagents add ` -Add a skill dependency. +Add one or more skill dependencies. ``` -dotagents add [--ref ] [--name ] +dotagents add [...] [--skill ...] [--ref ] [--all] ``` **Examples:** ```bash -dotagents add getsentry/skills --name find-bugs -dotagents add getsentry/warden --name warden-skill --ref v1.0.0 +dotagents add getsentry/skills find-bugs +dotagents add getsentry/skills find-bugs code-review commit +dotagents add getsentry/skills --skill find-bugs --skill code-review +dotagents add getsentry/warden warden-skill --ref v1.0.0 +dotagents add getsentry/skills --all dotagents add path:../shared-skills/my-skill dotagents add myorg/single-skill-repo # auto-detects if repo has one skill ``` **Behavior:** -1. Parse specifier to determine source type -2. Clone/fetch repo to cache -3. Discover skill(s) in the repo - - If `--name` is given, look for that specific skill +1. Validate source against trust policy before any network operations +2. Parse specifier to determine source type +3. Clone/fetch repo to cache +4. Discover skill(s) in the repo + - If skill names are given (positional or `--skill`), verify each exists in the source + - If `--all`, add a wildcard entry for the entire source - If repo has exactly one skill, use it automatically - - If repo has multiple skills and no `--name`, list them and ask user to pick -4. Add `[[skills]]` entry to `agents.toml` -5. Run install to fetch and place the skill -6. Update `agents.lock` + - If repo has multiple skills and no names given, show interactive picker (TTY) or list them (non-TTY) +5. When adding multiple skills, skip any that already exist in `agents.toml` (with a warning). Error only if all specified skills already exist. +6. Add `[[skills]]` entry to `agents.toml` for each new skill +7. Run install to fetch and place the skills +8. Update `agents.lock` **Flags:** - `--ref `: Pin to a specific tag/branch/commit -- `--name `: Specify which skill to add from a multi-skill repo +- `--skill ` (repeatable): Specify which skill(s) to add. Alternative to positional arguments. +- `--all`: Add all skills from the source as a wildcard entry + +Positional skill names and `--skill` flags cannot be mixed. ### `dotagents remove ` @@ -414,12 +433,29 @@ dotagents sync ``` **Behavior:** -1. Regenerate `.agents/.gitignore` -2. Create/verify/repair symlinks (legacy and agent-specific) -3. Warn if orphaned skills exist (installed but not in agents.toml) -4. Warn if declared skills are missing (in agents.toml but not installed) -5. Verify integrity hashes, warn on local modifications +1. Adopt orphaned skills (installed but not in `agents.toml`) into config +2. Regenerate `.agents/.gitignore` +3. Check for missing skills (in `agents.toml` but not installed) +4. Verify integrity hashes, warn on local modifications +5. Create/verify/repair symlinks 6. Verify and repair MCP config files for declared agents +7. Verify and repair hook config files for declared agents + +### `dotagents mcp` + +Manage MCP server declarations. + +``` +dotagents mcp add --command [--args ...] [--env ...] +dotagents mcp add --url [--header ...] [--env ...] +dotagents mcp remove +dotagents mcp list [--json] +``` + +**Behavior:** +- `add`: Append an `[[mcp]]` entry to `agents.toml` and run install to generate agent configs. Each server uses either `--command` (stdio) or `--url` (HTTP), not both. +- `remove`: Remove the named `[[mcp]]` entry from `agents.toml` and run install. +- `list`: Show declared MCP servers with transport type, target, and environment variables. ### `dotagents list` @@ -588,6 +624,7 @@ dotagents/ SPEC.md # This file src/ index.ts # Library entry point (re-exports all modules) + scope.ts # Project/user scope resolution cli/ index.ts # CLI entry point, command routing commands/ @@ -598,15 +635,20 @@ dotagents/ update.ts sync.ts list.ts + mcp.ts agents/ types.ts # McpDeclaration, AgentDefinition interfaces registry.ts # Agent registry (claude, cursor, codex, vscode, opencode) + definitions/ # Per-agent definitions (claude.ts, cursor.ts, etc.) mcp-writer.ts # MCP config file generation per agent + hook-writer.ts # Hook config file generation per agent + paths.ts # Agent config path resolution + errors.ts # Agent-specific error types index.ts # Re-exports config/ schema.ts # Zod schemas for agents.toml loader.ts # TOML parse + validate - writer.ts # TOML modification (add/remove skills) + writer.ts # TOML modification (add/remove skills, MCP, hooks) index.ts # Re-exports lockfile/ schema.ts # Zod schemas for agents.lock @@ -626,6 +668,9 @@ dotagents/ symlinks/ manager.ts # Create/verify/repair symlinks, directory migration index.ts # Re-exports + trust/ + validator.ts # Trust policy enforcement + index.ts # Re-exports gitignore/ writer.ts # Generate .agents/.gitignore index.ts # Re-exports @@ -645,6 +690,7 @@ dotagents/ | `smol-toml` | TOML parsing and serialization | | `zod` | Runtime schema validation (v4, imported as `zod/v4`) | | `chalk` | Terminal colors | +| `@clack/prompts` | Interactive CLI prompts | ### Dev