Component Migration Standardized Workflow

1. Executive Summary

This document analyzes the complete H.22 component migration process executed on 2026-02-11 (migration of pdf-to-markdown pipeline from coditect-core to coditect-research-continuum), extracts a standardized repeatable workflow, and maps it against international standards for change management, configuration management, and software lifecycle governance.

Key deliverables:

• 12-step interactive workflow with user prompt points
• Standards compliance matrix (ISO 10007, ISO 20000, NIST SP 800-128, NIST CSF 2.0, NIST SSDF, ITIL v4)
• ADR-175 Component Migration Process specification
• Workflow definition (WF-component-migration.yaml)

---

2. Process Reconstruction — What Actually Happened

2.1 Chronological Steps (H.22, 2026-02-11)

#	Phase	Step	Duration	User Input Required
1	Analysis	Gap analysis — audited 12 existing migration components	15 min	No
2	Analysis	Identified zero components handle cross-repo relocation	—	No
3	Design	Proposed 5-phase pipeline architecture	10 min	Yes — user approved
4	Design	User chose Option A (Full Move) over recommended Option B (Split)	—	Yes — architecture decision
5	Design	User corrected: stubs needed for ALL component types, not just SKILL.md	—	Yes — requirement correction
6	Build	Created scripts/component-migration.py (~600 LOC, 8 subtasks)	45 min	No
7	Build	Updated component-lifecycle.md v1.0.0 → v1.1.0 (Phase 6 MIGRATE)	10 min	No
8	Build	Updated component-create.md v1.0.0 → v1.1.0 (--stub support)	5 min	No
9	Test	Dry-run single + batch — found schema pattern bug, fixed	10 min	No
10	Execute	Batch migration: 4 components, 29 files, 3 stubs	5 min	Yes — execute confirmation
11	Verify	Stub validation, registry audit, file count check	5 min	No
12	Commit	Bottom-up commit + push across 3 repos	10 min	Yes — push confirmation

Total elapsed: ~2 hours User interaction points: 4 (architecture choice, requirement correction, execute confirmation, push confirmation)

2.2 Five-Phase Pipeline (Per Component)

PREFLIGHT ──→ COPY ──→ STUB ──→ REGISTRY ──→ VERIFY
   │             │         │         │            │
   ├─ Source     ├─ Files  ├─ Stub   ├─ framework ├─ Stubs exist?
   │  exists?    │  to     │  in     │  -registry ├─ Frontmatter?
   ├─ Target     │  target │  source │  .json     ├─ Registry
   │  writable?  │  repo   │  repo   ├─ component │  entries?
   └─ Conflicts? │        │        │  -activation├─ Counts
                 │        │        │  .json      │  correct?
                 │        │        └─ component  └─ Files in
                 │        │           -counts       target?
                 │        │           .json
                 │        └─ 3 variants:
                 │           Markdown (commands, agents)
                 │           Python (hooks, scripts)
                 │           Directory (skills)
                 └─ Schema: copy only, no stub

---

3. Standards Compliance Analysis

3.1 Applicable Standards

Standard	Full Name	Relevance
ISO 10007:2017	Quality Management — Guidelines for Configuration Management	Configuration baseline, change control, status accounting, audit
ISO/IEC 20000-1:2018	IT Service Management — Requirements	Change management, release/deployment management
NIST SP 800-128	Guide for Security-Focused Configuration Management	Baseline configuration, change control, monitoring
NIST CSF 2.0	Cybersecurity Framework (2024)	Asset management, configuration change control (PR.IP-3)
NIST SP 800-218	Secure Software Development Framework (SSDF)	Software supply chain provenance, traceability
ITIL v4	IT Infrastructure Library	Change enablement, release management, configuration management
CMMI CM	Capability Maturity Model Integration — Configuration Management	Process maturity, baseline establishment

3.2 ISO 10007 Compliance Matrix

ISO 10007 defines 5 linked activities for configuration management:

ISO 10007 Activity	Our Implementation	Status
1. CM Planning	Migration manifest (batch spec), reason, target selection	✅ Implemented
2. Configuration Identification	discover_component_files() — discovers all files comprising a component, assigns type-specific patterns	✅ Implemented
3. Change Control	5-phase pipeline with preflight checks, dry-run mode, user approval gates	✅ Implemented
4. Status Accounting	Registry updates (framework-registry.json, component-activation-status.json, component-counts.json), stub frontmatter with status: relocated	✅ Implemented
5. Verification & Audit	VERIFY phase checks stubs, registries, file counts; session log with commit hashes	✅ Implemented

3.3 NIST SP 800-128 Compliance Matrix

NIST 800-128 Requirement	Our Implementation	Status
Baseline Configuration	Component registry (framework-registry.json) serves as baseline	✅
Configuration Change Control	Preflight → user approval → execution → verification	✅
Audit of Changes	Session log entries with timestamps, commit hashes, file counts	✅
Continuous Monitoring	Registry status fields (active → relocated), stub discovery	✅
SecCM Integration into SDLC	Migration integrated into component lifecycle (Phase 6)	✅

3.4 ITIL v4 Change Enablement Mapping

ITIL v4 Practice	Our Implementation
Change Authority	User approval gate before execution
Change Types	Component migration = "normal change" (pre-authorized after dry-run approval)
Change Schedule	Documented in session log with timestamp
Change Model	Standardized 5-phase pipeline, repeatable for any component type
Post-Implementation Review	VERIFY phase + registry audit

3.5 Environment Promotion Mapping

The migration workflow maps to the industry standard R&D → Dev → Staging → Production pattern:

Environment	CODITECT Equivalent	Migration Use Case
R&D	coditect-core/skills/ (experimental)	Components incubated here
Dev	Product repos (e.g., coditect-research-continuum/src/)	Components migrated here when ready
Staging	--dry-run mode + preflight checks	Validates migration before execution
Production	Post-push state	Components live in target repo, stubs in source

---

4. Standardized Interactive Workflow Design

4.1 Workflow Steps (12 Steps)

┌──────────────────────────────────────────────┐
│  STEP 1: INITIATION (User Prompt)            │
│  ▸ What components to migrate?               │
│  ▸ Source repository?                        │
│  ▸ Target repository?                        │
│  ▸ Reason for migration?                     │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 2: DISCOVERY (Automated)               │
│  ▸ Discover all files for each component     │
│  ▸ Count files, measure size                 │
│  ▸ Identify component types                  │
│  ▸ Map dependencies                          │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 3: INVENTORY REPORT (Display)          │
│  ▸ Show migration manifest table             │
│  ▸ File counts per component                 │
│  ▸ Estimated impact (registries, stubs)      │
│  ▸ Dependency warnings                       │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 4: STRATEGY SELECTION (User Prompt)    │
│  ▸ Full Move (copy + stub)?                  │
│  ▸ Split (some files stay)?                  │
│  ▸ Deprecate (stub only, no target)?         │
│  ▸ Keep Source (copy only, no stub)?         │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 5: PREFLIGHT CHECK (Automated)         │
│  ▸ Source files exist?                       │
│  ▸ Target repo accessible?                   │
│  ▸ No naming conflicts in target?            │
│  ▸ Git status clean?                         │
│  ▸ All registries writable?                  │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 6: DRY-RUN PREVIEW (Display)          │
│  ▸ Show exactly what will be copied          │
│  ▸ Show stub content preview                 │
│  ▸ Show registry changes preview             │
│  ▸ Rollback plan if needed                   │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 7: APPROVAL GATE (User Prompt)         │
│  ▸ Approve migration execution?              │
│  ▸ Modify parameters?                        │
│  ▸ Abort?                                    │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 8: EXECUTION (Automated)               │
│  ▸ Phase A: Copy files to target             │
│  ▸ Phase B: Create stubs in source           │
│  ▸ Phase C: Update registries                │
│  ▸ Progress reporting per component          │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 9: VERIFICATION (Automated)            │
│  ▸ Stubs exist with correct frontmatter?     │
│  ▸ All files present in target?              │
│  ▸ Registries reflect relocated status?      │
│  ▸ Component counts refreshed?               │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 10: AUDIT LOG (Automated)              │
│  ▸ Session log entry with full details       │
│  ▸ Migration manifest saved                  │
│  ▸ Before/after registry diff                │
│  ▸ Timestamps and evidence                   │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 11: COMMIT & PUSH (User Prompt)        │
│  ▸ Bottom-up: target repo first              │
│  ▸ Then source repo (stubs + registries)     │
│  ▸ Then parent repo (submodule pointers)     │
│  ▸ Remote URL verification before each push  │
└──────────────┬───────────────────────────────┘
               ▼
┌──────────────────────────────────────────────┐
│  STEP 12: COMPLETION REPORT (Display)        │
│  ▸ Summary table: components migrated        │
│  ▸ Commit hashes across repos                │
│  ▸ Updated component counts                  │
│  ▸ Next steps / follow-up items              │
└──────────────────────────────────────────────┘

4.2 User Interaction Points Summary

Step	Type	What User Decides
1	INPUT	Components, source, target, reason
4	CHOICE	Migration strategy (Full Move / Split / Deprecate / Keep Source)
7	GATE	Approve, modify, or abort after dry-run preview
11	GATE	Approve commit and push to remotes

4.3 Automated Steps (No User Input)

Step	What Happens
2	File discovery across all component types
3	Inventory report generation
5	Preflight validation (5 checks)
6	Dry-run preview generation
8	File copy, stub creation, registry updates
9	Post-execution verification (4 checks)
10	Audit log creation with evidence
12	Completion report with metrics

---

5. Cross-Reference: Steps vs. Standards

Step	ISO 10007	NIST 800-128	ITIL v4	NIST CSF 2.0
1. Initiation	CM Planning	Change Request	Change initiation	—
2. Discovery	Configuration Identification	Baseline ID	CI identification	ID.AM (Asset Mgmt)
3. Inventory	Status Accounting	Baseline documentation	CMDB update	ID.AM-1
4. Strategy	Change Control	Change evaluation	Change classification	—
5. Preflight	Verification	Pre-change validation	Change assessment	PR.IP-3
6. Dry-Run	Verification	Impact assessment	Change modeling	—
7. Approval	Change Control	Change authority	CAB approval	—
8. Execution	Change Control	Change implementation	Change execution	PR.IP-3
9. Verification	Verification & Audit	Post-change audit	PIR	DE.CM
10. Audit Log	Status Accounting	Audit trail	Change record	—
11. Commit	Change Control	Baseline update	Release deployment	—
12. Completion	Status Accounting	Status reporting	Change closure	—

---

6. Component Types and Migration Patterns

6.1 Seven Component Types

Type	Source Pattern	Stub Type	Discovery
skill	skills/{name}/ (directory)	skills/{name}/SKILL.md	Recursive directory scan
command	commands/{name}.md	Same file replaced	Single file
agent	agents/{name}.md	Same file replaced	Single file
hook	hooks/{name}.py	Python stub with __status__	Single file
script	scripts/{name}.py	Python stub with __status__	Single file
workflow	workflows/{name}.yaml	YAML stub with status: relocated	Single file
schema	config/schemas/{name}.schema.json	None (copy only)	Single file

6.2 Stub Frontmatter Standard

All markdown stubs MUST contain:

---
title: "{Name} (Relocated)"
component_type: {type}
version: 1.0.0
status: relocated
relocated_to: {target_repo}
relocated_path: {target_path}
relocated_date: "{ISO-8601}"
original_path: "{source_path}"
reason: "{migration_reason}"
summary: "RELOCATED — see {target_repo}"
keywords:
  - relocated
  - stub
created: "{original_created}"
updated: "{migration_date}"
---

---

7. Risk Assessment

Risk	Likelihood	Impact	Mitigation
Broken imports/references	Medium	High	Stub redirect discovery; grep for old paths
Registry inconsistency	Low	Medium	Atomic registry updates in single phase
Git push to wrong remote	Low	Critical	URL verification before every push
Partial migration (power failure)	Low	Medium	Rollback capability via --rollback
Missing file in discovery	Low	Medium	Recursive scan + dry-run preview
Component not found after move	Medium	High	Stubs remain in source repo for discovery

---

8. Recommendations

1. Automate stub validation (H.22.2) — Pre-commit hook that validates all status: relocated stubs have required frontmatter fields
2. Migration manifest archival — Save each migration's manifest as JSON alongside the session log for audit retrieval
3. Dependency graph check — Before migration, scan for components that import/reference the migrating component and warn about broken references
4. Post-migration smoke test — After push, verify stubs are discoverable via component-indexer.py --search
5. Quarterly audit — Periodic review of all status: relocated stubs to confirm target repos still contain the components

---

9. References

Standards

• ISO 10007:2017 — Quality Management Guidelines for Configuration Management
• ISO/IEC 20000-1:2018 — IT Service Management Requirements
• NIST SP 800-128 — Guide for Security-Focused Configuration Management
• NIST Cybersecurity Framework 2.0
• NIST SP 800-218 — Secure Software Development Framework (SSDF)
• ITIL v4 — Change Enablement

Internal Documents

• internal/analysis/research-continuum/component-migration-workflow-analysis-2026-02-11.md — Initial gap analysis
• internal/analysis/research-continuum/research-continuum-code-migration-analysis-2026-02-11.md — Code migration analysis
• internal/architecture/adrs/ADR-175-component-migration-process.md — Architecture decision record
• workflows/component-migration.yaml — Executable workflow definition

Environment Promotion Best Practices

• Dev, Test, Prod: Best Practices (2025)
• Software Environment Management (Octopus Deploy)
• Staging Environment Best Practices (Statsig)

---

Document: internal/analysis/research-continuum/component-migration-standardized-workflow-2026-02-11.md Author: Claude (Opus 4.6) Task: H.22 Project: PILOT