@agents-dev/cli 0.7.7

package/docs/EXAMPLES.md

@@ -0,0 +1,211 @@
+# Usage Examples
+
+Real-world scenarios.
+
+## Solo Developer
+
+**Scenario:** You use Cursor + Claude Code
+
+```bash
+cd ~/my-project
+agents start
+
+# Add MCP servers
+agents mcp add https://mcpservers.org/servers/context7-mcp
+agents mcp add https://mcpservers.org/servers/playwright-mcp
+
+# Sync
+agents sync
+```
+
+**Daily workflow:**
+```bash
+agents status        # Check sync status
+agents watch         # Auto-sync changes
+```
+
+---
+
+## Team Setup
+
+**Lead sets up:**
+```bash
+agents start
+agents connect --llm codex,claude,gemini
+
+# Add company MCP servers
+agents mcp add company-api \
+  --url "https://api.company.com/mcp" \
+  --secret-header "Authorization=Bearer {{API_TOKEN}}"
+
+# Commit
+git add .agents/ AGENTS.md
+git commit -m "Add agents config"
+git push
+```
+
+**New member onboards:**
+```bash
+git pull
+agents start  # Prompts for API_TOKEN
+# ✅ Done in 30 seconds
+```
+
+---
+
+## Multiple Projects
+
+**Project A (Frontend):**
+```bash
+cd ~/projects/frontend-app
+agents init
+agents connect --llm cursor
+agents mcp add eslint-mcp --command "npx eslint-mcp-server"
+agents sync
+```
+
+**Project B (Backend):**
+```bash
+cd ~/projects/api-server
+agents init
+agents connect --llm claude,gemini
+agents mcp add database-schema --command "db-mcp-server"
+agents sync
+```
+
+Each project has its own `.agents/` config. No conflicts.
+
+---
+
+## CI/CD Integration
+
+**.github/workflows/validate-agents.yml:**
+```yaml
+name: Validate Agents Config
+
+on:
+  pull_request:
+    paths:
+      - '.agents/**'
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm install -g @agents-dev/cli
+      - run: agents doctor
+      - run: agents mcp test --json
+      - run: agents sync --check
+```
+
+---
+
+## Monorepo
+
+**Root (company-wide servers):**
+```bash
+cd monorepo
+agents init
+agents mcp add company-auth --url "https://auth.company.com/mcp"
+```
+
+**Package (package-specific):**
+```bash
+cd packages/frontend
+agents init
+agents mcp add design-system --command "design-mcp-server"
+```
+
+**Result:** Inherit root config + add package-specific servers.
+
+---
+
+## Advanced MCP
+
+### Add complex server with secrets
+
+```bash
+agents mcp add complex-api \
+  --url "https://api.example.com/mcp" \
+  --secret-header "Authorization=Bearer {{OAUTH_TOKEN}}" \
+  --secret-header "X-API-Key={{API_KEY}}" \
+  --header "X-Client-Version=1.0.0"
+```
+
+Prompts for `OAUTH_TOKEN` and `API_KEY`. Stores in `.agents/local.json`.
+
+### Test before committing
+
+```bash
+# Add new server
+agents mcp add experimental --url "https://new-api.com/mcp"
+
+# Test
+agents mcp test experimental --runtime
+
+# If OK, commit
+git add .agents/agents.json
+git commit -m "Add experimental MCP"
+```
+
+### Target specific tool
+
+```bash
+# Claude-only server
+agents mcp add claude-artifacts \
+  --url "https://artifacts.anthropic.com/mcp" \
+  --target claude
+
+# Universal server
+agents mcp add context7 \
+  --url "https://context7.com/mcp"
+
+agents sync
+```
+
+**Result:**
+- Claude: `claude-artifacts` + `context7`
+- Cursor: `context7` only
+
+---
+
+## Scripting
+
+### Rotate MCP token daily
+
+```bash
+#!/bin/bash
+# rotate-mcp-token.sh
+
+NEW_TOKEN=$(curl -s https://auth.company.com/token)
+
+jq ".mcpServers.companyApi.env.API_TOKEN = \"$NEW_TOKEN\"" \
+  .agents/local.json > .agents/local.json.tmp
+mv .agents/local.json.tmp .agents/local.json
+
+agents sync
+```
+
+### Status in shell prompt
+
+Add to `.bashrc`:
+```bash
+agents_prompt() {
+  if [ -d ".agents" ]; then
+    STATUS=$(agents status --fast --json 2>/dev/null | jq -r '.status')
+    [ "$STATUS" = "synced" ] && echo " 🟢" || echo " 🟡"
+  fi
+}
+
+PS1='$(agents_prompt) '"$PS1"
+```
+
+---
+
+## More Examples?
+
+[Open a discussion](https://github.com/amtiYo/agents/discussions) and share your workflow!

package/docs/README.md

@@ -0,0 +1,26 @@
+# Documentation
+
+## Available Docs
+
+| Document | Description |
+|:---------|:------------|
+| [Usage Examples](EXAMPLES.md) | Real-world scenarios |
+| [System Design](agents-system.md) | Technical architecture |
+
+## External Resources
+
+### Standards
+- [AGENTS.md](https://agents.md)
+- [Model Context Protocol](https://modelcontextprotocol.io)
+
+### Tools
+- [Codex](https://developers.openai.com/codex) | [Claude Code](https://code.claude.com/docs) | [Gemini CLI](https://geminicli.com/docs)
+- [Cursor](https://cursor.com/docs) | [Copilot](https://github.com/features/copilot) | [Antigravity](https://antigravity.google/docs)
+
+## Contributing
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md)
+
+---
+
+**Questions?** [Issues](https://github.com/amtiYo/agents/issues) | [Discussions](https://github.com/amtiYo/agents/discussions)

package/docs/agents-system.md

@@ -0,0 +1,178 @@
+# System Architecture
+
+Technical blueprint for advanced users.
+
+## Problem
+
+| Issue | Impact |
+|:------|:-------|
+| Different instruction formats | `.cursorrules`, `CLAUDE.md`, `AGENTS.md` |
+| Different MCP configs | TOML, JSON, different schemas |
+| Different skill packaging | Incompatible formats |
+
+**Result:** Setup cost ↑, drift across teams ↑
+
+## Solution
+
+`agents` provides **one source of truth**:
+
+| Component | Purpose |
+|:----------|:--------|
+| `AGENTS.md` | Instructions (all tools) |
+| `.agents/agents.json` | MCP servers (shared) |
+| `.agents/local.json` | Secrets (gitignored) |
+| `.agents/skills/` | Reusable workflows |
+
+## Core Principles
+
+- ✅ Single source of truth in `.agents/`
+- ✅ Root `AGENTS.md` is canonical
+- ✅ One command setup: `agents start`
+- ✅ Deterministic sync to tool configs
+- ✅ Source-only git strategy (default)
+
+## File Structure
+
+```
+project/
+├── AGENTS.md                    # Instructions
+├── .agents/
+│   ├── agents.json             # MCP servers (committed)
+│   ├── local.json              # Secrets (gitignored)
+│   ├── skills/                 # Workflows
+│   └── generated/              # Auto-generated (gitignored)
+├── .codex/                     # Materialized (gitignored)
+├── .claude/                    # Materialized (gitignored)
+├── .cursor/                    # Materialized (gitignored)
+└── ...
+```
+
+## Command Flow
+
+| Command | What It Does |
+|:--------|:-------------|
+| `agents start` | Interactive setup + trust/approval confirmations |
+| `agents status` | Check connection status |
+| `agents doctor` | Validate configs |
+| `agents sync` | Generate tool-specific configs |
+| `agents watch` | Auto-sync on changes |
+| `agents mcp add <url>` | Add MCP server |
+| `agents mcp test --runtime` | Live connectivity check |
+
+## Integration Mapping
+
+| Tool | Generated Config |
+|:-----|:-----------------|
+| **Codex** | `.codex/config.toml` |
+| **Claude** | `claude mcp add -s local` (CLI) |
+| **Gemini** | `.gemini/settings.json` |
+| **Cursor** | `.cursor/mcp.json` + CLI enable |
+| **Copilot** | `.vscode/mcp.json` |
+| **Antigravity** | `.antigravity/mcp.json` |
+
+## VS Code Integration
+
+**Managed in `.vscode/settings.json`:**
+```json
+{
+  "files.exclude": {
+    "**/.codex": true,
+    "**/.claude": true,
+    "**/.cursor": true,
+    "**/.gemini": true,
+    "**/.antigravity": true,
+    "**/.agents/generated": true
+  }
+}
+```
+
+**State tracking:** `.agents/generated/vscode.settings.state.json`
+
+## Skills Sync
+
+| Tool | Location |
+|:-----|:---------|
+| **Source** | `.agents/skills/*/SKILL.md` |
+| **Codex** | Reads `.agents/skills/` directly |
+| **Claude** | Symlink to `.claude/skills/` |
+| **Cursor** | Symlink to `.cursor/skills/` |
+| **Gemini** | Symlink to `.gemini/skills/` |
+
+**Validation:** `agents doctor` checks frontmatter (`name`, `description`)
+
+## Reset Options
+
+| Command | Effect |
+|:--------|:-------|
+| `agents reset` | Remove generated files, keep `.agents/` |
+| `agents reset --local-only` | Remove tool configs only |
+| `agents reset --hard` | Remove everything (`.agents/`, `AGENTS.md`, gitignore entries) |
+
+## Security Model
+
+| Type | Storage |
+|:-----|:--------|
+| **Shared config** | `.agents/agents.json` (committed) |
+| **Secrets** | `.agents/local.json` (gitignored) |
+| **Validation** | Fail-fast on invalid env/header keys |
+
+**Rules:**
+- ❌ No secrets in git
+- ✅ Secrets in `.agents/local.json`
+- ✅ Strict key validation (shell-safe for env, HTTP token for headers)
+
+## Sync Process
+
+```
+1. Read .agents/agents.json
+2. Merge with .agents/local.json
+3. Generate tool-specific configs
+4. Write atomically (temp + rename)
+5. Acquire lock (prevent race conditions)
+```
+
+## MCP Server Format
+
+**stdio transport:**
+```json
+{
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["@modelcontextprotocol/server-filesystem", "/path"]
+}
+```
+
+**http/sse transport:**
+```json
+{
+  "transport": "http",
+  "url": "https://api.example.com/mcp"
+}
+```
+
+**With secrets:**
+```json
+{
+  "transport": "http",
+  "url": "https://api.example.com/mcp",
+  "env": {
+    "API_KEY": "{{API_KEY}}"  // Prompt for value
+  }
+}
+```
+
+## Git Strategy
+
+**Committed:**
+- ✅ `.agents/agents.json`
+- ✅ `.agents/skills/`
+- ✅ `AGENTS.md`
+
+**Gitignored:**
+- ❌ `.agents/local.json`
+- ❌ `.agents/generated/`
+- ❌ `.codex/`, `.claude/`, `.cursor/`, `.gemini/`, `.antigravity/`
+
+---
+
+**Deep dive?** See [AGENTS.md](../AGENTS.md) for implementation details.

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@agents-dev/cli",
+  "version": "0.7.7",
+  "description": "One config to rule them all — Practical standard layer for multi-LLM development. Sync MCP servers, skills, and AGENTS.md across Codex, Claude Code, Gemini CLI, Cursor, Copilot, and Antigravity.",
+  "main": "dist/cli.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli.ts",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "bin": {
+    "agents": "bin/agents"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "templates/",
+    "docs/",
+    "README.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agents",
+    "mcp",
+    "model-context-protocol",
+    "agents-md",
+    "codex",
+    "claude-code",
+    "gemini-cli",
+    "cursor",
+    "copilot",
+    "antigravity",
+    "ai-coding",
+    "llm-tools",
+    "config-sync",
+    "multi-llm",
+    "agentic-ai",
+    "cli"
+  ],
+  "author": "amtiYo",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/amtiYo/agents.git"
+  },
+  "bugs": {
+    "url": "https://github.com/amtiYo/agents/issues"
+  },
+  "homepage": "https://github.com/amtiYo/agents#readme",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.0.0",
+    "@iarna/toml": "^2.2.5",
+    "commander": "^14.0.3",
+    "jsonc-parser": "^3.3.1",
+    "picocolors": "^1.1.1",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.0",
+    "@types/prompts": "^2.4.9",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "eslint": "^9.39.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  }
+}

package/templates/agents/AGENTS.md

@@ -0,0 +1,23 @@
+## Mission
+Deliver correct, maintainable changes with minimal risk.
+
+## Scope
+- Respect repository architecture and conventions.
+- Keep edits focused; avoid unrelated refactors.
+- Never commit secrets.
+
+## Engineering Rules
+- Validate changes with relevant checks before final delivery.
+- Surface assumptions and edge cases explicitly.
+- Prefer reversible changes and deterministic outputs.
+
+## MCP & Skills
+- MCP server definitions: `.agents/agents.json`
+- Local MCP overrides/secrets: `.agents/local.json`
+- Project skills: `.agents/skills/*/SKILL.md`
+
+## Workflow
+1. Plan briefly.
+2. Implement minimal viable change.
+3. Validate (lint/tests/build/smoke as needed).
+4. Report results and residual risks.

package/templates/agents/README.md

@@ -0,0 +1,25 @@
+# .agents
+
+Project-local standard for AGENTS.md + MCP + SKILLS.
+
+## Source files (commit these)
+- `agents.json`: selected integrations + MCP servers + workspace behavior
+- `skills/*/SKILL.md`: project skills
+
+## Root instruction file
+- `../AGENTS.md`: canonical instruction document
+
+## Local/private files (do not commit)
+- `local.json`: machine-specific MCP overrides and secrets
+
+## Generated files
+- `generated/*`: renderer outputs used by `agents sync`
+- `generated/vscode.settings.state.json`: managed VS Code hide state
+
+## Common materialized outputs
+- `.codex/config.toml`
+- `.gemini/settings.json`
+- `.vscode/mcp.json`
+- `.vscode/settings.json`
+- `.cursor/mcp.json`
+- `.antigravity/mcp.json`

package/templates/agents/skills/README.md

@@ -0,0 +1,27 @@
+# Skills Folder
+
+This directory stores project skills used across supported LLM tools.
+
+## Skill structure
+Each skill must live in its own folder and contain `SKILL.md`:
+
+```text
+.agents/skills/<skill-id>/SKILL.md
+```
+
+## Minimal SKILL.md template
+```md
+---
+name: my-skill
+description: When this skill should be used.
+---
+
+Step-by-step instructions for the agent.
+```
+
+Keep skills narrow and reusable. Prefer one clear outcome per skill.
+
+## Recommended conventions
+- Directory name should match frontmatter `name`.
+- Use kebab-case for `name` (lowercase letters, numbers, `-`).
+- Keep `description` specific so tools can trigger the skill correctly.

package/templates/agents/skills/skill-guide/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: skill-guide
+description: Explain how to create, organize, and maintain skills in .agents/skills when the user asks about skills.
+---
+
+When asked about skills:
+
+1. Explain required structure:
+- One directory per skill under `.agents/skills`.
+- A required `SKILL.md` file with YAML frontmatter.
+
+2. Explain required frontmatter:
+- `name`: short unique identifier.
+- `description`: explicit trigger guidance for when the skill should be used.
+
+3. Provide a minimal starter template and ask for:
+- the task scope,
+- expected input/output,
+- success criteria.
+
+4. Recommend progressive disclosure:
+- keep `SKILL.md` concise,
+- put large references/examples in separate files.
+
+5. Suggest validation checklist:
+- clear trigger description,
+- deterministic steps,
+- no secrets in skill files,
+- tested with at least one real prompt.