Phase 3C: Agent reorganization and migration

[ashleyshaw]

Phase 3C: Agent Reorganization and Migration

Epic: Repository Restructuring Initiative
Depends on: #1295 (Phase 2) ✅, #1542 (Phase 3B) ✅
Parallel with: #1535 (Phase 3A), #1537 (Phase 3D)
Type: Phase 3 sub-task (agent reorganization)
Priority: High

Overview

Phase 1C audited agent structure and identified 35 agents (19 spec-based + 16 multi-file) across 788+ references. Phase 3C executes the reorganization:

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

Status: Ready to execute
Estimated effort: 6–8 hours
Timeline: Execute in parallel with Phase 3A & 3D

---

Tasks

Task 1: Spec-Based Agents Organization (.github/agents/)

Verify 19 spec-based agent files in correct location:

• `.github/agents/{agent-name}.agent.md`
• Examples: AI-Readiness-Estimator, Website-Scope-Estimator, Zendesk-Support

Actions:

• Verify all 19 spec-based agents are in `.github/agents/`
• Check all agent manifests have correct `file_type: agent-spec`
• Verify references in AGENTS.md point to `.github/agents/`

---

Task 2: Multi-File Agents Organization (root agents/)

Verify 16 multi-file agents in correct locations:

• `agents/{agent-name}/` — full multi-file implementations
• Examples: PRD-Agent (1,637 files), Playwright-Testing-Agent (458 files)

Actions:

• Verify all 16 multi-file agents are at root `agents/` level
• Check agent structure: agent/, skills/, references/ subdirs
• Verify 788+ references across codebase point to correct locations

---

Task 3: Update All References (788+ locations)

Batch update references by priority:

P0 Critical (50–75 refs):

• CLAUDE.md agent structure section
• AGENTS.md agent listing & architecture
• agents/agent.md reference table
• .github/agents/ README

P1 High (200–300 refs):

• Documentation files (docs/, instructions/)
• Agent README files
• Schema definitions referencing agents
• workflow files

P2 Medium (100–150 refs):

• Script references
• Test file imports
• Configuration references
• Comments/documentation

P3 Low (remainder):

• Old/archived references
• Comments that mention agent names

---

Task 4: Consolidation & Cleanup

Actions:

• Remove duplicate agent definitions (if any found)
• Archive obsolete agent versions with deprecation notices
• Verify no "orphan" agent references (pointing to non-existent agents)
• Update AGENT_STRUCTURE.md documentation

---

Success Criteria (DoD)

• All 19 spec-based agents verified in `.github/agents/`
• All 16 multi-file agents verified in root `agents/`
• All 788+ references updated to correct locations
• Agent manifests validated with correct `file_type`
• CLAUDE.md and AGENTS.md updated with final structure
• No broken agent references in codebase
• All files pass linting
• PR created, reviewed, merged to develop
• Link this issue in commit/PR for traceability

---

Related Issues

• Phase 1C: Audit Agent Reorganization (Restructured) #1301 — Phase 1C: Agent reorganization audit
• docs: Phase 2 governance updates with Phase 1 audit findings (#1295) #1534 — Phase 2: Governance ✅ MERGED
• Phase 3: Execute File Migrations & Reference Updates (#1296) #1535 — Phase 3A: Instructions migration
• Phase 3B: Schema consolidation completion & path consistency #1542 — Phase 3B: Schema consolidation ✅ COMPLETE
• refactor: delete .github/agents per Phase 1 restructuring (#1510) #1537 — Phase 3D: Reports consolidation
• Repository Structure Realignment Initiative #1290 — Repository restructuring epic

---

Phase 3 parallel execution: 6–8 hour timeline

Definition of Ready (DoR)

• Phase 1B audit complete (Phase 1C: Audit Agent Reorganization (Restructured) #1301)
• Phase 2 governance complete (docs: Phase 2 governance updates with Phase 1 audit findings (#1295) #1534)
• Phase 3B schema consolidation complete (Phase 3B: Schema consolidation completion & path consistency #1542)
• Repository restructuring epic in progress

Definition of Done (DoD)

• All 19 spec-based agents verified in .github/agents/
• All 16 multi-file agents verified in root agents/
• All 788+ references updated to correct locations
• Agent manifests validated with correct file_type
• CLAUDE.md and AGENTS.md updated with final structure
• No broken agent references in codebase
• All files pass linting
• Code merged to develop
• Parallel with: Phase 3: Execute File Migrations & Reference Updates (#1296) #1535 (Phase 3A), refactor: delete .github/agents per Phase 1 restructuring (#1510) #1537 (Phase 3D)

[linear-code]

LS-2281

[github-actions]

✅ Template check passed after update. Thanks for fixing the issue body.

[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-08-05T11:31:34.232Z

Maintained by project-meta-sync workflow.