Migrating Existing Projects

Add aiorg kits to your existing codebase.

When to Migrate

Use migration if:

• You already have a codebase
• You want to add AI-powered tools (Marketing OS, PMF OS, etc.)
• You have a non-aiorg template you want to enhance

Use fresh install if:

• Starting from scratch
• Switching templates entirely
• Your current codebase is a mess

---

Adding Companion Kits

Companion kits (Marketing OS, PMF OS, Success OS, QA Team) inject into existing projects without changing your code.

Basic Migration

cd ~/my-existing-project
npx @aiorg/cli add marketing-os

This creates:

your-project/
├── .aiorg                    # Project link file
├── .marketing-os/            # Kit data folder
│   ├── config/
│   ├── content/
│   └── data/
├── .claude/                  # Claude Code config (merged)
│   ├── commands/             # Kit commands added
│   └── knowledge/            # Kit knowledge added
├── CLAUDE.md                 # Updated with kit context
└── [your existing code]

Multiple Kits

Add multiple kits to the same project:

cd ~/my-project
npx @aiorg/cli add marketing-os
npx @aiorg/cli add pmf-os
npx @aiorg/cli add success-os

Each kit gets its own data folder but shares the same .claude/ configuration.

---

Project Linking

When you add a kit, the CLI asks about project linking.

First Kit: Create Project

$ npx @aiorg/cli add marketing-os

No .aiorg file found. This appears to be a new project.

? Project name: my-startup
? Description: Task management for freelancers

Creating project: my-startup
├── ~/.aiorg/projects/my-startup/context.json
└── ./.aiorg

Additional Kits: Join Project

$ npx @aiorg/cli add pmf-os

Found project: my-startup
Adding PMF OS to existing project...

Done! Run /setup to get started.

Why Projects Matter

Projects enable kit collaboration:

• Kits share business context
• No re-explaining your idea
• Handoffs between kits are seamless

---

Handling CLAUDE.md

If you already have a CLAUDE.md:

Option 1: Merge (Recommended)

The CLI merges kit instructions with your existing CLAUDE.md:

# Your Existing Project

[Your existing content preserved]

---

## Marketing OS

[Kit content added below]

Option 2: Replace

If your CLAUDE.md is minimal or template-generated:

npx @aiorg/cli add marketing-os --replace-claude-md

Option 3: Keep Separate

For complex setups:

npx @aiorg/cli add marketing-os --no-merge

This creates .claude/kit-marketing-os.md instead of modifying CLAUDE.md.

---

Handling .claude/ Directory

If you already have .claude/ configuration:

Commands

Kit commands are added to .claude/commands/:

• Your existing commands preserved
• Kit commands added with prefixes if conflicts

Settings

.claude/settings.json is merged:

• Your settings take priority
• Kit settings added for missing keys

Knowledge

Kit knowledge added to .claude/knowledge/:

• No conflicts (new files)
• Enhances Claude's understanding

---

Migration Scenarios

Scenario 1: Next.js App Without Kits

cd ~/my-nextjs-app
npx @aiorg/cli add marketing-os

Result:

• .marketing-os/ folder created
• .claude/ directory enhanced
• CLAUDE.md created or merged
• Run /setup to configure

Scenario 2: Non-JavaScript Project

Companion kits work with any tech stack:

cd ~/my-python-project
npx @aiorg/cli add pmf-os

PMF OS doesn't care about your tech stack — it's about understanding users, not code.

Scenario 3: Existing Claude Code Setup

cd ~/project-with-claude-md
npx @aiorg/cli add success-os

Your existing CLAUDE.md is preserved and extended.

Scenario 4: Multiple Related Projects

For a monorepo or related projects:

# Main app
cd ~/projects/my-app
npx @aiorg/cli add marketing-os
# Links to project: my-startup

# Landing page
cd ~/projects/my-landing
npx @aiorg/cli add marketing-os
# Choose: Link to existing project? > my-startup

# Both share context

---

Rollback

If something goes wrong:

Remove a Kit

npx @aiorg/cli remove marketing-os

This removes:

• .marketing-os/ folder
• Kit-specific commands from .claude/
• Kit sections from CLAUDE.md (if possible)

Manual Cleanup

# Remove kit data
rm -rf .marketing-os/

# Remove from CLAUDE.md manually
# Edit CLAUDE.md and remove kit section

# Remove commands
rm .claude/commands/marketing-*.md

---

Migration Checklist

---

Tips

Keep Your Workflow

Companion kits add capabilities without disrupting:

• Your build process unchanged
• Your deployment unchanged
• Your existing commands preserved

Start with One Kit

Don't add everything at once:

1. Add one kit
2. Use it for a week
3. Add another when needed

Use the Shared Context

After adding a kit:

npx @aiorg/cli status

See what context is shared across your kits.