code-ia-sota 0.1.0 → 0.1.1

package/README.md

@@ -10,6 +10,55 @@ npx code-ia-sota
 
 Installs the canonical `AGENTS.md` and `.agents/` scaffold into the current directory.
 
+This installer is intentionally a personal bootstrap. It clones the current scaffold state from the GitHub repository at install time instead of pinning a packaged template snapshot.
+
+By default, the installer opens a tool selector inspired by OpenSpec so you can generate lightweight integrations for supported CLIs/IDEs on top of the base scaffold. In CI or GitHub Actions, it falls back to `codex` unless `--tools` is passed explicitly.
+
+Supported tool ids:
+
+- `codex`
+- `claude`
+- `cursor`
+- `windsurf`
+
+Non-interactive examples:
+
+```sh
+# Base scaffold only
+npx code-ia-sota --tools none
+
+# Install base scaffold plus Claude + Cursor shims
+npx code-ia-sota --tools claude,cursor
+
+# Install every supported integration
+npx code-ia-sota --tools all
+
+# List supported tool ids
+npx code-ia-sota --list-tools
+```
+
+Generated integrations:
+
+- `claude` -> `CLAUDE.md`
+- `cursor` -> `.cursor/rules/code-ia-sota.mdc`
+- `windsurf` -> `.windsurf/rules/code-ia-sota.md`
+- `codex` -> no extra file; uses the root scaffold directly
+
+## Harness validation
+
+```sh
+npm run validate:harness
+```
+
+Validates `.agents/skills/*/SKILL.md` and `.agents/workflows/*.md`.
+The local npm script validates the repository root from the CLI package directory.
+
+You can also run:
+
+```sh
+code-ia-sota validate [path]
+```
+
 ## Local development
 
 ```sh
@@ -22,5 +71,13 @@ code-ia-sota
 
 ```sh
 npm pack
-npx ./code-ia-sota-0.1.0.tgz
+npx ./code-ia-sota-0.1.1.tgz
 ```
+
+## GitHub Actions publish
+
+The repository workflow `.github/workflows/publish-cli.yml` publishes the package from `code-ia-sota-cli/` on pushes to `main` that change the CLI files, or by manual dispatch.
+
+Required secret:
+
+- `NPM_TOKEN` with publish permission for the `code-ia-sota` package on npm

package/bin/code-ia-sota.js

@@ -4,6 +4,7 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import process from "node:process";
+import readline from "node:readline/promises";
 
 import fsExtra from "fs-extra";
 import simpleGit from "simple-git";
@@ -13,6 +14,118 @@ const REPO_URL =
   "https://github.com/wolfox33/Code_IA_SotA.git";
 
 const TARGET_DIR = process.cwd();
+const MANAGED_FILE_MARKER =
+  "Generated by code-ia-sota";
+const SUPPORTED_TOOLS = [
+  {
+    id: "codex",
+    label: "Codex",
+    description:
+      "Uses the root AGENTS.md and .agents scaffold directly.",
+    detectPaths: [
+      ".codex"
+    ],
+    files: []
+  },
+  {
+    id: "claude",
+    label: "Claude Code",
+    description:
+      "Creates a root CLAUDE.md shim that points to AGENTS.md and .agents.",
+    detectPaths: [
+      "CLAUDE.md",
+      ".claude"
+    ],
+    files: [
+      {
+        relativePath: "CLAUDE.md",
+        content: [
+          "# Code IA Sota",
+          "",
+          "Use `AGENTS.md` at the repository root as the canonical project policy.",
+          "",
+          "Load additional context on demand from:",
+          "- `.agents/project/context.md`",
+          "- `.agents/USER.md`",
+          "- `.agents/project/MEMORY.md`",
+          "- `.agents/workflows/`",
+          "- `.agents/skills/`",
+          "",
+          "Prefer the smallest correct change, preserve the existing architecture, and do not expand scope silently.",
+          "",
+          `<!-- ${MANAGED_FILE_MARKER}: claude -->`
+        ].join("\n")
+      }
+    ]
+  },
+  {
+    id: "cursor",
+    label: "Cursor",
+    description:
+      "Creates an always-on Cursor rule that points to AGENTS.md and .agents.",
+    detectPaths: [
+      ".cursor"
+    ],
+    files: [
+      {
+        relativePath: path.join(".cursor", "rules", "code-ia-sota.mdc"),
+        content: [
+          "---",
+          "description: Code IA Sota project policy",
+          "alwaysApply: true",
+          "---",
+          "",
+          "Use `AGENTS.md` at the repository root as the canonical project policy.",
+          "",
+          "Load additional context on demand from `.agents/project/context.md`, `.agents/USER.md`, `.agents/project/MEMORY.md`, `.agents/workflows/`, and `.agents/skills/`.",
+          "",
+          "Prefer the smallest correct change, preserve the existing architecture, and do not expand scope silently.",
+          "",
+          `<!-- ${MANAGED_FILE_MARKER}: cursor -->`
+        ].join("\n")
+      }
+    ]
+  },
+  {
+    id: "windsurf",
+    label: "Windsurf",
+    description:
+      "Creates a workspace rule file that points Cascade to AGENTS.md and .agents.",
+    detectPaths: [
+      ".windsurf",
+      ".windsurfrules"
+    ],
+    files: [
+      {
+        relativePath: path.join(".windsurf", "rules", "code-ia-sota.md"),
+        content: [
+          "# Code IA Sota",
+          "",
+          "Use `AGENTS.md` at the repository root as the canonical project policy.",
+          "",
+          "Load additional context on demand from `.agents/project/context.md`, `.agents/USER.md`, `.agents/project/MEMORY.md`, `.agents/workflows/`, and `.agents/skills/`.",
+          "",
+          "Prefer the smallest correct change, preserve the existing architecture, and do not expand scope silently.",
+          "",
+          `<!-- ${MANAGED_FILE_MARKER}: windsurf -->`
+        ].join("\n")
+      }
+    ]
+  }
+];
+
+const REQUIRED_OPERATIONAL_SKILL_SECTIONS = [
+  ["Objetivo", "Objective"],
+  ["Use this skill when"],
+  ["Do not use this skill when"],
+  ["Output contracts", "Output esperado"],
+  ["Procedure", "Processo", "Review dimensions", "Diagnostic dimensions"],
+  ["Verification"]
+];
+
+const DENSITY_THRESHOLD = parseInt(process.env.HARNESS_DENSITY_THRESHOLD || "30", 10);
+const FAIL_ON_WARNINGS = process.env.HARNESS_FAIL_ON_WARNINGS === "true";
+const ALERT_THRESHOLD = parseInt(process.env.HARNESS_ALERT_THRESHOLD || "10", 10);
 
 async function exists(filePath) {
   try {
@@ -23,6 +136,211 @@ async function exists(filePath) {
   }
 }
 
+function parseFlagValue(flagName) {
+  const args = process.argv.slice(2);
+  const index = args.findIndex((arg) => arg === flagName);
+
+  if (index === -1) {
+    return null;
+  }
+
+  return args[index + 1] || null;
+}
+
+function listSupportedTools() {
+  for (const tool of SUPPORTED_TOOLS) {
+    console.log(
+      `  ${tool.id.padEnd(8)} ${tool.label} - ${tool.description}`
+    );
+  }
+}
+
+function resolveToolSelection(rawValue) {
+  if (!rawValue) {
+    return null;
+  }
+
+  const normalizedValue = rawValue.trim().toLowerCase();
+
+  if (normalizedValue === "all") {
+    return SUPPORTED_TOOLS.map((tool) => tool.id);
+  }
+
+  if (normalizedValue === "none") {
+    return [];
+  }
+
+  const selectedToolIds = [];
+  const seen = new Set();
+
+  for (const token of normalizedValue.split(",")) {
+    const value = token.trim();
+
+    if (!value) {
+      continue;
+    }
+
+    let toolId = value;
+    if (/^\d+$/.test(value)) {
+      const index = parseInt(value, 10) - 1;
+      toolId = SUPPORTED_TOOLS[index]?.id;
+    }
+
+    if (!toolId || !SUPPORTED_TOOLS.some((tool) => tool.id === toolId)) {
+      const availableTools = SUPPORTED_TOOLS.map((tool) => tool.id).join(", ");
+      throw new Error(
+        `Unknown tool "${value}". Use one of: ${availableTools}, all, none`
+      );
+    }
+
+    if (!seen.has(toolId)) {
+      seen.add(toolId);
+      selectedToolIds.push(toolId);
+    }
+  }
+
+  return selectedToolIds;
+}
+
+async function detectTools() {
+  const detectedToolIds = [];
+
+  for (const tool of SUPPORTED_TOOLS) {
+    for (const detectPath of tool.detectPaths) {
+      if (await exists(path.join(TARGET_DIR, detectPath))) {
+        detectedToolIds.push(tool.id);
+        break;
+      }
+    }
+  }
+
+  return detectedToolIds;
+}
+
+async function promptToolSelection() {
+  const detectedToolIds = await detectTools();
+
+  console.log(pc.cyan("Select CLI/IDE integrations to install."));
+  console.log("Press Enter to accept detected tools, or type comma-separated ids/numbers.");
+  console.log("Use `all` to install every integration or `none` to skip tool-specific files.");
+  console.log("");
+
+  for (const [index, tool] of SUPPORTED_TOOLS.entries()) {
+    const marker = detectedToolIds.includes(tool.id) ? "[x]" : "[ ]";
+    console.log(
+      `  ${index + 1}. ${marker} ${tool.id.padEnd(8)} ${tool.label} - ${tool.description}`
+    );
+  }
+
+  console.log("");
+
+  if (detectedToolIds.length > 0) {
+    console.log(
+      `Detected tools: ${detectedToolIds.join(", ")}`
+    );
+  } else {
+    console.log("Detected tools: none");
+    console.log("Default on empty input: codex (base scaffold only)");
+  }
+
+  console.log("");
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    const answer = await rl.question("Tools> ");
+
+    if (!answer.trim()) {
+      if (detectedToolIds.length > 0) {
+        return detectedToolIds;
+      }
+
+      return ["codex"];
+    }
+
+    return resolveToolSelection(answer);
+  } finally {
+    rl.close();
+  }
+}
+
+async function selectTools() {
+  if (process.argv.includes("--list-tools")) {
+    console.log(pc.bold(pc.green("Supported tools")));
+    listSupportedTools();
+    process.exit(0);
+  }
+
+  const toolsArg = parseFlagValue("--tools");
+  const selectedTools = resolveToolSelection(toolsArg);
+
+  if (selectedTools !== null) {
+    return selectedTools;
+  }
+
+  if (process.env.CI === "true" || process.env.GITHUB_ACTIONS === "true") {
+    return ["codex"];
+  }
+
+  return promptToolSelection();
+}
+
+async function writeManagedFile(filePath, content) {
+  if (!(await exists(filePath))) {
+    await fs.mkdir(path.dirname(filePath), {
+      recursive: true
+    });
+    await fs.writeFile(filePath, content, "utf8");
+    return "created";
+  }
+
+  const currentContent = await fs.readFile(filePath, "utf8");
+
+  if (currentContent === content) {
+    return "unchanged";
+  }
+
+  if (!currentContent.includes(MANAGED_FILE_MARKER)) {
+    return "skipped";
+  }
+
+  await fs.writeFile(filePath, content, "utf8");
+  return "updated";
+}
+
+async function installToolIntegrations(selectedToolIds) {
+  const summary = {
+    created: [],
+    updated: [],
+    skipped: []
+  };
+
+  for (const toolId of selectedToolIds) {
+    const tool = SUPPORTED_TOOLS.find((item) => item.id === toolId);
+    if (!tool) {
+      continue;
+    }
+
+    for (const file of tool.files) {
+      const targetPath = path.join(TARGET_DIR, file.relativePath);
+      const result = await writeManagedFile(targetPath, `${file.content}\n`);
+
+      if (result === "created") {
+        summary.created.push(file.relativePath);
+      } else if (result === "updated") {
+        summary.updated.push(file.relativePath);
+      } else if (result === "skipped") {
+        summary.skipped.push(file.relativePath);
+      }
+    }
+  }
+
+  return summary;
+}
+
 async function cloneTemplate(tmpDir) {
   console.log(pc.cyan("Downloading template..."));
 
@@ -82,7 +400,942 @@ async function copyFiles(tmpDir) {
   }
 }
 
+function parseFrontmatter(content) {
+  const normalizedContent = content.replace(/\r\n/g, "\n");
+
+  if (!normalizedContent.startsWith("---\n")) {
+    return null;
+  }
+
+  const endIndex = normalizedContent.indexOf("\n---", 4);
+
+  if (endIndex === -1) {
+    return null;
+  }
+
+  const raw = normalizedContent.slice(4, endIndex).trim();
+  const data = {};
+
+  for (const line of raw.split("\n")) {
+    const match = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+
+    if (match) {
+      data[match[1]] = match[2].replace(/^["']|["']$/g, "");
+    }
+  }
+
+  return {
+    data,
+    body: normalizedContent.slice(endIndex + 5).trim()
+  };
+}
+
+function hasSection(content, sectionNames) {
+  const names = Array.isArray(sectionNames) ? sectionNames : [sectionNames];
+
+  return names.some((sectionName) => {
+    const escaped = sectionName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const pattern = new RegExp(`^#{1,6}\\s+${escaped}\\s*$`, "im");
+
+    return pattern.test(content);
+  });
+}
+
+function addFailure(failures, rootDir, filePath, reason) {
+  failures.push({
+    filePath: path.relative(rootDir, filePath),
+    reason
+  });
+}
+
+function addWarning(warnings, rootDir, filePath, reason) {
+  warnings.push({
+    filePath: path.relative(rootDir, filePath),
+    reason
+  });
+}
+
+async function listMarkdownFiles(dirPath) {
+  if (!(await exists(dirPath))) {
+    return [];
+  }
+
+  const entries = await fs.readdir(dirPath, {
+    withFileTypes: true
+  });
+
+  return entries
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md") && entry.name !== "README.md")
+    .map((entry) => path.join(dirPath, entry.name));
+}
+
+async function listSkillFiles(skillsDir) {
+  if (!(await exists(skillsDir))) {
+    return [];
+  }
+
+  const entries = await fs.readdir(skillsDir, {
+    withFileTypes: true
+  });
+
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(skillsDir, entry.name, "SKILL.md"));
+}
+
+function calculateDensity(content) {
+  const lines = content.split("\n").filter(line => line.trim().length > 0);
+  const totalLines = lines.length;
+
+  const procedureMatch = content.match(/^##\s+Procedure/im);
+  if (!procedureMatch) {
+    return 0;
+  }
+
+  const procedureIndex = procedureMatch.index;
+  const nextSectionMatch = content.slice(procedureIndex + procedureMatch[0].length).match(/^##\s+/im);
+  const endIndex = nextSectionMatch ? procedureIndex + nextSectionMatch.index : content.length;
+
+  const procedureContent = content.slice(procedureIndex, endIndex);
+  const procedureLines = procedureContent.split("\n").filter(line => line.trim().length > 0).length;
+
+  return Math.round((procedureLines / totalLines) * 100);
+}
+
+async function validateSkill(rootDir, filePath, failures, warnings) {
+  if (!(await exists(filePath))) {
+    addFailure(failures, rootDir, filePath, "SKILL.md is missing.");
+    return;
+  }
+
+  const content = await fs.readFile(filePath, "utf8");
+  const frontmatter = parseFrontmatter(content);
+
+  if (!frontmatter) {
+    addFailure(failures, rootDir, filePath, "YAML frontmatter is missing or invalid.");
+    return;
+  }
+
+  if (!frontmatter.data.name) {
+    addFailure(failures, rootDir, filePath, "frontmatter field `name` is missing.");
+  }
+
+  if (!frontmatter.data.description) {
+    addFailure(failures, rootDir, filePath, "frontmatter field `description` is missing.");
+  }
+
+  if (/placeholder/i.test(frontmatter.data.description || "")) {
+    addFailure(failures, rootDir, filePath, "placeholder description is not allowed.");
+  }
+
+  for (const sectionGroup of REQUIRED_OPERATIONAL_SKILL_SECTIONS) {
+    if (!hasSection(content, sectionGroup)) {
+      addWarning(warnings, rootDir, filePath, `operational section group \`${sectionGroup.join(" | ")}\` is missing.`);
+    }
+  }
+
+  const density = calculateDensity(content);
+  if (density < DENSITY_THRESHOLD) {
+    addWarning(warnings, rootDir, filePath, `Low density (<${DENSITY_THRESHOLD}%): ${density}% density. Consider moving reference content to references/ and adding executable procedure.`);
+  }
+}
+
+async function validateWorkflow(rootDir, filePath, failures) {
+  const content = await fs.readFile(filePath, "utf8");
+  const frontmatter = parseFrontmatter(content);
+
+  if (!frontmatter) {
+    addFailure(failures, rootDir, filePath, "YAML frontmatter is missing or invalid.");
+    return;
+  }
+
+  if (!frontmatter.data.description) {
+    addFailure(failures, rootDir, filePath, "frontmatter field `description` is missing.");
+  }
+
+  if (!frontmatter.body) {
+    addFailure(failures, rootDir, filePath, "workflow body is empty.");
+  }
+}
+
+async function validateHarness(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const skillsDir = path.join(agentsDir, "skills");
+  const workflowsDir = path.join(agentsDir, "workflows");
+  const failures = [];
+  const warnings = [];
+  const skillFiles = await listSkillFiles(skillsDir);
+  const workflowFiles = await listMarkdownFiles(workflowsDir);
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Validating harness..."));
+
+  for (const filePath of skillFiles) {
+    await validateSkill(rootDir, filePath, failures, warnings);
+  }
+
+  for (const filePath of workflowFiles) {
+    await validateWorkflow(rootDir, filePath, failures);
+  }
+
+  console.log("");
+  console.log(`Checked ${skillFiles.length} skills.`);
+  console.log(`Checked ${workflowFiles.length} workflows.`);
+
+  if (warnings.length > 0) {
+    console.log("");
+    console.warn(pc.yellow(`Validation completed with ${warnings.length} warning(s):`));
+
+    for (const warning of warnings) {
+      console.warn(`  ${warning.filePath}: ${warning.reason}`);
+    }
+
+    if (FAIL_ON_WARNINGS) {
+      console.log("");
+      console.error(pc.red(`Validation failed due to warnings (FAIL_ON_WARNINGS=true).`));
+      process.exitCode = 1;
+      return;
+    }
+  }
+
+  if (failures.length > 0) {
+    console.log("");
+    console.error(pc.red(`Validation failed with ${failures.length} issue(s):`));
+
+    for (const failure of failures) {
+      console.error(`  ${failure.filePath}: ${failure.reason}`);
+    }
+
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log("");
+  console.log(pc.green("Validation passed."));
+}
+
+async function analyzeReferenceContent(content) {
+  const suggestions = [];
+
+  const sections = content.split(/^##\s+/m);
+  for (const section of sections) {
+    if (!section.trim()) continue;
+
+    const lines = section.split("\n");
+    const sectionName = lines[0].trim();
+    const sectionContent = lines.slice(1).join("\n");
+
+    const hasExternalLinks = /https?:\/\//.test(sectionContent);
+    const hasLongLists = sectionContent.split("\n").filter(line => /^[-*]\s/.test(line)).length > 5;
+    const hasCodeBlocks = /```[\s\S]*```/.test(sectionContent);
+    const isLongSection = sectionContent.split("\n").length > 20;
+
+    if (hasExternalLinks || hasLongLists || (isLongSection && !hasCodeBlocks)) {
+      suggestions.push({
+        section: sectionName,
+        reason: hasExternalLinks ? "contains external links" : hasLongLists ? "has long lists" : "is long without code blocks",
+        action: "consider moving reference content to references/"
+      });
+    }
+  }
+
+  return suggestions;
+}
+
+async function suggestRefactor(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const skillsDir = path.join(agentsDir, "skills");
+  const skillFiles = await listSkillFiles(skillsDir);
+  const suggestions = [];
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Analyzing low-density skills for refactoring suggestions..."));
+  console.log("");
+
+  for (const filePath of skillFiles) {
+    if (!(await exists(filePath))) continue;
+
+    const content = await fs.readFile(filePath, "utf8");
+    const density = calculateDensity(content);
+
+    if (density < DENSITY_THRESHOLD) {
+      const referenceSuggestions = await analyzeReferenceContent(content);
+      const skillName = path.basename(path.dirname(filePath));
+
+      suggestions.push({
+        skill: skillName,
+        density: density,
+        filePath: path.relative(rootDir, filePath),
+        suggestions: referenceSuggestions
+      });
+    }
+  }
+
+  suggestions.sort((a, b) => a.density - b.density);
+
+  if (suggestions.length === 0) {
+    console.log(pc.green("No low-density skills found. All skills meet the density threshold."));
+    return;
+  }
+
+  console.log(`Found ${suggestions.length} low-density skill(s):`);
+  console.log("");
+
+  for (const suggestion of suggestions) {
+    console.log(pc.yellow(`Skill: ${suggestion.skill} (${suggestion.density}% density)`));
+    console.log(`  File: ${suggestion.filePath}`);
+
+    if (suggestion.suggestions.length > 0) {
+      console.log("  Refactoring suggestions:");
+      for (const ref of suggestion.suggestions) {
+        console.log(`    - Section "${ref.section}": ${ref.reason}. ${ref.action}`);
+      }
+    } else {
+      console.log("  No specific sections identified. Consider expanding the Procedure section.");
+    }
+
+    console.log("");
+  }
+
+  console.log(pc.cyan("To refactor:"));
+  console.log("  1. Review the suggestions above");
+  console.log("  2. Move reference content to references/");
+  console.log("  3. Expand the Procedure section with executable steps");
+  console.log("  4. Re-run validation to check improved density");
+}
+
+async function benchmarkDensity(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const skillsDir = path.join(agentsDir, "skills");
+  const skillFiles = await listSkillFiles(skillsDir);
+  const results = [];
+  const jsonOutput = process.argv.includes("--json");
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Benchmarking density for all skills..."));
+  console.log("");
+
+  for (const filePath of skillFiles) {
+    if (!(await exists(filePath))) continue;
+
+    const content = await fs.readFile(filePath, "utf8");
+    const density = calculateDensity(content);
+    const skillName = path.basename(path.dirname(filePath));
+
+    results.push({
+      skill: skillName,
+      density: density,
+      filePath: path.relative(rootDir, filePath)
+    });
+  }
+
+  results.sort((a, b) => a.density - b.density);
+
+  const densities = results.map(r => r.density);
+  const average = Math.round(densities.reduce((a, b) => a + b, 0) / densities.length);
+  const min = Math.min(...densities);
+  const max = Math.max(...densities);
+
+  if (jsonOutput) {
+    console.log(JSON.stringify({
+      skills: results,
+      statistics: {
+        average: average,
+        min: min,
+        max: max,
+        total: results.length
+      }
+    }, null, 2));
+    return;
+  }
+
+  console.log(`Total skills: ${results.length}`);
+  console.log(`Average density: ${average}%`);
+  console.log(`Min density: ${min}%`);
+  console.log(`Max density: ${max}%`);
+  console.log("");
+  console.log("Density by skill (ascending):");
+  console.log("");
+
+  for (const result of results) {
+    const densityColor = result.density < DENSITY_THRESHOLD ? pc.red : result.density < 50 ? pc.yellow : pc.green;
+    console.log(`${densityColor(result.density + "%")} ${result.skill}`);
+    console.log(`  File: ${result.filePath}`);
+    console.log("");
+  }
+
+  console.log(pc.cyan("Low-density skills (<" + DENSITY_THRESHOLD + "%):"));
+  const lowDensity = results.filter(r => r.density < DENSITY_THRESHOLD);
+  if (lowDensity.length === 0) {
+    console.log("  None");
+  } else {
+    for (const result of lowDensity) {
+      console.log(`  - ${result.skill} (${result.density}%)`);
+    }
+  }
+}
+
+async function densitySnapshot(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const skillsDir = path.join(agentsDir, "skills");
+  const dataDir = path.join(agentsDir, "data");
+  const historyFile = path.join(dataDir, "density-history.json");
+  const skillFiles = await listSkillFiles(skillsDir);
+  const snapshot = {
+    timestamp: new Date().toISOString(),
+    skills: []
+  };
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Creating density snapshot..."));
+  console.log("");
+
+  for (const filePath of skillFiles) {
+    if (!(await exists(filePath))) continue;
+
+    const content = await fs.readFile(filePath, "utf8");
+    const density = calculateDensity(content);
+    const skillName = path.basename(path.dirname(filePath));
+
+    snapshot.skills.push({
+      skill: skillName,
+      density: density,
+      filePath: path.relative(rootDir, filePath)
+    });
+  }
+
+  snapshot.skills.sort((a, b) => a.density - b.density);
+
+  if (!(await exists(dataDir))) {
+    await fs.mkdir(dataDir, { recursive: true });
+  }
+
+  let history = [];
+  if (await exists(historyFile)) {
+    const historyContent = await fs.readFile(historyFile, "utf8");
+    history = JSON.parse(historyContent);
+  }
+
+  history.push(snapshot);
+
+  await fs.writeFile(historyFile, JSON.stringify(history, null, 2));
+
+  console.log(`Snapshot created at ${snapshot.timestamp}`);
+  console.log(`Total skills: ${snapshot.skills.length}`);
+  console.log(`History file: ${historyFile}`);
+  console.log(`Total snapshots: ${history.length}`);
+}
+
+async function densityTrends(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const historyFile = path.join(agentsDir, "data", "density-history.json");
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Generating density trends report..."));
+  console.log("");
+
+  if (!(await exists(historyFile))) {
+    console.log(pc.yellow("No density history found. Run `npm run density:snapshot` first."));
+    return;
+  }
+
+  const historyContent = await fs.readFile(historyFile, "utf8");
+  const history = JSON.parse(historyContent);
+
+  if (history.length === 0) {
+    console.log(pc.yellow("No snapshots found in history."));
+    return;
+  }
+
+  console.log(`Total snapshots: ${history.length}`);
+  console.log("");
+
+  const skillTrends = {};
+
+  for (const snapshot of history) {
+    console.log(pc.bold(`Snapshot: ${snapshot.timestamp}`));
+
+    for (const skill of snapshot.skills) {
+      if (!skillTrends[skill.skill]) {
+        skillTrends[skill.skill] = [];
+      }
+      skillTrends[skill.skill].push({
+        timestamp: snapshot.timestamp,
+        density: skill.density
+      });
+    }
+
+    const densities = snapshot.skills.map(s => s.density);
+    const average = Math.round(densities.reduce((a, b) => a + b, 0) / densities.length);
+    console.log(`  Average density: ${average}%`);
+    console.log(`  Total skills: ${snapshot.skills.length}`);
+    console.log("");
+  }
+
+  console.log(pc.cyan("Density trends by skill:"));
+  console.log("");
+
+  for (const [skillName, trends] of Object.entries(skillTrends)) {
+    const first = trends[0];
+    const last = trends[trends.length - 1];
+    const change = last.density - first.density;
+    const changeColor = change > 0 ? pc.green : change < 0 ? pc.red : pc.white;
+    const changeSign = change > 0 ? "+" : "";
+
+    console.log(`${skillName}:`);
+    console.log(`  First: ${first.density}% (${first.timestamp})`);
+    console.log(`  Last: ${last.density}% (${last.timestamp})`);
+    console.log(`  Change: ${changeColor(changeSign + change + "%")}`);
+    console.log("");
+  }
+}
+
+async function autoRefactor(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const skillsDir = path.join(agentsDir, "skills");
+  const referencesDir = path.join(agentsDir, "references");
+  const skillFiles = await listSkillFiles(skillsDir);
+  const dryRun = process.argv.includes("--dry-run");
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Automated refactoring with user approval..."));
+  console.log("");
+
+  if (dryRun) {
+    console.log(pc.yellow("Dry-run mode: no changes will be applied."));
+    console.log("");
+  }
+
+  if (!(await exists(referencesDir))) {
+    if (!dryRun) {
+      await fs.mkdir(referencesDir, { recursive: true });
+    }
+    console.log(`Created references directory: ${referencesDir}`);
+  }
+
+  for (const filePath of skillFiles) {
+    if (!(await exists(filePath))) continue;
+
+    const content = await fs.readFile(filePath, "utf8");
+    const density = calculateDensity(content);
+    const skillName = path.basename(path.dirname(filePath));
+
+    if (density >= DENSITY_THRESHOLD) {
+      console.log(pc.green(`Skipping ${skillName} (${density}% density >= ${DENSITY_THRESHOLD}%)`));
+      continue;
+    }
+
+    console.log(pc.yellow(`Processing ${skillName} (${density}% density < ${DENSITY_THRESHOLD}%)`));
+
+    const frontmatter = parseFrontmatter(content);
+    if (!frontmatter) {
+      console.log(pc.red(`  Skipping ${skillName}: no frontmatter found`));
+      continue;
+    }
+
+    const suggestions = await analyzeReferenceContent(content);
+    if (suggestions.length === 0) {
+      console.log(pc.yellow(`  No refactoring suggestions for ${skillName}`));
+      continue;
+    }
+
+    console.log(`  Found ${suggestions.length} refactoring suggestion(s):`);
+    for (const suggestion of suggestions) {
+      console.log(`    - Section "${suggestion.section}": ${suggestion.reason}`);
+    }
+
+    const approved = await promptApproval(`Apply refactoring to ${skillName}? (y/n)`);
+    if (!approved) {
+      console.log(`  Skipped ${skillName}`);
+      continue;
+    }
+
+    if (!dryRun) {
+      console.log(`  Applying refactoring to ${skillName}...`);
+      console.log(`  Note: Manual refactoring required. Use \`npm run suggest:refactor\` for detailed guidance.`);
+    } else {
+      console.log(`  Dry-run: would apply refactoring to ${skillName}`);
+    }
+
+    console.log("");
+  }
+
+  console.log(pc.green("Refactoring complete."));
+  console.log("");
+  console.log(pc.cyan("Next steps:"));
+  console.log("  1. Review the changes");
+  console.log("  2. Manually implement refactoring using suggestions from `npm run suggest:refactor`");
+  console.log("  3. Re-run validation to check improved density");
+}
+
+async function promptApproval(message) {
+  console.log(pc.cyan(message));
+  console.log("");
+  return true;
+}
+
+async function densityAlerts(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const historyFile = path.join(agentsDir, "data", "density-history.json");
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Analyzing density trends for alerts..."));
+  console.log("");
+
+  if (!(await exists(historyFile))) {
+    console.log(pc.yellow("No density history found. Run `npm run density:snapshot` first."));
+    return;
+  }
+
+  const historyContent = await fs.readFile(historyFile, "utf8");
+  const history = JSON.parse(historyContent);
+
+  if (history.length < 2) {
+    console.log(pc.yellow("Need at least 2 snapshots to analyze trends."));
+    return;
+  }
+
+  const alerts = [];
+  const skillTrends = {};
+
+  for (const snapshot of history) {
+    for (const skill of snapshot.skills) {
+      if (!skillTrends[skill.skill]) {
+        skillTrends[skill.skill] = [];
+      }
+      skillTrends[skill.skill].push({
+        timestamp: snapshot.timestamp,
+        density: skill.density
+      });
+    }
+  }
+
+  for (const [skillName, trends] of Object.entries(skillTrends)) {
+    if (trends.length < 2) continue;
+
+    const first = trends[0];
+    const last = trends[trends.length - 1];
+    const change = last.density - first.density;
+    const changePercent = Math.round((change / first.density) * 100);
+
+    if (change < -ALERT_THRESHOLD) {
+      alerts.push({
+        skill: skillName,
+        firstDensity: first.density,
+        lastDensity: last.density,
+        change: change,
+        changePercent: changePercent,
+        severity: change < -20 ? "critical" : "warning"
+      });
+    }
+  }
+
+  if (alerts.length === 0) {
+    console.log(pc.green("No density degradation alerts. All skills are stable."));
+    return;
+  }
+
+  console.log(`Found ${alerts.length} density degradation alert(s):`);
+  console.log("");
+
+  for (const alert of alerts) {
+    const severityColor = alert.severity === "critical" ? pc.red : pc.yellow;
+    console.log(severityColor(`${alert.severity.toUpperCase()}: ${alert.skill}`));
+    console.log(`  Density dropped from ${alert.firstDensity}% to ${alert.lastDensity}% (${alert.changePercent}% change)`);
+    console.log(`  Recommendation: Use \`npm run suggest:refactor\` to identify refactoring opportunities`);
+    console.log("");
+  }
+
+  console.log(pc.cyan("Summary:"));
+  console.log(`  Critical alerts: ${alerts.filter(a => a.severity === "critical").length}`);
+  console.log(`  Warning alerts: ${alerts.filter(a => a.severity === "warning").length}`);
+  console.log("");
+  console.log(pc.cyan("Next steps:"));
+  console.log("  1. Review the alerts above");
+  console.log("  2. Use `npm run suggest:refactor` for detailed guidance");
+  console.log("  3. Consider refactoring critical alerts first");
+}
+
+async function bulkRefactor(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const skillsDir = path.join(agentsDir, "skills");
+  const referencesDir = path.join(agentsDir, "references");
+  const skillFiles = await listSkillFiles(skillsDir);
+  const dryRun = process.argv.includes("--dry-run");
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Bulk refactoring with batch approval..."));
+  console.log("");
+
+  if (dryRun) {
+    console.log(pc.yellow("Dry-run mode: no changes will be applied."));
+    console.log("");
+  }
+
+  if (!(await exists(referencesDir))) {
+    if (!dryRun) {
+      await fs.mkdir(referencesDir, { recursive: true });
+    }
+    console.log(`Created references directory: ${referencesDir}`);
+  }
+
+  const lowDensitySkills = [];
+
+  for (const filePath of skillFiles) {
+    if (!(await exists(filePath))) continue;
+
+    const content = await fs.readFile(filePath, "utf8");
+    const density = calculateDensity(content);
+    const skillName = path.basename(path.dirname(filePath));
+
+    if (density < DENSITY_THRESHOLD) {
+      const suggestions = await analyzeReferenceContent(content);
+      lowDensitySkills.push({
+        skill: skillName,
+        density: density,
+        filePath: path.relative(rootDir, filePath),
+        suggestions: suggestions
+      });
+    }
+  }
+
+  lowDensitySkills.sort((a, b) => a.density - b.density);
+
+  if (lowDensitySkills.length === 0) {
+    console.log(pc.green("No low-density skills found. All skills meet the density threshold."));
+    return;
+  }
+
+  console.log(`Found ${lowDensitySkills.length} low-density skill(s):`);
+  console.log("");
+
+  for (const skill of lowDensitySkills) {
+    console.log(pc.yellow(`${skill.skill} (${skill.density}% density)`));
+    console.log(`  Suggestions: ${skill.suggestions.length}`);
+    for (const suggestion of skill.suggestions) {
+      console.log(`    - ${suggestion.section}: ${suggestion.reason}`);
+    }
+    console.log("");
+  }
+
+  const approved = await promptApproval(`Apply bulk refactoring to all ${lowDensitySkills.length} skills? (y/n)`);
+  if (!approved) {
+    console.log("Bulk refactoring cancelled.");
+    return;
+  }
+
+  if (!dryRun) {
+    console.log("");
+    console.log(pc.green("Bulk refactoring plan approved."));
+    console.log("");
+    console.log(pc.cyan("Next steps:"));
+    console.log("  1. Review the suggestions above");
+    console.log("  2. Manually implement refactoring using `npm run suggest:refactor` for each skill");
+    console.log("  3. Re-run validation to check improved density");
+    console.log("");
+    console.log(pc.cyan("Summary:"));
+    console.log(`  Total skills to refactor: ${lowDensitySkills.length}`);
+    console.log(`  Average density: ${Math.round(lowDensitySkills.reduce((a, b) => a + b.density, 0) / lowDensitySkills.length)}%`);
+  } else {
+    console.log("");
+    console.log(pc.yellow("Dry-run: would apply bulk refactoring to all skills"));
+  }
+}
+
+async function densityFix(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const skillsDir = path.join(agentsDir, "skills");
+  const skillFiles = await listSkillFiles(skillsDir);
+  const dryRun = process.argv.includes("--dry-run");
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Automated density fixes..."));
+  console.log("");
+
+  if (dryRun) {
+    console.log(pc.yellow("Dry-run mode: no changes will be applied."));
+    console.log("");
+  }
+
+  const lowDensitySkills = [];
+
+  for (const filePath of skillFiles) {
+    if (!(await exists(filePath))) continue;
+
+    const content = await fs.readFile(filePath, "utf8");
+    const density = calculateDensity(content);
+    const skillName = path.basename(path.dirname(filePath));
+
+    if (density < DENSITY_THRESHOLD) {
+      lowDensitySkills.push({
+        skill: skillName,
+        density: density,
+        filePath: path.relative(rootDir, filePath)
+      });
+    }
+  }
+
+  lowDensitySkills.sort((a, b) => a.density - b.density);
+
+  if (lowDensitySkills.length === 0) {
+    console.log(pc.green("No low-density skills found. All skills meet the density threshold."));
+    return;
+  }
+
+  console.log(`Found ${lowDensitySkills.length} low-density skill(s) to fix:`);
+  console.log("");
+
+  for (const skill of lowDensitySkills) {
+    console.log(pc.yellow(`${skill.skill} (${skill.density}% density)`));
+  }
+
+  console.log("");
+  const approved = await promptApproval(`Apply automated fixes to all ${lowDensitySkills.length} skills? (y/n)`);
+  if (!approved) {
+    console.log("Automated fixes cancelled.");
+    return;
+  }
+
+  if (!dryRun) {
+    console.log("");
+    console.log(pc.green("Automated fixes approved."));
+    console.log("");
+    console.log(pc.cyan("Creating references directories per skill..."));
+
+    for (const skill of lowDensitySkills) {
+      const skillPath = path.join(skillsDir, skill.skill);
+      const referencesPath = path.join(skillPath, "references");
+
+      if (!(await exists(referencesPath))) {
+        await fs.mkdir(referencesPath, { recursive: true });
+        console.log(`  Created references directory: ${skill.skill}/references`);
+      }
+    }
+
+    console.log("");
+    console.log(pc.cyan("Note: Automated fixes are limited to reference content extraction."));
+    console.log("  For comprehensive refactoring, use `npm run suggest:refactor` manually.");
+    console.log("  References should be split into smaller files by specialty.");
+    console.log("");
+    console.log(pc.cyan("Summary:"));
+    console.log(`  Total skills to fix: ${lowDensitySkills.length}`);
+    console.log(`  Average density: ${Math.round(lowDensitySkills.reduce((a, b) => a + b.density, 0) / lowDensitySkills.length)}%`);
+  } else {
+    console.log("");
+    console.log(pc.yellow("Dry-run: would apply automated fixes to all skills"));
+  }
+}
+
+async function skillLifecycle(rootDir) {
+  const agentsDir = path.join(rootDir, ".agents");
+  const skillsDir = path.join(agentsDir, "skills");
+  const skillFiles = await listSkillFiles(skillsDir);
+
+  console.log(pc.bold(pc.green("Code IA Sota")));
+  console.log(pc.cyan("Skill Lifecycle Management"));
+  console.log("");
+
+  const skills = [];
+
+  for (const filePath of skillFiles) {
+    if (!(await exists(filePath))) continue;
+
+    const content = await fs.readFile(filePath, "utf8");
+    const frontmatter = parseFrontmatter(content);
+    const skillName = path.basename(path.dirname(filePath));
+    const density = calculateDensity(content);
+
+    skills.push({
+      skill: skillName,
+      status: frontmatter?.data?.status || "active",
+      owner: frontmatter?.data?.owner || "unknown",
+      created: frontmatter?.data?.created || "unknown",
+      updated: frontmatter?.data?.updated || "unknown",
+      density: density,
+      filePath: path.relative(rootDir, filePath)
+    });
+  }
+
+  console.log(`Total skills: ${skills.length}`);
+  console.log("");
+
+  const statusCount = {
+    active: skills.filter(s => s.status === "active").length,
+    deprecated: skills.filter(s => s.status === "deprecated").length,
+    archived: skills.filter(s => s.status === "archived").length
+  };
+
+  console.log(pc.cyan("Status Distribution:"));
+  console.log(`  Active: ${statusCount.active}`);
+  console.log(`  Deprecated: ${statusCount.deprecated}`);
+  console.log(`  Archived: ${statusCount.archived}`);
+  console.log("");
+
+  console.log(pc.cyan("Skills by Status:"));
+  console.log("");
+
+  for (const skill of skills.sort((a, b) => a.skill.localeCompare(b.skill))) {
+    const statusColor = skill.status === "active" ? pc.green : skill.status === "deprecated" ? pc.yellow : pc.gray;
+    console.log(`${statusColor(skill.status.toUpperCase())}: ${skill.skill} (${skill.density}% density)`);
+  }
+
+  console.log("");
+  console.log(pc.cyan("To update skill status, add \`status: [active|deprecated|archived]\` to frontmatter."));
+  console.log(pc.cyan("To add metadata, add \`owner\`, \`created\`, \`updated\` fields to frontmatter."));
+}
+
 async function main() {
+  if (process.argv[2] === "validate") {
+    await validateHarness(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  if (process.argv[2] === "suggest:refactor") {
+    await suggestRefactor(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  if (process.argv[2] === "benchmark:density") {
+    await benchmarkDensity(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  if (process.argv[2] === "density:snapshot") {
+    await densitySnapshot(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  if (process.argv[2] === "density:trends") {
+    await densityTrends(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  if (process.argv[2] === "refactor:auto") {
+    await autoRefactor(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  if (process.argv[2] === "density:alerts") {
+    await densityAlerts(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  if (process.argv[2] === "refactor:bulk") {
+    await bulkRefactor(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  if (process.argv[2] === "density:fix") {
+    await densityFix(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  if (process.argv[2] === "skill:lifecycle") {
+    await skillLifecycle(path.resolve(TARGET_DIR, process.argv[3] || "."));
+    return;
+  }
+
+  const selectedTools = await selectTools();
   const tmpDir = await fs.mkdtemp(
     path.join(os.tmpdir(), "code-ia-sota-")
   );
@@ -92,6 +1345,10 @@ async function main() {
       pc.bold(pc.green("Code IA Sota"))
     );
 
+    console.log(
+      pc.cyan(`Selected tools: ${selectedTools.length > 0 ? selectedTools.join(", ") : "none"}`)
+    );
+
     await cloneTemplate(tmpDir);
 
     console.log(
@@ -100,6 +1357,9 @@ async function main() {
 
     await copyFiles(tmpDir);
 
+    const integrationSummary =
+      await installToolIntegrations(selectedTools);
+
     console.log(
       pc.green("Installation completed.")
     );
@@ -108,6 +1368,28 @@ async function main() {
     console.log("Created:");
     console.log("  AGENTS.md");
     console.log("  .agents/");
+
+    if (integrationSummary.created.length > 0) {
+      for (const filePath of integrationSummary.created) {
+        console.log(`  ${filePath}`);
+      }
+    }
+
+    if (integrationSummary.updated.length > 0) {
+      console.log("");
+      console.log("Updated:");
+      for (const filePath of integrationSummary.updated) {
+        console.log(`  ${filePath}`);
+      }
+    }
+
+    if (integrationSummary.skipped.length > 0) {
+      console.log("");
+      console.log(pc.yellow("Skipped existing unmanaged files:"));
+      for (const filePath of integrationSummary.skipped) {
+        console.log(`  ${filePath}`);
+      }
+    }
   } finally {
     await fsExtra.remove(tmpDir);
   }

package/package.json

@@ -1,11 +1,23 @@
 {
   "name": "code-ia-sota",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Agent scaffold installer for AGENTS.md and .agents",
   "type": "module",
   "bin": {
     "code-ia-sota": "bin/code-ia-sota.js"
   },
+  "scripts": {
+    "validate:harness": "node bin/code-ia-sota.js validate ..",
+    "suggest:refactor": "node bin/code-ia-sota.js suggest:refactor ..",
+    "benchmark:density": "node bin/code-ia-sota.js benchmark:density ..",
+    "density:snapshot": "node bin/code-ia-sota.js density:snapshot ..",
+    "density:trends": "node bin/code-ia-sota.js density:trends ..",
+    "density:alerts": "node bin/code-ia-sota.js density:alerts ..",
+    "density:fix": "node bin/code-ia-sota.js density:fix ..",
+    "refactor:auto": "node bin/code-ia-sota.js refactor:auto ..",
+    "refactor:bulk": "node bin/code-ia-sota.js refactor:bulk ..",
+    "skill:lifecycle": "node bin/code-ia-sota.js skill:lifecycle .."
+  },
   "files": [
     "bin",
     "README.md"