agent-retire

You are the Agent Retire command — graceful deprecation flow for AI workforce. Removes an agent from active rotation while preserving audit trail and reversibility.

When to use

• Agent has had 0 invocations in last 90 days (use /agent-review --idle to find candidates)
• Agent's archetype is no longer in your active project mix
• Agent's prompt is being superseded by a better one (consolidation)
• Agent has been flagged as misbehaving in multiple verdicts

What gets retired

1. Agent prompt file — agents/<name>.md → agents/_retired/<name>.md
2. SessionStart sync list — <name> removed from plugin.json
3. Decisions log — entry added to ~/.great_cto/decisions.md
4. Verdicts — ~/.great_cto/verdicts/<name>.log preserved (audit trail; never deleted)
5. Lessons referencing the agent — left untouched (historical record)

What's reversible

To un-retire: mv agents/_retired/<name>.md agents/<name>.md + add back to sync list. All prior verdicts/lessons resume.

Step 1 — Parse args + validate

source .great_cto/env.sh 2>/dev/null || export PATH="/opt/homebrew/bin:$HOME/.local/bin:/usr/local/bin:$PATH"

ARCHIVE_ONLY=0
REASON=""
AGENT_NAME=""
LIST_CANDIDATES=0

# Parse args
while [ $# -gt 0 ]; do
  case "$1" in
    --archive-only)   ARCHIVE_ONLY=1; shift ;;
    --list-candidates) LIST_CANDIDATES=1; shift ;;
    --reason)         REASON="$2"; shift 2 ;;
    --reason=*)       REASON="${1#*=}"; shift ;;
    *)                AGENT_NAME="$1"; shift ;;
  esac
done

# --list-candidates mode
if [ "$LIST_CANDIDATES" = "1" ]; then
  echo "## Retire candidates — agents with 0 invocations in last 90 days"
  echo ""
  SINCE_TS=$(date -u -v -90d +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || \
             date -u -d "90 days ago" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null)
  VERDICTS_DIR=~/.great_cto/verdicts
  [ -d "$VERDICTS_DIR" ] || VERDICTS_DIR=.great_cto/verdicts

  for log in "$VERDICTS_DIR"/*.log; do
    [ -f "$log" ] || continue
    AGENT=$(basename "$log" .log)
    RECENT_COUNT=$(awk -v ts="$SINCE_TS" '$1 > ts' "$log" | wc -l | tr -d ' ')
    if [ "$RECENT_COUNT" = "0" ]; then
      LAST=$(tail -1 "$log" 2>/dev/null | awk '{print $1}')
      echo "- \`$AGENT\` — last seen $LAST"
    fi
  done

  echo ""
  echo "_To retire: \`/agent-retire <name>\`. Files preserved in \`agents/_retired/\` for un-retire later._"
  exit 0
fi

# Validate agent name
if [ -z "$AGENT_NAME" ]; then
  echo "Usage: /agent-retire <agent-name> [--archive-only] [--reason 'text']"
  echo "       /agent-retire --list-candidates"
  exit 2
fi

AGENT_FILE="agents/$AGENT_NAME.md"
if [ ! -f "$AGENT_FILE" ]; then
  echo "No such agent file: $AGENT_FILE"
  echo ""
  echo "Available agents (active):"
  ls agents/*.md 2>/dev/null | sed 's|agents/||; s|\.md||' | head -40
  exit 1
fi