# Migrate Existing Project to Project Planning Structure

Convert an existing project (with scattered markdown/docs) to use `.context/project/` structure.

**Note**: For small projects needing only one subproject, use the name **"main"** as the default.

## Arguments

$ARGUMENTS

## Overview

This command:
1. Launches explorer agents to scan and understand your project
2. Discovers existing markdown files, subprojects, and current state
3. Creates `.context/project/` structure with pre-filled content
4. Optionally moves existing files to proper locations

## Execution Instructions

### Step 1: Initial Scan with Explorer Agents

Launch 5 parallel explorer agents to gather project information:

**Agent 1: Markdown Discovery**
```
Find all markdown files in the project. For each file:
- Path
- Title/purpose (from content)
- Type: documentation, decision log, notes, readme, spec, etc.
Report as structured list.
```

**Agent 2: Project Structure Analysis**
```
Analyze the codebase structure:
- Main directories and their purposes
- Identify potential subprojects/modules (e.g., frontend/, backend/, api/)
- Key technologies used
- Entry points and main files
Report the logical structure.
```

**Agent 3: Current State Discovery**
```
Find indicators of current project state:
- TODOs in code comments
- README status sections
- Any existing tracking files
- Recent git commits (last 10) for context
- Package.json, requirements.txt, etc. for dependencies
Report what's working, what's in progress.
```

**Agent 4: Configuration & Environment**
```
Find configuration details:
- Environment files (.env.example, config files)
- Build/deployment configs
- API endpoints or external services
- Database schemas if present
Report environment setup.
```

**Agent 5: Documentation Quality**
```
Assess existing documentation:
- Is there a main README?
- API docs?
- Architecture docs?
- Are docs up to date or stale?
Report documentation gaps and strengths.
```

### Step 2: Synthesize Findings

After agents complete:
1. Combine all findings
2. Identify:
   - Project name (from package.json, README, or directory)
   - Subprojects (from structure analysis)
   - Current state (from state discovery)
   - Existing files to migrate
   - Documentation gaps

### Step 3: Ask Clarifying Questions

Present findings and ask:

1. "I found these potential subprojects: [list]. Is this correct? Any to add/remove?"
2. "Which subproject should be active/primary?"
3. "I found [N] markdown files. Should I organize them into the new structure?"
4. "Any additional context about the project I should know?"

### Step 4: Generate Structure with Content

Create `.context/project/` structure using `pp-init-assets/templates/` but:

**Pre-fill root INDEX.md instead of placeholders:**

- **INDEX.md**: Use discovered project name, description from README, list actual subprojects, set active subproject, add discovered high-level TODOs, fill subproject status table
- **WORKFLOW.md**: Copy as-is
- **PRINCIPLES.md**: Copy as-is
- **LESSONS.md**: Copy as-is

**For each subproject:**

- **INDEX.md**: Subproject overview
- **TODO.md**: Convert discovered TODOs from code into task list
- **STATUS.md**: Actual status from analysis
- **CODEBASE.md**: Files in that subproject
- **CHANGELOG.md**: Initialize with recent git history summary for that subproject
- **PRINCIPLES.md**: Only if subproject has specific principles (usually skip)
- **LESSONS.md**: Copy from root template

### Step 5: Migration Plan (Requires Confirmation)

Present migration plan:

```
Files to move:
- docs/api-spec.md → .context/project/{subproject}/docs/
- DECISIONS.md → .context/project/{subproject}/docs/
- old-notes.md → .context/project/archive/

Files to keep in place:
- README.md (root)
- CONTRIBUTING.md (root)
```

Ask: "Should I proceed with moving these files? (y/n)"

If yes, execute moves.
If no, skip migration, just create structure.

### Step 6: Final Report

Show:
1. Created structure (tree view)
2. Files that were migrated
3. Suggested next steps:
   - Review generated STATUS.md for accuracy
   - Add any missing TODOs
   - Create first PRD for current work

## Templates Reference

Uses same templates as `/pp-init` from:
`~/.claude/commands/pp-init-assets/templates/`

But fills content from discovered information instead of placeholders.

## Examples

```bash
# Basic migration
/pp-migrate

# With context hint
/pp-migrate This is a Facebook ads automation project with webhook server and analytics dashboard

# Skip file migration
/pp-migrate --no-move
```

## Flags

- `--no-move`: Create structure but don't move existing files
- `--dry-run`: Show what would be done without making changes

## Notes

- Always backs up files before moving (copies to archive first)
- Preserves git history by using `git mv` when possible
- If `.context/project/` already exists, asks before overwriting