jared
/
cc-os
1
0
Fork 0
Code Issues 18 Pull Requests Packages Projects Releases Wiki Activity
cc-os/plugins/cc-architect/planning/cc-architect-migration-plan.md

11 KiB
Raw Blame History

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:

---
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:

# 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