@joehom/awm-cli 0.0.1

package/src/commands/tool.js

@@ -0,0 +1,45 @@
+import { Command } from 'commander';
+import inquirer from 'inquirer';
+import { log } from '../utils/logger.js';
+import { listTools } from '../registry/toolRegistry.js';
+import { readWorkspace, writeWorkspace } from '../workspace/workspaceConfig.js';
+import { applyAll } from '../workspace/applyWorkspace.js';
+
+export function makeToolCommand() {
+  return new Command('tool')
+    .description('Select which tools this workspace targets, then resync MCPs and skills')
+    .action(async () => {
+      const allTools = listTools();
+      if (allTools.length === 0) throw new Error('No tool definitions found');
+
+      const ws = readWorkspace();
+      const currentTools = ws?.tools ?? [];
+
+      let answer;
+      try {
+        answer = await inquirer.prompt([{
+          type: 'checkbox',
+          name: 'tools',
+          message: 'Select tools for this workspace (space to toggle, enter to confirm):',
+          choices: allTools.map(id => ({ name: id, value: id, checked: currentTools.includes(id) })),
+          validate: v => v.length > 0 || 'Select at least one tool',
+        }]);
+      } catch (err) {
+        if (err.name === 'ExitPromptError') {
+          log.info('Cancelled.');
+          return;
+        }
+        throw err;
+      }
+
+      const updated = { ...(ws ?? { mcps: [], skills: [] }), tools: answer.tools };
+      writeWorkspace(updated);
+
+      if (updated.mcps.length > 0 || updated.skills.length > 0) {
+        log.info('Resyncing MCPs and skills to updated tool list...');
+        await applyAll(updated);
+      }
+
+      log.success(`Tools updated: ${answer.tools.join(', ')}`);
+    });
+}

package/src/defaults/mcps/fetch.json

@@ -0,0 +1,6 @@
+{
+  "id": "fetch",
+  "transport": "stdio",
+  "command": "uvx",
+  "args": ["mcp-server-fetch"]
+}

package/src/defaults/mcps/filesystem.json

@@ -0,0 +1,6 @@
+{
+  "id": "filesystem",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-filesystem", "${env:HOME}"]
+}

package/src/defaults/mcps/github.json

@@ -0,0 +1,9 @@
+{
+  "id": "github",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-github"],
+  "env": {
+    "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_TOKEN}"
+  }
+}

package/src/defaults/mcps/memory.json

@@ -0,0 +1,6 @@
+{
+  "id": "memory",
+  "transport": "stdio",
+  "command": "npx",
+  "args": ["-y", "@modelcontextprotocol/server-memory"]
+}

package/src/defaults/skills/awm-cli/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: awm-cli
+description: Use when the user asks to manage MCP servers, skills, or workspace configs for AI coding tools (Claude Code, Cursor, Codex, Copilot CLI, Gemini CLI, Windsurf, GitHub Copilot) using the awm CLI. Triggers on requests to register MCPs, add MCPs/skills to a project, import configs, or check registry health.
+---
+
+# AWM — Agent Workspace Manager CLI
+
+## Overview
+
+AWM is a local-first CLI that keeps a central registry of MCP servers and skills at `~/.agent-workspace/registry/`, then writes the correct config files into projects for supported AI tools.
+
+**Core pattern:** Register once → add to workspace → auto-applied to all tools.
+
+```
+awm init                           # create .awm.json in project root
+awm mcp add                        # pick MCPs from registry → apply to all tools
+awm skill add                      # pick skills from registry → apply to all tools
+```
+
+---
+
+## RULES — Follow These Before Running Any Command
+
+**ALWAYS ask before acting. Never assume.**
+
+1. **Check existing state first** — Run `awm status` if `.awm.json` exists, and `awm mcp list -g` / `awm skill list -g` to see what's in the registry. Do not recreate things that already exist.
+
+2. **Only add what the user explicitly requested** — If the user says "add fetch and memory", add ONLY fetch and memory. Do not add other MCPs or skills, even if they exist in the registry.
+
+3. **Confirm the plan before running** — Before executing any sequence of commands, show the user what you are about to do:
+   ```
+   I will run:
+     awm init                  (creates .awm.json, you pick tools)
+     awm mcp add               (you pick: fetch, memory)
+   Proceed?
+   ```
+
+4. **Run `awm init` only once per project** — It creates `.awm.json`. If it already exists, use `awm status` instead.
+
+5. **`mcp add` and `skill add` auto-apply** — After selection, MCPs and skills are immediately written to all tool config files in the project.
+
+---
+
+## Quick Reference
+
+### Workspace commands
+
+| Command | What it does |
+|---------|-------------|
+| `awm init` | Interactive: pick tools → create `.awm.json` in cwd |
+| `awm status` | Show current project tools, MCPs, skills, lastSync |
+| `awm doctor` | Validate registry + `.awm.json` health |
+
+### MCP commands
+
+| Command | What it does |
+|---------|-------------|
+| `awm mcp register [id]` | Interactive prompt → save MCP to global registry |
+| `awm mcp unregister <id>` | Remove MCP from global registry |
+| `awm mcp import` | Scan cwd tool config files → register found MCPs |
+| `awm mcp add` | Checkbox from registry → add to `.awm.json` + apply to tools |
+| `awm mcp delete <id>` | Remove MCP from `.awm.json` + re-apply tools |
+| `awm mcp list` | List MCPs in current workspace |
+| `awm mcp list -g` | List all MCPs in global registry |
+| `awm mcp show <id>` | Print full MCP definition |
+
+### Skill commands
+
+| Command | What it does |
+|---------|-------------|
+| `awm skill register <name> --from <path>` | Copy dir/file into global registry |
+| `awm skill unregister <name>` | Remove skill from global registry |
+| `awm skill import` | Scan `.claude/skills/`, `.agents/skills/` → register found skills |
+| `awm skill add` | Checkbox from registry → add to `.awm.json` + apply to tools |
+| `awm skill delete <name>` | Remove skill from `.awm.json` |
+| `awm skill list` | List skills in current workspace |
+| `awm skill list -g` | List all skills in global registry |
+| `awm skill show <name>` | Print SKILL.md |
+
+### Other commands
+
+| Command | What it does |
+|---------|-------------|
+| `awm tool list` | List known tool IDs |
+| `awm tool show <id>` | Print tool definition JSON |
+| `awm setup [--force]` | Re-seed default MCPs and skills into registry |
+
+---
+
+## Common Workflows
+
+### Set up a new project
+
+```bash
+# 1. Check registry state
+awm mcp list -g
+awm skill list -g
+
+# 2. Initialize workspace (interactive: pick tools)
+awm init
+
+# 3. Add ONLY the MCPs the user requested
+awm mcp add        # checkbox → select fetch, memory (if user asked)
+
+# 4. Add ONLY the skills the user requested
+awm skill add      # checkbox → select awm-cli (if user asked)
+
+# 5. Verify
+awm status
+cat .awm.json
+```
+
+### Register a new MCP from a file
+
+To register an MCP defined in a JSON file, use `mcp register` interactively, or import existing tool configs:
+
+```bash
+awm mcp import     # scans .mcp.json, .cursor/mcp.json, .gemini/settings.json, etc.
+```
+
+### Register a skill
+
+```bash
+# From a directory (must contain SKILL.md)
+awm skill register clean-arch --from ./skills/clean-arch/
+
+# From a single markdown file
+awm skill register tdd --from ./TDD.md
+```
+
+---
+
+## Workspace Config — `.awm.json`
+
+Created by `awm init` at the project root:
+
+```json
+{
+  "tools": ["claude-code", "cursor", "windsurf"],
+  "mcps": ["fetch", "memory"],
+  "skills": ["awm-cli"],
+  "lastSync": "2026-03-08T12:00:00Z"
+}
+```
+
+- **`tools`** — which AI tools to write configs for in this project
+- **`mcps`** — MCP IDs from the global registry active in this project
+- **`skills`** — skill names from the global registry active in this project
+- **`lastSync`** — timestamp of last `mcp add` or `skill add` apply
+
+---
+
+## Apply Output by Tool
+
+| Tool | MCP file | Format | Skills |
+|------|----------|--------|--------|
+| `claude-code` | `.mcp.json` | JSON | `.claude/skills/<name>/` |
+| `codex` | `.codex/config.toml` | TOML | — |
+| `cursor` | `.cursor/mcp.json` | JSON | — |
+| `gemini-cli` | `.gemini/settings.json` | JSON | — |
+| `github-copilot` | `.vscode/mcp.json` | JSON (`servers`) | — |
+| `windsurf` | — | — | — |
+| `copilot-cli` | — | — | — |
+
+Notes:
+- **claude-code** is the only tool that supports skills.
+- **Merge-safe writes** — `mcp add` only touches the MCP root key. All other keys in tool config files are preserved.
+- **Env passthrough** — `${env:VAR}` values are written verbatim; the target tool resolves them at runtime.
+
+---
+
+## Default MCPs (pre-installed)
+
+| ID | Command | Notes |
+|----|---------|-------|
+| `github` | `npx -y @modelcontextprotocol/server-github` | Needs `GITHUB_TOKEN` env var |
+| `filesystem` | `npx -y @modelcontextprotocol/server-filesystem` | Local file access |
+| `memory` | `npx -y @modelcontextprotocol/server-memory` | Persistent knowledge graph |
+| `fetch` | `uvx mcp-server-fetch` | Web fetching (requires `uv`) |
+
+---
+
+## Environment Variable Override
+
+```bash
+AWM_REGISTRY=/path/to/registry awm mcp list -g
+```
+
+Default registry: `~/.agent-workspace/registry/`

package/src/defaults/tools/claude-code.json

@@ -0,0 +1,27 @@
+{
+  "id": "claude-code",
+  "name": "Claude Code",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "project": {
+      "targetFile": ".mcp.json",
+      "rootObject": "mcpServers"
+    },
+    "global": {
+      "targetFile": "~/.claude.json",
+      "rootObject": "mcpServers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".claude/skills"
+    },
+    "global": {
+      "targetFolder": "~/.claude/skills"
+    }
+  }
+}

package/src/defaults/tools/codex.json

@@ -0,0 +1,27 @@
+{
+  "id": "codex",
+  "name": "Codex CLI",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "toml",
+    "project": {
+      "targetFile": ".codex/config.toml",
+      "rootObject": "mcp_servers"
+    },
+    "global": {
+      "targetFile": "~/.codex/config.toml",
+      "rootObject": "mcp_servers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".agents/skills"
+    },
+    "global": {
+      "targetFolder": "~/.agents/skills"
+    }
+  }
+}

package/src/defaults/tools/copilot-cli.json

@@ -0,0 +1,18 @@
+{
+  "id": "copilot-cli",
+  "name": "Copilot CLI",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "global": {
+      "targetFile": "~/.copilot/mcp-config.json",
+      "rootObject": "servers"
+    }
+  },
+  "skills": {
+    "global": "~/.copilot/skills"
+  }
+}

package/src/defaults/tools/cursor.json

@@ -0,0 +1,27 @@
+{
+  "id": "cursor",
+  "name": "Cursor",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "project": {
+      "targetFile": ".cursor/mcp.json",
+      "rootObject": "mcpServers"
+    },
+    "global": {
+      "targetFile": "~/.cursor/mcp.json",
+      "rootObject": "mcpServers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".cursor/rules"
+    },
+    "global": {
+      "targetFolder": "~/.cursor/rules"
+    }
+  }
+}

package/src/defaults/tools/gemini-cli.json

@@ -0,0 +1,27 @@
+{
+  "id": "gemini-cli",
+  "name": "Gemini CLI",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "project": {
+      "targetFile": ".gemini/settings.json",
+      "rootObject": "mcpServers"
+    },
+    "global": {
+      "targetFile": "~/.gemini/settings.json",
+      "rootObject": "mcpServers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".gemini/skills"
+    },
+    "global": {
+      "targetFolder": "~/.gemini/skills"
+    }
+  }
+}

package/src/defaults/tools/github-copilot.json

@@ -0,0 +1,23 @@
+{
+  "id": "github-copilot",
+  "name": "GitHub Copilot (VS Code)",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "project": {
+      "targetFile": ".vscode/mcp.json",
+      "rootObject": "servers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".github/skills"
+    },
+    "global": {
+      "targetFolder": "~/.copilot/skills"
+    }
+  }
+}

package/src/defaults/tools/windsurf.json

@@ -0,0 +1,23 @@
+{
+  "id": "windsurf",
+  "name": "Windsurf",
+  "supports": {
+    "mcp": true,
+    "skills": true
+  },
+  "mcp": {
+    "format": "json",
+    "global": {
+      "targetFile": "~/.codeium/windsurf/mcp_config.json",
+      "rootObject": "mcpServers"
+    }
+  },
+  "skills": {
+    "project": {
+      "targetFolder": ".windsurf/skills"
+    },
+    "global": {
+      "targetFolder": "~/.codeium/windsurf/skills"
+    }
+  }
+}

package/src/index.js

@@ -0,0 +1,35 @@
+import { Command } from 'commander';
+import { ensureRegistryDirs } from './registry/paths.js';
+import { log } from './utils/logger.js';
+import { makeMcpCommand } from './commands/mcp.js';
+import { makeSkillCommand } from './commands/skill.js';
+import { makeInitCommand } from './commands/init.js';
+import { makePullCommand } from './commands/pull.js';
+import { makeStatusCommand } from './commands/status.js';
+import { makeDoctorCommand } from './commands/doctor.js';
+import { makeToolCommand } from './commands/tool.js';
+import { makeSetupCommand } from './commands/setup.js';
+
+const program = new Command();
+
+program
+  .name('awm')
+  .description('Agent Workspace Manager — manage MCP servers, skills, and workspace configs for AI coding tools')
+  .version('1.0.0');
+
+program.addCommand(makeInitCommand());
+program.addCommand(makePullCommand());
+program.addCommand(makeStatusCommand());
+program.addCommand(makeMcpCommand());
+program.addCommand(makeSkillCommand());
+program.addCommand(makeDoctorCommand());
+program.addCommand(makeToolCommand());
+program.addCommand(makeSetupCommand());
+
+try {
+  ensureRegistryDirs();
+  await program.parseAsync(process.argv);
+} catch (err) {
+  log.error(err.message);
+  process.exit(1);
+}

package/src/registry/mcpRegistry.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getMcpsDir } from './paths.js';
+import { readJson, writeJson, listFiles } from '../utils/fileUtils.js';
+import { validateMcp } from '../utils/validator.js';
+
+function mcpFile(id) {
+  return path.join(getMcpsDir(), `${id}.json`);
+}
+
+/**
+ * List all registered MCP IDs.
+ * @returns {string[]}
+ */
+export function listMcps() {
+  return listFiles(getMcpsDir())
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace(/\.json$/, ''));
+}
+
+/**
+ * Get an MCP definition by ID. Returns null if not found.
+ * @param {string} id
+ * @returns {object|null}
+ */
+export function getMcp(id) {
+  return readJson(mcpFile(id));
+}
+
+/**
+ * Save an MCP definition (validates first).
+ * Throws if validation fails.
+ * @param {object} mcp
+ */
+export function saveMcp(mcp) {
+  const { valid, errors } = validateMcp(mcp);
+  if (!valid) {
+    throw new Error(`Invalid MCP definition: ${errors.join('; ')}`);
+  }
+  writeJson(mcpFile(mcp.id), mcp);
+}
+
+/**
+ * Remove an MCP by ID. Throws if not found.
+ * @param {string} id
+ */
+export function removeMcp(id) {
+  const file = mcpFile(id);
+  if (!fs.existsSync(file)) {
+    throw new Error(`MCP "${id}" not found in registry`);
+  }
+  fs.rmSync(file);
+}
+
+/**
+ * Import one or more MCPs from a JSON value (single object or array).
+ * @param {object|object[]} data
+ * @returns {string[]} imported IDs
+ */
+export function importMcps(data) {
+  const items = Array.isArray(data) ? data : [data];
+  const imported = [];
+  for (const item of items) {
+    saveMcp(item);
+    imported.push(item.id);
+  }
+  return imported;
+}

package/src/registry/paths.js

@@ -0,0 +1,21 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getRegistryRoot } from '../utils/pathResolver.js';
+
+export function getMcpsDir() {
+  return path.join(getRegistryRoot(), 'mcps');
+}
+
+export function getSkillsDir() {
+  return path.join(getRegistryRoot(), 'skills');
+}
+
+export function getToolsDir() {
+  return path.join(getRegistryRoot(), 'tools');
+}
+
+export function ensureRegistryDirs() {
+  for (const dir of [getMcpsDir(), getSkillsDir(), getToolsDir()]) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}

package/src/registry/skillRegistry.js

@@ -0,0 +1,61 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getSkillsDir } from './paths.js';
+import { listDirs, fileExists, copyDir } from '../utils/fileUtils.js';
+
+function skillDir(name) {
+  return path.join(getSkillsDir(), name);
+}
+
+/**
+ * List all registered skill names.
+ * @returns {string[]}
+ */
+export function listSkills() {
+  return listDirs(getSkillsDir());
+}
+
+/**
+ * Add a skill from a source path (directory or single .md file).
+ * If src is a directory, it is copied as-is.
+ * If src is a .md file, it is placed into a new folder named after the skill,
+ * saved as SKILL.md.
+ * @param {string} name
+ * @param {string} src  absolute path to source
+ */
+export async function addSkill(name, src) {
+  const dest = skillDir(name);
+  const stat = fs.statSync(src);
+  if (stat.isDirectory()) {
+    await copyDir(src, dest);
+  } else if (src.endsWith('.md')) {
+    fs.mkdirSync(dest, { recursive: true });
+    fs.copyFileSync(src, path.join(dest, 'SKILL.md'));
+  } else {
+    throw new Error(`Skill source must be a directory or .md file: ${src}`);
+  }
+}
+
+/**
+ * Show the SKILL.md contents for a skill.
+ * Returns null if SKILL.md doesn't exist.
+ * @param {string} name
+ * @returns {string|null}
+ */
+export function showSkill(name) {
+  const skillMd = path.join(skillDir(name), 'SKILL.md');
+  if (!fileExists(skillMd)) return null;
+  return fs.readFileSync(skillMd, 'utf8');
+}
+
+/**
+ * Remove a skill by name. Throws if not found.
+ * @param {string} name
+ */
+export function removeSkill(name) {
+  const dir = skillDir(name);
+  if (!fs.existsSync(dir)) {
+    throw new Error(`Skill "${name}" not found in registry`);
+  }
+  fs.rmSync(dir, { recursive: true });
+}

package/src/registry/toolRegistry.js

@@ -0,0 +1,43 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getToolsDir } from './paths.js';
+import { readJson, listFiles } from '../utils/fileUtils.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const BUILTIN_TOOLS_DIR = path.join(__dirname, '..', 'tools');
+
+/**
+ * Load a tool definition by ID.
+ * Checks user registry tools/ first, then falls back to builtin src/tools/.
+ * Returns null if not found.
+ * @param {string} id
+ * @returns {object|null}
+ */
+export function loadTool(id) {
+  // User override
+  const userFile = path.join(getToolsDir(), `${id}.json`);
+  if (fs.existsSync(userFile)) return readJson(userFile);
+
+  // Builtin
+  const builtinFile = path.join(BUILTIN_TOOLS_DIR, `${id}.json`);
+  if (fs.existsSync(builtinFile)) return readJson(builtinFile);
+
+  return null;
+}
+
+/**
+ * List all known tool IDs (union of user overrides and builtins).
+ * @returns {string[]}
+ */
+export function listTools() {
+  const userTools = listFiles(getToolsDir())
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace(/\.json$/, ''));
+
+  const builtinTools = listFiles(BUILTIN_TOOLS_DIR)
+    .filter(f => f.endsWith('.json'))
+    .map(f => f.replace(/\.json$/, ''));
+
+  return [...new Set([...userTools, ...builtinTools])];
+}