@valentia-ai-skills/framework 1.0.0

package/README.md

@@ -0,0 +1,103 @@
+# AI Skills Framework
+
+Centralized coding standards, security patterns, and SOPs for AI-assisted development.
+
+**One install. All AI tools. Every team follows the same rules.**
+
+## Quick Start
+
+```bash
+# Install
+npm install --save-dev @valentia-ai-skills/framework
+
+# Setup (auto-detects your AI tools)
+npx ai-skills setup
+
+# Done. Your AI tools now follow your org's standards.
+```
+
+## What It Does
+
+This package installs your organization's coding standards into whatever AI coding tool your team uses:
+
+| AI Tool | What Gets Created |
+|---------|------------------|
+| **Claude Code** | Individual skill folders in `.claude/skills/` |
+| **Cursor** | Merged rules file at `.cursor/rules/ai-skills.mdc` |
+| **GitHub Copilot** | Merged rules at `.github/copilot-instructions.md` |
+| **Windsurf** | Merged rules at `.windsurfrules` |
+| **Any other tool** | Generic `.ai-rules` file |
+
+The CLI auto-detects which tools you're using and installs the right format.
+
+## Included Skills
+
+### Global (all teams)
+- **code-standards** — Naming, file structure, formatting, error handling
+- **git-workflow** — Branching, commits, PRs, releases
+- **security-baseline** — Auth, validation, secrets, XSS, SQL injection
+- **api-design** — REST URLs, status codes, pagination, versioning
+- **testing-standards** — Coverage, AAA pattern, mocking, integration/E2E
+- **documentation** — READMEs, API docs, ADRs, changelogs, runbooks
+- **deployment** — CI/CD, Docker, environments, rollback, feature flags
+
+### Stack-specific
+- **react** — Components, hooks, state management, performance
+- **react-native** — Navigation, FlatList, offline-first, platform code
+- **node-backend** — Layered architecture, DI, error handling, health checks
+- **python-backend** — FastAPI, Pydantic, async patterns, pytest
+- **devops** — Terraform, Kubernetes, monitoring, SLOs, alerting
+
+## Commands
+
+```bash
+npx ai-skills setup    # First-time setup
+npx ai-skills update   # Update to latest skills
+npx ai-skills status   # Check what's installed
+npx ai-skills list     # Show all available skills
+npx ai-skills doctor   # Health check
+```
+
+## Updating
+
+```bash
+# Update the package
+npm update @valentia-ai-skills/framework
+
+# Refresh the installed skills
+npx ai-skills update
+```
+
+## How It Works
+
+1. **Install** — `npm install` adds the package to your project
+2. **Setup** — `npx ai-skills setup` detects your AI tools and writes config files
+3. **Code** — When you use any AI coding tool, it reads those config files and follows the rules
+4. **Update** — `npm update` + `npx ai-skills update` refreshes everything
+
+The skills never touch your application code. They only tell AI tools what conventions to follow.
+
+## For Team Leads
+
+Add this to your project's `package.json` so every developer gets the skills on `npm install`:
+
+```json
+{
+  "devDependencies": {
+    "@valentia-ai-skills/framework": "^1.0.0"
+  },
+  "scripts": {
+    "postinstall": "npx ai-skills setup"
+  }
+}
+```
+
+Now every `git clone` + `npm install` automatically configures AI skills.
+
+## Customization
+
+After setup, a `.ai-skills.json` config file tracks your preferences. The generated rules files can be committed to git so the whole team shares the same setup.
+
+## Contributing
+
+To add or modify skills, edit the SKILL.md files in the `skills/` directory and publish a new package version.

package/bin/cli.js

@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+
+/**
+ * ai-skills CLI
+ * 
+ * Usage:
+ *   npx ai-skills setup          # First-time setup — detects your AI tools and installs skills
+ *   npx ai-skills update         # Pull latest skills into your project
+ *   npx ai-skills status         # Show which skills are installed and which tools are configured
+ *   npx ai-skills list           # List all available skills
+ *   npx ai-skills add <skill>    # Add a specific skill
+ *   npx ai-skills remove <skill> # Remove a specific skill
+ *   npx ai-skills doctor         # Check setup health
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+// ── Constants ──
+
+const SKILLS_SOURCE = path.join(__dirname, "..", "skills");
+const PROJECT_ROOT = process.cwd();
+
+const TOOL_CONFIGS = {
+  "claude-code": {
+    name: "Claude Code",
+    skillsDir: ".claude/skills",
+    rulesFile: null,
+    detect: () => fs.existsSync(path.join(PROJECT_ROOT, ".claude")) || shellHas("claude"),
+    format: "skill-folder", // copies full SKILL.md folder structure
+  },
+  cursor: {
+    name: "Cursor",
+    skillsDir: null,
+    rulesFile: ".cursor/rules/ai-skills.mdc",
+    detect: () =>
+      fs.existsSync(path.join(PROJECT_ROOT, ".cursor")) ||
+      fs.existsSync(path.join(PROJECT_ROOT, ".cursorules")),
+    format: "rules-file", // merges into a single rules file
+  },
+  copilot: {
+    name: "GitHub Copilot",
+    skillsDir: null,
+    rulesFile: ".github/copilot-instructions.md",
+    detect: () =>
+      fs.existsSync(path.join(PROJECT_ROOT, ".github")) ||
+      fs.existsSync(path.join(PROJECT_ROOT, ".github/copilot-instructions.md")),
+    format: "rules-file",
+  },
+  windsurf: {
+    name: "Windsurf",
+    skillsDir: null,
+    rulesFile: ".windsurfrules",
+    detect: () => fs.existsSync(path.join(PROJECT_ROOT, ".windsurfrules")),
+    format: "rules-file",
+  },
+  generic: {
+    name: "Generic (.ai-rules)",
+    skillsDir: null,
+    rulesFile: ".ai-rules",
+    detect: () => true, // always available as fallback
+    format: "rules-file",
+  },
+};
+
+const COLORS = {
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  red: "\x1b[31m",
+  dim: "\x1b[2m",
+  bold: "\x1b[1m",
+  reset: "\x1b[0m",
+};
+
+// ── Helpers ──
+
+function c(color, text) {
+  return `${COLORS[color]}${text}${COLORS.reset}`;
+}
+
+function shellHas(cmd) {
+  try {
+    require("child_process").execSync(`which ${cmd} 2>/dev/null`, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function getAllSkills() {
+  const skills = [];
+  if (!fs.existsSync(SKILLS_SOURCE)) return skills;
+
+  for (const category of ["global", "stack", "onboarding"]) {
+    const catDir = path.join(SKILLS_SOURCE, category);
+    if (!fs.existsSync(catDir)) continue;
+
+    if (category === "onboarding") {
+      if (fs.existsSync(path.join(catDir, "SKILL.md"))) {
+        skills.push({ name: "onboarding", category, path: catDir });
+      }
+      continue;
+    }
+
+    for (const item of fs.readdirSync(catDir)) {
+      const itemPath = path.join(catDir, item);
+      if (fs.statSync(itemPath).isDirectory() && fs.existsSync(path.join(itemPath, "SKILL.md"))) {
+        skills.push({ name: item, category, path: itemPath });
+      }
+    }
+  }
+  return skills;
+}
+
+function readSkillContent(skillPath) {
+  const skillMd = path.join(skillPath, "SKILL.md");
+  if (!fs.existsSync(skillMd)) return null;
+  return fs.readFileSync(skillMd, "utf-8");
+}
+
+function extractSkillRules(content) {
+  // Remove YAML frontmatter
+  const withoutFrontmatter = content.replace(/^---[\s\S]*?---\n*/m, "");
+  return withoutFrontmatter.trim();
+}
+
+function mkdirp(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+function copyDir(src, dest) {
+  mkdirp(dest);
+  for (const item of fs.readdirSync(src)) {
+    const srcItem = path.join(src, item);
+    const destItem = path.join(dest, item);
+    if (item === "tests") continue; // skip test prompts in installed version
+    if (fs.statSync(srcItem).isDirectory()) {
+      copyDir(srcItem, destItem);
+    } else {
+      fs.copyFileSync(srcItem, destItem);
+    }
+  }
+}
+
+function detectTools() {
+  const detected = [];
+  for (const [key, config] of Object.entries(TOOL_CONFIGS)) {
+    if (key === "generic") continue;
+    if (config.detect()) {
+      detected.push(key);
+    }
+  }
+  return detected;
+}
+
+function loadProjectConfig() {
+  const configPath = path.join(PROJECT_ROOT, ".ai-skills.json");
+  if (fs.existsSync(configPath)) {
+    return JSON.parse(fs.readFileSync(configPath, "utf-8"));
+  }
+  return null;
+}
+
+function saveProjectConfig(config) {
+  const configPath = path.join(PROJECT_ROOT, ".ai-skills.json");
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+}
+
+// ── Commands ──
+
+function cmdSetup() {
+  console.log(c("blue", "\n━━━ AI Skills Framework — Setup ━━━\n"));
+
+  // 1. Detect AI tools
+  const tools = detectTools();
+  if (tools.length === 0) {
+    console.log(c("yellow", "No AI coding tools detected in this project."));
+    console.log("Will create a generic .ai-rules file that works with any tool.\n");
+    tools.push("generic");
+  } else {
+    console.log(`Detected AI tools: ${tools.map((t) => c("green", TOOL_CONFIGS[t].name)).join(", ")}\n`);
+  }
+
+  // 2. Get all available skills
+  const allSkills = getAllSkills();
+  const globalSkills = allSkills.filter((s) => s.category === "global");
+  const stackSkills = allSkills.filter((s) => s.category === "stack");
+
+  console.log(`Available skills: ${c("bold", allSkills.length)}`);
+  console.log(`  Global: ${globalSkills.map((s) => s.name).join(", ")}`);
+  console.log(`  Stack:  ${stackSkills.map((s) => s.name).join(", ")}\n`);
+
+  // 3. Install for each detected tool
+  let installedCount = 0;
+
+  for (const toolKey of tools) {
+    const tool = TOOL_CONFIGS[toolKey];
+    console.log(c("yellow", `Setting up for ${tool.name}...`));
+
+    if (tool.format === "skill-folder") {
+      // Claude Code: copy individual SKILL.md folders
+      const skillsDir = path.join(PROJECT_ROOT, tool.skillsDir);
+      for (const skill of allSkills) {
+        const dest = path.join(skillsDir, skill.name);
+        copyDir(skill.path, dest);
+        console.log(`  ${c("green", "✓")} ${skill.name}`);
+        installedCount++;
+      }
+    } else if (tool.format === "rules-file") {
+      // Cursor / Copilot / Windsurf / Generic: merge into single rules file
+      const rulesPath = path.join(PROJECT_ROOT, tool.rulesFile);
+      mkdirp(path.dirname(rulesPath));
+
+      let rulesContent = `# AI Development Skills Framework\n`;
+      rulesContent += `# Auto-generated by @valentia-ai-skills/framework\n`;
+      rulesContent += `# Do not edit manually — run 'npx ai-skills update' to refresh\n`;
+      rulesContent += `# Last updated: ${new Date().toISOString().split("T")[0]}\n\n`;
+
+      for (const skill of allSkills) {
+        const content = readSkillContent(skill.path);
+        if (content) {
+          const rules = extractSkillRules(content);
+          rulesContent += `\n${"=".repeat(60)}\n`;
+          rulesContent += `# SKILL: ${skill.name} (${skill.category})\n`;
+          rulesContent += `${"=".repeat(60)}\n\n`;
+          rulesContent += rules + "\n";
+        }
+      }
+
+      fs.writeFileSync(rulesPath, rulesContent);
+      console.log(`  ${c("green", "✓")} Written to ${tool.rulesFile} (${allSkills.length} skills merged)`);
+      installedCount += allSkills.length;
+    }
+    console.log("");
+  }
+
+  // 4. Save project config
+  const config = {
+    version: "1.0.0",
+    installedAt: new Date().toISOString(),
+    tools,
+    skills: allSkills.map((s) => ({ name: s.name, category: s.category })),
+  };
+  saveProjectConfig(config);
+
+  // 5. Summary
+  console.log(c("blue", "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"));
+  console.log(c("green", `✅ Setup complete!`));
+  console.log(`   ${allSkills.length} skills installed for ${tools.length} tool(s)\n`);
+  console.log(`Config saved to ${c("dim", ".ai-skills.json")}`);
+  console.log(`To update later: ${c("bold", "npx ai-skills update")}`);
+  console.log(`To check status:  ${c("bold", "npx ai-skills status")}\n`);
+}
+
+function cmdUpdate() {
+  console.log(c("blue", "\n━━━ AI Skills Framework — Update ━━━\n"));
+
+  const config = loadProjectConfig();
+  if (!config) {
+    console.log(c("yellow", "No .ai-skills.json found. Run 'npx ai-skills setup' first."));
+    process.exit(1);
+  }
+
+  // Re-run setup with saved tool preferences
+  const tools = config.tools || detectTools();
+  const allSkills = getAllSkills();
+
+  for (const toolKey of tools) {
+    const tool = TOOL_CONFIGS[toolKey];
+    if (!tool) continue;
+
+    console.log(c("yellow", `Updating ${tool.name}...`));
+
+    if (tool.format === "skill-folder") {
+      const skillsDir = path.join(PROJECT_ROOT, tool.skillsDir);
+      for (const skill of allSkills) {
+        const dest = path.join(skillsDir, skill.name);
+        copyDir(skill.path, dest);
+        console.log(`  ${c("green", "✓")} ${skill.name}`);
+      }
+    } else if (tool.format === "rules-file") {
+      const rulesPath = path.join(PROJECT_ROOT, tool.rulesFile);
+      mkdirp(path.dirname(rulesPath));
+
+      let rulesContent = `# AI Development Skills Framework\n`;
+      rulesContent += `# Auto-generated by @valentia-ai-skills/framework\n`;
+      rulesContent += `# Do not edit manually — run 'npx ai-skills update' to refresh\n`;
+      rulesContent += `# Last updated: ${new Date().toISOString().split("T")[0]}\n\n`;
+
+      for (const skill of allSkills) {
+        const content = readSkillContent(skill.path);
+        if (content) {
+          const rules = extractSkillRules(content);
+          rulesContent += `\n${"=".repeat(60)}\n`;
+          rulesContent += `# SKILL: ${skill.name} (${skill.category})\n`;
+          rulesContent += `${"=".repeat(60)}\n\n`;
+          rulesContent += rules + "\n";
+        }
+      }
+
+      fs.writeFileSync(rulesPath, rulesContent);
+      console.log(`  ${c("green", "✓")} ${tool.rulesFile} updated`);
+    }
+  }
+
+  // Update config
+  config.updatedAt = new Date().toISOString();
+  config.skills = allSkills.map((s) => ({ name: s.name, category: s.category }));
+  saveProjectConfig(config);
+
+  console.log(c("green", `\n✅ Updated ${allSkills.length} skills!\n`));
+}
+
+function cmdStatus() {
+  console.log(c("blue", "\n━━━ AI Skills Framework — Status ━━━\n"));
+
+  const config = loadProjectConfig();
+  const allSkills = getAllSkills();
+  const tools = detectTools();
+
+  // Package version
+  const pkg = require(path.join(__dirname, "..", "package.json"));
+  console.log(`Package version: ${c("bold", pkg.version)}`);
+  console.log(`Skills available: ${c("bold", allSkills.length)}`);
+
+  // Installed status
+  if (config) {
+    console.log(`Installed: ${c("green", "Yes")} (${config.installedAt.split("T")[0]})`);
+    if (config.updatedAt) {
+      console.log(`Last updated: ${config.updatedAt.split("T")[0]}`);
+    }
+    console.log(`Tools configured: ${config.tools.map((t) => TOOL_CONFIGS[t]?.name || t).join(", ")}`);
+  } else {
+    console.log(`Installed: ${c("red", "No")} — run 'npx ai-skills setup'`);
+  }
+
+  // Detected tools
+  console.log(`\nDetected AI tools in this project:`);
+  for (const [key, toolConfig] of Object.entries(TOOL_CONFIGS)) {
+    if (key === "generic") continue;
+    const detected = toolConfig.detect();
+    console.log(`  ${detected ? c("green", "●") : c("dim", "○")} ${toolConfig.name}`);
+  }
+
+  // Skill inventory
+  console.log(`\nSkill inventory:`);
+  for (const skill of allSkills) {
+    const content = readSkillContent(skill.path);
+    const versionMatch = content?.match(/version:\s*["']?([^"'\n]+)/);
+    const version = versionMatch ? versionMatch[1].trim() : "?";
+    console.log(`  ${c("green", "✓")} ${skill.name} ${c("dim", `v${version}`)} ${c("dim", `(${skill.category})`)}`);
+  }
+  console.log("");
+}
+
+function cmdList() {
+  const allSkills = getAllSkills();
+  console.log(c("blue", "\n━━━ Available Skills ━━━\n"));
+
+  const categories = {};
+  for (const skill of allSkills) {
+    if (!categories[skill.category]) categories[skill.category] = [];
+    categories[skill.category].push(skill);
+  }
+
+  for (const [cat, skills] of Object.entries(categories)) {
+    console.log(c("yellow", `${cat.toUpperCase()}`));
+    for (const s of skills) {
+      const content = readSkillContent(s.path);
+      const descMatch = content?.match(/description:\s*>?\s*\n?\s*(.+)/);
+      const desc = descMatch ? descMatch[1].trim().slice(0, 70) + "..." : "";
+      console.log(`  ${s.name.padEnd(22)} ${c("dim", desc)}`);
+    }
+    console.log("");
+  }
+}
+
+function cmdDoctor() {
+  console.log(c("blue", "\n━━━ AI Skills — Health Check ━━━\n"));
+
+  let issues = 0;
+  const allSkills = getAllSkills();
+
+  // Check skills source exists
+  if (allSkills.length === 0) {
+    console.log(c("red", "✗ No skills found in package. Package may be corrupted."));
+    issues++;
+  } else {
+    console.log(c("green", `✓ ${allSkills.length} skills found in package`));
+  }
+
+  // Check project config
+  const config = loadProjectConfig();
+  if (!config) {
+    console.log(c("yellow", "⚠ No .ai-skills.json — run 'npx ai-skills setup'"));
+    issues++;
+  } else {
+    console.log(c("green", `✓ Project configured (${config.tools.length} tool(s))`));
+
+    // Check each tool's files exist
+    for (const toolKey of config.tools) {
+      const tool = TOOL_CONFIGS[toolKey];
+      if (!tool) continue;
+
+      if (tool.format === "skill-folder") {
+        const dir = path.join(PROJECT_ROOT, tool.skillsDir);
+        if (fs.existsSync(dir)) {
+          const count = fs.readdirSync(dir).filter(
+            (f) => fs.existsSync(path.join(dir, f, "SKILL.md"))
+          ).length;
+          console.log(c("green", `✓ ${tool.name}: ${count} skills in ${tool.skillsDir}/`));
+        } else {
+          console.log(c("red", `✗ ${tool.name}: ${tool.skillsDir}/ missing`));
+          issues++;
+        }
+      } else if (tool.rulesFile) {
+        const rulesPath = path.join(PROJECT_ROOT, tool.rulesFile);
+        if (fs.existsSync(rulesPath)) {
+          console.log(c("green", `✓ ${tool.name}: ${tool.rulesFile} exists`));
+        } else {
+          console.log(c("red", `✗ ${tool.name}: ${tool.rulesFile} missing`));
+          issues++;
+        }
+      }
+    }
+  }
+
+  console.log(issues === 0
+    ? c("green", "\n✅ Everything looks good!\n")
+    : c("yellow", `\n⚠ ${issues} issue(s) found. Run 'npx ai-skills setup' to fix.\n`)
+  );
+}
+
+// ── Main ──
+
+const command = process.argv[2] || "setup";
+
+switch (command) {
+  case "setup":
+    cmdSetup();
+    break;
+  case "update":
+    cmdUpdate();
+    break;
+  case "status":
+    cmdStatus();
+    break;
+  case "list":
+    cmdList();
+    break;
+  case "doctor":
+    cmdDoctor();
+    break;
+  case "help":
+  case "--help":
+  case "-h":
+    console.log(`
+${c("blue", "AI Skills Framework")}
+
+Usage:
+  npx ai-skills setup           Setup skills for detected AI tools
+  npx ai-skills update          Update skills to latest version
+  npx ai-skills status          Show installed skills and tools
+  npx ai-skills list            List all available skills
+  npx ai-skills doctor          Check setup health
+  npx ai-skills help            Show this help
+
+How it works:
+  1. Install:  npm install --save-dev @valentia-ai-skills/framework
+  2. Setup:    npx ai-skills setup
+  3. Code:     Your AI tools now follow your org's standards
+  4. Update:   npm update @valentia-ai-skills/framework && npx ai-skills update
+`);
+    break;
+  default:
+    console.log(c("red", `Unknown command: ${command}`));
+    console.log("Run 'npx ai-skills help' for usage info.");
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@valentia-ai-skills/framework",
+  "version": "1.0.0",
+  "description": "AI development skills framework — centralized coding standards, security patterns, and SOPs for AI-assisted development. Works with Claude Code, Cursor, Copilot, Windsurf, and any AI coding tool.",
+  "keywords": [
+    "ai-skills",
+    "claude-code",
+    "cursor",
+    "copilot",
+    "windsurf",
+    "coding-standards",
+    "development-framework",
+    "ai-development"
+  ],
+  "author": "Valentia",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codearraydev/valentia-awsome-skills.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ai-skills": "./bin/cli.js"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "setup": "node bin/cli.js setup",
+    "update": "node bin/cli.js update"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/",
+    "scripts/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+/**
+ * Runs after npm install. Prints a friendly message.
+ * Does NOT auto-setup — that's intentional so devs can choose.
+ */
+
+const G = "\x1b[32m";
+const B = "\x1b[34m";
+const R = "\x1b[0m";
+const D = "\x1b[2m";
+
+console.log(`
+${B}━━━ AI Skills Framework installed ━━━${R}
+
+  Run ${G}npx ai-skills setup${R} to configure for your AI tools.
+  ${D}(Claude Code, Cursor, Copilot, Windsurf auto-detected)${R}
+`);