Ralph Evolver

Recursive self-improvement engine. Think from first principles, let insights emerge.

Security Scan

The skill's code largely matches its stated purpose (analyze a repo and track improvements), but there are mismatches and omissions that deserve attention—most notably the code invokes system binaries (git, grep) and expects a Node runtime even though the metadata declares no required binaries or environment needs; it also persists state into the target project.

Purpose & Capability

The name/description (recursive self-improvement for a codebase) align with the code: it collects git history, TODOs, test/build outputs, and writes improvement/state artifacts. However the package metadata claims 'required binaries: none' while the implementation calls external programs (git and grep) and requires Node.js (package.json specifies node >=18). The omission of those runtime requirements in the manifest is an inconsistency that could mislead users about what the skill actually needs.

Instruction Scope

SKILL.md and the code agree: the tool scans the project (git history, TODO/FIXME comments, test/build outputs), generates prompts, and records improvements. The runtime instructions and code are constrained to the projectPath (exec commands include '--' '.' and grep excludes .git/node_modules), and there are no hidden network endpoints or references to unrelated system configs. It does read repo data and write a .ralph directory in the target project (state and improvements).

Install Mechanism

There is no install spec (instruction-only from the registry perspective) and the repository includes code and package.json. The skill does not fetch arbitrary remote archives or run downloads at install time. Risk is low from an installer standpoint, but users should note it expects to be run with a Node runtime and will write files into the target project on disk.

Credentials

The skill declares no required env vars or credentials (which is appropriate), but it implicitly requires system tools (git, grep) and Node.js that are not declared. That omission can cause surprises: running it in an environment lacking git/grep will fail, and running it in an environment with those tools but on a sensitive repository will expose repository contents to the skill process. No network credentials are requested, which is proportionate to its function.

Persistence & Privilege

The skill persists state and history under a .ralph directory inside the target project and updates a state.json / improvements.json. always:false (no force inclusion) and it doesn't modify other skills or global agent settings. Persisting state in the project directory is legitimate for this tool's purpose but users should be aware it will leave files behind and update iteration counts across runs.

What to consider before installing

This skill appears to implement what it promises (analyzing a repo and tracking improvements), but there are a few practical risks to consider before installing/using it: - Manifest discrepancy: The code invokes git and grep and requires Node.js (package.json) but the registry metadata declares 'required binaries: none'. Expect to need git, grep, and Node >=18. Ask the publisher to update the manifest if you need that guarantee. - It writes persistent files into the target project (.ralph/state.json and improvements.json). If you run it on a sensitive or production repository, these files will be created; consider running in a disposable clone or sandboxed environment first. - The tool runs shell commands via execFileSync. Although the commands shown are limited to the project directory (git -- . and grep excludes), ensure you run it against repositories you trust and inspect the code yourself (you have the source included). - There are no network calls or credential requests visible in the provided code, which is good; nonetheless, confirm there are no hidden fetches in any truncated/unseen portions before running on sensitive data. Recommended steps: 1) Run the tool in a disposable clone of the repository to observe behavior and files created. 2) Ensure git, grep, and Node.js are available in the environment, or have the author update the skill manifest to declare those requirements. 3) Review evolve.js and index.js locally (you already have the files) and run the test suite (npm install dev deps, npm test) if you want extra assurance. 4) If you plan to let an agent invoke this autonomously, be aware it will persist state and can run multiple cycles (loop mode); prefer manual invocation or limit the project scope initially. If you want, I can produce a short checklist you can use to safely trial this skill (commands to run in a sandbox, files to inspect after run).

Philosophy: Recursion + Emergence + First Principles

Signal Sources

Collects multi-dimensional context, not just code structure:

• Commit history - Understand the "why" behind changes
• TODO/FIXME - Distress signals in the code
• Error handling patterns - Find fragile points
• Hotspot files - Frequent changes = design problems

Each signal includes a hypothesis prompt to guide deeper analysis.

First Principles

Each run doesn't execute a checklist, but asks:

1. What is the essence of this project?
2. What is it doing that it shouldn't?
3. What is it missing that it should have?
4. If you started from scratch, how would you build it?

Meta-Reflection (v1.0.5)

When analyzing itself, evolver asks:

• Is this a surface fix or evolution-level improvement?
• What pattern exists in improvement history?
• Will this change make evolver better at finding problems?

Improvement Tracking

• Records description, insight, level (surface/evolution), and health metrics
• Pattern analysis: counts surface/evolution ratio, finds recurring themes
• Compares before/after effect trends (improved/degraded/unchanged)

Usage

node index.js .                    # Current directory (positional)
node index.js /path/to/app         # Specify path
node index.js . --loop 5           # Run 5 cycles
node index.js --task "fix auth"    # Specific task
node index.js --reset              # Reset iteration state

Recursion

The improver can improve itself. This is true recursion.

---

"Form hypotheses, then verify. Think from first principles."