From b780734649f78fc95271760c43d991e53ee9128b Mon Sep 17 00:00:00 2001 From: catlog22 Date: Mon, 2 Mar 2026 17:41:40 +0800 Subject: [PATCH] Add comprehensive command and skill reference documentation in Chinese - Created a new document for command and skill references, detailing orchestrator commands, workflow session commands, issue workflow commands, IDAW commands, with-file workflows, cycle workflows, CLI commands, memory commands, team skills, workflow skills, utility skills, and Codex capabilities. - Added a comparison table for workflows, outlining their best uses, levels, self-containment, and automatic chaining behavior. --- ccw/frontend/src/main.tsx | 26 +- ccw/src/core/routes/cli-routes.ts | 2 +- ccw/src/core/routes/memory-routes.ts | 2 +- ccw/src/core/websocket.ts | 328 +++++++---- ccw/src/tools/cli-executor-state.ts | 17 +- ccw/src/tools/cli-history-store.ts | 121 +++-- docs/.vitepress/config.ts | 41 +- docs/reference/commands-skills.md | 753 ++++++++++++++++++++++++++ docs/skills/claude-workflow.md | 27 + docs/workflows/comparison-table.md | 175 ++++++ docs/zh/reference/commands-skills.md | 753 ++++++++++++++++++++++++++ docs/zh/workflows/comparison-table.md | 175 ++++++ 12 files changed, 2215 insertions(+), 205 deletions(-) create mode 100644 docs/reference/commands-skills.md create mode 100644 docs/workflows/comparison-table.md create mode 100644 docs/zh/reference/commands-skills.md create mode 100644 docs/zh/workflows/comparison-table.md diff --git a/ccw/frontend/src/main.tsx b/ccw/frontend/src/main.tsx index 72e3e672..ea6c7970 100644 --- a/ccw/frontend/src/main.tsx +++ b/ccw/frontend/src/main.tsx @@ -8,32 +8,14 @@ import 'xterm/css/xterm.css' import { loadMessagesForLocale, getInitialLocale } from './lib/i18n' import { logWebVitals } from './lib/webVitals' -/** - * Initialize CSRF token by fetching from backend - * This ensures the CSRF cookie is set before any mutating API calls - */ -async function initCsrfToken() { - try { - // Fetch CSRF token from backend - this sets the XSRF-TOKEN cookie - await fetch('/api/csrf-token', { - method: 'GET', - credentials: 'same-origin', - }) - } catch (error) { - // Log error but don't block app initialization - console.error('Failed to initialize CSRF token:', error) - } -} - async function bootstrapApplication() { const rootElement = document.getElementById('root') if (!rootElement) throw new Error('Failed to find the root element') - // Parallelize CSRF token fetch and locale detection (independent operations) - const [, locale] = await Promise.all([ - initCsrfToken(), - getInitialLocale() - ]) + // CSRF token initialization is deferred to first mutating request + // This eliminates network RTT from app startup path + // See: ccw/frontend/src/lib/api.ts - fetchApi handles lazy token fetch + const locale = await getInitialLocale() // Load only the active locale's messages (lazy load secondary on demand) const messages = await loadMessagesForLocale(locale) diff --git a/ccw/src/core/routes/cli-routes.ts b/ccw/src/core/routes/cli-routes.ts index f2dd90a9..fcd644b5 100644 --- a/ccw/src/core/routes/cli-routes.ts +++ b/ccw/src/core/routes/cli-routes.ts @@ -1093,7 +1093,7 @@ export async function handleCliRoutes(ctx: RouteContext): Promise { return { error: 'Execution not found', status: 404 }; } - const review = historyStore.saveReview({ + const review = await historyStore.saveReview({ execution_id: executionId, status, rating, diff --git a/ccw/src/core/routes/memory-routes.ts b/ccw/src/core/routes/memory-routes.ts index 3b48aff2..f80ce073 100644 --- a/ccw/src/core/routes/memory-routes.ts +++ b/ccw/src/core/routes/memory-routes.ts @@ -589,7 +589,7 @@ Return ONLY valid JSON in this exact format (no markdown, no code blocks, just p const storeModule = await import('../../tools/cli-history-store.js'); const store = storeModule.getHistoryStore(projectPath); const insightId = `insight-${Date.now()}`; - store.saveInsight({ + await store.saveInsight({ id: insightId, tool, promptCount: prompts.length, diff --git a/ccw/src/core/websocket.ts b/ccw/src/core/websocket.ts index c4dfd7d1..97917cde 100644 --- a/ccw/src/core/websocket.ts +++ b/ccw/src/core/websocket.ts @@ -24,6 +24,212 @@ export const wsClients = new Set(); // Track message counts per client for rate limiting export const wsClientMessageCounts = new Map(); +/** + * Universal broadcast throttling system + * Reduces WebSocket traffic by deduplicating and rate-limiting broadcast messages + */ + +interface ThrottleEntry { + lastSend: number; + pendingData: unknown; +} + +type ThrottleCategory = 'state_update' | 'memory_cpu' | 'log_output' | 'immediate'; + +/** Map of message type to throttle configuration */ +const THROTTLE_CONFIG = new Map( + [ + // State updates - high frequency, low value when duplicated + ['LOOP_STATE_UPDATE', { interval: 1000, category: 'state_update' }], + ['ORCHESTRATOR_STATE_UPDATE', { interval: 1000, category: 'state_update' }], + ['COORDINATOR_STATE_UPDATE', { interval: 1000, category: 'state_update' }], + ['QUEUE_SCHEDULER_STATE_UPDATE', { interval: 1000, category: 'state_update' }], + + // Memory/CPU updates - medium frequency + ['LOOP_STEP_COMPLETED', { interval: 500, category: 'memory_cpu' }], + ['ORCHESTRATOR_NODE_COMPLETED', { interval: 500, category: 'memory_cpu' }], + ['COORDINATOR_COMMAND_COMPLETED', { interval: 500, category: 'memory_cpu' }], + ['QUEUE_ITEM_UPDATED', { interval: 500, category: 'memory_cpu' }], + + // Log/output - higher frequency allowed for real-time streaming + ['LOOP_LOG_ENTRY', { interval: 200, category: 'log_output' }], + ['ORCHESTRATOR_LOG', { interval: 200, category: 'log_output' }], + ['COORDINATOR_LOG_ENTRY', { interval: 200, category: 'log_output' }], + + // Item added/removed - send immediately + ['QUEUE_ITEM_ADDED', { interval: 0, category: 'immediate' }], + ['QUEUE_ITEM_REMOVED', { interval: 0, category: 'immediate' }], + ['QUEUE_SCHEDULER_CONFIG_UPDATED', { interval: 0, category: 'immediate' }], + ['ORCHESTRATOR_NODE_STARTED', { interval: 0, category: 'immediate' }], + ['ORCHESTRATOR_NODE_FAILED', { interval: 0, category: 'immediate' }], + ['COORDINATOR_COMMAND_STARTED', { interval: 0, category: 'immediate' }], + ['COORDINATOR_COMMAND_FAILED', { interval: 0, category: 'immediate' }], + ['COORDINATOR_QUESTION_ASKED', { interval: 0, category: 'immediate' }], + ['COORDINATOR_ANSWER_RECEIVED', { interval: 0, category: 'immediate' }], + ['LOOP_COMPLETED', { interval: 0, category: 'immediate' }], + ['LOOP_COMPLETED' as any, { interval: 0, category: 'immediate' }], + ].filter(([key]) => key !== 'LOOP_COMPLETED' as any) +); + +// Add LOOP_COMPLETED separately to avoid type issues +THROTTLE_CONFIG.set('LOOP_COMPLETED', { interval: 0, category: 'immediate' }); + +/** Per-message-type throttle tracking */ +const throttleState = new Map(); + +/** Metrics for broadcast optimization */ +export const broadcastMetrics = { + sent: 0, + throttled: 0, + deduped: 0, +}; + +/** + * Get throttle configuration for a message type + */ +function getThrottleConfig(messageType: string): { interval: number; category: ThrottleCategory } { + return THROTTLE_CONFIG.get(messageType) || { interval: 0, category: 'immediate' }; +} + +/** + * Serialize message data for comparison + */ +function serializeMessage(data: unknown): string { + if (typeof data === 'string') return data; + if (typeof data === 'object' && data !== null) { + return JSON.stringify(data, Object.keys(data).sort()); + } + return String(data); +} + +/** + * Create WebSocket frame + */ +export function createWebSocketFrame(data: unknown): Buffer { + const payload = Buffer.from(JSON.stringify(data), 'utf8'); + const length = payload.length; + + let frame; + if (length <= 125) { + frame = Buffer.alloc(2 + length); + frame[0] = 0x81; // Text frame, FIN + frame[1] = length; + payload.copy(frame, 2); + } else if (length <= 65535) { + frame = Buffer.alloc(4 + length); + frame[0] = 0x81; + frame[1] = 126; + frame.writeUInt16BE(length, 2); + payload.copy(frame, 4); + } else { + frame = Buffer.alloc(10 + length); + frame[0] = 0x81; + frame[1] = 127; + frame.writeBigUInt64BE(BigInt(length), 2); + payload.copy(frame, 10); + } + + return frame; +} + +/** + * Broadcast message to all connected WebSocket clients with universal throttling + * - Deduplicates identical messages within throttle window + * - Rate-limits by message type with adaptive intervals + * - Preserves message ordering within each type + */ +export function broadcastToClients(data: unknown): void { + const eventType = + typeof data === 'object' && data !== null && 'type' in data ? (data as { type?: unknown }).type : undefined; + + if (!eventType || typeof eventType !== 'string') { + // Unknown message type - send immediately + const frame = createWebSocketFrame(data); + for (const client of wsClients) { + try { + client.write(frame); + } catch (e) { + wsClients.delete(client); + } + } + console.log(`[WS] Broadcast to ${wsClients.size} clients: unknown type`); + return; + } + + const config = getThrottleConfig(eventType); + const now = Date.now(); + const state = throttleState.get(eventType); + + if (config.interval === 0) { + // Immediate - send without throttling + const frame = createWebSocketFrame(data); + for (const client of wsClients) { + try { + client.write(frame); + } catch (e) { + wsClients.delete(client); + } + } + broadcastMetrics.sent++; + throttleState.set(eventType, { lastSend: now, pendingData: data }); + console.log(`[WS] Broadcast to ${wsClients.size} clients: ${eventType} (immediate)`); + return; + } + + // Check if we should throttle + const currentDataHash = serializeMessage(data); + + if (state) { + const timeSinceLastSend = now - state.lastSend; + + // Check for duplicate data + if (timeSinceLastSend < config.interval) { + const pendingDataHash = serializeMessage(state.pendingData); + if (currentDataHash === pendingDataHash) { + // Duplicate message - drop it + broadcastMetrics.deduped++; + console.log(`[WS] Throttled duplicate ${eventType} (${timeSinceLastSend}ms since last)`); + return; + } + // Different data but within throttle window - update pending + throttleState.set(eventType, { lastSend: state.lastSend, pendingData: data }); + broadcastMetrics.throttled++; + console.log(`[WS] Throttled ${eventType} (${timeSinceLastSend}ms since last, pending updated)`); + return; + } + } + + // Send the message + const frame = createWebSocketFrame(data); + for (const client of wsClients) { + try { + client.write(frame); + } catch (e) { + wsClients.delete(client); + } + } + + broadcastMetrics.sent++; + throttleState.set(eventType, { lastSend: now, pendingData: data }); + console.log(`[WS] Broadcast to ${wsClients.size} clients: ${eventType}`); +} + +/** + * Get broadcast throttling metrics + */ +export function getBroadcastMetrics(): Readonly { + return { ...broadcastMetrics }; +} + +/** + * Reset broadcast throttling metrics (for testing/monitoring) + */ +export function resetBroadcastMetrics(): void { + broadcastMetrics.sent = 0; + broadcastMetrics.throttled = 0; + broadcastMetrics.deduped = 0; +} + /** * Check if a new WebSocket connection should be accepted * Returns true if connection allowed, false if limit reached @@ -387,25 +593,6 @@ export function createWebSocketFrame(data: unknown): Buffer { return frame; } -/** - * Broadcast message to all connected WebSocket clients - */ -export function broadcastToClients(data: unknown): void { - const frame = createWebSocketFrame(data); - - for (const client of wsClients) { - try { - client.write(frame); - } catch (e) { - wsClients.delete(client); - } - } - - const eventType = - typeof data === 'object' && data !== null && 'type' in data ? (data as { type?: unknown }).type : undefined; - console.log(`[WS] Broadcast to ${wsClients.size} clients:`, eventType); -} - /** * Extract session ID from file path */ @@ -435,12 +622,9 @@ export function extractSessionIdFromPath(filePath: string): string | null { } /** - * Loop-specific broadcast with throttling - * Throttles LOOP_STATE_UPDATE messages to avoid flooding clients + * Loop broadcast types (without timestamp - added automatically) + * Throttling is handled universally in broadcastToClients */ -let lastLoopBroadcast = 0; -const LOOP_BROADCAST_THROTTLE = 1000; // 1 second - export type LoopMessage = | Omit | Omit @@ -448,18 +632,10 @@ export type LoopMessage = | Omit; /** - * Broadcast loop state update with throttling + * Broadcast loop update with automatic throttling + * Note: Throttling is now handled universally in broadcastToClients */ export function broadcastLoopUpdate(message: LoopMessage): void { - const now = Date.now(); - - // Throttle LOOP_STATE_UPDATE to reduce WebSocket traffic - if (message.type === 'LOOP_STATE_UPDATE' && now - lastLoopBroadcast < LOOP_BROADCAST_THROTTLE) { - return; - } - - lastLoopBroadcast = now; - broadcastToClients({ ...message, timestamp: new Date().toISOString() @@ -467,8 +643,8 @@ export function broadcastLoopUpdate(message: LoopMessage): void { } /** - * Broadcast loop log entry (no throttling) - * Used for streaming real-time logs to Dashboard + * Broadcast loop log entry + * Note: Throttling is now handled universally in broadcastToClients */ export function broadcastLoopLog(loop_id: string, step_id: string, line: string): void { broadcastToClients({ @@ -482,6 +658,7 @@ export function broadcastLoopLog(loop_id: string, step_id: string, line: string) /** * Union type for Orchestrator messages (without timestamp - added automatically) + * Throttling is handled universally in broadcastToClients */ export type OrchestratorMessage = | Omit @@ -491,29 +668,10 @@ export type OrchestratorMessage = | Omit; /** - * Orchestrator-specific broadcast with throttling - * Throttles ORCHESTRATOR_STATE_UPDATE messages to avoid flooding clients - */ -let lastOrchestratorBroadcast = 0; -const ORCHESTRATOR_BROADCAST_THROTTLE = 1000; // 1 second - -/** - * Broadcast orchestrator update with throttling - * STATE_UPDATE messages are throttled to 1 per second - * Other message types are sent immediately + * Broadcast orchestrator update with automatic throttling + * Note: Throttling is now handled universally in broadcastToClients */ export function broadcastOrchestratorUpdate(message: OrchestratorMessage): void { - const now = Date.now(); - - // Throttle ORCHESTRATOR_STATE_UPDATE to reduce WebSocket traffic - if (message.type === 'ORCHESTRATOR_STATE_UPDATE' && now - lastOrchestratorBroadcast < ORCHESTRATOR_BROADCAST_THROTTLE) { - return; - } - - if (message.type === 'ORCHESTRATOR_STATE_UPDATE') { - lastOrchestratorBroadcast = now; - } - broadcastToClients({ ...message, timestamp: new Date().toISOString() @@ -521,8 +679,8 @@ export function broadcastOrchestratorUpdate(message: OrchestratorMessage): void } /** - * Broadcast orchestrator log entry (no throttling) - * Used for streaming real-time execution logs to Dashboard + * Broadcast orchestrator log entry + * Note: Throttling is now handled universally in broadcastToClients */ export function broadcastOrchestratorLog(execId: string, log: Omit): void { broadcastToClients({ @@ -639,6 +797,7 @@ export interface CoordinatorAnswerReceivedMessage { /** * Union type for Coordinator messages (without timestamp - added automatically) + * Throttling is handled universally in broadcastToClients */ export type CoordinatorMessage = | Omit @@ -650,29 +809,10 @@ export type CoordinatorMessage = | Omit; /** - * Coordinator-specific broadcast with throttling - * Throttles COORDINATOR_STATE_UPDATE messages to avoid flooding clients - */ -let lastCoordinatorBroadcast = 0; -const COORDINATOR_BROADCAST_THROTTLE = 1000; // 1 second - -/** - * Broadcast coordinator update with throttling - * STATE_UPDATE messages are throttled to 1 per second - * Other message types are sent immediately + * Broadcast coordinator update with automatic throttling + * Note: Throttling is now handled universally in broadcastToClients */ export function broadcastCoordinatorUpdate(message: CoordinatorMessage): void { - const now = Date.now(); - - // Throttle COORDINATOR_STATE_UPDATE to reduce WebSocket traffic - if (message.type === 'COORDINATOR_STATE_UPDATE' && now - lastCoordinatorBroadcast < COORDINATOR_BROADCAST_THROTTLE) { - return; - } - - if (message.type === 'COORDINATOR_STATE_UPDATE') { - lastCoordinatorBroadcast = now; - } - broadcastToClients({ ...message, timestamp: new Date().toISOString() @@ -680,8 +820,8 @@ export function broadcastCoordinatorUpdate(message: CoordinatorMessage): void { } /** - * Broadcast coordinator log entry (no throttling) - * Used for streaming real-time coordinator logs to Dashboard + * Broadcast coordinator log entry + * Note: Throttling is now handled universally in broadcastToClients */ export function broadcastCoordinatorLog( executionId: string, @@ -715,6 +855,7 @@ export type { /** * Union type for Queue messages (without timestamp - added automatically) + * Throttling is handled universally in broadcastToClients */ export type QueueMessage = | Omit @@ -724,29 +865,10 @@ export type QueueMessage = | Omit; /** - * Queue-specific broadcast with throttling - * Throttles QUEUE_SCHEDULER_STATE_UPDATE messages to avoid flooding clients - */ -let lastQueueBroadcast = 0; -const QUEUE_BROADCAST_THROTTLE = 1000; // 1 second - -/** - * Broadcast queue update with throttling - * STATE_UPDATE messages are throttled to 1 per second - * Other message types are sent immediately + * Broadcast queue update with automatic throttling + * Note: Throttling is now handled universally in broadcastToClients */ export function broadcastQueueUpdate(message: QueueMessage): void { - const now = Date.now(); - - // Throttle QUEUE_SCHEDULER_STATE_UPDATE to reduce WebSocket traffic - if (message.type === 'QUEUE_SCHEDULER_STATE_UPDATE' && now - lastQueueBroadcast < QUEUE_BROADCAST_THROTTLE) { - return; - } - - if (message.type === 'QUEUE_SCHEDULER_STATE_UPDATE') { - lastQueueBroadcast = now; - } - broadcastToClients({ ...message, timestamp: new Date().toISOString() diff --git a/ccw/src/tools/cli-executor-state.ts b/ccw/src/tools/cli-executor-state.ts index e216b91a..4e6e4553 100644 --- a/ccw/src/tools/cli-executor-state.ts +++ b/ccw/src/tools/cli-executor-state.ts @@ -128,7 +128,7 @@ export function ensureHistoryDir(baseDir: string): string { */ async function saveConversationAsync(baseDir: string, conversation: ConversationRecord): Promise { const store = await getSqliteStore(baseDir); - store.saveConversation(conversation); + await store.saveConversation(conversation); } /** @@ -138,7 +138,10 @@ async function saveConversationAsync(baseDir: string, conversation: Conversation export function saveConversation(baseDir: string, conversation: ConversationRecord): void { try { const store = getSqliteStoreSync(baseDir); - store.saveConversation(conversation); + // Fire and forget - don't block on async save in sync context + store.saveConversation(conversation).catch(err => { + console.error('[CLI Executor] Failed to save conversation:', err.message); + }); } catch { // If sync not available, queue for async save saveConversationAsync(baseDir, conversation).catch(err => { @@ -399,7 +402,7 @@ export function getExecutionDetail(baseDir: string, executionId: string): Execut */ export async function deleteExecutionAsync(baseDir: string, executionId: string): Promise<{ success: boolean; error?: string }> { const store = await getSqliteStore(baseDir); - return store.deleteConversation(executionId); + return await store.deleteConversation(executionId); } /** @@ -408,7 +411,11 @@ export async function deleteExecutionAsync(baseDir: string, executionId: string) export function deleteExecution(baseDir: string, executionId: string): { success: boolean; error?: string } { try { const store = getSqliteStoreSync(baseDir); - return store.deleteConversation(executionId); + // Fire and forget - don't block on async delete in sync context + store.deleteConversation(executionId).catch(err => { + console.error('[CLI Executor] Failed to delete execution:', err.message); + }); + return { success: true }; // Optimistic response } catch { return { success: false, error: 'SQLite store not initialized' }; } @@ -424,7 +431,7 @@ export async function batchDeleteExecutionsAsync(baseDir: string, ids: string[]) errors?: string[]; }> { const store = await getSqliteStore(baseDir); - const result = store.batchDelete(ids); + const result = await store.batchDelete(ids); return { ...result, total: ids.length }; } diff --git a/ccw/src/tools/cli-history-store.ts b/ccw/src/tools/cli-history-store.ts index 30c47d3c..ac062d9c 100644 --- a/ccw/src/tools/cli-history-store.ts +++ b/ccw/src/tools/cli-history-store.ts @@ -121,7 +121,8 @@ export class CliHistoryStore { this.db = new Database(this.dbPath); this.db.pragma('journal_mode = WAL'); this.db.pragma('synchronous = NORMAL'); - this.db.pragma('busy_timeout = 5000'); // Wait up to 5 seconds for locks + this.db.pragma('busy_timeout = 10000'); // Wait up to 10 seconds for locks (increased for write-heavy scenarios) + this.db.pragma('wal_autocheckpoint = 1000'); // Optimize WAL checkpointing this.initSchema(); this.migrateFromJson(historyDir); @@ -386,12 +387,13 @@ export class CliHistoryStore { } /** - * Execute a database operation with retry logic for SQLITE_BUSY errors + * Execute a database operation with retry logic for SQLITE_BUSY errors (async, non-blocking) * @param operation - Function to execute * @param maxRetries - Maximum retry attempts (default: 3) * @param baseDelay - Base delay in ms for exponential backoff (default: 100) */ - private withRetry(operation: () => T, maxRetries = 3, baseDelay = 100): T { + private async withRetry(operation: () => T, maxRetries = 3, baseDelay = 100): Promise { + const sleep = (ms: number) => new Promise(resolve => setTimeout(resolve, ms)); let lastError: Error | null = null; for (let attempt = 0; attempt <= maxRetries; attempt++) { @@ -405,10 +407,8 @@ export class CliHistoryStore { if (attempt < maxRetries) { // Exponential backoff: 100ms, 200ms, 400ms const delay = baseDelay * Math.pow(2, attempt); - // Sync sleep using Atomics (works in Node.js) - const sharedBuffer = new SharedArrayBuffer(4); - const sharedArray = new Int32Array(sharedBuffer); - Atomics.wait(sharedArray, 0, 0, delay); + // Async non-blocking sleep + await sleep(delay); } } else { // Non-BUSY error, throw immediately @@ -421,7 +421,7 @@ export class CliHistoryStore { } /** - * Migrate existing JSON files to SQLite + * Migrate existing JSON files to SQLite (async, non-blocking) */ private migrateFromJson(historyDir: string): void { const migrationMarker = join(historyDir, '.migrated'); @@ -429,41 +429,50 @@ export class CliHistoryStore { return; // Already migrated } - // Find all date directories - const dateDirs = readdirSync(historyDir).filter(d => { - const dirPath = join(historyDir, d); - return statSync(dirPath).isDirectory() && /^\d{4}-\d{2}-\d{2}$/.test(d); - }); + // Fire-and-forget async migration + (async () => { + try { + // Find all date directories + const dateDirs = readdirSync(historyDir).filter(d => { + const dirPath = join(historyDir, d); + return statSync(dirPath).isDirectory() && /^\d{4}-\d{2}-\d{2}$/.test(d); + }); - let migratedCount = 0; + let migratedCount = 0; - for (const dateDir of dateDirs) { - const dirPath = join(historyDir, dateDir); - const files = readdirSync(dirPath).filter(f => f.endsWith('.json')); + for (const dateDir of dateDirs) { + const dirPath = join(historyDir, dateDir); + const files = readdirSync(dirPath).filter(f => f.endsWith('.json')); - for (const file of files) { - try { - const filePath = join(dirPath, file); - const data = JSON.parse(readFileSync(filePath, 'utf8')); + for (const file of files) { + try { + const filePath = join(dirPath, file); + const data = JSON.parse(readFileSync(filePath, 'utf8')); - // Convert to conversation record if legacy format - const conversation = this.normalizeRecord(data); - this.saveConversation(conversation); - migratedCount++; + // Convert to conversation record if legacy format + const conversation = this.normalizeRecord(data); + await this.saveConversation(conversation); + migratedCount++; - // Optionally delete the JSON file after migration - // unlinkSync(filePath); - } catch (err) { - console.error(`Failed to migrate ${file}:`, (err as Error).message); + // Optionally delete the JSON file after migration + // unlinkSync(filePath); + } catch (err) { + console.error(`Failed to migrate ${file}:`, (err as Error).message); + } + } } - } - } - // Create migration marker - if (migratedCount > 0) { - require('fs').writeFileSync(migrationMarker, new Date().toISOString()); - console.log(`[CLI History] Migrated ${migratedCount} records to SQLite`); - } + // Create migration marker + if (migratedCount > 0) { + require('fs').writeFileSync(migrationMarker, new Date().toISOString()); + console.log(`[CLI History] Migrated ${migratedCount} records to SQLite`); + } + } catch (err) { + console.error('[CLI History] Migration failed:', (err as Error).message); + } + })().catch(err => { + console.error('[CLI History] Migration error:', (err as Error).message); + }); } /** @@ -499,9 +508,9 @@ export class CliHistoryStore { } /** - * Save or update a conversation + * Save or update a conversation (async for non-blocking retry) */ - saveConversation(conversation: ConversationRecord): void { + async saveConversation(conversation: ConversationRecord): Promise { // Ensure prompt is a string before calling substring const lastTurn = conversation.turns.length > 0 ? conversation.turns[conversation.turns.length - 1] : null; const rawPrompt = lastTurn?.prompt ?? ''; @@ -579,7 +588,7 @@ export class CliHistoryStore { } }); - this.withRetry(() => transaction()); + await this.withRetry(() => transaction()); } /** @@ -852,11 +861,11 @@ export class CliHistoryStore { } /** - * Delete a conversation + * Delete a conversation (async for non-blocking retry) */ - deleteConversation(id: string): { success: boolean; error?: string } { + async deleteConversation(id: string): Promise<{ success: boolean; error?: string }> { try { - const result = this.withRetry(() => + const result = await this.withRetry(() => this.db.prepare('DELETE FROM conversations WHERE id = ?').run(id) ); return { success: result.changes > 0 }; @@ -866,9 +875,9 @@ export class CliHistoryStore { } /** - * Batch delete conversations + * Batch delete conversations (async for non-blocking retry) */ - batchDelete(ids: string[]): { success: boolean; deleted: number; errors?: string[] } { + async batchDelete(ids: string[]): Promise<{ success: boolean; deleted: number; errors?: string[] }> { const deleteStmt = this.db.prepare('DELETE FROM conversations WHERE id = ?'); const errors: string[] = []; let deleted = 0; @@ -884,7 +893,7 @@ export class CliHistoryStore { } }); - this.withRetry(() => transaction()); + await this.withRetry(() => transaction()); return { success: true, @@ -947,9 +956,9 @@ export class CliHistoryStore { // ========== Native Session Mapping Methods ========== /** - * Save or update native session mapping + * Save or update native session mapping (async for non-blocking retry) */ - saveNativeSessionMapping(mapping: NativeSessionMapping): void { + async saveNativeSessionMapping(mapping: NativeSessionMapping): Promise { const stmt = this.db.prepare(` INSERT INTO native_session_mapping (ccw_id, tool, native_session_id, native_session_path, project_hash, transaction_id, created_at) VALUES (@ccw_id, @tool, @native_session_id, @native_session_path, @project_hash, @transaction_id, @created_at) @@ -960,7 +969,7 @@ export class CliHistoryStore { transaction_id = @transaction_id `); - this.withRetry(() => stmt.run({ + await this.withRetry(() => stmt.run({ ccw_id: mapping.ccw_id, tool: mapping.tool, native_session_id: mapping.native_session_id, @@ -1144,7 +1153,7 @@ export class CliHistoryStore { // Persist mapping for future loads (best-effort). try { - this.saveNativeSessionMapping({ + await this.saveNativeSessionMapping({ ccw_id: ccwId, tool, native_session_id: best.sessionId, @@ -1290,9 +1299,9 @@ export class CliHistoryStore { // ========== Insights Methods ========== /** - * Save an insights analysis result + * Save an insights analysis result (async for non-blocking retry) */ - saveInsight(insight: { + async saveInsight(insight: { id: string; tool: string; promptCount: number; @@ -1301,13 +1310,13 @@ export class CliHistoryStore { rawOutput?: string; executionId?: string; lang?: string; - }): void { + }): Promise { const stmt = this.db.prepare(` INSERT OR REPLACE INTO insights (id, created_at, tool, prompt_count, patterns, suggestions, raw_output, execution_id, lang) VALUES (@id, @created_at, @tool, @prompt_count, @patterns, @suggestions, @raw_output, @execution_id, @lang) `); - this.withRetry(() => stmt.run({ + await this.withRetry(() => stmt.run({ id: insight.id, created_at: new Date().toISOString(), tool: insight.tool, @@ -1391,9 +1400,9 @@ export class CliHistoryStore { } /** - * Save or update a review for an execution + * Save or update a review for an execution (async for non-blocking retry) */ - saveReview(review: Omit & { created_at?: string; updated_at?: string }): ReviewRecord { + async saveReview(review: Omit & { created_at?: string; updated_at?: string }): Promise { const now = new Date().toISOString(); const created_at = review.created_at || now; const updated_at = review.updated_at || now; @@ -1409,7 +1418,7 @@ export class CliHistoryStore { updated_at = @updated_at `); - const result = this.withRetry(() => stmt.run({ + const result = await this.withRetry(() => stmt.run({ execution_id: review.execution_id, status: review.status, rating: review.rating ?? null, diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 792359bd..a8e35ab6 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -19,22 +19,7 @@ export default withMermaid(defineConfig({ // Ignore dead links for incomplete docs ignoreDeadLinks: true, head: [ - ['link', { rel: 'icon', href: '/favicon.svg', type: 'image/svg+xml' }], - [ - 'script', - {}, - `(() => { - try { - const theme = localStorage.getItem('ccw-theme') || 'blue' - document.documentElement.setAttribute('data-theme', theme) - - const mode = localStorage.getItem('ccw-color-mode') || 'auto' - const prefersDark = window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches - const isDark = mode === 'dark' || (mode === 'auto' && prefersDark) - document.documentElement.classList.toggle('dark', isDark) - } catch {} -})()` - ], + ['link', { rel: 'icon', href: `${base}favicon.svg`, type: 'image/svg+xml' }], ['meta', { name: 'theme-color', content: '#3b82f6' }], ['meta', { name: 'og:type', content: 'website' }], ['meta', { name: 'og:locale', content: 'en_US' }], @@ -227,6 +212,16 @@ export default withMermaid(defineConfig({ ] } ], + '/reference/': [ + { + text: '📚 Reference', + collapsible: true, + items: [ + { text: 'Commands & Skills', link: '/reference/commands-skills' }, + { text: 'Claude Code Hooks', link: '/reference/claude-code-hooks-guide' } + ] + } + ], '/agents/': [ { text: '🤖 Agents', @@ -244,6 +239,7 @@ export default withMermaid(defineConfig({ collapsible: true, items: [ { text: 'Overview', link: '/workflows/' }, + { text: 'Comparison Table', link: '/workflows/comparison-table' }, { text: '4-Level System', link: '/workflows/4-level' }, { text: 'Examples', link: '/workflows/examples' }, { text: 'Best Practices', link: '/workflows/best-practices' }, @@ -343,7 +339,8 @@ export default withMermaid(defineConfig({ { text: '指南', link: '/zh/guide/ch01-what-is-claude-dms3' }, { text: '命令', link: '/zh/commands/claude/' }, { text: '技能', link: '/zh/skills/claude-index' }, - { text: '功能', link: '/zh/features/spec' } + { text: '功能', link: '/zh/features/spec' }, + { text: '参考', link: '/zh/reference/commands-skills' } ], sidebar: { '/zh/guide/': [ @@ -469,11 +466,21 @@ export default withMermaid(defineConfig({ collapsible: true, items: [ { text: '概述', link: '/zh/workflows/' }, + { text: '工作流对比', link: '/zh/workflows/comparison-table' }, { text: '四级体系', link: '/zh/workflows/4-level' }, { text: '最佳实践', link: '/zh/workflows/best-practices' }, { text: '团队协作', link: '/zh/workflows/teams' } ] } + ], + '/zh/reference/': [ + { + text: '📚 参考', + collapsible: true, + items: [ + { text: '命令与技能参考', link: '/zh/reference/commands-skills' } + ] + } ] } } diff --git a/docs/reference/commands-skills.md b/docs/reference/commands-skills.md new file mode 100644 index 00000000..7d0f9f5b --- /dev/null +++ b/docs/reference/commands-skills.md @@ -0,0 +1,753 @@ +# Commands & Skills Reference + +> **Quick Reference**: Complete catalog of Claude commands, skills, and Codex capabilities + +--- + +## Table of Contents + +1. [Main Orchestrator Commands](#1-main-orchestrator-commands) +2. [Workflow Session Commands](#2-workflow-session-commands) +3. [Issue Workflow Commands](#3-issue-workflow-commands) +4. [IDAW Commands](#4-idaw-commands) +5. [With-File Workflows](#5-with-file-workflows) +6. [Cycle Workflows](#6-cycle-workflows) +7. [CLI Commands](#7-cli-commands) +8. [Memory Commands](#8-memory-commands) +9. [Team Skills](#9-team-skills) +10. [Workflow Skills](#10-workflow-skills) +11. [Utility Skills](#11-utility-skills) +12. [Codex Capabilities](#12-codex-capabilities) + +--- + +## Quick Reference Table + +### Commands Quick Reference + +| Category | Command | Description | Arguments | +|----------|---------|-------------|-----------| +| **Orchestrator** | `/ccw` | Main workflow orchestrator | `"task description"` | +| **Orchestrator** | `/ccw-coordinator` | Command orchestration tool | `[task description]` | +| **Session** | `/workflow:session:start` | Start workflow session | `[--type] [--auto|--new] [task]` | +| **Session** | `/workflow:session:resume` | Resume paused session | - | +| **Session** | `/workflow:session:complete` | Complete active session | `[-y] [--detailed]` | +| **Session** | `/workflow:session:list` | List all sessions | - | +| **Session** | `/workflow:session:sync` | Sync session to specs | `[-y] ["what was done"]` | +| **Session** | `/workflow:session:solidify` | Crystallize learnings | `[--type] [--category] "rule"` | +| **Issue** | `/issue:new` | Create structured issue | ` [--priority 1-5]` | +| **Issue** | `/issue:discover` | Discover potential issues | ` [--perspectives=...]` | +| **Issue** | `/issue:plan` | Plan issue resolution | `--all-pending ` | +| **Issue** | `/issue:queue` | Form execution queue | `[--queues ] [--issue ]` | +| **Issue** | `/issue:execute` | Execute queue | `--queue [--worktree]` | +| **IDAW** | `/idaw:run` | IDAW orchestrator | `[--task ] [--dry-run]` | +| **IDAW** | `/idaw:add` | Add task to queue | - | +| **IDAW** | `/idaw:resume` | Resume IDAW session | - | +| **IDAW** | `/idaw:status` | Show queue status | - | +| **With-File** | `/workflow:brainstorm-with-file` | Interactive brainstorming | `[-c] [-m creative|structured] "topic"` | +| **With-File** | `/workflow:analyze-with-file` | Collaborative analysis | `[-c] "topic"` | +| **With-File** | `/workflow:debug-with-file` | Hypothesis-driven debugging | `"bug description"` | +| **With-File** | `/workflow:collaborative-plan-with-file` | Multi-agent planning | - | +| **With-File** | `/workflow:roadmap-with-file` | Strategic roadmap | - | +| **Cycle** | `/workflow:integration-test-cycle` | Integration test cycle | - | +| **Cycle** | `/workflow:refactor-cycle` | Refactor cycle | - | +| **CLI** | `/cli:codex-review` | Codex code review | `[--uncommitted|--base|--commit]` | +| **CLI** | `/cli:cli-init` | Initialize CLI config | - | +| **Memory** | `/memory:prepare` | Prepare memory context | - | +| **Memory** | `/memory:style-skill-memory` | Style/skill memory | - | + +### Skills Quick Reference + +| Category | Skill | Internal Pipeline | Use Case | +|----------|-------|-------------------|----------| +| **Workflow** | workflow-lite-planex | explore → plan → confirm → execute | Quick features, bug fixes | +| **Workflow** | workflow-plan | session → context → convention → gen → verify/replan | Complex feature planning | +| **Workflow** | workflow-execute | session discovery → task processing → commit | Execute pre-generated plans | +| **Workflow** | workflow-tdd-plan | 6-phase TDD plan → verify | TDD development | +| **Workflow** | workflow-test-fix | session → context → analysis → gen → cycle | Test generation and fixes | +| **Workflow** | workflow-multi-cli-plan | ACE context → CLI discussion → plan → execute | Multi-perspective planning | +| **Workflow** | workflow-skill-designer | - | Create new skills | +| **Team** | team-lifecycle-v5 | spec pipeline → impl pipeline | Full lifecycle | +| **Team** | team-planex | planner wave → executor wave | Issue batch execution | +| **Team** | team-arch-opt | architecture analysis → optimization | Architecture optimization | +| **Utility** | brainstorm | framework → parallel analysis → synthesis | Multi-perspective ideation | +| **Utility** | review-cycle | discovery → analysis → aggregation → deep-dive | Code review | +| **Utility** | spec-generator | study → brief → PRD → architecture → epics | Specification packages | + +--- + +## 1. Main Orchestrator Commands + +### /ccw + +**Description**: Main workflow orchestrator - analyze intent, select workflow, execute command chain in main process + +**Arguments**: `"task description"` + +**Category**: orchestrator + +**5-Phase Workflow**: +1. Phase 1: Analyze Intent (detect task type, complexity, clarity) +2. Phase 1.5: Requirement Clarification (if clarity < 2) +3. Phase 2: Select Workflow & Build Command Chain +4. Phase 3: User Confirmation +5. Phase 4: Setup TODO Tracking & Status File +6. Phase 5: Execute Command Chain + +**Skill Mapping**: + +| Skill | Internal Pipeline | +|-------|-------------------| +| workflow-lite-planex | explore → plan → confirm → execute | +| workflow-plan | session → context → convention → gen → verify/replan | +| workflow-execute | session discovery → task processing → commit | +| workflow-tdd-plan | 6-phase TDD plan → verify | +| workflow-test-fix | session → context → analysis → gen → cycle | +| workflow-multi-cli-plan | ACE context → CLI discussion → plan → execute | +| review-cycle | session/module review → fix orchestration | +| brainstorm | auto/single-role → artifacts → analysis → synthesis | +| spec-generator | product-brief → PRD → architecture → epics | + +**Auto Mode**: `-y` or `--yes` flag skips confirmations, propagates to all skills + +--- + +### /ccw-coordinator + +**Description**: Command orchestration tool - analyze requirements, recommend chain, execute sequentially with state persistence + +**Arguments**: `[task description]` + +**Category**: orchestrator + +**3-Phase Workflow**: +1. Phase 1: Analyze Requirements +2. Phase 2: Discover Commands & Recommend Chain +3. Phase 3: Execute Sequential Command Chain + +**Minimum Execution Units**: + +| Unit | Commands | Purpose | +|------|----------|---------| +| Quick Implementation | lite-plan (plan → execute) | Lightweight plan and execution | +| Multi-CLI Planning | multi-cli-plan | Multi-perspective planning | +| Bug Fix | lite-plan --bugfix | Bug diagnosis and fix | +| Full Planning + Execution | plan → execute | Detailed planning | +| Verified Planning + Execution | plan → plan-verify → execute | Planning with verification | +| TDD Planning + Execution | tdd-plan → execute | TDD workflow | +| Issue Workflow | discover → plan → queue → execute | Complete issue lifecycle | + +--- + +### /flow-create + +**Description**: Flow template generator for meta-skill/flow-coordinator + +**Arguments**: `[template-name] [--output ]` + +**Category**: utility + +**Execution Flow**: +1. Phase 1: Template Design (name + description + level) +2. Phase 2: Step Definition (command category → specific command → execution unit → mode) +3. Phase 3: Generate JSON + +--- + +## 2. Workflow Session Commands + +### /workflow:session:start + +**Description**: Discover existing sessions or start new workflow session with intelligent session management and conflict detection + +**Arguments**: `[--type ] [--auto|--new] [task description]` + +**Category**: session-management + +**Session Types**: + +| Type | Description | Default For | +|------|-------------|-------------| +| workflow | Standard implementation | workflow-plan skill | +| review | Code review sessions | review-cycle skill | +| tdd | TDD-based development | workflow-tdd-plan skill | +| test | Test generation/fix | workflow-test-fix skill | +| docs | Documentation sessions | memory-manage skill | + +**Modes**: +- **Discovery Mode** (default): List active sessions, prompt user +- **Auto Mode** (`--auto`): Intelligent session selection +- **Force New Mode** (`--new`): Create new session + +--- + +### /workflow:session:resume + +**Description**: Resume the most recently paused workflow session with automatic session discovery and status update + +**Category**: session-management + +--- + +### /workflow:session:complete + +**Description**: Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag + +**Arguments**: `[-y|--yes] [--detailed]` + +**Category**: session-management + +**Execution Phases**: +1. Find Session +2. Generate Manifest Entry +3. Atomic Commit (mv to archives) +4. Auto-Sync Project State + +--- + +### /workflow:session:list + +**Description**: List all workflow sessions with status filtering, shows session metadata and progress information + +**Category**: session-management + +--- + +### /workflow:session:sync + +**Description**: Quick-sync session work to specs/*.md and project-tech + +**Arguments**: `[-y|--yes] ["what was done"]` + +**Category**: session-management + +**Process**: +1. Gather Context (git diff, session, summary) +2. Extract Updates (guidelines, tech) +3. Preview & Confirm +4. Write both files + +--- + +### /workflow:session:solidify + +**Description**: Crystallize session learnings and user-defined constraints into permanent project guidelines, or compress recent memories + +**Arguments**: `[-y|--yes] [--type ] [--category ] [--limit ] "rule or insight"` + +**Category**: session-management + +**Type Categories**: + +| Type | Subcategories | +|------|---------------| +| convention | coding_style, naming_patterns, file_structure, documentation | +| constraint | architecture, tech_stack, performance, security | +| learning | architecture, performance, security, testing, process, other | +| compress | (operates on core memories) | + +--- + +## 3. Issue Workflow Commands + +### /issue:new + +**Description**: Create structured issue from GitHub URL or text description + +**Arguments**: `[-y|--yes] [--priority 1-5]` + +**Category**: issue + +**Execution Flow**: +1. Input Analysis & Clarity Detection +2. Data Extraction (GitHub or Text) +3. Lightweight Context Hint (ACE for medium clarity) +4. Conditional Clarification +5. GitHub Publishing Decision +6. Create Issue + +--- + +### /issue:discover + +**Description**: Discover potential issues from multiple perspectives using CLI explore. Supports Exa external research for security and best-practices perspectives. + +**Arguments**: `[-y|--yes] [--perspectives=bug,ux,...] [--external]` + +**Category**: issue + +**Available Perspectives**: + +| Perspective | Focus | Categories | +|-------------|-------|------------| +| bug | Potential Bugs | edge-case, null-check, resource-leak, race-condition | +| ux | User Experience | error-message, loading-state, feedback, accessibility | +| test | Test Coverage | missing-test, edge-case-test, integration-gap | +| quality | Code Quality | complexity, duplication, naming, documentation | +| security | Security Issues | injection, auth, encryption, input-validation | +| performance | Performance | n-plus-one, memory-usage, caching, algorithm | +| maintainability | Maintainability | coupling, cohesion, tech-debt, extensibility | +| best-practices | Best Practices | convention, pattern, framework-usage, anti-pattern | + +--- + +### /issue:plan + +**Description**: Batch plan issue resolution using issue-plan-agent (explore + plan closed-loop) + +**Arguments**: `[-y|--yes] --all-pending [,,...] [--batch-size 3]` + +**Category**: issue + +**Execution Process**: +1. Issue Loading & Intelligent Grouping +2. Unified Explore + Plan (issue-plan-agent) +3. Solution Registration & Binding +4. Summary + +--- + +### /issue:queue + +**Description**: Form execution queue from bound solutions using issue-queue-agent (solution-level) + +**Arguments**: `[-y|--yes] [--queues ] [--issue ]` + +**Category**: issue + +**Core Capabilities**: +- Agent-driven ordering logic +- Solution-level granularity +- Conflict clarification +- Parallel/Sequential group assignment + +--- + +### /issue:execute + +**Description**: Execute queue with DAG-based parallel orchestration (one commit per solution) + +**Arguments**: `[-y|--yes] --queue [--worktree []]` + +**Category**: issue + +**Execution Flow**: +1. Validate Queue ID (REQUIRED) +2. Get DAG & User Selection +3. Dispatch Parallel Batch (DAG-driven) +4. Next Batch (repeat) +5. Worktree Completion + +**Recommended Executor**: Codex (2hr timeout, full write access) + +--- + +### /issue:from-brainstorm + +**Description**: Convert brainstorm session ideas into issue with executable solution for parallel-dev-cycle + +**Arguments**: `SESSION="" [--idea=] [--auto] [-y|--yes]` + +**Category**: issue + +**Execution Flow**: +1. Session Loading +2. Idea Selection +3. Enrich Issue Context +4. Create Issue +5. Generate Solution Tasks +6. Bind Solution + +--- + +## 4. IDAW Commands + +### /idaw:run + +**Description**: IDAW orchestrator - execute task skill chains serially with git checkpoints + +**Arguments**: `[-y|--yes] [--task [,,...]] [--dry-run]` + +**Category**: idaw + +**Skill Chain Mapping**: + +| Task Type | Skill Chain | +|-----------|-------------| +| bugfix | workflow-lite-planex → workflow-test-fix | +| bugfix-hotfix | workflow-lite-planex | +| feature | workflow-lite-planex → workflow-test-fix | +| feature-complex | workflow-plan → workflow-execute → workflow-test-fix | +| refactor | workflow:refactor-cycle | +| tdd | workflow-tdd-plan → workflow-execute | +| test | workflow-test-fix | +| test-fix | workflow-test-fix | +| review | review-cycle | +| docs | workflow-lite-planex | + +**6-Phase Execution**: +1. Load Tasks +2. Session Setup +3. Startup Protocol +4. Main Loop (serial, one task at a time) +5. Checkpoint (per task) +6. Report + +--- + +### /idaw:add + +**Description**: Add task to IDAW queue with auto-inferred task type and skill chain + +**Category**: idaw + +--- + +### /idaw:resume + +**Description**: Resume IDAW session with crash recovery + +**Category**: idaw + +--- + +### /idaw:status + +**Description**: Show IDAW queue status + +**Category**: idaw + +--- + +### /idaw:run-coordinate + +**Description**: Multi-agent IDAW execution with parallel task coordination + +**Category**: idaw + +--- + +## 5. With-File Workflows + +### /workflow:brainstorm-with-file + +**Description**: Interactive brainstorming with multi-CLI collaboration, idea expansion, and documented thought evolution + +**Arguments**: `[-y|--yes] [-c|--continue] [-m|--mode creative|structured] "idea or topic"` + +**Category**: with-file + +**Output Directory**: `.workflow/.brainstorm/{session-id}/` + +**4-Phase Workflow**: +1. Phase 1: Seed Understanding (parse topic, select roles, expand vectors) +2. Phase 2: Divergent Exploration (cli-explore-agent + Multi-CLI perspectives) +3. Phase 3: Interactive Refinement (multi-round) +4. Phase 4: Convergence & Crystallization + +**Output Artifacts**: +- `brainstorm.md` - Complete thought evolution timeline +- `exploration-codebase.json` - Codebase context +- `perspectives.json` - Multi-CLI findings +- `synthesis.json` - Final synthesis + +--- + +### /workflow:analyze-with-file + +**Description**: Interactive collaborative analysis with documented discussions, CLI-assisted exploration, and evolving understanding + +**Arguments**: `[-y|--yes] [-c|--continue] "topic or question"` + +**Category**: with-file + +**Output Directory**: `.workflow/.analysis/{session-id}/` + +**4-Phase Workflow**: +1. Phase 1: Topic Understanding +2. Phase 2: CLI Exploration (cli-explore-agent + perspectives) +3. Phase 3: Interactive Discussion (multi-round) +4. Phase 4: Synthesis & Conclusion + +**Decision Recording Protocol**: Must record direction choices, key findings, assumption changes, user feedback + +--- + +### /workflow:debug-with-file + +**Description**: Interactive hypothesis-driven debugging with documented exploration, understanding evolution, and Gemini-assisted correction + +**Arguments**: `[-y|--yes] "bug description or error message"` + +**Category**: with-file + +**Output Directory**: `.workflow/.debug/{session-id}/` + +**Core Workflow**: Explore → Document → Log → Analyze → Correct Understanding → Fix → Verify + +**Output Artifacts**: +- `debug.log` - NDJSON execution evidence +- `understanding.md` - Exploration timeline + consolidated understanding +- `hypotheses.json` - Hypothesis history with verdicts + +--- + +### /workflow:collaborative-plan-with-file + +**Description**: Multi-agent collaborative planning with Plan Note shared doc + +**Category**: with-file + +--- + +### /workflow:roadmap-with-file + +**Description**: Strategic requirement roadmap → issue creation → execution-plan.json + +**Category**: with-file + +--- + +### /workflow:unified-execute-with-file + +**Description**: Universal execution engine - consumes plan output from collaborative-plan, roadmap, brainstorm + +**Category**: with-file + +--- + +## 6. Cycle Workflows + +### /workflow:integration-test-cycle + +**Description**: Self-iterating integration test with reflection - explore → test dev → test-fix cycle → reflection + +**Category**: cycle + +**Output Directory**: `.workflow/.test-cycle/` + +--- + +### /workflow:refactor-cycle + +**Description**: Tech debt discovery → prioritize → execute → validate + +**Category**: cycle + +**Output Directory**: `.workflow/.refactor-cycle/` + +--- + +## 7. CLI Commands + +### /cli:codex-review + +**Description**: Interactive code review using Codex CLI via ccw endpoint with configurable review target, model, and custom instructions + +**Arguments**: `[--uncommitted|--base |--commit ] [--model ] [--title ] [prompt]` + +**Category**: cli + +**Review Targets**: + +| Target | Flag | Description | +|--------|------|-------------| +| Uncommitted changes | `--uncommitted` | Review staged, unstaged, and untracked changes | +| Compare to branch | `--base <BRANCH>` | Review changes against base branch | +| Specific commit | `--commit <SHA>` | Review changes introduced by a commit | + +**Focus Areas**: General review, Security focus, Performance focus, Code quality + +**Important**: Target flags and prompt are mutually exclusive + +--- + +### /cli:cli-init + +**Description**: Initialize CLI configuration for ccw endpoint + +**Category**: cli + +--- + +## 8. Memory Commands + +### /memory:prepare + +**Description**: Prepare memory context for session + +**Category**: memory + +--- + +### /memory:style-skill-memory + +**Description**: Style and skill memory management + +**Category**: memory + +--- + +## 9. Team Skills + +### Team Lifecycle Skills + +| Skill | Description | +|-------|-------------| +| team-lifecycle-v5 | Full team lifecycle with role-spec-driven worker agents | +| team-planex | Planner + executor wave pipeline (for large issue batches or roadmap outputs) | +| team-coordinate-v2 | Team coordination and orchestration | +| team-executor-v2 | Task execution with worker agents | +| team-arch-opt | Architecture optimization skill | + +### Team Domain Skills + +| Skill | Description | +|-------|-------------| +| team-brainstorm | Multi-perspective brainstorming | +| team-review | Code review workflow | +| team-testing | Testing workflow | +| team-frontend | Frontend development workflow | +| team-issue | Issue management workflow | +| team-iterdev | Iterative development workflow | +| team-perf-opt | Performance optimization workflow | +| team-quality-assurance | QA workflow | +| team-roadmap-dev | Roadmap development workflow | +| team-tech-debt | Technical debt management | +| team-uidesign | UI design workflow | +| team-ultra-analyze | Deep analysis workflow | + +--- + +## 10. Workflow Skills + +| Skill | Internal Pipeline | Description | +|-------|-------------------|-------------| +| workflow-lite-planex | explore → plan → confirm → execute | Lightweight merged-mode planning | +| workflow-plan | session → context → convention → gen → verify/replan | Full planning with architecture design | +| workflow-execute | session discovery → task processing → commit | Execute from planning session | +| workflow-tdd-plan | 6-phase TDD plan → verify | TDD workflow planning | +| workflow-test-fix | session → context → analysis → gen → cycle | Test generation and fix cycle | +| workflow-multi-cli-plan | ACE context → CLI discussion → plan → execute | Multi-CLI collaborative planning | +| workflow-skill-designer | - | Workflow skill design and generation | + +--- + +## 11. Utility Skills + +| Skill | Description | +|-------|-------------| +| brainstorm | Unified brainstorming skill (auto-parallel + role analysis) | +| review-code | Code review skill | +| review-cycle | Session/module review → fix orchestration | +| spec-generator | Product-brief → PRD → architecture → epics | +| skill-generator | Generate new skills | +| skill-tuning | Tune existing skills | +| command-generator | Generate new commands | +| memory-capture | Capture session memories | +| memory-manage | Manage stored memories | +| issue-manage | Issue management utility | +| ccw-help | CCW help and documentation | + +--- + +## 12. Codex Capabilities + +### Codex Review Mode + +**Command**: `ccw cli --tool codex --mode review [OPTIONS]` + +| Option | Description | +|--------|-------------| +| `[PROMPT]` | Custom review instructions (positional, no target flags) | +| `-c model=<model>` | Override model via config | +| `--uncommitted` | Review staged, unstaged, and untracked changes | +| `--base <BRANCH>` | Review changes against base branch | +| `--commit <SHA>` | Review changes introduced by a commit | +| `--title <TITLE>` | Optional commit title for review summary | + +**Available Models**: +- Default: gpt-5.2 +- o3: OpenAI o3 reasoning model +- gpt-4.1: GPT-4.1 model +- o4-mini: OpenAI o4-mini (faster) + +**Constraints**: +- Target flags (`--uncommitted`, `--base`, `--commit`) **cannot** be used with positional `[PROMPT]` +- Custom prompts only supported WITHOUT target flags (reviews uncommitted by default) + +### Codex Integration Points + +| Integration Point | Description | +|-------------------|-------------| +| CLI endpoint | `ccw cli --tool codex --mode <analysis\|write\|review>` | +| Multi-CLI planning | Pragmatic perspective in workflow-multi-cli-plan | +| Code review | `/cli:codex-review` command | +| Issue execution | Recommended executor for `/issue:execute` | +| Devil's advocate | Challenge mode in brainstorm refinement | + +### Codex Mode Summary + +| Mode | Permission | Use Case | +|------|------------|----------| +| analysis | Read-only | Code analysis, architecture review | +| write | Full access | Implementation, file modifications | +| review | Read-only output | Git-aware code review | + +--- + +## Summary Statistics + +| Category | Count | +|----------|-------| +| Main Orchestrator Commands | 3 | +| Workflow Session Commands | 6 | +| Issue Workflow Commands | 6 | +| IDAW Commands | 5 | +| With-File Workflows | 6 | +| Cycle Workflows | 2 | +| CLI Commands | 2 | +| Memory Commands | 2 | +| Team Skills | 17 | +| Workflow Skills | 7 | +| Utility Skills | 11 | +| **Total Commands** | 32 | +| **Total Skills** | 35 | + +--- + +## Invocation Patterns + +### Slash Command Invocation + +``` +/<namespace>:<command> [arguments] [flags] +``` + +Examples: +- `/ccw "Add user authentication"` +- `/workflow:session:start --auto "implement feature"` +- `/issue:new https://github.com/org/repo/issues/123` +- `/cli:codex-review --base main` + +### Skill Invocation (from code) + +```javascript +Skill({ skill: "workflow-lite-planex", args: '"task description"' }) +Skill({ skill: "brainstorm", args: '"topic or question"' }) +Skill({ skill: "review-cycle", args: '--session="WFS-xxx"' }) +``` + +### CLI Tool Invocation + +```bash +ccw cli -p "PURPOSE: ... TASK: ... MODE: analysis|write" --tool <tool> --mode <mode> +``` + +--- + +## Related Documentation + +- [Workflow Comparison Table](../workflows/comparison-table.md) - Workflow selection guide +- [Workflow Overview](../workflows/index.md) - 4-Level workflow system +- [Claude Workflow Skills](../skills/claude-workflow.md) - Detailed skill documentation diff --git a/docs/skills/claude-workflow.md b/docs/skills/claude-workflow.md index 4b30ddae..ebe166ad 100644 --- a/docs/skills/claude-workflow.md +++ b/docs/skills/claude-workflow.md @@ -24,6 +24,9 @@ | `workflow-tdd-plan` | TDD workflow | `/workflow-tdd-plan` | | `workflow-test-fix` | Test-fix workflow | `/workflow-test-fix` | | `workflow-skill-designer` | Skill design workflow | `/workflow-skill-designer` | +| `team-arch-opt` | Architecture optimization | `/team-arch-opt` | + +> **New in 7.2.1**: `team-arch-opt` skill added for architecture analysis and optimization. `workflow-lite-planex` renamed from `workflow-lite-plan`. ## Skills Details @@ -323,6 +326,30 @@ Wave 2: Issue 6-10 → Parallel planning → Parallel execution ... ``` +--- + +### team-arch-opt + +**One-Liner**: Architecture optimization — Analyze and optimize system architecture + +**Trigger**: +```shell +/team-arch-opt +/ccw "team arch opt: analyze module structure" +``` + +**Features**: +- Architecture analysis and assessment +- Optimization recommendations +- Team-based architecture review +- Role-spec-driven worker agents + +**Use Cases**: +- Architecture health assessment +- Module dependency analysis +- Performance bottleneck identification +- Technical debt evaluation + ## Related Commands - [Claude Commands - Workflow](../commands/claude/workflow.md) diff --git a/docs/workflows/comparison-table.md b/docs/workflows/comparison-table.md new file mode 100644 index 00000000..c6f7a8a7 --- /dev/null +++ b/docs/workflows/comparison-table.md @@ -0,0 +1,175 @@ +# Workflow Comparison Table + +> **Complete reference for all CCW workflows** - Compare workflows by invocation, pipeline, use case, complexity, and auto-chain behavior. + +## Quick Reference + +| Workflow | Best For | Level | Self-Contained | +|----------|----------|-------|----------------| +| workflow-lite-planex | Quick tasks, bug fixes | 2 (Lightweight) | YES | +| workflow-plan → workflow-execute | Complex features | 3-4 (Standard) | NO (requires execute) | +| workflow-tdd-plan → workflow-execute | TDD development | 3 (Standard) | NO (requires execute) | +| workflow-test-fix | Test generation/fix | 3 (Standard) | YES | +| workflow-multi-cli-plan | Multi-perspective planning | 3 (Standard) | YES | +| brainstorm-with-file | Ideation, exploration | 4 (Full) | NO (chains to plan) | +| analyze-with-file | Deep analysis | 3 (Standard) | NO (chains to lite-plan) | +| debug-with-file | Hypothesis-driven debugging | 3 (Standard) | YES | +| collaborative-plan-with-file | Multi-agent planning | 3 (Standard) | NO (chains to execute) | +| roadmap-with-file | Strategic roadmaps | 4 (Strategic) | NO (chains to team-planex) | +| integration-test-cycle | Integration testing | 3 (Standard) | YES | +| refactor-cycle | Tech debt refactoring | 3 (Standard) | YES | +| review-cycle | Code review | 3 (Standard) | YES | +| spec-generator | Specification packages | 4 (Full) | NO (chains to plan) | +| team-planex | Issue batch execution | Team | YES | +| team-lifecycle-v5 | Full lifecycle | Team | YES | +| issue pipeline | Issue management | 2.5 (Bridge) | YES | + +--- + +## Complete Comparison Table + +| Workflow | Invocation | Pipeline | Use Case | Level | Self-Contained | Auto-Chains To | +|----------|------------|----------|----------|-------|----------------|----------------| +| **Plan+Execute Workflows** | +| workflow-lite-planex | `/ccw "task"` (auto for low/medium complexity) | explore → plan → confirm → execute | Quick features, bug fixes, simple tasks | 2 (Lightweight) | YES | workflow-test-fix | +| workflow-plan | `/ccw "complex feature"` (high complexity) | session → context → convention → gen → verify/replan | Complex feature planning, formal verification | 3-4 (Standard) | NO | workflow-execute | +| workflow-execute | `/workflow-execute` (after plan) | session discovery → task processing → commit | Execute pre-generated plans | 3 (Standard) | YES | review-cycle (optional) | +| workflow-multi-cli-plan | `/ccw "multi-cli plan: ..."` | ACE context → CLI discussion → plan → execute | Multi-perspective planning | 3 (Standard) | YES | (internal handoff) | +| **TDD Workflows** | +| workflow-tdd-plan | `/ccw "Implement with TDD"` | 6-phase TDD plan → verify | Test-driven development planning | 3 (Standard) | NO | workflow-execute | +| workflow-test-fix | `/ccw "generate tests"` or auto-chained | session → context → analysis → gen → cycle | Test generation, coverage improvement | 3 (Standard) | YES | (standalone) | +| **Brainstorm Workflows** | +| brainstorm | `/brainstorm "topic"` | mode detect → framework → parallel analysis → synthesis | Multi-perspective ideation | 4 (Full) | YES (ideation only) | workflow-plan | +| brainstorm-with-file | `/ccw "brainstorm: ..."` | brainstorm + documented artifacts | Documented ideation with session | 4 (Full) | NO | workflow-plan → execute | +| collaborative-plan-with-file | `/ccw "collaborative plan: ..."` | understanding → parallel agents → plan-note.md | Multi-agent collaborative planning | 3 (Standard) | NO | unified-execute-with-file | +| **Analysis Workflows** | +| analyze-with-file | `/ccw "analyze: ..."` | multi-CLI analysis → discussion.md | Deep understanding, architecture exploration | 3 (Standard) | NO | workflow-lite-planex | +| debug-with-file | `/ccw "debug: ..."` | hypothesis-driven iteration → debug.log | Systematic debugging | 3 (Standard) | YES | (standalone) | +| **Review Workflows** | +| review-cycle | `/ccw "review code"` | discovery → analysis → aggregation → deep-dive → completion | Code review, quality gates | 3 (Standard) | YES | fix mode (if findings) | +| **Specification Workflows** | +| spec-generator | `/ccw "specification: ..."` | study → discovery → brief → PRD → architecture → epics | Complete specification package | 4 (Full) | YES (docs only) | workflow-plan / team-planex | +| **Team Workflows** | +| team-planex | `/ccw "team planex: ..."` | coordinator → planner wave → executor wave | Issue-based parallel execution | Team | YES | (complete pipeline) | +| team-lifecycle-v5 | `/ccw "team lifecycle: ..."` | spec pipeline → impl pipeline | Full lifecycle specification to validation | Team | YES | (complete lifecycle) | +| team-arch-opt | (architecture optimization) | architecture analysis → optimization | Architecture optimization | Team | YES | (complete) | +| **Cycle Workflows** | +| integration-test-cycle | `/ccw "integration test: ..."` | explore → test dev → test-fix cycle → reflection | Integration testing with iteration | 3 (Standard) | YES | (self-iterating) | +| refactor-cycle | `/ccw "refactor: ..."` | discover → prioritize → execute → validate | Tech debt discovery and refactoring | 3 (Standard) | YES | (self-iterating) | +| **Issue Workflow** | +| issue pipeline | `/ccw "use issue workflow"` | discover → plan → queue → execute | Structured issue management | 2.5 (Bridge) | YES | (complete pipeline) | +| **Roadmap Workflow** | +| roadmap-with-file | `/ccw "roadmap: ..."` | strategic roadmap → issue creation → execution-plan | Strategic requirement decomposition | 4 (Strategic) | NO | team-planex | + +--- + +## Workflow Level Classification + +| Level | Workflows | Characteristics | +|-------|-----------|-----------------| +| **2 (Lightweight)** | workflow-lite-planex, docs | Quick execution, minimal phases | +| **2.5 (Bridge)** | issue pipeline, rapid-to-issue | Bridge to issue workflow | +| **3 (Standard)** | workflow-plan, workflow-execute, workflow-tdd-plan, workflow-test-fix, review-cycle, debug-with-file, analyze-with-file, workflow-multi-cli-plan | Full planning/execution, multi-phase | +| **4 (Full)** | brainstorm, spec-generator, brainstorm-with-file, roadmap-with-file | Complete exploration, specification | +| **Team** | team-planex, team-lifecycle-v5, team-arch-opt | Multi-agent parallel execution | +| **Cycle** | integration-test-cycle, refactor-cycle | Self-iterating with reflection | + +--- + +## Auto-Chain Reference + +| Source Workflow | Auto-Chains To | Condition | +|-----------------|---------------|-----------| +| workflow-lite-planex | workflow-test-fix | Default (unless skip-tests) | +| workflow-plan | workflow-execute | After plan confirmation | +| workflow-execute | review-cycle | User choice via Phase 6 | +| workflow-tdd-plan | workflow-execute | After TDD plan validation | +| brainstorm | workflow-plan | Auto-chain for formal planning | +| brainstorm-with-file | workflow-plan → workflow-execute | Auto | +| analyze-with-file | workflow-lite-planex | Auto | +| debug-with-file | (none) | Standalone | +| collaborative-plan-with-file | unified-execute-with-file | Auto | +| roadmap-with-file | team-planex | Auto | +| spec-generator | workflow-plan / team-planex | User choice | +| review-cycle | fix mode | If findings exist | + +--- + +## Self-Contained vs Multi-Skill + +| Workflow | Self-Contained | Notes | +|----------|---------------|-------| +| workflow-lite-planex | YES | Complete plan + execute | +| workflow-plan | NO | Requires workflow-execute | +| workflow-execute | YES | Complete execution | +| workflow-tdd-plan | NO | Requires workflow-execute | +| workflow-test-fix | YES | Complete generation + execution | +| brainstorm | YES (ideation) | NO for implementation | +| review-cycle | YES | Complete review + optional fix | +| spec-generator | YES (docs) | NO for implementation | +| team-planex | YES | Complete team pipeline | +| team-lifecycle-v5 | YES | Complete lifecycle | +| debug-with-file | YES | Complete debugging | +| integration-test-cycle | YES | Self-iterating | +| refactor-cycle | YES | Self-iterating | + +--- + +## Keyword Detection Reference + +| Keyword Pattern | Detected Workflow | +|-----------------|-------------------| +| `urgent`, `critical`, `hotfix` | bugfix-hotfix | +| `from scratch`, `greenfield`, `new project` | greenfield | +| `brainstorm`, `ideation`, `multi-perspective` | brainstorm | +| `debug`, `hypothesis`, `systematic` | debug-with-file | +| `analyze`, `understand`, `collaborative analysis` | analyze-with-file | +| `roadmap` | roadmap-with-file | +| `specification`, `PRD`, `产品需求` | spec-generator | +| `integration test`, `集成测试` | integration-test-cycle | +| `refactor`, `技术债务` | refactor-cycle | +| `team planex`, `wave pipeline` | team-planex | +| `multi-cli`, `多模型协作` | workflow-multi-cli-plan | +| `TDD`, `test-driven` | workflow-tdd-plan | +| `review`, `code review` | review-cycle | +| `issue workflow`, `use issue workflow` | issue pipeline | + +--- + +## Workflow Selection Guide + +| Task Type | Recommended Workflow | Command Chain | +|-----------|---------------------|---------------| +| Quick feature | `/ccw "..."` | lite-planex → test-fix | +| Bug fix | `/ccw "fix ..."` | lite-planex --bugfix → test-fix | +| Complex feature | `/ccw "..."` (detected) | plan → execute → review → test-fix | +| Exploration | `/workflow:analyze-with-file "..."` | analysis → (optional) lite-planex | +| Ideation | `/workflow:brainstorm-with-file "..."` | brainstorm → plan → execute | +| Debugging | `/workflow:debug-with-file "..."` | hypothesis-driven debugging | +| Issue management | `/issue:new` → `/issue:plan` → `/issue:queue` → `/issue:execute` | issue workflow | +| Multi-issue batch | `/issue:discover` → `/issue:plan --all-pending` | issue batch workflow | +| Code review | `/cli:codex-review --uncommitted` | codex review | +| Team coordination | `team-lifecycle-v5` or `team-planex` | team workflow | +| TDD development | `/ccw "Implement with TDD"` | tdd-plan → execute | +| Integration testing | `/ccw "integration test: ..."` | integration-test-cycle | +| Tech debt | `/ccw "refactor: ..."` | refactor-cycle | +| Specification docs | `/ccw "specification: ..."` | spec-generator → plan | + +--- + +## Greenfield Development Paths + +| Size | Pipeline | Complexity | +|------|----------|------------| +| Small | brainstorm-with-file → workflow-plan → workflow-execute | 3 | +| Medium | brainstorm-with-file → workflow-plan → workflow-execute → workflow-test-fix | 3 | +| Large | brainstorm-with-file → workflow-plan → workflow-execute → review-cycle → workflow-test-fix | 4 | + +--- + +## Related Documentation + +- [4-Level System](./4-level.md) - Detailed workflow explanation +- [Best Practices](./best-practices.md) - Workflow optimization tips +- [Examples](./examples.md) - Workflow usage examples +- [Teams](./teams.md) - Team workflow coordination diff --git a/docs/zh/reference/commands-skills.md b/docs/zh/reference/commands-skills.md new file mode 100644 index 00000000..7d300436 --- /dev/null +++ b/docs/zh/reference/commands-skills.md @@ -0,0 +1,753 @@ +# 命令与技能参考 + +> **快速参考**: Claude 命令、技能和 Codex 能力的完整目录 + +--- + +## 目录 + +1. [主编排器命令](#1-主编排器命令) +2. [工作流会话命令](#2-工作流会话命令) +3. [Issue 工作流命令](#3-issue-工作流命令) +4. [IDAW 命令](#4-idaw-命令) +5. [With-File 工作流](#5-with-file-工作流) +6. [循环工作流](#6-循环工作流) +7. [CLI 命令](#7-cli-命令) +8. [记忆命令](#8-记忆命令) +9. [团队技能](#9-团队技能) +10. [工作流技能](#10-工作流技能) +11. [实用技能](#11-实用技能) +12. [Codex 能力](#12-codex-能力) + +--- + +## 快速参考表 + +### 命令快速参考 + +| 类别 | 命令 | 描述 | 参数 | +|----------|---------|-------------|-----------| +| **编排器** | `/ccw` | 主工作流编排器 | `"任务描述"` | +| **编排器** | `/ccw-coordinator` | 命令编排工具 | `[任务描述]` | +| **会话** | `/workflow:session:start` | 启动工作流会话 | `[--type] [--auto|--new] [任务]` | +| **会话** | `/workflow:session:resume` | 恢复暂停的会话 | - | +| **会话** | `/workflow:session:complete` | 完成活动会话 | `[-y] [--detailed]` | +| **会话** | `/workflow:session:list` | 列出所有会话 | - | +| **会话** | `/workflow:session:sync` | 同步会话到规格 | `[-y] ["完成内容"]` | +| **会话** | `/workflow:session:solidify` | 固化学习成果 | `[--type] [--category] "规则"` | +| **Issue** | `/issue:new` | 创建结构化 Issue | `<url|文本> [--priority 1-5]` | +| **Issue** | `/issue:discover` | 发现潜在问题 | `<路径> [--perspectives=...]` | +| **Issue** | `/issue:plan` | 规划 Issue 解决 | `--all-pending <ids>` | +| **Issue** | `/issue:queue` | 形成执行队列 | `[--queues <n>] [--issue <id>]` | +| **Issue** | `/issue:execute` | 执行队列 | `--queue <id> [--worktree]` | +| **IDAW** | `/idaw:run` | IDAW 编排器 | `[--task <ids>] [--dry-run]` | +| **IDAW** | `/idaw:add` | 添加任务到队列 | - | +| **IDAW** | `/idaw:resume` | 恢复 IDAW 会话 | - | +| **IDAW** | `/idaw:status` | 显示队列状态 | - | +| **With-File** | `/workflow:brainstorm-with-file` | 交互式头脑风暴 | `[-c] [-m creative|structured] "主题"` | +| **With-File** | `/workflow:analyze-with-file` | 协作分析 | `[-c] "主题"` | +| **With-File** | `/workflow:debug-with-file` | 假设驱动调试 | `"Bug描述"` | +| **With-File** | `/workflow:collaborative-plan-with-file` | 多代理规划 | - | +| **With-File** | `/workflow:roadmap-with-file` | 战略路线图 | - | +| **Cycle** | `/workflow:integration-test-cycle` | 集成测试循环 | - | +| **Cycle** | `/workflow:refactor-cycle` | 重构循环 | - | +| **CLI** | `/cli:codex-review` | Codex 代码审查 | `[--uncommitted|--base|--commit]` | +| **CLI** | `/cli:cli-init` | 初始化 CLI 配置 | - | +| **Memory** | `/memory:prepare` | 准备记忆上下文 | - | +| **Memory** | `/memory:style-skill-memory` | 样式/技能记忆 | - | + +### 技能快速参考 + +| 类别 | 技能 | 内部流水线 | 用例 | +|----------|-------|-------------------|----------| +| **Workflow** | workflow-lite-planex | explore → plan → confirm → execute | 快速功能、Bug 修复 | +| **Workflow** | workflow-plan | session → context → convention → gen → verify/replan | 复杂功能规划 | +| **Workflow** | workflow-execute | session discovery → task processing → commit | 执行预生成的计划 | +| **Workflow** | workflow-tdd-plan | 6阶段 TDD plan → verify | TDD 开发 | +| **Workflow** | workflow-test-fix | session → context → analysis → gen → cycle | 测试生成与修复 | +| **Workflow** | workflow-multi-cli-plan | ACE context → CLI discussion → plan → execute | 多视角规划 | +| **Workflow** | workflow-skill-designer | - | 创建新技能 | +| **Team** | team-lifecycle-v5 | spec pipeline → impl pipeline | 完整生命周期 | +| **Team** | team-planex | planner wave → executor wave | Issue 批量执行 | +| **Team** | team-arch-opt | architecture analysis → optimization | 架构优化 | +| **Utility** | brainstorm | framework → parallel analysis → synthesis | 多视角创意 | +| **Utility** | review-cycle | discovery → analysis → aggregation → deep-dive | 代码审查 | +| **Utility** | spec-generator | study → brief → PRD → architecture → epics | 规格文档包 | + +--- + +## 1. 主编排器命令 + +### /ccw + +**描述**: 主工作流编排器 - 分析意图、选择工作流、在主进程中执行命令链 + +**参数**: `"任务描述"` + +**类别**: orchestrator + +**5阶段工作流**: +1. Phase 1: 分析意图 (检测任务类型、复杂度、清晰度) +2. Phase 1.5: 需求澄清 (如果清晰度 < 2) +3. Phase 2: 选择工作流并构建命令链 +4. Phase 3: 用户确认 +5. Phase 4: 设置 TODO 跟踪和状态文件 +6. Phase 5: 执行命令链 + +**技能映射**: + +| 技能 | 内部流水线 | +|-------|-------------------| +| workflow-lite-planex | explore → plan → confirm → execute | +| workflow-plan | session → context → convention → gen → verify/replan | +| workflow-execute | session discovery → task processing → commit | +| workflow-tdd-plan | 6阶段 TDD plan → verify | +| workflow-test-fix | session → context → analysis → gen → cycle | +| workflow-multi-cli-plan | ACE context → CLI discussion → plan → execute | +| review-cycle | session/module review → fix orchestration | +| brainstorm | auto/single-role → artifacts → analysis → synthesis | +| spec-generator | product-brief → PRD → architecture → epics | + +**自动模式**: `-y` 或 `--yes` 标志跳过确认，传播到所有技能 + +--- + +### /ccw-coordinator + +**描述**: 命令编排工具 - 分析需求、推荐链、带状态持久化顺序执行 + +**参数**: `[任务描述]` + +**类别**: orchestrator + +**3阶段工作流**: +1. Phase 1: 分析需求 +2. Phase 2: 发现命令并推荐链 +3. Phase 3: 顺序执行命令链 + +**最小执行单元**: + +| 单元 | 命令 | 用途 | +|------|----------|---------| +| 快速实现 | lite-plan (plan → execute) | 轻量级规划和执行 | +| 多CLI规划 | multi-cli-plan | 多视角规划 | +| Bug修复 | lite-plan --bugfix | Bug诊断和修复 | +| 完整规划+执行 | plan → execute | 详细规划 | +| 验证规划+执行 | plan → plan-verify → execute | 带验证的规划 | +| TDD规划+执行 | tdd-plan → execute | TDD工作流 | +| Issue工作流 | discover → plan → queue → execute | 完整Issue生命周期 | + +--- + +### /flow-create + +**描述**: 元技能/flow-coordinator 的流程模板生成器 + +**参数**: `[模板名称] [--output <路径>]` + +**类别**: utility + +**执行流程**: +1. Phase 1: 模板设计 (名称 + 描述 + 级别) +2. Phase 2: 步骤定义 (命令类别 → 具体命令 → 执行单元 → 模式) +3. Phase 3: 生成 JSON + +--- + +## 2. 工作流会话命令 + +### /workflow:session:start + +**描述**: 发现现有会话或启动新工作流会话，具有智能会话管理和冲突检测 + +**参数**: `[--type <workflow|review|tdd|test|docs>] [--auto|--new] [任务描述]` + +**类别**: session-management + +**会话类型**: + +| 类型 | 描述 | 默认对应技能 | +|------|-------------|-------------| +| workflow | 标准实现 | workflow-plan skill | +| review | 代码审查会话 | review-cycle skill | +| tdd | TDD开发 | workflow-tdd-plan skill | +| test | 测试生成/修复 | workflow-test-fix skill | +| docs | 文档会话 | memory-manage skill | + +**模式**: +- **发现模式** (默认): 列出活动会话，提示用户 +- **自动模式** (`--auto`): 智能会话选择 +- **强制新建模式** (`--new`): 创建新会话 + +--- + +### /workflow:session:resume + +**描述**: 恢复最近暂停的工作流会话，自动发现会话并更新状态 + +**类别**: session-management + +--- + +### /workflow:session:complete + +**描述**: 标记活动工作流会话为完成，归档并记录经验教训，更新清单，移除活动标志 + +**参数**: `[-y|--yes] [--detailed]` + +**类别**: session-management + +**执行阶段**: +1. 查找会话 +2. 生成清单条目 +3. 原子提交 (移至归档) +4. 自动同步项目状态 + +--- + +### /workflow:session:list + +**描述**: 列出所有工作流会话，支持状态过滤，显示会话元数据和进度信息 + +**类别**: session-management + +--- + +### /workflow:session:sync + +**描述**: 快速同步会话工作到 specs/*.md 和 project-tech + +**参数**: `[-y|--yes] ["完成内容"]` + +**类别**: session-management + +**流程**: +1. 收集上下文 (git diff, session, summary) +2. 提取更新 (guidelines, tech) +3. 预览并确认 +4. 写入两个文件 + +--- + +### /workflow:session:solidify + +**描述**: 将会话学习成果和用户定义约束固化为永久项目指南，或压缩近期记忆 + +**参数**: `[-y|--yes] [--type <convention|constraint|learning|compress>] [--category <类别>] [--limit <N>] "规则或见解"` + +**类别**: session-management + +**类型类别**: + +| 类型 | 子类别 | +|------|---------------| +| convention | coding_style, naming_patterns, file_structure, documentation | +| constraint | architecture, tech_stack, performance, security | +| learning | architecture, performance, security, testing, process, other | +| compress | (操作核心记忆) | + +--- + +## 3. Issue 工作流命令 + +### /issue:new + +**描述**: 从 GitHub URL 或文本描述创建结构化 Issue + +**参数**: `[-y|--yes] <github-url | 文本描述> [--priority 1-5]` + +**类别**: issue + +**执行流程**: +1. 输入分析与清晰度检测 +2. 数据提取 (GitHub 或文本) +3. 轻量级上下文提示 (ACE 用于中等清晰度) +4. 条件性澄清 +5. GitHub 发布决策 +6. 创建 Issue + +--- + +### /issue:discover + +**描述**: 使用 CLI explore 从多视角发现潜在问题。支持 Exa 外部研究用于安全和最佳实践视角。 + +**参数**: `[-y|--yes] <路径模式> [--perspectives=bug,ux,...] [--external]` + +**类别**: issue + +**可用视角**: + +| 视角 | 关注点 | 类别 | +|-------------|-------|------------| +| bug | 潜在Bug | edge-case, null-check, resource-leak, race-condition | +| ux | 用户体验 | error-message, loading-state, feedback, accessibility | +| test | 测试覆盖 | missing-test, edge-case-test, integration-gap | +| quality | 代码质量 | complexity, duplication, naming, documentation | +| security | 安全问题 | injection, auth, encryption, input-validation | +| performance | 性能 | n-plus-one, memory-usage, caching, algorithm | +| maintainability | 可维护性 | coupling, cohesion, tech-debt, extensibility | +| best-practices | 最佳实践 | convention, pattern, framework-usage, anti-pattern | + +--- + +### /issue:plan + +**描述**: 使用 issue-plan-agent 批量规划 Issue 解决方案 (探索 + 计划闭环) + +**参数**: `[-y|--yes] --all-pending <issue-id>[,<issue-id>,...] [--batch-size 3]` + +**类别**: issue + +**执行过程**: +1. Issue 加载与智能分组 +2. 统一探索 + 规划 (issue-plan-agent) +3. 解决方案注册与绑定 +4. 汇总 + +--- + +### /issue:queue + +**描述**: 使用 issue-queue-agent 从绑定解决方案形成执行队列 (解决方案级别) + +**参数**: `[-y|--yes] [--queues <n>] [--issue <id>]` + +**类别**: issue + +**核心能力**: +- 代理驱动的排序逻辑 +- 解决方案级别粒度 +- 冲突澄清 +- 并行/顺序组分配 + +--- + +### /issue:execute + +**描述**: 使用基于 DAG 的并行编排执行队列 (每个解决方案一次提交) + +**参数**: `[-y|--yes] --queue <queue-id> [--worktree [<现有路径>]]` + +**类别**: issue + +**执行流程**: +1. 验证队列 ID (必需) +2. 获取 DAG 和用户选择 +3. 分发并行批次 (DAG 驱动) +4. 下一批次 (重复) +5. Worktree 完成 + +**推荐执行器**: Codex (2小时超时, 完整写入权限) + +--- + +### /issue:from-brainstorm + +**描述**: 将头脑风暴会话想法转换为带可执行解决方案的 Issue + +**参数**: `SESSION="<session-id>" [--idea=<index>] [--auto] [-y|--yes]` + +**类别**: issue + +**执行流程**: +1. 会话加载 +2. 想法选择 +3. 丰富 Issue 上下文 +4. 创建 Issue +5. 生成解决方案任务 +6. 绑定解决方案 + +--- + +## 4. IDAW 命令 + +### /idaw:run + +**描述**: IDAW 编排器 - 带 Git 检查点顺序执行任务技能链 + +**参数**: `[-y|--yes] [--task <id>[,<id>,...]] [--dry-run]` + +**类别**: idaw + +**技能链映射**: + +| 任务类型 | 技能链 | +|-----------|-------------| +| bugfix | workflow-lite-planex → workflow-test-fix | +| bugfix-hotfix | workflow-lite-planex | +| feature | workflow-lite-planex → workflow-test-fix | +| feature-complex | workflow-plan → workflow-execute → workflow-test-fix | +| refactor | workflow:refactor-cycle | +| tdd | workflow-tdd-plan → workflow-execute | +| test | workflow-test-fix | +| test-fix | workflow-test-fix | +| review | review-cycle | +| docs | workflow-lite-planex | + +**6阶段执行**: +1. 加载任务 +2. 会话设置 +3. 启动协议 +4. 主循环 (顺序，一次一个任务) +5. 检查点 (每个任务) +6. 报告 + +--- + +### /idaw:add + +**描述**: 添加任务到 IDAW 队列，自动推断任务类型和技能链 + +**类别**: idaw + +--- + +### /idaw:resume + +**描述**: 带崩溃恢复的 IDAW 会话恢复 + +**类别**: idaw + +--- + +### /idaw:status + +**描述**: 显示 IDAW 队列状态 + +**类别**: idaw + +--- + +### /idaw:run-coordinate + +**描述**: 带并行任务协调的多代理 IDAW 执行 + +**类别**: idaw + +--- + +## 5. With-File 工作流 + +### /workflow:brainstorm-with-file + +**描述**: 交互式头脑风暴，具有多 CLI 协作、想法扩展和文档化思维演进 + +**参数**: `[-y|--yes] [-c|--continue] [-m|--mode creative|structured] "想法或主题"` + +**类别**: with-file + +**输出目录**: `.workflow/.brainstorm/{session-id}/` + +**4阶段工作流**: +1. Phase 1: 种子理解 (解析主题, 选择角色, 扩展向量) +2. Phase 2: 发散探索 (cli-explore-agent + 多 CLI 视角) +3. Phase 3: 交互式精炼 (多轮) +4. Phase 4: 收敛与结晶 + +**输出产物**: +- `brainstorm.md` - 完整思维演进时间线 +- `exploration-codebase.json` - 代码库上下文 +- `perspectives.json` - 多 CLI 发现 +- `synthesis.json` - 最终综合 + +--- + +### /workflow:analyze-with-file + +**描述**: 交互式协作分析，具有文档化讨论、CLI 辅助探索和演进理解 + +**参数**: `[-y|--yes] [-c|--continue] "主题或问题"` + +**类别**: with-file + +**输出目录**: `.workflow/.analysis/{session-id}/` + +**4阶段工作流**: +1. Phase 1: 主题理解 +2. Phase 2: CLI 探索 (cli-explore-agent + 视角) +3. Phase 3: 交互式讨论 (多轮) +4. Phase 4: 综合与结论 + +**决策记录协议**: 必须记录方向选择、关键发现、假设变更、用户反馈 + +--- + +### /workflow:debug-with-file + +**描述**: 交互式假设驱动调试，具有文档化探索、理解演进和 Gemini 辅助纠正 + +**参数**: `[-y|--yes] "Bug 描述或错误信息"` + +**类别**: with-file + +**输出目录**: `.workflow/.debug/{session-id}/` + +**核心工作流**: 探索 → 文档 → 日志 → 分析 → 纠正理解 → 修复 → 验证 + +**输出产物**: +- `debug.log` - NDJSON 执行证据 +- `understanding.md` - 探索时间线 + 整合理解 +- `hypotheses.json` - 带结论的假设历史 + +--- + +### /workflow:collaborative-plan-with-file + +**描述**: 带 Plan Note 共享文档的多代理协作规划 + +**类别**: with-file + +--- + +### /workflow:roadmap-with-file + +**描述**: 战略需求路线图 → Issue 创建 → execution-plan.json + +**类别**: with-file + +--- + +### /workflow:unified-execute-with-file + +**描述**: 通用执行引擎 - 消费来自 collaborative-plan、roadmap、brainstorm 的计划输出 + +**类别**: with-file + +--- + +## 6. 循环工作流 + +### /workflow:integration-test-cycle + +**描述**: 带反思的自迭代集成测试 - 探索 → 测试开发 → 测试修复循环 → 反思 + +**类别**: cycle + +**输出目录**: `.workflow/.test-cycle/` + +--- + +### /workflow:refactor-cycle + +**描述**: 技术债务发现 → 优先级排序 → 执行 → 验证 + +**类别**: cycle + +**输出目录**: `.workflow/.refactor-cycle/` + +--- + +## 7. CLI 命令 + +### /cli:codex-review + +**描述**: 使用 Codex CLI 通过 ccw 端点进行交互式代码审查，支持可配置审查目标、模型和自定义指令 + +**参数**: `[--uncommitted|--base <分支>|--commit <sha>] [--model <模型>] [--title <标题>] [提示]` + +**类别**: cli + +**审查目标**: + +| 目标 | 标志 | 描述 | +|--------|------|-------------| +| 未提交更改 | `--uncommitted` | 审查已暂存、未暂存和未跟踪的更改 | +| 与分支比较 | `--base <BRANCH>` | 审查与基础分支的差异 | +| 特定提交 | `--commit <SHA>` | 审查提交引入的更改 | + +**关注领域**: 一般审查、安全重点、性能重点、代码质量 + +**重要**: 目标标志和提示互斥 + +--- + +### /cli:cli-init + +**描述**: 初始化 ccw 端点的 CLI 配置 + +**类别**: cli + +--- + +## 8. 记忆命令 + +### /memory:prepare + +**描述**: 为会话准备记忆上下文 + +**类别**: memory + +--- + +### /memory:style-skill-memory + +**描述**: 样式和技能记忆管理 + +**类别**: memory + +--- + +## 9. 团队技能 + +### 团队生命周期技能 + +| 技能 | 描述 | +|-------|-------------| +| team-lifecycle-v5 | 带角色规格驱动工作代理的完整团队生命周期 | +| team-planex | 规划器 + 执行器波流水线 (用于大批量 Issue 或路线图输出) | +| team-coordinate-v2 | 团队协调和编排 | +| team-executor-v2 | 带工作代理的任务执行 | +| team-arch-opt | 架构优化技能 | + +### 团队领域技能 + +| 技能 | 描述 | +|-------|-------------| +| team-brainstorm | 多视角头脑风暴 | +| team-review | 代码审查工作流 | +| team-testing | 测试工作流 | +| team-frontend | 前端开发工作流 | +| team-issue | Issue 管理工作流 | +| team-iterdev | 迭代开发工作流 | +| team-perf-opt | 性能优化工作流 | +| team-quality-assurance | QA 工作流 | +| team-roadmap-dev | 路线图开发工作流 | +| team-tech-debt | 技术债务管理 | +| team-uidesign | UI 设计工作流 | +| team-ultra-analyze | 深度分析工作流 | + +--- + +## 10. 工作流技能 + +| 技能 | 内部流水线 | 描述 | +|-------|-------------------|-------------| +| workflow-lite-planex | explore → plan → confirm → execute | 轻量级合并模式规划 | +| workflow-plan | session → context → convention → gen → verify/replan | 带架构设计的完整规划 | +| workflow-execute | session discovery → task processing → commit | 从规划会话执行 | +| workflow-tdd-plan | 6阶段 TDD plan → verify | TDD 工作流规划 | +| workflow-test-fix | session → context → analysis → gen → cycle | 测试生成与修复循环 | +| workflow-multi-cli-plan | ACE context → CLI discussion → plan → execute | 多 CLI 协作规划 | +| workflow-skill-designer | - | 工作流技能设计和生成 | + +--- + +## 11. 实用技能 + +| 技能 | 描述 | +|-------|-------------| +| brainstorm | 统一头脑风暴技能 (自动并行 + 角色分析) | +| review-code | 代码审查技能 | +| review-cycle | 会话/模块审查 → 修复编排 | +| spec-generator | 产品简介 → PRD → 架构 → Epics | +| skill-generator | 生成新技能 | +| skill-tuning | 调优现有技能 | +| command-generator | 生成新命令 | +| memory-capture | 捕获会话记忆 | +| memory-manage | 管理存储的记忆 | +| issue-manage | Issue 管理工具 | +| ccw-help | CCW 帮助和文档 | + +--- + +## 12. Codex 能力 + +### Codex 审查模式 + +**命令**: `ccw cli --tool codex --mode review [选项]` + +| 选项 | 描述 | +|--------|-------------| +| `[提示]` | 自定义审查指令 (位置参数, 无目标标志) | +| `-c model=<模型>` | 通过配置覆盖模型 | +| `--uncommitted` | 审查已暂存、未暂存和未跟踪的更改 | +| `--base <BRANCH>` | 审查与基础分支的差异 | +| `--commit <SHA>` | 审查提交引入的更改 | +| `--title <TITLE>` | 可选的提交标题用于审查摘要 | + +**可用模型**: +- 默认: gpt-5.2 +- o3: OpenAI o3 推理模型 +- gpt-4.1: GPT-4.1 模型 +- o4-mini: OpenAI o4-mini (更快) + +**约束**: +- 目标标志 (`--uncommitted`, `--base`, `--commit`) **不能**与位置参数 `[提示]` 一起使用 +- 自定义提示仅支持不带目标标志的情况 (默认审查未提交更改) + +### Codex 集成点 + +| 集成点 | 描述 | +|-------------------|-------------| +| CLI 端点 | `ccw cli --tool codex --mode <analysis\|write\|review>` | +| 多 CLI 规划 | workflow-multi-cli-plan 中的务实视角 | +| 代码审查 | `/cli:codex-review` 命令 | +| Issue 执行 | `/issue:execute` 的推荐执行器 | +| 魔鬼代言人 | 头脑风暴精炼中的挑战模式 | + +### Codex 模式汇总 + +| 模式 | 权限 | 用例 | +|------|------------|----------| +| analysis | 只读 | 代码分析、架构审查 | +| write | 完整访问 | 实现、文件修改 | +| review | 只读输出 | Git 感知的代码审查 | + +--- + +## 统计汇总 + +| 类别 | 数量 | +|----------|-------| +| 主编排器命令 | 3 | +| 工作流会话命令 | 6 | +| Issue 工作流命令 | 6 | +| IDAW 命令 | 5 | +| With-File 工作流 | 6 | +| 循环工作流 | 2 | +| CLI 命令 | 2 | +| 记忆命令 | 2 | +| 团队技能 | 17 | +| 工作流技能 | 7 | +| 实用技能 | 11 | +| **命令总数** | 32 | +| **技能总数** | 35 | + +--- + +## 调用模式 + +### 斜杠命令调用 + +``` +/<命名空间>:<命令> [参数] [标志] +``` + +示例: +- `/ccw "添加用户认证"` +- `/workflow:session:start --auto "实现功能"` +- `/issue:new https://github.com/org/repo/issues/123` +- `/cli:codex-review --base main` + +### 技能调用 (从代码) + +```javascript +Skill({ skill: "workflow-lite-planex", args: '"任务描述"' }) +Skill({ skill: "brainstorm", args: '"主题或问题"' }) +Skill({ skill: "review-cycle", args: '--session="WFS-xxx"' }) +``` + +### CLI 工具调用 + +```bash +ccw cli -p "PURPOSE: ... TASK: ... MODE: analysis|write" --tool <工具> --mode <模式> +``` + +--- + +## 相关文档 + +- [工作流对比表](../workflows/comparison-table.md) - 工作流选择指南 +- [工作流概览](../workflows/index.md) - 4级工作流系统 +- [Claude 工作流技能](../skills/claude-workflow.md) - 详细技能文档 diff --git a/docs/zh/workflows/comparison-table.md b/docs/zh/workflows/comparison-table.md new file mode 100644 index 00000000..980cfc49 --- /dev/null +++ b/docs/zh/workflows/comparison-table.md @@ -0,0 +1,175 @@ +# 工作流对比表 + +> **CCW 工作流完整参考** - 按调用方式、流水线、用例、复杂度和自动链式行为对比所有工作流。 + +## 快速参考 + +| 工作流 | 最佳用途 | 级别 | 自包含 | +|----------|----------|-------|----------------| +| workflow-lite-planex | 快速任务、Bug 修复 | 2 (轻量级) | 是 | +| workflow-plan → workflow-execute | 复杂功能 | 3-4 (标准) | 否 (需要 execute) | +| workflow-tdd-plan → workflow-execute | TDD 开发 | 3 (标准) | 否 (需要 execute) | +| workflow-test-fix | 测试生成/修复 | 3 (标准) | 是 | +| workflow-multi-cli-plan | 多视角规划 | 3 (标准) | 是 | +| brainstorm-with-file | 创意构思、探索 | 4 (完整) | 否 (链式到 plan) | +| analyze-with-file | 深度分析 | 3 (标准) | 否 (链式到 lite-plan) | +| debug-with-file | 假设驱动调试 | 3 (标准) | 是 | +| collaborative-plan-with-file | 多代理规划 | 3 (标准) | 否 (链式到 execute) | +| roadmap-with-file | 战略路线图 | 4 (战略) | 否 (链式到 team-planex) | +| integration-test-cycle | 集成测试 | 3 (标准) | 是 | +| refactor-cycle | 技术债务重构 | 3 (标准) | 是 | +| review-cycle | 代码审查 | 3 (标准) | 是 | +| spec-generator | 规格文档包 | 4 (完整) | 否 (链式到 plan) | +| team-planex | Issue 批量执行 | Team | 是 | +| team-lifecycle-v5 | 完整生命周期 | Team | 是 | +| issue pipeline | Issue 管理 | 2.5 (桥接) | 是 | + +--- + +## 完整对比表 + +| 工作流 | 调用方式 | 流水线 | 用例 | 级别 | 自包含 | 自动链式到 | +|----------|------------|----------|----------|-------|----------------|----------------| +| **Plan+Execute 工作流** | +| workflow-lite-planex | `/ccw "任务"` (低/中复杂度自动选择) | explore → plan → confirm → execute | 快速功能、Bug 修复、简单任务 | 2 (轻量级) | 是 | workflow-test-fix | +| workflow-plan | `/ccw "复杂功能"` (高复杂度) | session → context → convention → gen → verify/replan | 复杂功能规划、正式验证 | 3-4 (标准) | 否 | workflow-execute | +| workflow-execute | `/workflow-execute` (plan 之后) | session discovery → task processing → commit | 执行预生成的计划 | 3 (标准) | 是 | review-cycle (可选) | +| workflow-multi-cli-plan | `/ccw "multi-cli plan: ..."` | ACE context → CLI discussion → plan → execute | 多视角规划 | 3 (标准) | 是 | (内部交接) | +| **TDD 工作流** | +| workflow-tdd-plan | `/ccw "Implement with TDD"` | 6阶段 TDD plan → verify | 测试驱动开发规划 | 3 (标准) | 否 | workflow-execute | +| workflow-test-fix | `/ccw "generate tests"` 或自动链式 | session → context → analysis → gen → cycle | 测试生成、覆盖率提升 | 3 (标准) | 是 | (独立) | +| **头脑风暴工作流** | +| brainstorm | `/brainstorm "主题"` | mode detect → framework → parallel analysis → synthesis | 多视角创意构思 | 4 (完整) | 是 (仅构思) | workflow-plan | +| brainstorm-with-file | `/ccw "brainstorm: ..."` | brainstorm + documented artifacts | 带会话文档的创意构思 | 4 (完整) | 否 | workflow-plan → execute | +| collaborative-plan-with-file | `/ccw "collaborative plan: ..."` | understanding → parallel agents → plan-note.md | 多代理协作规划 | 3 (标准) | 否 | unified-execute-with-file | +| **分析工作流** | +| analyze-with-file | `/ccw "analyze: ..."` | multi-CLI analysis → discussion.md | 深度理解、架构探索 | 3 (标准) | 否 | workflow-lite-planex | +| debug-with-file | `/ccw "debug: ..."` | hypothesis-driven iteration → debug.log | 系统化调试 | 3 (标准) | 是 | (独立) | +| **审查工作流** | +| review-cycle | `/ccw "review code"` | discovery → analysis → aggregation → deep-dive → completion | 代码审查、质量门禁 | 3 (标准) | 是 | fix mode (如有发现) | +| **规格工作流** | +| spec-generator | `/ccw "specification: ..."` | study → discovery → brief → PRD → architecture → epics | 完整规格文档包 | 4 (完整) | 是 (仅文档) | workflow-plan / team-planex | +| **团队工作流** | +| team-planex | `/ccw "team planex: ..."` | coordinator → planner wave → executor wave | 基于 Issue 的并行执行 | Team | 是 | (完整流水线) | +| team-lifecycle-v5 | `/ccw "team lifecycle: ..."` | spec pipeline → impl pipeline | 从规格到验证的完整生命周期 | Team | 是 | (完整生命周期) | +| team-arch-opt | (架构优化) | architecture analysis → optimization | 架构优化 | Team | 是 | (完整) | +| **循环工作流** | +| integration-test-cycle | `/ccw "integration test: ..."` | explore → test dev → test-fix cycle → reflection | 带迭代的集成测试 | 3 (标准) | 是 | (自迭代) | +| refactor-cycle | `/ccw "refactor: ..."` | discover → prioritize → execute → validate | 技术债务发现与重构 | 3 (标准) | 是 | (自迭代) | +| **Issue 工作流** | +| issue pipeline | `/ccw "use issue workflow"` | discover → plan → queue → execute | 结构化 Issue 管理 | 2.5 (桥接) | 是 | (完整流水线) | +| **路线图工作流** | +| roadmap-with-file | `/ccw "roadmap: ..."` | strategic roadmap → issue creation → execution-plan | 战略需求拆解 | 4 (战略) | 否 | team-planex | + +--- + +## 工作流级别分类 + +| 级别 | 工作流 | 特点 | +|-------|-----------|-----------------| +| **2 (轻量级)** | workflow-lite-planex, docs | 快速执行、最少阶段 | +| **2.5 (桥接)** | issue pipeline, rapid-to-issue | 桥接到 Issue 工作流 | +| **3 (标准)** | workflow-plan, workflow-execute, workflow-tdd-plan, workflow-test-fix, review-cycle, debug-with-file, analyze-with-file, workflow-multi-cli-plan | 完整规划/执行、多阶段 | +| **4 (完整)** | brainstorm, spec-generator, brainstorm-with-file, roadmap-with-file | 完整探索、规格化 | +| **Team** | team-planex, team-lifecycle-v5, team-arch-opt | 多代理并行执行 | +| **Cycle** | integration-test-cycle, refactor-cycle | 带反思的自迭代 | + +--- + +## 自动链式参考 + +| 源工作流 | 自动链式到 | 条件 | +|-----------------|---------------|-----------| +| workflow-lite-planex | workflow-test-fix | 默认 (除非 skip-tests) | +| workflow-plan | workflow-execute | 计划确认后 | +| workflow-execute | review-cycle | 用户通过 Phase 6 选择 | +| workflow-tdd-plan | workflow-execute | TDD 计划验证后 | +| brainstorm | workflow-plan | 自动链式到正式规划 | +| brainstorm-with-file | workflow-plan → workflow-execute | 自动 | +| analyze-with-file | workflow-lite-planex | 自动 | +| debug-with-file | (无) | 独立 | +| collaborative-plan-with-file | unified-execute-with-file | 自动 | +| roadmap-with-file | team-planex | 自动 | +| spec-generator | workflow-plan / team-planex | 用户选择 | +| review-cycle | fix mode | 如有发现 | + +--- + +## 自包含 vs 多技能 + +| 工作流 | 自包含 | 说明 | +|----------|---------------|-------| +| workflow-lite-planex | 是 | 完整 plan + execute | +| workflow-plan | 否 | 需要 workflow-execute | +| workflow-execute | 是 | 完整执行 | +| workflow-tdd-plan | 否 | 需要 workflow-execute | +| workflow-test-fix | 是 | 完整生成 + 执行 | +| brainstorm | 是 (构思) | 否 (实现) | +| review-cycle | 是 | 完整审查 + 可选修复 | +| spec-generator | 是 (文档) | 否 (实现) | +| team-planex | 是 | 完整团队流水线 | +| team-lifecycle-v5 | 是 | 完整生命周期 | +| debug-with-file | 是 | 完整调试 | +| integration-test-cycle | 是 | 自迭代 | +| refactor-cycle | 是 | 自迭代 | + +--- + +## 关键词检测参考 + +| 关键词模式 | 检测到的工作流 | +|-----------------|-------------------| +| `urgent`, `critical`, `hotfix`, `紧急`, `严重` | bugfix-hotfix | +| `from scratch`, `greenfield`, `new project`, `从零开始`, `全新` | greenfield | +| `brainstorm`, `ideation`, `multi-perspective`, `头脑风暴`, `创意` | brainstorm | +| `debug`, `hypothesis`, `systematic`, `调试`, `假设` | debug-with-file | +| `analyze`, `understand`, `collaborative analysis`, `分析`, `理解` | analyze-with-file | +| `roadmap`, `路线图`, `规划` | roadmap-with-file | +| `specification`, `PRD`, `产品需求`, `规格` | spec-generator | +| `integration test`, `集成测试`, `端到端` | integration-test-cycle | +| `refactor`, `技术债务`, `重构` | refactor-cycle | +| `team planex`, `wave pipeline`, `团队执行` | team-planex | +| `multi-cli`, `多模型协作`, `多CLI` | workflow-multi-cli-plan | +| `TDD`, `test-driven`, `测试驱动` | workflow-tdd-plan | +| `review`, `code review`, `代码审查` | review-cycle | +| `issue workflow`, `use issue workflow`, `Issue工作流` | issue pipeline | + +--- + +## 工作流选择指南 + +| 任务类型 | 推荐工作流 | 命令链 | +|-----------|---------------------|---------------| +| 快速功能 | `/ccw "..."` | lite-planex → test-fix | +| Bug 修复 | `/ccw "fix ..."` | lite-planex --bugfix → test-fix | +| 复杂功能 | `/ccw "..."` (自动检测) | plan → execute → review → test-fix | +| 探索分析 | `/workflow:analyze-with-file "..."` | analysis → (可选) lite-planex | +| 创意构思 | `/workflow:brainstorm-with-file "..."` | brainstorm → plan → execute | +| 调试 | `/workflow:debug-with-file "..."` | hypothesis-driven debugging | +| Issue 管理 | `/issue:new` → `/issue:plan` → `/issue:queue` → `/issue:execute` | issue workflow | +| 多 Issue 批量 | `/issue:discover` → `/issue:plan --all-pending` | issue batch workflow | +| 代码审查 | `/cli:codex-review --uncommitted` | codex review | +| 团队协调 | `team-lifecycle-v5` 或 `team-planex` | team workflow | +| TDD 开发 | `/ccw "Implement with TDD"` | tdd-plan → execute | +| 集成测试 | `/ccw "integration test: ..."` | integration-test-cycle | +| 技术债务 | `/ccw "refactor: ..."` | refactor-cycle | +| 规格文档 | `/ccw "specification: ..."` | spec-generator → plan | + +--- + +## 从零开始开发路径 + +| 规模 | 流水线 | 复杂度 | +|------|----------|------------| +| 小型 | brainstorm-with-file → workflow-plan → workflow-execute | 3 | +| 中型 | brainstorm-with-file → workflow-plan → workflow-execute → workflow-test-fix | 3 | +| 大型 | brainstorm-with-file → workflow-plan → workflow-execute → review-cycle → workflow-test-fix | 4 | + +--- + +## 相关文档 + +- [4级系统](./4-level.md) - 详细工作流说明 +- [最佳实践](./best-practices.md) - 工作流优化技巧 +- [示例](./examples.md) - 工作流使用示例 +- [团队](./teams.md) - 团队工作流协调