@netanelyasi/agent-ready 0.2.0 → 0.2.1

package/README.md

@@ -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

@@ -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) {
@@ -196,33 +196,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 = [
+    const deniedPathPatterns = [
         "node_modules/**",
         ".next/**",
         "dist/**",
@@ -233,6 +240,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 +254,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 +266,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 +280,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`;
 }

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.1",
   "description": "Generate an AI-agent harness for any codebase: CLAUDE.md, CODEMAP.md, skills, ignore rules, and readiness reports.",
   "type": "module",
   "bin": {