Skip to content

AGENTS.claude.sonnet.md

Latest commit

 

History

History
149 lines (104 loc) · 14.9 KB

AGENTS.claude.sonnet.md

File metadata and controls

149 lines (104 loc) · 14.9 KB
Raw

agents-reverse-engineer

The agents-reverse-engineer project converts codebases into AI-friendly documentation formats (.sum files and AGENTS.md directory overviews) by orchestrating file discovery, LLM-driven analysis, and structured markdown synthesis for consumption by AI coding assistants like Claude Code, Gemini CLI, OpenCode, and Codex.

Contents

Documentation

  • CONTRIBUTING.md: Defines contribution workflow: fork repo, branch from main, run npm run build before PR submission. Dev setup: git clone, npm install, npm run dev (tsx watch mode). Bug reports require repro steps, environment details (OS, Node version, AI runtime) via GitHub Issues with bug label. Feature requests use enhancement label.
  • LANGUAGES-MANIFEST.md: Maps 24 languages to manifest files and package managers. Supported: JavaScript/TypeScript (package.json, npm/yarn/pnpm), Python (requirements.txt/pyproject.toml/setup.py/Pipfile, pip/poetry/pipenv), Go (go.mod), Rust (Cargo.toml). Lists 20 unsupported languages (Ruby, Java, Kotlin, C#/.NET, PHP, Swift, Elixir, Erlang, Scala, Clojure, Haskell, Dart/Flutter, Lua, R, Julia, Zig, Nim, OCaml, C/C++) with manifest identifiers for future dependency analysis.
  • README.md: Documents CLI commands (are install, are init, are discover, are generate, are update, are specify, are rebuild, are clean, are dashboard) and slash commands (/are-init, /are-discover, /are-generate, /are-update, /are-specify, /are-rebuild, /are-clean, /are-dashboard). Defines config schema (.agents-reverse-engineer/config.yaml): exclude.patterns/vendorDirs/binaryExtensions, options.followSymlinks/maxFileSize, ai.backend/model/timeoutMs/maxRetries/concurrency, ai.telemetry.keepRuns. Documents artifact formats: .sum files (YAML frontmatter + Purpose/Public Interface/Dependencies/Implementation sections), AGENTS.md (directory role + grouped files + subdirectory descriptions). Lists global flags: --model, --backend, --concurrency, --dry-run, --force, --fail-fast, --show-excluded, --uncommitted, --eval, --debug, --trace.

Configuration

  • LICENSE: MIT License grants unrestricted use, copy, modify, merge, publish, distribute, sublicense, sell permissions. Copyright 2026 GeoloeG-IsT. Mandates copyright notice inclusion in all copies. Disclaims warranty (MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NONINFRINGEMENT). No liability for CLAIM, DAMAGES, LIABILITY.
  • package.json: Exposes agents-reverse-engineer and are binaries pointing to dist/cli/index.js. Scripts: build (tsc), build:hooks (copy hooks/ to hooks/dist/), prepublishOnly (build + build:hooks), prepack (rm LICENSE.sum/README.md.sum), dev (tsx watch). Dependencies: fast-glob (^3.3.3), ignore (^7.0.3), isbinaryfile (^5.0.4), jsonc-parser (^3.3.1), picocolors (^1.1.1), simple-git (^3.27.0), yaml (^2.7.0), zod (^3.24.1). DevDependencies: @types/node (^22.10.7), marked (^15.0.12), tsx (^4.19.2), typescript (^5.7.3). Exports /core subpath: dist/core/index.js with types. Engine: node >=18.0.0. Module: "module" (ESM).
  • tsconfig.json: Targets ES2022, module/moduleResolution NodeNext (ESM), lib ES2022. Output to dist/ from src/. Enables strict, declaration, declarationMap, sourceMap, esModuleInterop, skipLibCheck, forceConsistentCasingInFileNames, resolveJsonModule, isolatedModules. Includes src/**/*, excludes node_modules/dist.

Subdirectories

  • .github/workflows/: GitHub Actions workflows for publishing VitePress documentation to GitHub Pages (pages.yml: deploy via actions/deploy-pages@v4) and npm package releases (publish.yml: Node 22 setup, npm ci, npm publish on tags v*.*.*).
  • hooks/: Runtime extensions for AI coding assistants: are-check-update.js (detached background version check caching to ~/.claude/cache/are-update-check.json), are-context-loader.js (PostToolUse hook injecting parent-directory AGENTS.md files as additionalContext with session-scoped deduplication), opencode-are-check-update.js (OpenCode session.created handler writing cache to ~/.config/opencode/cache/are-update-check.json).
  • scripts/: Shell/Node.js utilities for quality analysis and packaging: analyze-sum-ratios.sh (compute .sum compression ratios, emit PASS/ACCEPTABLE/ABOVE TARGET vs 25% threshold), analyze-agents-compression.sh (calculate AGENTS.md vs aggregated inputs ratio, classify as EXCELLENT/GOOD/ACCEPTABLE/MINIMAL using 50%/70%/90% thresholds), build-hooks.js (copy .js files from hooks/ to hooks/dist/ for npm bundling).
  • src/: TypeScript source root implementing AI service abstraction (ai/), file discovery with filters (discovery/), LLM prompt construction (generation/prompts/), documentation writers (generation/writers/), incremental updates (update/), quality checks (quality/), interactive installer (installer/), CLI routing (cli/), rebuild orchestration (rebuild/), specification synthesis (specify/), config management (config/), public programmatic API (core/).

Stack

Node.js 18+ application written in TypeScript (5.7.3), compiled to ESM via tsc (target ES2022, moduleResolution NodeNext). CLI binaries (are, agents-reverse-engineer) invoke dist/cli/index.js. Programmatic API exported via /core subpath. Build toolchain: tsx (^4.19.2) for dev watch mode, marked (^15.0.12) for markdown parsing. Runtime dependencies: fast-glob (file discovery), ignore (gitignore parsing), isbinaryfile (binary detection), simple-git (change tracking), yaml (config serialization), zod (schema validation), picocolors (terminal formatting), jsonc-parser (settings.json editing).

Configuration

.agents-reverse-engineer/config.yaml (created by are init) defines:

  • exclude.patterns (string[]): Glob patterns for file exclusion (overrides gitignore)
  • exclude.vendorDirs (string[], default: ['node_modules', 'dist', '.git'])
  • exclude.binaryExtensions (string[], default: ['.png', '.jpg', '.pdf'])
  • options.followSymlinks (boolean)
  • options.maxFileSize (number, bytes, default: 1048576)
  • ai.backend ('claude'|'codex'|'gemini'|'opencode'|'auto')
  • ai.model (string, backend-specific)
  • ai.timeoutMs (number, default: 300000)
  • ai.maxRetries (number, default: 3)
  • ai.concurrency (number, 1-20, auto-detected from CPU/RAM if unset)
  • ai.telemetry.keepRuns (number, default: 50)

TypeScript compilation configured via tsconfig.json: strict type-checking, ESM output with declaration maps and source maps.

Architecture

Two-Phase Pipeline: /are-discover performs post-order directory traversal via discovery/walker.ts, applies filter chain (gitignore→vendor→binary→custom via discovery/filters/index.ts), writes GENERATION-PLAN.md. /are-generate executes Phase 1 (file analysis: orchestration/pool.ts concurrently invokes ai/service.ts with generation/prompts/buildFilePrompt, writes .sum files via generation/writers/sum.ts) then Phase 2 (directory synthesis: post-order depth traversal calls generation/prompts/buildDirectoryPrompt, writes AGENTS.md via generation/writers/agents-md.ts). Post-generation runs quality checks (quality/inconsistency/code-vs-doc.ts, quality/phantom-paths/validator.ts).

Incremental Updates: /are-update invokes change-detection/detector.ts to compute git-based file changes, filters via content hash comparison against .sum frontmatter, calls update/orphan-cleaner.ts to remove stale artifacts, identifies affected directories via update/index.ts:getAffectedDirectories, regenerates .sum/AGENTS.md for modified subtrees.

AI Backend Abstraction: ai/registry.ts auto-detects available CLIs (claude, codex, gemini, opencode) via which lookup with priority order Claude→Codex→Gemini→OpenCode. ai/service.ts spawns subprocesses via ai/subprocess.ts with timeout enforcement (SIGTERM + 5s grace → SIGKILL), wraps calls with ai/retry.ts exponential backoff (3 retries, 1s base, 8s max, 2x multiplier). Logs to ai/telemetry/run-log.ts (.agents-reverse-engineer/logs/run-{command}-{backend}-{model}-{timestamp}.json), trace to orchestration/trace.ts (.agents-reverse-engineer/traces/trace-{timestamp}.ndjson).

Installer: installer/index.ts detects runtime via integration/detect.ts, prompts for location (global ~/.claude/, ~/.config/opencode/, etc. or local ./.claude/, ./.agents/) via installer/prompts.ts, writes command templates via integration/templates.ts, registers hooks/permissions via installer/operations.ts. Uninstaller (installer/uninstall.ts) removes command files, strips ARE permissions from settings.json, deletes local .agents-reverse-engineer folders.

Specification Workflow: /are-specify collects AGENTS.md files via specify/index.ts, constructs synthesis prompt via specify/prompts.ts (12 mandatory sections: Project Overview, Architecture, Public API Surface, Dependencies, Build Plan with Defines:/Consumes: lists, etc.), invokes AI backend, writes specs/SPEC.md or multi-file tree via specify/writer.ts. /are-rebuild orchestrates checkpoint-based reconstruction: parses specs/*.md phases, executes in dependency order, injects context from prior groups, writes files via rebuild/output-parser.ts delimiter parsing (===FILE: path=== ... ===END_FILE===).

Workflow & Conventions

Installation: npx agents-reverse-engineer@latest runs interactive installer selecting runtime (Claude Code, Codex, OpenCode, Gemini CLI, all) and location (global -g, local -l). Writes command templates to .claude/, .agents/, .opencode/, .gemini/ config directories. Registers hooks: are-check-update.js (background version check), are-context-loader.js (auto-inject AGENTS.md on Read tool use). Adds ARE permissions to settings.json for Bash/Read tools.

Generation Workflow: /are-init creates .agents-reverse-engineer/config.yaml with defaults. /are-discover scans codebase respecting .gitignore/config exclusions, writes GENERATION-PLAN.md. /are-generate runs two-phase pipeline (file analysis → directory synthesis), emits .sum files (YAML frontmatter + Purpose/Public Interface/Dependencies/Implementation sections), AGENTS.md per directory, pointer files (CLAUDE.md for Claude Code, AGENTS.override.md for Codex). Logs progress to .agents-reverse-engineer/progress.log, telemetry to .agents-reverse-engineer/logs/, traces to .agents-reverse-engineer/traces/.

Incremental Updates: /are-update invokes git-based change detection, filters modified files via content hash, regenerates affected .sum/AGENTS.md, removes orphaned artifacts. Use --uncommitted flag to include unstaged changes.

Specification Synthesis: /are-specify aggregates AGENTS.md into specs/SPEC.md with 12-section structure (Project Overview, Tech Stack, Architecture, Module Dependencies, Public API Surface, Data Models, Configuration, Build & Deploy, Testing Strategy, Operations, Extension Points, Build Plan). Use --multi-file for multi-spec projects, --dry-run to preview output.

Rebuild: /are-rebuild reconstructs project from specs/*.md via dependency-ordered execution with checkpoint resumption. Validates Defines:/Consumes: DAG, injects context from prior groups, parses LLM output via delimiter format (===FILE: path=== ... ===END_FILE===).

Uninstallation: npx agents-reverse-engineer@latest uninstall removes command files from AI assistant config directories, strips ARE-related permissions from settings.json, deletes local .agents-reverse-engineer folders (global config preserved).

Commits: Use npm run build before commits. prepublishOnly hook auto-runs build + build:hooks. prepack removes LICENSE.sum/README.md.sum. Follow conventional commits format.

Behavioral Contracts

Generation Sentinel: <!-- Generated by agents-reverse-engineer (version-agnostic prefix) in AGENTS.md/CLAUDE.md files marks AI-generated content. Hooks (are-context-loader.js) detect via content.includes('Generated by agents-reverse-engineer').

Exit Codes:

  • 0: Success or no-op (no changes detected, file already exists with --force)
  • 1: Partial failure (some files failed, quality checks found issues)
  • 2: Total failure or CLI not found

Config File Path: .agents-reverse-engineer/config.yaml (from src/config/loader.ts)

Concurrency Formula (from src/config/defaults.ts):

min(cores * 5, floor(totalMemGB * 0.5 / 0.512), 20)

Progress Log Path: .agents-reverse-engineer/progress.log

Trace Path Pattern: .agents-reverse-engineer/traces/trace-{ISO8601-with-dashes}.ndjson

Telemetry Log Pattern: .agents-reverse-engineer/logs/run-{command}-{backend}-{model}-{timestamp}.json

Backend Priority Order: Claude → Codex → Gemini → OpenCode (when backend: 'auto')

Retry Options (from src/ai/retry.ts):

  • maxRetries: 3
  • baseDelayMs: 1000
  • maxDelayMs: 8000
  • multiplier: 2
  • Rate limit pattern: ['rate limit', '429', 'too many requests', 'overloaded']

Subprocess Timeout Escalation: SIGTERM → 5s grace period (SIGKILL_GRACE_MS = 5000) → SIGKILL

Rebuild Delimiter Format (from src/rebuild/output-parser.ts):

===FILE: relative/path/to/file.ext===
file content here
===END_FILE===

Specification Structure (12 mandatory sections):

  1. Project Overview
  2. Tech Stack
  3. Architecture
  4. Module Dependencies (with Defines:/Consumes: lists)
  5. Public API Surface
  6. Data Models
  7. Configuration
  8. Build & Deploy
  9. Testing Strategy
  10. Operations
  11. Extension Points
  12. Build Plan (with Defines:/Consumes: per phase)

Cache Paths:

  • Claude Code: ~/.claude/cache/are-update-check.json, ~/.claude/cache/npm-cache/
  • OpenCode: ~/.config/opencode/cache/are-update-check.json, ~/.config/opencode/cache/npm-cache/
  • Context loader dedup: {os.tmpdir()}/are-context-loader/{session_id}.json

Version File Paths:

  • Local: .claude/ARE-VERSION, .opencode/ARE-VERSION
  • Global: ~/.claude/ARE-VERSION, ~/.config/opencode/ARE-VERSION
  • Fallback: '0.0.0'

Shell Script Thresholds:

  • analyze-sum-ratios.sh: 25% target (PASS <25%, ACCEPTABLE <30%, ABOVE TARGET ≥30%), outlier detection ratio >50% or <10%
  • analyze-agents-compression.sh: EXCELLENT <50% (>2x compression), GOOD <70% (~1.5x), ACCEPTABLE <90% (<1.2x), MINIMAL ≥90%

File Discovery Patterns:

  • .sum files: find . -name "*.sum" -type f ! -path "*/node_modules/*" ! -path "*/.git/*"
  • AGENTS.md files: find . -name "AGENTS.md" -type f | sort
  • Immediate subdirectories: find "$dir" -maxdepth 1 -mindepth 1 -type d
  • Same-directory .sum: find "$dir" -maxdepth 1 -name "*.sum" -type f