[Feature Idea] Agent Versioning and Non-Destructive Update System

The Problem

Currently, users can create and customize a powerful collection of agents in their ~/.claude/agents/ directory. This is a fantastic feature for personalization. However, a long-term challenge arises:

• Agents Become Stale: As the underlying technologies evolve (e.g., React 19, new Python best practices), the base instructions within these agents can become outdated.
• Manual Updates are Risky: Users have no safe way to incorporate improvements or bug fixes from the upstream repository into their customized agents without the risk of overwriting their personal modifications.
• No Centralized Knowledge: There is no system to track which version of an agent a user has, or to notify them of critical updates.

This creates a dilemma: either the user sticks with an outdated agent, or they risk losing their valuable customizations during a manual update.

Proposed Solution

I propose an Agent Versioning and Update Manifest System. This system would allow users to safely update the "base" logic of their agents while intelligently preserving their custom modifications.

This would involve three core components:

1. Version Metadata: Agents would have version information embedded in their YAML frontmatter.
2. Update Manifest: A central manifest.json file in the repository would define available updates, changes, and non-destructive patches.
3. CLI Update Tool: A command (e.g., ./squad update) would manage the entire process, from checking for updates to applying them safely.

---

Detailed Implementation Plan

Here is a breakdown of the proposed system components:

1. Version Metadata in Agent Frontmatter

We would extend the agent's YAML frontmatter to include versioning and update information.

---
name: react-performance-ninja
description: React optimization specialist

# Versioning & Update Fields
version: 1.2.0
base_agent: react-arena-specialist  # Optional: Tracks the original template
last_updated: 2024-01-31
update_channel: stable             # Users could opt into 'stable' or 'beta' channels
---

2. The Update Manifest (manifest.json)

A new file, agents/updates/manifest.json, would serve as the source of truth for all available updates.

• It would list updates by version, including a human-readable changelog.
• Crucially, it would contain a patches array with structured instructions on how to apply the update (e.g., append to a section, replace a specific string).

{
  "updates": [
    {
      "agent_pattern": "react-*",
      "version": "1.3.0",
      "date": "2024-02-01",
      "changes": {
        "libraries": ["Added React 19 support", "Updated for Next.js 14 patterns"],
        "capabilities": ["New section on Server Components best practices"],
        "fixes": ["Improved memory leak detection instructions"]
      },
      "patches": [
        {
          "type": "append",
          "section_header": "## Core Principles",
          "content_to_add": "\n\n## React 19 Features\nYou are an expert in React 19, including the `use` hook..."
        },
        {
          "type": "replace",
          "target_string": "always use React.memo for performance",
          "replacement_string": "use React.memo strategically for performance, especially with expensive component trees"
        }
      ]
    }
  ]
}

3. CLI-Based Agent Update Tool (./squad update)

A new command would be added to the squad CLI tool to provide a safe and intuitive user experience.

User Workflow:

1. The user runs ./squad update.
2. The tool scans ~/.claude/agents/, checking the version of each agent against the manifest.json.
3. It presents a clear list of available updates and their changelogs.

```
Updates Available:

• react-performance-ninja (1.2.0 -> 1.3.0)
• Added React 19 support
• New section on Server Components

```

1. The user can view a diff preview of the proposed changes before accepting.
2. If the user accepts, the tool automatically creates a backup of the existing agent.
3. It then applies the patches from the manifest.
4. An update_history.json file logs all actions for future reference and potential rollbacks.

4. Advanced Features (Update Modes & squad-commander Integration)

• Update Modes:
• Suggest Mode (Default): Show what could be updated without applying any changes.
• Patch Mode: Apply all available updates automatically after user confirmation.
• Interactive Merge Mode: For complex updates, guide the user through a merge process.
• Rollback Mode: Revert an agent to a previous version using the backup.
• squad-commander Enhancement: The commander would be updated to generate new agents with the latest version metadata from the start.

Benefits of This System

• Longevity and Maintainability: Custom agents remain relevant and powerful over time.
• User Confidence: Users can customize their agents freely, knowing they won't miss out on important upstream improvements.
• Safe Updates: The backup and rollback system eliminates the risk of losing work.
• Clear Debugging: Version tracking helps identify issues related to outdated agent instructions.
• Community Contributions: Creates a clear pathway for the community to contribute not just new agents, but also patches and improvements to existing ones.

This system would transform the agents from static files into a living, evolving toolkit, significantly enhancing the long-term value of the platform. I'm open to feedback and would be happy to discuss this proposal further.