gsd-migrate

GSD Project Migration Assistant

Bridges the gap between existing projects and GSD adoption by inferring GSD artifacts from current project state, preserving git history and existing work.

When to Use

Activate when the user:

• Has an existing project and wants to adopt GSD
• Mentions "migrate", "convert to GSD", "add GSD"
• Asks "can I use GSD on an existing project?"
• Has brownfield code and wants structure

What This Skill Does

Analyzes existing project to extract:

• Project vision from README, package.json, docs
• Requirements from features, git commits, code analysis
• Current progress from file structure and git history
• Work remaining from TODOs, issues, backlog

Generates GSD artifacts that map current state:

• PROJECT.md (what this is, validated requirements, decisions)
• ROADMAP.md (completed phases + future work)
• STATE.md (current position)
• config.json (sensible defaults)

Preserves history:

• No git rewriting or rebasing
• Existing commits untouched
• GSD structure added on top

Migration Process

Phase 1: Discovery & Analysis

Step 1.1: Detect Project Type

# Analyze project indicators
if [ -f "package.json" ]; then
  PROJECT_TYPE="javascript"
  # Read: name, description, dependencies
elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then
  PROJECT_TYPE="python"
elif [ -f "go.mod" ]; then
  PROJECT_TYPE="go"
elif [ -f "Cargo.toml" ]; then
  PROJECT_TYPE="rust"
fi

# Check for frameworks
if grep -q "react" package.json 2>/dev/null; then
  FRAMEWORK="react"
elif grep -q "express" package.json 2>/dev/null; then
  FRAMEWORK="express"
fi

Step 1.2: Extract Project Vision

Sources to analyze:

| Source | What to Extract | |--------|-----------------| | README.md | Project purpose, features, usage | | package.json / Cargo.toml | Name, description, keywords | | CONTRIBUTING.md | Project goals, roadmap | | docs/ | Architecture, design decisions | | Git commits | Feature patterns, evolution |

Example extraction:

From README.md:
"TaskFlow - A lightweight task management API for teams"
→ Core Value: Team task coordination

From package.json:
"keywords": ["tasks", "api", "collaboration"]
→ Domain: Collaborative task management

From git log:
Early commits: Setup, models, basic CRUD
Recent commits: Real-time updates, permissions
→ Project maturity: Mid-stage, core features built

Step 1.3: Identify Completed Work

Analyze git history:

# Get all commits
git log --oneline --all > commits.txt

# Identify feature commits
grep -E "feat|add|implement" commits.txt

# Group by feature area
# "feat: add user auth" → Authentication feature
# "feat: implement tasks CRUD" → Task management feature

Analyze codebase:

# Find main features from file structure
ls src/
# → auth/, tasks/, notifications/, teams/

# For each directory, infer feature
# auth/ → Authentication feature
# tasks/ → Task management feature

Step 1.4: Identify Remaining Work

Sources for remaining work:

# TODOs in code
grep -r "TODO" src/ --include="*.js" --include="*.ts"

# GitHub/GitLab issues
gh issue list --state open

# Comments marked with future work
grep -r "FIXME\|HACK\|XXX" src/

# Incomplete features (from README)
# README says "Features: Auth, Tasks, Search"
# But src/ only has auth/ and tasks/
# → Search is remaining work

Phase 2: Generate GSD Artifacts

Step 2.1: Create PROJECT.md

Template:

# [Project Name]

## What This Is

[Extracted from README/package.json]

## Current State

**Built:** [Summary of completed features]
**Codebase:** [LOC] across [N] files
**Last activity:** [Most recent commit date]

**Migrated to GSD:** [Today's date]

## Core Value

[One-sentence value prop from README]

## Requirements

### Validated

[Features that already exist in codebase]

- ✓ REQ-01: User authentication
  - Source: src/auth/, committed [date]
- ✓ REQ-02: Task CRUD operations
  - Source: src/tasks/, committed [date]

### Active

[Work in progress or remaining from backlog]

- → REQ-03: Real-time notifications
  - Source: TODOs in src/, GitHub issue #42
- → REQ-04: Team collaboration
  - Source: README planned features

### Out of Scope

[Explicitly not doing, from CONTRIBUTING or discussions]

## Constraints

[Inferred from dependencies, architecture]

- **Tech stack:** [From package.json/requirements.txt]
- **Deployment:** [From Dockerfile, deployment files]
- **Compatibility:** [From .nvmrc, engines field]

## Key Decisions

| Decision | Rationale | Outcome |
|----------|-----------|---------|
| [Tech choice from dependencies] | [Inferred] | ✓ Good - [status] |

Step 2.2: Create ROADMAP.md

Map completed work to phases:

# Roadmap

## Milestones

### v1.0 - MVP (Complete)

Completed: [Date of feature completion]

#### Phase 1: Project Setup

**Status:** ✓ Complete
**Completed:** [First commit date]

**Goal:** Initialize project structure

**Deliverables:**
- ✓ Node.js project with Express
- ✓ Database configuration (PostgreSQL)
- ✓ Basic server skeleton

**Success Criteria:**
- Server starts successfully
- Database connection works

---

#### Phase 2: Authentication

**Status:** ✓ Complete
**Completed:** [Auth commit date]

**Goal:** User registration and login

**Deliverables:**
- ✓ User model with password hashing
- ✓ Registration endpoint
- ✓ Login with JWT
- ✓ Auth middleware

**Success Criteria:**
- Users can register and login
- Protected routes require valid JWT

---

### v2.0 - Collaboration Features (In Progress)

#### Phase 3: Task Management

**Status:** ✓ Complete
**Completed:** [Task commit date]

**Goal:** CRUD operations for tasks

**Deliverables:**
- ✓ Task model
- ✓ Create, read, update, delete endpoints
- ✓ Task assignment to users

---

#### Phase 4: Real-Time Notifications

**Status:** → In Progress
**Started:** [Date or "Not started"]

**Goal:** Live updates for task changes

**Deliverables:**
- WebSocket server setup
- Task change events
- Client subscription model

**Success Criteria:**
- Users see task updates in real-time
- No polling required

---

#### Phase 5: Team Collaboration

**Status:** Planned

**Goal:** Multi-user teams with permissions

**Deliverables:**
- Team model
- Invite system
- Role-based permissions
- Team task visibility

**Success Criteria:**
- Users can create teams
- Tasks scoped to teams
- Only team members can view team tasks

Step 2.3: Create STATE.md

Map current position:

# Project State

## Project Reference

See: .planning/PROJECT.md (created [date] during migration)

**Core value:** [From PROJECT.md]
**Current focus:** [Inferred from recent commits or in-progress work]

## Current Position

Phase: 4 of 5 (based on ROADMAP.md analysis)
Plan: In progress (Phase 4 started, not complete)
Status: Migrated to GSD [date]
Last activity: [Most recent commit date]

Progress: [████████░░] 80% (4 of 5 phases)

## Completed Work (Pre-GSD)

| Phase | Name | Completion Date |
|-------|------|-----------------|
| 1 | Project Setup | [First commit date] |
| 2 | Authentication | [Auth complete date] |
| 3 | Task Management | [Tasks complete date] |

## Current Work

Phase 4: Real-Time Notifications
Status: In progress (WebSocket setup done, events TODO)
Files: src/websocket/, src/events/ (partial)

## Accumulated Context

### Decisions

Pre-GSD decisions inferred from codebase:

| Decision | Source | Date |
|----------|--------|------|
| PostgreSQL over MongoDB | package.json dependencies | [Date] |
| JWT over sessions | src/auth/jwt.js | [Date] |
| Express framework | package.json | [Initial commit] |

### Pending Todos

- [ ] Complete WebSocket event system (Phase 4)
- [ ] Add team permissions (Phase 5)
- [ ] Write integration tests (TODO comments in code)

### Blockers/Concerns

None (fresh migration)

## Session Continuity

Last session: [Migration date]
Stopped at: Migration complete, GSD structure created
Resume file: N