Initial commit

2025-11-30 09:03:52 +08:00
commit 0b586b3216
42 changed files with 5241 additions and 0 deletions
--- a/commands/pp-migrate-v2.md
+++ b/commands/pp-migrate-v2.md
@@ -0,0 +1,262 @@
+# Migrate PP v1.0 to v1.1+ Structure
+
+**TEMPORARY COMMAND**: Upgrades old Project Planning structure (v1.0.0) to new structure (v1.1.0+).
+
+## Arguments
+
+None
+
+## Purpose
+
+Migrate existing PP projects from old structure (with root STATUS.md, CODEBASE.md, CHANGELOG.md) to new simplified structure (with combined INDEX.md).
+
+**Use this if you have projects using the old PP structure that need upgrading.**
+
+## What Changes
+
+### Old Structure (v1.0.0):
+```
+.context/project/
+├── INDEX.md (old format)
+├── STATUS.md ← will be archived
+├── CODEBASE.md ← will be archived
+├── CHANGELOG.md ← will be archived
+├── WORKFLOW.md (old)
+└── subproject/
+```
+
+### New Structure (v1.1.0+):
+```
+.context/project/
+├── INDEX.md ← NEW (combines INDEX + STATUS + high-level TODOs)
+├── WORKFLOW.md ← UPDATED
+├── PRINCIPLES.md
+├── LESSONS.md
+└── subproject/ ← UNCHANGED
+```
+
+## Execution Instructions
+
+### Step 1: Detect Old Structure
+
+Check if this is an old PP structure:
+```bash
+ls .context/project/STATUS.md
+```
+
+**If STATUS.md doesn't exist:**
+- Inform user: "Project already using new structure or not initialized. Nothing to migrate."
+- Exit
+
+**If STATUS.md exists:**
+- Proceed to Step 2
+
+### Step 2: Read Old Files
+
+Read and extract data from old files:
+
+**From STATUS.md:**
+- Active subproject (section: "## Active Subproject")
+- Subproject summary table (section: "## Subproject Summary")
+- Overall progress (if any)
+- Cross-project dependencies (if any)
+- Recent decisions (if any)
+
+**From INDEX.md (old):**
+- Project name
+- Project description
+- Created date
+- Subprojects table
+- Environment info
+
+**From CODEBASE.md:**
+- Check if it had any important root-level file listings
+- (Usually empty or minimal in old structure)
+
+**From CHANGELOG.md:**
+- Check if it had any cross-project entries
+- (Usually empty or minimal in old structure)
+
+### Step 3: Create New INDEX.md
+
+Generate new INDEX.md using the template from `pp-init-assets/templates/root/INDEX.md`:
+
+**Populate with extracted data:**
+- `{{PROJECT_NAME}}` - from old INDEX.md
+- `{{PROJECT_DESCRIPTION}}` - from old INDEX.md
+- `{{DATE}}` - original created date from old INDEX.md
+- `{{ACTIVE_SUBPROJECT}}` - from old STATUS.md
+- `{{SUBPROJECT_TABLE}}` - from old INDEX.md
+- `{{SUBPROJECT_STATUS_TABLE}}` - from old STATUS.md
+- `{{ENVIRONMENT}}` - from old INDEX.md
+- `{{TODO_ITEM_1}}`, `{{TODO_ITEM_2}}`, `{{TODO_ITEM_3}}` - set to "TBD" or extract from context
+
+**Save to:** `.context/project/INDEX.md` (overwrite old INDEX.md)
+
+### Step 4: Update WORKFLOW.md
+
+Replace old WORKFLOW.md with new version:
+```bash
+cp ~/.claude/commands/pp-init-assets/templates/root/WORKFLOW.md .context/project/WORKFLOW.md
+```
+
+### Step 5: Archive Old Files
+
+Move old root-level files to archive:
+```bash
+mkdir -p .context/project/archive/v1.0-migration-$(date +%Y%m%d)
+mv .context/project/STATUS.md .context/project/archive/v1.0-migration-*/
+mv .context/project/CODEBASE.md .context/project/archive/v1.0-migration-*/
+mv .context/project/CHANGELOG.md .context/project/archive/v1.0-migration-*/
+```
+
+**Create archive README:**
+Create `.context/project/archive/v1.0-migration-{date}/README.md`:
+```markdown
+# v1.0 Structure Archive
+
+These files were archived during migration from PP v1.0.0 to v1.1.0+ on {date}.
+
+## Archived Files
+
+- STATUS.md - Replaced by combined INDEX.md
+- CODEBASE.md - Moved to subproject level only
+- CHANGELOG.md - Moved to subproject level only
+
+## What Changed
+
+v1.1.0+ simplified the root structure:
+- Root now has only: INDEX.md, WORKFLOW.md, PRINCIPLES.md, LESSONS.md
+- All detailed tracking (STATUS, TODO, CHANGELOG, CODEBASE) lives in subprojects
+- INDEX.md now combines project overview + active subproject + status summary
+
+## Data Preservation
+
+All data from these files was extracted and merged into the new INDEX.md.
+Nothing was lost during migration.
+```
+
+### Step 6: Verify Subprojects Unchanged
+
+Confirm that subproject directories remain intact:
+```bash
+ls .context/project/{subproject}/
+```
+
+**Subprojects should still have:**
+- STATUS.md
+- TODO.md
+- CHANGELOG.md
+- CODEBASE.md
+- etc.
+
+**No changes needed** - subproject structure is the same in both versions.
+
+### Step 7: Show Summary
+
+Display migration summary:
+```
+## PP Structure Migration Complete
+
+**Old Structure**: v1.0.0
+**New Structure**: v1.1.0+
+**Date**: {YYYY-MM-DD HH:MM}
+
+### Changes Made:
+
+✅ Created new INDEX.md (combines INDEX + STATUS + high-level TODOs)
+✅ Updated WORKFLOW.md to new version
+✅ Archived old files:
+   - STATUS.md → archive/v1.0-migration-{date}/
+   - CODEBASE.md → archive/v1.0-migration-{date}/
+   - CHANGELOG.md → archive/v1.0-migration-{date}/
+
+### What Stayed the Same:
+
+✓ All subproject directories unchanged
+✓ All subproject files (STATUS, TODO, CHANGELOG, CODEBASE) intact
+✓ Project data preserved in new INDEX.md
+✓ PRINCIPLES.md, LESSONS.md unchanged
+
+### New Root Structure:
+
+.context/project/
+├── INDEX.md ← NEW (combined)
+├── WORKFLOW.md ← UPDATED
+├── PRINCIPLES.md
+├── LESSONS.md
+└── {subprojects}/ ← UNCHANGED
+
+### Next Steps:
+
+1. Review new INDEX.md to verify data accuracy
+2. Check active subproject is correct
+3. Continue using PP commands as normal
+4. Old files safely archived if you need to reference them
+
+---
+
+**Note**: This migration is one-way. The old files are archived, not deleted.
+You can always reference them in the archive/ folder.
+```
+
+## Error Handling
+
+**If .context/project/ doesn't exist:**
+```
+No PP structure found. Run /pp-init first to create project structure.
+```
+
+**If STATUS.md doesn't exist:**
+```
+Project already using new structure (v1.1.0+) or not fully initialized.
+
+If you have subprojects but no root STATUS.md, you're likely already upgraded.
+Nothing to migrate.
+```
+
+**If migration fails mid-way:**
+```
+Migration encountered an error. Your files are safe:
+- Original files still in place
+- Partial changes may exist
+
+Recommendation:
+1. Check .context/project/ directory
+2. Manually review what was changed
+3. Restore from backup if needed
+4. Report issue to plugin maintainer
+```
+
+## Safety Features
+
+- **Non-destructive**: Old files archived, not deleted
+- **Backup created**: Archive folder with timestamp
+- **Verification**: Checks structure before starting
+- **Detailed logging**: Shows exactly what changed
+
+## Usage Example
+
+```bash
+# In a project with old PP structure
+cd /path/to/project
+
+# Run migration
+/pp-migrate-v2
+
+# Result: Upgraded to new structure
+# Old files safely archived
+```
+
+## Notes
+
+- **Temporary command**: Will be removed in future versions once most projects are migrated
+- **One-time operation**: Only need to run once per project
+- **Idempotent**: Safe to run multiple times (detects if already migrated)
+- **Subprojects untouched**: Only root structure changes
+- **Data preserved**: Nothing is lost, everything merged into new INDEX.md
+
+## Version History
+
+- Created for v1.1.0 → v1.1.0+ migration
+- To be deprecated in v2.0.0