Phase 3: Execute File Migrations & Reference Updates

[ashleyshaw]

Overview

Execute all file migrations and cross-reference updates based on completed audits from Phase 1. This is the core execution phase.

Scope

4 migration streams (can run in parallel):

1. Instructions Migration

   • Move portable files from .github/instructions/ → root instructions/
   • Keep repo-local files in .github/instructions/
   • Update 502+ references
   • Archive migration: .github/instructions/.archive/ → instructions/.archive/

2. Schema Consolidation

   • Move files from .github/schema/ → .schemas/
   • Update 35 script references
   • Update 150+ documentation references
   • Update package.json glob patterns

3. Agents Reorganization

   • Move spec-based agents from root agents/ → .github/agents/
   • Move multi-file agents from .github/agents/ → root agents/
   • Update 3,751+ file references
   • Update memory profile system
   • Update plugin integrations

4. Reports Placement

   • Move audit files from root → .github/reports/audits/
   • Update reference locations

Definition of Done

• All portable instructions moved to root
• All repo-local instructions remain in .github/instructions/
• All schemas consolidated to .schemas/
• Agents separated into two-tier structure
• Audit reports moved to .github/reports/audits/
• All 3,000+ file references updated
• All documentation links corrected
• No broken imports or path references
• Old directories cleaned up (or marked for deletion)

Execution Strategy

Recommended order:

1. Reports placement (quick, non-blocking)
2. Instructions migration (parallel with schemas)
3. Schema consolidation (parallel with instructions)
4. Agents reorganization (sequential, largest scope)

Safety measures:

• Commit after each major file move
• Git history preserved for rollback
• Automated reference updates with verification

Related Issues

• Parent: Repository Structure Realignment Initiative #1290 (Repository Structure Realignment Initiative)
• Depends on: Phase 1 audits (1291, 1292, 1293, 1294)
• Depends on: Phase 2 documentation updates (1295)

Effort Estimate

8-10 hours (parallel execution reduces wall-clock time)

Notes

• Complexity: High (4 parallel streams, 3,000+ file updates)
• Risk: Medium (well-audited, but high volume)
• Coordination: Use branching strategy to prevent conflicts
• Testing: Automated reference validation before commit

[linear-code]

LS-1836

[github-actions]

⚠️ This issue was closed but does not meet our completion requirements.

Issues preventing closure:

• Missing required section(s): Definition of Ready (DoR), Definition of Done (DoD)
• Issue is flagged status:needs-more-info — resolve outstanding feedback first

What you can do:

1. Fix the issue: Edit this issue and update the body with the correct template sections (DoR and DoD sections)
2. Reopen it: Click the "Reopen issue" button on this page to reopen after fixing
3. Force close: Add the meta:force-close label to this issue if closure is necessary despite incomplete requirements

After fixing: The issue will no longer show this warning and can be closed normally.
Need help? See the issue template guide: https://github.com/lightspeedwp/.github/issues/new/choose

[github-actions]

⏱️ Aging and SLA annotation

• Age: 0 day(s)
• SLA state: Within SLA
• Thresholds: warn at 7 days, breach at 14 days
• Last updated: 2026-07-24T12:30:20.182Z

Maintained by project-meta-sync workflow.