Phase 1A: Audit & Migrate Instructions

[ashleyshaw]

Overview

Audit and migrate instructions from .github/instructions/ (currently mixed portable + repo-local) to separate structure:

• Portable standards → root instructions/ folder
• Repo-local guidance → .github/instructions/ (control-plane-specific only)

Scope

Source: 47 files in .github/instructions/
References: 502 references across 156 files (423 in documentation, 17 in scripts, 5 in workflows, 57 in config)
Portable files: 12 portable instruction files (a11y, coding-standards, documentation-formats, issues, pull-requests, etc.)
Repo-local files: 35 control-plane-specific instruction files

Definition of Done

• Identify and categorize all 47 instruction files (portable vs. repo-local)
• Update 8 broken links in CLAUDE.md
• Update AGENTS.md references
• Update all 502 reference locations
• Migrate portable files to root instructions/
• Keep repo-local files in .github/instructions/
• Update .github/custom-instructions.md with new paths
• Update instructions/file-organisation.instructions.md
• Validate all CI workflows pass
• Archive migration notes in CHANGELOG

Related Issues

• Parent: Repository Structure Realignment Initiative #1290 (Repository Structure Realignment Initiative)
• Related: Schema consolidation (Repository Structure: Schema Consolidation Migration #1288)
• Related: Agents reorganization (TBD)

Effort Estimate

2-3 hours (audit + migration + validation)

Notes

• Archive handling: Migrate .github/instructions/.archive/ to instructions/.archive/
• Pattern precedent: plugin-structure.instructions.md already successfully migrated
• Priority: High (blocks other structure realignment work)

[linear-code]

LS-1831

[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:29:36.143Z

Maintained by project-meta-sync workflow.