File Migration Playbook

Guide Origin: Official | ArcKit Version: [VERSION]

migrate-filenames.sh converts legacy ArcKit filenames to the standardized Document ID naming convention.

Platform note: This migration script requires a bash shell (Linux, macOS, or Windows via Git Bash / WSL). It is a one-time migration utility and does not affect day-to-day ArcKit command usage.

Overview

ArcKit uses standardized Document IDs for all artifacts:

ARC-{PROJECT_ID}-{TYPE}-v{VERSION}.md

Examples:

ARC-001-REQ-v1.0.md - Requirements for project 001
ARC-001-ADR-001-v1.0.md - First ADR for project 001
ARC-000-PRIN-v1.0.md - Global architecture principles

Command

# Single project
${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh projects/001-my-project

# Dry run (preview changes)
${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh projects/001-my-project --dry-run

# All projects
${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh --all

# Global directory only
${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh --global

Options

Option	Description
`--dry-run`	Preview changes without modifying files
`--all`	Migrate all projects in `projects/` directory
`--global`	Migrate only `projects/000-global/`
`--force`	Overwrite existing files if they exist
`--no-backup`	Skip creating backup (not recommended)
`--help`, `-h`	Show help message

File Mappings

Core Documents

Old Filename	Type Code	New Filename
`requirements.md`	REQ	`ARC-{PID}-REQ-v1.0.md`
`stakeholder-drivers.md`	STKE	`ARC-{PID}-STKE-v1.0.md`
`stakeholder-analysis.md`	STKE	`ARC-{PID}-STKE-v1.0.md`
`risk-register.md`	RISK	`ARC-{PID}-RISK-v1.0.md`
`sobc.md`	SOBC	`ARC-{PID}-SOBC-v1.0.md`
`data-model.md`	DATA	`ARC-{PID}-DATA-v1.0.md`
`research-findings.md`	RSCH	`ARC-{PID}-RSCH-v1.0.md`
`traceability-matrix.md`	TRAC	`ARC-{PID}-TRAC-v1.0.md`
`analysis-report.md`	ANAL	`ARC-{PID}-ANAL-v1.0.md`

Global Documents (000-global)

Old Filename	Type Code	New Filename
`architecture-principles.md`	PRIN	`ARC-000-PRIN-v1.0.md`
`principles.md`	PRIN	`ARC-000-PRIN-v1.0.md`

Strategy & Operations

Old Filename	Type Code	New Filename
`project-plan.md`	PLAN	`ARC-{PID}-PLAN-v1.0.md`
`roadmap.md`	ROAD	`ARC-{PID}-ROAD-v1.0.md`
`backlog.md`	BKLG	`ARC-{PID}-BKLG-v1.0.md`
`devops-strategy.md`	DEVOPS	`ARC-{PID}-DEVOPS-v1.0.md`
`mlops-strategy.md`	MLOPS	`ARC-{PID}-MLOPS-v1.0.md`
`finops-strategy.md`	FINOPS	`ARC-{PID}-FINOPS-v1.0.md`
`operational-readiness.md`	OPS	`ARC-{PID}-OPS-v1.0.md`
`servicenow-design.md`	SNOW	`ARC-{PID}-SNOW-v1.0.md`
`platform-design.md`	PLAT	`ARC-{PID}-PLAT-v1.0.md`

Procurement

Old Filename	Type Code	New Filename
`sow.md`	SOW	`ARC-{PID}-SOW-v1.0.md`
`dos-requirements.md`	DOS	`ARC-{PID}-DOS-v1.0.md`
`digital-marketplace-dos.md`	DOS	`ARC-{PID}-DOS-v1.0.md`
`gcloud-requirements.md`	GCLD	`ARC-{PID}-GCLD-v1.0.md`
`gcloud-clarification-questions.md`	GCLC	`ARC-{PID}-GCLC-v1.0.md`
`evaluation-criteria.md`	EVAL	`ARC-{PID}-EVAL-v1.0.md`

Compliance

Old Filename	Type Code	New Filename
`tcop-review.md`	TCOP	`ARC-{PID}-TCOP-v1.0.md`
`tcop-assessment.md`	TCOP	`ARC-{PID}-TCOP-v1.0.md`
`ukgov-secure-by-design.md`	SECD	`ARC-{PID}-SECD-v1.0.md`
`secure-by-design.md`	SECD	`ARC-{PID}-SECD-v1.0.md`
`mod-secure-by-design.md`	SECD-MOD	`ARC-{PID}-SECD-MOD-v1.0.md`
`ai-playbook-assessment.md`	AIPB	`ARC-{PID}-AIPB-v1.0.md`
`atrs-record.md`	ATRS	`ARC-{PID}-ATRS-v1.0.md`
`jsp-936.md`	JSP936	`ARC-{PID}-JSP936-v1.0.md`
`jsp936.md`	JSP936	`ARC-{PID}-JSP936-v1.0.md`
`dpia.md`	DPIA	`ARC-{PID}-DPIA-v1.0.md`
`principles-compliance-assessment.md`	PRIN-COMP	`ARC-{PID}-PRIN-COMP-v1.0.md`

Reviews

Old Filename	Type Code	New Filename
`hld-review.md`	HLDR	`ARC-{PID}-HLDR-v1.0.md`
`dld-review.md`	DLDR	`ARC-{PID}-DLDR-v1.0.md`

Other

Old Filename	Type Code	New Filename
`PROJECT-STORY.md`	STORY	`ARC-{PID}-STORY-v1.0.md`

Subdirectory Handling

Multi-Instance Documents

Files in these subdirectories are renamed with sequence numbers:

Subdirectory	Type Code	New Pattern
`decisions/`	ADR	`ARC-{PID}-ADR-{NNN}-v1.0.md`
`diagrams/`	DIAG	`ARC-{PID}-DIAG-{NNN}-v1.0.md`
`wardley-maps/`	WARD	`ARC-{PID}-WARD-{NNN}-v1.0.md`
`data-contracts/`	DMC	`ARC-{PID}-DMC-{NNN}-v1.0.md`
`research/`	RSCH	`ARC-{PID}-RSCH-{NNN}-v1.0.md`

Research Files

Root-level research files are moved to research/ subdirectory:

Pattern	Migrated To
`research-*.md`	`research/ARC-{PID}-RSCH-{NNN}-v1.0.md`
`research.md`	`research/ARC-{PID}-RSCH-{NNN}-v1.0.md`

Procurement Subdirectory

Files in procurement/ are migrated to the project root:

Before:
  projects/001-project/procurement/gcloud-requirements.md
  projects/001-project/procurement/digital-marketplace-dos.md

After:
  projects/001-project/ARC-001-GCLD-v1.0.md
  projects/001-project/ARC-001-DOS-v1.0.md

Reviews Subdirectory

HLD and DLD review files are moved to reviews/:

Before:
  projects/001-project/hld-review.md

After:
  projects/001-project/reviews/ARC-001-HLDR-v1.0.md

Legacy Locations

Global Principles

The migration script checks these legacy locations for principles:

Legacy Location	Migrated To
`.arckit/memory/architecture-principles.md`	`projects/000-global/ARC-000-PRIN-v1.0.md`
`.arckit/memory/principles.md`	`projects/000-global/ARC-000-PRIN-v1.0.md`

Root-Level Diagrams

Files matching these patterns are moved to diagrams/:

Pattern	Migrated To
`*-diagram.md`	`diagrams/ARC-{PID}-DIAG-{NNN}-v1.0.md`
`diagram-*.md`	`diagrams/ARC-{PID}-DIAG-{NNN}-v1.0.md`

Root-Level Wardley Maps

Files matching these patterns are moved to wardley-maps/:

Pattern	Migrated To
`*-wardley.md`	`wardley-maps/ARC-{PID}-WARD-{NNN}-v1.0.md`
`*-map.md`	`wardley-maps/ARC-{PID}-WARD-{NNN}-v1.0.md`

Date-Suffixed Files

Some compliance files have date suffixes. These are handled specially:

Pattern	Migrated To
`principles-compliance-assessment-YYYY-MM-DD.md`	`ARC-{PID}-PRIN-COMP-v1.0.md`
`service-assessment-*-prep.md`	`ARC-{PID}-SVCASS-v1.0.md`

Backups

By default, the script creates a timestamped backup before making changes:

projects/001-project/.backup/20260128_143022/
├── requirements.md
├── stakeholder-drivers.md
└── risk-register.md

Use --no-backup to skip backups (not recommended).

Examples

Preview All Changes

${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh --all --dry-run

Output:

[INFO] Migrating project: 001-payment-gateway (ID: 001)
[DRY-RUN] Would rename: requirements.md → ARC-001-REQ-v1.0.md
[DRY-RUN] Would rename: stakeholder-drivers.md → ARC-001-STKE-v1.0.md
[DRY-RUN] Would rename: risk-register.md → ARC-001-RISK-v1.0.md
[DRY-RUN] No changes made

Migrate Global Principles

${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh --global

This will:

Create projects/000-global/ if it doesn't exist
Check .arckit/memory/ for legacy principles files
Migrate to projects/000-global/ARC-000-PRIN-v1.0.md

Migrate Single Project

${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh projects/001-payment-gateway

Force Overwrite Existing

${CLAUDE_PLUGIN_ROOT}/scripts/bash/migrate-filenames.sh projects/001-payment-gateway --force

Post-Migration Steps

Review backups: Check .backup/ directories for original files
Update references: Search for old filenames in documentation
Run pages command: Regenerate documentation site with /arckit.pages
Commit changes: Add migrated files to version control

Troubleshooting

"Cannot extract project ID"

Project directories must follow the pattern {NNN}-{name}:

Valid: 001-payment-gateway, 002-user-auth
Invalid: payment-gateway, project1

"Target exists, skipping"

A file with the new name already exists. Use --force to overwrite.

Files Not Migrated

Check that the filename matches a known mapping. The script only migrates recognized ArcKit artifact names.

Review Checklist

Ran --dry-run first to preview changes
Verified backup directory was created
Checked all expected files were migrated
Updated cross-references in documentation
Regenerated GitHub Pages with /arckit.pages
Committed changes to version control

Key Principles

Non-destructive: Original files are backed up before migration
Idempotent: Already-migrated files are skipped
Predictable: Consistent naming pattern across all projects
Traceable: Document IDs enable cross-referencing

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

File Migration Playbook

Overview

Command

Options

File Mappings

Core Documents

Global Documents (000-global)

Strategy & Operations

Procurement

Compliance

Reviews

Other

Subdirectory Handling

Multi-Instance Documents

Research Files

Procurement Subdirectory

Reviews Subdirectory

Legacy Locations

Global Principles

Root-Level Diagrams

Root-Level Wardley Maps

Date-Suffixed Files

Backups

Examples

Preview All Changes

Migrate Global Principles

Migrate Single Project

Force Overwrite Existing

Post-Migration Steps

Troubleshooting

"Cannot extract project ID"

"Target exists, skipping"

Files Not Migrated

Review Checklist

Key Principles

FilesExpand file tree

migration.md

Latest commit

History

migration.md

File metadata and controls

File Migration Playbook

Overview

Command

Options

File Mappings

Core Documents

Global Documents (000-global)

Strategy & Operations

Procurement

Compliance

Reviews

Other

Subdirectory Handling

Multi-Instance Documents

Research Files

Procurement Subdirectory

Reviews Subdirectory

Legacy Locations

Global Principles

Root-Level Diagrams

Root-Level Wardley Maps

Date-Suffixed Files

Backups

Examples

Preview All Changes

Migrate Global Principles

Migrate Single Project

Force Overwrite Existing

Post-Migration Steps

Troubleshooting

"Cannot extract project ID"

"Target exists, skipping"

Files Not Migrated

Review Checklist

Key Principles