Evo

/evo — AI Self-Evolution

Parse arguments then route to the correct mode file. Each mode file contains full instructions.

Argument Parsing

/evo                    → mode: scan, depth: standard (auto: full/incremental/self-test)
/evo deep               → mode: scan, depth: deep
/evo help               → print the command quick reference below, then stop (no scan)

/evo pin                → mode: anchor, ANCHOR_SUB=create, ANCHOR_NAME=(empty)
/evo pin <name>         → mode: anchor, ANCHOR_SUB=create, ANCHOR_NAME=name
/evo pin <name> <desc>  → mode: anchor, ANCHOR_SUB=create, ANCHOR_NAME=name, ANCHOR_DESC=rest
/evo pin list           → mode: anchor, ANCHOR_SUB=list
/evo pin diff [name]    → mode: anchor, ANCHOR_SUB=diff, ANCHOR_NAME=name or empty
/evo pin rm <name>      → mode: anchor, ANCHOR_SUB=delete, ANCHOR_NAME=name

/evo back               → mode: restore, ANCHOR_NAME=(empty)
/evo back <name>        → mode: restore, ANCHOR_NAME=name
/evo back --no-learn    → mode: restore, NO_LEARN=yes (flag works with or without a name)

/evo learn              → mode: learn, DESCRIPTION=(empty)
/evo learn <desc>       → mode: learn, DESCRIPTION=rest of args
/evo learn + <knowledge>→ mode: teach, KNOWLEDGE=rest after "+"

/evo st | status        → run: bash scripts/snap.sh status (then stop)

Rules (first match wins): 0. First arg is help, --help, -h, or ? → print the quick reference below, then stop

1. First arg is pin → anchor mode
   • Second arg list or ls → anchor/list
   • Second arg diff → anchor/diff (third arg = name, optional)
   • Second arg rm → anchor/delete (third arg = name, REQUIRED)
   • Otherwise → anchor/create (second arg = name if present, rest = description)
2. First arg is back → restore
   • Strip --no-learn from anywhere in the remaining args → NO_LEARN=yes
   • What remains (if anything) = ANCHOR_NAME; empty means restore mode asks or defaults
3. First arg is learn:
   • If second arg is + → teach mode (rest after + = KNOWLEDGE)
   • Otherwise → learn mode (rest = DESCRIPTION)
4. First arg is st or status → status (run script, done)
5. First arg is deep → scan with deep depth
6. No args or anything else → scan with standard depth

Quick Reference (for /evo help)

/evo                     Scan project (auto: full / incremental / self-test)
/evo deep                Deep scan with per-module analysis
/evo pin [name [desc]]   Freeze current understanding (+code) as a baseline.
                         Empty name → auto-named baseline-<timestamp>
/evo pin list            List pinned baselines
/evo pin diff [name]     Cognitive diff: current snapshot vs a pin
/evo pin rm <name>       Delete a pin
/evo back [name]         Auto-capture lesson, then restore a baseline (+wisdom)
/evo back --no-learn     Restore without capturing a lesson first
/evo learn [desc]        Extract a lesson from the current conversation
/evo learn + <text>      Inject knowledge the AI cannot discover from code
/evo st                  Status: version, snapshot age, pins, lessons, include tier

Routing

After determining the mode, read the corresponding mode file and follow its instructions exactly:

Read the mode file, substitute any {{VARIABLES}}, then execute the instructions within it.

Note: restore mode reads modes/learn.md itself (with {{QUIET}} = yes) to auto-capture a lesson before restoring. scan mode similarly delegates to modes/examine.md for self-tests.

Mechanical Operations

All git queries, file counting, meta.json I/O, token estimation, and status display are handled by scripts/snap.sh. Call it via Bash:

bash scripts/snap.sh <command> [args...]

Key commands: git_info, has_snapshot, meta_read, meta_write, ensure_dirs, status, count_source_files, count_constraints, count_lessons, estimate_tokens, doc_header, include_block, anchor_create, anchor_list, anchor_get, anchor_delete, anchor_exists, anchor_active, anchor_set_active, anchor_resolve, anchor_picker, anchor_count, anchor_doc_list, code_capture, code_ref_exists, code_archive, code_restore, code_diff_stat, code_changed_files, code_missing_paths.

Code State

Pins freeze both understanding and the code it describes. Code lives in refs/evo/pins/<safe_name> (built by git stash create, so uncommitted work is included and the working tree is never touched). Restoring is always the user's explicit choice — see modes/restore.md Phase 2.5.

Two limits to respect and surface, never paper over:

• Untracked files are not captured. git stash create ignores them. anchor_create reports the count so the user can git add first.
• git gc --prune with an aggressive expiry can still drop refs, though refs/evo/* protects against normal gc. code_ref_exists returns "no" in that case; treat the pin as docs-only.

Guidelines

• Never include conversational filler in generated documents. Every line conveys information.
• Always include file path references (e.g., src/auth/middleware.ts:42) in architecture docs.
• Prefer project-relative paths over absolute paths.
• Launch agents in a single message for maximum parallelism.
• Token estimates: character_count / 4.
• For non-git projects, skip git features gracefully.
• .claude/snapshot/ should be in .gitignore unless user explicitly wants to version-control it.