360 lines
11 KiB
Markdown
360 lines
11 KiB
Markdown
# 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
|