Component Migration Workflow System — Gap Analysis & Proposal

Date: 2026-02-11 Author: Claude (Opus 4.6) Task: H.22 — Component Migration Workflow System Project: PILOT Status: PROPOSED — awaiting approval

Problem Statement

CODITECT needs to relocate components between repositories (e.g., pdf-to-markdown from coditect-core to coditect-research-continuum). The framework has extensive migration infrastructure for code/database/naming migrations, but zero support for component relocation between repositories.

When a component moves:

Framework discovery (skill catalog, command index, component search) breaks silently
Registry entries (framework-registry.json, component-activation-status.json) become stale
Component counts in component-counts.json become inaccurate
Users invoking relocated commands get no feedback

Discovery: What Exists Today

Migration Infrastructure (Code/Database/Naming Only)

Component	Type	Purpose	Handles Relocation?
`skills/migration-safety-patterns/SKILL.md`	Skill	Safe file renaming (ADR-100 patterns)	No
`skills/migration-strategy/SKILL.md`	Skill	Database migration planning	No
`skills/interactive-migration/SKILL.md`	Skill	Interactive migration execution	No
`skills/framework-migration-patterns/SKILL.md`	Skill	Framework version upgrades	No
`agents/migration-safety-specialist.md`	Agent	Safe migration enforcement	No
`agents/lowercase-migration-agent.md`	Agent	Lowercase naming migration	No
`hooks/migration-safety-validator.py`	Hook	Validates migration safety	No
`hooks/validators/migration-validator.py`	Hook	Database migration validation	No
`commands/migration-preflight.md`	Command	Pre-flight checklist	No
`commands/migration-status.md`	Command	Migration queue status	No
`commands/migration-mark.md`	Command	Manual status marking	No
`commands/migration-next.md`	Command	Next pending migration	No

Finding: 12 migration components exist. ALL handle code/database/naming migrations. NONE handle component relocation between repos.

Component Lifecycle (Updated This Session)

Component	Type	Migration Support	Status
`commands/component-lifecycle.md`	Command	Phase 6: MIGRATE added (v1.1.0)	Docs only — no script
`commands/component-create.md`	Command	`--stub` support added (v1.1.0)	Docs only — no script

Finding: Command documentation updated but no execution scripts exist for migration operations.

What's Missing (Gap Map)

Need	Component Type	Exists?	Gap
Migration execution script	Script	No	Core gap — no script moves files + creates stubs
Stub template	Template	No	Templates dir has agent/skill/command but no stub template
Stub validation hook	Hook	No	No validation that stubs have correct frontmatter
Migration workflow definition	Workflow	No	No WF-* workflow orchestrating the full migration
Registry updater for relocations	Script	No	Existing `ensure_component_registered.py` doesn't handle `status: relocated`
Migration preflight for relocation	Command	Partial	`migration-preflight.md` exists but only covers code/DB migrations
Batch migration orchestration	Script	No	No batch processing for multi-component moves

Proposed Solution: Component Migration Workflow System

Architecture

User invokes: /component-lifecycle skill pdf-to-markdown --migrate --to coditect-research-continuum

     ┌─────────────────────────────────┐
     │  /component-lifecycle --migrate  │
     └─────────────┬───────────────────┘
                   │
     ┌─────────────▼───────────────────┐
     │   Phase 6a: PREFLIGHT           │
     │   - Verify source exists        │
     │   - Verify target repo exists   │
     │   - Check for conflicts         │
     │   - Show migration plan         │
     └─────────────┬───────────────────┘
                   │
     ┌─────────────▼───────────────────┐
     │   Phase 6b: COPY                │
     │   - Copy files to target repo   │
     │   - Preserve directory structure│
     │   - Update import paths         │
     └─────────────┬───────────────────┘
                   │
     ┌─────────────▼───────────────────┐
     │   Phase 6c: STUB                │
     │   - Create redirect stubs       │
     │   - Apply stub template         │
     │   - Validate stub frontmatter   │
     └─────────────┬───────────────────┘
                   │
     ┌─────────────▼───────────────────┐
     │   Phase 6d: REGISTRY            │
     │   - Update framework-registry   │
     │   - Update activation-status    │
     │   - Update component-counts     │
     └─────────────┬───────────────────┘
                   │
     ┌─────────────▼───────────────────┐
     │   Phase 6e: VERIFY              │
     │   - Validate stubs discoverable │
     │   - Validate registries updated │
     │   - Run stub validation hook    │
     └─────────────┬───────────────────┘
                   │
     ┌─────────────▼───────────────────┐
     │   Phase 5: CONTEXT (/cx)        │
     │   - Log migration in session    │
     └─────────────────────────────────┘

Components to Create

1. Migration Execution Script (NEW)

Path: scripts/component-migration.py Type: Script Purpose: Executes component relocation: copies files, creates stubs, updates registries

scripts/component-migration.py \
  --type skill \
  --name pdf-to-markdown \
  --to coditect-research-continuum \
  --target-path src/pipeline/ \
  --reason "Product code moved to dedicated product repository"

Capabilities:

Discover all files belonging to a component (by type + name)
Copy files to target repo (within rollout-master tree)
Create redirect stubs with standardized frontmatter
Update framework-registry.json (status → relocated)
Update component-activation-status.json (status → relocated)
Update component-counts.json (decrement active, increment relocated)
Batch mode for multi-component migration
Dry-run mode for previewing changes
Rollback capability (undo stubs, restore originals from git)

2. Stub Validation Hook (NEW)

Path: hooks/validators/stub-relocation-validator.py Type: Hook (PreToolUse:Write/Edit) Purpose: Validates that any file with status: relocated has all required frontmatter fields

Required fields:

status: relocated or status: deprecated
relocated_to (required if relocated)
relocated_date (ISO date)
relocated_path (path in target repo)
original_path (path in source repo)
reason (human-readable explanation)

3. Migration Workflow Definition (NEW)

Path: docs/workflows/WF-component-migration.md Type: Workflow Purpose: Orchestrates the full component migration lifecycle

Phases:

PREFLIGHT — Validate source, target, conflicts
COPY — Transfer files to target repository
STUB — Create redirect stubs in source
REGISTRY — Update all framework registries
VERIFY — Validate stubs and registries
CONTEXT — Log migration to session

4. Stub Template (NEW)

Path: templates/components/stub-relocated.md Type: Template Purpose: Standard template for redirect stub components

5. Migration Preflight Extension (EXTEND)

Path: commands/migration-preflight.md (existing) Type: Command (extend) Purpose: Add --component-relocation mode to existing preflight command

New checks:

Target repo exists and is accessible
Component files discoverable in source
No conflicts in target
Registry entries exist for component

Component Summary

#	Component	Type	Action	Priority	Effort
1	`scripts/component-migration.py`	Script	CREATE	P1	8-12h
2	`hooks/validators/stub-relocation-validator.py`	Hook	CREATE	P1	2-4h
3	`docs/workflows/WF-component-migration.md`	Workflow	CREATE	P1	2-3h
4	`templates/components/stub-relocated.md`	Template	CREATE	P1	1h
5	`commands/migration-preflight.md`	Command	EXTEND	P2	2-3h
6	`commands/component-lifecycle.md`	Command	DONE (v1.1.0)	—	Done
7	`commands/component-create.md`	Command	DONE (v1.1.0)	—	Done

Total new effort: ~15-23 hours Already done: component-lifecycle + component-create updated

Immediate Next Steps

Create scripts/component-migration.py — the core execution engine
Create hooks/validators/stub-relocation-validator.py — ensures stub quality
Create docs/workflows/WF-component-migration.md — workflow orchestration
Create templates/components/stub-relocated.md — stub template
Register and activate all new + updated components
Execute first migration: pdf-to-markdown → coditect-research-continuum

Code Migration Analysis: internal/analysis/research-continuum/research-continuum-code-migration-analysis-2026-02-11.md
ADR-174: internal/architecture/adrs/ADR-174-research-continuum-agentic-knowledge-infrastructure.md
Vision Document: internal/analysis/research-continuum/CODITECT-Research-Continuum-Vision-Document.md
Migration Safety Patterns: skills/migration-safety-patterns/SKILL.md

Problem Statement​

Discovery: What Exists Today​

Migration Infrastructure (Code/Database/Naming Only)​

Component Lifecycle (Updated This Session)​

What's Missing (Gap Map)​

Proposed Solution: Component Migration Workflow System​

Architecture​

Components to Create​

1. Migration Execution Script (NEW)​

2. Stub Validation Hook (NEW)​

3. Migration Workflow Definition (NEW)​

4. Stub Template (NEW)​

5. Migration Preflight Extension (EXTEND)​

Component Summary​

Immediate Next Steps​

Related Documents​