catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-02-28 09:23:08 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
430d817e435bd4ba30e52c0bc78ed78b33798fb1
Claude-Code-Workflow/.claude/skills/team-ultra-analyze/SKILL.md
catlog22 430d817e43 feat(skills): update 12 team skills to v3 design patterns 
- Update all 12 team-* SKILL.md files with v3 structure:
  - Replace JS pseudocode with text decision tables
  - Add Role Registry with Compact column
  - Add COMPACT PROTECTION blocks
  - Add Cadence Control sections
  - Add Wisdom Accumulation sections
  - Add Task Metadata Registry
  - Add Orchestration Mode user commands

- Update 58 role files (SKILL.md + roles/*):
  - Flat-file skills: team-brainstorm, team-issue, team-testing,
    team-uidesign, team-planex, team-iterdev
  - Folder-based skills: team-review, team-roadmap-dev, team-frontend,
    team-quality-assurance, team-tech-debt, team-ultra-analyze

- Preserve special architectures:
  - team-planex: 2-member (planner + executor only)
  - team-tech-debt: Stop-Wait strategy (run_in_background:false)
  - team-iterdev: 7 behavior protocol tables in coordinator

- All 12 teams reviewed for content completeness (PASS)
2026-02-26 21:14:45 +08:00

440 lines
20 KiB
Markdown
Raw Blame History

---
name: team-ultra-analyze
description: Unified team skill for deep collaborative analysis. All roles invoke this skill with --role arg for role-specific execution. Triggers on "team ultra-analyze", "team analyze".
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Task(*), AskUserQuestion(*), Read(*), Write(*), Edit(*), Bash(*), Glob(*), Grep(*)
---
# Team Ultra Analyze
Deep collaborative analysis team skill. Splits monolithic analysis into 5-role collaboration: explore -> analyze -> discuss -> synthesize. Supports Quick/Standard/Deep pipeline modes with configurable depth (N parallel agents). Discussion loops enable user-guided progressive understanding. All members route via `--role=xxx`.
## Architecture
```
+-------------------------------------------------------------+
| Skill(skill="team-ultra-analyze") |
| args="topic description" or args="--role=xxx" |
+----------------------------+--------------------------------+
| Role Router
+---- --role present? ----+
| NO | YES
v v
Orchestration Mode Role Dispatch
(auto -> coordinator) (route to role.md)
|
+-----+------+----------+-----------+
v v v v v
coordinator explorer analyst discussant synthesizer
EXPLORE-* ANALYZE-* DISCUSS-* SYNTH-*
```
## Command Architecture
```
roles/
+-- coordinator/
| +-- role.md # Orchestration: topic clarification, pipeline selection, discussion loop, reporting
| +-- commands/
| +-- dispatch.md # Task chain creation and dependency management
| +-- monitor.md # Progress monitoring + discussion loop
+-- explorer/
| +-- role.md # Codebase exploration
| +-- commands/
| +-- explore.md # cli-explore-agent parallel exploration
+-- analyst/
| +-- role.md # Deep analysis
| +-- commands/
| +-- analyze.md # CLI multi-perspective analysis
+-- discussant/
| +-- role.md # Discussion processing + direction adjustment
| +-- commands/
| +-- deepen.md # Deep-dive exploration
+-- synthesizer/
+-- role.md # Synthesis and conclusions
+-- commands/
+-- synthesize.md # Cross-perspective integration
```
**Design principle**: role.md retains Phase 1 (Task Discovery) and Phase 5 (Report) inline. Phase 2-4 delegate to `commands/*.md` based on complexity.
## Role Router
### Input Parsing
Parse `$ARGUMENTS` to extract `--role` and optional `--agent-name`. If `--role` is absent, enter Orchestration Mode (auto route to coordinator). The `--agent-name` parameter supports parallel instances (e.g., explorer-1, analyst-2) and is passed through to role.md for task discovery filtering.
### Role Registry
| Role | File | Task Prefix | Type | Compact |
|------|------|-------------|------|---------|
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | orchestrator | **compress: must re-read** |
| explorer | [roles/explorer/role.md](roles/explorer/role.md) | EXPLORE-* | parallel worker | compress: must re-read |
| analyst | [roles/analyst/role.md](roles/analyst/role.md) | ANALYZE-* | parallel worker | compress: must re-read |
| discussant | [roles/discussant/role.md](roles/discussant/role.md) | DISCUSS-* | pipeline | compress: must re-read |
| synthesizer | [roles/synthesizer/role.md](roles/synthesizer/role.md) | SYNTH-* | pipeline | compress: must re-read |
> **COMPACT PROTECTION**: Role files are execution documents, not reference material. When context compression occurs and role instructions are reduced to summaries, you **must immediately `Read` the corresponding role.md to reload before continuing execution**. Never execute any Phase based on compressed summaries alone.
### Dispatch
1. Extract `--role` from arguments
2. If no `--role` -> route to coordinator (Orchestration Mode)
3. Look up role in registry -> Read the role file -> Execute its phases
### Orchestration Mode
When invoked without `--role`, coordinator auto-starts. User just provides the analysis topic.
**Invocation**: `Skill(skill="team-ultra-analyze", args="analysis topic description")`
**Lifecycle**:
```
User provides analysis topic
-> coordinator Phase 1-3: topic clarification -> TeamCreate -> pipeline selection -> create task chain
-> coordinator Phase 4: spawn depth explorers in parallel (background) -> STOP
-> Explorers execute -> SendMessage callback -> coordinator spawns analysts
-> Analysts execute -> SendMessage callback -> coordinator spawns discussant
-> Discussion loop (Deep mode: user feedback -> deepen -> re-analyze -> repeat)
-> coordinator spawns synthesizer -> final conclusions -> Phase 5 report
```
**User Commands** (wake suspended coordinator):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status diagram, do not advance pipeline |
| `resume` / `continue` | Check worker status, advance to next pipeline step |
---
## Shared Infrastructure
The following templates apply to all worker roles. Each role.md only needs to define **Phase 2-4** role-specific logic.
### Worker Phase 1: Task Discovery (shared by all workers)
Each worker executes the same task discovery flow on startup:
1. Call `TaskList()` to get all tasks
2. Filter: subject matches this role's prefix + owner matches this agent's name + status is pending + blockedBy is empty
3. No tasks -> idle wait
4. Has tasks -> `TaskGet` for details -> `TaskUpdate` mark in_progress
**Resume Artifact Check** (prevent duplicate output after recovery):
- Check if this task's output artifacts already exist
- Artifacts complete -> skip to Phase 5 report completion
- Artifacts incomplete or missing -> execute Phase 2-4 normally
### Worker Phase 5: Report (shared by all workers)
Standard report flow after task completion:
1. **Message Bus**: Call `mcp__ccw-tools__team_msg` to log message
- Parameters: operation="log", team=<team-name>, from=<role>, to="coordinator", type=<message-type>, summary="[<role>] <summary>", ref=<artifact-path>
- **CLI fallback**: When MCP unavailable -> `ccw team log --team <team> --from <role> --to coordinator --type <type> --summary "[<role>] ..." --json`
2. **SendMessage**: Send result to coordinator (both content and summary prefixed with `[<role>]`)
3. **TaskUpdate**: Mark task completed
4. **Loop**: Return to Phase 1 to check for next task
### Wisdom Accumulation (all roles)
Cross-task knowledge accumulation. Coordinator creates `wisdom/` directory during session initialization.
**Directory**:
```
<session-folder>/wisdom/
+-- learnings.md # Patterns and insights
+-- decisions.md # Analysis direction decisions
+-- conventions.md # Codebase conventions discovered
+-- issues.md # Known risks and issues
```
**Worker load** (Phase 2): Extract `Session: <path>` from task description, read wisdom directory files.
**Worker contribute** (Phase 4/5): Write discoveries from this task into corresponding wisdom files.
### Role Isolation Rules
| Allowed | Prohibited |
|---------|-----------|
| Process tasks matching own prefix | Process tasks with other role prefixes |
| SendMessage to coordinator | Communicate directly with other workers |
| Read/write shared-memory.json (own fields) | Create tasks for other roles |
| Delegate to commands/*.md | Modify resources outside own responsibility |
Coordinator additionally prohibited: directly executing code exploration or analysis, directly calling cli-explore-agent or CLI analysis tools, bypassing workers to complete work.
### Shared Memory
Core shared artifact stored at `<session-folder>/shared-memory.json`. Each role reads the full memory but writes only to its own designated field:
| Role | Write Field |
|------|-------------|
| explorer | `explorations` |
| analyst | `analyses` |
| discussant | `discussions` |
| synthesizer | `synthesis` |
| coordinator | `decision_trail` + `current_understanding` |
On startup, read the file. After completing work, update own field and write back. If file does not exist, initialize with empty object.
### Message Bus (All Roles)
All roles log messages before sending via SendMessage. Call `mcp__ccw-tools__team_msg` with: operation="log", team=<team-name>, from=<role>, to="coordinator", type=<message-type>, summary="[<role>] <summary>", ref=<file-path>.
| Role | Types |
|------|-------|
| coordinator | `pipeline_selected`, `discussion_round`, `direction_adjusted`, `task_unblocked`, `error`, `shutdown` |
| explorer | `exploration_ready`, `error` |
| analyst | `analysis_ready`, `error` |
| discussant | `discussion_processed`, `error` |
| synthesizer | `synthesis_ready`, `error` |
**CLI fallback**: When MCP unavailable -> `ccw team log --team "<team>" --from "<role>" --to "coordinator" --type "<type>" --summary "<summary>" --json`
---
## Three-Mode Pipeline Architecture
```
Quick: EXPLORE-001 -> ANALYZE-001 -> SYNTH-001
Standard: [EXPLORE-001..depth](parallel) -> [ANALYZE-001..depth](parallel) -> DISCUSS-001 -> SYNTH-001
Deep: [EXPLORE-001..depth] -> [ANALYZE-001..depth] -> DISCUSS-001 -> ANALYZE-fix -> DISCUSS-002 -> ... -> SYNTH-001
```
### Mode Auto-Detection
Parse `--mode` from arguments first. If not specified, auto-detect from topic description:
| Condition | Mode | Depth |
|-----------|------|-------|
| `--mode=quick` explicit or topic contains "quick/overview/fast" | Quick | 1 |
| `--mode=deep` explicit or topic contains "deep/thorough/detailed/comprehensive" | Deep | N (from perspectives) |
| Default (no match) | Standard | N (from perspectives) |
**Depth** is determined by the number of selected analysis perspectives (e.g., architecture, implementation, performance, security, concept, comparison, decision). Quick mode always uses depth=1. Standard/Deep mode uses depth = number of selected perspectives.
### Discussion Loop (Deep Mode)
```
coordinator(AskUser) -> DISCUSS-N(deepen) -> [optional ANALYZE-fix] -> coordinator(AskUser) -> ... -> SYNTH
```
Maximum 5 discussion rounds. If exceeded, force synthesis and offer continuation option.
## Decision Recording Protocol
**CRITICAL**: Inherited from the original analyze-with-file command. During analysis, the following must be immediately recorded to discussion.md:
| Trigger | What to Record | Target Section |
|---------|---------------|----------------|
| **Direction choice** | What was chosen, why, which alternatives were rejected | `#### Decision Log` |
| **Key finding** | Discovery content, impact scope, confidence level | `#### Key Findings` |
| **Assumption change** | Old assumption -> new understanding, reason for change, impact | `#### Corrected Assumptions` |
| **User feedback** | User's raw input, adoption/adjustment rationale | `#### User Input` |
## Cadence Control
**Beat model**: Event-driven. Each beat = coordinator wakes -> processes callback -> spawns next phase -> STOP.
```
Beat Cycle (single beat)
=====================================================================
Event Coordinator Workers
---------------------------------------------------------------------
callback/resume --> +- handleCallback -+
| mark completed |
| check pipeline |
+- handleSpawnNext -+
| find ready tasks |
| spawn workers ---+--> [Worker A] Phase 1-5
| (parallel OK) --+--> [Worker B] Phase 1-5
+- STOP (idle) -----+ |
|
callback <----------------------------------------+
(next beat) SendMessage + TaskUpdate(completed)
=====================================================================
```
**Discussion Loop Beat (Deep mode with configurable depth)**:
```
Phase 1 (explore): Spawn depth explorers simultaneously
EXPLORE-1, EXPLORE-2, ..., EXPLORE-depth (all parallel)
-> All complete -> coordinator wakes
Phase 2 (analyze): Spawn depth analysts simultaneously
ANALYZE-1, ANALYZE-2, ..., ANALYZE-depth (all parallel)
-> All complete -> coordinator wakes
Phase 3 (discuss): Spawn 1 discussant
DISCUSS-001
-> Complete -> coordinator asks user for direction
Phase 3a (loop): If user requests deeper analysis (Deep mode only):
-> Spawn ANALYZE-fix tasks -> DISCUSS-002 -> ask user -> repeat
-> Maximum 5 rounds
Phase 4 (synth): Spawn 1 synthesizer
SYNTHESIZE-001
-> Complete -> coordinator reports to user
```
**Pipeline Beat Views**:
```
Quick (3 beats, serial)
------------------------------------------------------
Beat 1 2 3
| | |
EXPLORE -> ANALYZE -> SYNTH
Standard (4 beats, parallel windows)
------------------------------------------------------
Beat 1 2 3 4
+----- ... ----+ +----- ... ----+ | |
E1 || E2 || EN A1 || A2 || AN -> DISCUSS -> SYNTH
+---- parallel ---+ +---- parallel ---+
Deep (4+ beats, with discussion loop)
------------------------------------------------------
Beat 1 2 3 3a... 4
+-...-+ +-...-+ | +-- loop --+ |
E1||EN A1||AN -> DISC -> A-fix->DISC -> SYNTH
(max 5 rounds)
```
**Checkpoints**:
| Trigger | Location | Behavior |
|---------|----------|----------|
| Discussion round (Deep mode) | After DISCUSS-N completes | Pause, AskUser for direction/continuation |
| Discussion loop limit | >5 rounds | Force synthesis, offer continuation |
| Pipeline stall | No ready + no running | Check missing tasks, report to user |
**Stall detection** (coordinator `handleCheck`):
| Check | Condition | Resolution |
|-------|-----------|------------|
| Worker unresponsive | in_progress task with no callback | Report waiting tasks, suggest user `resume` |
| Pipeline deadlock | No ready + no running + has pending | Check blockedBy chain, report blockage |
| Discussion loop over limit | DISCUSS round > 5 | Terminate loop, output latest discussion state |
## Task Metadata Registry
| Task ID | Role | Phase | Dependencies | Description |
|---------|------|-------|-------------|-------------|
| EXPLORE-1..depth | explorer | explore | (none) | Parallel codebase exploration, one per perspective |
| ANALYZE-1..depth | analyst | analyze | EXPLORE-1..depth (all complete) | Parallel deep analysis, one per perspective |
| DISCUSS-001 | discussant | discuss | ANALYZE-1..depth (all complete) | Process analysis results, identify gaps |
| ANALYZE-fix-N | analyst | discuss-loop | DISCUSS-N | Re-analysis for specific areas (Deep mode only) |
| DISCUSS-002..N | discussant | discuss-loop | ANALYZE-fix-N | Subsequent discussion rounds (Deep mode, max 5) |
| SYNTHESIZE-001 | synthesizer | synthesize | Last DISCUSS-N | Cross-perspective integration and conclusions |
**Dynamic task creation**: Coordinator creates EXPLORE-1 through EXPLORE-depth and ANALYZE-1 through ANALYZE-depth based on the number of selected perspectives. Discussion loop tasks (ANALYZE-fix-N, DISCUSS-002+) are created dynamically in Deep mode based on user feedback.
## Coordinator Spawn Template
When coordinator spawns workers, use background mode (Spawn-and-Stop pattern). The coordinator determines the depth (number of parallel agents) based on selected perspectives.
**Phase 1 - Spawn Explorers**: Create depth explorer agents in parallel (EXPLORE-1 through EXPLORE-depth). Each explorer receives its assigned perspective/domain and agent name for task matching. All spawned with run_in_background:true. Coordinator stops after spawning and waits for callbacks.
**Phase 2 - Spawn Analysts**: After all explorers complete, create depth analyst agents in parallel (ANALYZE-1 through ANALYZE-depth). Each analyst receives its assigned perspective matching the corresponding explorer. All spawned with run_in_background:true. Coordinator stops.
**Phase 3 - Spawn Discussant**: After all analysts complete, create 1 discussant. It processes all analysis results and presents findings to user. Coordinator stops.
**Phase 3a - Discussion Loop** (Deep mode only): Based on user feedback, coordinator may create additional ANALYZE-fix and DISCUSS tasks. Loop continues until user is satisfied or 5 rounds reached.
**Phase 4 - Spawn Synthesizer**: After final discussion round, create 1 synthesizer. It integrates all explorations, analyses, and discussions into final conclusions. Coordinator stops.
**Quick mode exception**: When depth=1, spawn single explorer, single analyst, single discussant, single synthesizer -- all as simple agents without numbered suffixes.
**Single spawn example** (worker template used for all roles):
```
Task({
subagent_type: "general-purpose",
description: "Spawn <role> worker",
team_name: <team-name>,
name: "<agent-name>",
run_in_background: true,
prompt: `You are team "<team-name>" <ROLE> (<agent-name>).
Your agent name is "<agent-name>", use it for task discovery owner matching.
## Primary Instruction
All work must be executed by calling Skill for role definition:
Skill(skill="team-ultra-analyze", args="--role=<role> --agent-name=<agent-name>")
Current topic: <task-description>
Session: <session-folder>
## Role Rules
- Only process <PREFIX>-* tasks where owner === "<agent-name>"
- All output prefixed with [<role>] identifier
- Communicate only with coordinator
- Do not use TaskCreate for other roles
- Call mcp__ccw-tools__team_msg before every SendMessage
## Workflow
1. Call Skill -> load role definition and execution logic
2. Execute role.md 5-Phase process
3. team_msg + SendMessage result to coordinator
4. TaskUpdate completed -> check next task`
})
```
## Team Configuration
| Setting | Value |
|---------|-------|
| Team name | ultra-analyze |
| Session directory | .workflow/.team/UAN-{slug}-{date}/ |
| Shared memory file | shared-memory.json |
| Analysis dimensions | architecture, implementation, performance, security, concept, comparison, decision |
| Max discussion rounds | 5 |
## Unified Session Directory
```
.workflow/.team/UAN-{slug}-{YYYY-MM-DD}/
+-- shared-memory.json # Exploration/analysis/discussion/synthesis shared memory
+-- 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
```
## Session Resume
Coordinator supports `--resume` / `--continue` for interrupted sessions:
1. Scan `.workflow/.team/UAN-*/` for active/paused sessions
2. Multiple matches -> AskUserQuestion for selection
3. Audit TaskList -> reconcile session state with task status
4. Reset in_progress -> pending (interrupted tasks)
5. Rebuild team and spawn needed workers only
6. Create missing tasks with correct blockedBy
7. Kick first executable task -> Phase 4 coordination loop
## Error Handling
| Scenario | Resolution |
|----------|------------|
| Unknown --role value | Error with available role list |
| Missing --role arg | Orchestration Mode -> coordinator |
| Role file not found | Error with expected path (roles/{name}/role.md) |
| Task prefix conflict | Log warning, proceed |
| Discussion loop stuck >5 rounds | Force synthesis, offer continuation |
| CLI tool unavailable | Fallback chain: gemini -> codex -> manual analysis |
| Explorer agent fails | Continue with available context, note limitation |
Reference in New Issue View Git Blame Copy Permalink