Repository navigation
Description
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
- task: documentation - migrate files and update references #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: task: documentation - migrate files and update references #1535 (Phase 3A), refactor: delete .github/agents per Phase 1 restructuring (#1510) #1537 (Phase 3D)
Metadata
Metadata
Assignees
Labels
Type
Fields
Priority
Activity
linear-code commentedon Aug 5, 2026
LS-2281
github-actions commentedon Aug 5, 2026
✅ Template check passed after update. Thanks for fixing the issue body.
github-actions commentedon Aug 5, 2026
⏱️ Aging and SLA annotation
Maintained by project-meta-sync workflow.
ashleyshaw commentedon Aug 7, 2026
✅ COMPLETE: Phase 3C Agent Reorganization merged (PR #1583). Two-tier agent structure implemented: Tier 1 GitHub-native in .github/agents/, Tier 2 portable in root agents/. All 35 agents properly categorized.
github-actions commentedon Aug 7, 2026
✅ Issue checklists finalised after closure.
feat: Phase 3 label validation enforcement (#1613)
docs: Add Phase 1-3 Completion Report (#1624)
feat: Phase 3 label validation enforcement (#1613)
docs: Add Phase 1-3 Completion Report (#1624)
docs: Add Phase 1-3 Completion Report (#1624)
docs: Add Phase 1 implementation plan and project documentation (#1612)
github-actions commentedon Sep 8, 2026
This issue has labels that are not in the canonical taxonomy:
migrate:type:taskpriority:highValid Canonical Labels
Please use labels with a prefix from the canonical taxonomy:
type:bug,type:feature,type:task,type:documentation, etc.status:needs-triage,status:in-progress,status:done, etc.priority:critical,priority:high,priority:normal,priority:lowarea:ci,area:docs,area:labels,area:security, etc.meta:needs-changelog,meta:duplicate,meta:blocked, etc.For the complete list, see .github/labels.yml.