legacy-to-ai-ready

# Legacy to AI-Ready

Transform legacy codebases into AI-ready projects by generating Claude Code configurations.

## Quick Start (5-Minute Setup)

For most projects, start with just CLAUDE.md:

1. **Analyze**: `python scripts/analyze_codebase.py [path]`
2. **Create CLAUDE.md** with build commands, code style, architecture overview
3. **Done** - Claude can now write code following your project's conventions

Expand to full configuration only when needed.

## Interactive Discovery

Before generating configs, ask these questions:

**Project Scope:**
- What is this project? (web app, API, CLI, library)
- Primary language and frameworks?
- Team size? (solo, small team, enterprise)

**Pain Points:**
- What mistakes do new developers commonly make?
- What patterns should always be followed?
- What operations are repeated frequently?

**Integration Needs:**
- External services used? (databases, APIs, cloud)
- CI/CD pipeline? (GitHub Actions, Jenkins)
- Code quality tools? (linters, formatters)

## Configuration Decision Tree

```
Start
│
├─ Small project / Solo dev
│  └─ CLAUDE.md only
│
├─ Team project
│  ├─ Multi-language? → Add .claude/rules/
│  ├─ Complex domain? → Add .claude/skills/
│  ├─ Code reviews? → Add .claude/agents/
│  └─ Repeated tasks? → Add .claude/commands/
│
└─ Enterprise / Large team
   └─ All configurations + MCP servers + Hooks
```

## Generated Configurations

| Config | Purpose | When to Create |
|--------|---------|----------------|
| **CLAUDE.md** | Project memory (shared) | Always (required) |
| **CLAUDE.local.md** | Personal preferences (git-ignored) | Individual customization |
| **.claudeignore** | Files Claude should not access | Sensitive files exist |
| **.claude/rules/** | Path-specific rules | Multi-module projects |
| **.claude/skills/** | Domain knowledge | Complex business logic |
| **.claude/agents/** | Task specialists | Repeated review/debug tasks |
| **.claude/commands/** | Quick prompts | Common workflows |
| **.claude/settings.json** | Hooks + permissions | Auto-formatting, security |
| **MCP servers** | External tools | Database/API integrations |

## Workflow

### Phase 1: Automated Analysis

```bash
python scripts/analyze_codebase.py [project-path]
```

The script detects:
- Languages and frameworks
- Directory structure patterns
- Development tools (linters, formatters)
- Git commit patterns
- Environment variables
- Code style indicators
- **CI/CD configurations** (GitHub Actions, etc.)
- **Sensitive files** (warns about .env, credentials)

**Output includes:**
- Recommendations for which configs to create
- Security warnings for sensitive files
- Suggested .claudeignore patterns

### Phase 2: Context Gathering

Claude should read:

1. **3-5 representative source files** - understand naming, patterns
2. **Test files** - understand testing approach
3. **Config files** - package.json, tsconfig, etc.
4. **README/docs** - project overview
5. **Recent commits** - understand commit style

### Phase 2.5: Discover Existing Resources

Before creating custom configs, search for existing skills and MCP servers:

1. **Search skill marketplaces** - SkillsMP, SkillHub.club, Claude Skills Hub
2. **Check GitHub repositories** - awesome-claude-skills, themed skill collections
3. **Find relevant MCP servers** - Glama, MCP Market, official registry

See [references/resource-discovery.md](references/resource-discovery.md) for complete directory of sources.

**Tip**: Many common needs (git commit, code review, database patterns) already have well-maintained skills available.

### Phase 3: Generate Configurations

#### 1. CLAUDE.md (Required)

Create at project root with:
- Quick reference commands (build, test, lint)
- Naming conventions
- Architecture overview
- Testing guidelines
- Git workflow

See [references/claude-md-patterns.md](references/claude-md-patterns.md).

#### 2. Rules (If Multi-Module)

Create `.claude/rules/` when:
- Multiple languages need different conventions
- Modules have distinct patterns (frontend/backend)
- Path-specific requirements exist

See [references/rules-patterns.md](references/rules-patterns.md).

#### 3. Skills (If Complex Domain)

Create `.claude/skills/` when:
- Domain-specific workflows exist (database, API patterns)
- Team knowledge needs preservation
- Complex procedures are repeated

See [references/skills-patterns.md](references/skills-patterns.md).

#### 4. Subagents (If Specialized Tasks)

Create `.claude/agents/` for:
- Code review automation
- Debugging assistance
- Security auditing
- Documentation generation

See [references/agents-patterns.md](references/agents-patterns.md).

#### 5. Commands (If Common Operations)

Create `.claude/commands/` for:
- Git commit workflow
- PR review process
- Deployment steps
- Test running

See [references/commands-patterns.md](references/commands-patterns.md).

#### 6. Hooks (If Auto-Formatting Needed)

Configure `.claude/settings.json` for:
- Auto-format on file edit
- Protected files
- Command logging

See [references/hooks-patterns.md](references/hooks-patterns.md).

#### 7. MCP Servers (If External Integrations)

Configure MCP for:
- Database access
- GitHub integration
- Slack notifications
- Custom internal tools

See [references/mcp-patterns.md](references/mcp-patterns.md).

### Phase 4: Validate

1. Ask Claude to perform a typical task
2. Verify it follows project conventions
3. Iterate based on gaps discovered

## Output Structure

Minimal (small projects):
```
project/
├── CLAUDE.md
└── [existing files]
```

Standard (team projects):
```
project/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   └── code-style.md
│   └── commands/
│       └── commit.md
└── [existing files]
```

Complete (enterprise):
```
project/
├── CLAUDE.md              # Shared project memory
├── CLAUDE.local.md        # Personal (git-ignored)
├── .claudeignore          # Files to protect
├── .claude/
│   ├── settings.json      # Hooks + permissions
│   ├── rules/
│   ├── skills/
│   ├── agents/
│   └── commands/
└── [existing files]
```

## Reference Materials

| Reference | When to Read |
|-----------|--------------|
| [examples.md](references/examples.md) | **Complete real-world examples** |
| [resource-discovery.md](references/resource-discovery.md) | **Find existing skills & MCP servers** |
| [advanced-patterns.md](references/advanced-patterns.md) | **Migrations, team collab, monorepos** |
| [claude-md-patterns.md](references/claude-md-patterns.md) | Creating CLAUDE.md |
| [rules-patterns.md](references/rules-patterns.md) | Module-specific rules |
| [skills-patterns.md](references/skills-patterns.md) | Domain knowledge |
| [agents-patterns.md](references/agents-patterns.md) | Task specialists |
| [commands-patterns.md](references/commands-patterns.md) | Quick prompts |
| [hooks-patterns.md](references/hooks-patterns.md) | Auto-formatting |
| [mcp-patterns.md](references/mcp-patterns.md) | External tools |

## Templates & Bundled Skills

Templates:
- `assets/CLAUDE.md.template` - Project memory template
- `assets/settings.json.template` - Hooks configuration
- `assets/claudeignore.template` - File ignore patterns

Bundled skills to install in target project:
- `assets/skill-creator/` - For creating new project-specific skills
- `assets/skill-downloader/` - For downloading additional skills
- `assets/resource-scout/` - For discovering existing skills & MCP servers

### Installing Bundled Skills

Copy these skills to the target project's `.claude/skills/` directory:

```bash
cp -r assets/skill-creator [target-project]/.claude/skills/
cp -r assets/skill-downloader [target-project]/.claude/skills/
cp -r assets/resource-scout [target-project]/.claude/skills/
```

This enables the target project to:
1. **resource-scout** - Discover existing skills & MCP servers before building custom
2. **skill-downloader** - Download and install skills from GitHub or archives
3. **skill-creator** - Create custom skills tailored to their domain

## Language Quick Reference

### TypeScript/JavaScript
- Extract: eslint, prettier, tsconfig
- Hooks: prettier auto-format
- Skills: API patterns, component patterns

### Python
- Extract: black, ruff, mypy, pyproject.toml
- Hooks: black/ruff auto-format
- Skills: API patterns, ORM patterns

### Go
- Extract: gofmt, golangci-lint
- Hooks: gofmt auto-format
- Skills: error handling patterns

### Rust
- Extract: rustfmt, clippy
- Hooks: rustfmt auto-format
- Skills: error handling, async patterns