evolve

name	evolve
description	Capture positive evolutions from epic execution. Detects new components, fields, patterns, and capabilities added during implementation. Updates design registries and agent knowledge. Only proposes changes when truly new additions are found.

Evolve Skill

Purpose

Capture positive evolutions from completed epics - the new components, fields, patterns, and capabilities that were added during implementation. This complements /retro (which captures failures) by documenting what was successfully created.

Key Principle: Only propose updates for truly new additions. If an epic used existing patterns and components, no updates are needed.

When to Use

• Automatically invoked at /run-tasks Step 10 (epic completion)
• User invokes /evolve <epic-id> directly
• After any epic that added new UI components, data fields, or patterns

---

Entry Points

Invocation	Description
/evolve <epic-id>	Analyze a specific completed epic
/evolve <epic-id> --dry-run	Preview without modifying files
/run-tasks Step 10	Automatically called before epic close

---

Process

Step 1: Gather Epic Context

Get the epic's git history to understand what changed:

# Get epic branch or commit range
EPIC_ID="$1"

# Find commits associated with this epic (from commit messages)
COMMITS=$(git log --oneline --grep="$EPIC_ID" --format="%H")

# Or if on epic branch
git log main..HEAD --oneline

Get the combined diff of all changes:

# Files changed in epic
git diff main...HEAD --name-only

# Full diff for analysis
git diff main...HEAD --unified=3

Step 2: Load Existing Registries

Read current documented patterns to compare against:

# Design system registries
COMPONENTS_REGISTRY=".design/Components.md"
FIELDS_REGISTRY=".design/Fields.md"
PATTERNS_REGISTRY=".design/Patterns.md"

# Extract known components (look for ## headers or component names)
KNOWN_COMPONENTS=$(grep -E "^### " "$COMPONENTS_REGISTRY" | sed 's/### //')

# Extract known fields
KNOWN_FIELDS=$(grep -E "^\| \`" "$FIELDS_REGISTRY" | sed 's/| `//' | cut -d'`' -f1)

# Extract known patterns
KNOWN_PATTERNS=$(grep -E "^### " "$PATTERNS_REGISTRY" | sed 's/### //')

Step 3: Detect New Additions

Analyze the diff for new exports and definitions:

3a. New React Components

# Find new component exports in renderer
git diff main...HEAD -- "src/renderer/**/*.tsx" | \
  grep -E "^\\+export (const|function) [A-Z]" | \
  sed 's/+export //' | \
  awk '{print $2}' | \
  cut -d'(' -f1

Look for:

• New files in src/renderer/components/
• New export const ComponentName or export function ComponentName
• New entries in component index files

3b. New Type Definitions / Fields

# Find new interface/type definitions
git diff main...HEAD -- "src/shared/types/**/*.ts" | \
  grep -E "^\\+export (interface|type) " | \
  sed 's/+export //'

# Find new enum values
git diff main...HEAD -- "src/shared/types/**/*.ts" | \
  grep -E "^\\+  [A-Z_]+ = "

Look for:

• New fields in existing interfaces
• New interfaces/types
• New enum values
• New Zod schemas

3c. New Patterns

Analyze code structure for repeated patterns:

• New hook patterns (useXxx)
• New utility functions
• New service patterns
• New IPC handlers

# Find new hooks
git diff main...HEAD -- "src/renderer/**/*.ts" | \
  grep -E "^\\+export function use[A-Z]"

# Find new utilities
git diff main...HEAD -- "src/*/lib/**/*.ts" | \
  grep -E "^\\+export (const|function)"

Step 4: Filter Against Known

Remove items already in registries:

function filterNew(detected: string[], known: string[]): string[] {
  return detected.filter(item =>
    !known.some(k => k.toLowerCase() === item.toLowerCase())
  );
}

const newComponents = filterNew(detectedComponents, knownComponents);
const newFields = filterNew(detectedFields, knownFields);
const newPatterns = filterNew(detectedPatterns, knownPatterns);

Step 5: Generate Evolution Report

If new items found, present for approval:

## Evolution Report: <epic-id>

### Summary
- **Epic**: <title>
- **New Components**: <count>
- **New Fields/Types**: <count>
- **New Patterns**: <count>

---

### New Components

#### TaskStatusBadge
- **File**: `src/renderer/components/common/TaskStatusBadge.tsx`
- **Props**: `{ status: TaskStatus, size?: 'sm' | 'md' }`
- **Usage**: Display task status with color coding

**Suggested addition to `.design/Components.md`:**
```markdown
### TaskStatusBadge

Status indicator for beads tasks.

**Usage:**
\`\`\`tsx
<TaskStatusBadge status="in_progress" size="sm" />
\`\`\`

**Variants:** Uses status colors from Colors.md

---

New Fields/Types

TaskPriority (enum)

• File: src/shared/types/beads.ts
• Values: P0 | P1 | P2 | P3 | P4

Suggested addition to .design/Fields.md:

Field	Type	Values	Description
priority	TaskPriority	P0-P4	Task urgency (P0=critical)

---

New Patterns

useBeadsQuery Hook

• File: src/renderer/lib/hooks/useBeadsQuery.ts
• Purpose: Cached data fetching for beads with auto-refresh

Suggested addition to .design/Patterns.md:

### useBeadsQuery

Custom hook for fetching beads data with caching.

\`\`\`tsx
const { data, loading, error, refetch } = useBeadsQuery('bd list --json');
\`\`\`

---

Approval Required

Apply these evolution updates?

1. Apply all updates
2. Apply selectively (I'll specify)
3. Skip all (no changes)

### Step 6: Apply Approved Updates

For each approved item, append to the appropriate registry:

#### Components Registry
```bash
cat >> .design/Components.md << 'EOF'

---

### <ComponentName>

<description>

**Usage:**
```tsx
<example code>

Added: Epic , EOF

#### Fields Registry
```bash
# Append to table in .design/Fields.md
# Insert before the closing of the table

Patterns Registry

cat >> .design/Patterns.md << 'EOF'

---

### <PatternName>

<description>

**Example:**
```tsx
<example code>

Added: Epic EOF

### Step 7: Update Agent Knowledge (Optional)

If new capabilities were discovered, offer to update agent prompts:

```markdown
### Agent Knowledge Updates

The following agents may benefit from knowing about new patterns:

#### typescript-agent.md
**Suggested Addition:**
```diff
+ ### TaskStatusBadge
+ Use TaskStatusBadge from components/common for status display.
+ Don't create custom status badges.

Apply agent updates?

1. Yes, update agent prompts
2. No, skip agent updates

### Step 8: Archive Evolution

Create evolution record:

```bash
mkdir -p .claude/evolutions

cat > .claude/evolutions/<epic-id>.md << 'EOF'
# Evolution: <epic-id>

**Date**: <date>
**Epic**: <title>

## Additions

### Components
- TaskStatusBadge

### Fields
- priority (TaskPriority enum)

### Patterns
- useBeadsQuery hook

## Registry Updates
- .design/Components.md: +1 component
- .design/Fields.md: +1 field
- .design/Patterns.md: +1 pattern
EOF

---

Handling Edge Cases

No New Additions

When epic used only existing patterns:

## Evolution Report: <epic-id>

**No new additions detected.**

This epic successfully reused existing:
- Components: Button, Card, Badge
- Fields: status, created_at, user_id
- Patterns: useBeadsQuery, IPC handler

No registry updates needed.

Dry Run Mode

When --dry-run specified:

---

**DRY RUN: No files modified**

To apply these updates, run:
`/evolve <epic-id>` (without --dry-run)

Conflicting Names

If detected item name conflicts with existing (but different implementation):

**Warning: Name Conflict**

Detected `StatusBadge` but `.design/Components.md` already has a StatusBadge.

Options:
1. This is the same component (skip)
2. This is different - rename to `TaskStatusBadge`
3. This replaces the old one (update existing entry)

---

Registry File Formats

.design/Components.md

# Component Patterns

> UI component registry for the project

---

## Core Components

### Button
<existing documentation>

### Card
<existing documentation>

---

## Feature Components

### TaskStatusBadge
**Added**: Epic bd-x1y2, 2024-01-15

Status indicator for beads tasks.
...

.design/Fields.md

# Field Registry

> Data field definitions, types, and allowed values

---

## Core Fields

| Field | Type | Values | Description |
|-------|------|--------|-------------|
| `id` | `string` | UUID | Unique identifier |
| `created_at` | `datetime` | ISO 8601 | Creation timestamp |
| `status` | `enum` | open, closed, blocked | Current state |

---

## Feature Fields

| Field | Type | Values | Description | Added |
|-------|------|--------|-------------|-------|
| `priority` | `TaskPriority` | P0-P4 | Task urgency | bd-x1y2 |

.design/Patterns.md

# Pattern Library

> Reusable code patterns and conventions

---

## Data Fetching

### useBeadsQuery
**Added**: Epic bd-x1y2

Custom hook for beads data with caching.

```tsx
const { data, loading, refetch } = useBeadsQuery('bd list --json');

---

State Management

Zustand Store Pattern

...

---

## Integration with /run-tasks

At Step 10 (epic completion), before closing:

```markdown
All tasks complete for "<epic-title>".

**Checking for evolutions...**

Found 2 new additions:
- Component: TaskStatusBadge
- Pattern: useBeadsQuery

Options:
1. Close epic (skip evolution capture)
2. Review and capture evolutions (recommended)
3. Run retrospective + evolution capture

If user selects 2 or 3, invoke /evolve <epic-id>.

---

Integration with /discover

The discovery skill should reference registries:

## Step 3: Establish Patterns

Before designing new components, check existing registries:

**Available Components** (from .design/Components.md):
- Button, Card, Badge, Input, Select, Dialog...

**Available Fields** (from .design/Fields.md):
- id, created_at, updated_at, status, priority...

**Available Patterns** (from .design/Patterns.md):
- useBeadsQuery, IPC handler, Zustand store...

Spec should reference existing patterns where applicable.

---

Token Budget

Target: ~1500 tokens for evolution check

Component	Budget
Git diff analysis	~300
Registry comparison	~200
Generate report	~500
Apply updates	~300
Archive	~200

Skip entirely if no new additions detected (~100 tokens).

---

Configuration

# project.yaml
workflow:
  evolution:
    enabled: true
    auto_prompt: true           # Prompt at epic close
    registries:
      components: ".design/Components.md"
      fields: ".design/Fields.md"
      patterns: ".design/Patterns.md"
    detect:
      components: true
      fields: true
      patterns: true
      agent_capabilities: false  # Optional

---

Files Modified

This skill may create or modify:

Path	Action	Approval
.design/Components.md	Append	Required
.design/Fields.md	Append	Required
.design/Patterns.md	Append	Required
.claude/agents/*.md	Append	Required
.claude/evolutions/<epic-id>.md	Create	Automatic

---

Example: No Changes Needed

User: /evolve bd-abc1

Claude:

## Evolution Report: bd-abc1

Analyzing epic "Add user profile page"...

**Detected patterns used:**
- Components: Card, Button, Input, Avatar
- Fields: user_id, email, created_at
- Patterns: useBeadsQuery, Zustand store

**Comparison with registries:**
- All components already documented
- All fields already in registry
- All patterns already captured

**No new additions detected.**

This epic successfully followed existing patterns. No registry updates needed.

---

Example: New Additions Found

User: /evolve bd-xyz9

Claude:

## Evolution Report: bd-xyz9

Analyzing epic "Task dependency visualization"...

### New Additions Detected

#### Components (2 new)
1. **DependencyGraph** - `src/renderer/components/board/DependencyGraph.tsx`
   - Interactive graph showing task dependencies
   - Uses react-flow for rendering

2. **DependencyEdge** - `src/renderer/components/board/DependencyEdge.tsx`
   - Custom edge component for dependency arrows

#### Fields (1 new)
1. **blocked_by** - `string[]` - Array of task IDs that block this task

#### Patterns (1 new)
1. **useGraphLayout** - Custom hook for auto-layout of dependency graphs

---

**Apply these updates?**
1. Apply all (4 additions)
2. Apply selectively
3. Skip all

User: 1

Claude:

Applying evolution updates...

- Updated: .design/Components.md (+2 components)
- Updated: .design/Fields.md (+1 field)
- Updated: .design/Patterns.md (+1 pattern)
- Created: .claude/evolutions/bd-xyz9.md

Evolution capture complete.