@netanelyasi/agent-ready 0.2.0 → 0.2.2

package/README.md

@@ -14,7 +14,7 @@
 
 <p align="center">
   <img alt="Status" src="https://img.shields.io/badge/status-experimental-f59e0b?style=flat-square" />
-  <img alt="Version" src="https://img.shields.io/badge/version-0.2.0-111827?style=flat-square" />
+  <img alt="Version" src="https://img.shields.io/badge/version-0.2.2-111827?style=flat-square" />
   <img alt="License" src="https://img.shields.io/badge/license-MIT-0f766e?style=flat-square" />
   <img alt="Runtime" src="https://img.shields.io/badge/runtime-Node.js-3c873a?style=flat-square" />
   <img alt="Built by BrainboxAI" src="https://img.shields.io/badge/by-BrainboxAI-111827?style=flat-square" />
@@ -76,7 +76,7 @@ CODEMAP.md                   # repository map for navigation
 .agent-ready/report.md       # readiness score and findings
 .agent-ready/recommendations.md
 .agent-ready/hooks/README.md
-.agent-ready/skills/*/SKILL.md
+.claude/skills/*/SKILL.md       # Claude Code-loadable skills
 apps/*/CLAUDE.md             # generated for detected monorepo workspaces
 ```
 
@@ -122,6 +122,14 @@ Preview generated files:
 agent-ready init /path/to/project --dry-run
 ```
 
+Preview generated file contents:
+
+```bash
+agent-ready init /path/to/project --dry-run --verbose
+```
+
+> Run `agent-ready init` manually from your terminal, not from inside an autonomous coding agent. It writes agent harness files such as `CLAUDE.md`, `.claude/settings.json`, and `.claude/hooks/*`, which some agent security classifiers correctly treat as self-modification.
+
 Generate the harness:
 
 ```bash
@@ -194,7 +202,7 @@ Generated hooks include:
 - `PreToolUse` for `Write|Edit|MultiEdit` — blocks edits to generated/noisy paths such as `node_modules`, `dist`, `build`, `coverage`, `.next`, `vendor`, and `*.generated.*`.
 - `PostToolUse` for `Write|Edit|MultiEdit` — reminds the agent which local validation command to run after edits.
 
-### `.agent-ready/skills/*/SKILL.md`
+### `.claude/skills/*/SKILL.md`
 
 On-demand task expertise. Examples:
 
@@ -327,10 +335,10 @@ Generating 14 files:
 - created: .agent-ready/report.md
 - created: .agent-ready/recommendations.md
 - created: .agent-ready/hooks/README.md
-- created: .agent-ready/skills/codebase-navigation/SKILL.md
-- created: .agent-ready/skills/validation/SKILL.md
-- created: .agent-ready/skills/nextjs-hydration/SKILL.md
-- created: .agent-ready/skills/supabase-debugging/SKILL.md
+- created: .claude/skills/codebase-navigation/SKILL.md
+- created: .claude/skills/validation/SKILL.md
+- created: .claude/skills/nextjs-hydration/SKILL.md
+- created: .claude/skills/supabase-debugging/SKILL.md
 - created: apps/web/CLAUDE.md
 - created: packages/db/CLAUDE.md
 ```
@@ -355,12 +363,20 @@ agent-ready init [path] --dry-run
 
 Show which files would be generated without writing anything.
 
+```bash
+agent-ready init [path] --dry-run --verbose
+```
+
+Show the generated contents too. Use this before deciding whether to run `init` for real or manually merge proposed files.
+
 ```bash
 agent-ready init [path] --force
 ```
 
 Overwrite existing files instead of writing `*.agent-ready-proposed`.
 
+When existing harness files are present, default `init` writes `*.agent-ready-proposed` files. Review and manually merge them; `agent-ready` does not assume its generated `CLAUDE.md` is better than a maintainer-authored one.
+
 ## Development
 
 Requirements:

package/dist/cli.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { scoreReadiness } from "./analyzers/scoreReadiness.js";
 import { generateFiles } from "./generators/generate.js";
 import { scanProject } from "./scanner/scanProject.js";
-import { safeWriteFile } from "./utils/fs.js";
+import { pathExists, safeWriteFile } from "./utils/fs.js";
 async function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.command === "help") {
@@ -18,17 +18,47 @@ async function main() {
         return;
     const files = generateFiles(scan, score, args.force);
     console.log(`\nGenerating ${files.length} files${args.dryRun ? " (dry-run)" : ""}:`);
+    let proposedCount = 0;
     for (const file of files) {
         const relative = path.relative(root, file.path).replaceAll(path.sep, "/");
         if (args.dryRun) {
-            console.log(`- would write ${relative}`);
+            const result = await plannedWriteResult(file.path, args.force);
+            if (result === "proposed")
+                proposedCount += 1;
+            const target = result === "proposed" ? `${relative}.agent-ready-proposed` : relative;
+            console.log(`- would ${writeVerb(result)}: ${target}`);
+            if (args.verbose)
+                printDryRunContent(target, file.content);
             continue;
         }
         const result = await safeWriteFile(file.path, file.content, args.force);
+        if (result === "proposed")
+            proposedCount += 1;
         const target = result === "proposed" ? `${relative}.agent-ready-proposed` : relative;
         console.log(`- ${result}: ${target}`);
     }
     console.log("\nDone. Start with CODEMAP.md and .agent-ready/report.md.");
+    if (proposedCount > 0)
+        console.log(`Review and manually merge ${proposedCount} *.agent-ready-proposed file(s); existing harness files were not overwritten.`);
+}
+async function plannedWriteResult(filePath, force) {
+    const exists = await pathExists(filePath);
+    if (force)
+        return exists ? "overwritten" : "created";
+    return exists ? "proposed" : "created";
+}
+function writeVerb(result) {
+    if (result === "created")
+        return "create";
+    if (result === "overwritten")
+        return "overwrite";
+    return "propose";
+}
+function printDryRunContent(target, content) {
+    console.log(`  --- ${target} begin ---`);
+    for (const line of content.trimEnd().split("\n"))
+        console.log(`  ${line}`);
+    console.log(`  --- ${target} end ---`);
 }
 function parseArgs(argv) {
     const command = argv[0] === "init" || argv[0] === "analyze" ? argv[0] : argv[0] ? "help" : "help";
@@ -65,7 +95,7 @@ function printSummary(scan, score) {
     }
 }
 function printHelp() {
-    console.log(`agent-ready\n\nUsage:\n  agent-ready analyze [path]\n  agent-ready init [path] [--dry-run] [--force]\n\nCommands:\n  analyze   Scan project and print readiness summary\n  init      Generate CLAUDE.md, CODEMAP.md, .aiignore, settings, skills, and reports\n\nOptions:\n  --dry-run   Show files that would be written\n  --force     Overwrite existing files instead of writing *.agent-ready-proposed\n`);
+    console.log(`agent-ready\n\nUsage:\n  agent-ready analyze [path]\n  agent-ready init [path] [--dry-run] [--verbose] [--force]\n\nCommands:\n  analyze   Scan project and print readiness summary\n  init      Generate CLAUDE.md, CODEMAP.md, .aiignore, settings, skills, and reports\n\nOptions:\n  --dry-run   Show files that would be written\n  --verbose   With --dry-run, print generated file contents\n  --force     Overwrite existing files instead of writing *.agent-ready-proposed\n`);
 }
 main().catch((error) => {
     console.error(error instanceof Error ? error.message : String(error));

package/dist/generators/generate.js

@@ -4,7 +4,7 @@ export function generateFiles(scan, score, force) {
     add("CLAUDE.md", generateClaudeMd(scan));
     add("CODEMAP.md", generateCodemap(scan));
     add(".aiignore", generateAiIgnore(scan));
-    add(".claude/settings.json", generateClaudeSettings(scan));
+    add(".claude/settings.json", generateClaudeSettings());
     add(".claude/hooks/prevent-destructive.mjs", generatePreventDestructiveHook());
     add(".claude/hooks/protect-generated.mjs", generateProtectGeneratedHook());
     add(".claude/hooks/suggest-validation.mjs", generateSuggestValidationHook(scan));
@@ -15,7 +15,7 @@ export function generateFiles(scan, score, force) {
         add(`${subdir.dir}/CLAUDE.md`, subdir.content);
     }
     for (const skill of generateSkills(scan)) {
-        add(`.agent-ready/skills/${skill.slug}/SKILL.md`, skill.content);
+        add(`.claude/skills/${skill.slug}/SKILL.md`, skill.content);
     }
     return files;
     function add(relativePath, content) {
@@ -114,7 +114,7 @@ function generateClaudeMd(scan) {
     if (scan.frameworks.includes("Next.js")) {
         lines.push("- Next.js detected: avoid hydration mismatches; access browser-only APIs only in client-safe code.");
     }
-    lines.push("", "## Generated Skills", "See `.agent-ready/skills/*/SKILL.md` for task-specific instructions that should be loaded on demand, not copied wholesale into this file.", "");
+    lines.push("", "## Generated Skills", "See `.claude/skills/*/SKILL.md` for task-specific instructions that Claude Code can load on demand. Keep skills focused and avoid copying them wholesale into this file.", "");
     return lines.join("\n");
 }
 function commandLines(scan) {
@@ -132,6 +132,20 @@ function commandLines(scan) {
         lines.push("- No standard validation commands were detected. Add project-specific commands here.");
     return lines;
 }
+// Flat one-command-per-rule list for the validation skill, e.g. "test: `npm run test`".
+// Unlike commandLines (which nests for CLAUDE.md), this stays flat so it renders
+// correctly as a SKILL.md bullet list.
+function validationSkillRules(scan) {
+    const order = ["dev", "build", "test", "lint", "typecheck", "format"];
+    const rules = [];
+    for (const name of order) {
+        for (const command of (scan.commands[name] ?? []).slice(0, 8))
+            rules.push(`${name}: \`${command}\``);
+    }
+    if (!rules.length)
+        rules.push("No standard validation commands were detected. Add project-specific commands here.");
+    return rules;
+}
 function generateCodemap(scan) {
     return [
         `# ${scan.name} — CODEMAP`,
@@ -196,33 +210,40 @@ function externalImportLines(scan) {
 function generateAiIgnore(scan) {
     const base = [
         "# Generated by agent-ready",
-        "node_modules/",
-        ".next/",
-        ".nuxt/",
-        "dist/",
-        "build/",
         "coverage/",
-        ".turbo/",
         ".cache/",
-        ".venv/",
-        "venv/",
-        "__pycache__/",
-        "vendor/",
-        "target/",
-        "bin/",
-        "obj/",
         "*.log",
         "*.lock",
         "generated/",
         "**/*.generated.*",
     ];
+    const add = (...patterns) => {
+        for (const pattern of patterns)
+            if (!base.includes(pattern))
+                base.push(pattern);
+    };
+    if (scan.packageManager || scan.languages.some((language) => ["TypeScript", "JavaScript", "Svelte"].includes(language)))
+        add("node_modules/", "dist/", "build/", ".turbo/");
+    if (scan.frameworks.includes("Next.js"))
+        add(".next/");
+    if (scan.frameworks.includes("Nuxt"))
+        add(".nuxt/");
+    if (scan.languages.includes("Python"))
+        add(".venv/", "venv/", "__pycache__/");
+    if (scan.languages.includes("Rust"))
+        add("target/");
+    if (scan.languages.includes("Go"))
+        add("bin/");
+    if (scan.languages.includes("C#"))
+        add("bin/", "obj/");
+    if (scan.languages.includes("PHP") || scan.frameworks.some((framework) => framework.includes("Composer")))
+        add("vendor/");
     for (const noisy of scan.noisyPaths)
-        if (!base.includes(`${noisy}/`))
-            base.push(`${noisy}/`);
-    return `${[...new Set(base)].join("\n")}\n`;
+        add(`${noisy}/`);
+    return `${base.join("\n")}\n`;
 }
-function generateClaudeSettings(scan) {
-    const deny = [
+function generateClaudeSettings() {
+    const deniedPathPatterns = [
         "node_modules/**",
         ".next/**",
         "dist/**",
@@ -233,6 +254,8 @@ function generateClaudeSettings(scan) {
         "generated/**",
         "**/*.generated.*",
     ];
+    const deniedWriteTools = ["Write", "Edit", "MultiEdit"];
+    const deny = deniedWriteTools.flatMap((tool) => deniedPathPatterns.map((pattern) => `${tool}(${pattern})`));
     const settings = {
         permissions: { deny: [...new Set(deny)] },
         hooks: {
@@ -245,7 +268,7 @@ function generateClaudeSettings(scan) {
                             command: "node",
                             args: ["${CLAUDE_PROJECT_DIR}/.claude/hooks/prevent-destructive.mjs"],
                             timeout: 10,
-                            statusMessage: "Checking command safety",
+                            statusMessage: "agent-ready: Checking command safety",
                         },
                     ],
                 },
@@ -257,7 +280,7 @@ function generateClaudeSettings(scan) {
                             command: "node",
                             args: ["${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-generated.mjs"],
                             timeout: 10,
-                            statusMessage: "Checking generated/noisy path safety",
+                            statusMessage: "agent-ready: Checking generated/noisy path safety",
                         },
                     ],
                 },
@@ -271,13 +294,12 @@ function generateClaudeSettings(scan) {
                             command: "node",
                             args: ["${CLAUDE_PROJECT_DIR}/.claude/hooks/suggest-validation.mjs"],
                             timeout: 10,
-                            statusMessage: "Suggesting validation",
+                            statusMessage: "agent-ready: Suggesting validation",
                         },
                     ],
                 },
             ],
         },
-        agentReady: { generatedBy: "agent-ready", project: scan.name },
     };
     return `${JSON.stringify(settings, null, 2)}\n`;
 }
@@ -459,7 +481,7 @@ function hookRecommendations(scan) {
 function generateSkills(scan) {
     const skills = [
         { slug: "codebase-navigation", content: skill("codebase-navigation", "Use when starting work in this repository or when a task spans unfamiliar directories.", ["Read CODEMAP.md first.", "Use narrow searches from the relevant directory before global search.", "Prefer symbol/reference search when LSP is available.", "Do not inspect ignored/generated directories unless explicitly needed."]) },
-        { slug: "validation", content: skill("validation", "Use after code edits or before declaring a task complete.", [...commandLines(scan).map((line) => line.replace(/^[- ]+/, "")), "Run the narrowest relevant command first.", "If validation cannot be run, report the exact reason."]) },
+        { slug: "validation", content: skill("validation", "Use after code edits or before declaring a task complete.", [...validationSkillRules(scan), "Run the narrowest relevant command first.", "If validation cannot be run, report the exact reason."]) },
     ];
     if (scan.frameworks.includes("Next.js"))
         skills.push({ slug: "nextjs-hydration", content: skill("nextjs-hydration", "Use when editing Next.js/React components, routes, or client/server boundaries.", ["Do not read localStorage/sessionStorage/window/document during server render or initial state.", "Use useEffect or guarded client-only code for browser APIs.", "Avoid Math.random() or new Date() in render paths that must hydrate identically.", "Keep server/client boundaries explicit."]) });
@@ -472,7 +494,28 @@ function generateSkills(scan) {
     return skills;
 }
 function skill(name, description, rules) {
-    return [`# ${name}`, "", `Description: ${description}`, "", "## Rules", ...rules.map((rule) => `- ${rule}`), ""].join("\n");
+    return [
+        "---",
+        `name: ${name}`,
+        `description: ${yamlScalar(description)}`,
+        "---",
+        "",
+        `# ${name}`,
+        "",
+        description,
+        "",
+        "## Rules",
+        ...rules.map((rule) => `- ${rule}`),
+        "",
+    ].join("\n");
+}
+// Claude Code parses SKILL.md frontmatter as YAML. Quote scalars that contain
+// characters YAML would otherwise treat as structure (`:`, leading `#`, etc.).
+function yamlScalar(value) {
+    if (/^[^\s].*[:#]|^[#&*!|>%@`"']|:\s|\s#/.test(value)) {
+        return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+    }
+    return value;
 }
 function list(items) {
     return items.length ? items.join(", ") : "none detected";

package/dist/scanner/scanProject.js

@@ -10,6 +10,7 @@ const LANGUAGE_EXTS = {
     "C#": [".cs"],
     Go: [".go"],
     Rust: [".rs"],
+    Svelte: [".svelte"],
     "C/C++": [".c", ".cc", ".cpp", ".h", ".hpp"],
 };
 export async function scanProject(rootInput) {
@@ -263,12 +264,12 @@ async function harnessFileState(root, relativePath) {
     if (!exists)
         return { exists: false, generatedByAgentReady: false, countsAsMaintainerAuthored: false };
     const text = await readText(fullPath);
-    const generatedByAgentReady = Boolean(text && /generated by `?agent-ready`?|agentReady|Generated by agent-ready/i.test(text));
+    const generatedByAgentReady = Boolean(text && /generated by `?agent-ready`?|agent-ready:|Generated by agent-ready/i.test(text));
     return { exists: true, generatedByAgentReady, countsAsMaintainerAuthored: !generatedByAgentReady };
 }
 async function analyzeCodeGraph(root, files, packages) {
     const sourceFiles = files
-        .filter((file) => /\.(tsx?|jsx?|mjs|cjs|py|go|rs)$/.test(file))
+        .filter((file) => /\.(tsx?|jsx?|mjs|cjs|py|go|rs|svelte)$/.test(file))
         .filter((file) => !file.endsWith(".d.ts"))
         .filter((file) => !file.includes(`${path.sep}dist${path.sep}`) && !file.includes(`${path.sep}node_modules${path.sep}`) && !file.includes(`${path.sep}target${path.sep}`))
         .slice(0, 2000);
@@ -342,10 +343,6 @@ function detectEntryPoints(root, packages, sourceSet) {
             ["src/main.js", "application entry", "conventional app entry"],
             ["src/server.ts", "server entry", "conventional server entry"],
             ["src/server.js", "server entry", "conventional server entry"],
-            ["app/page.tsx", "Next.js route", "App Router page"],
-            ["app/layout.tsx", "Next.js layout", "App Router layout"],
-            ["src/app/page.tsx", "Next.js route", "App Router page"],
-            ["pages/index.tsx", "Next.js route", "Pages Router index"],
             ["main.py", "Python entry", "conventional Python entry"],
             ["app.py", "Python app", "conventional Python app entry"],
             ["src/main.py", "Python entry", "conventional Python entry"],
@@ -363,10 +360,9 @@ function detectEntryPoints(root, packages, sourceSet) {
             if (!source.startsWith(packageRoot))
                 continue;
             const local = source.slice(packageRoot.length);
-            if (/^pages\/api\/.+\.(tsx?|jsx?)$/.test(local))
-                entries.set(source, { path: source, kind: "API route", reason: "Next.js API route" });
-            if (/^app\/.+\/(page|route)\.(tsx?|jsx?)$/.test(local))
-                entries.set(source, { path: source, kind: "Next.js route", reason: "App Router route/page" });
+            const frameworkEntry = frameworkEntryPoint(local);
+            if (frameworkEntry)
+                entries.set(source, { path: source, ...frameworkEntry });
             if (/^cmd\/[^/]+\/main\.go$/.test(local))
                 entries.set(source, { path: source, kind: "Go command", reason: "cmd/*/main.go" });
             if (/^src\/bin\/[^/]+\.rs$/.test(local))
@@ -380,6 +376,34 @@ function detectEntryPoints(root, packages, sourceSet) {
     }
     return [...entries.values()].sort((a, b) => a.path.localeCompare(b.path)).slice(0, 40);
 }
+function frameworkEntryPoint(localPath) {
+    if (/^(src\/)?app\/(page|layout|route)\.(tsx?|jsx?)$/.test(localPath)) {
+        const file = localPath.includes("/layout.") ? "layout" : localPath.includes("/route.") ? "route handler" : "page";
+        return { kind: `Next.js ${file}`, reason: "App Router root entry" };
+    }
+    if (/^(src\/)?app\/.+\/(page|layout|route|loading|error|not-found)\.(tsx?|jsx?)$/.test(localPath)) {
+        return { kind: "Next.js route", reason: "App Router route segment entry" };
+    }
+    if (/^(src\/)?pages\/index\.(tsx?|jsx?)$/.test(localPath))
+        return { kind: "Next.js route", reason: "Pages Router index" };
+    if (/^(src\/)?pages\/(api\/.+|.+)\.(tsx?|jsx?)$/.test(localPath))
+        return { kind: "Next.js route", reason: "Pages Router route/API entry" };
+    if (/^(src\/)?middleware\.(tsx?|jsx?)$/.test(localPath))
+        return { kind: "Next.js middleware", reason: "Next.js request middleware entry" };
+    if (/^next\.config\.(tsx?|jsx?|mjs|cjs)$/.test(localPath))
+        return { kind: "Next.js config", reason: "Next.js configuration entry" };
+    if (/^app\/(root|entry\.(client|server))\.(tsx?|jsx?)$/.test(localPath))
+        return { kind: "Remix entry", reason: "Remix root/client/server entry" };
+    if (/^app\/routes\/.+\.(tsx?|jsx?)$/.test(localPath))
+        return { kind: "Remix route", reason: "Remix route module" };
+    if (/^src\/routes\/(\+page|\+layout|\+server)\.(svelte|tsx?|jsx?)$/.test(localPath))
+        return { kind: "SvelteKit route", reason: "SvelteKit root route entry" };
+    if (/^src\/routes\/.+\/(\+page|\+layout|\+server)\.(svelte|tsx?|jsx?)$/.test(localPath))
+        return { kind: "SvelteKit route", reason: "SvelteKit route entry" };
+    if (/^src\/hooks(\.server)?\.(tsx?|jsx?)$/.test(localPath))
+        return { kind: "SvelteKit hook", reason: "SvelteKit lifecycle hook entry" };
+    return undefined;
+}
 function extractImportSpecifiers(text, from) {
     const specifiers = new Set();
     const ext = path.posix.extname(from);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@netanelyasi/agent-ready",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Generate an AI-agent harness for any codebase: CLAUDE.md, CODEMAP.md, skills, ignore rules, and readiness reports.",
   "type": "module",
   "bin": {