CtrlK
BlogDocsLog inGet started
Tessl Logo

team-ultra-analyze

Deep collaborative analysis team skill. All roles route via this SKILL.md. Beat model is coordinator-only (monitor.md). Structure is roles/ + specs/. Triggers on "team ultra-analyze", "team analyze".

62

Quality

53%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./.codex/skills/team-ultra-analyze/SKILL.md
SKILL.md
Quality
Evals
Security

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

RolePathPrefixInner Loop
coordinatorroles/coordinator/role.md
explorerroles/explorer/role.mdEXPLORE-*false
analystroles/analyst/role.mdANALYZE-*false
discussantroles/discussant/role.mdDISCUSS-*false
synthesizerroles/synthesizer/role.mdSYNTH-*false

Role Router

Parse $ARGUMENTS:

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

Delegation Lock

Coordinator is a PURE ORCHESTRATOR. It coordinates, it does NOT do.

Before calling ANY tool, apply this check:

Tool CallVerdictReason
spawn_agent, wait_agent, close_agent, send_message, assign_taskALLOWEDOrchestration
list_agentsALLOWEDAgent health check
request_user_inputALLOWEDUser interaction
mcp__ccw-tools__team_msgALLOWEDMessage bus
Read/Write on .workflow/.team/ filesALLOWEDSession state
Read on roles/, commands/, specs/ALLOWEDLoading own instructions
Read/Grep/Glob on project source codeBLOCKEDDelegate to worker
Edit on any file outside .workflow/BLOCKEDDelegate to worker
Bash("ccw cli ...")BLOCKEDOnly workers call CLI
Bash running build/test/lint commandsBLOCKEDDelegate to worker

If a tool call is BLOCKED: STOP. Create a task, spawn a worker.

No exceptions for "simple" tasks. Even a single-file read-and-report MUST go through spawn_agent.


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:

spawn_agent({
  agent_type: "team_worker",
  task_name: "<task-id>",
  fork_context: false,
  items: [
    { type: "text", text: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
requirement: <topic-description>
inner_loop: false

Read role_spec file (<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.` },

    { type: "text", text: `## Task Context
task_id: <task-id>
title: <task-title>
description: <task-description>
pipeline_phase: <pipeline-phase>` },

    { type: "text", text: `## Upstream Context
<prev_context>` }
  ]
})

After spawning, use wait_agent({ targets: [...], timeout_ms: 900000 }) to collect results, then close_agent({ target }) each worker.

Model Selection Guide

Rolemodelreasoning_effortRationale
Explorer (EXPLORE-*)(default)mediumFile reading and pattern scanning, less reasoning needed
Analyst (ANALYZE-*)(default)highDeep analysis requires full reasoning
Discussant (DISCUSS-*)(default)highSynthesis of multiple viewpoints, dialectic reasoning
Synthesizer (SYNTH-*)(default)mediumAggregation and summary over generation

Override model/reasoning_effort in spawn_agent when cost optimization is needed:

spawn_agent({
  agent_type: "team_worker",
  task_name: "<task-id>",
  fork_context: false,
  model: "<model-override>",
  reasoning_effort: "<effort-level>",
  items: [...]
})

User Commands

CommandAction
check / statusOutput execution status diagram, do not advance pipeline
resume / continueCheck worker status, advance to next pipeline step

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

v4 Agent Coordination

Message Semantics

IntentAPIExample
Send exploration findings to running analystssend_messageQueue upstream context without interrupting ANALYZE-* workers
Not used in this skillassign_taskNo resident agents -- all workers are one-shot
Check running agentslist_agentsVerify parallel explorer/analyst health during resume

Parallel Phase Coordination

Standard/Deep modes spawn N parallel agents in EXPLORE and ANALYZE phases. Use batch spawn + wait:

// EXPLORE phase: spawn N explorers in parallel
const explorerNames = ["EXPLORE-001", "EXPLORE-002", ..., "EXPLORE-00N"]
for (const name of explorerNames) {
  spawn_agent({ agent_type: "team_worker", task_name: name, ... })
}
wait_agent({ targets: explorerNames, timeout_ms: 900000 })
// Collect all results, then spawn ANALYZE phase

// ANALYZE phase: send exploration context to analysts via items (not send_message)
// since analysts are spawned AFTER explorers complete

Agent Health Check

Use list_agents({}) in handleResume and handleComplete:

// Reconcile session state with actual running agents
const running = list_agents({})
// Compare with tasks.json active_agents
// Reset orphaned tasks (in_progress but agent gone) to pending
// Critical for parallel phases -- multiple agents may crash independently

Named Agent Targeting

Workers are spawned with task_name: "<task-id>" enabling direct addressing:

  • send_message({ target: "ANALYZE-001", items: [...] }) -- queue supplementary exploration findings
  • close_agent({ target: "EXPLORE-001" }) -- cleanup by name after wait_agent returns

Completion Action

When pipeline completes, coordinator presents:

request_user_input({
  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" }
    ]
  }]
})
ChoiceAction
Archive & CleanUpdate session status="completed" -> output final summary
Keep ActiveUpdate session status="paused" -> output resume instructions
Export Resultsrequest_user_input for target path -> copy deliverables -> Archive & Clean

Specs Reference

Error Handling

ScenarioResolution
Unknown --role valueError with role registry list
Role file not foundError with expected path (roles/{name}/role.md)
Discussion loop stuck >5 roundsForce synthesis, offer continuation
CLI tool unavailableFallback chain: gemini -> codex -> manual analysis
Explorer agent failsContinue with available context, note limitation
Fast-advance conflictCoordinator reconciles on next callback
Completion action failsDefault to Keep Active
Repository
catlog22/Claude-Code-Workflow
Last updated
Created

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.