Migration Guide: v3.x to v4.x

Version: 5.8.0

Complete guide for migrating Claude Craft projects from version 3.x to 4.x.

What's New in v4.x

Major Changes

TCL Structure - Tiered Context Loading for 95% token reduction
BMAD v6 - Complete project management framework
Ralph Wiggum v2 - Claude Code hooks integration
9 BMAD Agents - Agent-as-Code YAML format
5 Quality Gates - Validation at each phase
Status-based Routing - Automatic story transitions

Breaking Changes

v3.x	v4.x	Migration
`.claude/rules/*.md`	`.claude/references/{tech}/*.md`	Automatic
Flat structure	TCL hierarchy	Automatic
`ralph.sh`	`ralph.yml` + hooks	Manual
`/workflow:` commands	`/bmad:` + `/sprint:` + `/gate:`	Command rename

Prerequisites

Before migrating:

Backup your project
bash
```
cp -r .claude .claude.backup
```

Commit any pending changes

bash

git add -A && git commit -m "Pre-migration snapshot"

Update Claude Craft
bash
```
cd ~/claude-craft
git pull origin main
```

Automatic Migration

Using NPX

bash

# Preview
npx @the-bearded-bear/claude-craft migrate ~/my-project --dry-run

# Migrate
npx @the-bearded-bear/claude-craft migrate ~/my-project

What Gets Migrated

1. Directory Structure

Before (v3.x):

.claude/
├── rules/
│   ├── 00-project-context.md
│   ├── 01-workflow-analysis.md
│   ├── 02-architecture.md
│   └── ...
├── agents/
├── commands/
└── CLAUDE.md

After (v4.x):

.claude/
├── CLAUDE.md           # Minimal (~200 tokens)
├── INDEX.md            # Quick reference
├── context.yaml        # Skill triggers
├── references/
│   ├── base/           # Universal principles
│   │   ├── solid-principles.md
│   │   ├── kiss-dry-yagni.md
│   │   └── ...
│   └── {technology}/   # Tech-specific
│       ├── architecture.md
│       ├── coding-standards.md
│       └── ...
├── skills/             # On-demand loading
├── agents/
├── commands/
├── templates/
└── checklists/

2. Rule Files Mapping

v3.x Rule	v4.x Location
`01-workflow-analysis.md`	`references/base/workflow-analysis.md`
`02-architecture.md`	`references/{tech}/architecture.md`
`03-coding-standards.md`	`references/{tech}/coding-standards.md`
`04-solid-principles.md`	`references/base/solid-principles.md`
`05-kiss-dry-yagni.md`	`references/base/kiss-dry-yagni.md`
`06-docker-tooling.md`	`references/{tech}/tooling.md`
`07-testing.md`	`references/{tech}/testing.md`
`08-quality-tools.md`	`references/{tech}/quality-tools.md`
`09-git-workflow.md`	`references/base/git-workflow.md`
`10-documentation.md`	`references/base/documentation.md`
`11-security.md`	`references/{tech}/security.md`

3. CLAUDE.md Transformation

Before (v3.x): Large file with all rules inline

After (v4.x): Minimal config with references

markdown

# Claude-Craft - Multi-Technology Framework

**Version:** 5.7.0

## Quick Reference

See `@.claude/INDEX.md` for condensed checklists.

## Technology Quick Links

| Technology | Reference |
|------------|-----------|
| Symfony | `@.claude/references/symfony/` |

## Available Commands

...

Manual Migration Steps

If automatic migration fails or you need custom handling:

Step 1: Create New Structure

bash

mkdir -p .claude/references/base
mkdir -p .claude/references/{your-tech}
mkdir -p .claude/skills

Step 2: Move Base Rules

bash

# From old rules/ to new references/base/
mv .claude/rules/04-solid-principles.md .claude/references/base/solid-principles.md
mv .claude/rules/05-kiss-dry-yagni.md .claude/references/base/kiss-dry-yagni.md
mv .claude/rules/09-git-workflow.md .claude/references/base/git-workflow.md
mv .claude/rules/10-documentation.md .claude/references/base/documentation.md
mv .claude/rules/01-workflow-analysis.md .claude/references/base/workflow-analysis.md

Step 3: Move Tech-Specific Rules

bash

# Example for Symfony
mv .claude/rules/02-architecture.md .claude/references/symfony/architecture.md
mv .claude/rules/03-coding-standards.md .claude/references/symfony/coding-standards.md
mv .claude/rules/07-testing.md .claude/references/symfony/testing.md
mv .claude/rules/11-security.md .claude/references/symfony/security.md

Step 4: Create INDEX.md

Create .claude/INDEX.md with condensed reference:

markdown

# Quick Reference Index

## Architecture Principles
- Clean Architecture layers
- Dependency direction: outer → inner
- Domain is the core

## Testing
- TDD: Red → Green → Refactor
- 80% coverage minimum

## Commands Quick Reference
- `/symfony:check-architecture`
- `/common:pre-commit-check`

Step 5: Update CLAUDE.md

Replace with minimal version (see template above).

Step 6: Preserve Custom Content

bash

# Keep your project context
cp .claude.backup/rules/00-project-context.md .claude/rules/

Migrating Ralph Wiggum

v3.x Ralph (Shell-based)

bash

# Old usage
./ralph.sh "task description"

v4.x Ralph (Hooks-integrated)

Create ralph.yml

yaml

version: 1
max_iterations: 10
technology: symfony

dod:
  - type: command
    command: "npm test"
    expect_exit_code: 0

Enable hooks in settings.json

json

{
  "hooks": {
    "SessionStart": [{
      "command": ".claude/hooks/ralph-context.sh"
    }]
  }
}

New usage
bash
```
/common:ralph-run "task description"
```

Migrating BMAD

v3.x Workflow Commands

bash

# Old
/workflow:init
/workflow:analyze
/workflow:plan
/workflow:design
/workflow:implement

v4.x BMAD Commands

bash

# New - Same commands still work
/workflow:init
/workflow:status

# Plus new BMAD commands
/bmad:init
/bmad:status
/bmad:route

# Sprint management
/sprint:next-story
/sprint:transition US-001 in-progress

# Quality gates
/gate:validate-prd
/gate:validate-story US-001

Command Changes

Renamed Commands

v3.x	v4.x
`/sprint:status`	`/sprint:bmad-status`
`/project:validate-story`	`/gate:validate-story`

New Commands

/bmad:init - Initialize BMAD
/bmad:route - Route to agent
/sprint:transition - Transition story
/sprint:auto-route - Auto routing
/gate:validate-* - Quality gates
/project:run-epic - Batch processing
/project:run-queue - Queue processing

Post-Migration Checklist

After migration, verify:

[ ] .claude/CLAUDE.md exists and is minimal
[ ] .claude/INDEX.md exists
[ ] .claude/references/ structure is correct
[ ] Commands work: /common:pre-commit-check
[ ] Agents work: @{tech}-reviewer
[ ] Skills work: /testing
[ ] Custom project context preserved

Verification Commands

bash

# Count files
find .claude -name "*.md" | wc -l

# Test commands
claude
/common:pre-commit-check

# Check structure
ls -la .claude/
ls -la .claude/references/

Rollback

If migration fails:

bash

# Restore from backup
rm -rf .claude
mv .claude.backup .claude

# Or restore from git
git checkout -- .claude/

Troubleshooting

"Reference file not found"

bash

# Check file exists
ls -la .claude/references/{tech}/

# Reinstall if needed
make install-symfony TARGET=. OPTIONS="--force"

"Command not recognized"

Restart Claude Code session:

bash

exit
claude

"BMAD not initialized"

bash

/bmad:init

Custom rules lost

Check backup:

bash

ls .claude.backup/rules/
cp .claude.backup/rules/00-project-context.md .claude/rules/

Getting Help

Check Troubleshooting Guide
Open GitHub Issue

Migration Guide: v3.x to v4.x ​

What's New in v4.x ​

Major Changes ​

Breaking Changes ​

Prerequisites ​

Automatic Migration ​

Using NPX ​

What Gets Migrated ​

1. Directory Structure ​

2. Rule Files Mapping ​

3. CLAUDE.md Transformation ​

Manual Migration Steps ​

Step 1: Create New Structure ​

Step 2: Move Base Rules ​

Step 3: Move Tech-Specific Rules ​

Step 4: Create INDEX.md ​

Step 5: Update CLAUDE.md ​

Step 6: Preserve Custom Content ​

Migrating Ralph Wiggum ​

v3.x Ralph (Shell-based) ​

v4.x Ralph (Hooks-integrated) ​

Migrating BMAD ​

v3.x Workflow Commands ​

v4.x BMAD Commands ​

Command Changes ​

Renamed Commands ​

New Commands ​

Post-Migration Checklist ​

Verification Commands ​

Rollback ​

Troubleshooting ​

"Reference file not found" ​

"Command not recognized" ​

"BMAD not initialized" ​

Custom rules lost ​

Getting Help ​

See Also ​

Migration Guide: v3.x to v4.x

What's New in v4.x

Major Changes

Breaking Changes

Prerequisites

Automatic Migration

Using NPX

What Gets Migrated

1. Directory Structure

2. Rule Files Mapping

3. CLAUDE.md Transformation

Manual Migration Steps

Step 1: Create New Structure

Step 2: Move Base Rules

Step 3: Move Tech-Specific Rules

Step 4: Create INDEX.md

Step 5: Update CLAUDE.md

Step 6: Preserve Custom Content

Migrating Ralph Wiggum

v3.x Ralph (Shell-based)

v4.x Ralph (Hooks-integrated)

Migrating BMAD

v3.x Workflow Commands

v4.x BMAD Commands

Command Changes

Renamed Commands

New Commands

Post-Migration Checklist

Verification Commands

Rollback

Troubleshooting

"Reference file not found"

"Command not recognized"

"BMAD not initialized"

Custom rules lost

Getting Help

See Also