Team Ultra Analyze

Team Ultra Analyze

Deep collaborative analysis: explore -> analyze -> discuss -> synthesize. Supports Quick/Standard/Deep pipeline modes with configurable depth (N parallel agents). Discussion loops enable user-guided progressive understanding.

Architecture

Skill(skill="team-ultra-analyze", args="<topic>")
                    |
         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
                 [team-worker agents, each loads roles/<role>/role.md]

Pipeline (Standard mode):
  [EXPLORE-1..N](parallel) -> [ANALYZE-1..N](parallel) -> DISCUSS-001 -> SYNTH-001

Pipeline (Deep mode):
  [EXPLORE-1..N] -> [ANALYZE-1..N] -> DISCUSS-001 -> ANALYZE-fix -> DISCUSS-002 -> ... -> SYNTH-001

Pipeline (Quick mode):
  EXPLORE-001 -> ANALYZE-001 -> SYNTH-001

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: UAN
• Session path: .workflow/.team/UAN-<slug>-<date>/
• Team name: ultra-analyze
• 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: "ultra-analyze",
  name: "<agent-name>",
  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: ultra-analyze
requirement: <topic-description>
agent_name: <agent-name>
inner_loop: 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, owner=<agent-name>) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

User Commands

Session Directory

.workflow/.team/UAN-{slug}-{YYYY-MM-DD}/
+-- .msg/messages.jsonl          # Message bus log
+-- .msg/meta.json               # Session metadata + cross-role state
+-- discussion.md                # Understanding evolution and discussion timeline
+-- explorations/                # Explorer output
|   +-- exploration-001.json
|   +-- exploration-002.json
+-- analyses/                    # Analyst output
|   +-- analysis-001.json
|   +-- analysis-002.json
+-- discussions/                 # Discussant output
|   +-- discussion-round-001.json
+-- conclusions.json             # Synthesizer output
+-- wisdom/                      # Cross-task knowledge
|   +-- learnings.md
|   +-- decisions.md
|   +-- conventions.md
|   +-- issues.md

Completion Action

When pipeline completes, coordinator presents:

AskUserQuestion({
  questions: [{
    question: "Ultra-Analyze pipeline complete. What would you like to do?",
    header: "Completion",
    multiSelect: false,
    options: [
      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
      { label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
      { label: "Export Results", description: "Export deliverables to a specified location, then clean" }
    ]
  }]
})

Specs Reference

• specs/team-config.json — Team configuration and pipeline settings

Error Handling

Deep Analyst

Perform deep multi-perspective analysis on exploration results via CLI tools. Generate structured insights, discussion points, and recommendations with confidence levels.

Phase 2: Context Loading

1. Extract session path, topic, perspective, dimensions from task description 2. Detect direction-fix mode: type:\s*direction-fix with adjusted_focus:\s*(.+) 3. Load corresponding exploration results:

4. Select CLI tool by perspective:

Phase 3: Deep Analysis via CLI

Build analysis prompt with exploration context:

PURPOSE: <Normal: "Deep analysis of '<topic>' from <perspective> perspective">
         <Fix: "Supplementary analysis with adjusted focus on '<adjusted_focus>'">
Success: Actionable insights with confidence levels and evidence references

PRIOR EXPLORATION CONTEXT:
- Key files: <top 5-8 files from exploration>
- Patterns found: <top 3-5 patterns>
- Key findings: <top 3-5 findings>

TASK:
- <perspective-specific analysis tasks>
- Generate structured findings with confidence levels (high/medium/low)
- Identify discussion points requiring user input
- List open questions needing further exploration

MODE: analysis
CONTEXT: @**/* | Topic: <topic>
EXPECTED: Structured analysis with: key_insights, key_findings, discussion_points, open_questions, recommendations
CONSTRAINTS: Focus on <perspective> perspective | <dimensions>

Execute: ccw cli -p "<prompt>" --tool <cli-tool> --mode analysis --rule <rule>

Tech Profile Scan

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

1. Check analysis findings → signals (sql_detected, auth_detected, ml_detected, api_surface) 2. Check risk areas → signals (perf_sensitive, injection_risk, legacy_patterns) 3. Include tech_profile in Phase 5 state_update data

Phase 4: Result Aggregation

Write analysis output to <session>/analyses/analysis-<num>.json:

{
  "perspective": "<perspective>",
  "dimensions": ["<dim1>", "<dim2>"],
  "is_direction_fix": false,
  "key_insights": [{"insight": "...", "confidence": "high", "evidence": "file:line"}],
  "key_findings": [{"finding": "...", "file_ref": "...", "impact": "..."}],
  "discussion_points": ["..."],
  "open_questions": ["..."],
  "recommendations": [{"action": "...", "rationale": "...", "priority": "high"}],
  "_metadata": {"cli_tool": "...", "cli_rule": "...", "perspective": "...", "timestamp": "..."}
}

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

• Read existing -> merge { "analyst": { perspective, insight_count, finding_count, is_direction_fix } } -> write back

Analyze Task

Parse topic -> detect pipeline mode and perspectives -> output analysis config.

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

Signal Detection

Pipeline Mode Detection

Parse --mode from arguments first. If not specified, auto-detect from topic description:

Dimension Detection

Scan topic keywords to select analysis perspectives:

Depth = number of selected perspectives. Quick mode always uses depth=1.

Pipeline Mode Rules

Output

Write analysis config to coordinator state (not a file), to be used by dispatch.md:

{
  "pipeline_mode": "<quick|standard|deep>",
  "depth": <number>,
  "perspectives": ["<perspective1>", "<perspective2>"],
  "topic": "<original topic>",
  "dimensions": ["<dim1>", "<dim2>"]
}

Complexity Scoring

Results: 1-3 Quick, 4-6 Standard, 7+ Deep (if not explicitly set)

Discussion Loop Configuration

Command: Dispatch

Create the analysis task chain with correct dependencies and structured task descriptions. Supports Quick, Standard, and Deep pipeline modes.

Phase 2: Context Loading

1. Load topic, pipeline mode, and selected perspectives from coordinator state 2. Load pipeline stage definitions from SKILL.md Task Metadata Registry 3. Determine depth = number of selected perspectives (Quick: always 1)

Phase 3: Task Chain Creation

Task Description Template

Every task description uses structured format:

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>
  - Topic: <analysis-topic>
  - Perspective: <perspective or 'all'>
  - Upstream artifacts: <artifact-1>, <artifact-2>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <deliverable path> + <quality criteria>
CONSTRAINTS: <scope limits, focus areas>
---
InnerLoop: false"
})
TaskUpdate({ taskId: "<TASK-ID>", addBlockedBy: [<dependency-list>], owner: "<role>" })

Mode Router

---

Quick Mode Task Chain

EXPLORE-001 (explorer):

TaskCreate({
  subject: "EXPLORE-001",
  description: "PURPOSE: Explore codebase structure for analysis topic | Success: Key files, patterns, and findings collected
TASK:
  - Detect project structure and relevant modules
  - Search for code related to analysis topic
  - Collect file references, patterns, and key findings
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Perspective: general
  - Dimensions: <dimensions>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/explorations/exploration-001.json | Structured exploration with files and findings
CONSTRAINTS: Focus on <topic> scope
---
InnerLoop: false"
})
TaskUpdate({ taskId: "EXPLORE-001", owner: "explorer" })

ANALYZE-001 (analyst):

TaskCreate({
  subject: "ANALYZE-001",
  description: "PURPOSE: Deep analysis of topic from technical perspective | Success: Actionable insights with confidence levels
TASK:
  - Load exploration results and build analysis context
  - Analyze from technical perspective across selected dimensions
  - Generate insights, findings, discussion points, recommendations
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Perspective: technical
  - Dimensions: <dimensions>
  - Upstream artifacts: explorations/exploration-001.json
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/analyses/analysis-001.json | Structured analysis with evidence
CONSTRAINTS: Focus on technical perspective | <dimensions>
---
InnerLoop: false"
})
TaskUpdate({ taskId: "ANALYZE-001", addBlockedBy: ["EXPLORE-001"], owner: "analyst" })

SYNTH-001 (synthesizer):

TaskCreate({
  subject: "SYNTH-001",
  description: "PURPOSE: Integrate analysis into final conclusions | Success: Executive summary with recommendations
TASK:
  - Load all exploration, analysis, and discussion artifacts
  - Extract themes, consolidate evidence, prioritize recommendations
  - Write conclusions and update discussion.md
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Upstream artifacts: explorations/*.json, analyses/*.json
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/conclusions.json + discussion.md update | Final conclusions with confidence levels
CONSTRAINTS: Pure integration, no new exploration
---
InnerLoop: false"
})
TaskUpdate({ taskId: "SYNTH-001", addBlockedBy: ["ANALYZE-001"], owner: "synthesizer" })

---

Standard Mode Task Chain

Create tasks in dependency order with parallel exploration and analysis windows:

EXPLORE-001..N (explorer, parallel): One per perspective. Each receives unique agent name (explorer-1, explorer-2, ...) for task discovery matching.

// For each perspective[i]:
TaskCreate({
  subject: "EXPLORE-<NNN>",
  description: "PURPOSE: Explore codebase from <perspective> angle | Success: Perspective-specific files and patterns collected
TASK:
  - Search codebase from <perspective> perspective
  - Collect files, patterns, findings relevant to this angle
  - Generate questions for downstream analysis
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Perspective: <perspective>
  - Dimensions: <dimensions>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/explorations/exploration-<NNN>.json
CONSTRAINTS: Focus on <perspective> angle
---
InnerLoop: false"
})
TaskUpdate({ taskId: "EXPLORE-<NNN>", owner: "explorer-<i+1>" })

ANALYZE-001..N (analyst, parallel): One per perspective. Each blocked by its corresponding EXPLORE-N.

TaskCreate({
  subject: "ANALYZE-<NNN>",
  description: "PURPOSE: Deep analysis from <perspective> perspective | Success: Insights with confidence and evidence
TASK:
  - Load exploration-<NNN> results
  - Analyze from <perspective> perspective
  - Generate insights, discussion points, open questions
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Perspective: <perspective>
  - Dimensions: <dimensions>
  - Upstream artifacts: explorations/exploration-<NNN>.json
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/analyses/analysis-<NNN>.json
CONSTRAINTS: <perspective> perspective | <dimensions>
---
InnerLoop: false"
})
TaskUpdate({ taskId: "ANALYZE-<NNN>", addBlockedBy: ["EXPLORE-<NNN>"], owner: "analyst-<i+1>" })

DISCUSS-001 (discussant): Blocked by all ANALYZE tasks.

TaskCreate({
  subject: "DISCUSS-001",
  description: "PURPOSE: Process analysis results into discussion summary | Success: Convergent themes and discussion points identified
TASK:
  - Aggregate all analysis results across perspectives
  - Identify convergent themes and conflicting views
  - Generate top discussion points and open questions
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Round: 1
  - Type: initial
  - Upstream artifacts: analyses/*.json
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/discussions/discussion-round-001.json + discussion.md update
CONSTRAINTS: Aggregate only, no new exploration
---
InnerLoop: false"
})
TaskUpdate({ taskId: "DISCUSS-001", addBlockedBy: ["ANALYZE-001", ..., "ANALYZE-<N>"], owner: "discussant" })

SYNTH-001 (synthesizer): Blocked by DISCUSS-001.

TaskCreate({
  subject: "SYNTH-001",
  description: "PURPOSE: Cross-perspective integration into final conclusions | Success: Executive summary with prioritized recommendations
...same as Quick mode SYNTH-001 but blocked by DISCUSS-001..."
})
TaskUpdate({ taskId: "SYNTH-001", addBlockedBy: ["DISCUSS-001"], owner: "synthesizer" })

---

Deep Mode Task Chain

Same as Standard mode, but omit SYNTH-001. It will be created dynamically after the discussion loop completes, blocked by the last DISCUSS-N task.

---

Discussion Loop Task Creation

Dynamic tasks created during discussion loop:

DISCUSS-N (subsequent rounds):

TaskCreate({
  subject: "DISCUSS-<NNN>",
  description: "PURPOSE: Process discussion round <N> | Success: Updated understanding with user feedback integrated
TASK:
  - Process user feedback: <feedback>
  - Execute <type> discussion strategy
  - Update discussion timeline
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Round: <N>
  - Type: <deepen|direction-adjusted|specific-questions>
  - User feedback: <feedback>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/discussions/discussion-round-<NNN>.json
---
InnerLoop: false"
})
TaskUpdate({ taskId: "DISCUSS-<NNN>", owner: "discussant" })

ANALYZE-fix-N (direction adjustment):

TaskCreate({
  subject: "ANALYZE-fix-<N>",
  description: "PURPOSE: Supplementary analysis with adjusted focus | Success: New insights from adjusted direction
TASK:
  - Re-analyze from adjusted perspective: <adjusted_focus>
  - Build on previous exploration findings
  - Generate updated discussion points
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Type: direction-fix
  - Adjusted focus: <adjusted_focus>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/analyses/analysis-fix-<N>.json
---
InnerLoop: false"
})
TaskUpdate({ taskId: "ANALYZE-fix-<N>", owner: "analyst" })

Phase 4: Validation

Verify task chain integrity:

Command: Monitor

Handle all coordinator monitoring events: worker callbacks, status checks, pipeline advancement, discussion loop control, and completion.

Constants

Phase 2: Context Loading

1. Load session.json for current state, pipeline_mode, discussion_round 2. Run TaskList() to get current task statuses 3. Identify trigger event type from Entry Router 4. Compute max discussion rounds from pipeline mode:

MAX_ROUNDS = pipeline_mode === 'deep' ? 5
           : pipeline_mode === 'standard' ? 1
           : 0

Phase 3: Event Handlers

handleCallback

Triggered when a worker sends completion message (via SendMessage callback).

1. Parse message to identify role, then resolve completed tasks:

Role detection (from message tag at start of body):

Task ID resolution (do NOT parse from message — use TaskList):

• Call TaskList() and find tasks matching the detected role's prefix
• Tasks with status completed that were not previously tracked = newly completed tasks
• This is reliable even when a worker reports multiple tasks (inner_loop) or when message format varies

2. Verify task completion (worker already marks completed in Phase 5):

TaskGet({ taskId: "<task-id>" })
// If still "in_progress" (worker failed to mark) → fallback:
TaskUpdate({ taskId: "<task-id>", status: "completed" })

3. Record completion in session state via team_msg

4. Role-specific post-completion logic:

5. Discussion Feedback Gate (when discussant completes):

When a DISCUSS-* task completes, the coordinator collects user feedback BEFORE spawning the next task. This replaces any while-loop pattern.

// Read current discussion_round from session state
discussion_round = session.discussion_round || 0
discussion_round++

// Update session state
Update session.json: discussion_round = discussion_round

// Check if discussion loop applies
IF pipeline_mode === 'quick':
    // No discussion in quick mode -- proceed to handleSpawnNext (SYNTH)
    -> handleSpawnNext

ELSE IF discussion_round >= MAX_ROUNDS:
    // Reached max rounds -- force proceed to synthesis
    Log: "Max discussion rounds reached, proceeding to synthesis"
    IF no SYNTH-001 task exists:
        Create SYNTH-001 task blocked by last DISCUSS task
    -> handleSpawnNext

ELSE:
    // Collect user feedback
    AskUserQuestion({
      questions: [{
        question: "Discussion round <N> complete. What next?",
        header: "Discussion Feedback",
        multiSelect: false,
        options: [
          { label: "Continue deeper", description: "Current direction is good, go deeper" },
          { label: "Adjust direction", description: "Shift analysis focus" },
          { label: "Done", description: "Sufficient depth, proceed to synthesis" }
        ]
      }]
    })

6. Feedback handling (still inside handleCallback, after AskUserQuestion returns):

Dynamic task creation templates:

DISCUSS-N (subsequent round):

TaskCreate({
  subject: "DISCUSS-<NNN>",
  description: "PURPOSE: Process discussion round <N> | Success: Updated understanding
TASK:
  - Process previous round results
  - Execute <type> discussion strategy
  - Update discussion timeline
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Round: <N>
  - Type: <deepen|direction-adjusted|specific-questions>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/discussions/discussion-round-<NNN>.json
---
InnerLoop: false"
})
TaskUpdate({ taskId: "DISCUSS-<NNN>", owner: "discussant" })

ANALYZE-fix-N (direction adjustment):

TaskCreate({
  subject: "ANALYZE-fix-<N>",
  description: "PURPOSE: Supplementary analysis with adjusted focus | Success: New insights from adjusted direction
TASK:
  - Re-analyze from adjusted perspective: <adjusted_focus>
  - Build on previous exploration findings
  - Generate updated discussion points
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Type: direction-fix
  - Adjusted focus: <adjusted_focus>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/analyses/analysis-fix-<N>.json
---
InnerLoop: false"
})
TaskUpdate({ taskId: "ANALYZE-fix-<N>", owner: "analyst" })

SYNTH-001 (created dynamically — check existence first):

// Guard: only create if SYNTH-001 doesn't exist yet (dispatch may have pre-created it)
const existingSynth = TaskList().find(t => t.subject === 'SYNTH-001')
if (!existingSynth) {
TaskCreate({
  subject: "SYNTH-001",
  description: "PURPOSE: Integrate all analysis into final conclusions | Success: Executive summary with recommendations
TASK:
  - Load all exploration, analysis, and discussion artifacts
  - Extract themes, consolidate evidence, prioritize recommendations
  - Write conclusions and update discussion.md
CONTEXT:
  - Session: <session-folder>
  - Topic: <topic>
  - Upstream artifacts: explorations/*.json, analyses/*.json, discussions/*.json
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/conclusions.json + discussion.md update
CONSTRAINTS: Pure integration, no new exploration
---
InnerLoop: false"
})
}
// Always update blockedBy to reference the last DISCUSS task (whether pre-existing or newly created)
TaskUpdate({ taskId: "SYNTH-001", addBlockedBy: ["<last-DISCUSS-task-id>"], owner: "synthesizer" })

7. Record user feedback to decision_trail via team_msg:

mcp__ccw-tools__team_msg({
  operation: "log", session_id: sessionId, from: "coordinator",
  type: "state_update",
  data: { decision_trail_entry: {
    round: discussion_round,
    decision: feedback,
    context: "User feedback at discussion round N",
    timestamp: current ISO timestamp
  }}
})

8. Proceed to handleSpawnNext

handleSpawnNext

Find and spawn the next ready tasks.

1. Scan task list for tasks where:

• Status is "pending"
• All blockedBy tasks have status "completed"

2. For each ready task, determine role from task prefix:

3. Spawn team-worker for each ready task:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker for <task-subject>",
  team_name: "ultra-analyze",
  name: "<agent-name>",
  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: ultra-analyze
requirement: <task-description>
agent_name: <agent-name>
inner_loop: false

## Current Task
- Task ID: <task-id>
- Task: <task-subject>

## 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, owner=<agent-name>) -> role-spec Phase 2-4 -> built-in Phase 5 (report).`
})

4. Parallel spawn rules:

5. STOP after spawning -- wait for next callback

handleCheck

Output current pipeline status without advancing.

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)

Pipeline Status (<mode> mode):
  [DONE]  EXPLORE-001  (explorer)     -> exploration-001.json
  [DONE]  EXPLORE-002  (explorer)     -> exploration-002.json
  [DONE]  ANALYZE-001  (analyst)      -> analysis-001.json
  [RUN]   ANALYZE-002  (analyst)      -> analyzing...
  [WAIT]  DISCUSS-001  (discussant)   -> blocked by ANALYZE-002
  [----]  SYNTH-001    (synthesizer)  -> blocked by DISCUSS-001

Discussion Rounds: 0/<max>
Pipeline Mode: <mode>
Session: <session-id>

Output status -- do NOT advance pipeline.

handleResume

Resume pipeline after user pause or interruption.

1. Audit task list for inconsistencies:

• Tasks stuck in "in_progress" -> reset to "pending"
• Tasks with completed blockers but still "pending" -> include in spawn list

2. Proceed to handleSpawnNext

handleComplete

Triggered when all pipeline tasks are completed.

Completion check:

1. Verify all tasks completed. If any not completed, return to handleSpawnNext 2. If all completed, inline-execute coordinator Phase 5 (shutdown workers → report → completion action). Do NOT STOP here — continue directly into Phase 5 within the same turn.

Phase 4: State Persistence

After every handler execution except handleComplete:

1. Update session.json with current state:

• discussion_round: current round count
• last_event: event type and timestamp
• active_tasks: list of in-progress task IDs

2. Verify task list consistency (no orphan tasks, no broken dependencies) 3. STOP and wait for next event

handleComplete exception: handleComplete does NOT STOP — it transitions directly to coordinator Phase 5.

Error Handling

Coordinator - Ultra Analyze Team

Role: coordinator Type: Orchestrator Team: ultra-analyze

Orchestrates the analysis pipeline: topic clarification, pipeline mode selection, task dispatch, discussion loop management, and final synthesis. Spawns team-worker agents for all worker roles.

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 discussion loop with max 5 rounds (Deep mode)
• Execute completion action in Phase 5

MUST NOT

• Implement domain logic (exploring, analyzing, discussing, synthesizing) -- workers handle this
• Spawn workers without creating tasks first
• Skip checkpoints when configured
• Force-advance pipeline past failed stages
• Directly call cli-explore-agent, CLI analysis tools, or execute codebase exploration

---

Command Execution Protocol

When coordinator needs to execute a command (dispatch, monitor):

1. Read the command file: roles/coordinator/commands/<command-name>.md 2. Follow the workflow defined in the command file (Phase 2-4 structure) 3. Commands are inline execution guides -- NOT separate agents or subprocesses 4. Execute synchronously -- complete the command workflow before proceeding

---

Entry Router

When coordinator is invoked, detect invocation type:

Message format discrimination:

• String messages starting with `[<role>]`: Worker/supervisor completion reports → route to handleCallback or handleSupervisorReport
• JSON object messages (contain type: field): Structured protocol messages (shutdown_response) → route by type field
• Other strings without role tags: System idle notifications → IGNORE

For callback/check/resume/complete: load @commands/monitor.md and execute matched handler, then STOP.

Router Implementation

1. Load session context (if exists):

• Scan .workflow/.team/UAN-*/.msg/meta.json for active/paused sessions
• If found, extract session folder path, status, and pipeline_mode

2. Parse $ARGUMENTS for detection keywords:

• Check for role name tags in message content
• Check for "check", "status", "resume", "continue" keywords

3. Route to handler:

• For monitor handlers: Read commands/monitor.md, execute matched handler, STOP
• For Phase 0: Execute Session Resume Check below
• For Phase 1: Execute Topic Understanding below

---

Phase 0: Session Resume Check

Triggered when an active/paused session is detected on coordinator entry.

1. Load session.json from detected session folder 2. Audit task list: TaskList() 3. Reconcile session state vs task status:

4. Rebuild team if not active: TeamCreate({ team_name: "ultra-analyze" }) 5. Spawn workers for ready tasks -> Phase 4 coordination loop

---

Phase 1: Topic Understanding & Requirement Clarification

TEXT-LEVEL ONLY. No source code reading.

1. Parse user task description from $ARGUMENTS 2. Extract explicit settings: --mode, scope, focus areas 3. Delegate to @commands/analyze.md for signal detection and pipeline mode selection 4. Interactive clarification (non-auto mode): AskUserQuestion for focus, perspectives, depth.

---

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-ultra-analyze

3. Generate session ID: UAN-{slug}-{YYYY-MM-DD} 4. Create session folder structure:

.workflow/.team/UAN-{slug}-{date}/
+-- .msg/messages.jsonl
+-- .msg/meta.json
+-- discussion.md
+-- explorations/
+-- analyses/
+-- discussions/
+-- wisdom/
    +-- learnings.md, decisions.md, conventions.md, issues.md

5. Write session.json with mode, requirement, timestamp 6. Initialize .msg/meta.json with pipeline metadata via team_msg:

mcp__ccw-tools__team_msg({
  operation: "log",
  session_id: "<session-id>",
  from: "coordinator",
  type: "state_update",
  summary: "Session initialized",
  data: {
    pipeline_mode: "<Quick|Deep|Standard>",
    pipeline_stages: ["explorer", "analyst", "discussant", "synthesizer"],
    roles: ["coordinator", "explorer", "analyst", "discussant", "synthesizer"],
    team_name: "ultra-analyze"
  }
})

7. Call TeamCreate({ team_name: "ultra-analyze" })

---

Phase 3: Create Task Chain

Execute @commands/dispatch.md inline (Command Execution Protocol): 1. Read roles/coordinator/commands/dispatch.md 2. Follow dispatch Phase 2 -> Phase 3 -> Phase 4 3. Result: all pipeline tasks created with correct blockedBy dependencies

---

Phase 4: Spawn & Coordination Loop

Initial Spawn

Find first unblocked tasks and spawn their workers. Use SKILL.md Worker Spawn Template with:

• role_spec: <skill_root>/roles/<role>/role.md
• team_name: ultra-analyze
• inner_loop: false

STOP after spawning. Wait for worker callback.

Coordination (via monitor.md handlers)

All subsequent coordination is handled by commands/monitor.md handlers triggered by worker callbacks.

---

Phase 5: Shutdown Workers + Report + Completion Action

Shutdown All Workers

Before reporting, gracefully shut down all active teammates. This is a multi-turn process:

1. Read team config: ~/.claude/teams/ultra-analyze/config.json 2. Build shutdown tracking list: pending_shutdown = [<all member names except coordinator>] 3. For each member in pending_shutdown, send shutdown request:

   SendMessage({
     to: "<member-name>",
     message: { type: "shutdown_request", reason: "Pipeline complete" }
   })

4. STOP — wait for responses. Each shutdown_response triggers a new coordinator turn. 5. On each subsequent turn (shutdown_response received):

• Remove responder from pending_shutdown
• If pending_shutdown is empty → proceed to Report section below
• If not empty → STOP again, wait for remaining responses

6. If a member is unresponsive after 2 follow-ups, remove from tracking and proceed

Note: Workers that completed Phase 5-F and reached STOP may have already terminated. SendMessage to a terminated agent is silently ignored — this is safe. Only resident agents (e.g., supervisor) require explicit shutdown.

Report

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

3. Include discussion summaries and decision trail 4. Output pipeline summary: task count, duration, mode

5. Completion Action (interactive):

AskUserQuestion({
  questions: [{
    question: "Ultra-Analyze pipeline complete. What would you like to do?",
    header: "Completion",
    multiSelect: false,
    options: [
      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up tasks and team resources" },
      { label: "Keep Active", description: "Keep session active for follow-up work or inspection" },
      { label: "Export Results", description: "Export deliverables to a specified location, then clean" }
    ]
  }]
})

6. Handle user choice per SKILL.md Completion Action section.

---

Error Handling

Discussant

Process analysis results and user feedback. Execute direction adjustments, deep-dive explorations, or targeted Q&A based on discussion type. Update discussion timeline.

Phase 2: Context Loading

1. Extract session path, topic, round, discussion type, user feedback:

2. Read all analysis and exploration results 3. Aggregate current findings, insights, open questions

Phase 3: Discussion Processing

Select strategy by discussion type:

initial: Cross-perspective summary -- identify convergent themes, conflicting views, top 5 discussion points and open questions from all analyses.

deepen: Use CLI tool for deep investigation:

Bash({
  command: `ccw cli -p "PURPOSE: Investigate open questions and uncertain insights; success = evidence-based findings
TASK: • Focus on open questions: <questions> • Find supporting evidence • Validate uncertain insights • Document findings
MODE: analysis
CONTEXT: @**/* | Memory: Session <session-folder>, previous analyses
EXPECTED: JSON output with investigation results | Write to <session>/discussions/deepen-<num>.json
CONSTRAINTS: Evidence-based analysis only
" --tool gemini --mode analysis --rule analysis-trace-code-execution`,
  run_in_background: false
})

direction-adjusted: CLI re-analysis from adjusted focus:

Bash({
  command: `ccw cli -p "Re-analyze '<topic>' with adjusted focus on '<userFeedback>'" --tool gemini --mode analysis`,
  run_in_background: false
})

specific-questions: Use CLI tool for targeted Q&A:

Bash({
  command: `ccw cli -p "PURPOSE: Answer specific user questions about <topic>; success = clear, evidence-based answers
TASK: • Answer: <userFeedback> • Provide code references • Explain context
MODE: analysis
CONTEXT: @**/* | Memory: Session <session-folder>
EXPECTED: JSON output with answers and evidence | Write to <session>/discussions/questions-<num>.json
CONSTRAINTS: Direct answers with code references
" --tool gemini --mode analysis`,
  run_in_background: false
})

Phase 4: Update Discussion Timeline

1. Write round content to <session>/discussions/discussion-round-<num>.json:

{
  "round": 1, "type": "initial", "user_feedback": "...",
  "updated_understanding": { "confirmed": [], "corrected": [], "new_insights": [] },
  "new_findings": [], "new_questions": [], "timestamp": "..."
}

2. Append round section to <session>/discussion.md:

### Round <N> - Discussion (<timestamp>)
#### Type: <discussType>
#### User Input: <userFeedback or "(Initial discussion round)">
#### Updated Understanding
**Confirmed**: <list> | **Corrected**: <list> | **New Insights**: <list>
#### New Findings / Open Questions

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

• Read existing -> merge { "discussant": { round, type, new_insight_count, corrected_count } } -> write back

Codebase Explorer

Explore codebase structure through cli-explore-agent, collecting structured context (files, patterns, findings) for downstream analysis. One explorer per analysis perspective.

Phase 2: Context & Scope Assessment

1. Load debug specs: Run ccw spec load --category debug for known issues and root-cause notes 2. Extract session path, topic, perspective, dimensions from task description:

2. Determine exploration number from task subject (EXPLORE-N) 3. Build exploration strategy by perspective:

Phase 3: Codebase Exploration

Use CLI tool for codebase exploration:

Bash({
  command: `ccw cli -p "PURPOSE: Explore codebase for <topic> from <perspective> perspective; success = structured findings with relevant files and patterns
TASK: • Run module depth analysis • Search for topic-related patterns • Identify key files and their relationships • Extract architectural insights
MODE: analysis
CONTEXT: @**/* | Memory: Session <session-folder>, perspective <perspective>
EXPECTED: JSON output with: relevant_files (path, relevance, summary), patterns, key_findings, module_map, questions_for_analysis, _metadata (perspective, search_queries, timestamp)
CONSTRAINTS: Focus on <perspective> angle - <strategy.focus> | Write to <session>/explorations/exploration-<num>.json
" --tool gemini --mode analysis --rule analysis-analyze-code-patterns`,
  run_in_background: false
})

ACE fallback (when CLI produces no output):

mcp__ace-tool__search_context({ project_root_path: ".", query: "<topic> <perspective>" })

Phase 4: Result Validation

Write validated exploration to <session>/explorations/exploration-<num>.json.

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

• Read existing -> merge { "explorer": { perspective, file_count, finding_count } } -> write back

Synthesizer

Integrate all explorations, analyses, and discussions into final conclusions. Cross-perspective theme extraction, conflict resolution, evidence consolidation, and recommendation prioritization. Pure integration role -- no external tools or CLI calls.

Phase 2: Context Loading

1. Extract session path and topic from task description 2. Read all exploration, analysis, and discussion round files 3. Load decision trail and current understanding from meta.json 4. Select synthesis strategy:

Phase 3: Cross-Perspective Synthesis

Execute synthesis across four dimensions:

1. Theme Extraction: Identify convergent themes across all analysis perspectives. Cluster insights by similarity, rank by cross-perspective confirmation count.

2. Conflict Resolution: Identify contradictions between perspectives. Present both sides with trade-off analysis when irreconcilable.

3. Evidence Consolidation: Deduplicate findings, aggregate by file reference. Map evidence to conclusions with confidence levels:

4. Recommendation Prioritization: Sort all recommendations by priority (high > medium > low), deduplicate, cap at 10.

Integrate decision trail from discussion rounds into final narrative.

Phase 4: Write Conclusions

1. Write <session>/conclusions.json:

{
  "session_id": "...", "topic": "...", "completed": "ISO-8601",
  "summary": "Executive summary...",
  "key_conclusions": [{"point": "...", "evidence": "...", "confidence": "high"}],
  "recommendations": [{"action": "...", "rationale": "...", "priority": "high"}],
  "open_questions": ["..."],
  "decision_trail": [{"round": 1, "decision": "...", "context": "..."}],
  "cross_perspective_synthesis": { "convergent_themes": [], "conflicts_resolved": [], "unique_contributions": [] },
  "_metadata": { "explorations": 3, "analyses": 3, "discussions": 2, "strategy": "standard" }
}

2. Append conclusions section to <session>/discussion.md:

## Conclusions
### Summary / Key Conclusions / Recommendations / Remaining Questions
## Decision Trail / Current Understanding (Final) / Session Statistics

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

• Read existing -> merge { "synthesizer": { conclusion_count, recommendation_count, open_question_count } } -> write back

Pipeline Definitions — Team Ultra Analyze

Pipeline Modes

Quick Mode (3 tasks, serial)

EXPLORE-001 -> ANALYZE-001 -> SYNTH-001

Standard Mode (2N+2 tasks, parallel windows)

[EXPLORE-001..N](parallel) -> [ANALYZE-001..N](parallel) -> DISCUSS-001 -> SYNTH-001

Deep Mode (2N+1 tasks initially, dynamic loop)

Same as Standard but SYNTH-001 is omitted at dispatch. Created dynamically after discussion loop completes.

Dynamic tasks created during discussion loop:

• DISCUSS-N (round N) — created based on user feedback
• ANALYZE-fix-N (direction fix) — created when user requests adjusted focus
• SYNTH-001 — created after final discussion round

Task Metadata Registry

Discussion Loop Control

Checkpoints