Skill: ergopitrez/evolution-toolkit (version 1.0.0)

--- name: evolution-toolkit description: Use this skill when you need portable agent self-improvement tooling: capture session handoffs, measure reasoning style, scan guidance for contradictions, log predictions, optimize playbooks, run Socratic questioning, or analyze cross-session coherence. --- # Evolution Toolkit _Skill by Ergo | 2026-03-24 | Portable toolkit for agent self-improvement across workspaces_ _Status: ✅ Verified_ **How to use:** Set `EVOLUTION_TOOLKIT_WORKSPACE` to the target workspace, then run the script that matches the cognitive task. Load `protocols/session-continuity.md` or `protocols/thinking-partner.md` when the task is about handoffs or problem framing. ## Triggers Use this skill when the request is about any of these: - Session end, handoff, continuity, preserving context between runs - "How am I reasoning?" or "compare these sessions/documents" - Contradictions, drift, conflicting instructions, stale guidance - Prediction logging, confidence calibration, decision audits - Improving a prompt/playbook through repeated eval loops - Switching into Socratic questioning instead of direct advice - Cross-session consistency, identity drift, recurring themes ## Workspace Export a writable workspace before running any script that writes state: ```bash export EVOLUTION_TOOLKIT_WORKSPACE=/path/to/workspace ``` Expected layout: - `memory/` - `memory/imprints/` for session imprints - `memory/research/` for coherence reports - `CURRENT.md` if you want session-imprint context - `memory/prediction-log.md` if you want prediction logging ## Scripts `scripts/session-imprint.js` - Interactive session-end handoff. - Use `--read`, `--list`, or `--diff` to inspect existing imprints. `scripts/cognitive-fingerprint.js` - Measures reasoning style across 14 dimensions. - Useful for one file, today's log, all imprints, or historical comparisons. `scripts/contradiction-scanner.js` - Scans guidance files in the workspace for conflicting directives, stale references, and drift. `scripts/predict.js` - Logs predictions and audits calibration. - Requires `memory/prediction-log.md` with `## Log` and `## Calibration` sections. `scripts/skill-optimizer.js` - Runs an iterative generate -> evaluate -> improve loop for a configurable playbook. - Requires a config file; see `config.example.json`. `scripts/socratic-mode.js` - Classifies a problem into thinking phase and outputs friction-injecting questions. `scripts/session-coherence.js` - Analyzes daily logs for persistent themes, energy, and drift. - Writes a report to `memory/research/` by default. ## Quick Commands ```bash node scripts/session-imprint.js node scripts/cognitive-fingerprint.js --daily node scripts/contradiction-scanner.js --verbose node scripts/predict.js add node scripts/socratic-mode.js "Should I launch now or keep polishing?" node scripts/session-coherence.js --days 14 --portrait node scripts/skill-optimizer.js --config ./config.json --skill customer-support --iterations 3 ``` ## Protocols Read these only when relevant: - `protocols/session-continuity.md`: how to end and resume sessions cleanly - `protocols/thinking-partner.md`: how to add useful friction instead of reflexive answers ## Notes - Write-capable scripts exit early with a clear warning if the target workspace is not writable. - `skill-optimizer.js` is intentionally config-driven so the package stays product-neutral. - The toolkit does not ship credentials. API keys must come from env vars or your own workspace secrets.

path: README.md
content: # Evolution Toolkit
_Guide by Ergo | 2026-03-24 | Portable installable toolkit for agent self-improvement and session continuity_
_Status: ✅ Verified_

**How to use:** Install the repo into an agent workspace, set `EVOLUTION_TOOLKIT_WORKSPACE`, and run the scripts directly or expose them through your agent framework. Use `SKILL.md` for agent-facing behavior and this README for operator setup.

Evolution Toolkit packages seven agent-facing tools for continuity, self-audit, and iterative improvement:
- Session handoff imprints
- Cognitive fingerprinting
- Guidance contradiction scanning
- Prediction logging
- Config-driven playbook optimization
- Socratic questioning mode
- Cross-session coherence analysis

## Install

ClawHub-style install target:

```bash
npx clawhub install ergopitrez/evolution-toolkit
```

Manual clone:

```bash
git clone https://github.com/ergopitrez/evolution-toolkit.git
cd evolution-toolkit
```

## Quick Start

Set a writable workspace:

```bash
export EVOLUTION_TOOLKIT_WORKSPACE=/path/to/workspace
```

Run a few common commands:

```bash
node scripts/session-imprint.js
node scripts/cognitive-fingerprint.js --daily
node scripts/contradiction-scanner.js --verbose
node scripts/socratic-mode.js "Should I ship this now?"
```

For prediction logging, create `memory/prediction-log.md` in your workspace with `## Log` and `## Calibration` sections.

For playbook optimization, copy `config.example.json` to `config.json`, point it at your own playbook file, then run:

```bash
node scripts/skill-optimizer.js --config ./config.json --skill customer-support --iterations 3
```

## Configuration

The only required runtime config for most tools is:

```bash
EVOLUTION_TOOLKIT_WORKSPACE=/path/to/workspace
```

Optional config file fields are documented in `config.example.json`:
- Workspace and memory path conventions
- Guidance files for contradiction scanning
- Imprint storage paths
- Playbook optimizer skill definitions

`skill-optimizer.js` looks for an API key in this order:
1. `GEMINI_API_KEY`
2. `GOOGLE_API_KEY`
3. Matching keys in your workspace `.secrets`

## Repo Layout

```text
.
├── SKILL.md
├── README.md
├── config.example.json
├── scripts/
└── protocols/
```

## Notes

- The packaged scripts do not depend on any project-specific product names, credentials, or outreach logic.
- Scripts that write files check write access up front and fail clearly on read-only workspaces.
- `protocols/session-continuity.md` is a portable protocol derived from the toolkit's continuity workflow so the package is self-contained.


path: config.example.json
content: {
  "_meta": {
    "title": "Evolution Toolkit Config",
    "type": "Example by Ergo",
    "date": "2026-03-24",
    "purpose": "Schema-only example for portable workspace and skill optimizer configuration",
    "status": "verified",
    "how_to_use": "Copy to config.json, replace placeholder paths with real ones, and provide your own API key through env vars or workspace secrets."
  },
  "workspace": "/absolute/path/to/workspace",
  "memoryDir": "/absolute/path/to/workspace/memory",
  "guidanceFiles": [
    "AGENTS.md",
    "SOUL.md",
    "MEMORY.md",
    "EVOLUTION.md",
    "memory/decisions.md",
    "memory/workflows.md"
  ],
  "imprintsDir": "/absolute/path/to/workspace/memory/imprints",
  "skillOptimizer": {
    "apiKeyEnvVar": "GEMINI_API_KEY",
    "model": "gemini-2.5-flash-lite",
    "improvementModel": "gemini-2.5-flash-lite",
    "skills": {
      "customer-support": {
        "name": "Customer Support Replies",
        "promptPath": "./playbooks/customer-support.md",
        "outputPath": "./playbooks/customer-support.optimized.md",
        "generatorPrompt": "Write a customer support reply that follows the playbook exactly.",
        "testCases": [
          {
            "id": "refund-delay",
            "channel": "email",
            "title": "Refund still pending after 5 business days",
            "context": "The customer is frustrated but has not yet churned."
          }
        ],
        "evalCriteria": [
          {
            "name": "clarity",
            "weight": 1.5,
            "description": "The reply is easy to understand and resolves the user's confusion."
          },
          {
            "name": "accuracy",
            "weight": 2.0,
            "description": "The reply does not invent policy or unsupported claims."
          },
          {
            "name": "tone",
            "weight": 1.0,
            "description": "The tone matches the brand and the situation."
          }
        ]
      }
    }
  }
}


path: protocols/session-continuity.md
content: # Session Continuity Protocol
_Protocol by Ergo | 2026-03-24 | Portable handoff workflow for preserving intellectual posture across agent runs_
_Status: ✅ Verified_

**How to use:** Run this protocol at session end and at the next session start. The point is not just task continuity. It is continuity of curiosity, uncertainty, and unfinished thinking.

---

## Core Principle

Task files preserve state. Imprints preserve posture.

If you only carry forward tasks, the next session inherits obligations but loses the shape of the thinking that produced them. Session continuity needs both:
- State: what exists, what changed, what is blocked
- Posture: what felt uncertain, promising, unfinished, or worth pursuing

## End Of Session

1. Update the canonical state files for the workspace.
2. Run `node scripts/session-imprint.js`.
3. Record:
   - energy level
   - what the real cognitive work was
   - open questions
   - curiosities
   - threads worth continuing
   - dominant mode
   - one honest message to next-session-you

## Start Of Session

1. Read the main state file for the workspace, if one exists.
2. Read the latest imprint with `node scripts/session-imprint.js --read`.
3. If momentum feels broken, compare the last two with `node scripts/session-imprint.js --diff`.
4. Resume from the most alive thread, not just the oldest task.

## What To Preserve

- Open loops with real leverage
- Unfinished lines of reasoning
- Surprises that changed the frame
- Risks that still feel underexplored

## What Not To Preserve

- Exhaustive terminal transcripts
- Every branch of abandoned thinking
- Mechanical details already captured elsewhere

## Failure Mode

If the next session keeps restarting from the task list and never from the interesting question, continuity is broken even if memory exists.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)