diff --git a/.claude/skills/team-coordinate-v2/SKILL.md b/.claude/skills/team-coordinate-v2/SKILL.md index db45c2f1..d42fc418 100644 --- a/.claude/skills/team-coordinate-v2/SKILL.md +++ b/.claude/skills/team-coordinate-v2/SKILL.md @@ -8,15 +8,6 @@ allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), Task Universal team coordination skill: analyze task -> generate role-specs -> dispatch -> execute -> deliver. Only the **coordinator** is built-in. All worker roles are **dynamically generated** as lightweight role-spec files and spawned via the `team-worker` agent. -## Key Changes from v1 - -| Change | Before (v1) | After (v2) | Impact | -|--------|------------|------------|--------| -| Worker agent | general-purpose + Skill load | team-worker agent (dedicated) | Eliminates Skill indirection | -| Role definitions | `/roles/.md` (~250 lines, includes Phase 1/5) | `/role-specs/.md` (~80 lines, Phase 2-4 only) | -68% worker content | -| Shared behavior | Duplicated in SKILL.md + each role.md | Built into team-worker agent | Single source of truth | -| Coordinator spawn | Skill(team-coordinate, --role=xxx) | Task(team-worker, role_spec=xxx.md) | Direct, no Skill call | -| Completion | Manual cleanup | Interactive completion action | Archive/Keep/Export prompt | ## Architecture diff --git a/.claude/skills/team-executor-v2/SKILL.md b/.claude/skills/team-executor-v2/SKILL.md index e05c1aec..b812702a 100644 --- a/.claude/skills/team-executor-v2/SKILL.md +++ b/.claude/skills/team-executor-v2/SKILL.md @@ -8,15 +8,6 @@ allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), Task Lightweight session execution skill: load session -> reconcile state -> spawn team-worker agents -> execute -> deliver. **No analysis, no role generation** -- only executes existing team-coordinate sessions. -## Key Changes from v1 - -| Change | Before (v1) | After (v2) | Impact | -|--------|------------|------------|--------| -| Worker agent | general-purpose + Skill load | team-worker agent (dedicated) | Eliminates Skill indirection | -| Role loading | `/roles/.md` (full role.md) | `/role-specs/.md` (Phase 2-4 only) | Lighter validation | -| Shared behavior | Duplicated in SKILL.md | Built into team-worker agent | Single source of truth | -| Executor spawn | Skill(team-executor, --role=xxx) | Task(team-worker, role_spec=xxx.md) | Direct, no Skill call | -| Completion | Manual cleanup | Interactive completion action | Archive/Keep/Export prompt | ## Architecture diff --git a/.claude/skills/team-lifecycle-v4/SKILL.md b/.claude/skills/team-lifecycle-v4/SKILL.md index df609a1c..d07fbcb7 100644 --- a/.claude/skills/team-lifecycle-v4/SKILL.md +++ b/.claude/skills/team-lifecycle-v4/SKILL.md @@ -8,15 +8,6 @@ allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), Task Unified team skill: specification -> implementation -> testing -> review. Optimized from v3 with **inline discuss subagent** and **shared explore utility**, halving spec pipeline beats from 12 to 6. -## Key Changes from v3 - -| Change | Before (v3) | After (v4) | Impact | -|--------|------------|------------|--------| -| Discuss | Standalone role, 6 separate beats | Inline subagent called by produce roles | Spec beats: 12 -> 6 | -| Explorer | Standalone service role | Shared Explore subagent with cache | Eliminates spawn overhead | -| Explore cache | Per-role, no sharing | Centralized `explorations/` with cache-index | Avoids duplicate exploration | -| Worker advance | Always callback coordinator | Fast-advance for simple successors | Fewer coordinator wakes | - ## Architecture ``` diff --git a/.claude/skills/team-lifecycle-v5/SKILL.md b/.claude/skills/team-lifecycle-v5/SKILL.md index 0d7331c6..86a218a8 100644 --- a/.claude/skills/team-lifecycle-v5/SKILL.md +++ b/.claude/skills/team-lifecycle-v5/SKILL.md @@ -8,15 +8,6 @@ allowed-tools: TeamCreate(*), TeamDelete(*), SendMessage(*), TaskCreate(*), Task Unified team skill: specification -> implementation -> testing -> review. Built on **team-worker agent architecture** — all worker roles share a single agent definition with role-specific Phase 2-4 loaded from markdown specs. -## Key Changes from v4 - -| Change | Before (v4) | After (v5) | Impact | -|--------|------------|------------|--------| -| Worker agent | general-purpose + Skill load | team-worker agent (dedicated) | Eliminates Skill indirection | -| Role definitions | roles/xxx/role.md (~250 lines, 60% shared) | role-specs/xxx.md (~80 lines, Phase 2-4 only) | -64% worker content | -| Shared behavior | Duplicated in each role.md | Built into team-worker agent | Single source of truth | -| Coordinator spawn | Skill(team-lifecycle-v4, --role=xxx) | Task(team-worker, role_spec=xxx.md) | Direct, no Skill call | - ## Architecture ``` diff --git a/CHANGELOG.md b/CHANGELOG.md index 716c72b0..388500f3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,127 @@ All notable changes to Claude Code Workflow (CCW) will be documented in this fil The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [7.0.0] - 2026-02-27 + +### ✨ New Features | 新功能 + +#### Major Architecture Updates | 架构重大更新 +- **Added**: team-coordinate-v2 / team-executor-v2 with team-worker agent architecture | 添加 team-coordinate-v2 / team-executor-v2，引入 team-worker 代理架构 +- **Added**: team-lifecycle-v5 with unified team-worker agent and role-spec files | 添加 team-lifecycle-v5，统一 team-worker 代理和角色规范文件 +- **Added**: Phase-based execution model (Phase 1-5 built-in, Phase 2-4 role-specific) | 添加基于阶段的执行模型（阶段1-5内置，阶段2-4角色特定） +- **Added**: Inner loop framework for processing multiple same-prefix tasks | 添加内循环框架，用于处理多个相同前缀任务 +- **Added**: Discuss and Explore subagents for multi-perspective critique and code exploration | 添加 Discuss 和 Explore 子代理，用于多视角批判和代码探索 +- **Added**: Wisdom accumulation system (learnings.md, decisions.md, conventions.md, issues.md) | 添加智慧积累系统 +- **Added**: Message bus protocol with team coordination | 添加消息总线协议和团队协调 + +#### Queue Scheduler Service | 队列调度服务 +- **Added**: Background queue execution service with API endpoints | 添加后台队列执行服务和 API 端点 +- **Added**: QueueItemExecutor for unified execution handling | 添加 QueueItemExecutor 统一执行处理 +- **Added**: CLI execution settings integration | 添加 CLI 执行设置集成 + +#### Workflow Session Commands | 工作流会话命令 +- **Added**: `workflow:session:start` command for starting new workflow sessions | 添加启动新工作流会话的命令 +- **Added**: `workflow:session:resume` command for resuming paused sessions | 添加恢复暂停会话的命令 +- **Added**: `workflow:session:complete` command for marking sessions complete | 添加标记会话完成的命令 +- **Added**: `workflow:session:sync` command with auto-sync integration | 添加会话同步命令及自动同步集成 + +#### Spec Management | 规范管理 +- **Added**: Category and scope filtering for enhanced organization | 添加分类和范围过滤以增强组织 +- **Added**: SpecContentDialog component for viewing and editing spec content | 添加规范内容对话框组件 +- **Added**: SpecDialog component for editing spec frontmatter | 添加规范前言编辑对话框组件 +- **Enhanced**: Spec management with hooks integration and settings configuration | 增强规范管理，集成钩子和设置配置 + +#### Analysis Viewer Page | 分析查看器页面 +- **Added**: Analysis viewer page with grid layout for analysis sessions | 添加分析查看器页面，采用网格布局 +- **Added**: Filtering capabilities and fullscreen mode | 添加过滤功能和全屏模式 +- **Added**: Pagination support and concurrent processing | 添加分页支持和并发处理 + +#### Terminal Dashboard | 终端仪表板 +- **Added**: Terminal Dashboard with multi-terminal grid layout | 添加多终端网格布局的终端仪表板 +- **Added**: Execution monitor panel with agent list | 添加带代理列表的执行监控面板 +- **Added**: Pane/session management with improved UX | 添加窗格/会话管理，改进用户体验 +- **Simplified**: CLI launch to dialog-only mode | 简化 CLI 启动为仅对话框模式 + +#### Orchestrator Template Editor | 编排器模板编辑器 +- **Redesigned**: Orchestrator page as template editor with terminal execution | 重新设计编排器页面为模板编辑器，支持终端执行 +- **Added**: Slash command functionality | 添加斜杠命令功能 +- **Added**: Wave-based execution with PlanEx roles | 添加基于波浪的执行和 PlanEx 角色 +- **Added**: Observability panel and LSP document caching | 添加可观测性面板和 LSP 文档缓存 + +#### Skill Hub | 技能中心 +- **Added**: Skill Hub for managing community skills | 添加管理社区技能的技能中心 +- **Added**: Skill CRUD operations with remote skill index | 添加技能 CRUD 操作和远程技能索引 +- **Added**: Standalone repository for community skills | 添加社区技能的独立仓库 + +#### CLI Multi-Provider Support | CLI 多提供商支持 +- **Added**: Multi-provider configuration for Claude, Codex, and Gemini | 添加 Claude、Codex 和 Gemini 的多提供商配置 +- **Added**: CLI config preview API for Codex and Gemini | 添加 Codex 和 Gemini 的 CLI 配置预览 API +- **Added**: Effort level configuration for Claude CLI | 添加 Claude CLI 的努力级别配置 + +#### A2UI (Agent-to-User Interface) | 代理到用户界面 +- **Enhanced**: A2UI with multi-select questions and RadioGroup component | 增强 A2UI，支持多选问题和单选组组件 +- **Added**: Markdown support and Sheet/drawer components | 添加 Markdown 支持和工作表/抽屉组件 +- **Added**: WebSocket integration for real-time communication | 添加 WebSocket 集成用于实时通信 + +#### Documentation Templates | 文档模板 +- **Added**: Templates for architecture documents, epics, product briefs, and requirements PRD | 添加架构文档、史诗、产品简介和需求 PRD 模板 +- **Added**: Roadmap generation with CLI roadmap planning agent | 添加使用 CLI 路线图规划代理生成路线图 + +### 💥 Breaking Changes | 破坏性变更 + +#### Removed Features | 移除的功能 +- **Removed**: Vanilla JS/CSS frontend - React SPA is now the sole entry point | 移除原生 JS/CSS 前端，React SPA 现为唯一入口点 +- **Removed**: Issue management skills (`issue-discover`, `issue-new`, `issue-plan`, `issue-queue`) - replaced by unified `issue-devpipeline` | 移除 issue 管理技能，由统一的 `issue-devpipeline` 替代 +- **Removed**: VSCode Bridge (`ccw-vscode-bridge`) | 移除 VSCode 桥接器 +- **Removed**: Executions tab from Issue Hub | 移除 Issue Hub 中的执行标签页 +- **Removed**: Sessions Panel from Terminal Dashboard | 移除终端仪表板中的会话面板 +- **Removed**: Obsolete commands (TDD coverage, test concept enhancement, context gathering, task generation) | 移除过时命令 +- **Removed**: Obsolete spec dimensions from schema | 移除架构模式中的过时维度 +- **Removed**: skills_lib from remote tracking | 从远程跟踪中移除 skills_lib + +#### Behavior Changes | 行为变更 +- **Changed**: Team message protocol from `team-name` to `session-id` in team_msg calls | 更改 team_msg 调用从 `team-name` 到 `session-id` +- **Changed**: Codex skill execution to serial execution, removed agent/CLI delegation | 更改 Codex 技能执行为串行执行，移除代理/CLI 委托 +- **Changed**: Session artifacts - removed redundant `issues.jsonl` and `execution-plan.json` | 更改会话构件，移除冗余文件 +- **Changed**: Workflow execute - merged 10 team commands into unified `team-lifecycle` skill | 更改工作流执行，合并 10 个团队命令到统一的 `team-lifecycle` 技能 + +### 🛠️ Improvements | 改进 + +#### Performance | 性能 +- **Improved**: LSP document caching for faster symbol lookup | 改进 LSP 文档缓存，加快符号查找 +- **Improved**: Concurrent analysis processing with parallel session handling | 改进并发分析处理，支持并行会话处理 +- **Improved**: Queue execution service with background task processing | 改进队列执行服务，支持后台任务处理 +- **Improved**: AST-based indexing for static code analysis | 改进基于 AST 的索引，用于静态代码分析 + +#### CodexLens Enhancements | CodexLens 增强 +- **Enhanced**: CodexLens frontend integration with reranker configuration UI | 增强 CodexLens 前端集成和重排序器配置 UI +- **Added**: CCW-LiteLLM installation progress overlay | 添加 CCW-LiteLLM 安装进度叠加层 +- **Added**: Staged settings for advanced configuration | 添加高级配置的分阶段设置 + +### 🔒 Security | 安全 + +#### Critical Fixes | 关键修复 +- **Fixed**: Path traversal attack prevention in session handling | 修复会话处理中的路径遍历攻击防护 +- **Fixed**: CSRF protection across all API calls with csrfFetch | 修复所有 API 调用的 CSRF 保护 +- **Added**: CSRF token fallback mechanism with regression tests | 添加 CSRF 令牌回退机制及回归测试 + +### 📚 Documentation | 文档 + +- **Added**: New architecture documentation for team-lifecycle-v5 | 添加 team-lifecycle-v5 的新架构文档 +- **Added**: Updated command references for workflow session commands | 更新工作流会话命令的命令参考 +- **Added**: Enhanced workflow guides with migration instructions | 添加带迁移说明的增强工作流指南 +- **Added**: New skill templates and examples | 添加新技能模板和示例 +- **Added**: Chinese localization for all new features | 为所有新功能添加中文本地化 + +### 🧪 Testing | 测试 + +- **Added**: Integration tests for command creation | 添加命令创建的集成测试 +- **Added**: E2E tests for Graph Explorer, History, and Orchestrator | 添加 Graph Explorer、History 和 Orchestrator 的端到端测试 +- **Added**: Regression tests for CSRF handling | 添加 CSRF 处理的回归测试 +- **Enhanced**: Test coverage across all modules | 增强所有模块的测试覆盖率 + +--- + ## [6.3.49] - 2026-01-28 ### ✨ New Features | 新功能 diff --git a/COMMAND_REFERENCE.md b/COMMAND_REFERENCE.md index 9dcbf8ed..4784893f 100644 --- a/COMMAND_REFERENCE.md +++ b/COMMAND_REFERENCE.md @@ -2,7 +2,7 @@ This document provides a comprehensive reference for all commands available in the Claude Code Workflow (CCW) system. -> **Version 6.2.0 Update**: Native CodexLens code intelligence (FTS + Semantic + HNSW), new Dashboard views (CLAUDE.md Manager, Skills Manager, Graph Explorer, Core Memory), CLI refactored to `ccw cli -p`, session clustering for intelligent memory, TypeScript backend migration. +> **Version 7.0.0 Update**: team-coordinate-v2/team-executor-v2/team-lifecycle-v5 architecture with unified team-worker agent, workflow session commands (start/resume/complete/sync), queue scheduler service, spec management enhancements, CLI multi-provider support, analysis viewer page, security enhancements, skill hub, terminal dashboard, orchestrator template editor, A2UI multi-select questions. ## CLI Commands (`/cli:*`) @@ -24,6 +24,8 @@ These commands orchestrate complex, multi-phase development processes, from plan | `/workflow:session:list` | List all workflow sessions with status. | | `/workflow:session:resume` | Resume the most recently paused workflow session. | | `/workflow:session:complete` | Mark the active workflow session as complete and remove active flag. | +| `/workflow:session:sync` | ⚡ **NEW** Sync workflow session state to disk during execution. | +| `/workflow:session:solidify` | ⚡ **NEW** Solidify workflow session artifacts and prepare for archiving. | ### Core Workflow @@ -127,6 +129,36 @@ Commands for managing individual tasks within a workflow session. | `/task:execute` | Execute tasks with appropriate agents and context-aware orchestration. | | `/task:replan` | ⚠️ **DEPRECATED** Use `/workflow:replan` instead. Legacy command for task replanning (maintained for backward compatibility). | +## Issue Commands (`/issue:*`) + +Commands for issue discovery, planning, and execution management. + +### Issue Discovery & Creation + +| Command | Description | +|---|---| +| `/issue:discover` | ⚡ **NEW** Discover issues from codebase analysis and error patterns. | +| `/issue:discover-by-prompt` | ⚡ **NEW** Discover issues based on natural language prompt description. | +| `/issue:new` | ⚡ **NEW** Create structured issue with title, context, priority, and labels. | + +### Issue Planning & Queue + +| Command | Description | +|---|---| +| `/issue:plan` | ⚡ **NEW** Generate solution plan for specified issue with task breakdown. | +| `/issue:queue` | ⚡ **NEW** Form execution queue from planned issues and tasks. | +| `/issue:execute` | ⚡ **NEW** Execute tasks from issue queue with orchestration. | +| `/issue:convert-to-plan` | ⚡ **NEW** Convert issue to executable implementation plan. | +| `/issue:from-brainstorm` | ⚡ **NEW** Create issue from brainstorming session artifacts. | + +### Issue Management + +| Command | Description | +|---|---| +| `/issue:manage` | ⚡ **NEW** Interactive issue management with menu-driven CRUD operations. | + +> **Note**: Issue commands use the `ccw issue` CLI endpoints for data storage and retrieval. + ## Memory and Versioning Commands | Command | Description | @@ -145,3 +177,57 @@ Commands for managing individual tasks within a workflow session. | `/version` | Display version information and check for updates. | | `/enhance-prompt` | Context-aware prompt enhancement using session memory and codebase analysis. | +## Team Skills + +Unified team coordination and execution skills with role-spec based architecture. + +### Core Team Skills (v5/v2) + +| Skill | Description | +|-------|-------------| +| `team-lifecycle-v5` | ⚡ **NEW** Unified team skill for full lifecycle (spec/impl/test/review) with team-worker agent architecture. Roles: analyst, writer, planner, executor, tester, reviewer, architect, fe-developer, fe-qa. | +| `team-coordinate-v2` | ⚡ **NEW** Universal team coordination with dynamic role generation. Generates role-specs at runtime and spawns team-worker agents. | +| `team-executor-v2` | ⚡ **NEW** Lightweight session execution - resumes existing team-coordinate-v2 sessions for pure execution. | + +### V4/V3 Team Skills (Maintained) + +| Skill | Description | +|-------|-------------| +| `team-lifecycle-v4` | Previous version lifecycle skill. Maintained for backward compatibility. | +| `team-lifecycle-v3` | Earlier version lifecycle skill. Maintained for backward compatibility. | +| `team-coordinate` | Original team coordinator. Use `team-coordinate-v2` for new projects. | +| `team-executor` | Original team executor. Use `team-executor-v2` for new projects. | + +### Specialized Team Skills + +| Skill | Description | +|-------|-------------| +| `team-brainstorm` | Multi-role brainstorming with role-specific analysis generation. | +| `team-issue` | Issue-driven development pipeline with discover, plan, and execute phases. | +| `team-iterdev` | Iterative development workflow with planning, implementation, and testing cycles. | +| `team-planex` | Planning and execution workflow with wave-based task management. | +| `team-frontend` | Frontend-specific development workflow with UI design and QA cycles. | +| `team-quality-assurance` | Quality assurance and testing workflow. | +| `team-roadmap-dev` | Roadmap development and management workflow. | +| `team-tech-debt` | Technical debt identification and remediation workflow. | +| `team-testing` | Comprehensive testing workflow. | +| `team-uidesign` | UI/UX design workflow with style extraction and prototyping. | +| `team-ultra-analyze` | Deep codebase analysis with multi-angle exploration. | +| `team-review` | Multi-dimensional code review workflow. | + +### Deprecated Team Skills + +| Skill | Status | Replacement | +|-------|--------|-------------| +| Various team commands (team-planex, team-iterdev, etc.) | ⚠️ **DEPRECATED** | Use `team-lifecycle-v5` for unified lifecycle management. | + +## Internal Tools (Deprecated) + +| Command | Description | +|---|---| +| `/workflow:tools:tdd-coverage-analysis` | ⚠️ **DEPRECATED** Use integrated test coverage analysis. | +| `/workflow:tools:test-concept-enhanced` | ⚠️ **DEPRECATED** Use `/workflow:test-gen` instead. | +| `/workflow:tools:context-gather` | ⚠️ **DEPRECATED** Context gathering is now integrated into main workflows. | +| `/workflow:tools:task-generate` | ⚠️ **DEPRECATED** Use `/workflow:lite-plan` or team-lifecycle task generation. | +| `/workflow:tools:task-generate-agent` | ⚠️ **DEPRECATED** Use unified task generation in workflows. | + diff --git a/GETTING_STARTED.md b/GETTING_STARTED.md index 89852626..6b5d7351 100644 --- a/GETTING_STARTED.md +++ b/GETTING_STARTED.md @@ -1,16 +1,16 @@ # 🚀 Claude Code Workflow (CCW) - Getting Started Guide -Welcome to Claude Code Workflow (CCW) v6.2! This guide will help you get up and running in 5 minutes and experience AI-driven automated software development with native CodexLens code intelligence and intelligent CLI orchestration. +Welcome to Claude Code Workflow (CCW) v7.0! This guide will help you get up and running in 5 minutes and experience AI-driven automated software development with team orchestration, queue scheduling, and intelligent CLI orchestration. **Project Repository**: [catlog22/Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow) -> **🎉 What's New in v6.2**: -> - 🔍 **Native CodexLens**: Full-Text + Semantic + Hybrid search with HNSW vector index -> - 🖥️ **New Dashboard Views**: CLAUDE.md Manager, Skills Manager, Graph Explorer, Core Memory -> - 💻 **CLI Refactor**: `ccw cli -p` for multi-model execution (Gemini/Qwen/Codex) -> - 🧠 **Session Clustering**: Intelligent memory management with visualization -> - 📘 **TypeScript Migration**: Full backend modernization +> **🎉 What's New in v7.0**: +> - 🤖 **Team Architecture v2**: team-coordinate-v2 / team-executor-v2 with unified team-worker agent architecture +> - 📋 **Queue Scheduler**: Background queue execution service with dependency resolution and session pooling +> - 🖥️ **New Dashboard Views**: Analysis Viewer, Terminal Dashboard with multi-terminal grid, Orchestrator Template Editor +> - 🔄 **Workflow Session Commands**: start/resume/complete/sync for complete session lifecycle management +> - 🌐 **A2UI v2**: Multi-select questions, RadioGroup components, WebSocket real-time communication --- @@ -57,6 +57,16 @@ Want to know the progress? You can check the status of the current workflow at a This will show the completion status of tasks, the currently executing task, and the next steps. +### Step 5: Complete the Session + +When all tasks are done, mark the session as complete: + +```bash +/workflow:session:complete +``` + +This archives the session, extracts lessons learned, and optionally syncs project state. + --- ## 🧠 Core Concepts Explained @@ -75,12 +85,88 @@ Understanding these concepts will help you use CCW more effectively: > - `@test-fix-agent`: Responsible for running tests and automatically fixing failures. > - `@ui-design-agent`: Responsible for UI design and prototype creation. > - `@cli-execution-agent`: Responsible for autonomous CLI task handling (v4.5.0+). + > - **team-worker**: Unified worker agent for team orchestration (v7.0+). - **Workflow** > A series of predefined, collaborative commands used to orchestrate different agents and tools to achieve a complex development goal (e.g., `plan`, `execute`, `test-gen`). --- +## 🆕 v7.0 New Features Overview + +### Workflow Session Management (v7.0) + +CCW v7.0 introduces comprehensive session lifecycle commands: + +```bash +# Start a new session with automatic naming +/workflow:session:start --auto "Implement user authentication" + +# Resume a paused session +/workflow:session:resume + +# Complete and archive the current session +/workflow:session:complete + +# Sync session work to project specs +/workflow:session:sync "What was accomplished" +``` + +### Team Architecture v2 (v7.0) + +For complex projects requiring multiple specialized roles, use Team Architecture v2: + +```bash +# Coordinate a team with auto-generated role specs +/team-coordinate "Build a real-time collaboration system" + +# Execute a pre-planned team session +/team-executor + +# Team members include: analyst, planner, executor, tester, reviewer, architect +``` + +**Key Features**: +- **Dynamic role-spec generation**: Creates role-specific instructions at runtime +- **team-worker agent**: Unified worker handling Phase 1-5 orchestration +- **Inner loop processing**: Handles multiple same-prefix tasks in a single agent +- **Discuss & Explore subagents**: Multi-perspective critique and code exploration + +### Queue Scheduler (v7.0) + +For background task execution with dependency management: + +```bash +# Access via Dashboard → Terminal Dashboard → Queue Panel +# Or use API endpoints for programmatic control +``` + +**Features**: +- Dependency resolution with topological sorting +- Session pooling with 3-tier allocation strategy +- Real-time WebSocket state updates +- Concurrent execution with configurable limits + +### New Dashboard Views (v7.0) + +**Analysis Viewer Page** (`/analysis`): +- Grid layout for concurrent analysis sessions +- Filtering, pagination, and fullscreen mode +- Real-time progress tracking + +**Terminal Dashboard** (`/terminal-dashboard`): +- Multi-terminal grid layout (tmux-style split panes) +- Execution monitor panel with agent orchestration +- Session group tree with drag-and-drop management +- Queue scheduler controls + +**Orchestrator Template Editor** (`/orchestrator`): +- Visual template editing for orchestration plans +- Slash command execution with terminal integration +- Observability panel for debugging + +--- + ## 🛠️ Common Scenarios ### Scenario 1: Quick Feature Development @@ -178,7 +264,7 @@ After planning, validate your implementation plan for consistency and completene -### Scenario 6: Bug Fixing +### Scenario 5: Bug Fixing Quick bug analysis and fix workflow: @@ -189,6 +275,26 @@ Quick bug analysis and fix workflow: # Claude will analyze severity, diagnose root cause, and implement the fix ``` +### Scenario 6: Team-Based Development (v7.0) + +For complex projects requiring multiple specialized perspectives: + +```bash +# Coordinate a team with automatic role generation +/team-coordinate "Design and implement a microservices architecture" + +# The workflow: +# 1. Analyze requirements and detect needed capabilities +# 2. Generate dynamic role-specs (analyst, planner, executor, tester, reviewer) +# 3. Create tasks with proper dependencies +# 4. Dispatch to team-worker agents +# 5. Monitor progress via callbacks +# 6. Complete with comprehensive report + +# Resume a paused team session +/team-executor .workflow/.team/TLS-xxx-2026-02-27 resume +``` + --- ## 🔧 Lightweight Commands diff --git a/GETTING_STARTED_CN.md b/GETTING_STARTED_CN.md index e2caf9e4..76b8aac5 100644 --- a/GETTING_STARTED_CN.md +++ b/GETTING_STARTED_CN.md @@ -1,16 +1,16 @@ # 🚀 Claude Code Workflow (CCW) - 快速上手指南 -欢迎来到 Claude Code Workflow (CCW) v6.2！本指南将帮助您在 5 分钟内快速入门，体验由 AI 驱动的自动化软件开发流程，原生 CodexLens 代码智能和智能 CLI 编排。 +欢迎来到 Claude Code Workflow (CCW) v7.0！本指南将帮助您在 5 分钟内快速入门，体验由 AI 驱动的自动化软件开发流程，包括团队编排、队列调度和智能 CLI 编排。 **项目地址**：[catlog22/Claude-Code-Workflow](https://github.com/catlog22/Claude-Code-Workflow) -> **🎉 v6.2 新特性**: -> - 🔍 **原生 CodexLens**: 全文搜索 + 语义搜索 + 混合搜索，支持 HNSW 向量索引 -> - 🖥️ **新 Dashboard 视图**: CLAUDE.md 管理器、技能管理器、图浏览器、核心记忆 -> - 💻 **CLI 重构**: `ccw cli -p` 支持多模型执行 (Gemini/Qwen/Codex) -> - 🧠 **会话聚类**: 智能记忆管理与可视化 -> - 📘 **TypeScript 迁移**: 后端全面现代化 +> **🎉 v7.0 新特性**: +> - 🤖 **团队架构 v2**: team-coordinate-v2 / team-executor-v2 统一 team-worker 代理架构 +> - 📋 **队列调度器**: 后台队列执行服务，支持依赖解析和会话池管理 +> - 🖥️ **新仪表板视图**: 分析查看器、多终端网格仪表板、编排器模板编辑器 +> - 🔄 **工作流会话命令**: start/resume/complete/sync 完整会话生命周期管理 +> - 🌐 **A2UI v2**: 多选问题、单选组组件、WebSocket 实时通信 --- @@ -57,6 +57,16 @@ 这会显示任务的完成情况、当前正在执行的任务以及下一步计划。 +### 第 5 步：完成会话 + +所有任务完成后，标记会话为完成： + +```bash +/workflow:session:complete +``` + +这会归档会话、提取经验教训，并可选地同步项目状态。 + --- ## 🧠 核心概念解析 @@ -75,12 +85,88 @@ > - `@test-fix-agent`: 负责运行测试并自动修复失败的用例。 > - `@ui-design-agent`: 负责 UI 设计和原型创建。 > - `@cli-execution-agent`: 负责自主 CLI 任务处理（v4.5.0+）。 + > - **team-worker**: 统一的工作代理，用于团队编排（v7.0+）。 - **工作流 (Workflow)** > 一系列预定义的、相互协作的命令，用于编排不同的智能体和工具，以完成一个复杂的开发目标（如 `plan`、`execute`、`test-gen`）。 --- +## 🆕 v7.0 新功能概览 + +### 工作流会话管理 (v7.0) + +CCW v7.0 引入完整的会话生命周期命令： + +```bash +# 启动新会话（自动命名） +/workflow:session:start --auto "实现用户认证" + +# 恢复暂停的会话 +/workflow:session:resume + +# 完成并归档当前会话 +/workflow:session:complete + +# 同步会话工作到项目规范 +/workflow:session:sync "完成的工作内容" +``` + +### 团队架构 v2 (v7.0) + +对于需要多个专业角色的复杂项目，使用团队架构 v2： + +```bash +# 协调团队，自动生成角色规范 +/team-coordinate "构建实时协作系统" + +# 执行预规划的团队会话 +/team-executor + +# 团队成员包括：analyst、planner、executor、tester、reviewer、architect +``` + +**核心功能**： +- **动态角色规范生成**：运行时创建角色特定指令 +- **team-worker 代理**：统一处理阶段1-5编排的工作代理 +- **内循环处理**：在单个代理中处理多个相同前缀任务 +- **Discuss & Explore 子代理**：多视角批判和代码探索 + +### 队列调度器 (v7.0) + +用于具有依赖管理的后台任务执行： + +```bash +# 通过仪表板访问 → Terminal Dashboard → Queue Panel +# 或使用 API 端点进行程序化控制 +``` + +**功能**： +- 拓扑排序的依赖解析 +- 三层分配策略的会话池管理 +- 实时 WebSocket 状态更新 +- 可配置限制的并发执行 + +### 新仪表板视图 (v7.0) + +**分析查看器页面** (`/analysis`): +- 并发分析会话的网格布局 +- 过滤、分页和全屏模式 +- 实时进度跟踪 + +**终端仪表板** (`/terminal-dashboard`): +- 多终端网格布局（tmux 风格分屏） +- 带代理编排的执行监控面板 +- 拖放式会话组树管理 +- 队列调度器控件 + +**编排器模板编辑器** (`/orchestrator`): +- 编排计划的可视化模板编辑 +- 斜杠命令执行与终端集成 +- 调试用的可观测性面板 + +--- + ## 🛠️ 常见场景示例 ### 场景 1：快速功能开发 @@ -188,7 +274,7 @@ - 识别资源冲突和技能差距 - 提供可执行的修复计划，集成 TodoWrite -### 场景 6：Bug 修复 +### 场景 5：Bug 修复 快速 Bug 分析和修复工作流： @@ -199,6 +285,26 @@ # Claude 会分析严重程度，诊断根因，并实现修复 ``` +### 场景 6：基于团队的协作开发 (v7.0) + +对于需要多个专业视角的复杂项目： + +```bash +# 协调团队，自动生成角色规范 +/team-coordinate "设计和实现微服务架构" + +# 工作流程： +# 1. 分析需求并检测所需能力 +# 2. 生成动态角色规范（analyst、planner、executor、tester、reviewer） +# 3. 创建具有适当依赖关系的任务 +# 4. 分派给 team-worker 代理 +# 5. 通过回调监控进度 +# 6. 完成并生成综合报告 + +# 恢复暂停的团队会话 +/team-executor .workflow/.team/TLS-xxx-2026-02-27 resume +``` + --- ## 🔧 轻量级命令 diff --git a/README.md b/README.md index ab992d76..9b5a378d 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ new line

- Version + Version npm License Stars @@ -50,20 +50,26 @@ From `lite-lite-lite` (instant) to `brainstorm` (multi-role analysis) ### 🔄 Multi-CLI Orchestration Gemini, Qwen, Codex, Claude - auto-select or manual -### ⚡ Dependency-Aware Parallelism -Agent parallel execution without worktree complexity +### ⚡ Team Architecture v2 +Role-based agents with inner loop execution + +### 🔧 Queue Scheduler +Background queue execution service -### 🔧 Issue Workflow -Post-development maintenance with optional worktree isolation +### 📦 Workflow Session Commands +start/resume/complete/sync sessions -### 📦 JSON-First State -`.task/IMPL-*.json` as single source of truth +### 🖥️ Terminal Dashboard +Multi-terminal grid with execution monitor -### 🖥️ Dashboard -Visual session management, CodexLens search, graph explorer +### 🎨 Orchestrator Editor +Template-based workflow visual editing + +### 💬 A2UI +Agent-to-User interactive interface @@ -359,18 +365,151 @@ ccw upgrade -a # Upgrade all installations └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ -│ Issue Workflow (Supplement) │ -│ 🔍 discover → 📋 plan → 📦 queue → ▶️ execute (worktree) │ +│ Team Architecture v2 │ +│ 🤖 team-worker agents with role-spec based execution │ +│ 🔄 Inner loop framework for sequential task processing │ +│ 📢 Message bus protocol with team coordination │ +│ 🧠 Wisdom accumulation (learnings/decisions/conventions) │ +└─────────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────────┐ +│ Queue Scheduler Service │ +│ ⚙️ Background execution service with API endpoints │ +│ 📊 Queue management and unified CLI execution settings │ +└─────────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────────┐ +│ Terminal Dashboard & Orchestrator │ +│ 🖥️ Multi-terminal grid with execution monitor │ +│ 🎨 Template-based workflow editor with slash commands │ +│ 📡 Real-time agent communication via A2UI │ └─────────────────────────────────────────────────────────────────┘ ``` **Core Principles:** - ⚡ **Dependency Analysis** solves parallelism - no worktree needed for main workflow -- 🔧 **Issue Workflow** supplements main workflow for post-development maintenance +- 🤖 **Team Architecture v2** provides unified role-based agent execution with inner loop +- 🔧 **Queue Scheduler** handles background task execution with unified settings +- 🖥️ **Terminal Dashboard** provides real-time monitoring and control - 🎯 Select workflow level based on complexity - avoid over-engineering --- +## 🎼 Team Cadence Control (Beat Model) + +The v2 team architecture introduces an **event-driven beat model** for efficient orchestration: + +``` +Beat Cycle (single beat) +====================================================================== + Event Coordinator Workers +---------------------------------------------------------------------- + callback/resume --> +- handleCallback -+ + | mark completed | + | check pipeline | + +- handleSpawnNext -+ + | find ready tasks | + | spawn workers ---+--> [team-worker A] Phase 1-5 + | (parallel OK) --+--> [team-worker B] Phase 1-5 + +- STOP (idle) -----+ | + | + callback <-----------------------------------------+ + (next beat) SendMessage + TaskUpdate(completed) +====================================================================== + + Fast-Advance (skips coordinator for simple linear successors) +====================================================================== + [Worker A] Phase 5 complete + +- 1 ready task? simple successor? --> spawn team-worker B directly + +- complex case? --> SendMessage to coordinator +====================================================================== +``` + +**Key Benefits:** +- 🎯 **Event-driven**: Coordinator only wakes when needed (callback/resume) +- ⚡ **Fast-advance**: Simple successors spawn directly without coordinator roundtrip +- 🔄 **Dynamic pipelines**: Generated per-task from dependency graph +- 📊 **Parallel execution**: Independent tasks run concurrently + +--- + +## 🖥️ Frontend Highlights + +### Terminal Dashboard + +Multi-terminal grid layout with real-time execution monitoring: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Dashboard Toolbar [Issues][Queue][Inspector]│ +├──────────┬──────────────────────────────────────────────────────┤ +│ Session │ Terminal Grid (tmux-style split panes) │ +│ Groups │ ┌─────────────────┬─────────────────────────────────┐│ +│ ├─ proj1 │ │ Terminal 1 │ Terminal 2 ││ +│ │ └─ cla│ │ $ ccw cli ... │ $ gemini analyze ... ││ +│ ├─ proj2 │ │ │ ││ +│ └─ ... │ └─────────────────┴─────────────────────────────────┘│ +│ │ Execution Monitor Panel (floating) │ +└──────────┴──────────────────────────────────────────────────────┘ +``` + +**Features:** +- 🖥️ Multi-terminal grid with resizable panes +- 📊 Execution monitor with agent list +- 📁 File sidebar for project navigation +- 🎯 Session grouping by project tags +- 🌙 Fullscreen/immersive mode + +### Orchestrator Editor + +Visual workflow template editor with drag-drop: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ FlowToolbar [Templates][Execute] │ +├────────────┬────────────────────────────────────────┬───────────┤ +│ Node │ Flow Canvas │ Property │ +│ Palette │ ┌──────────┐ ┌──────────┐ │ Panel │ +│ ├─ Prompt │ │ Prompt │────▶│ CLI Tool │ │ │ +│ ├─ CLI │ │ Template │ │ Executor │ │ Edit node │ +│ ├─ Slash │ └──────────┘ └──────────┘ │ props │ +│ └─ Flow │ │ │ │ │ +│ │ ▼ ▼ │ │ +│ │ ┌──────────────────────────┐ │ │ +│ │ │ Slash Command │ │ │ +│ │ │ /workflow:plan │ │ │ +│ │ └──────────────────────────┘ │ │ +└────────────┴────────────────────────────────────────┴───────────┘ +``` + +**Features:** +- 🎨 React Flow-based visual editing +- 📦 Template library with pre-built workflows +- 🔧 Property panel for node configuration +- ⚡ Slash command integration + +### Analysis Viewer + +Grid layout for analysis sessions with filtering: + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Filters: [Type ▼] [Status ▼] [Date Range] [Fullscreen] │ +├─────────────────────────────────────────────────────────────────┤ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ +│ │ Analysis #1 │ │ Analysis #2 │ │ Analysis #3 │ │ +│ │ Type: security │ │ Type: perf │ │ Type: architecture │ │ +│ │ Status: ✓ done │ │ Status: ✓ done │ │ Status: ⏳ running │ │ +│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ +│ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ Analysis #4 │ │ Analysis #5 │ │ +│ │ ... │ │ ... │ │ +│ └─────────────────┘ └─────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + ## 🤝 Contributing

diff --git a/README_CN.md b/README_CN.md index 7ccefadd..a66d8abf 100644 --- a/README_CN.md +++ b/README_CN.md @@ -5,7 +5,7 @@

- Version + Version npm License Stars @@ -48,20 +48,26 @@ ### 🔄 多 CLI 编排 Gemini、Qwen、Codex、Claude - 自动选择或手动指定 -### ⚡ 依赖感知并行 -Agent 并行执行，无需 worktree 复杂性 +### ⚡ Team 架构 v2 +基于角色的智能体，支持内循环执行 + +### 🔧 队列调度器 +后台队列执行服务 -### 🔧 Issue 工作流 -开发后维护，可选 worktree 隔离 +### 📦 工作流会话命令 +启动/恢复/完成/同步会话 -### 📦 JSON 优先状态 -`.task/IMPL-*.json` 作为唯一事实来源 +### 🖥️ 终端仪表板 +多终端网格带执行监控器 -### 🖥️ Dashboard -可视化会话管理、CodexLens 搜索、图浏览器 +### 🎨 编排器编辑器 +基于模板的可视化工作流编辑 + +### 💬 A2UI +智能体到用户的交互界面 @@ -355,18 +361,151 @@ ccw upgrade -a # 升级所有安装 └─────────────────────────────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────────────────────────────┐ -│ Issue 工作流 (补充) │ -│ 🔍 discover → 📋 plan → 📦 queue → ▶️ execute (worktree) │ +│ Team 架构 v2 │ +│ 🤖 基于 role-spec 的 team-worker 智能体执行 │ +│ 🔄 内循环框架用于顺序任务处理 │ +│ 📢 消息总线协议与团队协调 │ +│ 🧠 智慧积累 (learnings/decisions/conventions) │ +└─────────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────────┐ +│ 队列调度服务 │ +│ ⚙️ 后台执行服务与 API 端点 │ +│ 📊 队列管理与统一的 CLI 执行设置 │ +└─────────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────────┐ +│ 终端仪表板与编排器 │ +│ 🖥️ 多终端网格与执行监控器 │ +│ 🎨 基于模板的工作流编辑器与斜杠命令 │ +│ 📡 通过 A2UI 实现实时智能体通信 │ └─────────────────────────────────────────────────────────────────┘ ``` **核心原则：** - ⚡ **依赖分析** 解决并行问题 - 主干工作流无需 worktree -- 🔧 **Issue 工作流** 补充主干工作流，用于开发后维护 +- 🤖 **Team 架构 v2** 提供统一的基于角色的智能体执行与内循环 +- 🔧 **队列调度器** 处理后台任务执行与统一设置 +- 🖥️ **终端仪表板** 提供实时监控和控制 - 🎯 根据复杂度选择工作流级别 - 避免过度工程化 --- +## 🎼 团队节拍控制 (Beat Model) + +v2 团队架构引入了**事件驱动的节拍模型**，实现高效编排： + +``` +节拍循环 (单个节拍) +====================================================================== + 事件 协调器 工作者 +---------------------------------------------------------------------- + 回调/恢复 --> +- 处理回调 ------+ + | 标记已完成 | + | 检查流水线 | + +- 处理下一批 -----+ + | 查找就绪任务 | + | 生成工作者 -----+--> [team-worker A] 阶段 1-5 + | (可并行) --+--> [team-worker B] 阶段 1-5 + +- 停止 (空闲) ----+ | + | + 回调 <--------------------------------------+ + (下一节拍) SendMessage + TaskUpdate(completed) +====================================================================== + + 快速推进 (简单线性后继跳过协调器) +====================================================================== + [工作者 A] 阶段 5 完成 + +- 1个就绪任务？简单后继？ --> 直接生成 team-worker B + +- 复杂情况？ --> SendMessage 给协调器 +====================================================================== +``` + +**核心优势：** +- 🎯 **事件驱动**：协调器仅在需要时唤醒（回调/恢复） +- ⚡ **快速推进**：简单后继直接生成，无需协调器往返 +- 🔄 **动态流水线**：根据依赖图按任务生成 +- 📊 **并行执行**：独立任务并发运行 + +--- + +## 🖥️ 前端亮点 + +### 终端仪表板 (Terminal Dashboard) + +多终端网格布局，实时执行监控： + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 仪表板工具栏 [问题][队列][检查器] │ +├──────────┬──────────────────────────────────────────────────────┤ +│ 会话 │ 终端网格 (tmux 风格分割窗格) │ +│ 分组 │ ┌─────────────────┬─────────────────────────────────┐│ +│ ├─ 项目1 │ │ 终端 1 │ 终端 2 ││ +│ │ └─ cla│ │ $ ccw cli ... │ $ gemini analyze ... ││ +│ ├─ 项目2 │ │ │ ││ +│ └─ ... │ └─────────────────┴─────────────────────────────────┘│ +│ │ 执行监控面板 (浮动) │ +└──────────┴──────────────────────────────────────────────────────┘ +``` + +**功能特性：** +- 🖥️ 多终端网格，可调整窗格大小 +- 📊 带智能体列表的执行监控器 +- 📁 项目导航文件侧边栏 +- 🎯 按项目标签分组会话 +- 🌙 全屏/沉浸模式 + +### 编排器编辑器 (Orchestrator Editor) + +可视化工作流模板编辑器，支持拖放： + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 流程工具栏 [模板][执行] │ +├────────────┬────────────────────────────────────────┬───────────┤ +│ 节点 │ 流程画布 │ 属性 │ +│ 调色板 │ ┌──────────┐ ┌──────────┐ │ 面板 │ +│ ├─ 提示词 │ │ 提示词 │────▶│ CLI 工具 │ │ │ +│ ├─ CLI │ │ 模板 │ │ 执行器 │ │ 编辑节点 │ +│ ├─ 斜杠 │ └──────────┘ └──────────┘ │ 属性 │ +│ └─ 流程 │ │ │ │ │ +│ │ ▼ ▼ │ │ +│ │ ┌──────────────────────────┐ │ │ +│ │ │ 斜杠命令 │ │ │ +│ │ │ /workflow:plan │ │ │ +│ │ └──────────────────────────┘ │ │ +└────────────┴────────────────────────────────────────┴───────────┘ +``` + +**功能特性：** +- 🎨 基于 React Flow 的可视化编辑 +- 📦 预构建工作流的模板库 +- 🔧 节点配置属性面板 +- ⚡ 斜杠命令集成 + +### 分析查看器 (Analysis Viewer) + +带过滤功能的分析会话网格布局： + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ 过滤器: [类型 ▼] [状态 ▼] [日期范围] [全屏] │ +├─────────────────────────────────────────────────────────────────┤ +│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │ +│ │ 分析 #1 │ │ 分析 #2 │ │ 分析 #3 │ │ +│ │ 类型: 安全 │ │ 类型: 性能 │ │ 类型: 架构 │ │ +│ │ 状态: ✓ 完成 │ │ 状态: ✓ 完成 │ │ 状态: ⏳ 运行中 │ │ +│ └─────────────────┘ └─────────────────┘ └─────────────────────┘ │ +│ ┌─────────────────┐ ┌─────────────────┐ │ +│ │ 分析 #4 │ │ 分析 #5 │ │ +│ │ ... │ │ ... │ │ +│ └─────────────────┘ └─────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +--- + ## 🤝 贡献

diff --git a/WORKFLOW_GUIDE.md b/WORKFLOW_GUIDE.md index 98e05e67..2f58a4d3 100644 --- a/WORKFLOW_GUIDE.md +++ b/WORKFLOW_GUIDE.md @@ -42,6 +42,16 @@ CCW provides two workflow systems: **Main Workflow** and **Issue Workflow**, wor └─────────────────────────────────────────────────────────────────────────────┘ ``` +## What's New in v7.0 + +**Major New Features**: +- **Team Architecture v2**: `team-coordinate-v2` and `team-executor-v2` with unified team-worker agent +- **Queue Scheduler**: Background task execution with dependency resolution +- **Workflow Session Commands**: `start`, `resume`, `complete`, `sync` for full lifecycle management +- **New Dashboard Views**: Analysis Viewer, Terminal Dashboard, Orchestrator Template Editor + +See [Session Management](#workflow-session-management-v70) and [Team Architecture v2](#team-architecture-v2-v70) sections below for details. + --- ## Main Workflow vs Issue Workflow @@ -98,6 +108,105 @@ Development → Release → Discover Issue → Worktree Fix → Merge back --- +## Workflow Session Management (v7.0) + +CCW v7.0 introduces comprehensive session lifecycle commands for managing workflow sessions from creation to completion. + +### Session Commands Overview + +| Command | Purpose | When to Use | +|---------|---------|-------------| +| `/workflow:session:start` | Start new session or discover existing | Beginning any workflow | +| `/workflow:session:resume` | Resume a paused session | Returning to interrupted work | +| `/workflow:session:complete` | Archive session and extract learnings | After all tasks complete | +| `/workflow:session:sync` | Sync session work to specs | Update project documentation | + +### Starting a Session + +```bash +# Discovery mode - list active sessions and let user choose +/workflow:session:start + +# Auto mode - intelligently create or reuse based on keywords +/workflow:session:start --auto "Implement OAuth2 authentication" + +# Force new mode - always create a fresh session +/workflow:session:start --new "User authentication feature" + +# Specify session type +/workflow:session:start --type tdd --auto "Test-driven user login" +``` + +**Session Types**: +- `workflow`: Standard implementation (default) +- `review`: Code review sessions +- `tdd`: Test-driven development +- `test`: Test generation/fix sessions +- `docs`: Documentation sessions + +### Resuming a Session + +```bash +# Resume most recently paused session +/workflow:session:resume + +# Resume specific session via execute +/workflow:execute --resume-session="WFS-user-auth-v2" +``` + +### Completing a Session + +```bash +# Interactive completion with review +/workflow:session:complete + +# Auto-complete with sync +/workflow:session:complete --yes + +# Detailed completion with metrics +/workflow:session:complete --detailed +``` + +**Completion Actions**: +- Archive session to `.workflow/archives/` +- Generate `manifest.json` with metrics +- Extract lessons learned (successes, challenges, patterns) +- Auto-sync project state (with `--yes`) + +### Syncing Session Work + +```bash +# Sync with confirmation +/workflow:session:ync "Added user authentication with JWT" + +# Auto-sync without confirmation +/workflow:session:sync -y "Implemented OAuth2 flow" +``` + +**Sync Updates**: +- `specs/*.md` - Project specifications from session context +- `project-tech.json` - Technology stack and architecture + +### Session Directory Structure + +``` +.workflow/ +├── active/ # Active sessions +│ └── WFS-{session-name}/ +│ ├── workflow-session.json # Session metadata +│ ├── IMPL_PLAN.md # Implementation plan +│ ├── TODO_LIST.md # Task checklist +│ ├── .task/ # Task JSON files +│ └── .process/ # Process artifacts +├── archives/ # Completed sessions +│ └── WFS-{session-name}/ +│ ├── manifest.json # Completion metrics +│ └── ... +└── project-tech.json # Project technology registry +``` + +--- + ## Level 1: Rapid Execution (lite-lite-lite) **Simplest - Single CLI analysis to execution, zero artifacts** @@ -869,6 +978,177 @@ flowchart TD --- +## Team Architecture v2 (v7.0) + +**For complex multi-role projects requiring specialized expertise and orchestration.** + +### Overview + +Team Architecture v2 (`team-coordinate-v2`, `team-executor-v2`) provides a unified team-worker agent architecture for complex software development workflows. + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ Team Coordinate / Team Executor v2 │ +│ │ +│ ┌─────────────┐ ┌─────────────────────────────────────────────────┐ │ +│ │ Coordinator │ ──→ │ Dynamic Role-Spec Generation │ │ +│ │ / Executor │ │ (analyst, planner, executor, tester, reviewer) │ │ +│ └─────────────┘ └─────────────────────────────────────────────────┘ │ +│ │ │ │ │ +│ ▼ ▼ │ │ +│ ┌─────────────┐ ┌─────────────────────────────────────────────────┐ │ +│ │ Task │ │ team-worker Agents │ │ +│ │ Dispatching │ │ (Phase 1: Task Discovery - built-in) │ │ +│ │ │ │ (Phase 2-4: Role-Specific - from spec files) │ │ +│ └─────────────┘ │ (Phase 5: Report + Fast-Advance - built-in) │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ │ │ +│ ▼ │ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ Subagents (Discuss, Explore, Doc-Generation) │ │ +│ └─────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### Key Concepts + +#### team-worker Agent + +The unified worker agent that: +- **Phase 1 (Built-in)**: Task discovery - filters tasks by prefix and status +- **Phase 2-4 (Role-Specific)**: Loads domain logic from role-spec markdown files +- **Phase 5 (Built-in)**: Report + Fast-Advance - handles completion and successor spawning + +#### Role-Spec Files + +Lightweight markdown files containing only Phase 2-4 logic: + +```yaml +--- +role: analyst +prefix: RESEARCH +inner_loop: false +subagents: [explore, discuss] +message_types: + success: research_ready + error: error +--- +``` + +#### Inner Loop Framework + +When `inner_loop: true`, a single agent processes all same-prefix tasks sequentially: + +``` +context_accumulator = [] + +Phase 1: Find first RESEARCH-* task + Phase 2-4: Execute role spec + Phase 5-L: Mark done, log, accumulate + More RESEARCH-* tasks? → Phase 1 (loop) + No more? → Phase 5-F (final report) +``` + +### Commands + +#### Team Coordinate + +Generate role-specs and orchestrate a team from scratch: + +```bash +/team-coordinate "Design and implement a real-time collaboration system" +``` + +**Process**: +1. Analyze requirements and detect capabilities +2. Generate role-specs dynamically +3. Create tasks with dependency chains +4. Spawn team-worker agents +5. Monitor progress via callbacks +6. Complete with comprehensive report + +#### Team Executor + +Execute a pre-planned team session: + +```bash +# Initial execution +/team-executor + +# Resume paused session +/team-executor resume + +# Check status without advancing +/team-executor status +``` + +### Available Roles + +| Role | Prefix | Responsibility | Inner Loop | +|------|--------|----------------|------------| +| analyst | RESEARCH | Codebase exploration, multi-perspective analysis | No | +| planner | PLAN | Task breakdown and dependency planning | Yes | +| executor | IMPL | Implementation and coding | Yes | +| tester | TEST | Testing and quality assurance | Yes | +| reviewer | REVIEW | Code review and quality gates | Yes | +| architect | DESIGN | Architecture and design decisions | No | +| fe-developer | FE-IMPL | Frontend implementation | Yes | +| fe-qa | FE-TEST | Frontend testing | Yes | + +### Subagents + +| Subagent | Purpose | +|----------|---------| +| discuss | Multi-perspective critique with dynamic perspectives | +| explore | Codebase exploration with caching | +| doc-generation | Document generation from templates | + +### Message Bus Protocol + +Team communication via `team_msg` operation: + +```javascript +mcp__ccw-tools__team_msg({ + operation: "log", + team: "", // Session ID, NOT team name + from: "", + to: "coordinator", + type: "", + summary: "[] ", + ref: "" +}) +``` + +### Session Structure + +``` +.workflow/.team// +├── team-session.json # Session metadata +├── task-analysis.json # Task dependencies +├── role-specs/ # Generated role-spec files +│ ├── analyst.md +│ ├── planner.md +│ └── executor.md +├── artifacts/ # Task outputs +├── discussions/ # Multi-perspective critiques +└── wisdom/ # Accumulated learnings + ├── learnings.md + ├── decisions.md + ├── conventions.md + └── issues.md +``` + +### Use Cases + +- ✅ Complex multi-system projects requiring specialized expertise +- ✅ Projects requiring architectural exploration before implementation +- ✅ Quality-critical projects requiring comprehensive testing and review +- ✅ Frontend + Backend coordination +- ❌ Simple single-module features (use `/workflow:plan` instead) +- ❌ Quick fixes (use `/workflow:lite-fix` instead) + +--- + ## Issue Workflow **Main Workflow Supplement - Post-development continuous maintenance** diff --git a/WORKFLOW_GUIDE_CN.md b/WORKFLOW_GUIDE_CN.md index 1f12a071..879d1405 100644 --- a/WORKFLOW_GUIDE_CN.md +++ b/WORKFLOW_GUIDE_CN.md @@ -40,6 +40,16 @@ CCW 提供两类工作流体系：**主干工作流** (Main Workflow) 和 **Issu └─────────────────────────────────────────────────────────────────────────────┘ ``` +## v7.0 新增功能 + +**主要新特性**： +- **团队架构 v2**: `team-coordinate-v2` 和 `team-executor-v2` 统一 team-worker 代理 +- **队列调度器**: 具有依赖解析的后台任务执行 +- **工作流会话命令**: `start`、`resume`、`complete`、`sync` 完整生命周期管理 +- **新仪表板视图**: 分析查看器、终端仪表板、编排器模板编辑器 + +详情请参阅下面的[会话管理](#workflow-会话管理-v70)和[团队架构 v2](#团队架构-v2-v70)章节。 + --- ## 主干工作流与 Issue 工作流的关系 @@ -96,6 +106,105 @@ Issue 工作流作为**补充机制**，场景不同： --- +## Workflow 会话管理 (v7.0) + +CCW v7.0 引入完整的会话生命周期命令，用于管理工作流会话从创建到完成的全过程。 + +### 会话命令概览 + +| 命令 | 用途 | 使用时机 | +|------|------|----------| +| `/workflow:session:start` | 启动新会话或发现现有会话 | 开始任何工作流 | +| `/workflow:session:resume` | 恢复暂停的会话 | 返回中断的工作 | +| `/workflow:session:complete` | 归档会话并提取经验 | 所有任务完成后 | +| `/workflow:session:sync` | 同步会话工作到规范 | 更新项目文档 | + +### 启动会话 + +```bash +# 发现模式 - 列出活动会话并让用户选择 +/workflow:session:start + +# 自动模式 - 基于关键词智能创建或重用 +/workflow:session:start --auto "实现 OAuth2 认证" + +# 强制新模式 - 始终创建新会话 +/workflow:session:start --new "用户认证功能" + +# 指定会话类型 +/workflow:session:start --type tdd --auto "测试驱动的用户登录" +``` + +**会话类型**： +- `workflow`: 标准实现（默认） +- `review`: 代码审查会话 +- `tdd`: 测试驱动开发 +- `test`: 测试生成/修复会话 +- `docs`: 文档会话 + +### 恢复会话 + +```bash +# 恢复最近暂停的会话 +/workflow:session:resume + +# 通过 execute 恢复特定会话 +/workflow:execute --resume-session="WFS-user-auth-v2" +``` + +### 完成会话 + +```bash +# 带审查的交互式完成 +/workflow:session:complete + +# 自动完成并同步 +/workflow:session:complete --yes + +# 带指标的详细完成 +/workflow:session:complete --detailed +``` + +**完成操作**： +- 将会话归档到 `.workflow/archives/` +- 生成带指标的 `manifest.json` +- 提取经验教训（成功、挑战、模式） +- 自动同步项目状态（使用 `--yes`） + +### 同步会话工作 + +```bash +# 带确认的同步 +/workflow:session:sync "添加了用户认证 JWT" + +# 无确认的自动同步 +/workflow:session:sync -y "实现了 OAuth2 流程" +``` + +**同步更新**： +- `specs/*.md` - 会话上下文的项目规范 +- `project-tech.json` - 技术栈和架构 + +### 会话目录结构 + +``` +.workflow/ +├── active/ # 活动会话 +│ └── WFS-{session-name}/ +│ ├── workflow-session.json # 会话元数据 +│ ├── IMPL_PLAN.md # 实现计划 +│ ├── TODO_LIST.md # 任务清单 +│ ├── .task/ # 任务 JSON 文件 +│ └── .process/ # 过程工件 +├── archives/ # 已完成的会话 +│ └── WFS-{session-name}/ +│ ├── manifest.json # 完成指标 +│ └── ... +└── project-tech.json # 项目技术注册表 +``` + +--- + ## Level 1: 急速执行 (lite-lite-lite) **最简单 - 一次 CLI 分析到执行，零产物** @@ -1076,6 +1185,177 @@ Phase 3: 执行 --- +## 团队架构 v2 (v7.0) + +**适用于需要多角色专业知识和编排的复杂多角色项目。** + +### 概述 + +团队架构 v2 (`team-coordinate-v2`、`team-executor-v2`) 为复杂软件开发工作流提供统一的 team-worker 代理架构。 + +``` +┌─────────────────────────────────────────────────────────────────────────────────┐ +│ Team Coordinate / Team Executor v2 │ +│ │ +│ ┌─────────────┐ ┌─────────────────────────────────────────────────┐ │ +│ │ Coordinator │ ──→ │ 动态角色规范生成 │ │ +│ │ / Executor │ │ (analyst, planner, executor, tester, reviewer) │ │ +│ └─────────────┘ └─────────────────────────────────────────────────┘ │ +│ │ │ │ │ +│ ▼ ▼ │ │ +│ ┌─────────────┐ ┌─────────────────────────────────────────────────┐ │ +│ │ 任务 │ │ team-worker 代理 │ │ +│ │ 分发 │ │ (阶段1: 任务发现 - 内置) │ │ +│ └─────────────┘ │ (阶段2-4: 角色特定 - 从规范文件) │ │ +│ │ (阶段5: 报告 + 快速推进 - 内置) │ │ +│ └─────────────────────────────────────────────────┘ │ +│ │ │ │ +│ ▼ │ │ +│ ┌─────────────────────────────────────────────────┐ │ +│ │ 子代理 (Discuss, Explore, Doc-Generation) │ │ +│ └─────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────────────────────────┘ +``` + +### 核心概念 + +#### team-worker 代理 + +统一的工作代理，负责： +- **阶段1（内置）**: 任务发现 - 按前缀和状态过滤任务 +- **阶段2-4（角色特定）**: 从角色规范 markdown 文件加载领域逻辑 +- **阶段5（内置）**: 报告 + 快速推进 - 处理完成和后继生成 + +#### 角色规范文件 + +仅包含阶段2-4逻辑的轻量级 markdown 文件： + +```yaml +--- +role: analyst +prefix: RESEARCH +inner_loop: false +subagents: [explore, discuss] +message_types: + success: research_ready + error: error +--- +``` + +#### 内循环框架 + +当 `inner_loop: true` 时，单个代理顺序处理所有相同前缀任务： + +``` +context_accumulator = [] + +阶段1: 查找第一个 RESEARCH-* 任务 + 阶段2-4: 执行角色规范 + 阶段5-L: 标记完成，记录，累积 + 更多 RESEARCH-* 任务？→ 阶段1（循环） + 没有了？→ 阶段5-F（最终报告） +``` + +### 命令 + +#### Team Coordinate + +从头生成角色规范并编排团队： + +```bash +/team-coordinate "设计和实现实时协作系统" +``` + +**流程**： +1. 分析需求并检测能力 +2. 动态生成角色规范 +3. 创建带依赖链的任务 +4. 生成 team-worker 代理 +5. 通过回调监控进度 +6. 完成并生成综合报告 + +#### Team Executor + +执行预规划的团队会话： + +```bash +# 初始执行 +/team-executor + +# 恢复暂停的会话 +/team-executor resume + +# 检查状态但不推进 +/team-executor status +``` + +### 可用角色 + +| 角色 | 前缀 | 职责 | 内循环 | +|------|------|------|--------| +| analyst | RESEARCH | 代码库探索、多视角分析 | 否 | +| planner | PLAN | 任务分解和依赖规划 | 是 | +| executor | IMPL | 实现和编码 | 是 | +| tester | TEST | 测试和质量保证 | 是 | +| reviewer | REVIEW | 代码审查和质量门 | 是 | +| architect | DESIGN | 架构和设计决策 | 否 | +| fe-developer | FE-IMPL | 前端实现 | 是 | +| fe-qa | FE-TEST | 前端测试 | 是 | + +### 子代理 + +| 子代理 | 用途 | +|--------|------| +| discuss | 多视角批判，动态视角 | +| explore | 代码库探索，带缓存 | +| doc-generation | 从模板生成文档 | + +### 消息总线协议 + +通过 `team_msg` 操作进行团队通信： + +```javascript +mcp__ccw-tools__team_msg({ + operation: "log", + team: "", // 会话 ID，不是团队名称 + from: "", + to: "coordinator", + type: "", + summary: "[] ", + ref: "" +}) +``` + +### 会话结构 + +``` +.workflow/.team// +├── team-session.json # 会话元数据 +├── task-analysis.json # 任务依赖 +├── role-specs/ # 生成的角色规范文件 +│ ├── analyst.md +│ ├── planner.md +│ └── executor.md +├── artifacts/ # 任务输出 +├── discussions/ # 多视角批判 +└── wisdom/ # 累积的经验 + ├── learnings.md + ├── decisions.md + ├── conventions.md + └── issues.md +``` + +### 使用场景 + +- ✅ 需要多专业知识的复杂多系统项目 +- ✅ 需要在实现前进行架构探索的项目 +- ✅ 质量关键项目，需要全面测试和审查 +- ✅ 前端 + 后端协调 +- ❌ 简单单模块功能（改用 `/workflow:plan`） +- ❌ 快速修复（改用 `/workflow:lite-fix`） + +--- + ## Issue 工作流 **主干工作流的补充 - 开发后的持续维护** diff --git a/ccw/frontend/src/components/shared/NativeSessionPanel.tsx b/ccw/frontend/src/components/shared/NativeSessionPanel.tsx index 6ce6703b..4fb664f7 100644 --- a/ccw/frontend/src/components/shared/NativeSessionPanel.tsx +++ b/ccw/frontend/src/components/shared/NativeSessionPanel.tsx @@ -23,13 +23,18 @@ import { DialogTitle, } from '@/components/ui/Dialog'; import { useNativeSession } from '@/hooks/useNativeSession'; +import { useNativeSessionByPath } from '@/hooks/useNativeSessionByPath'; import { SessionTimeline } from './SessionTimeline'; import { getToolVariant } from '@/lib/cli-tool-theme'; +import type { NativeSessionListItem } from '@/lib/api'; // ========== Types ========== export interface NativeSessionPanelProps { - executionId: string; + /** Legacy: CCW execution ID for lookup */ + executionId?: string; + /** New: Session metadata with path for direct file loading */ + session?: NativeSessionListItem | null; open: boolean; onOpenChange: (open: boolean) => void; } @@ -63,14 +68,34 @@ async function copyToClipboard(text: string): Promise { * * Shows session metadata, token summary, and all conversation turns * with thoughts and tool calls for Gemini/Codex/Qwen native sessions. + * + * Supports two modes: + * - executionId: Look up session via CCW database + * - session: Load session directly from file path */ export function NativeSessionPanel({ executionId, + session, open, onOpenChange, }: NativeSessionPanelProps) { const { formatMessage } = useIntl(); - const { data: session, isLoading, error } = useNativeSession(open ? executionId : null); + + // Use appropriate hook based on what's provided + // Priority: session (path-based) > executionId (lookup-based) + const pathBasedResult = useNativeSessionByPath( + open && session ? session.filePath : null, + session?.tool + ); + + const idBasedResult = useNativeSession( + open && !session && executionId ? executionId : null + ); + + // Determine which result to use + const { data, isLoading, error } = session + ? pathBasedResult + : idBasedResult; const [copiedField, setCopiedField] = React.useState(null); @@ -91,44 +116,46 @@ export function NativeSessionPanel({ {formatMessage({ id: 'nativeSession.title', defaultMessage: 'Native Session' })} - {session && ( + {(data || session) && (
- - {session.tool.toUpperCase()} + + {(data?.tool || session?.tool || 'unknown').toUpperCase()} - {session.model && ( + {data?.model && ( - {session.model} + {data.model} )} - - {truncate(session.sessionId, 16)} - + {(data?.sessionId || session?.sessionId) && ( + + {truncate(data?.sessionId || session?.sessionId || '', 16)} + + )}
)}
- {session && ( + {(data || session) && (
- {new Date(session.startTime).toLocaleString()} + {new Date(data?.startTime || session?.createdAt || '').toLocaleString()} - {session.workingDir && ( + {(data?.workingDir || session?.projectHash) && ( - {session.workingDir} + {data?.workingDir || session?.projectHash} )} - {session.projectHash && ( + {data?.projectHash && ( - {truncate(session.projectHash, 12)} + {truncate(data.projectHash, 12)} )} - {session.turns.length} {formatMessage({ id: 'nativeSession.meta.turns', defaultMessage: 'turns' })} + {data && {data.turns.length} {formatMessage({ id: 'nativeSession.meta.turns', defaultMessage: 'turns' })}}
)} @@ -142,15 +169,18 @@ export function NativeSessionPanel({
) : error ? ( -
+
{formatMessage({ id: 'nativeSession.error', defaultMessage: 'Failed to load session' })}
+

+ {formatMessage({ id: 'nativeSession.errorHint', defaultMessage: 'The session file may have been moved or deleted.' })} +

- ) : session ? ( + ) : data ? (
- +
) : (
@@ -159,12 +189,12 @@ export function NativeSessionPanel({ )} {/* Footer Actions */} - {session && ( + {data && (