@valentia-ai-skills/framework 2.0.5 → 2.0.6

package/README.md

@@ -65,14 +65,14 @@ npx ai-skills help           # Show help
 #### Legacy Codebase Intelligence Scanner
 
 ```bash
-# Add / refresh a project by uploading a scan intelligence package
-npx ai-skills legacy-projects add --path ./my-project-intelligence/
+# Upload a scan package to the Skills Console (creates or refreshes the project)
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --dry-run   # validate only
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/ --token <token>
 
-# Validate the payload without uploading (dry run)
-npx ai-skills legacy-projects add --path ./my-project-intelligence/ --dry-run
-
-# Supply an explicit auth token instead of going through OTP
-npx ai-skills legacy-projects add --path ./my-project-intelligence/ --token <your-token>
+# Download a project's skills from the console → install into your local AI tools
+npx ai-skills legacy-projects add "My Project"
+npx ai-skills legacy-projects add "My Project" --path ./output-dir/  # also save raw files locally
 
 # List all legacy projects for your team
 npx ai-skills legacy-projects list
@@ -84,10 +84,7 @@ npx ai-skills legacy-projects status "My Project"
 npx ai-skills legacy-projects remove "My Project"
 ```
 
-> `upload-legacy-scan` is also available as a direct alias:
-> `npx ai-skills upload-legacy-scan --path ./my-project-intelligence/`
-
-The `--path` directory must contain a `manifest.json` file. See the [Legacy Scanner](#legacy-codebase-intelligence-scanner) section below for the required format.
+The `--path` directory for `upload-legacy-scan` must contain a `manifest.json` file. See the [Legacy Scanner](#legacy-codebase-intelligence-scanner) section below for the required format.
 
 ### Environment Variables
 
@@ -289,10 +286,11 @@ The framework supports ingesting intelligence packages generated by legacy codeb
 ### How It Works
 
 1. **Scan** — A compatible scanner tool analyses an existing codebase and produces an intelligence folder
-2. **Add** — `npx ai-skills legacy-projects add --path <folder>` uploads the package, creating the project if it doesn't exist or replacing its documents if it does
+2. **Upload** — `npx ai-skills upload-legacy-scan --path <folder>` ships the intelligence package to your team's Skills Console, creating or refreshing the project
 3. **Review** — Tech leads review auto-generated skills, reports, and diagrams in the Skills Console, approving or flagging each document
-4. **Promote** — Approved skills are promoted into the team's active toolkit and distributed on the next `npx ai-skills update`
-5. **Rescan** — Re-running `add` on the same project name replaces all documents with the latest scan output
+4. **Install** — Developers run `npx ai-skills legacy-projects add <project-name>` to download approved skills from the console and have them installed into their local AI tools automatically
+5. **Code** — AI tools (Claude Code, Cursor, Copilot, Windsurf) now have full context about the legacy project's patterns
+6. **Rescan** — Re-running `upload-legacy-scan` on the same project name replaces all documents with the latest scan output
 
 ### Intelligence Package Format
 
@@ -347,8 +345,12 @@ Approved skills are promoted into the team's standard toolkit and distributed on
 ### Managing Projects from the CLI
 
 ```bash
-# Add a new project (or refresh an existing one)
-npx ai-skills legacy-projects add --path ./my-project-intelligence/
+# Upload a scan package (add new project or replace existing)
+npx ai-skills upload-legacy-scan --path ./my-project-intelligence/
+
+# Download a project's skills and install them into your local AI tools
+npx ai-skills legacy-projects add "My Project"
+npx ai-skills legacy-projects add "My Project" --path ./output/  # also write raw files locally
 
 # List all projects with status, module count, and completeness score
 npx ai-skills legacy-projects list

package/bin/cli.js

@@ -1665,8 +1665,108 @@ async function cmdLegacyProjects() {
     console.log(`\n  Console: ${c("dim", p.console_url)}\n`);
 
   } else if (subcommand === "add") {
-    // Delegate to upload-legacy-scan — argv flags (--path, --dry-run, --token) are preserved
-    await cmdUploadLegacyScan();
+    // Download a legacy project's skills from the console and install them
+    // into the developer's local AI tools (Claude Code, Cursor, Copilot, Windsurf).
+    const projectName = args[0];
+    if (!projectName) {
+      console.log(c("red", "Usage: npx ai-skills legacy-projects add <project-name> [--path <dir>]"));
+      console.log(c("dim", "  Downloads the project's skills from the console and installs them into your AI tools.\n"));
+      process.exit(1);
+    }
+
+    // Optional --path flag to also save raw files to a local directory
+    let outputPath = null;
+    for (let i = 1; i < args.length; i++) {
+      if (args[i] === "--path" && args[i + 1]) outputPath = args[++i];
+    }
+
+    console.log(c("blue", `\n━━━ Install Legacy Project: ${projectName} ━━━\n`));
+    let result;
+    try {
+      result = await fetchJSONWithAuth(MANAGE_LEGACY_PROJECTS_URL, { action: "download", email, project_name: projectName }, null);
+    } catch (err) {
+      console.log(c("red", `✗ ${err.message}`));
+      process.exit(1);
+    }
+
+    const project = result.project;
+    const documents = result.documents || [];
+
+    if (documents.length === 0) {
+      console.log(c("yellow", "No documents found for this project.\n  Check the project name or upload a scan first with:\n  npx ai-skills upload-legacy-scan --path <dir>\n"));
+      return;
+    }
+
+    const skillDocs = documents.filter((d) => d.category === "skill");
+    const reportDocs = documents.filter((d) => d.category === "report" || d.category === "guide");
+    const diagramDocs = documents.filter((d) => d.category === "diagram");
+
+    console.log(`  Project:  ${c("bold", project.name)}`);
+    console.log(`  Status:   ${project.status}  |  ${project.completeness_score}% complete`);
+    console.log(`  Skills:   ${skillDocs.length}   Reports: ${reportDocs.length}   Diagrams: ${diagramDocs.length}\n`);
+
+    // ── Install skill documents into local AI tools ──
+    if (skillDocs.length > 0) {
+      const tools = detectTools();
+      if (tools.length === 0) {
+        console.log(c("yellow", "  ⚠  No AI tools detected — install Claude Code, Cursor, Copilot, or Windsurf first.\n"));
+      } else {
+        // Build skill objects in the format installSkillsForTool expects
+        const skills = skillDocs.map((doc) => ({
+          name: `legacy-${doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}`,
+          scope: "global",  // global so filterSkillsForProject passes them through
+          content: doc.content,
+        }));
+
+        console.log(`  Installing into detected AI tools:\n`);
+        for (const toolKey of tools) {
+          const tool = TOOL_CONFIGS[toolKey];
+          const count = installSkillsForTool(toolKey, skills);
+          console.log(`    ${c("green", "✓")} ${tool.name}: ${count} skill(s)`);
+        }
+        console.log("");
+      }
+    } else {
+      console.log(c("dim", "  No skills in this project (reports/diagrams only).\n"));
+    }
+
+    // ── Optionally save the full raw package to --path ──
+    if (outputPath) {
+      const resolved = path.resolve(outputPath);
+      mkdirp(resolved);
+
+      if (skillDocs.length > 0) {
+        const modulesDir = path.join(resolved, "modules");
+        mkdirp(modulesDir);
+        for (const doc of skillDocs) {
+          const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+          const docDir = path.join(modulesDir, safeName);
+          mkdirp(docDir);
+          fs.writeFileSync(path.join(docDir, "SKILL.md"), doc.content);
+        }
+      }
+
+      for (const doc of reportDocs) {
+        const fileName = doc.document_type.toUpperCase() + ".md";
+        fs.writeFileSync(path.join(resolved, fileName), doc.content);
+      }
+
+      if (diagramDocs.length > 0) {
+        const diagramsDir = path.join(resolved, "diagrams");
+        mkdirp(diagramsDir);
+        for (const doc of diagramDocs) {
+          const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+          fs.writeFileSync(path.join(diagramsDir, `${safeName}.mmd`), doc.content);
+        }
+      }
+
+      console.log(`  ${c("green", "✓")} Raw files saved to: ${c("bold", resolved)}\n`);
+    }
+
+    console.log(c("green", `✓ "${project.name}" is ready. Restart your AI tool to activate the skills.\n`));
+    if (result.project?.console_url) {
+      console.log(`  Console: ${c("dim", result.project.console_url)}\n`);
+    }
     return;
 
   } else if (subcommand === "remove") {
@@ -1695,7 +1795,7 @@ async function cmdLegacyProjects() {
 
   } else {
     console.log(c("red", `Unknown subcommand: ${subcommand}`));
-    console.log(c("dim", "Usage: npx ai-skills legacy-projects add --path <dir> | list | status <name> | remove <name>\n"));
+    console.log(c("dim", "Usage: npx ai-skills legacy-projects add <name> | list | status <name> | remove <name>\n"));
     process.exit(1);
   }
 }
@@ -1724,7 +1824,8 @@ Usage:
   npx ai-skills list     List locally bundled skills
   npx ai-skills analyze  Analyze last commit against active skills
   npx ai-skills upload-legacy-scan  Upload a legacy codebase intelligence package
-  npx ai-skills legacy-projects add --path <dir>   Upload a scan package and add / refresh the project
+  npx ai-skills legacy-projects add <name>             Download project skills → install into AI tools
+  npx ai-skills legacy-projects add <name> --path <dir> Also save raw files to a local directory
   npx ai-skills legacy-projects list               List all legacy projects
   npx ai-skills legacy-projects status <name>      Show project status and document counts
   npx ai-skills legacy-projects remove <name>      Delete a project and all its documents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@valentia-ai-skills/framework",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "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",