@valentia-ai-skills/framework 2.0.6 → 2.0.7

package/README.md

@@ -70,9 +70,9 @@ 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>
 
-# Download a project's skills from the console → install into your local AI tools
+# Download a project → recreates exact intelligence folder structure (modules/, diagrams/, reports)
 npx ai-skills legacy-projects add "My Project"
-npx ai-skills legacy-projects add "My Project" --path ./output-dir/  # also save raw files locally
+npx ai-skills legacy-projects add "My Project" --path ~/projects/  # save to a specific directory
 
 # List all legacy projects for your team
 npx ai-skills legacy-projects list
@@ -288,8 +288,8 @@ The framework supports ingesting intelligence packages generated by legacy codeb
 1. **Scan** — A compatible scanner tool analyses an existing codebase and produces an intelligence folder
 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. **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
+4. **Download** — Developers run `npx ai-skills legacy-projects add <project-name>` to reconstruct the full intelligence package folder locally — identical structure to the original scan output (`modules/`, `diagrams/`, report `.md` files, `manifest.json`)
+5. **Code** — AI tools (Claude Code, Cursor, Copilot, Windsurf) can now read the local package using the project's legacy-reading skills
 6. **Rescan** — Re-running `upload-legacy-scan` on the same project name replaces all documents with the latest scan output
 
 ### Intelligence Package Format
@@ -348,9 +348,9 @@ Approved skills are promoted into the team's standard toolkit and distributed on
 # 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
+# Download a project → recreates the exact intelligence package folder structure locally
+npx ai-skills legacy-projects add "Clinical Sanctuary"
+npx ai-skills legacy-projects add "Clinical Sanctuary" --path ~/projects/  # save to specific dir
 
 # List all projects with status, module count, and completeness score
 npx ai-skills legacy-projects list

package/bin/cli.js

@@ -1665,22 +1665,33 @@ async function cmdLegacyProjects() {
     console.log(`\n  Console: ${c("dim", p.console_url)}\n`);
 
   } else if (subcommand === "add") {
-    // Download a legacy project's skills from the console and install them
-    // into the developer's local AI tools (Claude Code, Cursor, Copilot, Windsurf).
+    // Download a legacy project from the console and reconstruct the complete
+    // intelligence package folder structure — the exact same layout produced
+    // by the scanner so existing legacy-reading skills can work on it.
+    //
+    // Output:
+    //   <outputDir>/<project-slug>/
+    //     manifest.json
+    //     MASTER_SKILL.md          (master skill, if present)
+    //     modules/<name>/SKILL.md  (module skills)
+    //     diagrams/<name>.mmd
+    //     OVERVIEW.md / API_REGISTRY.md / RISK_REPORT.md … (reports/guides)
+
     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"));
+      console.log(c("red", "Usage: npx ai-skills legacy-projects add <project-name> [--path <output-dir>]"));
+      console.log(c("dim", "  Downloads the project intelligence package and recreates the original folder structure.\n"));
       process.exit(1);
     }
 
-    // Optional --path flag to also save raw files to a local directory
-    let outputPath = null;
+    // --path defaults to current working directory
+    let outputBase = process.cwd();
     for (let i = 1; i < args.length; i++) {
-      if (args[i] === "--path" && args[i + 1]) outputPath = args[++i];
+      if (args[i] === "--path" && args[i + 1]) outputBase = args[++i];
     }
 
-    console.log(c("blue", `\n━━━ Install Legacy Project: ${projectName} ━━━\n`));
+    console.log(c("blue", `\n━━━ Download Legacy Project: ${projectName} ━━━\n`));
+
     let result;
     try {
       result = await fetchJSONWithAuth(MANAGE_LEGACY_PROJECTS_URL, { action: "download", email, project_name: projectName }, null);
@@ -1693,80 +1704,123 @@ async function cmdLegacyProjects() {
     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"));
+      console.log(c("yellow", `No documents found for "${projectName}".\n  Check the project name with:  npx ai-skills legacy-projects list\n`));
       return;
     }
 
-    const skillDocs = documents.filter((d) => d.category === "skill");
-    const reportDocs = documents.filter((d) => d.category === "report" || d.category === "guide");
+    const skillDocs   = documents.filter((d) => d.category === "skill");
+    const reportDocs  = documents.filter((d) => d.category === "report");
+    const guideDocs   = documents.filter((d) => 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);
-        }
+    console.log(`  Project:   ${c("bold", project.name)}`);
+    console.log(`  Status:    ${project.status}  |  ${project.completeness_score}% complete`);
+    console.log(`  Skills:    ${skillDocs.length}   Reports: ${reportDocs.length}   Guides: ${guideDocs.length}   Diagrams: ${diagramDocs.length}\n`);
+
+    // ── Create project root folder ──
+    const projectSlug = project.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    const projectDir = path.resolve(outputBase, `${projectSlug}-intelligence`);
+    mkdirp(projectDir);
+    console.log(`  Saving to: ${c("bold", projectDir)}\n`);
+
+    // ── Skill documents ──
+    const masterDoc = skillDocs.find((d) => d.document_type === "master");
+    const moduleDocs = skillDocs.filter((d) => d.document_type !== "master").sort((a, b) => a.priority - b.priority);
+
+    if (masterDoc) {
+      fs.writeFileSync(path.join(projectDir, "MASTER_SKILL.md"), masterDoc.content);
+      console.log(`  ${c("green", "✓")} MASTER_SKILL.md`);
+    }
+
+    if (moduleDocs.length > 0) {
+      const modulesDir = path.join(projectDir, "modules");
+      mkdirp(modulesDir);
+      for (const doc of moduleDocs) {
+        const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+        const modDir = path.join(modulesDir, safeName);
+        mkdirp(modDir);
+        fs.writeFileSync(path.join(modDir, "SKILL.md"), doc.content);
+        console.log(`  ${c("green", "✓")} modules/${safeName}/SKILL.md`);
       }
+    }
 
-      for (const doc of reportDocs) {
-        const fileName = doc.document_type.toUpperCase() + ".md";
-        fs.writeFileSync(path.join(resolved, fileName), doc.content);
-      }
+    // ── Report & guide documents — write as DOCUMENT_TYPE.md at root ──
+    const REPORT_FILENAMES = {
+      api_registry:       "API_REGISTRY.md",
+      business_rules:     "BUSINESS_RULES.md",
+      data_models:        "DATA_MODELS.md",
+      dependencies:       "DEPENDENCIES.md",
+      env_config:         "ENV_CONFIG.md",
+      risk_report:        "RISK_REPORT.md",
+      glossary:           "GLOSSARY.md",
+      overview:           "OVERVIEW.md",
+      reproduction_guide: "REPRODUCTION_GUIDE.md",
+    };
 
-      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);
-        }
+    for (const doc of [...reportDocs, ...guideDocs]) {
+      const fileName = REPORT_FILENAMES[doc.document_type] || (doc.document_type.toUpperCase() + ".md");
+      fs.writeFileSync(path.join(projectDir, fileName), doc.content);
+      console.log(`  ${c("green", "✓")} ${fileName}`);
+    }
+
+    // ── Diagram documents ──
+    if (diagramDocs.length > 0) {
+      const diagramsDir = path.join(projectDir, "diagrams");
+      mkdirp(diagramsDir);
+      for (const doc of diagramDocs) {
+        const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+        const ext = doc.document_type === "mermaid" ? "mmd" : "mmd";
+        const diagramFile = `${safeName}.${ext}`;
+        fs.writeFileSync(path.join(diagramsDir, diagramFile), doc.content);
+        console.log(`  ${c("green", "✓")} diagrams/${diagramFile}`);
       }
+    }
 
-      console.log(`  ${c("green", "✓")} Raw files saved to: ${c("bold", resolved)}\n`);
+    // ── Reconstruct manifest.json ──
+    const manifestSkills = [];
+    if (masterDoc) {
+      manifestSkills.push({ name: masterDoc.name, type: "master", file: "MASTER_SKILL.md" });
     }
+    for (const doc of moduleDocs) {
+      const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+      manifestSkills.push({ name: doc.name, type: "module", file: `modules/${safeName}/SKILL.md` });
+    }
+
+    const manifestDiagrams = diagramDocs.map((doc) => {
+      const safeName = doc.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+      return { name: doc.name, file: `diagrams/${safeName}.mmd`, type: doc.document_type };
+    });
 
-    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`);
+    const manifestReports = {};
+    for (const doc of [...reportDocs, ...guideDocs]) {
+      const fileName = REPORT_FILENAMES[doc.document_type] || (doc.document_type.toUpperCase() + ".md");
+      manifestReports[doc.document_type] = fileName;
+    }
+
+    const manifest = {
+      project: project.name,
+      scanned_at: project.last_scanned_at || new Date().toISOString(),
+      downloaded_at: new Date().toISOString(),
+      source: "valentia-skills-console",
+      tech_stack: project.tech_stack || {},
+      skills: manifestSkills,
+      diagrams: manifestDiagrams,
+      reports: manifestReports,
+      statistics: {
+        total_modules: moduleDocs.length,
+        total_diagrams: diagramDocs.length,
+        completeness_score: project.completeness_score,
+      },
+    };
+    fs.writeFileSync(path.join(projectDir, "manifest.json"), JSON.stringify(manifest, null, 2) + "\n");
+    console.log(`  ${c("green", "✓")} manifest.json`);
+
+    console.log(c("green", `\n✓ "${project.name}" downloaded — ${documents.length} file(s)\n`));
+    console.log(`  Folder: ${c("bold", projectDir)}`);
+    if (project.console_url) {
+      console.log(`  Console: ${c("dim", project.console_url)}`);
     }
+    console.log("");
     return;
 
   } else if (subcommand === "remove") {
@@ -1824,8 +1878,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 <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 add <name>             Download project → recreate intelligence folder locally
+  npx ai-skills legacy-projects add <name> --path <dir> Save to a specific directory (default: cwd)
   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.6",
+  "version": "2.0.7",
   "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",