mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-03-10 17:11:04 +08:00
feat: Add templates for epics, product brief, and requirements documentation
- Introduced a comprehensive template for generating epics and stories in Phase 5, including an index and individual epic files. - Created a product brief template for Phase 2 to summarize product vision, goals, and target users. - Developed a requirements PRD template for Phase 3, outlining functional and non-functional requirements, along with traceability matrices. feat: Implement tech debt roles for assessment, execution, planning, scanning, validation, and analysis - Added roles for tech debt assessment, executor, planner, scanner, validator, and analyst, each with defined phases and processes for managing technical debt. - Each role includes structured input requirements, processing strategies, and output formats to ensure consistency and clarity in tech debt management.
This commit is contained in:
catlog22
@@ -1,362 +1,70 @@
|
||||
---
|
||||
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".
|
||||
description: 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".
|
||||
allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), TaskUpdate(*), TaskList(*), TaskGet(*), Agent(*), 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`.
|
||||
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-description>" |
|
||||
+-------------------+-------------------------------+
|
||||
Skill(skill="team-ultra-analyze", args="<topic>")
|
||||
|
|
||||
Orchestration Mode (auto -> coordinator)
|
||||
SKILL.md (this file) = Router
|
||||
|
|
||||
Coordinator (inline)
|
||||
Phase 0-5 orchestration
|
||||
|
|
||||
+-------+-------+-------+-------+
|
||||
v v v v
|
||||
[tw] [tw] [tw] [tw]
|
||||
explor- analy- discu- synthe-
|
||||
er st ssant sizer
|
||||
+--------------+--------------+
|
||||
| |
|
||||
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]
|
||||
|
||||
(tw) = team-worker agent
|
||||
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
|
||||
```
|
||||
|
||||
## Command Architecture
|
||||
## Role Registry
|
||||
|
||||
```
|
||||
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 | Path | Prefix | Inner Loop |
|
||||
|------|------|--------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | — | — |
|
||||
| explorer | [roles/explorer/role.md](roles/explorer/role.md) | EXPLORE-* | false |
|
||||
| analyst | [roles/analyst/role.md](roles/analyst/role.md) | ANALYZE-* | false |
|
||||
| discussant | [roles/discussant/role.md](roles/discussant/role.md) | DISCUSS-* | false |
|
||||
| synthesizer | [roles/synthesizer/role.md](roles/synthesizer/role.md) | SYNTH-* | false |
|
||||
|
||||
## Role Router
|
||||
|
||||
### Input Parsing
|
||||
Parse `$ARGUMENTS`:
|
||||
- Has `--role <name>` → Read `roles/<name>/role.md`, execute Phase 2-4
|
||||
- No `--role` → Read `roles/coordinator/role.md`, execute entry router
|
||||
|
||||
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.
|
||||
## Shared Constants
|
||||
|
||||
### Role Registry
|
||||
- **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>, ...)`
|
||||
|
||||
| Role | Spec | Task Prefix | Inner Loop |
|
||||
|------|------|-------------|------------|
|
||||
| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | (none) | - |
|
||||
| explorer | [role-specs/explorer.md](role-specs/explorer.md) | EXPLORE-* | false |
|
||||
| analyst | [role-specs/analyst.md](role-specs/analyst.md) | ANALYZE-* | false |
|
||||
| discussant | [role-specs/discussant.md](role-specs/discussant.md) | DISCUSS-* | false |
|
||||
| synthesizer | [role-specs/synthesizer.md](role-specs/synthesizer.md) | SYNTH-* | false |
|
||||
## Worker Spawn Template
|
||||
|
||||
> **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", session_id=<session-id>, from=<role>, type=<message-type>, data={ref: "<artifact-path>"}
|
||||
- `to` and `summary` auto-defaulted -- do NOT specify explicitly
|
||||
- **CLI fallback**: `ccw team log --session-id <session-id> --from <role> --type <type> --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 |
|
||||
| Share state via team_msg(type='state_update') | 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.
|
||||
|
||||
### Cross-Role State
|
||||
|
||||
Cross-role state managed via `team_msg(type='state_update')`, stored in `.msg/meta.json.role_state`. Each role reads all states but writes only to its own designated field:
|
||||
|
||||
| Role | State Field |
|
||||
|------|-------------|
|
||||
| explorer | `explorations` |
|
||||
| analyst | `analyses` |
|
||||
| discussant | `discussions` |
|
||||
| synthesizer | `synthesis` |
|
||||
| coordinator | `decision_trail` + `current_understanding` |
|
||||
|
||||
On startup, read role states via `team_msg(operation="get_state", session_id=<session-id>)`. After completing work, share results via `team_msg(operation="log", session_id=<session-id>, from=<role>, type="state_update", data={...})`.
|
||||
|
||||
### Message Bus (All Roles)
|
||||
|
||||
All roles log messages before sending via SendMessage. Call `mcp__ccw-tools__team_msg` with: operation="log", session_id=<session-id>, from=<role>, type=<message-type>, data={ref: "<file-path>"}. `to` and `summary` are auto-defaulted.
|
||||
|
||||
|
||||
|
||||
| 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 --session-id <session-id> --from <role> --type <type> --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
|
||||
|
||||
### v5 Worker Spawn (all roles)
|
||||
|
||||
When coordinator spawns workers, use `team-worker` agent with role-spec path. The coordinator determines depth (number of parallel agents) based on selected perspectives.
|
||||
|
||||
**Phase 1 - Spawn Explorers**: Create depth explorer team-worker agents in parallel (EXPLORE-1 through EXPLORE-depth). Each receives its assigned perspective/domain and agent name for task matching.
|
||||
|
||||
**Phase 2 - Spawn Analysts**: After all explorers complete, create depth analyst team-worker agents in parallel (ANALYZE-1 through ANALYZE-depth).
|
||||
|
||||
**Phase 3 - Spawn Discussant**: After all analysts complete, create 1 discussant. Coordinator stops.
|
||||
|
||||
**Phase 3a - Discussion Loop** (Deep mode only): Based on user feedback, coordinator may create additional ANALYZE-fix and DISCUSS tasks.
|
||||
|
||||
**Phase 4 - Spawn Synthesizer**: After final discussion round, create 1 synthesizer.
|
||||
|
||||
**Quick mode exception**: When depth=1, spawn single explorer, single analyst, single discussant, single synthesizer without numbered suffixes.
|
||||
|
||||
**Single spawn template** (worker template used for all roles):
|
||||
Coordinator spawns workers using this template:
|
||||
|
||||
```
|
||||
Agent({
|
||||
@@ -367,7 +75,7 @@ Agent({
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: <role>
|
||||
role_spec: .claude/skills/team-ultra-analyze/role-specs/<role>.md
|
||||
role_spec: .claude/skills/team-ultra-analyze/roles/<role>/role.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: ultra-analyze
|
||||
@@ -376,37 +84,34 @@ agent_name: <agent-name>
|
||||
inner_loop: false
|
||||
|
||||
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).`
|
||||
Execute built-in Phase 1 (task discovery, owner=<agent-name>) -> role Phase 2-4 -> built-in Phase 5 (report).`
|
||||
})
|
||||
```
|
||||
|
||||
## Team Configuration
|
||||
## User Commands
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| Team name | ultra-analyze |
|
||||
| Session directory | .workflow/.team/UAN-{slug}-{date}/ |
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| `check` / `status` | Output execution status diagram, do not advance pipeline |
|
||||
| `resume` / `continue` | Check worker status, advance to next pipeline step |
|
||||
|
||||
| Analysis dimensions | architecture, implementation, performance, security, concept, comparison, decision |
|
||||
| Max discussion rounds | 5 |
|
||||
|
||||
## Unified Session Directory
|
||||
## Session Directory
|
||||
|
||||
```
|
||||
.workflow/.team/UAN-{slug}-{YYYY-MM-DD}/
|
||||
+-- .msg/messages.jsonl # Message bus log
|
||||
+-- .msg/meta.json # Session metadata
|
||||
+-- discussion.md # Understanding evolution and discussion timeline
|
||||
+-- explorations/ # Explorer output
|
||||
+-- .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
|
||||
+-- analyses/ # Analyst output
|
||||
| +-- analysis-001.json
|
||||
| +-- analysis-002.json
|
||||
+-- discussions/ # Discussant output
|
||||
+-- discussions/ # Discussant output
|
||||
| +-- discussion-round-001.json
|
||||
+-- conclusions.json # Synthesizer output
|
||||
+-- wisdom/ # Cross-task knowledge
|
||||
+-- conclusions.json # Synthesizer output
|
||||
+-- wisdom/ # Cross-task knowledge
|
||||
| +-- learnings.md
|
||||
| +-- decisions.md
|
||||
| +-- conventions.md
|
||||
@@ -415,7 +120,7 @@ Execute built-in Phase 1 (task discovery, owner=<agent-name>) -> role-spec Phase
|
||||
|
||||
## Completion Action
|
||||
|
||||
When the pipeline completes (all tasks done, coordinator Phase 5):
|
||||
When pipeline completes, coordinator presents:
|
||||
|
||||
```
|
||||
AskUserQuestion({
|
||||
@@ -435,29 +140,21 @@ AskUserQuestion({
|
||||
| Choice | Action |
|
||||
|--------|--------|
|
||||
| Archive & Clean | Update session status="completed" -> TeamDelete() -> output final summary |
|
||||
| Keep Active | Update session status="paused" -> output resume instructions: `Skill(skill="team-ultra-analyze", args="resume")` |
|
||||
| Keep Active | Update session status="paused" -> output resume instructions |
|
||||
| Export Results | AskUserQuestion for target path -> copy deliverables -> Archive & Clean |
|
||||
|
||||
## Session Resume
|
||||
## Specs Reference
|
||||
|
||||
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
|
||||
- [specs/team-config.json](specs/team-config.json) — Team configuration and pipeline settings
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Resolution |
|
||||
|----------|------------|
|
||||
| Unknown --role value | Error with available role list |
|
||||
| Missing --role arg | Orchestration Mode -> coordinator |
|
||||
| Unknown --role value | Error with role registry list |
|
||||
| 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 |
|
||||
| Fast-advance conflict | Coordinator reconciles on next callback |
|
||||
| Completion action fails | Default to Keep Active |
|
||||
|
||||
90
.claude/skills/team-ultra-analyze/roles/analyst/role.md
Normal file
90
.claude/skills/team-ultra-analyze/roles/analyst/role.md
Normal file
@@ -0,0 +1,90 @@
|
||||
---
|
||||
role: analyst
|
||||
prefix: ANALYZE
|
||||
inner_loop: false
|
||||
additional_prefixes: [ANALYZE-fix]
|
||||
message_types:
|
||||
success: analysis_ready
|
||||
error: error
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| Exploration results | `<session>/explorations/*.json` | Yes |
|
||||
|
||||
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:
|
||||
|
||||
| Condition | Source |
|
||||
|-----------|--------|
|
||||
| Direction fix | Read ALL exploration files, merge context |
|
||||
| Normal ANALYZE-N | Read exploration matching number N |
|
||||
| Fallback | Read first available exploration file |
|
||||
|
||||
4. Select CLI tool by perspective:
|
||||
|
||||
| Perspective | CLI Tool | Rule Template |
|
||||
|-------------|----------|---------------|
|
||||
| technical | gemini | analysis-analyze-code-patterns |
|
||||
| architectural | claude | analysis-review-architecture |
|
||||
| business | codex | analysis-analyze-code-patterns |
|
||||
| domain_expert | gemini | analysis-analyze-code-patterns |
|
||||
| direction-fix (any) | gemini | analysis-diagnose-bug-root-cause |
|
||||
|
||||
## 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>`
|
||||
|
||||
## Phase 4: Result Aggregation
|
||||
|
||||
Write analysis output to `<session>/analyses/analysis-<num>.json`:
|
||||
|
||||
```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
|
||||
@@ -0,0 +1,73 @@
|
||||
# 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:
|
||||
|
||||
| Condition | Mode | Depth |
|
||||
|-----------|------|-------|
|
||||
| `--mode=quick` or topic contains "quick/overview/fast" | Quick | 1 |
|
||||
| `--mode=deep` or topic contains "deep/thorough/detailed/comprehensive" | Deep | N (from perspectives) |
|
||||
| Default (no match) | Standard | N (from perspectives) |
|
||||
|
||||
### Dimension Detection
|
||||
|
||||
Scan topic keywords to select analysis perspectives:
|
||||
|
||||
| Dimension | Keywords |
|
||||
|-----------|----------|
|
||||
| architecture | architecture, design, structure |
|
||||
| implementation | implement, code, source |
|
||||
| performance | performance, optimize, speed |
|
||||
| security | security, auth, vulnerability |
|
||||
| concept | concept, theory, principle |
|
||||
| comparison | compare, vs, difference |
|
||||
| decision | decision, choice, tradeoff |
|
||||
|
||||
**Depth** = number of selected perspectives. Quick mode always uses depth=1.
|
||||
|
||||
## Pipeline Mode Rules
|
||||
|
||||
| Mode | Task Structure |
|
||||
|------|----------------|
|
||||
| quick | EXPLORE-001 -> ANALYZE-001 -> SYNTH-001 (serial, depth=1) |
|
||||
| standard | EXPLORE-001..N (parallel) -> ANALYZE-001..N (parallel) -> DISCUSS-001 -> SYNTH-001 |
|
||||
| deep | Same as standard but SYNTH-001 omitted (created dynamically after discussion loop) |
|
||||
|
||||
## Output
|
||||
|
||||
Write analysis config to coordinator state (not a file), to be used by dispatch.md:
|
||||
|
||||
```json
|
||||
{
|
||||
"pipeline_mode": "<quick|standard|deep>",
|
||||
"depth": <number>,
|
||||
"perspectives": ["<perspective1>", "<perspective2>"],
|
||||
"topic": "<original topic>",
|
||||
"dimensions": ["<dim1>", "<dim2>"]
|
||||
}
|
||||
```
|
||||
|
||||
## Complexity Scoring
|
||||
|
||||
| Factor | Points |
|
||||
|--------|--------|
|
||||
| Per perspective | +1 |
|
||||
| Deep mode | +2 |
|
||||
| Cross-domain (3+ perspectives) | +1 |
|
||||
|
||||
Results: 1-3 Quick, 4-6 Standard, 7+ Deep (if not explicitly set)
|
||||
|
||||
## Discussion Loop Configuration
|
||||
|
||||
| Mode | Max Discussion Rounds |
|
||||
|------|----------------------|
|
||||
| quick | 0 |
|
||||
| standard | 1 |
|
||||
| deep | 5 |
|
||||
@@ -36,16 +36,6 @@ When coordinator needs to execute a command (dispatch, monitor):
|
||||
3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
|
||||
4. **Execute synchronously** -- complete the command workflow before proceeding
|
||||
|
||||
Example:
|
||||
```
|
||||
Phase 3 needs task dispatch
|
||||
-> Read roles/coordinator/commands/dispatch.md
|
||||
-> Execute Phase 2 (Context Loading)
|
||||
-> Execute Phase 3 (Task Chain Creation)
|
||||
-> Execute Phase 4 (Validation)
|
||||
-> Continue to Phase 4
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Entry Router
|
||||
@@ -54,12 +44,12 @@ When coordinator is invoked, detect invocation type:
|
||||
|
||||
| Detection | Condition | Handler |
|
||||
|-----------|-----------|---------|
|
||||
| Worker callback | Message contains role tag [explorer], [analyst], [discussant], [synthesizer] | -> handleCallback |
|
||||
| Status check | Arguments contain "check" or "status" | -> handleCheck |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
|
||||
| Pipeline complete | All tasks have status "completed" | -> handleComplete |
|
||||
| Interrupted session | Active/paused session exists | -> Phase 0 (Session Resume Check) |
|
||||
| New session | None of above | -> Phase 1 (Topic Understanding) |
|
||||
| Worker callback | Message contains role tag [explorer], [analyst], [discussant], [synthesizer] | -> handleCallback (monitor.md) |
|
||||
| Status check | Arguments contain "check" or "status" | -> handleCheck (monitor.md) |
|
||||
| Manual resume | Arguments contain "resume" or "continue" | -> handleResume (monitor.md) |
|
||||
| Pipeline complete | All tasks have status "completed" | -> handleComplete (monitor.md) |
|
||||
| Interrupted session | Active/paused session exists | -> Phase 0 |
|
||||
| New session | None of above | -> Phase 1 |
|
||||
|
||||
For callback/check/resume/complete: load `commands/monitor.md` and execute matched handler, then STOP.
|
||||
|
||||
@@ -85,12 +75,7 @@ For callback/check/resume/complete: load `commands/monitor.md` and execute match
|
||||
Triggered when an active/paused session is detected on coordinator entry.
|
||||
|
||||
1. Load session.json from detected session folder
|
||||
2. Audit task list:
|
||||
|
||||
```
|
||||
TaskList()
|
||||
```
|
||||
|
||||
2. Audit task list: `TaskList()`
|
||||
3. Reconcile session state vs task status:
|
||||
|
||||
| Task Status | Session Expects | Action |
|
||||
@@ -99,42 +84,19 @@ TaskList()
|
||||
| completed | Already tracked | Skip |
|
||||
| pending + unblocked | Ready to run | Include in spawn list |
|
||||
|
||||
4. Rebuild team if not active:
|
||||
|
||||
```
|
||||
TeamCreate({ team_name: "ultra-analyze" })
|
||||
```
|
||||
|
||||
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. **Pipeline mode selection**:
|
||||
|
||||
| Condition | Mode | Depth |
|
||||
|-----------|------|-------|
|
||||
| `--mode=quick` or topic contains "quick/overview/fast" | Quick | 1 |
|
||||
| `--mode=deep` or topic contains "deep/thorough/detailed/comprehensive" | Deep | N (from perspectives) |
|
||||
| Default | Standard | N (from perspectives) |
|
||||
|
||||
4. **Dimension detection** (from topic keywords):
|
||||
|
||||
| Dimension | Keywords |
|
||||
|-----------|----------|
|
||||
| architecture | architecture, design, structure |
|
||||
| implementation | implement, code |
|
||||
| performance | performance, optimize |
|
||||
| security | security, auth |
|
||||
| concept | concept, theory |
|
||||
| comparison | compare, vs |
|
||||
| decision | decision, choice |
|
||||
|
||||
5. **Interactive clarification** (non-auto mode): AskUserQuestion for focus, perspectives, depth.
|
||||
3. Delegate to `commands/analyze.md` for signal detection and pipeline mode selection
|
||||
4. **Interactive clarification** (non-auto mode): AskUserQuestion for focus, perspectives, depth.
|
||||
|
||||
---
|
||||
|
||||
@@ -156,9 +118,8 @@ TeamCreate({ team_name: "ultra-analyze" })
|
||||
```
|
||||
|
||||
3. Write session.json with mode, requirement, timestamp
|
||||
4. Initialize .msg/meta.json with pipeline metadata:
|
||||
4. Initialize .msg/meta.json with pipeline metadata via team_msg:
|
||||
```typescript
|
||||
// Use team_msg to write pipeline metadata to .msg/meta.json
|
||||
mcp__ccw-tools__team_msg({
|
||||
operation: "log",
|
||||
session_id: "<session-id>",
|
||||
@@ -173,7 +134,6 @@ mcp__ccw-tools__team_msg({
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
5. Call `TeamCreate({ team_name: "ultra-analyze" })`
|
||||
|
||||
---
|
||||
@@ -181,7 +141,6 @@ mcp__ccw-tools__team_msg({
|
||||
## 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
|
||||
@@ -192,38 +151,16 @@ Execute `commands/dispatch.md` inline (Command Execution Protocol):
|
||||
|
||||
### Initial Spawn
|
||||
|
||||
Find first unblocked tasks and spawn their workers:
|
||||
|
||||
```
|
||||
Agent({
|
||||
subagent_type: "team-worker",
|
||||
description: "Spawn explorer worker",
|
||||
team_name: "ultra-analyze",
|
||||
name: "explorer",
|
||||
run_in_background: true,
|
||||
prompt: `## Role Assignment
|
||||
role: explorer
|
||||
role_spec: .claude/skills/team-ultra-analyze/role-specs/explorer.md
|
||||
session: <session-folder>
|
||||
session_id: <session-id>
|
||||
team_name: ultra-analyze
|
||||
requirement: <topic-description>
|
||||
inner_loop: false
|
||||
|
||||
Read role_spec file to load Phase 2-4 domain instructions.
|
||||
Execute built-in Phase 1 -> role-spec Phase 2-4 -> built-in Phase 5.`
|
||||
})
|
||||
```
|
||||
Find first unblocked tasks and spawn their workers. Use SKILL.md Worker Spawn Template with:
|
||||
- `role_spec: .claude/skills/team-ultra-analyze/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:
|
||||
|
||||
- handleCallback -> mark task done -> check pipeline -> handleSpawnNext
|
||||
- handleSpawnNext -> find ready tasks -> spawn team-worker agents -> STOP
|
||||
- handleComplete -> all done -> Phase 5
|
||||
All subsequent coordination is handled by `commands/monitor.md` handlers triggered by worker callbacks.
|
||||
|
||||
---
|
||||
|
||||
@@ -247,7 +184,7 @@ All subsequent coordination is handled by `commands/monitor.md` handlers trigger
|
||||
```
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "Team pipeline complete. What would you like to do?",
|
||||
question: "Ultra-Analyze pipeline complete. What would you like to do?",
|
||||
header: "Completion",
|
||||
multiSelect: false,
|
||||
options: [
|
||||
@@ -259,13 +196,7 @@ AskUserQuestion({
|
||||
})
|
||||
```
|
||||
|
||||
6. Handle user choice:
|
||||
|
||||
| Choice | Steps |
|
||||
|--------|-------|
|
||||
| Archive & Clean | TaskList -> verify all completed -> update session status="completed" -> TeamDelete() -> output final summary |
|
||||
| Keep Active | Update session status="paused" -> output resume instructions |
|
||||
| Export Results | AskUserQuestion for target directory -> copy artifacts -> Archive & Clean |
|
||||
6. Handle user choice per SKILL.md Completion Action section.
|
||||
|
||||
---
|
||||
|
||||
|
||||
107
.claude/skills/team-ultra-analyze/roles/discussant/role.md
Normal file
107
.claude/skills/team-ultra-analyze/roles/discussant/role.md
Normal file
@@ -0,0 +1,107 @@
|
||||
---
|
||||
role: discussant
|
||||
prefix: DISCUSS
|
||||
inner_loop: false
|
||||
message_types:
|
||||
success: discussion_processed
|
||||
error: error
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| Analysis results | `<session>/analyses/*.json` | Yes |
|
||||
| Exploration results | `<session>/explorations/*.json` | No |
|
||||
|
||||
1. Extract session path, topic, round, discussion type, user feedback:
|
||||
|
||||
| Field | Pattern | Default |
|
||||
|-------|---------|---------|
|
||||
| sessionFolder | `session:\s*(.+)` | required |
|
||||
| topic | `topic:\s*(.+)` | required |
|
||||
| round | `round:\s*(\d+)` | 1 |
|
||||
| discussType | `type:\s*(.+)` | "initial" |
|
||||
| userFeedback | `user_feedback:\s*(.+)` | empty |
|
||||
|
||||
2. Read all analysis and exploration results
|
||||
3. Aggregate current findings, insights, open questions
|
||||
|
||||
## Phase 3: Discussion Processing
|
||||
|
||||
Select strategy by discussion type:
|
||||
|
||||
| Type | Mode | Description |
|
||||
|------|------|-------------|
|
||||
| initial | inline | Aggregate all analyses: convergent themes, conflicts, top discussion points |
|
||||
| deepen | cli | Use CLI tool to investigate open questions deeper |
|
||||
| direction-adjusted | cli | Re-analyze via `ccw cli` from adjusted perspective |
|
||||
| specific-questions | cli | Targeted exploration answering user questions |
|
||||
|
||||
**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:
|
||||
```javascript
|
||||
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:
|
||||
```javascript
|
||||
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:
|
||||
```javascript
|
||||
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`:
|
||||
```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`:
|
||||
```markdown
|
||||
### 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
|
||||
74
.claude/skills/team-ultra-analyze/roles/explorer/role.md
Normal file
74
.claude/skills/team-ultra-analyze/roles/explorer/role.md
Normal file
@@ -0,0 +1,74 @@
|
||||
---
|
||||
role: explorer
|
||||
prefix: EXPLORE
|
||||
inner_loop: false
|
||||
message_types:
|
||||
success: exploration_ready
|
||||
error: error
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
|
||||
1. Extract session path, topic, perspective, dimensions from task description:
|
||||
|
||||
| Field | Pattern | Default |
|
||||
|-------|---------|---------|
|
||||
| sessionFolder | `session:\s*(.+)` | required |
|
||||
| topic | `topic:\s*(.+)` | required |
|
||||
| perspective | `perspective:\s*(.+)` | "general" |
|
||||
| dimensions | `dimensions:\s*(.+)` | "general" |
|
||||
|
||||
2. Determine exploration number from task subject (EXPLORE-N)
|
||||
3. Build exploration strategy by perspective:
|
||||
|
||||
| Perspective | Focus | Search Depth |
|
||||
|-------------|-------|-------------|
|
||||
| general | Overall codebase structure and patterns | broad |
|
||||
| technical | Implementation details, code patterns, feasibility | medium |
|
||||
| architectural | System design, module boundaries, interactions | broad |
|
||||
| business | Business logic, domain models, value flows | medium |
|
||||
| domain_expert | Domain patterns, standards, best practices | deep |
|
||||
|
||||
## Phase 3: Codebase Exploration
|
||||
|
||||
Use CLI tool for codebase exploration:
|
||||
|
||||
```javascript
|
||||
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):
|
||||
```javascript
|
||||
mcp__ace-tool__search_context({ project_root_path: ".", query: "<topic> <perspective>" })
|
||||
```
|
||||
|
||||
## Phase 4: Result Validation
|
||||
|
||||
| Check | Method | Action on Failure |
|
||||
|-------|--------|-------------------|
|
||||
| Output file exists | Read output path | Create empty result, run ACE fallback |
|
||||
| Has relevant_files | Array length > 0 | Trigger ACE supplementary search |
|
||||
| Has key_findings | Array length > 0 | Note partial results, proceed |
|
||||
|
||||
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
|
||||
78
.claude/skills/team-ultra-analyze/roles/synthesizer/role.md
Normal file
78
.claude/skills/team-ultra-analyze/roles/synthesizer/role.md
Normal file
@@ -0,0 +1,78 @@
|
||||
---
|
||||
role: synthesizer
|
||||
prefix: SYNTH
|
||||
inner_loop: false
|
||||
message_types:
|
||||
success: synthesis_ready
|
||||
error: error
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
| Input | Source | Required |
|
||||
|-------|--------|----------|
|
||||
| Task description | From task subject/description | Yes |
|
||||
| Session path | Extracted from task description | Yes |
|
||||
| All artifacts | `<session>/explorations/*.json`, `analyses/*.json`, `discussions/*.json` | Yes |
|
||||
| Decision trail | From wisdom/.msg/meta.json | No |
|
||||
|
||||
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:
|
||||
|
||||
| Condition | Strategy |
|
||||
|-----------|----------|
|
||||
| Single analysis, no discussions | simple (Quick mode summary) |
|
||||
| Multiple analyses, >2 discussion rounds | deep (track evolution) |
|
||||
| Default | standard (cross-perspective integration) |
|
||||
|
||||
## 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:
|
||||
|
||||
| Level | Criteria |
|
||||
|-------|----------|
|
||||
| High | Multiple sources confirm, strong evidence |
|
||||
| Medium | Single source or partial evidence |
|
||||
| Low | Speculative, needs verification |
|
||||
|
||||
**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`:
|
||||
```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`:
|
||||
```markdown
|
||||
## 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
|
||||
64
.claude/skills/team-ultra-analyze/specs/pipelines.md
Normal file
64
.claude/skills/team-ultra-analyze/specs/pipelines.md
Normal file
@@ -0,0 +1,64 @@
|
||||
# Pipeline Definitions — Team Ultra Analyze
|
||||
|
||||
## Pipeline Modes
|
||||
|
||||
### Quick Mode (3 tasks, serial)
|
||||
|
||||
```
|
||||
EXPLORE-001 -> ANALYZE-001 -> SYNTH-001
|
||||
```
|
||||
|
||||
| Task | Role | Dependencies |
|
||||
|------|------|-------------|
|
||||
| EXPLORE-001 | explorer | (none) |
|
||||
| ANALYZE-001 | analyst | EXPLORE-001 |
|
||||
| SYNTH-001 | synthesizer | ANALYZE-001 |
|
||||
|
||||
### Standard Mode (2N+2 tasks, parallel windows)
|
||||
|
||||
```
|
||||
[EXPLORE-001..N](parallel) -> [ANALYZE-001..N](parallel) -> DISCUSS-001 -> SYNTH-001
|
||||
```
|
||||
|
||||
| Task | Role | Dependencies |
|
||||
|------|------|-------------|
|
||||
| EXPLORE-001..N | explorer | (none, parallel) |
|
||||
| ANALYZE-001..N | analyst | corresponding EXPLORE-N |
|
||||
| DISCUSS-001 | discussant | all ANALYZE tasks |
|
||||
| SYNTH-001 | synthesizer | DISCUSS-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
|
||||
|
||||
| Task ID | Role | Dependencies | Description |
|
||||
|---------|------|-------------|-------------|
|
||||
| EXPLORE-1..depth | explorer | (none) | Parallel codebase exploration, one per perspective |
|
||||
| ANALYZE-1..depth | analyst | EXPLORE-1..depth (all) | Parallel deep analysis, one per perspective |
|
||||
| DISCUSS-001 | discussant | ANALYZE-1..depth (all) | Process analysis results, identify gaps |
|
||||
| ANALYZE-fix-N | analyst | DISCUSS-N | Re-analysis for adjusted focus (Deep mode) |
|
||||
| DISCUSS-002..N | discussant | ANALYZE-fix-N | Subsequent discussion rounds (Deep mode, max 5) |
|
||||
| SYNTH-001 | synthesizer | Last DISCUSS-N | Cross-perspective integration and conclusions |
|
||||
|
||||
## Discussion Loop Control
|
||||
|
||||
| Mode | Max Rounds | Trigger |
|
||||
|------|-----------|---------|
|
||||
| quick | 0 | No discussion |
|
||||
| standard | 1 | After DISCUSS-001 |
|
||||
| deep | 5 | After each DISCUSS-N |
|
||||
|
||||
## 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 |
|
||||
Reference in New Issue
Block a user