Phase 1C: Reorganize Agents (Two-Tier Structure)

[ashleyshaw]

Overview

Reorganize agents to implement two-tier structure:

• Spec-based agents (simple YAML/JSON): .github/agents/
• Multi-file agents (complex implementations): root agents/

Scope

Current State: 35 agents (12,459 files) all in .github/agents/

• 19 spec-based agents (simple definitions)
• 16 multi-file agents (enterprise implementations)

Target State:

• Spec-based → .github/agents/ (control-plane-specific)
• Multi-file → root agents/ (installable, portable)

References: 3,751+ files reference agent paths

• Memory profiles: 19 files expect root agent paths
• Plugin integration: 10+ plugin files reference root paths
• Documentation: Governance files (CLAUDE.md, AGENTS.md, file-organisation.instructions.md)

Definition of Done

• Inventory and categorize all 35 agents (spec-based vs. multi-file)
• Identify all spec-based agent files (19 agents)
• Identify all multi-file agent directories (16 agents)
• Update memory profile system references
• Move spec-based agents to .github/agents/
• Move multi-file agents to root agents/
• Update CLAUDE.md (agent tier documentation)
• Update AGENTS.md (canonical paths)
• Update file-organisation.instructions.md
• Update all 3,751+ reference locations
• Update plugin integration files (10+ files)
• Update workflow references
• Validate memory profile system works
• Run CI/CD pipeline
• Update CHANGELOG with migration entry

Related Issues

• Parent: Repository Structure Realignment Initiative #1290 (Repository Structure Realignment Initiative)
• Tracked in: Issue [Audit] File Organization - Align with CLAUDE.md Repository Boundaries #653 (File Organization Audit)
• Related documentation: Agent standards initiative

Effort Estimate

6-8 hours (audit + migrations + comprehensive reference updates)

Notes

• Highest complexity: 12,459 files involved, 3,751+ references
• Memory system integration: Must validate after migration
• Plugin ecosystem: Must maintain backward compatibility
• Risk: Medium (large scope, but well-understood dependencies)
• Priority: High (foundational for portable agent distribution)
• Timeline: Can proceed after instructions/schemas (sequential recommended)

[linear-code]

LS-1833

[github-actions]

⚠️ This issue does not follow a required issue template.

Missing required section(s): Definition of Ready (DoR), Definition of Done (DoD)

The issue will remain open and flagged until the body is corrected.
Please update the issue with one of the official templates:

• https://github.com/lightspeedwp/.github/issues/new/choose

If this was opened by automation, update the automation to preserve the template sections before creating the issue.

[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:43.153Z

Maintained by project-meta-sync workflow.