@netanelyasi/agent-ready 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BrainboxAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,457 @@
+# agent-ready
+
+<p align="center">
+  <strong>Turn any repository into an AI-agent-ready codebase.</strong>
+</p>
+
+<p align="center">
+  <a href="#install">Install</a> ·
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#what-it-generates">What it Generates</a> ·
+  <a href="#how-it-works">How it Works</a> ·
+  <a href="#development">Development</a>
+</p>
+
+<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="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" />
+</p>
+
+`agent-ready` is a CLI by **BrainboxAI** that scans a project and generates the harness AI coding agents need to work safely and effectively: context files, code maps, ignore rules, skills, hook templates, and readiness reports.
+
+It is designed for real repositories—not demo apps. Use it on small apps, legacy codebases, monorepos, service folders, or projects that need a clean onboarding layer for Claude Code and other agentic coding tools.
+
+> [!WARNING]
+> `agent-ready` is an **experimental early preview**. It is useful today, but its repository detection is heuristic and generated files should be reviewed before committing.
+
+> [!NOTE]
+> **Inspired by Anthropic's Claude Code large-codebase guidance**  
+> This project was created after studying Anthropic's article:  
+> [**How Claude Code works in large codebases: best practices and where to start**](https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start).  
+> `agent-ready` turns those ideas—lean `CLAUDE.md` files, codebase maps, skills, hooks, MCP, LSP, scoped context, and subagent-friendly workflows—into a repeatable CLI workflow.
+
+## Table of Contents
+
+- [Why agent-ready](#why-agent-ready)
+- [Install](#install)
+- [Quick Start](#quick-start)
+- [What it Generates](#what-it-generates)
+- [How it Works](#how-it-works)
+- [Detected Project Signals](#detected-project-signals)
+- [Code Understanding](#code-understanding)
+- [Safety Model](#safety-model)
+- [Limitations](#limitations)
+- [Example Output](#example-output)
+- [CLI Reference](#cli-reference)
+- [Development](#development)
+- [Roadmap](#roadmap)
+- [Brand](#brand)
+- [Acknowledgements](#acknowledgements)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why agent-ready
+
+AI agents perform best when a repository is legible:
+
+- Where should the agent start searching?
+- Which files are generated noise?
+- Which test/build commands are safe and local?
+- Which project rules belong in always-loaded context?
+- Which expertise should load only on demand?
+- What should the agent never touch without confirmation?
+
+`agent-ready` turns those answers into files an agent can actually use.
+
+Instead of manually writing a bloated `CLAUDE.md`, it creates a layered harness:
+
+```txt
+CLAUDE.md                    # lean root agent guide
+CODEMAP.md                   # repository map for navigation
+.aiignore                    # noisy paths to avoid
+.claude/settings.json        # versioned deny rules
+.agent-ready/report.md       # readiness score and findings
+.agent-ready/recommendations.md
+.agent-ready/hooks/README.md
+.agent-ready/skills/*/SKILL.md
+apps/*/CLAUDE.md             # generated for detected monorepo workspaces
+```
+
+## Install
+
+### Run with npx
+
+```bash
+npx @netanelyasi/agent-ready analyze .
+npx @netanelyasi/agent-ready init . --dry-run
+```
+
+### Install globally
+
+```bash
+npm install -g @netanelyasi/agent-ready
+agent-ready analyze .
+```
+
+### From source
+
+```bash
+git clone https://github.com/Brainboxai-IL/agent-ready.git agent-ready
+cd agent-ready
+npm install
+npm run build
+node dist/cli.js analyze .
+```
+
+> Published package: [`@netanelyasi/agent-ready`](https://www.npmjs.com/package/@netanelyasi/agent-ready). The CLI binary remains `agent-ready` after global install.
+
+## Quick Start
+
+Analyze a project without writing files:
+
+```bash
+agent-ready analyze /path/to/project
+```
+
+Preview generated files:
+
+```bash
+agent-ready init /path/to/project --dry-run
+```
+
+Generate the harness:
+
+```bash
+agent-ready init /path/to/project
+```
+
+Overwrite existing generated files intentionally:
+
+```bash
+agent-ready init /path/to/project --force
+```
+
+By default, existing files are not overwritten. If `CLAUDE.md` already exists, `agent-ready` writes:
+
+```txt
+CLAUDE.md.agent-ready-proposed
+```
+
+## What it Generates
+
+### `CLAUDE.md`
+
+A lean root guide for AI agents:
+
+- project snapshot
+- detected stack
+- important directories
+- validation commands
+- operating rules
+- critical framework/database notes
+
+It is intentionally short. Task-specific expertise is placed in skills instead of loading into every session.
+
+### `CODEMAP.md`
+
+A navigation map for agents before broad search:
+
+- detected entry points
+- central files by internal import usage
+- representative internal import graph
+- external dependencies used in source files
+- top-level directory purpose
+- workspace/package manifests
+- search guidance
+- high-signal project structure
+
+### `.aiignore`
+
+Common noise exclusions:
+
+```txt
+node_modules/
+.next/
+dist/
+build/
+coverage/
+.turbo/
+vendor/
+generated/
+**/*.generated.*
+```
+
+### `.claude/settings.json`
+
+Versioned deny rules and runnable Claude Code hooks so every developer gets the same baseline safety.
+
+Generated hooks include:
+
+- `PreToolUse` for `Bash` — blocks destructive commands such as `rm -rf`, `git reset --hard`, `git clean -f`, and force-pushes.
+- `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`
+
+On-demand task expertise. Examples:
+
+- `codebase-navigation`
+- `validation`
+- `nextjs-hydration`
+- `supabase-debugging`
+- `rtl-ui`
+- `deployment`
+
+Skills are generated only when matching project signals are detected.
+
+### `.claude/hooks/*.mjs`
+
+Runnable hook scripts wired by `.claude/settings.json`:
+
+- `.claude/hooks/prevent-destructive.mjs`
+- `.claude/hooks/protect-generated.mjs`
+- `.claude/hooks/suggest-validation.mjs`
+
+### `.agent-ready/hooks/README.md`
+
+Human-readable hook policy notes for maintainers. The actual Claude Code hooks are generated under `.claude/hooks` and wired in `.claude/settings.json`.
+
+### Workspace `CLAUDE.md` files
+
+In monorepos, `agent-ready` creates local guides next to detected package manifests, for example:
+
+```txt
+apps/web/CLAUDE.md
+packages/db/CLAUDE.md
+services/api/CLAUDE.md
+```
+
+Each one contains local commands and navigation rules for that workspace.
+
+## How it Works
+
+`agent-ready` scans the repository directly from disk. It does not upload code, build embeddings, or require a remote index.
+
+The scanner detects:
+
+1. package manifests and scripts
+2. languages and frameworks
+3. database/tooling signals
+4. deployment infrastructure
+5. monorepo/workspace layout
+6. important directories
+7. noisy/generated paths
+8. existing AI harness files
+
+Then it generates a practical agent harness and assigns an **Agent Readiness Score**.
+
+Important: the score does **not** give full credit for files that `agent-ready` generated itself. Generated files are treated as a baseline. They only become readiness signal after maintainers review and customize them.
+
+## Detected Project Signals
+
+Current detection includes:
+
+| Area | Signals |
+| --- | --- |
+| JavaScript/TypeScript | `package.json`, lockfiles, scripts, TS/JS files |
+| Frameworks | Next.js, React, Vue, Nuxt, SvelteKit, Vite, Express, NestJS |
+| Other languages | Python, PHP, Java, C#, Go, Rust, C/C++ |
+| Databases | Supabase, Prisma, Drizzle, PostgreSQL, MySQL, MongoDB |
+| Monorepos | Turborepo, Nx, pnpm workspaces, package workspaces |
+| Deployment | Docker, GitHub Actions, Vercel, Netlify, Cloudflare Workers |
+| UI traits | Hebrew/RTL detection |
+| Validation | build, test, lint, typecheck, format scripts |
+
+## Code Understanding
+
+`agent-ready` is moving beyond boilerplate generation. It now builds a lightweight static map for JavaScript, TypeScript, Python, Go, and Rust projects:
+
+- package/script entry points
+- common CLI, server, app, route, Python, Go, and Rust entry files
+- JS/TS imports, including TypeScript source imported with runtime `.js` specifiers
+- Python `import` / `from ... import ...` relationships, including relative modules
+- Go imports resolved through the local `go.mod` module path
+- Rust `mod` declarations and basic `crate::` / `self::` / `super::` use paths
+- central files ranked by inbound imports
+- external packages imported by source files
+
+This makes `CODEMAP.md` useful as a code navigation artifact, not just a formatted directory listing.
+
+## Safety Model
+
+`agent-ready` is conservative by default.
+
+- **No overwrite by default** — existing files produce `*.agent-ready-proposed`.
+- **Dry-run supported** — preview before writing.
+- **Runnable hooks generated** — safety checks are wired in `.claude/settings.json`, not just described in documentation.
+- **Generated noise is denied** — build/vendor/generated paths are excluded and protected by a `PreToolUse` hook.
+- **Root context stays lean** — deep knowledge goes into skills.
+- **Local validation preferred** — workspace commands are favored over full-repo commands.
+- **No self-inflating score** — generated files are not counted as maintainer-authored readiness until reviewed/customized.
+
+## Limitations
+
+`agent-ready` is intentionally conservative and heuristic.
+
+- Detection can miss custom frameworks, unusual scripts, and non-standard repository layouts.
+- Generated files are a strong starting point, not a replacement for maintainer review.
+- Static code understanding covers JS/TS plus first-pass Python/Go/Rust import graphs. PHP/Java/C#/C/C++ are detected but do not yet get import graph mapping.
+- It does not yet perform deep semantic analysis of README files, CI workflows, environment variables, or architecture docs.
+- It does not upload code or call remote AI services.
+- It is not affiliated with or endorsed by Anthropic.
+
+## Example Output
+
+```txt
+Agent Ready: my-app
+Root: /code/my-app
+Score: 72/100
+Languages: TypeScript, Python
+Frameworks: Next.js, React
+Databases/tools: Supabase
+Deployment: Docker, GitHub Actions
+Monorepo: yes (Turborepo, pnpm workspaces)
+
+Missing:
+- No CODEMAP.md / codebase map
+- No reusable skills directory
+
+Generating 14 files:
+- created: CLAUDE.md
+- created: CODEMAP.md
+- created: .aiignore
+- created: .claude/settings.json
+- 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: apps/web/CLAUDE.md
+- created: packages/db/CLAUDE.md
+```
+
+## CLI Reference
+
+```bash
+agent-ready analyze [path]
+```
+
+Scan a project and print the readiness summary. Does not write files.
+
+```bash
+agent-ready init [path]
+```
+
+Scan a project and generate the AI-agent harness.
+
+```bash
+agent-ready init [path] --dry-run
+```
+
+Show which files would be generated without writing anything.
+
+```bash
+agent-ready init [path] --force
+```
+
+Overwrite existing files instead of writing `*.agent-ready-proposed`.
+
+## Development
+
+Requirements:
+
+- Node.js
+- npm
+
+Install dependencies:
+
+```bash
+npm install
+```
+
+Run in development:
+
+```bash
+npm run dev -- analyze .
+npm run dev -- init . --dry-run
+```
+
+Type-check:
+
+```bash
+npm run check
+```
+
+Run tests:
+
+```bash
+npm test
+```
+
+Build:
+
+```bash
+npm run build
+```
+
+Run compiled CLI:
+
+```bash
+node dist/cli.js analyze .
+```
+
+## Roadmap
+
+Planned improvements:
+
+- deeper README/config/workflow analysis
+- richer monorepo workspace detection
+- generated `CONTRIBUTING.md` and `SECURITY.md` templates
+- optional AI-assisted repository summary mode
+- npm package release
+- plugin/export presets for Claude Code, Cursor, Codex, and other agents
+- CI mode for failing builds when agent readiness drops below a threshold
+
+## Brand
+
+`agent-ready` is built by **BrainboxAI**.
+
+BrainboxAI builds practical AI-agent infrastructure: tools, workflows, and automation systems that help teams move from ad-hoc prompting to reliable agent operations.
+
+## Acknowledgements
+
+`agent-ready` was created after studying Anthropic's guidance on making large codebases navigable for Claude Code.
+
+> **Reference article**  
+> [How Claude Code works in large codebases: best practices and where to start](https://claude.com/blog/how-claude-code-works-in-large-codebases-best-practices-and-where-to-start) — Anthropic.
+
+The core idea is to turn those best practices into a repeatable CLI workflow:
+
+- scan the repository
+- generate lean, layered context
+- map the codebase before broad search
+- separate reusable expertise into skills
+- document hooks, validation paths, MCP, and LSP recommendations
+- keep generated/build/vendor noise away from agents
+
+This project is independent and is not affiliated with or endorsed by Anthropic.
+
+## Contributing
+
+Contributions are welcome once the public repository is available.
+
+Before opening a pull request:
+
+1. Run `npm run check`.
+2. Run `npm run build`.
+3. Test the CLI on at least one real project with `--dry-run`.
+4. Keep generated context lean; do not move task-specific expertise into root `CLAUDE.md` templates.
+
+## License
+
+MIT © BrainboxAI

package/dist/analyzers/scoreReadiness.d.ts

@@ -0,0 +1,2 @@
+import type { ProjectScan, ReadinessScore } from "../types.js";
+export declare function scoreReadiness(scan: ProjectScan): ReadinessScore;

package/dist/analyzers/scoreReadiness.js

@@ -0,0 +1,49 @@
+export function scoreReadiness(scan) {
+    let score = 0;
+    const strengths = [];
+    const missing = [];
+    const warnings = [];
+    addHarness(scan.existingHarness.claudeMd, 18, "Maintainer-authored root CLAUDE.md exists", "No maintainer-authored root CLAUDE.md");
+    addHarness(scan.existingHarness.codemap, 12, "Maintainer-authored CODEMAP.md exists", "No maintainer-authored CODEMAP.md / codebase map");
+    addHarness(scan.existingHarness.aiIgnore, 10, "Maintainer-authored .aiignore exists", "No maintainer-authored .aiignore");
+    addHarness(scan.existingHarness.claudeSettings, 10, "Maintainer-authored .claude/settings.json exists", "No maintainer-authored Claude settings/permissions");
+    add(Boolean(scan.commands.build?.length), 10, "Build command detected", "No build command detected");
+    add(Boolean(scan.commands.test?.length || scan.commands.lint?.length || scan.commands.typecheck?.length), 12, "Validation commands detected", "No test/lint/typecheck command detected");
+    add(scan.codeGraph.entryPoints.length > 0, 8, "Code entry points detected", "No code entry points detected");
+    add(scan.codeGraph.importEdges.length > 0 || scan.codeGraph.externalImports.length > 0, 8, "Import graph detected", "No import graph detected");
+    add(scan.monorepo.detected ? scan.packages.length > 1 : true, 5, "Workspace/package layout detected", "Monorepo detected but packages are unclear");
+    add(scan.languages.length > 0, 5, `Languages detected: ${scan.languages.join(", ")}`, "Could not detect languages");
+    add(scan.existingHarness.skillsDir && !isOnlyAgentReadySkills(scan), 2, "Maintainer skills directory exists", "No maintainer-authored reusable skills directory");
+    warnIfGenerated("CLAUDE.md", scan.existingHarness.claudeMd);
+    warnIfGenerated("CODEMAP.md", scan.existingHarness.codemap);
+    warnIfGenerated(".aiignore", scan.existingHarness.aiIgnore);
+    warnIfGenerated(".claude/settings.json", scan.existingHarness.claudeSettings);
+    if (scan.monorepo.detected && !scan.existingHarness.claudeMd.exists)
+        warnings.push("Monorepo without CLAUDE.md: agents will waste context discovering structure.");
+    if (scan.noisyPaths.length > 0 && !scan.existingHarness.aiIgnore.exists)
+        warnings.push(`Noisy paths detected (${scan.noisyPaths.join(", ")}) but no .aiignore exists.`);
+    if (scan.traits.hasHebrewOrRtl)
+        strengths.push("Hebrew/RTL trait detected; RTL UI skill will be generated.");
+    if (scan.databases.length > 0)
+        strengths.push(`Database tooling detected: ${scan.databases.join(", ")}.`);
+    return { score: Math.min(score, 100), strengths, missing, warnings };
+    function add(condition, points, yes, no) {
+        if (condition) {
+            score += points;
+            strengths.push(yes);
+        }
+        else {
+            missing.push(no);
+        }
+    }
+    function addHarness(file, points, yes, no) {
+        add(file.countsAsMaintainerAuthored, points, yes, file.exists ? `${no} (existing file is agent-ready generated and needs maintainer review)` : no);
+    }
+    function warnIfGenerated(label, file) {
+        if (file.generatedByAgentReady)
+            warnings.push(`${label} was generated by agent-ready; it is not counted as maintainer-authored readiness until reviewed/customized.`);
+    }
+}
+function isOnlyAgentReadySkills(scan) {
+    return scan.existingHarness.skillsDir && !scan.existingHarness.claudeMd.countsAsMaintainerAuthored;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+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";
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.command === "help") {
+        printHelp();
+        return;
+    }
+    const root = path.resolve(args.target);
+    const scan = await scanProject(root);
+    const score = scoreReadiness(scan);
+    printSummary(scan, score);
+    if (args.command === "analyze")
+        return;
+    const files = generateFiles(scan, score, args.force);
+    console.log(`\nGenerating ${files.length} files${args.dryRun ? " (dry-run)" : ""}:`);
+    for (const file of files) {
+        const relative = path.relative(root, file.path).replaceAll(path.sep, "/");
+        if (args.dryRun) {
+            console.log(`- would write ${relative}`);
+            continue;
+        }
+        const result = await safeWriteFile(file.path, file.content, args.force);
+        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.");
+}
+function parseArgs(argv) {
+    const command = argv[0] === "init" || argv[0] === "analyze" ? argv[0] : argv[0] ? "help" : "help";
+    const flags = new Set(argv.filter((arg) => arg.startsWith("--")));
+    const target = argv.find((arg, index) => index > 0 && !arg.startsWith("--")) ?? ".";
+    return {
+        command,
+        target,
+        dryRun: flags.has("--dry-run"),
+        force: flags.has("--force"),
+        verbose: flags.has("--verbose"),
+    };
+}
+function printSummary(scan, score) {
+    console.log(`Agent Ready: ${scan.name}`);
+    console.log(`Root: ${scan.root}`);
+    console.log(`Score: ${score.score}/100`);
+    console.log(`Languages: ${scan.languages.join(", ") || "none detected"}`);
+    console.log(`Frameworks: ${scan.frameworks.join(", ") || "none detected"}`);
+    console.log(`Databases/tools: ${scan.databases.join(", ") || "none detected"}`);
+    console.log(`Deployment: ${scan.deployment.join(", ") || "none detected"}`);
+    console.log(`Monorepo: ${scan.monorepo.detected ? `yes (${scan.monorepo.tools.join(", ") || "multiple packages"})` : "no/unclear"}`);
+    console.log(`Entry points: ${scan.codeGraph.entryPoints.length}`);
+    console.log(`Resolved internal imports: ${scan.codeGraph.importEdges.length}`);
+    if (score.missing.length) {
+        console.log("\nMissing:");
+        for (const item of score.missing)
+            console.log(`- ${item}`);
+    }
+    if (score.warnings.length) {
+        console.log("\nWarnings:");
+        for (const item of score.warnings)
+            console.log(`- ${item}`);
+    }
+}
+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`);
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/generators/generate.d.ts

@@ -0,0 +1,2 @@
+import type { GeneratedFile, ProjectScan, ReadinessScore } from "../types.js";
+export declare function generateFiles(scan: ProjectScan, score: ReadinessScore, force: boolean): GeneratedFile[];