makepad-evolution

Makepad Skills Evolution

This skill enables makepad-skills to self-improve continuously during development.

Automatic vs Manual Triggers

IMPORTANT FOR CLAUDE: Some mechanisms should trigger automatically without user request.

Automatic (Claude should do proactively)

| Mechanism | When to Auto-Trigger | |-----------|---------------------| | Version Adaptation | At session start, read Cargo.toml and detect Makepad branch | | Personalization | On first code generation, scan 2-3 existing widgets for style | | Self-Correction | Immediately when skill-suggested code fails | | Usage Feedback | After each pattern usage (success or failure) |

Semi-Automatic (Claude proposes, user confirms)

| Mechanism | When to Propose | |-----------|-----------------| | Self-Evolution | After solving a non-trivial problem worth documenting |

Manual (User must request)

| Mechanism | Trigger Phrase | |-----------|---------------| | Self-Validation | "validate makepad-skills" | | Health Report | "show pattern health report" |

Session Start Checklist (Auto-Execute)

When starting a Makepad development session, Claude should automatically:

1. [ ] Detect Makepad version from Cargo.toml
       → Set internal context: "Using Makepad {branch}"

2. [ ] Scan project style (if not done before)
       → Note naming conventions, module structure

3. [ ] Apply version-specific and personalized suggestions
       → All subsequent advice adapted automatically

Claude: Do these silently. Don't announce unless relevant to user's question.

When to Evolve

Trigger skill evolution when any of these occur during development:

| Trigger | Target Skill | Priority | |---------|--------------|----------| | New widget pattern discovered | makepad-patterns | High | | Shader technique learned | makepad-shaders | High | | Compilation error solved | makepad-troubleshooting | High | | Layout solution found | makepad-adaptive-layout | Medium | | Build/packaging issue resolved | makepad-packaging | Medium | | New project structure insight | makepad-init | Low | | Core concept clarified | makepad-fundamentals | Low |

Evolution Process

Step 1: Identify Knowledge Worth Capturing

Ask yourself:

• Is this a reusable pattern? (not project-specific)
• Did it take significant effort to figure out?
• Would it help other Makepad developers?
• Is it not already documented in makepad-skills?

Step 2: Classify the Knowledge

Widget/Component Pattern     → makepad-patterns/SKILL.md
Shader/Visual Effect         → makepad-shaders/SKILL.md
Error/Debug Solution         → makepad-troubleshooting/SKILL.md
Layout/Responsive Design     → makepad-adaptive-layout/SKILL.md
Build/Deploy Issue           → makepad-packaging/SKILL.md
Project Structure            → makepad-init/SKILL.md
Core Concept/API             → makepad-fundamentals/SKILL.md

Step 3: Format the Contribution

For Patterns (makepad-patterns):

## Pattern N: [Pattern Name]

Brief description of what this pattern solves.

### live_design!
\```rust
live_design! {
    // DSL code
}
\```

### Rust Implementation
\```rust
// Rust code
\```

### Usage
\```rust
// How to use
\```

For Troubleshooting (makepad-troubleshooting):

### [Error Type/Message]

**Symptom**: What the developer sees

**Cause**: Why this happens

**Solution**:
\```rust
// Fixed code
\```

For Shaders (makepad-shaders):

### [Effect Name]

\```rust
draw_bg: {
    // shader code with comments
    fn pixel(self) -> vec4 {
        // implementation
    }
}
\```

Step 4: Update the Skill File

1. Read the target SKILL.md file
2. Find the appropriate section
3. Add new content following existing format
4. Ensure no duplicate content

Step 5: Mark Evolution (NOT Version)

Important: Do NOT update version number locally. Add an evolution marker instead:

<!-- Evolution: 2024-01-15 | source: my-app | author: @zhangsan -->

Place this comment above the new content you added.

Step 6: Submit via Git

# Create branch for your contribution
git checkout -b evolution/add-loading-pattern

# Commit your changes
git add makepad-patterns/SKILL.md
git commit -m "evolution: add loading state pattern from my-app"

# Push and create PR
git push origin evolution/add-loading-pattern

Multi-Developer Collaboration

The Problem

Developer A: evolves locally → version 1.4.1
Developer B: evolves locally → version 1.4.1  ← Conflict!

The Solution: Content-First Model

┌─────────────────────────────────────────────────────────┐
│  Local Development (Each Developer)                     │
│  - Add content only                                     │
│  - Add evolution markers (date, source, author)         │
│  - Do NOT change version number                         │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Git PR / Merge                                         │
│  - Content reviewed and merged                          │
│  - Conflicts resolved at content level                  │
└─────────────────────────────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────┐
│  Release (Maintainer / CI)                              │
│  - Bump version based on accumulated changes            │
│  - Tag release                                          │
│  - Publish                                              │
└─────────────────────────────────────────────────────────┘

Evolution Marker Format

Each contribution should include a marker:

<!-- Evolution: YYYY-MM-DD | source: project-name | author: @github-handle -->

Example in makepad-patterns/SKILL.md:

## Pattern 15: Loading State Button

<!-- Evolution: 2024-01-15 | source: moly | author: @zhangsan -->

A button that shows loading spinner when processing...

Git Workflow

# 1. Sync with upstream before evolving
git fetch upstream
git rebase upstream/main

# 2. Create evolution branch
git checkout -b evolution/descriptive-name

# 3. Make your changes (content only, no version bump)
# ... edit SKILL.md files ...

# 4. Commit with conventional prefix
git commit -m "evolution(patterns): add loading state button"
git commit -m "evolution(troubleshooting): fix for timer not firing"
git commit -m "evolution(shaders): add glassmorphism effect"

# 5. Push and create PR
git push origin evolution/descriptive-name
gh pr create --title "evolution: add loading patterns from moly"

Handling Content Conflicts

When multiple developers add to the same section:

<<<<<<< HEAD
## Pattern 15: Loading Button
<!-- Evolution: 2024-01-15 | source: moly | author: @zhangsan -->
=======
## Pattern 15: Expandable Card
<!-- Evolution: 2024-01-15 | source: robrix | author: @lisi -->
>>>>>>> evolution/add-card-pattern

Resolution: Renumber and keep both

## Pattern 15: Loading Button
<!-- Evolution: 2024-01-15 | source: moly | author: @zhangsan -->
...

## Pattern 16: Expandable Card
<!-- Evolution: 2024-01-15 | source: robrix | author: @lisi -->
...

Version Bumping (Maintainer Only)

At release time, maintainer reviews accumulated changes:

# Check what's new since last release
git log v1.4.0..HEAD --oneline

# Determine version bump
# - Only troubleshooting fixes → patch (1.4.1)
# - New patterns/shaders → minor (1.5.0)
# - New skill files → major (2.0.0)

# Update version in plugin.json
# Tag and release
git tag v1.5.0
git push --tags

CI Automation (Optional)

.github/workflows/version.yml:

name: Auto Version on Release
on:
  push:
    branches: [main]
    paths:
      - '*/SKILL.md'

jobs:
  version:
    runs-on: ubuntu-latest