ma-agents 1.3.0 → 1.5.0

package/index.js

@@ -1,20 +1,22 @@
 /**
- * AI Agent Skills - Programmatic API
+ * ma-agents - Programmatic API
  *
  * This module exports the core functionality for use as a library.
- * For CLI usage, use: npx ai-agent-skills
+ * For CLI usage, use: npx ma-agents
  */
 
-const { installSkill, listSkills, listAgents } = require('./lib/installer');
+const { installSkill, uninstallSkill, getStatus, listSkills, listAgents, readManifest, getInstalledSkillInfo, compareSemver } = require('./lib/installer');
 const { getAgent, getAllAgents } = require('./lib/agents');
 
 module.exports = {
-  // Installer functions
   installSkill,
+  uninstallSkill,
+  getStatus,
   listSkills,
   listAgents,
-
-  // Agent functions
+  readManifest,
+  getInstalledSkillInfo,
+  compareSemver,
   getAgent,
   getAllAgents
 };

package/lib/agents.js

@@ -17,6 +17,7 @@ const agents = [
   {
     id: 'claude-code',
     name: 'Claude Code',
+    version: '1.0.0',
     description: 'Anthropic Claude Code CLI',
     getProjectPath: () => path.join(process.cwd(), '.claude', 'skills'),
     getGlobalPath: () => {
@@ -35,6 +36,7 @@ const agents = [
   {
     id: 'gemini',
     name: 'Google Gemini',
+    version: '1.0.0',
     description: 'Google Gemini Code Assist',
     getProjectPath: () => path.join(process.cwd(), '.gemini', 'skills'),
     getGlobalPath: () => {
@@ -53,6 +55,7 @@ const agents = [
   {
     id: 'copilot',
     name: 'GitHub Copilot',
+    version: '1.0.0',
     description: 'GitHub Copilot Agent Mode',
     getProjectPath: () => path.join(process.cwd(), '.github', 'copilot', 'skills'),
     getGlobalPath: () => {
@@ -71,6 +74,7 @@ const agents = [
   {
     id: 'kilocode',
     name: 'Kilocode',
+    version: '1.0.0',
     description: 'Kilocode AI Assistant',
     getProjectPath: () => path.join(process.cwd(), '.kilocode', 'skills'),
     getGlobalPath: () => {
@@ -89,6 +93,7 @@ const agents = [
   {
     id: 'cline',
     name: 'Cline',
+    version: '1.0.0',
     description: 'Cline AI Assistant',
     getProjectPath: () => path.join(process.cwd(), '.cline', 'skills'),
     getGlobalPath: () => {
@@ -102,11 +107,17 @@ const agents = [
       }
     },
     fileExtension: '.md',
-    template: 'cline'
+    template: 'cline',
+    // Cline uses different directory names than the generic structure
+    resourceMap: {
+      'references': 'docs',
+      'assets': 'templates'
+    }
   },
   {
     id: 'cursor',
     name: 'Cursor',
+    version: '1.0.0',
     description: 'Cursor AI Editor',
     getProjectPath: () => path.join(process.cwd(), '.cursor', 'skills'),
     getGlobalPath: () => {

package/lib/installer.js

@@ -1,11 +1,72 @@
 const fs = require('fs-extra');
 const path = require('path');
 const chalk = require('chalk');
+const prompts = require('prompts');
 const { getAgent, getAllAgents } = require('./agents');
 
+const MANIFEST_FILE = '.ma-agents.json';
+const MANIFEST_VERSION = '1.0.0';
+
+function getPackageVersion() {
+  const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf-8'));
+  return pkg.version;
+}
+
+// --- Manifest functions ---
+
+function readManifest(installPath) {
+  const manifestPath = path.join(installPath, MANIFEST_FILE);
+  if (!fs.existsSync(manifestPath)) {
+    return null;
+  }
+  try {
+    return JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+function writeManifest(installPath, manifest) {
+  const manifestPath = path.join(installPath, MANIFEST_FILE);
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+}
+
+function ensureManifest(installPath, agentId, scope) {
+  let manifest = readManifest(installPath);
+  if (!manifest) {
+    manifest = {
+      manifestVersion: MANIFEST_VERSION,
+      agent: agentId,
+      scope: scope,
+      skills: {}
+    };
+  }
+  return manifest;
+}
+
+function getInstalledSkillInfo(installPath, skillId) {
+  const manifest = readManifest(installPath);
+  if (!manifest || !manifest.skills || !manifest.skills[skillId]) {
+    return null;
+  }
+  return manifest.skills[skillId];
+}
+
 /**
- * Get all available skills
+ * Compare two semver strings. Returns -1, 0, or 1.
  */
+function compareSemver(a, b) {
+  const pa = (a || '0.0.0').split('.').map(Number);
+  const pb = (b || '0.0.0').split('.').map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] > pb[i]) return 1;
+    if (pa[i] < pb[i]) return -1;
+  }
+  return 0;
+}
+
+// --- Skill listing ---
+
 function listSkills() {
   const skillsDir = path.join(__dirname, '..', 'skills');
 
@@ -32,17 +93,82 @@ function listSkills() {
   }).filter(Boolean);
 }
 
-/**
- * Get all supported agents
- */
 function listAgents() {
   return getAllAgents();
 }
 
-/**
- * Install a skill for specified agents
- */
-async function installSkill(skillId, agentIds, customPath = '', scope = 'project') {
+// --- Core install logic (no prompts) ---
+
+async function performInstall(skillId, skill, agent, installPath) {
+  const skillSourceDir = path.join(__dirname, '..', 'skills', skillId);
+  let sourceFile = path.join(skillSourceDir, `${agent.template}${agent.fileExtension}`);
+
+  if (!fs.existsSync(sourceFile)) {
+    sourceFile = path.join(skillSourceDir, `generic${agent.fileExtension}`);
+  }
+
+  if (!fs.existsSync(sourceFile)) {
+    const skillMdPath = path.join(skillSourceDir, 'SKILL.md');
+    if (fs.existsSync(skillMdPath)) {
+      sourceFile = skillMdPath;
+    }
+  }
+
+  if (!fs.existsSync(sourceFile)) {
+    console.log(chalk.yellow(`    Warning: No template found for ${agent.name}, skipping`));
+    return false;
+  }
+
+  const skillDir = path.join(installPath, skillId);
+  await fs.ensureDir(skillDir);
+
+  let content = await fs.readFile(sourceFile, 'utf-8');
+
+  // Strip any existing YAML frontmatter from the source
+  const frontmatterRegex = /^---\s*\n[\s\S]*?\n---\s*\n/;
+  content = content.replace(frontmatterRegex, '');
+
+  // Inject YAML frontmatter from skill.json (single source of truth)
+  const frontmatter = [
+    '---',
+    `name: ${skill.name}`,
+    `description: ${skill.description}`,
+    '---',
+    ''
+  ].join('\n');
+  content = frontmatter + content;
+
+  const targetFile = path.join(skillDir, 'SKILL.md');
+  await fs.writeFile(targetFile, content, 'utf-8');
+  console.log(chalk.green(`    + Installed to ${targetFile}`));
+
+  // Copy bundled resources
+  const resourceMap = agent.resourceMap || {};
+  const resourceDirs = ['scripts', 'references', 'assets', 'examples', 'hooks', 'docs', 'templates'];
+  for (const dir of resourceDirs) {
+    const resourceSource = path.join(skillSourceDir, dir);
+    if (fs.existsSync(resourceSource)) {
+      const targetDirName = resourceMap[dir] || dir;
+      const resourceTarget = path.join(skillDir, targetDirName);
+      await fs.copy(resourceSource, resourceTarget);
+      console.log(chalk.green(`    + Copied ${dir}/ → ${targetDirName}/`));
+    }
+  }
+
+  // Copy template.md if it exists
+  const templateSource = path.join(skillSourceDir, 'template.md');
+  if (fs.existsSync(templateSource)) {
+    await fs.copy(templateSource, path.join(skillDir, 'template.md'));
+    console.log(chalk.green(`    + Copied template.md`));
+  }
+
+  return true;
+}
+
+// --- Install with upgrade detection ---
+
+async function installSkill(skillId, agentIds, customPath = '', scope = 'project', options = {}) {
+  const { force = false } = options;
   const skills = listSkills();
   const skill = skills.find(s => s.id === skillId);
 
@@ -50,7 +176,7 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
     throw new Error(`Skill '${skillId}' not found. Run "list" to see available skills.`);
   }
 
-  console.log(chalk.cyan(`\nInstalling skill: ${skill.name}`));
+  console.log(chalk.cyan(`\nInstalling skill: ${skill.name} v${skill.version}`));
 
   for (const agentId of agentIds) {
     const agent = getAgent(agentId);
@@ -60,61 +186,202 @@ async function installSkill(skillId, agentIds, customPath = '', scope = 'project
       continue;
     }
 
-    console.log(chalk.gray(`  Installing for ${agent.name}...`));
-
     try {
-      // Determine installation path
       const installPath = customPath || (scope === 'global' ? agent.getGlobalPath() : agent.getProjectPath());
-
-      // Ensure the skills directory exists
       await fs.ensureDir(installPath);
 
-      // Get the skill source file based on agent template
-      const skillSourceDir = path.join(__dirname, '..', 'skills', skillId);
-      let sourceFile = path.join(skillSourceDir, `${agent.template}${agent.fileExtension}`);
+      const installed = getInstalledSkillInfo(installPath, skillId);
 
-      // Fallback to generic template if specific template doesn't exist
-      if (!fs.existsSync(sourceFile)) {
-        sourceFile = path.join(skillSourceDir, `generic${agent.fileExtension}`);
-      }
+      if (installed && !force) {
+        const cmp = compareSemver(skill.version, installed.version);
 
-      // Fallback to SKILL.md if no agent-specific or generic template exists
-      if (!fs.existsSync(sourceFile)) {
-        const skillMdPath = path.join(skillSourceDir, 'SKILL.md');
-        if (fs.existsSync(skillMdPath)) {
-          sourceFile = skillMdPath;
+        let action;
+        if (cmp > 0) {
+          // Upgrade available
+          console.log(chalk.yellow(`  ${skill.name} v${installed.version} → v${skill.version} update available for ${agent.name}`));
+          const { choice } = await prompts({
+            type: 'select',
+            name: 'choice',
+            message: 'What would you like to do?',
+            choices: [
+              { title: 'Update (recommended)', value: 'update' },
+              { title: 'Skip (keep current)', value: 'skip' },
+              { title: 'Clean reinstall', value: 'reinstall' },
+              { title: 'Remove (uninstall)', value: 'remove' }
+            ]
+          });
+          action = choice;
+        } else if (cmp === 0) {
+          // Same version
+          console.log(chalk.gray(`  ${skill.name} v${installed.version} already installed for ${agent.name}`));
+          const { choice } = await prompts({
+            type: 'select',
+            name: 'choice',
+            message: 'What would you like to do?',
+            choices: [
+              { title: 'Skip (keep current)', value: 'skip' },
+              { title: 'Clean reinstall', value: 'reinstall' },
+              { title: 'Remove (uninstall)', value: 'remove' }
+            ]
+          });
+          action = choice;
+        } else {
+          // Downgrade
+          console.log(chalk.yellow(`  ${skill.name} v${installed.version} installed, package has v${skill.version} for ${agent.name}`));
+          const { choice } = await prompts({
+            type: 'select',
+            name: 'choice',
+            message: 'What would you like to do?',
+            choices: [
+              { title: 'Skip (keep current)', value: 'skip' },
+              { title: `Downgrade to v${skill.version}`, value: 'update' },
+              { title: 'Remove (uninstall)', value: 'remove' }
+            ]
+          });
+          action = choice;
         }
+
+        if (!action || action === 'skip') {
+          console.log(chalk.gray(`    Skipped`));
+          continue;
+        }
+
+        if (action === 'remove') {
+          await performUninstall(skillId, installPath);
+          const manifest = ensureManifest(installPath, agentId, scope);
+          delete manifest.skills[skillId];
+          writeManifest(installPath, manifest);
+          console.log(chalk.green(`    - Removed ${skill.name} from ${agent.name}`));
+          continue;
+        }
+
+        if (action === 'reinstall') {
+          await performUninstall(skillId, installPath);
+        }
+
+        // action === 'update' or 'reinstall' → proceed to install below
       }
 
-      if (!fs.existsSync(sourceFile)) {
-        console.log(chalk.yellow(`    Warning: No template found for ${agent.name}, skipping`));
-        continue;
+      if (!installed || force) {
+        console.log(chalk.gray(`  Installing for ${agent.name}...`));
       }
 
-      // Copy the skill file
-      const targetFile = path.join(installPath, `${skillId}${agent.fileExtension}`);
-      await fs.copy(sourceFile, targetFile);
-      console.log(chalk.green(`    + Installed to ${targetFile}`));
-
-      // Copy bundled resources (scripts/, references/, assets/) if they exist
-      const resourceDirs = ['scripts', 'references', 'assets'];
-      for (const dir of resourceDirs) {
-        const resourceSource = path.join(skillSourceDir, dir);
-        if (fs.existsSync(resourceSource)) {
-          const resourceTarget = path.join(installPath, skillId, dir);
-          await fs.ensureDir(path.join(installPath, skillId));
-          await fs.copy(resourceSource, resourceTarget);
-          console.log(chalk.green(`    + Copied ${dir}/ resources`));
+      const success = await performInstall(skillId, skill, agent, installPath);
+
+      if (success) {
+        // Update manifest
+        const manifest = ensureManifest(installPath, agentId, scope);
+        const now = new Date().toISOString();
+        const existing = manifest.skills[skillId];
+        manifest.skills[skillId] = {
+          version: skill.version,
+          installedAt: existing ? existing.installedAt : now,
+          updatedAt: now,
+          installerVersion: getPackageVersion(),
+          agentVersion: agent.version
+        };
+        writeManifest(installPath, manifest);
+      }
+    } catch (error) {
+      console.log(chalk.red(`    x Failed: ${error.message}`));
+    }
+  }
+}
+
+// --- Uninstall ---
+
+async function performUninstall(skillId, installPath) {
+  const skillDir = path.join(installPath, skillId);
+  if (fs.existsSync(skillDir)) {
+    await fs.remove(skillDir);
+  }
+}
+
+async function uninstallSkill(skillId, agentIds, customPath = '', scope = 'project') {
+  console.log(chalk.cyan(`\nUninstalling skill: ${skillId}`));
+
+  for (const agentId of agentIds) {
+    const agent = getAgent(agentId);
+
+    if (!agent) {
+      console.log(chalk.yellow(`  Warning: Skipping unknown agent: ${agentId}`));
+      continue;
+    }
+
+    try {
+      const installPath = customPath || (scope === 'global' ? agent.getGlobalPath() : agent.getProjectPath());
+      const installed = getInstalledSkillInfo(installPath, skillId);
+
+      if (!installed) {
+        const skillDir = path.join(installPath, skillId);
+        if (fs.existsSync(skillDir)) {
+          await performUninstall(skillId, installPath);
+          console.log(chalk.green(`  - Removed ${skillId} from ${agent.name} (legacy install)`));
+        } else {
+          console.log(chalk.gray(`  ${skillId} is not installed for ${agent.name}`));
         }
+        continue;
       }
+
+      await performUninstall(skillId, installPath);
+
+      const manifest = ensureManifest(installPath, agentId, scope);
+      delete manifest.skills[skillId];
+      writeManifest(installPath, manifest);
+
+      console.log(chalk.green(`  - Removed ${skillId} v${installed.version} from ${agent.name}`));
     } catch (error) {
       console.log(chalk.red(`    x Failed: ${error.message}`));
     }
   }
 }
 
+// --- Status ---
+
+function getStatus(agentIds, customPath = '', scope = 'project') {
+  const results = [];
+
+  const targetAgents = agentIds && agentIds.length > 0
+    ? agentIds.map(id => getAgent(id)).filter(Boolean)
+    : getAllAgents();
+
+  for (const agent of targetAgents) {
+    const projectPath = agent.getProjectPath();
+    const globalPath = agent.getGlobalPath();
+
+    // Check both scopes unless custom path is specified
+    const pathsToCheck = customPath
+      ? [{ path: customPath, scope: 'custom' }]
+      : [
+          { path: projectPath, scope: 'project' },
+          { path: globalPath, scope: 'global' }
+        ];
+
+    for (const { path: checkPath, scope: checkScope } of pathsToCheck) {
+      const manifest = readManifest(checkPath);
+      if (!manifest || !manifest.skills || Object.keys(manifest.skills).length === 0) {
+        continue;
+      }
+
+      results.push({
+        agent: agent,
+        installPath: checkPath,
+        scope: checkScope,
+        skills: manifest.skills
+      });
+    }
+  }
+
+  return results;
+}
+
 module.exports = {
   listSkills,
   listAgents,
-  installSkill
+  installSkill,
+  uninstallSkill,
+  getStatus,
+  readManifest,
+  getInstalledSkillInfo,
+  compareSemver
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ma-agents",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "NPX tool to install skills for AI coding agents (Claude Code, Gemini, Copilot, Kilocode, Cline, Cursor)",
   "main": "index.js",
   "bin": {
@@ -32,4 +32,4 @@
   "engines": {
     "node": ">=14.0.0"
   }
-}
+}

package/skills/README.md

@@ -191,6 +191,31 @@ Creates production-ready hardened Docker configurations following security best
 
 ---
 
+### 5. Test-Accompanied Development (TAD)
+**Directory:** `test-accompanied-development/`
+
+Enforces a "Test-Alongside" policy where every public method is accompanied by a corresponding unit test. It ensures high code quality by mandating that all public interfaces are verified by automated tests at the moment of creation.
+
+**Key Features:**
+- ✅ **Automatic Enforcement**: Mandates tests for every new public method.
+- ✅ **Integration**: References `test-generator` for implementation standards.
+- ✅ **Workflow Guardrail**: Prevents "test debt" by requiring tests alongside code.
+
+---
+
+### 6. Logging Best Practices
+**Directory:** `logging-best-practices/`
+
+Standardizes structured logging (JSON) across Backend, Frontend, Realtime, and Algorithmic domains. Enforces mandatory exception logging and OpenTelemetry-aligned context fields.
+
+**Key Features:**
+- ✅ **Structured Logging**: Mandates JSON format for machine-readability.
+- ✅ **Domain-Specific**: Tailored guidance for Web, Server, and High-Performance Algorithm domains.
+- ✅ **Mandatory Exceptions**: Every catch block must log full stack traces.
+- ✅ **Context-Rich**: Standardizes fields like `trace_id`, `placement`, and `process_name`.
+
+---
+
 ## Requirements
 
 ### All Skills

package/skills/code-review/SKILL.md

@@ -0,0 +1,39 @@
+# Code Review
+
+Perform comprehensive code reviews following industry best practices.
+
+## What to Review
+
+1. **Code Quality**: Readability, naming conventions, structure
+2. **Best Practices**: Language-specific patterns, error handling, performance
+3. **Security**: Common vulnerabilities (SQL injection, XSS, CSRF, etc.)
+4. **Testing**: Coverage, edge cases, test quality
+5. **Documentation**: Comments, API docs, clarity
+
+## Review Process
+
+- Analyze code for bugs and logical errors
+- Check adherence to coding standards
+- Identify security vulnerabilities
+- Suggest refactoring opportunities
+- Assess test coverage and documentation
+
+## Output Format
+
+```
+## Code Review Summary
+
+### Strengths
+- [Positive aspects]
+
+### Issues Found
+- **[High/Medium/Low]** [Issue description]
+  - Location: [file:line]
+  - Fix: [recommendation]
+
+### Suggestions
+- [Improvements]
+
+### Overall Assessment
+[Summary and rating]
+```

package/skills/commit-message/SKILL.md

@@ -0,0 +1,75 @@
+# Commit Message Generator
+
+Generate meaningful commit messages following Conventional Commits specification.
+
+## Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+## Types
+
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `style`: Code style/formatting
+- `refactor`: Code refactoring
+- `test`: Adding/updating tests
+- `chore`: Maintenance tasks
+- `perf`: Performance improvements
+- `ci`: CI/CD changes
+- `build`: Build system changes
+- `revert`: Revert previous commit
+
+## Guidelines
+
+1. **Subject line** (max 50 chars):
+   - Use imperative mood ("Add" not "Added")
+   - Don't capitalize first letter
+   - No period at the end
+
+2. **Body** (optional):
+   - Explain what and why, not how
+   - Wrap at 72 characters
+
+3. **Footer** (optional):
+   - Breaking changes: `BREAKING CHANGE: description`
+   - Issue references: `Fixes #123`
+
+## Examples
+
+```
+feat(auth): add JWT token refresh mechanism
+
+Implement automatic token refresh to improve user experience
+and reduce re-authentication prompts.
+
+Fixes #456
+```
+
+```
+fix(api): resolve memory leak in user service
+
+The user cache was not being cleared properly, causing
+memory to grow over time.
+```
+
+```
+docs: update installation instructions
+
+Add steps for Windows users and clarify dependency requirements.
+```
+
+## Process
+
+1. Analyze the code changes
+2. Determine the type of change
+3. Identify the scope (component/module affected)
+4. Write clear, concise subject
+5. Add body if changes need explanation
+6. Add footer for breaking changes or issue refs

package/skills/create-hardened-docker-skill/SKILL.md

@@ -1,8 +1,3 @@
----
-name: create-hardened-docker
-description: Creates production-ready hardened Docker configurations (Dockerfile, docker-compose.yml, nginx.conf, .dockerignore) following CIS Docker Benchmark, OWASP, and NIST SP 800-190 standards. Includes multi-stage builds, non-root execution, read-only filesystems, capability dropping, and comprehensive security hardening.
----
-
 # Create Hardened Docker
 
 ## Overview

package/skills/git-workflow-skill/SKILL.md

@@ -1,8 +1,3 @@
----
-name: git-workflow-skill
-description: Mandatory feature branch workflow using git worktrees for parallel multi-agent development. Use this skill BEFORE making ANY change to files in a Git repository that are not ignored by .gitignore. Enforces isolated worktrees per feature, conventional commits, and PR-based merging. Supports multiple AI agents working simultaneously on different features without conflicts.
----
-
 # Git Workflow (Worktree-Based)
 
 Multi-agent parallel development using git worktrees. Each agent gets an isolated working directory — no branch switching, no conflicts between agents.

package/skills/js-ts-security-skill/SKILL.md

@@ -1,7 +1,3 @@
----
-name: js-ts-security-skill
-description: Verify the security of JavaScript and TypeScript codebases against OWASP Top 10 2025 standards.
----
 
 # JS/TS Security Skill