/migrating-agent-systems

name: migrating-agent-systems
description: Sets up or migrates a project's Claude Code agent system through the analyze, brainstorm, plan, apply pipeline. Use when user says "setup agent", "migrate agent system", "configure claude code", "add agent system".

Migrating Agent Systems

Overview

**Migrating agent systems IS routing to the correct workflow based on project state.**

Detect whether an agent system already exists, then invoke the appropriate skill chain. This skill is a thin router — all logic lives in the specialized skills.

**Core principle:** Detect, don't assume. Route, don't implement.

Routing

**Pattern:** Tree **Handoff:** auto-invoke **Next:** `analyzing-agent-systems` | `brainstorming-workflows` **Chain:** main

Task Initialization (MANDATORY)

Follow [task initialization protocol](../../references/task-initialization.md).

**Tasks:** 1. Detect and assess existing agent system 2. Read or create `.rcc/config.yml` 3. Rules refactoring proposal 4. Route to appropriate skill chain

Announce: "Created 4 tasks. Starting execution..."

Task 1: Detect and Assess Existing Agent System

**Goal:** Determine the project's agent system maturity level, not just presence/absence.

**Check for Claude Code components:**

• `CLAUDE.md` (project root)
• `.claude/` directory
• `.claude/rules/` directory
• `.claude/settings.json`
• `.claude/skills/` directory

**Check for other AI tool configurations:**

• `.cursorrules` (Cursor)
• `.github/copilot-instructions.md` (GitHub Copilot)
• `.windsurfrules` (Windsurf)
• `.aider.conf.yml` (Aider)

**Check for existing conventions:**

• `.editorconfig`
• Linter configs (`.eslintrc*`, `.prettierrc*`, `ruff.toml`, etc.)
• CI/CD pipeline configs (`.github/workflows/`, `.gitlab-ci.yml`)

**Maturity classification:**

| Level | Criteria | Route | |-------|----------|-------| | **None** | No components found | → `brainstorming-workflows` | | **Seed** | Only other AI tool configs exist (`.cursorrules`, etc.) — no Claude Code components | → `brainstorming-workflows` (import existing configs as starting context) | | **Partial** | Has CLAUDE.md or rules but missing skills/hooks | → `analyzing-agent-systems` | | **Established** | Has CLAUDE.md + rules + at least one skill or hook | → `analyzing-agent-systems` |

**For Seed level:** Record which other AI configs exist and their content summary — these become input for the brainstorming step to avoid re-discovering known conventions.

**Verification:** Clear maturity classification with evidence (which components found, which missing).

Task 2: Read or Create `.rcc/config.yml`

**Goal:** Ensure the project has a `.rcc/config.yml` recording migration state and key decisions. Idempotent — on re-runs, this prevents redoing work. Also migrate legacy folders if present.

**Read [references/config-schema.md](references/config-schema.md)** for the full schema and field semantics.

**Process:**

2a — Legacy folder migration (run BEFORE creating config)

RCC v11 moved artifact output from `docs/agent-system/` + `docs/validation-reports/` into `.rcc/`. If legacy folders exist, migrate them first.

**Detect legacy folders:**

test -d docs/agent-system && echo "legacy-agent-system"
test -d docs/validation-reports && echo "legacy-validation"

**If either exists:**

1. List contents to the user: > 偵測到舊版路徑。RCC v11 起產出改寫到 `.rcc/`。建議遷移： > - `docs/agent-system/` → `.rcc/` （找到 N 份檔案） > - `docs/validation-reports/` → `.rcc/validation/` （找到 M 份檔案） > > 要執行遷移嗎？（預設：是）

2. **If confirmed:**

• `mkdir -p .rcc/validation`
• For each file in `docs/agent-system/`:
• Tracked (`git ls-files <file>` returns path) → `git mv <file> .rcc/<basename>`
• Untracked → `mv <file> .rcc/<basename>`
• For each file in `docs/validation-reports/`:
• Same tracked/untracked split → target `.rcc/validation/<basename>`
• If `docs/agent-system/archive/` exists, move wholesale: `git mv docs/agent-system/archive .rcc/archive` (or `mv` for untracked)
• `rmdir docs/agent-system docs/validation-reports` after emptying
• If `docs/` is now empty, `rmdir docs/` too

3. **If declined:** record in `decisions_log` that legacy folders were kept, and note this skill will not re-offer migration unless forced.

4. **Report to user:** summary of files moved with tracked/untracked counts.

2b — Handle `.rcc/config.yml`

1. **Check `.rcc/config.yml` exists.**

2. **If exists:** Load it. Report to user: > 偵測到 `.rcc/config.yml`：上次遷移 `{migration.last_at}`，使用 rcc `{migration.last_rcc_version}`。本次 rcc 版本為 `{current}`。 > > - release automation: `{release_automation.decision}` / `{release_automation.tool}` > - safety settings: `{settings_scope.safety_bypass}`

• If `last_rcc_version < current`: offer re-migration to pull newer patterns
• If `config_version: 1` with a `models:` block: delete the block and bump to `config_version: 2` (component parameters are not recorded in config; see [references/config-schema.md](references/config-schema.md))
• If `migration.completed: true` and versions match: ask if user wants to re-run anyway or proceed to specific task

3. **If missing:** Create `.rcc/` directory (if not already by 2a) and write a new `config.yml`. Ask the user (one round of questions):

   要記錄以下決策到 .rcc/config.yml 嗎？
   1. Release automation（版號自動化）：release-please / semantic-release / 跳過
   2. 安全規則 (safety_bypass) 要放在：
      - `.claude/settings.json`（團隊共享，checked in）[預設]
      - `.claude/settings.local.json`（個人，gitignored）
      - `~/.claude/settings.json`（使用者全域）

（不詢問、不記錄模型或 effort——這些由元件 frontmatter 控制，預設 inherit session model。）

4. **Write config.yml** with user answers + detected state from Task 1. Populate `decisions_log` with each confirmed answer. If 2a migrated folders, add a log entry recording that.

5. **Also ensure** `.gitignore` does not exclude `.rcc/` (config.yml must be tracked).

**Verification:** Legacy folders migrated or decline record