Refactor code structure for improved readability and maintainability

Author: catlog22

.claude/agents/team-worker.md

@@ -237,15 +237,15 @@ After Phase 4 completes, determine Phase 5 variant:
 ### Phase 5-L: Loop Completion (when inner_loop=true AND more same-prefix tasks pending)
 
 1. **TaskUpdate**: Mark current task `completed`
-2. **Message Bus**: Log completion
+2. **Message Bus**: Log completion with verification evidence
    ```
    mcp__ccw-tools__team_msg(
      operation="log",
      team=<session_id>,
      from=<role>,
      to="coordinator",
      type=<message_types.success>,
-     summary="[<role>] <task-id> complete. <brief-summary>",
+     summary="[<role>] <task-id> complete. <brief-summary>. Verified: <verification_method>",
      ref=<artifact-path>
    )
    ```
@@ -283,7 +283,7 @@ After Phase 4 completes, determine Phase 5 variant:
 | Condition | Action |
 |-----------|--------|
 | Same-prefix successor (inner loop role) | Do NOT spawn — main agent handles via inner loop |
-| 1 ready task, simple linear successor, different prefix | Spawn directly via `Task(run_in_background: true)` |
+| 1 ready task, simple linear successor, different prefix | Spawn directly via `Task(run_in_background: true)` + log `fast_advance` to message bus |
 | Multiple ready tasks (parallel window) | SendMessage to coordinator (needs orchestration) |
 | No ready tasks + others running | SendMessage to coordinator (status update) |
 | No ready tasks + nothing running | SendMessage to coordinator (pipeline may be complete) |
@@ -311,6 +311,23 @@ inner_loop: <true|false based on successor role>`
 })
 ```
 
+### Fast-Advance Notification
+
+After spawning a successor via fast-advance, MUST log to message bus:
+
+```
+mcp__ccw-tools__team_msg(
+  operation="log",
+  team=<session_id>,
+  from=<role>,
+  to="coordinator",
+  type="fast_advance",
+  summary="[<role>] fast-advanced <completed-task-id> → spawned <successor-role> for <successor-task-id>"
+)
+```
+
+This is a passive log entry (NOT a SendMessage). Coordinator reads it on next callback to reconcile `active_workers`.
+
 ### SendMessage Format
 
 ```
@@ -320,8 +337,10 @@ SendMessage(team_name=<team_name>, recipient="coordinator", message="[<role>] <f
 **Final report contents**:
 - Tasks completed (count + list)
 - Artifacts produced (paths)
+- Files modified (paths + before/after evidence from Phase 4 verification)
 - Discuss results (verdicts + ratings)
 - Key decisions (from context_accumulator)
+- Verification summary (methods used, pass/fail status)
 - Any warnings or issues
 
 ---

.claude/skills/team-coordinate-v2/roles/coordinator/commands/analyze-task.md

@@ -90,16 +90,26 @@ Apply merging rules to reduce role count (cap at 5).
 
 ### Step 6: Role-Spec Metadata Assignment
 
-For each role, determine frontmatter fields:
+For each role, determine frontmatter and generation hints:
 
 | Field | Derivation |
 |-------|------------|
 | `prefix` | From capability prefix (e.g., RESEARCH, DRAFT, IMPL) |
 | `inner_loop` | `true` if role has 2+ serial same-prefix tasks |
-| `subagents` | Inferred from responsibility type: orchestration -> [explore], code-gen (docs) -> [explore], validation -> [] |
+| `subagents` | Suggested, not mandatory — coordinator may adjust based on task needs |
+| `pattern_hint` | Reference pattern name from role-spec-template (research/document/code/analysis/validation) — guides coordinator's Phase 2-4 composition, NOT a rigid template selector |
+| `output_type` | `artifact` (new files in session/artifacts/) / `codebase` (modify existing project files) / `mixed` (both) — determines verification strategy in Behavioral Traits |
 | `message_types.success` | `<prefix>_complete` |
 | `message_types.error` | `error` |
 
+**output_type derivation**:
+
+| Task Signal | output_type | Example |
+|-------------|-------------|---------|
+| "write report", "analyze", "research" | `artifact` | New analysis-report.md in session |
+| "update docs", "modify code", "fix bug" | `codebase` | Modify existing project files |
+| "implement feature + write summary" | `mixed` | Code changes + implementation summary |
+
 ## Phase 4: Output
 
 Write `<session-folder>/task-analysis.json`:
@@ -132,6 +142,8 @@ Write `<session-folder>/task-analysis.json`:
       "inner_loop": false,
       "role_spec_metadata": {
         "subagents": ["explore"],
+        "pattern_hint": "research",
+        "output_type": "artifact",
         "message_types": {
           "success": "research_complete",
           "error": "error"

.claude/skills/team-coordinate-v2/roles/coordinator/commands/monitor.md

@@ -60,10 +60,12 @@ Receive callback from [<role>]
       +- None completed -> STOP
 ```
 
-**Fast-advance note**: A worker may have already spawned its successor via fast-advance. When processing a callback:
-1. Check if the expected next task is already `in_progress` (fast-advanced)
-2. If yes -> skip spawning that task, update active_workers to include the fast-advanced worker
-3. If no -> normal handleSpawnNext
+**Fast-advance reconciliation**: A worker may have already spawned its successor via fast-advance. When processing any callback or resume:
+1. Read recent `fast_advance` messages from team_msg (type="fast_advance")
+2. For each fast_advance message: add the spawned successor to `active_workers` if not already present
+3. Check if the expected next task is already `in_progress` (fast-advanced)
+4. If yes -> skip spawning that task (already running)
+5. If no -> normal handleSpawnNext
 
 ---
 
@@ -262,6 +264,13 @@ handleCallback / handleResume detects:
       4. -> handleSpawnNext (will re-spawn the task normally)
 ```
 
+### Fast-Advance State Sync
+
+On every coordinator wake (handleCallback, handleResume, handleCheck):
+1. Read team_msg entries with `type="fast_advance"` since last coordinator wake
+2. For each entry: sync `active_workers` with the spawned successor
+3. This ensures coordinator's state reflects fast-advance decisions even before the successor's callback arrives
+
 ### Consensus-Blocked Handling
 
 ```

.claude/skills/team-coordinate-v2/roles/coordinator/role.md

@@ -182,13 +182,15 @@ Regardless of complexity score or role count, coordinator MUST:
 
 4. **Call TeamCreate** with team name derived from session ID
 
-5. **Read `specs/role-spec-template.md`** + task-analysis.json
+5. **Read `specs/role-spec-template.md`** for Behavioral Traits + Reference Patterns
 
 6. **For each role in task-analysis.json#roles**:
-   - Fill role-spec template with:
-     - YAML frontmatter: role, prefix, inner_loop, subagents, message_types
-     - Phase 2-4 content from responsibility type reference sections in template
-     - Task-specific instructions from task description
+   - Fill YAML frontmatter: role, prefix, inner_loop, subagents, message_types
+   - **Compose Phase 2-4 content** (NOT copy from template):
+     - Phase 2: Derive input sources and context loading steps from **task description + upstream dependencies**
+     - Phase 3: Describe **execution goal** (WHAT to achieve) from task description — do NOT prescribe specific subagent or tool
+     - Phase 4: Combine **Behavioral Traits** (from template) + **output_type** (from task analysis) to compose verification steps
+     - Reference Patterns may guide phase structure, but task description determines specific content
    - Write generated role-spec to `<session>/role-specs/<role-name>.md`
 
 7. **Register roles** in team-session.json#roles (with `role_spec` path instead of `role_file`)