helixevo 0.2.0

package/README.md

@@ -0,0 +1,193 @@
+# Helix
+
+Self-evolving skill ecosystem for AI agents. Captures failures, evolves skills through multi-judge evaluation, and maintains a Pareto frontier of optimal skill configurations.
+
+## How it works
+
+Helix builds on ideas from [EvoSkill](https://arxiv.org/abs/2603.02766) and [AutoResearch](https://github.com/karpathy/autoResearch) to create a three-directional evolution system:
+
+- **Generalize ↑** — Detect cross-project patterns and promote them to abstract skills
+- **Specialize ↓** — Create project-specific skills from domain skills + project failures
+- **Lateral ↔** — Merge, split, and resolve conflicts between skills
+
+Every proposed change goes through:
+1. **3 independent LLM judges** (Task Completion, Correction Alignment, Side-Effect Check)
+2. **Regression testing** against golden cases
+3. **3-day canary deployment** with auto-rollback
+
+## Prerequisites
+
+- **Node.js 18+**
+- **[Bun](https://bun.sh)** — used for building (`curl -fsSL https://bun.sh/install | bash`)
+- **[Claude CLI](https://docs.anthropic.com/en/docs/claude-code)** — installed and authenticated
+  - Requires a **Claude Max plan** subscription
+  - Helix uses `claude --print` for all LLM operations (no API key needed)
+
+Verify prerequisites:
+```bash
+node --version    # v18+
+bun --version     # any
+claude --version  # any
+```
+
+## Install
+
+### From npm (recommended)
+
+```bash
+npm install -g helixevo
+```
+
+### From GitHub
+
+```bash
+npm install -g github:danielchen26/helixevo
+```
+
+### From source
+
+```bash
+git clone https://github.com/danielchen26/helixevo.git
+cd helixevo
+npm install
+npm run build
+npm link
+```
+
+## Quick Start
+
+```bash
+# 1. Initialize — imports existing skills + generates golden cases
+helixevo init
+
+# 2. Capture failures from a session
+helixevo capture path/to/session.json --project myapp
+
+# 3. Evolve skills from failures
+helixevo evolve --verbose
+
+# 4. View the skill network
+helixevo graph
+
+# 5. Open the web dashboard
+helixevo dashboard
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `helixevo watch` | Always-on learning: auto-capture + auto-evolve |
+| `helixevo metrics` | Correction rates, skill trends, evolution impact |
+| `helixevo health` | Network health: cohesion, coverage, balance, transfer |
+| `helixevo init` | Import existing skills + generate golden cases |
+| `helixevo capture <session>` | Extract failures from a session file |
+| `helixevo evolve` | Evolve skills from captured failures |
+| `helixevo generalize` | Promote cross-project patterns ↑ |
+| `helixevo specialize --project <name>` | Create project-specific skills ↓ |
+| `helixevo graph` | View skill network in terminal |
+| `helixevo research` | Proactive web research for skill improvement |
+| `helixevo dashboard` | Open web dashboard at localhost:3847 |
+| `helixevo status` | Show system health |
+| `helixevo report` | Generate evolution report |
+
+### Common options
+
+Most commands support:
+- `--dry-run` — Preview changes without applying
+- `--verbose` — Show detailed LLM interactions
+
+### Graph options
+
+```bash
+helixevo graph                    # TUI view (instant, cached)
+helixevo graph --mermaid          # Open in browser as Mermaid diagram
+helixevo graph --obsidian ~/vault # Sync to Obsidian vault
+helixevo graph --rebuild          # Re-infer relationships (LLM call)
+helixevo graph --optimize         # Detect merge/split/conflict opportunities
+```
+
+### Research options
+
+```bash
+helixevo research --verbose             # Full output
+helixevo research --project ./myapp     # Focus research on a project
+helixevo research --max-hypotheses 5    # Test more hypotheses
+helixevo research --dry-run             # Preview without creating skills
+```
+
+## Data
+
+All data is stored in `~/.helix/`:
+
+```
+~/.helix/
+├── config.json              # Configuration
+├── failures.jsonl           # Captured failures
+├── frontier.json            # Pareto frontier (top-k configurations)
+├── evolution-history.json   # All evolution runs + proposals
+├── golden-cases.jsonl       # Regression test cases
+├── skill-graph.json         # Cached network (nodes + edges)
+├── canary-registry.json     # Active canary deployments
+├── knowledge-buffer.json    # Research discoveries + drafts
+├── general/                 # Skills (SKILL.md files)
+│   ├── my-skill/SKILL.md
+│   └── ...
+├── backups/                 # Pre-canary skill backups
+└── reports/                 # Generated reports
+```
+
+## Web Dashboard
+
+The dashboard provides an interactive view of your skill ecosystem:
+
+```bash
+helixevo dashboard
+# Opens http://localhost:3847
+```
+
+**Tabs:**
+- **Overview** — Stats, frontier programs, recent evolution
+- **Skill Network** — Interactive graph + skill cards + project view + co-evolution analysis
+- **Evolution** — Timeline of all evolution runs with judge scores
+- **Research** — Knowledge buffer: discoveries and drafts
+- **Frontier** — Pareto frontier with 4-dimension scores + canary status
+
+The dashboard requires Next.js dependencies. On first run:
+```bash
+cd dashboard && npm install
+```
+
+## Craft Agent Integration
+
+Helix includes a Craft Agent skill at `integrations/craft-agent/`:
+
+```bash
+# Copy to your skills directory
+cp -r integrations/craft-agent/skills/skill-evolver ~/.agents/skills/
+```
+
+Then use `[skill:skill-evolver]` in Craft Agent to trigger evolution.
+
+## Architecture
+
+```
+Failures → Cluster → Propose → Replay → Multi-Judge → Regression → Canary → Frontier
+              │                              │
+              │                     3 independent judges:
+              │                     - Task Completion
+              │                     - Correction Alignment
+              │                     - Side-Effect Check
+              │
+         Knowledge Buffer
+         (discoveries + drafts from rejected proposals)
+```
+
+**Three-layer hierarchy:**
+- **System** — Global agent behaviors
+- **Domain** — Cross-project patterns (generalized skills)
+- **Project** — Project-specific specializations
+
+## License
+
+MIT