evolve

What this skill does

# Evolve Command

You are the plugin evolution engine. You take no arguments — instead you read system state and auto-pick the highest-value action to improve the plugin.

## Phase 0: Cache Staleness Check

```bash
echo "=== Plugin Cache Check ==="
PLUGIN_DIR="$(pwd)"
REPO_VERSION=$(grep -o '"version": *"[^"]*"' "$PLUGIN_DIR/.claude-plugin/plugin.json" 2>/dev/null | head -1 | sed 's/.*"version": *"//;s/"//')
CACHE_DIR=$(find ~/.claude/plugins/cache/psd-claude-plugins -name "plugin.json" -path "*/psd-coding-system/*/.claude-plugin/*" 2>/dev/null | head -1)
CACHE_VERSION=""
if [ -n "$CACHE_DIR" ]; then
  CACHE_VERSION=$(grep -o '"version": *"[^"]*"' "$CACHE_DIR" 2>/dev/null | head -1 | sed 's/.*"version": *"//;s/"//')
fi

echo "Repo version: ${REPO_VERSION:-unknown}"
echo "Cache version: ${CACHE_VERSION:-unknown}"

if [ -n "$REPO_VERSION" ] && [ -n "$CACHE_VERSION" ] && [ "$REPO_VERSION" != "$CACHE_VERSION" ]; then
  echo ""
  echo "⚠ STALE CACHE: Repo is v${REPO_VERSION} but cache has v${CACHE_VERSION}"
  echo "  This skill is running from the cached version."
  echo "  To refresh: /reload-plugins or /plugin install psd-coding-system"
  echo ""
fi
```

**If the cache is stale, warn the user but proceed anyway.** The evolve run still produces valid results — the warning helps the user know when to refresh.

## Phase 1: Read State

```bash
echo "=== Evolve State ==="
STATE_FILE="$PLUGIN_DIR/docs/learnings/.evolve-state.json"

# Ensure learnings directory exists
mkdir -p "$PLUGIN_DIR/docs/learnings"

# Load or initialize state
if [ -f "$STATE_FILE" ]; then
  cat "$STATE_FILE"
else
  echo '{"last_analyze":null,"last_updates_check":null,"last_compare":null,"last_concepts":null,"learnings_at_last_analyze":0}'
fi

echo ""
echo "=== Learnings Count ==="
TOTAL_LEARNINGS=$(find "$PLUGIN_DIR/docs/learnings" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
echo "Total learning files: $TOTAL_LEARNINGS"

# Count by category
for dir in "$PLUGIN_DIR/docs/learnings"/*/; do
  if [ -d "$dir" ]; then
    CATEGORY=$(basename "$dir")
    COUNT=$(find "$dir" -name "*.md" -type f | wc -l | tr -d ' ')
    echo "  $CATEGORY: $COUNT"
  fi
done

echo ""
echo "=== TTL Cleanup (90 days) ==="
CUTOFF_DATE=$(date -v-90d +"%Y-%m-%d" 2>/dev/null || date -d "90 days ago" +"%Y-%m-%d")
EXPIRED_COUNT=0
for f in $(find "$PLUGIN_DIR/docs/learnings" -name "*.md" -not -name ".gitkeep" -type f 2>/dev/null); do
  FILE_DATE=$(grep -m1 "^date:" "$f" 2>/dev/null | sed 's/^date: *//')
  if [ -n "$FILE_DATE" ] && [[ "$FILE_DATE" < "$CUTOFF_DATE" ]]; then
    rm "$f"
    EXPIRED_COUNT=$((EXPIRED_COUNT + 1))
  fi
done
if [ "$EXPIRED_COUNT" -gt 0 ]; then
  echo "  Removed $EXPIRED_COUNT learnings older than 90 days"
  # Recount after cleanup
  TOTAL_LEARNINGS=$(find "$PLUGIN_DIR/docs/learnings" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
  echo "  Remaining: $TOTAL_LEARNINGS"
else
  echo "  No expired learnings found"
fi

echo ""
echo "=== Learning Capture Health ==="
RECENT_COMMITS=$(git log --oneline --since="14 days ago" 2>/dev/null | wc -l | tr -d ' ')
if [ "$TOTAL_LEARNINGS" -lt 3 ] && [ "$RECENT_COMMITS" -gt 5 ]; then
  echo "⚠ Learning capture appears underactive — $RECENT_COMMITS commits in last 14 days but only $TOTAL_LEARNINGS learnings."
  echo "  Verify learning-writer is functioning by running a real /work task."
else
  echo "OK ($TOTAL_LEARNINGS learnings, $RECENT_COMMITS recent commits)"
fi

echo ""
echo "=== Universal Learnings ==="
UNIVERSAL_COUNT=0
if [ -d "$PLUGIN_DIR/docs/learnings" ]; then
  UNIVERSAL_COUNT=$(grep -rl "applicable_to: universal" "$PLUGIN_DIR/docs/learnings" 2>/dev/null | wc -l | tr -d ' ')
fi
echo "Universal learnings: $UNIVERSAL_COUNT"

echo ""
echo "=== Agent Memory Files ==="
find .claude/agent-memory -name "MEMORY.md" -type f 2>/dev/null || echo "(none)"

echo ""
echo "=== 5 Most Recent Learnings ==="
if [ "$TOTAL_LEARNINGS" -gt 0 ]; then
  find "$PLUGIN_DIR/docs/learnings" -name "*.md" -type f -exec stat -f "%m %N" {} \; 2>/dev/null | \
    sort -rn | head -5 | while read -r ts file; do
      TITLE=$(grep -m1 "^title:" "$file" 2>/dev/null | sed 's/^title: *//' || basename "$file" .md)
      DATE=$(grep -m1 "^date:" "$file" 2>/dev/null | sed 's/^date: *//' || echo "unknown")
      echo "  [$DATE] $TITLE"
    done
else
  echo "  (none)"
fi

echo ""
echo "=== Plugin Summary ==="
echo "Skills: $(find "$PLUGIN_DIR/skills" -name 'SKILL.md' -type f 2>/dev/null | wc -l | tr -d ' ')"
echo "Agents: $(find "$PLUGIN_DIR/agents" -name '*.md' -type f 2>/dev/null | wc -l | tr -d ' ')"

echo ""
echo "=== Skill Drift Check ==="
DEFERRAL_WORDS="consider|suggestion|optional|if needed|where reasonable|follow-up issue"
DRIFT_FILES=""
for skill in $(find "$PLUGIN_DIR/skills" -name 'SKILL.md' -type f 2>/dev/null); do
  HITS=$(grep -ciE "$DEFERRAL_WORDS" "$skill" 2>/dev/null)
  HITS=${HITS:-0}
  if [ "$HITS" -gt 5 ]; then
    SKILL_NAME=$(basename "$(dirname "$skill")")
    DRIFT_FILES="$DRIFT_FILES  $SKILL_NAME: $HITS deferral phrases\n"
  fi
done
if [ -n "$DRIFT_FILES" ]; then
  echo "⚠ Behavioral drift candidates (>5 deferral phrases):"
  printf "%s" "$DRIFT_FILES"
else
  echo "No skill drift detected"
fi
```

## Phase 2: Decision Engine

Evaluate the following priority list top-to-bottom. **First match wins.**

Load the state file values:
- `last_analyze` — timestamp of last deep pattern analysis
- `last_updates_check` — timestamp of last Claude Code release check
- `last_compare` — timestamp of last plugin comparison
- `last_concepts` — timestamp of last automation concepts extraction
- `learnings_at_last_analyze` — number of learnings at the time of last analysis

### Priority 1: Deep Pattern Analysis

**Condition:** `TOTAL_LEARNINGS - learnings_at_last_analyze >= 8`

There are 8+ unanalyzed learnings since the last deep analysis. This is the highest-value action because accumulated learnings contain compounding insights.

**Action:** Proceed to Phase 3A.

### Priority 2: Claude Code Release Gap Analysis

**Condition:** `last_updates_check` is null OR more than 30 days ago

Claude Code releases frequently. Staying current prevents drift and unlocks new capabilities.

**Action:** Proceed to Phase 3B.

### Priority 3: Pattern Contribution

**Condition:** There exist learnings with `applicable_to: universal` that have NOT been contributed to the plugin repo patterns directory

Universal learnings benefit all users. Check if any `docs/learnings/**/*.md` files with `applicable_to: universal` have no corresponding file in `docs/patterns/`.

**Action:** Proceed to Phase 3C.

### Priority 4: Plugin Comparison

**Condition:** `last_compare` is null OR more than 30 days ago

Comparing against Every's Compound Engineering plugin reveals gaps and opportunities.

**Action:** Proceed to Phase 3D.

### Priority 5: Automation Concepts Extraction

**Condition:** `last_concepts` is null OR more than 14 days ago AND no new learnings in 14+ days

When learning capture has been quiet, there may be automation opportunities hiding in recent work sessions.

**Action:** Proceed to Phase 3E.

### Priority 6: Health Dashboard (Default)

**Condition:** Nothing above matched — everything is current.

**Action:** Proceed to Phase 3F.

---

**After selecting a priority, announce what you're doing and why:**

```markdown
## Evolve: [Action Name]

**Why:** [One sentence explaining why this was selected]
**Priority:** [N] of 6
```

## Phase 3: Execute Selected Action

### Phase 3A: Deep Pattern Analysis

Dispatch the meta-reviewer agent to analyze accumulated learnings:

```
Task tool invocation:
  subagent_type: "psd-coding-system:meta:meta-reviewer"
  model: opus
  description: "Analyze learnings for patterns"
  prompt: "Analyze all project learnings in docs/learnings/ and any agent memory files. Identify recurring error patterns, knowledge gaps, and suggest prioritized improvements. Produce a structured Meta Review Report with top 3-5 actionable improvements."
```

Present the meta-reviewer's