agents-reverse-engineer AGENTS.md

agents-reverse-engineer

npx-installable CLI toolkit for AI coding assistants that generates AI-optimized .sum file summaries, AGENTS.md hierarchical documentation, and runtime integration hooks for Claude Code, OpenCode, Gemini CLI, and Codex, with A/B testing framework for measuring AI planning and implementation quality impact.

Stack

Runtime: Node.js 18+ with TypeScript (ES2022 modules via tsconfig.json)
AI Backends: Claude CLI, OpenAI Codex, Google Gemini, OpenCode (subprocess adapters)
File Discovery: fast-glob with ignore/isbinaryfile filters
Git Operations: simple-git (change detection, worktree isolation)
Schema Validation: zod (config.yaml schema)
Output Formats: YAML frontmatter (.sum files), NDJSON (telemetry traces), HTML (dashboard reports via Chart.js CDN)
Entry Points: bin.agents-reverse-engineer and bin.are → dist/cli/index.js
Core API: exports["./core"] → dist/core/index.js with types at dist/core/index.d.ts (@beta stability)

Contents

Configuration & Licensing

• CONTRIBUTING.md — Developer workflow: npm install (dependencies), npm run build (tsc → dist/), npm run dev (tsx watch live reload). Project structure: src/cli/ (CLI entry + commands), src/config/ (schema + loading), src/discovery/ (file discovery + plan gen), src/generation/ (AI-driven doc gen), src/orchestration/ (concurrency pool + tracing + process mgmt), src/ai/ (AI service abstraction + subprocess mgmt), src/plan/ (A/B plan comparison), src/implement/ (A/B implementation comparison). Fork-branch-PR contribution workflow. Bug reports require repro steps + environment. Feature requests use enhancement label. MIT licensed.
• LANGUAGES-MANIFEST.md — Mapping of 24 languages to package manifest files: JavaScript/TypeScript (package.json), Python (requirements.txt, pyproject.toml, setup.py, Pipfile), Go (go.mod), Rust (Cargo.toml) marked supported (✓); Ruby (Gemfile), Java (pom.xml, build.gradle), and 17 others currently unsupported. Used by src/generation/prompts/builder.ts for import map construction.
• LICENSE — MIT license granting unrestricted use/modification/distribution with copyright notice requirement. AS IS warranty disclaimer. Copyright holder: GeoloeG-IsT (2026).
• package.json — npm package metadata v1.2.17. Entry points: bin.agents-reverse-engineer/bin.are → dist/cli/index.js, exports["."] → dist/cli/index.js, exports["./core"] → dist/core/index.js with type definitions at dist/core/index.d.ts. Build scripts: build (tsc), build:hooks (scripts/build-hooks.js), prepublishOnly (sequential builds), prepack (removes LICENSE.sum/README.md.sum), dev (tsx watch). Dependencies: fast-glob, ignore, isbinaryfile, jsonc-parser, simple-git, yaml, zod, picocolors. Node >=18.0.0 required.
• tsconfig.json — TypeScript compiler config: target ES2022, module/moduleResolution NodeNext, outDir dist/, rootDir src/, declaration/declarationMap/sourceMap true, strict true, forceConsistentCasingInFileNames true, isolatedModules true, resolveJsonModule true. Include src/**/*, exclude node_modules/dist.