open-index/open-npm huggingface dataset:
npm package: @nerdvana/evolver-adapter-claude-code
Description: > Claude Code CLI executor adapter for the Evolver framework.
Latest version: 0.2.1

# @evolver/adapter-claude-code

> Claude Code CLI executor adapter for the Evolver framework.

## Installation

```bash
pnpm add @evolver/adapter-claude-code
```

## Usage

```typescript
import { ClaudeCodeExecutor, ResultParser } from "@evolver/adapter-claude-code";

const executor = new ClaudeCodeExecutor({
  name:        "claude-code",
  command:     "claude",
  skillsPath:  "./skills",
  skillFormat: "markdown",
  timeout:     60_000,
  concurrency: 2,
});

// Execute a program against tasks (implements @evolver/core Executor interface)
const results = await executor.run(program, tasks);
```

## API

### `ClaudeCodeExecutor`

Executes tasks via the Claude Code CLI (`--print --output-format json --skill-path`). Deploys skills as `.md` files to a temp directory, runs tasks in batches with configurable concurrency, and scores results.

```typescript
new ClaudeCodeExecutor(config: AdapterConfig)
executor.run(program: Program, tasks: Task[]): Promise<ExecutionResult[]>
```

Security: uses `execFile` (no shell invocation) to prevent injection. All arguments are passed as arrays.

Built-in scorers: `exact-match` (default) and `fuzzy`.

### `ResultParser`

Static parser for Claude Code CLI stdout/stderr output.

```typescript
ResultParser.parse(taskId: string, stdout: string, stderr: string, durationMs: number): ExecutionResult
```

Handles JSON and raw text output. Extracts `tokenUsage` and promotes `result` field when present in JSON responses.

## Configuration

Uses `AdapterConfig` from `@evolver/core`:

| Option | Type | Description |
|--------|------|-------------|
| `name` | `string` | Adapter identifier |
| `command` | `string` | CLI command (e.g. `"claude"`) |
| `skillsPath` | `string` | Path to skills directory |
| `skillFormat` | `"markdown" \| "json" \| "yaml"` | Skill file format |
| `timeout` | `number` | Per-task timeout in milliseconds |
| `concurrency` | `number` | Max parallel task executions |

## Testing

```bash
pnpm test
```
npm package: @nerdvana/evolver-adapter-codex
Description: > OpenAI Codex CLI executor adapter for the Evolver framework.
Latest version: 0.2.1

# @evolver/adapter-codex

> OpenAI Codex CLI executor adapter for the Evolver framework.

## Installation

```bash
pnpm add @evolver/adapter-codex
```

## Usage

```typescript
import { CodexExecutor, SkillConverter } from "@evolver/adapter-codex";

const executor = new CodexExecutor({
  name:        "codex",
  command:     "codex",
  skillsPath:  "./skills",
  skillFormat: "markdown",
  timeout:     60_000,
  concurrency: 2,
});

// Execute tasks (implements @evolver/core Executor interface)
const results = await executor.run(program, tasks);

// Convert skills to AGENTS.md format
const agentsMd = SkillConverter.mergeAgentsMd(skills);
```

## API

### `CodexExecutor`

Executes tasks via the Codex CLI (`--quiet --approval-mode full-auto`). Converts skills to a single `AGENTS.md` file, deploys to a temp directory, and runs tasks with configurable concurrency.

```typescript
new CodexExecutor(config: AdapterConfig)
executor.run(program: Program, tasks: Task[]): Promise<ExecutionResult[]>
```

Security: uses `execFile` (no shell invocation) to prevent injection.

Built-in scorers: `exact-match` (default) and `fuzzy`.

### `SkillConverter`

Converts SKILL.md format to Codex's `AGENTS.md` format. Each skill becomes a `## heading` section.

```typescript
SkillConverter.toAgentsMd(skill: Skill): string
SkillConverter.mergeAgentsMd(skills: Skill[]): string
```

## Configuration

Uses `AdapterConfig` from `@evolver/core`:

| Option | Type | Description |
|--------|------|-------------|
| `name` | `string` | Adapter identifier |
| `command` | `string` | CLI command (e.g. `"codex"`) |
| `skillsPath` | `string` | Path to skills directory |
| `skillFormat` | `"markdown" \| "json" \| "yaml"` | Skill file format |
| `timeout` | `number` | Per-task timeout in milliseconds |
| `concurrency` | `number` | Max parallel task executions |

## Testing

```bash
pnpm test
```
npm package: @nerdvana/evolver-adapter-cursor
Description: > Cursor IDE CLI executor adapter for the Evolver framework.
Latest version: 0.2.1

# @evolver/adapter-cursor

> Cursor IDE CLI executor adapter for the Evolver framework.

## Installation

```bash
pnpm add @evolver/adapter-cursor
```

## Usage

```typescript
import { CursorExecutor, SkillConverter } from "@evolver/adapter-cursor";
import type { CursorRulesOutput } from "@evolver/adapter-cursor";

const executor = new CursorExecutor({
  name:        "cursor",
  command:     "cursor",
  skillsPath:  "./skills",
  skillFormat: "markdown",
  timeout:     60_000,
  concurrency: 2,
});

// Execute tasks (implements @evolver/core Executor interface)
const results = await executor.run(program, tasks);

// Convert a single skill to Cursor format
const output: CursorRulesOutput = SkillConverter.toCursorRules(skill);
// output.cursorrules -> .cursorrules file content
// output.rules       -> { "skill-name.md": content }

// Merge multiple skills into one .cursorrules
const merged = SkillConverter.mergeCursorRules(skills);
```

## API

### `CursorExecutor`

Executes tasks via the Cursor CLI (`--cli --output-format json`). Converts skills to `.cursorrules` + `rules/*.md` format, deploys to a temp directory, and runs tasks with configurable concurrency.

```typescript
new CursorExecutor(config: AdapterConfig)
executor.run(program: Program, tasks: Task[]): Promise<ExecutionResult[]>
```

Security: uses `execFile` (no shell invocation) to prevent injection.

Built-in scorers: `exact-match` (default) and `fuzzy`.

### `SkillConverter`

Converts SKILL.md format to Cursor's `.cursorrules` + `rules/` directory structure.

```typescript
SkillConverter.toCursorRules(skill: Skill): CursorRulesOutput
SkillConverter.mergeCursorRules(skills: Skill[]): string
SkillConverter.buildRulesMap(skills: Skill[]): Record<string, string>
```

### `CursorRulesOutput`

```typescript
interface CursorRulesOutput {
  cursorrules: string;              // .cursorrules file content
  rules:       Record<string, string>; // rules/ directory files
}
```

## Configuration

Uses `AdapterConfig` from `@evolver/core`:

| Option | Type | Description |
|--------|------|-------------|
| `name` | `string` | Adapter identifier |
| `command` | `string` | CLI command (e.g. `"cursor"`) |
| `skillsPath` | `string` | Path to skills directory |
| `skillFormat` | `"markdown" \| "json" \| "yaml"` | Skill file format |
| `timeout` | `number` | Per-task timeout in milliseconds |
| `concurrency` | `number` | Max parallel task executions |

## Testing

```bash
pnpm test
```
npm package: @nerdvana/evolver-cli
Description: > Command-line interface for the Evolver skill evolution framework.
Latest version: 0.2.1

# @evolver/cli

> Command-line interface for the Evolver skill evolution framework.

## Installation

```bash
pnpm add -g @evolver/cli
```

## Usage

### `evolver evolve` -- Run the evolution loop

```bash
evolver evolve \
  --task-dir ./tasks \
  --adapter claude-code \
  --max-iterations 10 \
  --frontier-capacity 3 \
  --budget-limit 5.0
```

### `evolver status` -- Show last run status

```bash
evolver status
```

Reads `.evolver/state.json` and prints last run timestamp, iterations, cost, best program score, frontier size, and discovered skills.

### `evolver skills list` -- List discovered skills

```bash
evolver skills list --skills-dir ./skills
```

### `evolver skills export` -- Export skills to another format

```bash
evolver skills export --format cursor --output .cursorrules
```

### `evolver skills test` -- Cross-model transfer test

```bash
evolver skills test \
  --cross-model \
  --task-dir ./tasks \
  --source claude-code \
  --target cursor,codex
```

## API

### Commands

| Command | Description |
|---------|-------------|
| `evolve` | Run the skill evolution loop |
| `status` | Show current evolution status from `.evolver/state.json` |
| `skills list` | List discovered skills in the skills directory |
| `skills export` | Export skills to another agent format (e.g. Cursor `.cursorrules`) |
| `skills test` | Run cross-model skill transfer tests |

### Modules

#### `loadConfig(taskDir: string): TaskConfig`

Parses `config.yaml` from the task directory.

#### `loadTasks(taskDir: string, subDir: string, defaultScorer?: ScorerType): Task[]`

Loads YAML task files from `{taskDir}/{subDir}/` into `Task[]` arrays.

#### `saveState(state: EvolverState): void` / `loadState(): EvolverState | null`

Persists/loads evolution state to/from `.evolver/state.json`.

## Configuration

### `evolve` command options

| Option | Default | Description |
|--------|---------|-------------|
| `--task-dir <path>` | (required) | Path to tasks directory |
| `--skills-dir <path>` | `./skills` | Output skills directory |
| `--adapter <name>` | `claude-code` | Executor adapter (`claude-code`, `cursor`, `codex`) |
| `--proposer-model <model>` | `claude-sonnet-4-6` | Model for proposal generation |
| `--builder-model <model>` | `claude-haiku-4-5` | Model for skill materialization |
| `--runs <n>` | `3` | Runs per evaluation |
| `--budget-limit <usd>` | none | Maximum budget in USD |
| `--frontier-capacity <n>` | `3` | Pareto frontier capacity |
| `--max-iterations <n>` | `10` | Maximum evolution iterations |
| `--failure-threshold <n>` | `0.5` | Score threshold for failure |
| `--plugin <name>` | none | Plugin to load (e.g. `memento`) |
| `--memento-url <url>` | none | Memento MCP server URL |
| `--memento-key <key>` | none | Memento MCP access key |

### Task directory structure

```
tasks/
  config.yaml          # Optional: default scorer, categories
  train/
    task-001.yaml      # { id, input, expected, category?, scorer? }
    task-002.yaml
  validation/
    task-010.yaml
```

## Testing

```bash
pnpm test
```
npm package: @nerdvana/evolver-plugin-memento
Description: > Memento MCP memory system plugin for the Evolver evolution loop.
Latest version: 0.2.1

# @evolver/plugin-memento

> Memento MCP memory system plugin for the Evolver evolution loop.

## Installation

```bash
pnpm add @evolver/plugin-memento
```

## Usage

```typescript
import { MementoClient, MementoPlugin } from "@evolver/plugin-memento";

// Create client
const client = new MementoClient({
  url:       "https://pmcp.nerdvana.kr/mcp",
  accessKey: process.env.MEMENTO_ACCESS_KEY!,
});

// Create plugin (implements @evolver/core Plugin interface)
const plugin = new MementoPlugin(client);

// Pass to EvolutionLoop
const loop = new EvolutionLoop({
  // ...other options
  plugins: [plugin],
});
```

The plugin hooks into the evolution loop lifecycle:

| Hook | Behavior |
|------|----------|
| `onFailure` | Recalls past similar errors from memory |
| `onProposal` | Recalls past skill evolution history |
| `onEvaluation` | Remembers skill evaluation results |
| `onFrontierUpdate` | Remembers frontier snapshots |

## API

### `MementoPlugin`

Bridges the Evolver plugin system with memento-mcp's remember/recall/forget tools.

```typescript
new MementoPlugin(client: MementoClient)
// Plugin.name = "memento"
// Plugin.hooks: { onFailure, onProposal, onEvaluation, onFrontierUpdate }
```

### `MementoClient`

MCP JSON-RPC client for memento-mcp. Handles `initialize` handshake and `tools/call` invocations.

```typescript
new MementoClient(config: MementoClientConfig)
client.remember(params: RememberParams): Promise<{ id: string }>
client.recall(params: RecallParams): Promise<RecallResult>
client.forget(params: ForgetParams): Promise<{ success: boolean }>
```

### Types

```typescript
interface MementoClientConfig {
  url:       string;   // MCP server URL
  accessKey: string;   // Bearer token
}

interface RememberParams {
  content:     string;
  topic:       string;
  type:        string;
  importance?: number;
}

interface RecallParams {
  keywords?: string[];
  topic?:    string;
  type?:     string;
}

interface ForgetParams {
  id: string;
}

interface MementoFragment {
  id:      string;
  content: string;
  type:    string;
}

interface RecallResult {
  fragments: MementoFragment[];
}
```

## Configuration

| Option | Type | Description |
|--------|------|-------------|
| `url` | `string` | Memento MCP server endpoint |
| `accessKey` | `string` | Bearer authentication token |

## Testing

```bash
pnpm test
```
npm package: @nerdvana/evolver-proposer
Description: > LLM-powered skill proposal generator with failure pattern analysis.
Latest version: 0.2.1

# @evolver/proposer

> LLM-powered skill proposal generator with failure pattern analysis.

## Installation

```bash
pnpm add @evolver/proposer
```

## Usage

```typescript
import { LlmProposer, groupByPattern } from "@evolver/proposer";

// Create a proposer (implements @evolver/core Proposer interface)
const proposer = new LlmProposer({
  model:  "claude-sonnet-4-6", // optional, default
  apiKey: process.env.ANTHROPIC_API_KEY, // optional, falls back to env
});

// Propose a skill from failures
const proposal = await proposer.propose(failures, feedbackHistory, pluginContext);
// proposal: { action, skillName, trigger, description, rationale, editTarget? }

// Analyze failure patterns independently
const groups = groupByPattern(failures);
// groups: FailureGroup[] with pattern, failures, summary
```

## API

### `LlmProposer`

Calls the Anthropic API to generate a `SkillProposal` based on failure analysis and proposal history.

```typescript
new LlmProposer(config?: LlmProposerConfig)
proposer.propose(
  failures: Failure[],
  history:  FeedbackEntry[],
  context?: PluginContext,
): Promise<SkillProposal>
```

### `groupByPattern(failures: Failure[]): FailureGroup[]`

Groups failures by normalized error message + category. O(n) single pass. Returns groups with pattern key, failure list, and human-readable summary.

### `FailureGroup`

```typescript
interface FailureGroup {
  pattern:  string;      // "category::normalized-error"
  failures: Failure[];
  summary:  string;      // Human-readable group summary
}
```

### `LlmProposerConfig`

```typescript
interface LlmProposerConfig {
  model?:  string; // Anthropic model ID (default: "claude-sonnet-4-6")
  apiKey?: string; // API key (default: ANTHROPIC_API_KEY env var)
}
```

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `model` | `string` | `"claude-sonnet-4-6"` | Anthropic model for proposal generation |
| `apiKey` | `string` | `ANTHROPIC_API_KEY` env | Anthropic API key |

## Testing

```bash
pnpm test
```
npm package: @nerdvana/evolver-skill-builder
Description: > Materializes skill proposals into concrete SKILL.md files via LLM generation.
Latest version: 0.2.1

# @evolver/skill-builder

> Materializes skill proposals into concrete SKILL.md files via LLM generation.

## Installation

```bash
pnpm add @evolver/skill-builder
```

## Usage

```typescript
import { SkillMaterializer, META_SKILL } from "@evolver/skill-builder";

// Create a skill builder (implements @evolver/core SkillBuilder interface)
const builder = new SkillMaterializer({
  model: "claude-haiku-4-5", // optional, default
});

// Build a Skill from a SkillProposal
const skill = await builder.build(proposal, parentSkills, pluginContext);
// skill: { name, trigger, content, scripts? }

// Access the meta-skill prompt for custom use
console.log(META_SKILL);
```

## API

### `SkillMaterializer`

Calls the Anthropic API with the META_SKILL best-practice prompt to generate SKILL.md content and optional helper scripts from a `SkillProposal`.

```typescript
new SkillMaterializer(options?: { model?: string; client?: Anthropic })
builder.build(
  proposal:     SkillProposal,
  parentSkills: Skill[],
  context?:     PluginContext,
): Promise<Skill>
builder.parseResponse(text: string, proposal: SkillProposal): Skill
```

The LLM response is expected to contain:
- A ```` ```markdown ``` ```` block with SKILL.md content (YAML frontmatter + body)
- Optional ```` ```typescript:filename ``` ```` blocks for helper scripts

### `META_SKILL`

Exported constant string containing skill authoring best practices. Covers SKILL.md structure, trigger rules, procedural instructions, content guidelines, and script conventions. Injected as system prompt during skill generation.

## Configuration

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `model` | `string` | `"claude-haiku-4-5"` | Anthropic model for skill generation |
| `client` | `Anthropic` | auto-created | Custom Anthropic SDK client instance |

## Testing

```bash
pnpm test
```