cc-os/plugins/cc-architect/planning/cc-architect-migration-plan.md

# CC-Architect Migration Plan

## Overview

Migrate cc-architect plugin to align with `plugin-architecture-philosophy.md`.

**Backup:** `~/dev/backup/cc-architect-2026-01-25/` (delete after 2026-03-25, 60 days)

**Philosophy Core Principles:**
- Skills dispatch general subagents (no custom agents)
- Commands consolidated into skills (skills are directly invocable)
- SKILL.md as 6-8 line dispatcher
- Workflows contain rubrics/templates/steps only (no theory)
- Trust AI knowledge; don't pre-document what AI knows

---

## Phase 0: Pre-Flight Checks

**Subagent:** Sonnet
**Purpose:** Resolve architectural paradoxes and validate prerequisites before migration.

### 0.1 Backup Validation
- Verify `~/dev/backup/cc-architect-2026-01-25/` exists and is complete
- Confirm backup is restorable (test copy one file back)
- Check available disk space

### 0.2 Resolve Agent-Architect Paradox

**Problem:** agent-architect skill teaches custom agent creation, but philosophy says "Custom agents are relics."

**Decision options:**
1. **Delete agent-architect** - Remove skill entirely
2. **Transform to workflow-architect** - Teach general subagent + workflow pattern instead

**Resolution:** Transform agent-architect to **workflow-architect** that teaches:
- Creating workflow documents (not agent files)
- Using general-purpose subagent with workflow paths
- This preserves the skill's purpose (helping users extend Claude) while aligning with philosophy

**Execution steps:**
1. `git mv skills/agent-architect skills/workflow-architect`
2. Update `skills/workflow-architect/SKILL.md` frontmatter: `name: workflow-architect`
3. Update `.claude-plugin/plugin.json` skills list (if referenced)
4. Grep for `/agent-architect` or `agent-architect` references → update to `/workflow-architect`
5. Update CLAUDE.md architect table
6. Update workflow files to teach workflow creation instead of agent creation

### 0.3 Resolve Slash-Command-Architect Fate

**Problem:** slash-command-architect teaches command creation, but philosophy says "Do not create new standalone commands."

**Decision:** Keep slash-command-architect for **legacy maintenance only**. Update SKILL.md to clearly state:
- Use for maintaining existing commands
- For new functionality, create skills instead
- Link to philosophy document

### 0.4 Audit Task Tool Invocations

**Action:** Grep all workflow files for `Task tool` or `Task:` invocations of custom agents.

**Known issues:**
- `new-agent.md` line 90 references description-architect agent
- `new-command.md` line 77 references description-architect agent
- `new-skill.md` line 155 references description-architect agent

**Fix strategy:** Identify all occurrences in Phase 0.4. Apply fixes during Phase 4 (workflow condensing) when those files are already being edited. This avoids duplicate file edits.

**Fix:** Update all workflows to use `Skill tool` with `/description-architect` instead of Task tool with custom agent.

### 0.5 Update Reference Docs

**Action:** Update plugin-structure.md and layout docs to mark `agents/` and `commands/` as deprecated/legacy patterns.

**Verification:**
- [ ] Backup validated
- [ ] Agent-architect transformation decision documented
- [ ] Slash-command-architect scope clarified
- [ ] All Task tool invocations of custom agents identified and fix strategy defined
- [ ] Reference docs updated to deprecate agents/commands directories

---

## Phase 1: Delete Custom Agents

**Subagent:** Haiku
**Prerequisite:** Phase 0 complete

**Files to delete (using `git rm`):**
- `agents/skill-architect.md`
- `agents/agent-architect.md`
- `agents/slash-command-architect.md`
- `agents/description-architect.md`
- `agents/plugin-architect.md`

**Before deletion:**
- Verify all workflows updated to not invoke these agents via Task tool (from Phase 0.4)

**After deletion:**
- Remove `agents/` directory if empty

**Verification:**
- `agents/` directory is empty or removed
- No workflow files contain Task tool invocations to deleted agents
- Check plugin.json doesn't reference deleted agents

**Rollback:** Restore from backup

---

## Phase 2: Delete Standalone Commands

**Subagent:** Haiku
**Files to delete (using `git rm`):**
- `commands/skill-architect.md`
- `commands/agent-architect.md`
- `commands/slash-command-architect.md`

**After deletion:**
- Remove `commands/` directory if empty

**Verification:**
- `commands/` directory is empty or removed
- Skills remain invocable via `/skill-name`
- Check plugin.json doesn't reference deleted commands

**Rollback:** Restore from backup

---

## Phase 3: Condense SKILL.md Files

**Subagent:** Sonnet (judgment required for what to keep)
**Target files:**
- `skills/skill-architect/SKILL.md`
- `skills/agent-architect/SKILL.md` → rename to `skills/workflow-architect/SKILL.md`
- `skills/slash-command-architect/SKILL.md`
- `skills/description-architect/SKILL.md`
- `skills/plugin-architect/SKILL.md`

**Transformation:**
From ~40 lines to ~10-15 lines:
```markdown
---
name: skill-architect
description: [keep existing]
---
# Skill Architect

## Workflows
- **New skill:** `workflows/new-skill.md`
- **Improve skill:** `workflows/improve-skill.md`
- **Audit skill:** `workflows/audit-skill.md`

Read `../../references/subagent-pattern.md` for dispatch rules.
```

**Verification (focus-based, not line-count):**
- Theory/explanation removed (architecture details, "why" sections)
- Workflow routing preserved (list of workflows with use-case triggers)
- Reference to subagent-pattern.md included
- Fits on one screen (~25 lines max, but clarity over count)
- All workflow paths correct and resolve
- Description frontmatter preserved

**Rollback:** Restore from backup

---

## Phase 4: Condense Workflow Files

**Subagent:** Sonnet (judgment required for what to keep)
**Prerequisite:** Read condensing rubric (below)

**Target:** All `workflows/*.md` files in each skill

### Condensing Rubric

**Remove (AI knows this):**
- "Goal:" explanations (AI understands task goals)
- "Why:" sections (trust AI reasoning)
- Framework explanations (AI knows frameworks)
- Conceptual overviews (AI has training data)

**Keep (AI doesn't know this):**
- Step numbers and sequence
- Specific file paths (project-specific)
- Templates and output formats (custom conventions)
- Rubrics and checklists (custom criteria)
- Subagent delegation hints ("Subagent: haiku/sonnet/opus")
- Checkpoints ("Confirm with user")
- Task document instructions

**Preserve invariants:**
- Workflows must include subagent hints (per skill-architect/invariants.md)
- Format can be concise but delegation info must remain

**Example transformation:**
```markdown
# Before (verbose)
### 2. Design the structure
**Goal:** Plan the skill's directory layout before creating files.
**Who:** Main agent or general subagent (cheap model).
**Must read:**
- `references/layout/reference.md`
**Do:**
- Map workflows to `workflows/*.md` files

# After (minimal)
### 2. Design structure
Subagent (haiku). Read: `references/layout/reference.md`
- Map workflows → `workflows/*.md`
- Write to task doc `## Proposed Structure`
Checkpoint: Confirm with user.
```

**User checkpoint after each workflow:**
- Show before/after comparison
- Highlight removed sections
- User confirms: "Proceed" or "Restore section X"

**Red flags (stop and review with user):**
- Step numbers changed or removed
- File paths removed
- Templates removed
- Subagent hints removed
- User checkpoints removed

**Verification:**
- Workflow files condensed (aim for 40-60% reduction, prioritize clarity over target)
- All action items preserved
- All file path references preserved and correct
- All templates/rubrics preserved
- Subagent hints preserved (invariant requirement)

**Rollback:** Restore from backup

---

## Phase 4.5: Intermediate Review

**Subagent:** Sonnet
**Purpose:** Catch major issues before final phases

**Check:**
- All condensed SKILL.md files are valid
- All condensed workflow files are functional
- No critical information lost in condensing
- Reference paths still resolve

**Output:** Quick P0-P1 issue list. Fix before proceeding.

---

## Phase 5: Update CLAUDE.md

**Subagent:** Haiku
**File:** `CLAUDE.md`

**Changes:**
- Remove references to deleted agents/commands
- Update task-to-workflow mapping if needed
- Update architect table if agent-architect renamed to workflow-architect
- Ensure skill invocation instructions are clear

**Verification:**
- No dangling references
- All listed skills exist
- Invoke instructions match current structure

**Rollback:** Restore from backup

---

## Phase 6: Validate Structure and Functionality

**Subagent:** Sonnet
**Actions:**

### Structural Validation
- Run any existing validation scripts
- Verify all internal file references resolve
- Check for broken links in reference paths
- Verify no orphaned files

### Functional Testing
For each architect skill:
- Invoke via `/skill-name` (or simulate invocation)
- Verify correct workflow is selected
- Verify subagent dispatch would work
- Complete one simple task if possible

**Output:** List of any remaining issues

---

## Phase 7: Post-Migration Review

**Subagent:** Opus (comprehensive review)
**Scope:** Full review of migrated plugin

**Checklist:**
- [ ] Alignment with plugin-architecture-philosophy.md
- [ ] No regression in capability (all workflows still work)
- [ ] Standards compliance (kebab-case, frontmatter, etc.)
- [ ] Architecture integrity (progressive disclosure maintained)
- [ ] No orphaned files
- [ ] No broken references
- [ ] Reversion protection preserved (invariants, golden examples, decisions)
- [ ] Under-scripting blind spot documented as known issue (from philosophy doc)

**Output:** P0-P3 issue report with recommendations

---

## Phase 8: Documentation

**Subagent:** Haiku
**Actions:**
- Create/update `CHANGELOG.md` (at plugin root: `cc-architect/CHANGELOG.md`) with migration notes
- Document breaking changes:
  - agent-architect → workflow-architect rename (if applicable)
  - commands/ directory removed
  - agents/ directory removed
- Note that slash-command-architect is now legacy-only

---

## Success Criteria

1. **No custom agents** - `agents/` deleted
2. **No standalone commands** - `commands/` deleted
3. **Lean SKILL.md** - Theory removed, workflow routing preserved, fits one screen
4. **Condensed workflows** - Reduced while preserving all action items
5. **No broken references** - All paths resolve
6. **No capability loss** - All workflows still executable
7. **Philosophy aligned** - Passes checklist from philosophy doc
8. **Functional testing passed** - Each skill invocable, each workflow path tested
9. **Reversion protection intact** - invariants.md, examples/golden/, .decisions/ preserved

---

## Execution Order

```
Phase 0 (pre-flight) → Phase 1 (agents) → Phase 2 (commands) → Phase 3 (SKILL.md) → Phase 4 (workflows) → Phase 4.5 (intermediate review) → Phase 5 (CLAUDE.md) → Phase 6 (validate) → Phase 7 (review) → Phase 8 (docs)
```

Each phase completes before next begins. Review after each phase for early issue detection.

---

## Rollback Procedure

If any phase fails critically:
1. Stop migration
2. Document what failed and why
3. Restore from `~/dev/backup/cc-architect-2026-01-25/`
4. Address root cause before retrying