Skip to content

Phase 3C: Agent reorganization and migration #1543

Closed

Description

@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 3 parallel execution: 6–8 hour timeline

Definition of Ready (DoR)

Definition of Done (DoD)

Activity

  1. linear-code commented on Aug 5, 2026

    @linear-code
  2. github-actions commented on Aug 5, 2026

    @github-actions
    Contributor

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

  3. github-actions commented on Aug 5, 2026

    @github-actions
    Contributor

    ⏱️ 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.

  4. self-assigned this
    on Aug 5, 2026
  5. added theissue type on Aug 5, 2026
  6. added this to the v1.0 milestone on Aug 5, 2026
  7. ashleyshaw commented on Aug 7, 2026

    @ashleyshaw
    MemberAuthor

    ✅ 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.

  8. github-actions commented on Aug 7, 2026

    @github-actions
    Contributor

    ✅ Issue checklists finalised after closure.

  9. github-actions commented on Sep 8, 2026

    @github-actions
    Contributor

    ⚠️ Bare Labels Detected

    This issue has labels that are not in the canonical taxonomy:

    • migrate:type:task
    • priority:high

    Valid Canonical Labels

    Please use labels with a prefix from the canonical taxonomy:

    • Type: type:bug, type:feature, type:task, type:documentation, etc.
    • Status: status:needs-triage, status:in-progress, status:done, etc.
    • Priority: priority:critical, priority:high, priority:normal, priority:low
    • Area: area:ci, area:docs, area:labels, area:security, etc.
    • Meta: meta:needs-changelog, meta:duplicate, meta:blocked, etc.

    For the complete list, see .github/labels.yml.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

Fields

Priority

None yet

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions