Migration

This guide covers upgrading between Fulcrum versions. Each major version may include breaking changes that require migration steps.

Current Version: 6.2

The latest stable version with full vendor-agnostic support and enhanced skills.

# Check your current version
cat ai-tools/config.json | grep version

# Or use npm
npm list @anthropic/fulcrum

v6.1 → v6.2

Released: January 2025
Difficulty: Easy (non-breaking)

What Changed

• Enhanced Beads integration with agent mail
• New /handoff-work-item command
• Improved parallel execution in /execute-work
• Better error recovery in workflows

Upgrade Steps

# 1. Update the package
npm update @anthropic/fulcrum

# 2. Regenerate vendor files
npm run fulcrum:generate

# 3. (Optional) Enable agent mail for Beads
/setup-beads --with-agent-mail

# Done! No breaking changes.

New Features to Try

# Work item handoffs between agents
/handoff-work-item bd-auth.3 --to qa-backend --context "Ready for testing"

# Improved execution with better parallelism
/execute-work all

v6.0 → v6.1

Released: December 2024
Difficulty: Easy (minor adjustments)

What Changed

• Skills system overhaul with project/user separation
• New skill format with YAML frontmatter
• Deprecated workflows/ in favor of skills/
• Added /generate-agent command

Breaking Changes

Upgrade Steps

# 1. Update the package
npm update @anthropic/fulcrum

# 2. Migrate custom workflows to skills
mkdir -p ai-tools/skills/project
mv ai-tools/workflows/*.md ai-tools/skills/project/

# 3. Update skill format (add frontmatter)
# See "Skill Format Migration" section below

# 4. Regenerate vendor files
npm run fulcrum:generate

# 5. Remove deprecated directory
rm -rf ai-tools/workflows/

Skill Format Migration

Skills now use YAML frontmatter. Update your custom skills:

# Before (v6.0)
# my-workflow.md

## My Custom Workflow

Instructions here...

---

# After (v6.1)
# my-skill.md

---
name: my-skill
description: Brief description of the skill
trigger: when to activate this skill
---

## My Custom Skill

Instructions here...

v5.x → v6.0

Released: November 2024
Difficulty: Moderate (significant restructure)

What Changed

• Complete vendor-agnostic architecture
• Single source of truth in ai-tools/
• New configuration format (config.json)
• Unified agent definitions
• Beads integration for work tracking
• New command naming (/start replaces /begin)

Breaking Changes

Upgrade Steps

# 1. Backup your current setup
git checkout -b backup-v5
git add -A && git commit -m "Backup before v6 migration"
git checkout main

# 2. Remove old configuration
rm -rf .claude-dev/
rm fulcrum.config.js

# 3. Install v6.0
npm install @anthropic/fulcrum@6

# 4. Run setup wizard
/setup-fulcrum

# 5. Migrate Memory Bank (if you had one)
# Copy any custom context files to agent_docs/
cp .claude-dev/context/*.md agent_docs/

# 6. Initialize Beads
/setup-beads

# 7. Regenerate all vendor files
npm run fulcrum:generate

Configuration Migration

// Before: fulcrum.config.js (v5.x)
module.exports = {
  agents: ['orchestrator', 'frontend', 'backend'],
  claude: {
    enabled: true,
    model: 'claude-3-5-sonnet'
  }
}

// After: ai-tools/config.json (v6.0)
{
  "version": "6.0.0",
  "vendors": {
    "enabled": ["claude"],
    "primary": "claude"
  },
  "agents": {
    "preset": "custom",
    "selected": [
      "work-orchestrator",
      "frontend-engineer", 
      "backend-engineer"
    ]
  }
}

Agent Name Changes

Troubleshooting

Common Issues

Clean Slate Migration

If migration is problematic, consider a clean install:

# Remove all Fulcrum files
rm -rf ai-tools/ .claude/ .cursorrules .windsurf/ .gemini/ agent_docs/ .beads/

# Fresh install
npm install @anthropic/fulcrum@latest
/setup-fulcrum
/setup-beads

Getting Help

• Check the release notes for detailed changelogs
• Search GitHub issues for known migration problems
• Join the Discord community for live help

Version History

Deprecation Timeline

Deprecated features and their removal schedule: