@joehom/awm-cli 0.0.1

package/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/adapters/jsonAdapter.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, writeJson } from '../utils/fileUtils.js';
+import { resolvePath } from '../utils/pathResolver.js';
+import { log } from '../utils/logger.js';
+
+/**
+ * Build the MCP block for a tool config file from an MCP definition.
+ * Strips internal fields (id, transport). Does NOT expand ${env:VAR} in env values.
+ * @param {object} mcp
+ * @returns {object}
+ */
+export function buildMcpBlock(mcp) {
+  const block = {
+    command: mcp.command,
+  };
+  if (mcp.args && mcp.args.length > 0) {
+    block.args = mcp.args;
+  }
+  if (mcp.env && Object.keys(mcp.env).length > 0) {
+    block.env = mcp.env; // passthrough — NOT expanded
+  }
+  return block;
+}
+
+/**
+ * Apply MCPs to a JSON config file (merge-safe).
+ * Reads existing file, merges into [rootObject] key, writes back (or dry-runs).
+ * @param {string} targetFile  may contain ~ or env vars
+ * @param {string} rootObject  e.g. "mcpServers"
+ * @param {object[]} mcps      canonical MCP definitions
+ * @param {boolean} dryRun
+ */
+export async function applyMcpJson(targetFile, rootObject, mcps, dryRun = false) {
+  const resolved = resolvePath(targetFile);
+  const existing = readJson(resolved) ?? {};
+
+  if (!existing[rootObject]) {
+    existing[rootObject] = {};
+  }
+
+  for (const mcp of mcps) {
+    existing[rootObject][mcp.id] = buildMcpBlock(mcp);
+  }
+
+  if (dryRun) {
+    log.dryRun(`Would write ${mcps.length} MCP(s) to ${resolved} under "${rootObject}"`);
+    log.dryRun(JSON.stringify(existing, null, 2));
+    return;
+  }
+
+  writeJson(resolved, existing);
+  log.success(`Wrote ${mcps.length} MCP(s) to ${resolved}`);
+}

package/src/adapters/skillApplier.js

@@ -0,0 +1,35 @@
+import path from 'node:path';
+import { getSkillsDir } from '../registry/paths.js';
+import { fileExists, copyDir } from '../utils/fileUtils.js';
+import { resolvePath } from '../utils/pathResolver.js';
+import { log } from '../utils/logger.js';
+
+/**
+ * Apply skills to a target folder.
+ * For each skill: validates SKILL.md exists, then copies the skill directory.
+ * @param {string[]} skillNames
+ * @param {string} targetFolder  may contain ~ or env vars
+ * @param {boolean} dryRun
+ */
+export async function applySkills(skillNames, targetFolder, dryRun = false) {
+  const resolvedTarget = resolvePath(targetFolder);
+
+  for (const name of skillNames) {
+    const skillDir = path.join(getSkillsDir(), name);
+    const skillMd = path.join(skillDir, 'SKILL.md');
+
+    if (!fileExists(skillMd)) {
+      throw new Error(`Skill "${name}" is missing SKILL.md at ${skillMd}`);
+    }
+
+    const dest = path.join(resolvedTarget, name);
+
+    if (dryRun) {
+      log.dryRun(`Would copy skill "${name}" → ${dest}`);
+      continue;
+    }
+
+    await copyDir(skillDir, dest);
+    log.success(`Copied skill "${name}" → ${dest}`);
+  }
+}

package/src/adapters/tomlAdapter.js

@@ -0,0 +1,49 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import TOML from '@iarna/toml';
+import { fileExists } from '../utils/fileUtils.js';
+import { resolvePath } from '../utils/pathResolver.js';
+import { log } from '../utils/logger.js';
+import { buildMcpBlock } from './jsonAdapter.js';
+
+/**
+ * Apply MCPs to a TOML config file (merge-safe).
+ * Reads existing file, merges into [rootObject] key, writes back (or dry-runs).
+ * @param {string} targetFile  may contain ~ or env vars
+ * @param {string} rootObject  e.g. "mcpServers"
+ * @param {object[]} mcps      canonical MCP definitions
+ * @param {boolean} dryRun
+ */
+export async function applyMcpToml(targetFile, rootObject, mcps, dryRun = false) {
+  const resolved = resolvePath(targetFile);
+  let existing = {};
+
+  if (fileExists(resolved)) {
+    try {
+      const raw = fs.readFileSync(resolved, 'utf8');
+      existing = TOML.parse(raw);
+    } catch (e) {
+      throw new Error(`Failed to parse TOML at ${resolved}: ${e.message}`);
+    }
+  }
+
+  if (!existing[rootObject]) {
+    existing[rootObject] = {};
+  }
+
+  for (const mcp of mcps) {
+    existing[rootObject][mcp.id] = buildMcpBlock(mcp);
+  }
+
+  const tomlStr = TOML.stringify(existing);
+
+  if (dryRun) {
+    log.dryRun(`Would write ${mcps.length} MCP(s) to ${resolved} under "${rootObject}"`);
+    log.dryRun(tomlStr);
+    return;
+  }
+
+  fs.mkdirSync(path.dirname(resolved), { recursive: true });
+  fs.writeFileSync(resolved, tomlStr, 'utf8');
+  log.success(`Wrote ${mcps.length} MCP(s) to ${resolved}`);
+}

package/src/commands/doctor.js

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Command } from 'commander';
+import { log } from '../utils/logger.js';
+import { getMcpsDir, getSkillsDir } from '../registry/paths.js';
+import { listFiles, listDirs, fileExists } from '../utils/fileUtils.js';
+import { validateMcp, validateToolDef } from '../utils/validator.js';
+import { loadTool, listTools } from '../registry/toolRegistry.js';
+import { readJson } from '../utils/fileUtils.js';
+import { getWorkspacePath } from '../workspace/workspaceConfig.js';
+
+export function makeDoctorCommand() {
+  return new Command('doctor')
+    .description('Check registry integrity and validate workspace config')
+    .action(() => {
+      const issues = [];
+
+      // Check registry dirs exist
+      for (const [label, dir] of [
+        ['mcps', getMcpsDir()],
+        ['skills', getSkillsDir()],
+      ]) {
+        if (!fs.existsSync(dir)) {
+          issues.push(`Registry dir missing: ${dir}`);
+        }
+      }
+
+      // Validate all MCP JSON files in registry
+      const mcpsDir = getMcpsDir();
+      const mcpFiles = listFiles(mcpsDir).filter(f => f.endsWith('.json'));
+      for (const file of mcpFiles) {
+        const data = readJson(path.join(mcpsDir, file));
+        const { valid, errors } = validateMcp(data);
+        if (!valid) {
+          issues.push(`MCP file "${file}": ${errors.join('; ')}`);
+        }
+      }
+
+      // Validate all tool definitions
+      const knownToolIds = listTools();
+      for (const toolId of knownToolIds) {
+        const toolDef = loadTool(toolId);
+        const { valid, errors } = validateToolDef(toolDef);
+        if (!valid) {
+          issues.push(`Tool "${toolId}": ${errors.join('; ')}`);
+        }
+      }
+
+      // Validate .awm.json if present in cwd
+      const wsPath = getWorkspacePath();
+      if (fs.existsSync(wsPath)) {
+        const ws = readJson(wsPath);
+        if (!ws) {
+          issues.push('.awm.json: invalid JSON');
+        } else {
+          if (!Array.isArray(ws.tools)) issues.push('.awm.json: "tools" must be an array');
+          if (!Array.isArray(ws.mcps)) issues.push('.awm.json: "mcps" must be an array');
+          if (!Array.isArray(ws.skills)) issues.push('.awm.json: "skills" must be an array');
+
+          if (Array.isArray(ws.tools)) {
+            for (const toolId of ws.tools) {
+              if (!knownToolIds.includes(toolId)) {
+                issues.push(`.awm.json: unknown tool "${toolId}"`);
+              }
+            }
+          }
+
+          const knownMcpIds = new Set(mcpFiles.map(f => f.replace(/\.json$/, '')));
+          if (Array.isArray(ws.mcps)) {
+            for (const mcpId of ws.mcps) {
+              if (!knownMcpIds.has(mcpId)) {
+                issues.push(`.awm.json: MCP "${mcpId}" not found in registry`);
+              }
+            }
+          }
+
+          const knownSkills = new Set(listDirs(getSkillsDir()));
+          if (Array.isArray(ws.skills)) {
+            for (const skillName of ws.skills) {
+              if (!knownSkills.has(skillName)) {
+                issues.push(`.awm.json: skill "${skillName}" not found in registry`);
+              } else {
+                const skillMd = path.join(getSkillsDir(), skillName, 'SKILL.md');
+                if (!fileExists(skillMd)) {
+                  issues.push(`.awm.json: skill "${skillName}" missing SKILL.md`);
+                }
+              }
+            }
+          }
+        }
+      }
+
+      if (issues.length > 0) {
+        for (const issue of issues) log.error(issue);
+        process.exit(1);
+      } else {
+        log.success('No issues found');
+      }
+    });
+}

package/src/commands/init.js

@@ -0,0 +1,34 @@
+import { Command } from 'commander';
+import inquirer from 'inquirer';
+import fs from 'node:fs';
+import { log } from '../utils/logger.js';
+import { listTools } from '../registry/toolRegistry.js';
+import { getWorkspacePath, writeWorkspace } from '../workspace/workspaceConfig.js';
+
+export function makeInitCommand() {
+  return new Command('init')
+    .description('Initialize a workspace config (.awm.json) in the current directory')
+    .option('--force', 'Overwrite existing .awm.json')
+    .action(async (opts) => {
+      const wsPath = getWorkspacePath();
+
+      if (fs.existsSync(wsPath) && !opts.force) {
+        throw new Error(`.awm.json already exists. Use --force to overwrite.`);
+      }
+
+      const tools = listTools();
+      if (tools.length === 0) throw new Error('No tool definitions found');
+
+      const { selectedTools } = await inquirer.prompt([{
+        type: 'checkbox',
+        name: 'selectedTools',
+        message: 'Select tools to support in this workspace:',
+        choices: tools,
+        validate: v => v.length > 0 || 'Select at least one tool',
+      }]);
+
+      writeWorkspace({ tools: selectedTools, mcps: [], skills: [] });
+      log.success(`Workspace initialized with tools: ${selectedTools.join(', ')}`);
+      log.info(`  Run "awm mcp add" to add MCPs, "awm skill add" to add skills.`);
+    });
+}