Team Arch Opt

Team Architecture Optimization

Orchestrate multi-agent architecture optimization: analyze codebase → design refactoring plan → implement changes → validate improvements → review code quality.

Architecture

Skill(skill="team-arch-opt", args="task description")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- analyze → dispatch → spawn workers → STOP
                                    |
                    +-------+-------+-------+-------+
                    v       v       v       v       v
                 [analyzer][designer][refactorer][validator][reviewer]

Role Registry

Role Router

Parse $ARGUMENTS:

• Has --role <name> → Read roles/<name>/role.md, execute Phase 2-4
• No --role → @roles/coordinator/role.md, execute entry router

Shared Constants

• Session prefix: TAO
• Session path: .workflow/.team/TAO-<slug>-<date>/
• CLI tools: ccw cli --mode analysis (read-only), ccw cli --mode write (modifications)
• Message bus: mcp__ccw-tools__team_msg(session_id=<session-id>, ...)

Worker Spawn Template

Coordinator spawns workers using this template:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: "arch-opt",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: arch-opt
requirement: <task-description>
inner_loop: <true|false>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

Inner Loop roles (refactorer): Set inner_loop dynamically — true for single mode, false for fan-out/independent (parallel branches). Single-task roles (analyzer, designer, validator, reviewer): Set inner_loop: false.

User Commands

Session Directory

.workflow/.team/TAO-<slug>-<date>/
├── session.json                    # Session metadata + status + parallel_mode
├── task-analysis.json              # Coordinator analyze output
├── artifacts/
│   ├── architecture-baseline.json  # Analyzer: pre-refactoring metrics
│   ├── architecture-report.md      # Analyzer: ranked structural issue findings
│   ├── refactoring-plan.md         # Designer: prioritized refactoring plan
│   ├── validation-results.json     # Validator: post-refactoring validation
│   ├── review-report.md            # Reviewer: code review findings
│   ├── aggregate-results.json      # Fan-out/independent: aggregated results
│   ├── branches/                   # Fan-out mode branch artifacts
│   │   └── B{NN}/
│   │       ├── refactoring-detail.md
│   │       ├── validation-results.json
│   │       └── review-report.md
│   └── pipelines/                  # Independent mode pipeline artifacts
│       └── {P}/
│           └── ...
├── explorations/
│   ├── cache-index.json            # Shared explore cache
│   └── <hash>.md
├── wisdom/
│   └── patterns.md                 # Discovered patterns and conventions
├── discussions/
│   ├── DISCUSS-REFACTOR.md
│   └── DISCUSS-REVIEW.md
└── .msg/
    ├── messages.jsonl              # Message bus log
    └── meta.json                   # Session state + cross-role state

Specs Reference

• specs/pipelines.md — Pipeline definitions, task registry, parallel modes

Error Handling

Architecture Analyzer

Analyze codebase architecture to identify structural issues: dependency cycles, coupling/cohesion problems, layering violations, God Classes, code duplication, dead code, and API surface bloat. Produce quantified baseline metrics and a ranked architecture report.

Phase 2: Context & Environment Detection

1. Extract session path and target scope from task description 2. Detect project type by scanning for framework markers:

3. Use explore CLI tool to map module structure, dependency graph, and layer boundaries within target scope 4. Detect available analysis tools (linters, dependency analyzers, build tools)

Phase 3: Architecture Analysis

Execute analysis based on detected project type:

Dependency analysis:

• Build import/require graph across modules
• Detect circular dependencies (direct and transitive cycles)
• Identify layering violations (e.g., UI importing from data layer, utils importing from domain)
• Calculate fan-in/fan-out per module (high fan-out = fragile hub, high fan-in = tightly coupled)

Structural analysis:

• Identify God Classes / God Modules (> 500 LOC, > 10 public methods, too many responsibilities)
• Calculate coupling metrics (afferent/efferent coupling per module)
• Calculate cohesion metrics (LCOM -- Lack of Cohesion of Methods)
• Detect code duplication (repeated logic blocks, copy-paste patterns)
• Identify missing abstractions (repeated conditionals, switch-on-type patterns)

API surface analysis:

• Count exported symbols per module (export bloat detection)
• Identify dead exports (exported but never imported elsewhere)
• Detect dead code (unreachable functions, unused variables, orphan files)
• Check for pattern inconsistencies (mixed naming conventions, inconsistent error handling)

All project types:

• Collect quantified architecture baseline metrics (dependency count, cycle count, coupling scores, LOC distribution)
• Rank top 3-7 architecture issues by severity (Critical / High / Medium)
• Record evidence: file paths, line numbers, measured values

Tech Profile Scan

After analysis, scan findings for context-aware trigger signals (based on detected codebase characteristics):

1. Check dependency analysis → signals (sql_detected, auth_detected, ml_detected) 2. Check structural analysis → risk signals (perf_sensitive, legacy_patterns, scaling_concern) 3. Include tech_profile in Phase 5 state_update data

Phase 4: Report Generation

1. Write architecture baseline to <session>/artifacts/architecture-baseline.json:

• Module count, dependency count, cycle count, average coupling, average cohesion
• God Class candidates with LOC and method count
• Dead code file count, dead export count
• Timestamp and project type details

2. Write architecture report to <session>/artifacts/architecture-report.md:

• Ranked list of architecture issues with severity, location (file:line or module), measured impact
• Issue categories: CYCLE, COUPLING, COHESION, GOD_CLASS, DUPLICATION, LAYER_VIOLATION, DEAD_CODE, API_BLOAT
• Evidence summary per issue
• Detected project type and analysis methods used

3. Update <session>/wisdom/.msg/meta.json under analyzer namespace:

• Read existing -> merge { "analyzer": { project_type, issue_count, top_issue, scope, categories } } -> write back

Analyze Task

Parse user task -> detect architecture capabilities -> build dependency graph -> design roles.

CONSTRAINT: Text-level analysis only. NO source code reading, NO codebase exploration.

Signal Detection

Dependency Graph

Natural ordering tiers:

• Tier 0: analyzer (knowledge gathering -- no dependencies)
• Tier 1: designer (requires analyzer output)
• Tier 2: refactorer (requires designer output)
• Tier 3: validator, reviewer (validation requires refactored artifacts, can run in parallel)

Complexity Scoring

Results: 1-3 Low, 4-6 Medium, 7+ High

Role Minimization

• Cap at 5 roles
• Merge overlapping capabilities
• Absorb trivial single-step roles

Output

Write <session>/task-analysis.json:

{
  "task_description": "<original>",
  "pipeline_type": "<single|fan-out|independent|auto>",
  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
  "complexity": { "score": 0, "level": "Low|Medium|High" },
  "parallel_mode": "<auto|single|fan-out|independent>",
  "max_branches": 5
}

Command: Dispatch

Create the architecture optimization task chain with correct dependencies and structured task descriptions. Supports single, fan-out, independent, and auto parallel modes.

Phase 2: Context Loading

1. Load user requirement and refactoring scope from session.json 2. Load pipeline stage definitions from SKILL.md Task Metadata Registry 3. Read parallel_mode and max_branches from session.json 4. For independent mode: read independent_targets array from session.json

Phase 3: Task Chain Creation (Mode-Branched)

Task Description Template

Every task description uses structured format for clarity:

TaskCreate({
  subject: "<TASK-ID>",
  description: "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>
TASK:
  - <step 1: specific action>
  - <step 2: specific action>
  - <step 3: specific action>
CONTEXT:
  - Session: <session-folder>
  - Scope: <refactoring-scope>
  - Branch: <branch-id or 'none'>
  - Upstream artifacts: <artifact-1>, <artifact-2>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <deliverable path> + <quality criteria>
CONSTRAINTS: <scope limits, focus areas>
---
InnerLoop: <true|false>
BranchId: <B01|A|none>"
})
TaskUpdate({ taskId: "<TASK-ID>", addBlockedBy: [<dependency-list>], owner: "<role>" })

Mode Router

---

Single Mode Task Chain

Create tasks in dependency order (backward compatible, unchanged):

ANALYZE-001 (analyzer, Stage 1):

TaskCreate({
  subject: "ANALYZE-001",
  description: "PURPOSE: Analyze codebase architecture to identify structural issues | Success: Baseline metrics captured, top 3-7 issues ranked by severity
TASK:
  - Detect project type and available analysis tools
  - Execute analysis across relevant dimensions (dependencies, coupling, cohesion, layering, duplication, dead code)
  - Collect baseline metrics and rank architecture issues by severity
CONTEXT:
  - Session: <session-folder>
  - Scope: <refactoring-scope>
  - Branch: none
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/artifacts/architecture-baseline.json + <session>/artifacts/architecture-report.md | Quantified metrics with evidence
CONSTRAINTS: Focus on <refactoring-scope> | Analyze before any changes
---
InnerLoop: false"
})
TaskUpdate({ taskId: "ANALYZE-001", owner: "analyzer" })

DESIGN-001 (designer, Stage 2):

TaskCreate({
  subject: "DESIGN-001",
  description: "PURPOSE: Design prioritized refactoring plan from architecture analysis | Success: Actionable plan with measurable success criteria per refactoring
TASK:
  - Analyze architecture report and baseline metrics
  - Select refactoring strategies per issue type
  - Prioritize by impact/effort ratio, define success criteria
  - Each refactoring MUST have a unique REFACTOR-ID (REFACTOR-001, REFACTOR-002, ...) with non-overlapping target files
CONTEXT:
  - Session: <session-folder>
  - Scope: <refactoring-scope>
  - Branch: none
  - Upstream artifacts: architecture-baseline.json, architecture-report.md
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/artifacts/refactoring-plan.md | Priority-ordered with structural improvement targets, discrete REFACTOR-IDs
CONSTRAINTS: Focus on highest-impact refactorings | Risk assessment required | Non-overlapping file targets per REFACTOR-ID
---
InnerLoop: false"
})
TaskUpdate({ taskId: "DESIGN-001", addBlockedBy: ["ANALYZE-001"], owner: "designer" })

REFACTOR-001 (refactorer, Stage 3):

TaskCreate({
  subject: "REFACTOR-001",
  description: "PURPOSE: Implement refactoring changes per design plan | Success: All planned refactorings applied, code compiles, existing tests pass
TASK:
  - Load refactoring plan and identify target files
  - Apply refactorings in priority order (P0 first)
  - Update all import references for moved/renamed modules
  - Validate changes compile and pass existing tests
CONTEXT:
  - Session: <session-folder>
  - Scope: <refactoring-scope>
  - Branch: none
  - Upstream artifacts: refactoring-plan.md
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: Modified source files + validation passing | Refactorings applied without regressions
CONSTRAINTS: Preserve existing behavior | Update all references | Follow code conventions
---
InnerLoop: true"
})
TaskUpdate({ taskId: "REFACTOR-001", addBlockedBy: ["DESIGN-001"], owner: "refactorer" })

VALIDATE-001 (validator, Stage 4 - parallel):

TaskCreate({
  subject: "VALIDATE-001",
  description: "PURPOSE: Validate refactoring results against baseline | Success: Build passes, tests pass, no metric regressions, API compatible
TASK:
  - Load architecture baseline and plan success criteria
  - Run build validation (compilation, type checking)
  - Run test validation (existing test suite)
  - Compare dependency metrics against baseline
  - Verify API compatibility (no dangling references)
CONTEXT:
  - Session: <session-folder>
  - Scope: <refactoring-scope>
  - Branch: none
  - Upstream artifacts: architecture-baseline.json, refactoring-plan.md
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/artifacts/validation-results.json | Per-dimension validation with verdicts
CONSTRAINTS: Must compare against baseline | Flag any regressions or broken imports
---
InnerLoop: false"
})
TaskUpdate({ taskId: "VALIDATE-001", addBlockedBy: ["REFACTOR-001"], owner: "validator" })

REVIEW-001 (reviewer, Stage 4 - parallel):

TaskCreate({
  subject: "REVIEW-001",
  description: "PURPOSE: Review refactoring code for correctness, pattern consistency, and migration safety | Success: All dimensions reviewed, verdict issued
TASK:
  - Load modified files and refactoring plan
  - Review across 5 dimensions: correctness, pattern consistency, completeness, migration safety, best practices
  - Issue verdict: APPROVE, REVISE, or REJECT with actionable feedback
CONTEXT:
  - Session: <session-folder>
  - Scope: <refactoring-scope>
  - Branch: none
  - Upstream artifacts: refactoring-plan.md, validation-results.json (if available)
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/artifacts/review-report.md | Per-dimension findings with severity
CONSTRAINTS: Focus on refactoring changes only | Provide specific file:line references
---
InnerLoop: false"
})
TaskUpdate({ taskId: "REVIEW-001", addBlockedBy: ["REFACTOR-001"], owner: "reviewer" })

---

Auto / Fan-out Mode Task Chain (Deferred Branching)

For auto and fan-out modes, create only shared stages now. Branch tasks are created at CP-2.5 after DESIGN-001 completes.

Create ANALYZE-001 and DESIGN-001 with same templates as single mode above.

Do NOT create REFACTOR/VALIDATE/REVIEW tasks yet. They are created by the CP-2.5 Branch Creation subroutine in monitor.md.

---

Independent Mode Task Chain

For independent mode, create M complete pipelines -- one per target in independent_targets array.

Pipeline prefix chars: A, B, C, D, E, F, G, H, I, J (from config pipeline_prefix_chars).

For each target index i (0-based), with prefix char P = pipeline_prefix_chars[i]:

// Create session subdirectory for this pipeline
Bash("mkdir -p <session>/artifacts/pipelines/<P>")

TaskCreate({ subject: "ANALYZE-<P>01", ... })
TaskCreate({ subject: "DESIGN-<P>01", ... })
TaskUpdate({ taskId: "DESIGN-<P>01", addBlockedBy: ["ANALYZE-<P>01"] })
TaskCreate({ subject: "REFACTOR-<P>01", ... })
TaskUpdate({ taskId: "REFACTOR-<P>01", addBlockedBy: ["DESIGN-<P>01"] })
TaskCreate({ subject: "VALIDATE-<P>01", ... })
TaskUpdate({ taskId: "VALIDATE-<P>01", addBlockedBy: ["REFACTOR-<P>01"] })
TaskCreate({ subject: "REVIEW-<P>01", ... })
TaskUpdate({ taskId: "REVIEW-<P>01", addBlockedBy: ["REFACTOR-<P>01"] })

Task descriptions follow same template as single mode, with additions:

• Pipeline: <P> in CONTEXT
• Artifact paths use <session>/artifacts/pipelines/<P>/ instead of <session>/artifacts/
• Meta.json namespace uses <role>.<P> (e.g., analyzer.A, refactorer.B)
• Each pipeline's scope is its specific target from independent_targets[i]

Example for pipeline A with target "refactor auth module":

TaskCreate({
  subject: "ANALYZE-A01",
  description: "PURPOSE: Analyze auth module architecture | Success: Auth module structural issues identified
TASK:
  - Detect project type and available analysis tools
  - Execute architecture analysis focused on auth module
  - Collect baseline metrics and rank auth module issues
CONTEXT:
  - Session: <session-folder>
  - Scope: refactor auth module
  - Pipeline: A
  - Shared memory: <session>/wisdom/.msg/meta.json (namespace: analyzer.A)
EXPECTED: <session>/artifacts/pipelines/A/architecture-baseline.json + architecture-report.md
CONSTRAINTS: Focus on auth module scope
---
InnerLoop: false
PipelineId: A"
})
TaskUpdate({ taskId: "ANALYZE-A01", owner: "analyzer" })

---

CP-2.5: Branch Creation Subroutine

Triggered by: monitor.md handleCallback when DESIGN-001 completes in auto or fan-out mode.

Procedure:

1. Read <session>/artifacts/refactoring-plan.md to count REFACTOR-IDs 2. Read .msg/meta.json -> designer.refactoring_count 3. Auto mode decision:

4. Update session.json with resolved parallel_mode (auto -> single or fan-out)

5. Fan-out branch creation (when count >= 3 or forced fan-out):

• Truncate to max_branches if refactoring_count > max_branches (keep top N by priority)
• For each refactoring i (1-indexed), branch ID = B{NN} where NN = zero-padded i:

// Create branch artifact directory
Bash("mkdir -p <session>/artifacts/branches/B{NN}")

// Extract single REFACTOR detail to branch
Write("<session>/artifacts/branches/B{NN}/refactoring-detail.md",
  extracted REFACTOR-{NNN} block from refactoring-plan.md)

6. Create branch tasks for each branch B{NN}:

TaskCreate({
  subject: "REFACTOR-B{NN}",
  description: "PURPOSE: Implement refactoring REFACTOR-{NNN} | Success: Single refactoring applied, compiles, tests pass
TASK:
  - Load refactoring detail from branches/B{NN}/refactoring-detail.md
  - Apply this single refactoring to target files
  - Update all import references for moved/renamed modules
  - Validate changes compile and pass existing tests
CONTEXT:
  - Session: <session-folder>
  - Branch: B{NN}
  - Upstream artifacts: branches/B{NN}/refactoring-detail.md
  - Shared memory: <session>/wisdom/.msg/meta.json (namespace: refactorer.B{NN})
EXPECTED: Modified source files for REFACTOR-{NNN} only
CONSTRAINTS: Only implement this branch's refactoring | Do not touch files outside REFACTOR-{NNN} scope
---
InnerLoop: false
BranchId: B{NN}"
})
TaskUpdate({ taskId: "REFACTOR-B{NN}", addBlockedBy: ["DESIGN-001"], owner: "refactorer" })

TaskCreate({
  subject: "VALIDATE-B{NN}",
  description: "PURPOSE: Validate branch B{NN} refactoring | Success: REFACTOR-{NNN} passes build, tests, and metric checks
TASK:
  - Load architecture baseline and REFACTOR-{NNN} success criteria
  - Validate build, tests, dependency metrics, and API compatibility
  - Compare against baseline, check for regressions
CONTEXT:
  - Session: <session-folder>
  - Branch: B{NN}
  - Upstream artifacts: architecture-baseline.json, branches/B{NN}/refactoring-detail.md
  - Shared memory: <session>/wisdom/.msg/meta.json (namespace: validator.B{NN})
EXPECTED: <session>/artifacts/branches/B{NN}/validation-results.json
CONSTRAINTS: Only validate this branch's changes
---
InnerLoop: false
BranchId: B{NN}"
})
TaskUpdate({ taskId: "VALIDATE-B{NN}", addBlockedBy: ["REFACTOR-B{NN}"], owner: "validator" })

TaskCreate({
  subject: "REVIEW-B{NN}",
  description: "PURPOSE: Review branch B{NN} refactoring code | Success: Code quality verified for REFACTOR-{NNN}
TASK:
  - Load modified files from refactorer.B{NN} namespace in .msg/meta.json
  - Review across 5 dimensions for this branch's changes only
  - Issue verdict: APPROVE, REVISE, or REJECT
CONTEXT:
  - Session: <session-folder>
  - Branch: B{NN}
  - Upstream artifacts: branches/B{NN}/refactoring-detail.md
  - Shared memory: <session>/wisdom/.msg/meta.json (namespace: reviewer.B{NN})
EXPECTED: <session>/artifacts/branches/B{NN}/review-report.md
CONSTRAINTS: Only review this branch's changes
---
InnerLoop: false
BranchId: B{NN}"
})
TaskUpdate({ taskId: "REVIEW-B{NN}", addBlockedBy: ["REFACTOR-B{NN}"], owner: "reviewer" })

7. Update session.json:

• branches: array of branch IDs (["B01", "B02", ...])
• fix_cycles: object keyed by branch ID, all initialized to 0

---

Phase 4: Validation

Verify task chain integrity:

Naming Rules Summary

If validation fails, fix the specific task and re-validate.

Monitor Pipeline

Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.

Constants

• SPAWN_MODE: background
• ONE_STEP_PER_INVOCATION: true
• FAST_ADVANCE_AWARE: true
• WORKER_AGENT: team-worker

Handler Router

handleCallback

Worker completed. Process and advance.

1. Parse message to identify role, task ID, and branch/pipeline label:

2. Mark task as completed: TaskUpdate({ taskId: "<task-id>", status: "completed" }) 3. Record completion in session state 4. CP-2.5 check (auto/fan-out mode only):

• If completed task is DESIGN-001 AND parallel_mode is auto or fan-out:
• Execute CP-2.5 Branch Creation from dispatch.md
• After branch creation, proceed to handleSpawnNext (spawns all REFACTOR-B* in parallel)
• STOP after spawning

5. Check stage checkpoints:

6. Proceed to handleSpawnNext

handleCheck

Read-only status report, then STOP.

Worker Progress (from message bus):

Before generating status output, read worker milestones:

const progressMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "progress", last: 50
})
const blockerMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "blocker", last: 10
})

// Aggregate latest milestone per task
const taskProgress = {}
for (const msg of (progressMsgs.result?.messages || [])) {
  const tid = msg.data?.task_id
  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
  }
}

Include in status output:

• Per-worker latest milestone (phase + progress_pct) next to task status
• Active blockers section (if any blockerMsgs found)

Output (single mode):

[coordinator] Pipeline Status
[coordinator] Progress: <done>/<total> (<pct>%)
[coordinator] Active: <workers with elapsed time>
[coordinator] Ready: <pending tasks with resolved deps>
[coordinator] Commands: 'resume' to advance | 'check' to refresh

Fan-out mode adds per-branch grouping. Independent mode adds per-pipeline grouping.

handleResume

1. Audit task list: Tasks stuck in "in_progress" -> reset to "pending" 2. For fan-out/independent: check each branch/pipeline independently 3. Proceed to handleSpawnNext

handleSpawnNext

Find ready tasks, spawn workers, STOP.

1. Collect: completedSubjects, inProgressSubjects, readySubjects 2. No ready + work in progress -> report waiting, STOP 3. No ready + nothing in progress -> handleComplete 4. Has ready -> for each: a. Check inner_loop: parse task description InnerLoop: field (NOT role.md default)

• InnerLoop: true AND same-role worker already active -> skip (worker picks up)
• InnerLoop: false OR no active same-role worker -> spawn new worker

b. TaskUpdate -> in_progress c. team_msg log -> task_unblocked d. Spawn team-worker (see SKILL.md Spawn Template):

      Agent({
        subagent_type: "team-worker",
        description: "Spawn <role> worker for <task-id>",
        team_name: "arch-opt",
        name: "<role>",
        run_in_background: true,
        prompt: `## Role Assignment
      role: <role>
      role_spec: ~  or <project>/.claude/skills/team-arch-opt/roles/<role>/role.md
      session: <session-folder>
      session_id: <session-id>
      team_name: arch-opt
      requirement: <task-description>
      inner_loop: <true|false>

      ## Progress Milestones
      session_id: <session-id>
      Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
      Report blockers immediately via team_msg type="blocker".
      Report completion via team_msg type="task_complete" after final SendMessage.

      Read role_spec file to load Phase 2-4 domain instructions.
      Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
      })

e. Add to active_workers 5. Parallel spawn rules by mode:

6. Update session, output summary, STOP

Review-Fix Cycle (CP-3)

Per-branch/pipeline scoping: Each branch/pipeline has its own independent fix cycle.

When both VALIDATE- and REVIEW- are completed for a branch/pipeline:

1. Read validation verdict from scoped meta.json namespace 2. Read review verdict from scoped meta.json namespace

Fix cycle tracking per branch in session.json fix_cycles:

• < 3: Create FIX task, increment cycle count
• >= 3: Escalate THIS branch to user. Other branches continue

handleComplete

Pipeline done. Generate report and completion action.

Completion check by mode:

1. For fan-out/independent: aggregate per-branch/pipeline results to <session>/artifacts/aggregate-results.json 2. If any tasks not completed, return to handleSpawnNext 3. If all completed -> transition to coordinator Phase 5

handleConsensus

Handle consensus_blocked signals from discuss rounds.

handleAdapt

Capability gap reported mid-pipeline.

1. Parse gap description 2. Check if existing role covers it -> redirect 3. Role count < 5 -> generate dynamic role-spec in <session>/role-specs/ 4. Create new task, spawn worker 5. Role count >= 5 -> merge or pause

Fast-Advance Reconciliation

On every coordinator wake: 1. Read team_msg entries with type="fast_advance" 2. Sync active_workers with spawned successors 3. No duplicate spawns

Coordinator

Orchestrate team-arch-opt: analyze -> dispatch -> spawn -> monitor -> report.

Identity

• Name: coordinator | Tag: [coordinator]
• Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results

Boundaries

MUST

• Use team-worker agent type for all worker spawns (NOT general-purpose)
• Follow Command Execution Protocol for dispatch and monitor commands
• Respect pipeline stage dependencies (blockedBy)
• Stop after spawning workers -- wait for callbacks
• Handle review-fix cycles with max 3 iterations
• Execute completion action in Phase 5

MUST NOT

• Implement domain logic (analyzing, refactoring, reviewing) -- workers handle this
• Spawn workers without creating tasks first
• Skip checkpoints when configured
• Force-advance pipeline past failed review/validation
• Modify source code directly -- delegate to refactorer worker

Command Execution Protocol

When coordinator needs to execute a specific phase: 1. Read commands/<command>.md 2. Follow the workflow defined in the command 3. Commands are inline execution guides, NOT separate agents 4. Execute synchronously, complete before proceeding

Entry Router

For callback/check/resume/consensus/adapt/complete: load @commands/monitor.md, execute handler, STOP.

Phase 0: Session Resume Check

1. Scan .workflow/.team/TAO-*/session.json for active/paused sessions 2. No sessions -> Phase 1 3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, kick first ready task) 4. Multiple -> AskUserQuestion for selection

Phase 1: Requirement Clarification

TEXT-LEVEL ONLY. No source code reading.

1. Parse task description from $ARGUMENTS 2. Parse parallel mode flags:

3. Identify architecture optimization target:

4. If target is unclear, AskUserQuestion for scope clarification 5. Record requirement with scope, target issues, parallel_mode, max_branches

Phase 2: Create Team + Initialize Session

1. Resolve workspace paths (MUST do first):

• project_root = result of Bash({ command: "pwd" })
• skill_root = <project_root>/.claude/skills/team-arch-opt

2. Generate session ID: TAO-<slug>-<date> 3. Create session folder structure 4. TeamCreate with team name arch-opt 5. Write session.json with parallel_mode, max_branches, branches, independent_targets, fix_cycles 6. Initialize meta.json via team_msg state_update:

   mcp__ccw-tools__team_msg({
     operation: "log", session_id: "<id>", from: "coordinator",
     type: "state_update", summary: "Session initialized",
     data: { pipeline_mode: "<mode>", pipeline_stages: ["analyzer","designer","refactorer","validator","reviewer"], team_name: "arch-opt" }
   })

7. Write session.json

Phase 3: Create Task Chain

Delegate to @commands/dispatch.md: 1. Read dependency graph and parallel mode from session.json 2. Topological sort tasks 3. Create tasks via TaskCreate, then set dependencies via TaskUpdate({ addBlockedBy }) 4. Update session.json with task count

Phase 4: Spawn-and-Stop

Delegate to @commands/monitor.md#handleSpawnNext: 1. Find ready tasks (pending + blockedBy resolved) 2. Spawn team-worker agents (see SKILL.md Spawn Template) 3. Output status summary 4. STOP

Phase 5: Report + Completion Action

1. Load session state -> count completed tasks, calculate duration 2. List deliverables:

3. Include discussion summaries if discuss rounds were used 4. Output pipeline summary: task count, duration, improvement metrics

5. Execute completion action per session.completion_action:

• interactive -> AskUserQuestion (Archive/Keep/Export)
• auto_archive -> Archive & Clean (status=completed, TeamDelete)
• auto_keep -> Keep Active (status=paused)

Error Handling

Refactoring Designer

Analyze architecture reports and baseline metrics to design a prioritized refactoring plan with concrete strategies, expected structural improvements, and risk assessments.

Phase 2: Analysis Loading

1. Extract session path from task description 2. Read architecture report -- extract ranked issue list with severities and categories 3. Read architecture baseline -- extract current structural metrics 4. Load .msg/meta.json for analyzer findings (project_type, scope) 5. Assess overall refactoring complexity:

Phase 3: Strategy Formulation

For each architecture issue, select refactoring approach by type:

Prioritize refactorings by impact/effort ratio:

If complexity is High, invoke discuss CLI tool (DISCUSS-REFACTOR round) to evaluate trade-offs between competing strategies before finalizing the plan.

Define measurable success criteria per refactoring (target metric improvement or structural change).

Phase 4: Plan Output

1. Write refactoring plan to <session>/artifacts/refactoring-plan.md:

Each refactoring MUST have a unique REFACTOR-ID and self-contained detail block:

   ### REFACTOR-001: <title>
   - Priority: P0
   - Target issue: <issue from report>
   - Issue type: <CYCLE|COUPLING|GOD_CLASS|DUPLICATION|LAYER_VIOLATION|DEAD_CODE|API_BLOAT>
   - Target files: <file-list>
   - Strategy: <selected approach>
   - Expected improvement: <metric> by <description>
   - Risk level: <Low/Medium/High>
   - Success criteria: <specific structural change to verify>
   - Implementation guidance:
     1. <step 1>
     2. <step 2>
     3. <step 3>

   ### REFACTOR-002: <title>
   ...

Requirements:

• Each REFACTOR-ID is sequentially numbered (REFACTOR-001, REFACTOR-002, ...)
• Each refactoring must be non-overlapping in target files (no two REFACTOR-IDs modify the same file unless explicitly noted with conflict resolution)
• Implementation guidance must be self-contained -- a branch refactorer should be able to work from a single REFACTOR block without reading others

2. Update <session>/wisdom/.msg/meta.json under designer namespace:

• Read existing -> merge -> write back:

   {
     "designer": {
       "complexity": "<Low|Medium|High>",
       "refactoring_count": 4,
       "priorities": ["P0", "P0", "P1", "P2"],
       "discuss_used": false,
       "refactorings": [
         {
           "id": "REFACTOR-001",
           "title": "<title>",
           "issue_type": "<CYCLE|COUPLING|...>",
           "priority": "P0",
           "target_files": ["src/a.ts", "src/b.ts"],
           "expected_improvement": "<metric> by <description>",
           "success_criteria": "<threshold>"
         }
       ]
     }
   }

3. If DISCUSS-REFACTOR was triggered, record discussion summary in <session>/discussions/DISCUSS-REFACTOR.md

Code Refactorer

inner_loop: dynamic — Dispatch sets per-task: true for single mode (one REFACTOR task with iterative fix cycles), false for fan-out/independent modes (REFACTOR-B01..N run as separate parallel workers). When false, each branch gets its own worker.

Implement architecture refactoring changes following the design plan. For FIX tasks, apply targeted corrections based on review/validation feedback.

Modes

Phase 2: Plan & Context Loading

1. Extract session path and task mode (REFACTOR or FIX) from task description 2. Detect branch/pipeline context from task description:

3. Load refactoring context by mode:

• Single mode (no branch): Read <session>/artifacts/refactoring-plan.md -- extract ALL priority-ordered changes
• Fan-out branch: Read <session>/artifacts/branches/B{NN}/refactoring-detail.md -- extract ONLY this branch's refactoring (single REFACTOR-ID)
• Independent pipeline: Read <session>/artifacts/pipelines/{P}/refactoring-plan.md -- extract this pipeline's plan

4. For FIX: parse review/validation feedback for specific issues to address 5. Use explore CLI tool to load implementation context for target files 6. For inner loop (single mode only): load context_accumulator from prior REFACTOR/FIX tasks

Meta.json namespace:

• Single: write to refactorer namespace
• Fan-out: write to refactorer.B{NN} namespace
• Independent: write to refactorer.{P} namespace

Phase 3: Code Implementation

Implementation backend selection:

For REFACTOR tasks:

• Single mode: Apply refactorings in plan priority order (P0 first, then P1, etc.)
• Fan-out branch: Apply ONLY this branch's single refactoring (from refactoring-detail.md)
• Independent pipeline: Apply this pipeline's refactorings in priority order
• Follow implementation guidance from plan (target files, patterns)
• Preserve existing behavior -- refactoring must not change functionality
• Update ALL import references when moving/renaming modules
• Update ALL test files that reference moved/renamed symbols

For FIX tasks:

• Read specific issues from review/validation feedback
• Apply targeted corrections to flagged code locations
• Verify the fix addresses the exact concern raised

General rules:

• Make minimal, focused changes per refactoring
• Add comments only where refactoring logic is non-obvious
• Preserve existing code style and conventions
• Verify no dangling imports after module moves

Phase 4: Self-Validation

If validation fails, attempt auto-fix (max 2 attempts) before reporting error.

Append to context_accumulator for next REFACTOR/FIX task (single/inner-loop mode only):

• Files modified, refactorings applied, validation results
• Any discovered patterns or caveats for subsequent iterations

Branch output paths:

• Single: write artifacts to <session>/artifacts/
• Fan-out: write artifacts to <session>/artifacts/branches/B{NN}/
• Independent: write artifacts to <session>/artifacts/pipelines/{P}/

Architecture Reviewer

Review refactoring code changes for correctness, pattern consistency, completeness, migration safety, and adherence to best practices. Provide structured verdicts with actionable feedback.

Phase 2: Context Loading

1. Extract session path from task description 2. Detect branch/pipeline context from task description:

3. Load refactoring context by mode:

• Single: Read <session>/artifacts/refactoring-plan.md
• Fan-out branch: Read <session>/artifacts/branches/B{NN}/refactoring-detail.md
• Independent: Read <session>/artifacts/pipelines/{P}/refactoring-plan.md

4. Load .msg/meta.json for scoped refactorer namespace:

• Single: refactorer namespace
• Fan-out: refactorer.B{NN} namespace
• Independent: refactorer.{P} namespace

5. Identify changed files from refactorer context -- read ONLY files modified by this branch/pipeline 6. If validation results available, read from scoped path:

• Single: <session>/artifacts/validation-results.json
• Fan-out: <session>/artifacts/branches/B{NN}/validation-results.json
• Independent: <session>/artifacts/pipelines/{P}/validation-results.json

Phase 3: Multi-Dimension Review

Analyze refactoring changes across five dimensions:

Per-dimension review process:

• Scan modified files for patterns matching each dimension
• Record findings with severity (Critical / High / Medium / Low)
• Include specific file:line references and suggested fixes

Correctness checks:

• Verify moved code preserves original behavior (no logic changes mixed with structural changes)
• Check all import/require statements updated to new paths
• Verify no orphaned files left behind after moves

Pattern consistency checks:

• New module names follow existing naming conventions
• Extracted interfaces/classes use consistent patterns with existing codebase
• File organization matches project conventions (e.g., index files, barrel exports)

Completeness checks:

• All test files updated for moved/renamed modules
• Configuration files updated if needed (e.g., path aliases, build configs)
• Type definitions updated for extracted interfaces

Migration safety checks:

• Public API surface unchanged (same exports available to consumers)
• No circular dependencies introduced by the refactoring
• Re-exports in place if module paths changed for backward compatibility

Best practices checks:

• Extracted modules have clear single responsibility
• Dependency direction follows layer conventions (dependencies flow inward)
• Appropriate abstraction level (not over-engineered, not under-abstracted)

If any Critical findings detected, invoke discuss CLI tool (DISCUSS-REVIEW round) to validate the assessment before issuing verdict.

Phase 4: Verdict & Feedback

Classify overall verdict based on findings:

1. Write review report to scoped output path:

• Single: <session>/artifacts/review-report.md
• Fan-out: <session>/artifacts/branches/B{NN}/review-report.md
• Independent: <session>/artifacts/pipelines/{P}/review-report.md
• Content: Per-dimension findings with severity, file:line, description; Overall verdict with rationale; Specific fix instructions for REVISE/REJECT verdicts

2. Update <session>/wisdom/.msg/meta.json under scoped namespace:

• Single: merge { "reviewer": { verdict, finding_count, critical_count, dimensions_reviewed } }
• Fan-out: merge { "reviewer.B{NN}": { verdict, finding_count, critical_count, dimensions_reviewed } }
• Independent: merge { "reviewer.{P}": { verdict, finding_count, critical_count, dimensions_reviewed } }

3. If DISCUSS-REVIEW was triggered, record discussion summary in <session>/discussions/DISCUSS-REVIEW.md (or DISCUSS-REVIEW-B{NN}.md for branch-scoped discussions)

Architecture Validator

Validate refactoring changes by running build checks, test suites, dependency metric comparisons, and API compatibility verification. Ensure refactoring improves architecture without breaking functionality.

Phase 2: Environment & Baseline Loading

1. Extract session path from task description 2. Detect branch/pipeline context from task description:

3. Load architecture baseline:

• Single / Fan-out: Read <session>/artifacts/architecture-baseline.json (shared baseline)
• Independent: Read <session>/artifacts/pipelines/{P}/architecture-baseline.json

4. Load refactoring context:

• Single: Read <session>/artifacts/refactoring-plan.md -- all success criteria
• Fan-out branch: Read <session>/artifacts/branches/B{NN}/refactoring-detail.md -- only this branch's criteria
• Independent: Read <session>/artifacts/pipelines/{P}/refactoring-plan.md

5. Load .msg/meta.json for project type and refactoring scope 6. Detect available validation tools from project:

7. Get changed files scope from .msg/meta.json:

• Single: refactorer namespace
• Fan-out: refactorer.B{NN} namespace
• Independent: refactorer.{P} namespace

Phase 3: Validation Execution

Run validations across four dimensions:

Build validation:

• Compile/type-check the project -- zero new errors allowed
• Verify all moved/renamed files are correctly referenced
• Check for missing imports or unresolved modules

Test validation:

• Run existing test suite -- all previously passing tests must still pass
• Identify any tests that need updating due to module moves (update, don't skip)
• Check for test file imports that reference old paths

Dependency metric validation:

• Recalculate architecture metrics post-refactoring
• Compare coupling scores against baseline (must improve or stay neutral)
• Verify no new circular dependencies introduced
• Check cohesion metrics for affected modules

API compatibility validation:

• Verify public API signatures are preserved (exported function/class/type names)
• Check for dangling references (imports pointing to removed/moved files)
• Verify no new dead exports introduced by the refactoring
• Check that re-exports maintain backward compatibility where needed

Branch-scoped validation (fan-out mode):

• Only validate metrics relevant to this branch's refactoring (from refactoring-detail.md)
• Still check for regressions across all metrics (not just branch-specific ones)

Phase 4: Result Analysis

Compare against baseline and plan criteria:

1. Write validation results to output path:

• Single: <session>/artifacts/validation-results.json
• Fan-out: <session>/artifacts/branches/B{NN}/validation-results.json
• Independent: <session>/artifacts/pipelines/{P}/validation-results.json
• Content: Per-dimension: name, baseline value, current value, improvement/regression, verdict; Overall verdict: PASS / WARN / FAIL; Failure details (if any)

2. Update <session>/wisdom/.msg/meta.json under scoped namespace:

• Single: merge { "validator": { verdict, improvements, regressions, build_pass, test_pass } }
• Fan-out: merge { "validator.B{NN}": { verdict, improvements, regressions, build_pass, test_pass } }
• Independent: merge { "validator.{P}": { verdict, improvements, regressions, build_pass, test_pass } }

3. If verdict is FAIL, include detailed feedback in message for FIX task creation:

• Which validations failed, specific errors, suggested investigation areas

Pipeline Definitions — team-arch-opt

Available Pipelines

Single Mode (Linear)

ANALYZE-001 → DESIGN-001 → REFACTOR-001 → VALIDATE-001 + REVIEW-001
[analyzer]    [designer]    [refactorer]    [validator]    [reviewer]
                                ^                |
                                +<-- FIX-001 ----+
                                          (max 3 iterations)

Fan-out Mode (Shared Stages + Parallel Branches)

ANALYZE-001 → DESIGN-001 --+→ REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
[analyzer]    [designer]    |  [refactorer]    [validator]    [reviewer]
                            +→ REFACTOR-B02 → VALIDATE-B02 + REVIEW-B02
                            +→ REFACTOR-B0N → VALIDATE-B0N + REVIEW-B0N
                                                           |
                                                      AGGREGATE → Phase 5

Branch tasks created at CP-2.5 after DESIGN-001 completes.

Independent Mode (M Complete Pipelines)

Pipeline A: ANALYZE-A01 → DESIGN-A01 → REFACTOR-A01 → VALIDATE-A01 + REVIEW-A01
Pipeline B: ANALYZE-B01 → DESIGN-B01 → REFACTOR-B01 → VALIDATE-B01 + REVIEW-B01
...                                                               |
                                                             AGGREGATE → Phase 5

Auto Mode

Auto-detects based on refactoring count at CP-2.5:

• count <= 2 → switch to single mode
• count >= 3 → switch to fan-out mode

Task Metadata Registry

Single Mode

Fan-out Mode (Branch Tasks at CP-2.5)

Independent Mode

Checkpoints

Task Naming Rules

Parallel Mode Invocation

Skill(skill="team-arch-opt", args="<task-description>")                           # auto mode
Skill(skill="team-arch-opt", args="--parallel-mode=fan-out <task-description>")   # force fan-out
Skill(skill="team-arch-opt", args='--parallel-mode=independent "target1" "target2"')  # independent
Skill(skill="team-arch-opt", args="--max-branches=3 <task-description>")           # limit branches