catlog22/Claude-Code-Workflow
1
0
Fork 0
mirror of https://github.com/catlog22/Claude-Code-Workflow.git synced 2026-03-03 15:43:11 +08:00
Code Issues Packages Projects Releases Wiki Activity

Refactor Chinese documentation for team skills and commands

Browse Source 
- Removed outdated table of contents from commands-skills.md
- Updated skills overview in claude-collaboration.md with new skill names and descriptions
- Enhanced clarity and structure of skills details, including roles and pipelines
- Added new team skills: team-arch-opt, team-perf-opt, team-brainstorm, team-frontend, team-uidesign, team-issue, team-iterdev, team-quality-assurance, team-roadmap-dev, team-tech-debt, team-ultra-analyze
- Improved user command section for better usability
- Streamlined best practices for team skills usage
This commit is contained in:
catlog22
2026-03-02 22:49:52 +08:00
parent 99d6438303
commit 1bf9006d65
13 changed files with 1872 additions and 1173 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
ccw/src/core/websocket.ts
View File

@@ -67,13 +67,9 @@ const THROTTLE_CONFIG = new Map<string, { interval: number; category: ThrottleCa
['COORDINATOR_QUESTION_ASKED', { interval: 0, category: 'immediate' }], ['COORDINATOR_QUESTION_ASKED', { interval: 0, category: 'immediate' }],
['COORDINATOR_ANSWER_RECEIVED', { interval: 0, category: 'immediate' }], ['COORDINATOR_ANSWER_RECEIVED', { interval: 0, category: 'immediate' }],
['LOOP_COMPLETED', { interval: 0, category: 'immediate' }], ['LOOP_COMPLETED', { interval: 0, category: 'immediate' }],
['LOOP_COMPLETED' as any, { interval: 0, category: 'immediate' }], ] as const
].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 */ /** Per-message-type throttle tracking */
const throttleState = new Map<string, ThrottleEntry>(); const throttleState = new Map<string, ThrottleEntry>();
@@ -563,36 +559,6 @@ export function parseWebSocketFrame(buffer: Buffer): { opcode: number; payload:
return { opcode, payload: payload.toString('utf8'), frameLength }; return { opcode, payload: payload.toString('utf8'), frameLength };
} }
/**
* 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;
}
/** /**
* Extract session ID from file path * Extract session ID from file path
*/ */

40
ccw/src/tools/cli-history-store.ts
View File

@@ -267,53 +267,37 @@ export class CliHistoryStore {
const hasProjectRoot = tableInfo.some(col => col.name === 'project_root'); const hasProjectRoot = tableInfo.some(col => col.name === 'project_root');
const hasRelativePath = tableInfo.some(col => col.name === 'relative_path'); const hasRelativePath = tableInfo.some(col => col.name === 'relative_path');
// Silent migrations - only log warnings/errors
if (!hasCategory) { if (!hasCategory) {
console.log('[CLI History] Migrating database: adding category column...'); this.db.exec(`ALTER TABLE conversations ADD COLUMN category TEXT DEFAULT 'user';`);
this.db.exec(`
ALTER TABLE conversations ADD COLUMN category TEXT DEFAULT 'user';
`);
// Create index separately to handle potential errors
try { try {
this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_category ON conversations(category);`); this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_category ON conversations(category);`);
} catch (indexErr) { } catch (indexErr) {
console.warn('[CLI History] Category index creation warning:', (indexErr as Error).message); console.warn('[CLI History] Category index creation warning:', (indexErr as Error).message);
} }
console.log('[CLI History] Migration complete: category column added');
} }
if (!hasParentExecutionId) { if (!hasParentExecutionId) {
console.log('[CLI History] Migrating database: adding parent_execution_id column...'); this.db.exec(`ALTER TABLE conversations ADD COLUMN parent_execution_id TEXT;`);
this.db.exec(`
ALTER TABLE conversations ADD COLUMN parent_execution_id TEXT;
`);
try { try {
this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_parent ON conversations(parent_execution_id);`); this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_parent ON conversations(parent_execution_id);`);
} catch (indexErr) { } catch (indexErr) {
console.warn('[CLI History] Parent execution index creation warning:', (indexErr as Error).message); console.warn('[CLI History] Parent execution index creation warning:', (indexErr as Error).message);
} }
console.log('[CLI History] Migration complete: parent_execution_id column added');
} }
// Add hierarchical storage support columns // Add hierarchical storage support columns
if (!hasProjectRoot) { if (!hasProjectRoot) {
console.log('[CLI History] Migrating database: adding project_root column for hierarchical storage...'); this.db.exec(`ALTER TABLE conversations ADD COLUMN project_root TEXT;`);
this.db.exec(`
ALTER TABLE conversations ADD COLUMN project_root TEXT;
`);
try { try {
this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_project_root ON conversations(project_root);`); this.db.exec(`CREATE INDEX IF NOT EXISTS idx_conversations_project_root ON conversations(project_root);`);
} catch (indexErr) { } catch (indexErr) {
console.warn('[CLI History] Project root index creation warning:', (indexErr as Error).message); console.warn('[CLI History] Project root index creation warning:', (indexErr as Error).message);
} }
console.log('[CLI History] Migration complete: project_root column added');
} }
if (!hasRelativePath) { if (!hasRelativePath) {
console.log('[CLI History] Migrating database: adding relative_path column for hierarchical storage...'); this.db.exec(`ALTER TABLE conversations ADD COLUMN relative_path TEXT;`);
this.db.exec(`
ALTER TABLE conversations ADD COLUMN relative_path TEXT;
`);
console.log('[CLI History] Migration complete: relative_path column added');
} }
// Add missing timestamp index for turns table (for time-based queries) // Add missing timestamp index for turns table (for time-based queries)
@@ -324,9 +308,7 @@ export class CliHistoryStore {
`).get(); `).get();
if (!indexExists) { if (!indexExists) {
console.log('[CLI History] Adding missing timestamp index to turns table...');
this.db.exec(`CREATE INDEX IF NOT EXISTS idx_turns_timestamp ON turns(timestamp DESC);`); this.db.exec(`CREATE INDEX IF NOT EXISTS idx_turns_timestamp ON turns(timestamp DESC);`);
console.log('[CLI History] Migration complete: turns timestamp index added');
} }
} catch (indexErr) { } catch (indexErr) {
console.warn('[CLI History] Turns timestamp index creation warning:', (indexErr as Error).message); console.warn('[CLI History] Turns timestamp index creation warning:', (indexErr as Error).message);
@@ -353,15 +335,11 @@ export class CliHistoryStore {
} }
} }
// Batch migration - only output log if there are columns to migrate // Batch migration - silent
if (missingTurnsColumns.length > 0) { if (missingTurnsColumns.length > 0) {
console.log(`[CLI History] Migrating turns table: adding ${missingTurnsColumns.length} columns (${missingTurnsColumns.join(', ')})...`);
for (const col of missingTurnsColumns) { for (const col of missingTurnsColumns) {
this.db.exec(`ALTER TABLE turns ADD COLUMN ${col} ${turnsColumnDefs[col]};`); this.db.exec(`ALTER TABLE turns ADD COLUMN ${col} ${turnsColumnDefs[col]};`);
} }
console.log('[CLI History] Migration complete: turns table updated');
} }
// Add transaction_id column to native_session_mapping table for concurrent session disambiguation // Add transaction_id column to native_session_mapping table for concurrent session disambiguation
@@ -369,16 +347,12 @@ export class CliHistoryStore {
const hasTransactionId = mappingInfo.some(col => col.name === 'transaction_id'); const hasTransactionId = mappingInfo.some(col => col.name === 'transaction_id');
if (!hasTransactionId) { if (!hasTransactionId) {
console.log('[CLI History] Migrating database: adding transaction_id column to native_session_mapping...'); this.db.exec(`ALTER TABLE native_session_mapping ADD COLUMN transaction_id TEXT;`);
this.db.exec(`
ALTER TABLE native_session_mapping ADD COLUMN transaction_id TEXT;
`);
try { try {
this.db.exec(`CREATE INDEX IF NOT EXISTS idx_native_transaction_id ON native_session_mapping(transaction_id);`); this.db.exec(`CREATE INDEX IF NOT EXISTS idx_native_transaction_id ON native_session_mapping(transaction_id);`);
} catch (indexErr) { } catch (indexErr) {
console.warn('[CLI History] Transaction ID index creation warning:', (indexErr as Error).message); console.warn('[CLI History] Transaction ID index creation warning:', (indexErr as Error).message);
} }
console.log('[CLI History] Migration complete: transaction_id column added');
} }
} catch (err) { } catch (err) {
console.error('[CLI History] Migration error:', (err as Error).message); console.error('[CLI History] Migration error:', (err as Error).message);

4
docs/.vitepress/config.ts
View File

@@ -75,8 +75,7 @@ export default withMermaid(defineConfig({
{ text: 'Guide', link: '/guide/ch01-what-is-claude-dms3' }, { text: 'Guide', link: '/guide/ch01-what-is-claude-dms3' },
{ text: 'Commands', link: '/commands/claude/' }, { text: 'Commands', link: '/commands/claude/' },
{ text: 'Skills', link: '/skills/' }, { text: 'Skills', link: '/skills/' },
{ text: 'Features', link: '/features/spec' }, { text: 'Features', link: '/features/spec' }
{ text: 'Components', link: '/components/' }
], ],
// Sidebar - 优化导航结构，增加二级标题和归类 // Sidebar - 优化导航结构，增加二级标题和归类
@@ -423,7 +422,6 @@ export default withMermaid(defineConfig({
{ text: '命令', link: '/zh/commands/claude/' }, { text: '命令', link: '/zh/commands/claude/' },
{ text: '技能', link: '/zh/skills/claude-index' }, { text: '技能', link: '/zh/skills/claude-index' },
{ text: '功能', link: '/zh/features/spec' }, { text: '功能', link: '/zh/features/spec' },
{ text: '组件', link: '/zh/components/' },
{ text: '参考', link: '/zh/reference/commands-skills' } { text: '参考', link: '/zh/reference/commands-skills' }
], ],
sidebar: { sidebar: {

510
docs/.vitepress/theme/styles/custom.css
View File

@@ -1,7 +1,7 @@
/** /**
* VitePress Custom Styles * VitePress Custom Styles
* Overrides and extensions for default VitePress theme * Overrides and extensions for default VitePress theme
* Design System: ui-ux-pro-max — dark-mode-first, developer-focused * Design System: ui-ux-pro-max — flat design, developer-focused, documentation-optimized
*/ */
/* ============================================ /* ============================================
@@ -33,10 +33,14 @@
--vp-custom-block-danger-border: #fecaca; --vp-custom-block-danger-border: #fecaca;
--vp-custom-block-danger-text: #b91c1c; --vp-custom-block-danger-text: #b91c1c;
/* Layout Width Adjustments */ /* Layout Width - Wider content area */
--vp-layout-max-width: 1600px; --vp-layout-max-width: 1600px;
--vp-content-width: 1000px; --vp-content-width: 920px;
--vp-sidebar-width: 272px; --vp-sidebar-width: 280px;
--vp-toc-width: 200px;
/* Prose width for optimal readability */
--vp-prose-width: 820px;
} }
.dark { .dark {
@@ -55,12 +59,9 @@
/* ============================================ /* ============================================
* Layout Container Adjustments * Layout Container Adjustments
* Use CSS variables in :root to control layout widths
* Do not override VitePress layout calculations with !important
* ============================================ */ * ============================================ */
.VPDoc .content-container,
.VPDoc.has-aside .content-container {
max-width: 90% !important;
padding: 0 32px;
}
/* Adjust sidebar and content layout */ /* Adjust sidebar and content layout */
/* NOTE: Removed duplicate padding-left - VitePress already handles sidebar layout */ /* NOTE: Removed duplicate padding-left - VitePress already handles sidebar layout */
@@ -77,6 +78,18 @@
padding: 4px 8px; padding: 4px 8px;
} }
/* ============================================
* Navigation Bar Border
* ============================================ */
.VPNav {
border-bottom: 1px solid var(--vp-c-divider);
}
/* ============================================
* Desktop Layout Adjustments
* Grid-based layout is defined in mobile.css @media (min-width: 1024px)
* ============================================ */
/* ============================================ /* ============================================
* Home Page Override * Home Page Override
* ============================================ */ * ============================================ */
@@ -97,6 +110,12 @@
max-width: 100vw; max-width: 100vw;
} }
/* Home page navbar - reduce title left margin since no sidebar */
.Layout:has(.pro-home) .VPNavBar .content-body,
.Layout:has(.pro-home) .VPNavBar .title {
padding-left: 0 !important;
}
/* Ensure VPFooter doesn't cause overflow */ /* Ensure VPFooter doesn't cause overflow */
.Layout:has(.pro-home) .VPFooter { .Layout:has(.pro-home) .VPFooter {
max-width: 100vw; max-width: 100vw;
@@ -136,54 +155,111 @@
/* ============================================ /* ============================================
* Documentation Content Typography * Documentation Content Typography
* Optimized for readability (65-75 chars per line)
* ============================================ */ * ============================================ */
.vp-doc {
font-family: var(--vp-font-family-base);
line-height: var(--vp-line-height-relaxed);
color: var(--vp-c-text-1);
}
/* Heading hierarchy with clear visual distinction */
.vp-doc h1 { .vp-doc h1 {
font-family: var(--vp-font-family-heading);
font-size: var(--vp-font-size-4xl);
font-weight: 800; font-weight: 800;
letter-spacing: -0.02em; letter-spacing: -0.025em;
margin-bottom: 1.5rem; line-height: var(--vp-line-height-tight);
margin-bottom: var(--vp-spacing-8);
color: var(--vp-c-text-1);
} }
.vp-doc h2 { .vp-doc h2 {
font-family: var(--vp-font-family-heading);
font-size: var(--vp-font-size-2xl);
font-weight: 700; font-weight: 700;
margin-top: 3rem;
padding-top: 2rem;
letter-spacing: -0.01em; letter-spacing: -0.01em;
line-height: var(--vp-line-height-tight);
margin-top: var(--vp-spacing-12);
padding-top: var(--vp-spacing-8);
border-top: 1px solid var(--vp-c-divider); border-top: 1px solid var(--vp-c-divider);
color: var(--vp-c-text-1);
} }
.vp-doc h2:first-of-type { .vp-doc h2:first-of-type {
margin-top: 1.5rem; margin-top: var(--vp-spacing-6);
border-top: none; border-top: none;
} }
.vp-doc h3 { .vp-doc h3 {
font-family: var(--vp-font-family-heading);
font-size: var(--vp-font-size-xl);
font-weight: 600; font-weight: 600;
margin-top: 2.5rem; line-height: var(--vp-line-height-snug);
margin-top: var(--vp-spacing-10);
color: var(--vp-c-text-1);
} }
.vp-doc h4 { .vp-doc h4 {
font-family: var(--vp-font-family-heading);
font-size: var(--vp-font-size-lg);
font-weight: 600; font-weight: 600;
margin-top: 2rem; line-height: var(--vp-line-height-snug);
margin-top: var(--vp-spacing-8);
color: var(--vp-c-text-2);
} }
.vp-doc h5 {
font-size: var(--vp-font-size-base);
font-weight: 600;
line-height: var(--vp-line-height-snug);
margin-top: var(--vp-spacing-6);
color: var(--vp-c-text-2);
}
.vp-doc h6 {
font-size: var(--vp-font-size-sm);
font-weight: 600;
line-height: var(--vp-line-height-snug);
margin-top: var(--vp-spacing-4);
color: var(--vp-c-text-3);
text-transform: uppercase;
letter-spacing: 0.05em;
}
/* Body text with optimal line height */
.vp-doc p { .vp-doc p {
line-height: 1.8; font-size: var(--vp-font-size-base);
margin: 1.25rem 0; line-height: var(--vp-line-height-relaxed);
margin: var(--vp-spacing-5) 0;
max-width: var(--vp-prose-width);
} }
/* Lists with proper spacing */
.vp-doc ul, .vp-doc ul,
.vp-doc ol { .vp-doc ol {
margin: 1.25rem 0; font-size: var(--vp-font-size-base);
padding-left: 1.5rem; line-height: var(--vp-line-height-relaxed);
margin: var(--vp-spacing-5) 0;
padding-left: var(--vp-spacing-6);
max-width: var(--vp-prose-width);
} }
.vp-doc li { .vp-doc li {
line-height: 1.8; line-height: var(--vp-line-height-relaxed);
margin: 0.5rem 0; margin: var(--vp-spacing-2) 0;
} }
.vp-doc li + li { .vp-doc li + li {
margin-top: 0.5rem; margin-top: var(--vp-spacing-2);
}
/* Nested lists */
.vp-doc ul ul,
.vp-doc ol ol,
.vp-doc ul ol,
.vp-doc ol ul {
margin: var(--vp-spacing-2) 0;
} }
/* Better spacing for code blocks in lists */ /* Better spacing for code blocks in lists */
@@ -191,6 +267,31 @@
margin: 0 2px; margin: 0 2px;
} }
/* Blockquotes */
.vp-doc blockquote {
margin: var(--vp-spacing-6) 0;
padding: var(--vp-spacing-4) var(--vp-spacing-6);
border-left: 4px solid var(--vp-c-primary);
background: var(--vp-c-bg-soft);
border-radius: 0 var(--vp-radius-lg) var(--vp-radius-lg) 0;
color: var(--vp-c-text-2);
font-style: italic;
}
.vp-doc blockquote p {
margin: var(--vp-spacing-2) 0;
}
/* Strong and emphasis */
.vp-doc strong {
font-weight: 600;
color: var(--vp-c-text-1);
}
.vp-doc em {
font-style: italic;
}
/* ============================================ /* ============================================
* Command Reference Specific Styles * Command Reference Specific Styles
* ============================================ */ * ============================================ */
@@ -212,12 +313,15 @@
/* ============================================ /* ============================================
* Custom Container Blocks * Custom Container Blocks
* Flat design with left accent border
* ============================================ */ * ============================================ */
.custom-container { .custom-container {
margin: 20px 0; margin: var(--vp-spacing-6) 0;
padding: 16px 20px; padding: var(--vp-spacing-4) var(--vp-spacing-5);
border-radius: 12px; border-radius: var(--vp-radius-xl);
border-left: 4px solid; border-left: 4px solid;
background: var(--vp-c-bg-soft);
box-shadow: var(--vp-shadow-xs);
} }
.custom-container.info { .custom-container.info {
@@ -231,103 +335,285 @@
} }
.dark .custom-container.success { .dark .custom-container.success {
background: rgba(16, 185, 129, 0.1); background: rgba(16, 185, 129, 0.08);
} }
.custom-container.tip { .custom-container.tip {
border-radius: 12px; border-radius: var(--vp-radius-xl);
background: rgba(59, 130, 246, 0.05);
} }
.custom-container.warning { .custom-container.warning {
border-radius: 12px; border-radius: var(--vp-radius-xl);
background: rgba(245, 158, 11, 0.05);
} }
.custom-container.danger { .custom-container.danger {
border-radius: 12px; border-radius: var(--vp-radius-xl);
background: rgba(239, 68, 68, 0.05);
}
/* Custom container titles */
.custom-container .custom-container-title {
font-family: var(--vp-font-family-heading);
font-weight: 600;
font-size: var(--vp-font-size-sm);
text-transform: uppercase;
letter-spacing: 0.05em;
margin-bottom: var(--vp-spacing-2);
}
/* VitePress default custom blocks */
.vp-doc .tip,
.vp-doc .warning,
.vp-doc .danger,
.vp-doc .info {
border-radius: var(--vp-radius-xl);
margin: var(--vp-spacing-6) 0;
padding: var(--vp-spacing-4) var(--vp-spacing-5);
box-shadow: var(--vp-shadow-xs);
}
.vp-doc .tip {
background: rgba(59, 130, 246, 0.05);
border-color: var(--vp-c-primary);
}
.vp-doc .warning {
background: rgba(245, 158, 11, 0.05);
border-color: var(--vp-c-accent);
}
.vp-doc .danger {
background: rgba(239, 68, 68, 0.05);
border-color: #ef4444;
}
.vp-doc .info {
background: var(--vp-c-bg-soft);
border-color: var(--vp-c-primary);
} }
/* ============================================ /* ============================================
* Code Block Improvements * Code Block Improvements
* Clean, flat design with subtle borders
* ============================================ */ * ============================================ */
.vp-code-group { .vp-code-group {
margin: 20px 0; margin: var(--vp-spacing-6) 0;
border-radius: 12px; border-radius: var(--vp-radius-xl);
overflow: hidden; overflow: hidden;
border: 1px solid var(--vp-c-divider);
box-shadow: var(--vp-shadow-sm);
} }
.vp-code-group .tabs { .vp-code-group .tabs {
background: var(--vp-c-bg-soft); background: var(--vp-c-bg-soft);
border-bottom: 1px solid var(--vp-c-divider); border-bottom: 1px solid var(--vp-c-divider);
padding: 0 var(--vp-spacing-2);
} }
.vp-code-group div[class*='language-'] { .vp-code-group div[class*='language-'] {
margin: 0; margin: 0;
border-radius: 0; border-radius: 0;
border: none;
} }
div[class*='language-'] { div[class*='language-'] {
border-radius: 12px; border-radius: var(--vp-radius-xl);
margin: 20px 0; margin: var(--vp-spacing-6) 0;
border: 1px solid var(--vp-c-divider);
background: var(--vp-c-bg-soft) !important;
box-shadow: var(--vp-shadow-sm);
} }
div[class*='language-'] pre { div[class*='language-'] pre {
line-height: 1.65; line-height: var(--vp-line-height-relaxed);
padding: var(--vp-spacing-5) var(--vp-spacing-6);
} }
/* Inline code */ div[class*='language-'] code {
font-family: var(--vp-font-family-mono);
font-size: var(--vp-font-size-sm);
font-weight: 400;
letter-spacing: -0.01em;
}
/* Code block header with language label */
div[class*='language-'] > span.lang {
font-size: var(--vp-font-size-xs);
font-weight: 500;
text-transform: uppercase;
letter-spacing: 0.05em;
color: var(--vp-c-text-3);
padding: var(--vp-spacing-2) var(--vp-spacing-4);
background: var(--vp-c-bg-soft);
border-radius: var(--vp-radius-md);
}
/* Inline code - subtle styling */
.vp-doc :not(pre) > code { .vp-doc :not(pre) > code {
border-radius: 6px; font-family: var(--vp-font-family-mono);
border-radius: var(--vp-radius-md);
padding: 2px 6px; padding: 2px 6px;
font-size: 0.875em; font-size: 0.875em;
font-weight: 500; font-weight: 500;
background: var(--vp-c-bg-soft);
border: 1px solid var(--vp-c-divider);
color: var(--vp-c-primary);
}
/* Copy button styling */
.vp-code-group .vp-copy,
div[class*='language-'] .vp-copy {
border-radius: var(--vp-radius-md);
transition: all var(--vp-transition-color);
}
.vp-code-group .vp-copy:hover,
div[class*='language-'] .vp-copy:hover {
background: var(--vp-c-bg-mute);
} }
/* ============================================ /* ============================================
* Table Styling * Table Styling
* Clean, flat design with subtle borders
* ============================================ */ * ============================================ */
table { .vp-doc table {
border-collapse: collapse; border-collapse: collapse;
width: 100%; width: 100%;
margin: 20px 0; margin: var(--vp-spacing-6) 0;
border-radius: 12px;
overflow: hidden;
} }
table th, .vp-doc table th,
table td { .vp-doc table td {
padding: 12px 16px; padding: var(--vp-spacing-3) var(--vp-spacing-4);
border: 1px solid var(--vp-c-divider); border: 1px solid var(--vp-c-divider);
text-align: left; text-align: left;
font-size: var(--vp-font-size-sm);
line-height: var(--vp-line-height-normal);
} }
table th { .vp-doc table th {
background: var(--vp-c-bg-soft); background: var(--vp-c-bg-soft);
font-family: var(--vp-font-family-heading);
font-weight: 600; font-weight: 600;
font-size: 0.875rem; font-size: var(--vp-font-size-xs);
text-transform: uppercase; text-transform: uppercase;
letter-spacing: 0.03em; letter-spacing: 0.05em;
color: var(--vp-c-text-2); color: var(--vp-c-text-2);
border-bottom-width: 2px;
} }
table tr:hover { .vp-doc table td {
color: var(--vp-c-text-1);
vertical-align: top;
}
.vp-doc table tr:hover {
background: var(--vp-c-bg-soft); background: var(--vp-c-bg-soft);
} }
.vp-doc table tr:hover td {
color: var(--vp-c-text-1);
}
/* Responsive tables */
@media (max-width: 767px) {
.vp-doc table {
display: block;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
}
.vp-doc table th,
.vp-doc table td {
padding: var(--vp-spacing-2) var(--vp-spacing-3);
font-size: var(--vp-font-size-xs);
white-space: nowrap;
}
}
/* ============================================ /* ============================================
* Sidebar Polish * Sidebar Polish
* Clean, organized navigation
* ============================================ */ * ============================================ */
.VPSidebar {
background: var(--vp-c-bg);
border-right: 1px solid var(--vp-c-divider);
}
.VPSidebar .group + .group { .VPSidebar .group + .group {
margin-top: 0.5rem; margin-top: var(--vp-spacing-4);
padding-top: 0.5rem; padding-top: var(--vp-spacing-4);
border-top: 1px solid var(--vp-c-divider); border-top: 1px solid var(--vp-c-divider);
} }
/* Sidebar item styling */
.VPSidebar .VPSidebarItem .text {
font-size: var(--vp-font-size-sm);
line-height: var(--vp-line-height-normal);
transition: color var(--vp-transition-color);
}
.VPSidebar .VPSidebarItem .link:hover .text {
color: var(--vp-c-primary);
}
.VPSidebar .VPSidebarItem.is-active .link .text {
color: var(--vp-c-primary);
font-weight: 600;
}
/* Sidebar group titles */
.VPSidebar .VPSidebarGroup .title {
font-family: var(--vp-font-family-heading);
font-size: var(--vp-font-size-xs);
font-weight: 600;
text-transform: uppercase;
letter-spacing: 0.05em;
color: var(--vp-c-text-3);
padding: var(--vp-spacing-2) var(--vp-spacing-4);
}
/* ============================================
* Navigation Polish
* ============================================ */
.VPNav {
background: var(--vp-c-bg);
border-bottom: 1px solid var(--vp-c-divider);
box-shadow: var(--vp-shadow-xs);
}
.VPNavBar .title {
font-family: var(--vp-font-family-heading);
font-weight: 700;
font-size: var(--vp-font-size-lg);
color: var(--vp-c-text-1);
}
.VPNavBarMenu .VPNavBarMenuLink {
font-family: var(--vp-font-family-heading);
font-weight: 500;
font-size: var(--vp-font-size-sm);
transition: color var(--vp-transition-color);
}
.VPNavBarMenu .VPNavBarMenuLink:hover {
color: var(--vp-c-primary);
}
.VPNavBarMenu .VPNavBarMenuLink.active {
color: var(--vp-c-primary);
font-weight: 600;
}
/* ============================================ /* ============================================
* Scrollbar Styling * Scrollbar Styling
* Subtle, flat design
* ============================================ */ * ============================================ */
::-webkit-scrollbar { ::-webkit-scrollbar {
width: 6px; width: 8px;
height: 6px; height: 8px;
} }
::-webkit-scrollbar-track { ::-webkit-scrollbar-track {
@@ -337,30 +623,148 @@ table tr:hover {
::-webkit-scrollbar-thumb { ::-webkit-scrollbar-thumb {
background: var(--vp-c-surface-2); background: var(--vp-c-surface-2);
border-radius: var(--vp-radius-full); border-radius: var(--vp-radius-full);
border: 2px solid transparent;
background-clip: padding-box;
} }
::-webkit-scrollbar-thumb:hover { ::-webkit-scrollbar-thumb:hover {
background: var(--vp-c-surface-3); background: var(--vp-c-surface-3);
border: 2px solid transparent;
background-clip: padding-box;
}
/* Firefox scrollbar */
* {
scrollbar-width: thin;
scrollbar-color: var(--vp-c-surface-2) transparent;
}
/* ============================================
* TOC (Table of Contents) Polish
* Sticky positioning handled by grid layout in mobile.css
* ============================================ */
.VPDocOutline {
padding-left: 24px;
}
.VPDocOutline .outline-link {
font-family: var(--vp-font-family-base);
font-size: var(--vp-font-size-sm);
line-height: var(--vp-line-height-normal);
padding: var(--vp-spacing-1) var(--vp-spacing-2);
color: var(--vp-c-text-3);
transition: color var(--vp-transition-color);
border-radius: var(--vp-radius-md);
}
.VPDocOutline .outline-link:hover {
color: var(--vp-c-primary);
background: var(--vp-c-bg-soft);
}
.VPDocOutline .outline-link.is-active {
color: var(--vp-c-primary);
font-weight: 500;
background: var(--vp-c-bg-soft);
}
.VPDocOutline .outline-marker {
width: 2px;
background: var(--vp-c-primary);
border-radius: var(--vp-radius-full);
} }
/* ============================================ /* ============================================
* Link Improvements * Link Improvements
* Clean, accessible link styling
* ============================================ */ * ============================================ */
a { a {
text-decoration: none; text-decoration: none;
transition: color 0.2s ease; color: var(--vp-c-primary);
transition: color var(--vp-transition-color);
cursor: pointer;
} }
a:hover { a:hover {
text-decoration: underline; text-decoration: underline;
color: var(--vp-c-primary-600);
}
a:visited {
color: var(--vp-c-primary-700);
}
.dark a:visited {
color: var(--vp-c-primary-300);
}
/* External link indicator */
.vp-doc a[target="_blank"]::after {
content: " ↗";
font-size: 0.75em;
opacity: 0.7;
}
/* ============================================
* Button Improvements
* ============================================ */
.VPButton {
font-family: var(--vp-font-family-heading);
font-weight: 600;
font-size: var(--vp-font-size-sm);
padding: var(--vp-spacing-2-5) var(--vp-spacing-5);
border-radius: var(--vp-radius-lg);
transition: all var(--vp-transition-color);
cursor: pointer;
}
.VPButton.brand {
background: var(--vp-c-primary);
color: white;
border: none;
}
.VPButton.brand:hover {
background: var(--vp-c-primary-600);
transform: translateY(-1px);
box-shadow: var(--vp-shadow-md);
}
.VPButton.alt {
background: var(--vp-c-bg-soft);
color: var(--vp-c-text-1);
border: 1px solid var(--vp-c-divider);
}
.VPButton.alt:hover {
background: var(--vp-c-bg-mute);
border-color: var(--vp-c-primary);
} }
/* ============================================ /* ============================================
* Focus States — Accessibility * Focus States — Accessibility
* Clear visible focus for keyboard navigation
* ============================================ */ * ============================================ */
:focus-visible { :focus-visible {
outline: 2px solid var(--vp-c-primary); outline: 2px solid var(--vp-c-primary);
outline-offset: 2px; outline-offset: 2px;
border-radius: var(--vp-radius-md);
}
/* Skip focus outline for mouse users */
:focus:not(:focus-visible) {
outline: none;
}
/* Better focus for interactive elements */
a:focus-visible,
button:focus-visible,
input:focus-visible,
select:focus-visible,
textarea:focus-visible {
outline: 2px solid var(--vp-c-primary);
outline-offset: 2px;
box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.15);
} }
/* ============================================ /* ============================================

271
docs/.vitepress/theme/styles/mobile.css
View File

@@ -1,5 +1,6 @@
/** /**
* Mobile-Responsive Styles * Mobile-Responsive Styles
* Design System: ui-ux-pro-max — flat design, mobile-first
* Breakpoints: < 480px (xs), < 768px (sm/mobile), 768px-1024px (md/tablet), > 1024px (lg/desktop) * Breakpoints: < 480px (xs), < 768px (sm/mobile), 768px-1024px (md/tablet), > 1024px (lg/desktop)
* WCAG 2.1 AA compliant * WCAG 2.1 AA compliant
* *
@@ -253,15 +254,16 @@
/* Base Mobile Styles (320px+) */ /* Base Mobile Styles (320px+) */
@media (max-width: 767px) { @media (max-width: 767px) {
/* Typography */ /* Typography - smaller base for mobile */
:root { :root {
--vp-font-size-base: 14px; --vp-font-size-base: 14px;
--vp-content-width: 100%; --vp-content-width: 100%;
--vp-prose-width: 100%;
} }
/* Container */ /* Container */
.container { .container {
padding: 0 12px; padding: 0 var(--vp-spacing-3);
} }
/* Navigation - ensure hamburger menu is visible */ /* Navigation - ensure hamburger menu is visible */
@@ -271,10 +273,15 @@
} }
.VPNavBar { .VPNavBar {
padding: 0 12px; padding: 0;
overflow: visible !important; overflow: visible !important;
} }
/* VPNavBar content padding for alignment */
.VPNavBar .content {
padding: 0 var(--vp-spacing-3);
}
/* Navigation bar content wrapper */ /* Navigation bar content wrapper */
.VPNavBar .content { .VPNavBar .content {
overflow: visible !important; overflow: visible !important;
@@ -297,8 +304,8 @@
/* Reduce nav-extensions gap on mobile */ /* Reduce nav-extensions gap on mobile */
.VPNavBar .nav-extensions { .VPNavBar .nav-extensions {
gap: 0.25rem; gap: var(--vp-spacing-1);
padding-left: 0.25rem; padding-left: var(--vp-spacing-1);
overflow: visible !important; overflow: visible !important;
} }
@@ -333,10 +340,10 @@
overflow-y: auto; overflow-y: auto;
background: var(--vp-c-bg); background: var(--vp-c-bg);
border: 1px solid var(--vp-c-divider); border: 1px solid var(--vp-c-divider);
border-radius: 8px; border-radius: var(--vp-radius-lg);
box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15); box-shadow: var(--vp-shadow-lg);
z-index: 100; z-index: 100;
padding: 8px 0; padding: var(--vp-spacing-2) 0;
} }
/* Language switcher dropdown fix */ /* Language switcher dropdown fix */
@@ -354,7 +361,7 @@
min-width: 200px !important; min-width: 200px !important;
max-width: calc(100vw - 24px) !important; max-width: calc(100vw - 24px) !important;
z-index: 1000 !important; z-index: 1000 !important;
box-shadow: 0 8px 24px rgba(0, 0, 0, 0.2) !important; box-shadow: var(--vp-shadow-xl) !important;
} }
/* Sidebar - fix display issues */ /* Sidebar - fix display issues */
@@ -365,12 +372,19 @@
top: 56px !important; top: 56px !important;
height: calc(100vh - 56px) !important; height: calc(100vh - 56px) !important;
max-height: calc(100vh - 56px) !important; max-height: calc(100vh - 56px) !important;
overflow: visible !important; overflow-y: auto !important;
overflow-x: hidden !important;
position: fixed !important; position: fixed !important;
left: 0 !important; left: 0 !important;
z-index: 40 !important; z-index: 40 !important;
background: var(--vp-c-bg) !important; background: var(--vp-c-bg) !important;
transition: transform 0.25s ease !important; transition: transform 0.25s ease !important;
border-right: 1px solid var(--vp-c-divider);
}
/* Add padding to sidebar nav to prevent scrollbar overlap with navbar */
.VPSidebar .VPSidebarNav {
padding-top: var(--vp-spacing-4) !important;
} }
/* Sidebar when open */ /* Sidebar when open */
@@ -386,7 +400,7 @@
/* Sidebar nav container */ /* Sidebar nav container */
.VPSidebar .VPSidebarNav { .VPSidebar .VPSidebarNav {
padding: 12px 0; padding: var(--vp-spacing-3) 0;
height: 100%; height: 100%;
min-height: auto; min-height: auto;
overflow-y: auto; overflow-y: auto;
@@ -395,17 +409,17 @@
/* Sidebar groups */ /* Sidebar groups */
.VPSidebar .VPSidebarGroup { .VPSidebar .VPSidebarGroup {
padding: 8px 16px; padding: var(--vp-spacing-2) var(--vp-spacing-4);
} }
/* Sidebar items */ /* Sidebar items */
.VPSidebar .VPSidebarItem { .VPSidebar .VPSidebarItem {
padding: 6px 0; padding: var(--vp-spacing-1-5) 0;
} }
/* Ensure sidebar links are properly sized */ /* Ensure sidebar links are properly sized */
.VPSidebar .link { .VPSidebar .link {
padding: 8px 12px; padding: var(--vp-spacing-2) var(--vp-spacing-3);
display: block; display: block;
} }
@@ -434,21 +448,21 @@
/* Make sure all sidebar content is visible */ /* Make sure all sidebar content is visible */
.VPSidebar .group { .VPSidebar .group {
margin: 0; margin: 0;
padding: 12px 16px; padding: var(--vp-spacing-3) var(--vp-spacing-4);
} }
.VPSidebar .title { .VPSidebar .title {
font-size: 14px; font-size: var(--vp-font-size-sm);
font-weight: 600; font-weight: 600;
padding: 4px 0; padding: var(--vp-spacing-1) 0;
color: var(--vp-c-text-1); color: var(--vp-c-text-1);
} }
/* Sidebar text styling */ /* Sidebar text styling */
.VPSidebar .text { .VPSidebar .text {
font-size: 14px; font-size: var(--vp-font-size-sm);
line-height: 1.5; line-height: var(--vp-line-height-normal);
padding: 6px 12px; padding: var(--vp-spacing-1-5) var(--vp-spacing-3);
} }
/* Ensure nested items are visible */ /* Ensure nested items are visible */
@@ -467,12 +481,12 @@
/* Content - reduce padding for better space usage */ /* Content - reduce padding for better space usage */
.VPContent { .VPContent {
padding: 12px; padding: var(--vp-spacing-3);
} }
/* Doc content adjustments - reduce padding */ /* Doc content adjustments - reduce padding */
.VPDoc .content-container { .VPDoc .content-container {
padding: 0 12px; padding: 0 var(--vp-spacing-3);
} }
/* Hide outline on mobile */ /* Hide outline on mobile */
@@ -482,27 +496,27 @@
/* Hero Section */ /* Hero Section */
.VPHomeHero { .VPHomeHero {
padding: 40px 12px; padding: var(--vp-spacing-10) var(--vp-spacing-3);
} }
.VPHomeHero h1 { .VPHomeHero h1 {
font-size: 28px; font-size: var(--vp-font-size-2xl);
line-height: 1.2; line-height: var(--vp-line-height-tight);
} }
.VPHomeHero p { .VPHomeHero p {
font-size: 14px; font-size: var(--vp-font-size-sm);
} }
/* Code Blocks - reduce margins */ /* Code Blocks - reduce margins */
div[class*='language-'] { div[class*='language-'] {
margin: 12px -12px; margin: var(--vp-spacing-3) calc(var(--vp-spacing-3) * -1);
border-radius: 0; border-radius: 0;
} }
div[class*='language-'] pre { div[class*='language-'] pre {
padding: 12px; padding: var(--vp-spacing-3);
font-size: 12px; font-size: var(--vp-font-size-xs);
} }
/* Tables - make them scrollable */ /* Tables - make them scrollable */
@@ -514,23 +528,23 @@
} }
table { table {
font-size: 12px; font-size: var(--vp-font-size-xs);
} }
table th, table th,
table td { table td {
padding: 8px 12px; padding: var(--vp-spacing-2) var(--vp-spacing-3);
} }
/* Buttons */ /* Buttons */
.VPButton { .VPButton {
padding: 8px 16px; padding: var(--vp-spacing-2) var(--vp-spacing-4);
font-size: 14px; font-size: var(--vp-font-size-sm);
} }
/* Cards */ /* Cards */
.VPFeature { .VPFeature {
padding: 16px; padding: var(--vp-spacing-4);
} }
/* Touch-friendly tap targets (min 44x44px per WCAG) */ /* Touch-friendly tap targets (min 44x44px per WCAG) */
@@ -550,13 +564,13 @@
/* Theme Switcher */ /* Theme Switcher */
.theme-switcher { .theme-switcher {
padding: 12px; padding: var(--vp-spacing-3);
} }
/* Breadcrumbs */ /* Breadcrumbs */
.breadcrumb { .breadcrumb {
padding: 8px 0; padding: var(--vp-spacing-2) 0;
font-size: 12px; font-size: var(--vp-font-size-xs);
} }
/* Table of Contents - hidden on mobile */ /* Table of Contents - hidden on mobile */
@@ -566,34 +580,34 @@
/* Typography adjustments for mobile */ /* Typography adjustments for mobile */
.vp-doc h1 { .vp-doc h1 {
font-size: 1.75rem; font-size: var(--vp-font-size-2xl);
margin-bottom: 1rem; margin-bottom: var(--vp-spacing-4);
} }
.vp-doc h2 { .vp-doc h2 {
font-size: 1.375rem; font-size: var(--vp-font-size-xl);
margin-top: 2rem; margin-top: var(--vp-spacing-8);
padding-top: 1.5rem; padding-top: var(--vp-spacing-6);
} }
.vp-doc h3 { .vp-doc h3 {
font-size: 1.125rem; font-size: var(--vp-font-size-lg);
margin-top: 1.5rem; margin-top: var(--vp-spacing-6);
} }
.vp-doc p { .vp-doc p {
line-height: 1.7; line-height: var(--vp-line-height-relaxed);
margin: 1rem 0; margin: var(--vp-spacing-4) 0;
} }
.vp-doc ul, .vp-doc ul,
.vp-doc ol { .vp-doc ol {
margin: 1rem 0; margin: var(--vp-spacing-4) 0;
padding-left: 1.25rem; padding-left: var(--vp-spacing-5);
} }
.vp-doc li { .vp-doc li {
margin: 0.375rem 0; margin: var(--vp-spacing-1-5) 0;
} }
} }
@@ -602,39 +616,40 @@
* ============================================ */ * ============================================ */
@media (min-width: 768px) and (max-width: 1023px) { @media (min-width: 768px) and (max-width: 1023px) {
:root { :root {
--vp-content-width: 760px; --vp-content-width: 720px;
--vp-sidebar-width: 240px; --vp-sidebar-width: 240px;
--vp-prose-width: 640px;
} }
.VPContent { .VPContent {
padding: 24px; padding: var(--vp-spacing-6);
} }
.VPDoc .content-container { .VPDoc .content-container {
padding: 0 24px; padding: 0 var(--vp-spacing-6);
max-width: 90% !important; max-width: 98% !important;
} }
.VPHomeHero { .VPHomeHero {
padding: 60px 24px; padding: var(--vp-spacing-16) var(--vp-spacing-6);
} }
.VPHomeHero h1 { .VPHomeHero h1 {
font-size: 36px; font-size: var(--vp-font-size-3xl);
} }
div[class*='language-'] { div[class*='language-'] {
margin: 12px 0; margin: var(--vp-spacing-3) 0;
} }
/* Outline visible but narrower */ /* Outline visible but narrower */
.VPDocOutline { .VPDocOutline {
width: 200px; width: 200px;
padding-left: 16px; padding-left: var(--vp-spacing-4);
} }
.VPDocOutline .outline-link { .VPDocOutline .outline-link {
font-size: 12px; font-size: var(--vp-font-size-xs);
} }
} }
@@ -643,52 +658,122 @@
* ============================================ */ * ============================================ */
@media (min-width: 1024px) { @media (min-width: 1024px) {
:root { :root {
--vp-layout-max-width: 1600px; --vp-layout-max-width: 1440px;
--vp-content-width: 960px; --vp-content-width: 860px;
--vp-sidebar-width: 272px; --vp-sidebar-width: 280px;
--vp-prose-width: 720px;
--vp-toc-width: 220px;
} }
.VPContent { .VPContent {
padding: 32px 48px; padding: var(--vp-spacing-8) var(--vp-spacing-12);
max-width: var(--vp-layout-max-width); /* Remove max-width to allow full viewport width */
} }
.VPDoc .content-container { /* Desktop sidebar - restore fixed positioning but with proper width */
max-width: 90% !important; .VPSidebar {
padding: 0 40px; position: fixed !important;
left: 0 !important;
top: var(--vp-nav-height, 56px) !important;
width: var(--vp-sidebar-width, 280px) !important;
height: calc(100vh - var(--vp-nav-height, 56px)) !important;
padding: 0 !important;
overflow-y: auto !important;
border-right: 1px solid var(--vp-c-divider) !important;
z-index: 10 !important;
} }
/* Outline - sticky on desktop with good width */ /* Desktop sidebar - add padding to inner nav */
.VPDocOutline { .VPSidebar nav.nav {
position: sticky; padding: var(--vp-spacing-4) !important;
top: calc(var(--vp-nav-height) + 24px); height: auto;
width: 256px; }
padding-left: 24px;
max-height: calc(100vh - var(--vp-nav-height) - 48px); /* Ensure content has proper margin-left to clear the sidebar */
.VPContent.has-sidebar {
margin-left: var(--vp-sidebar-width, 280px) !important;
margin-right: calc(var(--vp-toc-width, 220px) + 48px) !important;
padding: var(--vp-spacing-8) var(--vp-spacing-12) !important;
}
/* Adjust doc container - remove auto margin to prevent offset */
.VPDoc.has-aside .content-container {
max-width: 100%;
padding: 0 var(--vp-spacing-10);
}
/* Right TOC - fixed position with right margin */
.VPDocAside {
position: fixed;
right: 24px;
top: calc(var(--vp-nav-height, 56px) + 16px);
width: var(--vp-toc-width, 220px);
height: auto;
max-height: calc(100vh - var(--vp-nav-height, 56px) - 64px);
overflow-y: auto; overflow-y: auto;
} }
.aside-container {
position: fixed;
right: 24px;
top: calc(var(--vp-nav-height, 56px) + 16px);
width: var(--vp-toc-width, 220px);
height: auto;
max-height: calc(100vh - var(--vp-nav-height, 56px) - 64px);
overflow-y: auto;
}
.VPDocOutline {
position: relative;
height: auto;
max-height: 100%;
overflow-y: auto;
padding: var(--vp-spacing-4);
}
/* Navbar title - anchor to left edge */
.VPNavBarTitle {
position: relative !important;
margin-left: 0 !important;
padding-left: 0 !important;
}
/* Ensure navbar content-body has proper left padding */
.VPNavBar .content-body {
padding-left: var(--vp-spacing-4) !important;
}
/* Fix title position */
.VPNavBar .title {
padding-left: var(--vp-spacing-4) !important;
left: 0 !important;
}
/* Home page navbar - reduce title left margin since no sidebar */
.Layout:has(.pro-home) .VPNavBar .content-body,
.Layout:has(.pro-home) .VPNavBar .title {
padding-left: 0 !important;
}
/* Home page - no sidebar margin */
.Layout:has(.pro-home) .VPContent {
margin-left: 0 !important;
}
.VPDocOutline .outline-marker { .VPDocOutline .outline-marker {
display: block; display: block;
} }
.VPDocOutline .outline-link { .VPDocOutline .outline-link {
font-size: 13px; font-size: var(--vp-font-size-sm);
line-height: 1.6; line-height: var(--vp-line-height-normal);
padding: 4px 12px; padding: var(--vp-spacing-1) var(--vp-spacing-3);
transition: color 0.2s ease; transition: color var(--vp-transition-color);
} }
.VPDocOutline .outline-link:hover { .VPDocOutline .outline-link:hover {
color: var(--vp-c-primary); color: var(--vp-c-primary);
} }
/* Two-column layout for content + TOC */
.content-with-toc {
display: grid;
grid-template-columns: 1fr 280px;
gap: 32px;
}
} }
/* ============================================ /* ============================================
@@ -696,17 +781,17 @@
* ============================================ */ * ============================================ */
@media (min-width: 1440px) { @media (min-width: 1440px) {
:root { :root {
--vp-content-width: 1040px; --vp-content-width: 920px;
--vp-sidebar-width: 280px; --vp-sidebar-width: 300px;
--vp-prose-width: 760px;
--vp-toc-width: 260px;
} }
.VPDoc .content-container { .VPDoc.has-aside .content-container {
max-width: 90% !important; max-width: 100%;
padding: 0 48px; padding: 0 var(--vp-spacing-12);
} margin-left: 0;
margin-right: 0;
.VPDocOutline {
width: 280px;
} }
} }

83
docs/.vitepress/theme/styles/variables.css
View File

@@ -79,23 +79,58 @@
--vp-c-text-4: #9ca3af; --vp-c-text-4: #9ca3af;
--vp-c-text-code: #ef4444; --vp-c-text-code: #ef4444;
/* Typography */ /* Typography - Developer-focused font pairing */
--vp-font-family-base: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Fira Sans', 'Droid Sans', 'Helvetica Neue', sans-serif; --vp-font-family-base: 'Inter', 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Helvetica Neue', sans-serif;
--vp-font-family-mono: 'Fira Code', 'Cascadia Code', 'JetBrains Mono', Consolas, 'Courier New', monospace; --vp-font-family-mono: 'JetBrains Mono', 'Fira Code', 'Cascadia Code', Consolas, 'Courier New', monospace;
--vp-font-family-heading: 'Inter', 'IBM Plex Sans', -apple-system, BlinkMacSystemFont, sans-serif;
/* Font Sizes */ /* Font Sizes - Modular scale (1.25 ratio) */
--vp-font-size-base: 16px; --vp-font-size-xs: 0.75rem; /* 12px */
--vp-font-size-sm: 14px; --vp-font-size-sm: 0.875rem; /* 14px */
--vp-font-size-lg: 18px; --vp-font-size-base: 1rem; /* 16px */
--vp-font-size-xl: 20px; --vp-font-size-lg: 1.125rem; /* 18px */
--vp-font-size-xl: 1.25rem; /* 20px */
--vp-font-size-2xl: 1.5rem; /* 24px */
--vp-font-size-3xl: 1.875rem; /* 30px */
--vp-font-size-4xl: 2.25rem; /* 36px */
/* Spacing (Fixed) */ /* Line Heights - Optimized for readability */
--vp-spacing-xs: 0.25rem; /* 4px */ --vp-line-height-tight: 1.25;
--vp-spacing-sm: 0.5rem; /* 8px */ --vp-line-height-snug: 1.4;
--vp-spacing-md: 1rem; /* 16px */ --vp-line-height-normal: 1.6;
--vp-spacing-lg: 1.5rem; /* 24px */ --vp-line-height-relaxed: 1.75;
--vp-spacing-xl: 2rem; /* 32px */ --vp-line-height-loose: 2;
--vp-spacing-2xl: 3rem; /* 48px */
/* Spacing (Fixed) - 8px base grid */
--vp-spacing-0: 0;
--vp-spacing-px: 1px;
--vp-spacing-0-5: 0.125rem; /* 2px */
--vp-spacing-1: 0.25rem; /* 4px */
--vp-spacing-1-5: 0.375rem; /* 6px */
--vp-spacing-2: 0.5rem; /* 8px */
--vp-spacing-2-5: 0.625rem; /* 10px */
--vp-spacing-3: 0.75rem; /* 12px */
--vp-spacing-3-5: 0.875rem; /* 14px */
--vp-spacing-4: 1rem; /* 16px */
--vp-spacing-5: 1.25rem; /* 20px */
--vp-spacing-6: 1.5rem; /* 24px */
--vp-spacing-7: 1.75rem; /* 28px */
--vp-spacing-8: 2rem; /* 32px */
--vp-spacing-9: 2.25rem; /* 36px */
--vp-spacing-10: 2.5rem; /* 40px */
--vp-spacing-12: 3rem; /* 48px */
--vp-spacing-14: 3.5rem; /* 56px */
--vp-spacing-16: 4rem; /* 64px */
--vp-spacing-20: 5rem; /* 80px */
--vp-spacing-24: 6rem; /* 96px */
/* Legacy aliases for backward compatibility */
--vp-spacing-xs: var(--vp-spacing-1);
--vp-spacing-sm: var(--vp-spacing-2);
--vp-spacing-md: var(--vp-spacing-4);
--vp-spacing-lg: var(--vp-spacing-6);
--vp-spacing-xl: var(--vp-spacing-8);
--vp-spacing-2xl: var(--vp-spacing-12);
/* Fluid Spacing (Responsive with clamp()) /* Fluid Spacing (Responsive with clamp())
* Scales smoothly between viewport widths * Scales smoothly between viewport widths
@@ -116,18 +151,24 @@
--container-outline: outline; --container-outline: outline;
--container-nav: nav; --container-nav: nav;
/* Border Radius */ /* Border Radius - Subtle, flat design friendly */
--vp-radius-none: 0;
--vp-radius-sm: 0.25rem; /* 4px */ --vp-radius-sm: 0.25rem; /* 4px */
--vp-radius-md: 0.375rem; /* 6px */ --vp-radius-md: 0.375rem; /* 6px */
--vp-radius-lg: 0.5rem; /* 8px */ --vp-radius-lg: 0.5rem; /* 8px */
--vp-radius-xl: 0.75rem; /* 12px */ --vp-radius-xl: 0.75rem; /* 12px */
--vp-radius-2xl: 1rem; /* 16px */
--vp-radius-3xl: 1.5rem; /* 24px */
--vp-radius-full: 9999px; --vp-radius-full: 9999px;
/* Shadows */ /* Shadows - Subtle for flat design */
--vp-shadow-sm: 0 1px 2px 0 rgb(0 0 0 / 0.05); --vp-shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.03);
--vp-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1); --vp-shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.05), 0 1px 2px -1px rgb(0 0 0 / 0.05);
--vp-shadow-lg: 0 10px 15px -3 rgb(0 0 0 / 0.1); --vp-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.07), 0 2px 4px -2px rgb(0 0 0 / 0.05);
--vp-shadow-xl: 0 20px 25px -5 rgb(0 0 0 / 0.1); --vp-shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.08), 0 4px 6px -4px rgb(0 0 0 / 0.05);
--vp-shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.08), 0 8px 10px -6px rgb(0 0 0 / 0.05);
--vp-shadow-inner: inset 0 2px 4px 0 rgb(0 0 0 / 0.05);
--vp-shadow-none: 0 0 #0000;
/* Transitions */ /* Transitions */
--vp-transition-color: 0.2s ease; --vp-transition-color: 0.2s ease;

403
docs/guide/ch05-advanced-tips.md
View File

@@ -2,255 +2,180 @@
## One-Line Positioning ## One-Line Positioning
**Advanced Tips are the key to efficiency improvement** — Deep CLI toolchain usage, multi-model collaboration optimization, memory management best practices. **Drive AI tool orchestration with natural language** — Semantic CLI invocation, multi-model collaboration, intelligent memory management.
--- ---
## 5.1 CLI Toolchain Usage ## 5.1 Semantic Tool Orchestration
### 5.1.1 CLI Configuration ### 5.1.1 Core Concept
CLI tool configuration file: `~/.claude/cli-tools.json` CCW's CLI tools are **AI-automated capability extensions**. Users simply describe needs in natural language, and AI automatically selects and invokes the appropriate tools.
::: tip Key Understanding
- User says: "Use Gemini to analyze this code"
- AI automatically: Invokes Gemini CLI + applies analysis rules + returns results
- Users don't need to know `ccw cli` command details
:::
### 5.1.2 Available Tools & Capabilities
| Tool | Strengths | Typical Trigger Words |
| --- | --- | --- |
| **Gemini** | Deep analysis, architecture design, bug diagnosis | "use Gemini", "deep understanding" |
| **Qwen** | Code generation, feature implementation | "let Qwen implement", "code generation" |
| **Codex** | Code review, Git operations | "use Codex", "code review" |
| **OpenCode** | Open-source multi-model | "use OpenCode" |
### 5.1.3 Semantic Trigger Examples
Simply express naturally in conversation, AI will automatically invoke the corresponding tool:
| Goal | User Semantic Description | AI Auto-Executes |
| :--- | :--- | :--- |
| **Security Assessment** | "Use Gemini to scan auth module for security vulnerabilities" | Gemini + Security analysis rule |
| **Code Implementation** | "Let Qwen implement a rate limiting middleware" | Qwen + Feature implementation rule |
| **Code Review** | "Use Codex to review this PR's changes" | Codex + Review rule |
| **Bug Diagnosis** | "Use Gemini to analyze the root cause of this memory leak" | Gemini + Diagnosis rule |
### 5.1.4 Underlying Configuration (Optional)
AI tool invocation configuration file at `~/.claude/cli-tools.json`:
```json ```json
{ {
"version": "3.3.0",
"tools": { "tools": {
"gemini": { "gemini": {
"enabled": true, "enabled": true,
"primaryModel": "gemini-2.5-flash", "primaryModel": "gemini-2.5-flash",
"secondaryModel": "gemini-2.5-flash", "tags": ["analysis", "Debug"]
"tags": ["analysis", "Debug"],
"type": "builtin"
}, },
"qwen": { "qwen": {
"enabled": true, "enabled": true,
"primaryModel": "coder-model", "primaryModel": "coder-model",
"secondaryModel": "coder-model", "tags": ["implementation"]
"tags": [],
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"secondaryModel": "gpt-5.2",
"tags": [],
"type": "builtin"
} }
} }
} }
``` ```
### 5.1.2 Tag Routing ::: info Note
Tags help AI automatically select the most suitable tool based on task type. Users typically don't need to modify this configuration.
Automatically select models based on task type: :::
| Tag | Applicable Model | Task Type |
| --- | --- | --- |
| **analysis** | Gemini | Code analysis, architecture design |
| **Debug** | Gemini | Root cause analysis, problem diagnosis |
| **implementation** | Qwen | Feature development, code generation |
| **review** | Codex | Code review, Git operations |
### 5.1.3 CLI Command Templates
#### Analysis Task
```bash
ccw cli -p "PURPOSE: Identify security vulnerabilities
TASK: • Scan for SQL injection • Check XSS • Verify CSRF
MODE: analysis
CONTEXT: @src/auth/**/*
EXPECTED: Security report with severity grading and fix recommendations
CONSTRAINTS: Focus on auth module" --tool gemini --mode analysis --rule analysis-assess-security-risks
```
#### Implementation Task
```bash
ccw cli -p "PURPOSE: Implement rate limiting
TASK: • Create middleware • Configure routes • Redis backend
MODE: write
CONTEXT: @src/middleware/**/* @src/config/**/*
EXPECTED: Production code + unit tests + integration tests
CONSTRAINTS: Follow existing middleware patterns" --tool qwen --mode write --rule development-implement-feature
```
### 5.1.4 Rule Templates
| Rule | Purpose |
| --- | --- |
| **analysis-diagnose-bug-root-cause** | Bug root cause analysis |
| **analysis-analyze-code-patterns** | Code pattern analysis |
| **analysis-review-architecture** | Architecture review |
| **analysis-assess-security-risks** | Security assessment |
| **development-implement-feature** | Feature implementation |
| **development-refactor-codebase** | Code refactoring |
| **development-generate-tests** | Test generation |
--- ---
## 5.2 Multi-Model Collaboration ## 5.2 Multi-Model Collaboration
### 5.2.1 Model Selection Guide ### 5.2.1 Collaboration Patterns
| Task | Recommended Model | Reason | Through semantic descriptions, multiple AI models can work together:
| Pattern | Description Style | Use Case |
| --- | --- | --- | | --- | --- | --- |
| **Code Analysis** | Gemini | Strong at deep code understanding and pattern recognition | | **Collaborative** | "Let Gemini and Codex jointly analyze architecture issues" | Multi-perspective analysis of the same problem |
| **Pipeline** | "Gemini designs, Qwen implements, Codex reviews" | Stage-by-stage complex task completion |
| **Iterative** | "Use Gemini to diagnose, Codex to fix, iterate until tests pass" | Bug fix loop |
| **Parallel** | "Let Gemini and Qwen each provide optimization suggestions" | Compare different approaches |
### 5.2.2 Semantic Examples
**Collaborative Analysis**
```
User: Let Gemini and Codex jointly analyze security and performance of src/auth module
AI: [Automatically invokes both models, synthesizes analysis results]
```
**Pipeline Development**
```
User: I need to implement a WebSocket real-time notification feature.
Please have Gemini design the architecture, Qwen implement the code, and Codex review.
AI: [Sequentially invokes three models, completing design→implement→review flow]
```
**Iterative Fix**
```
User: Tests failed. Use Gemini to diagnose the issue, have Qwen fix it, loop until tests pass.
AI: [Automatically iterates diagnose-fix loop until problem is resolved]
```
### 5.2.3 Model Selection Guide
| Task Type | Recommended Model | Reason |
| --- | --- | --- |
| **Architecture Analysis** | Gemini | Strong at deep understanding and pattern recognition |
| **Bug Diagnosis** | Gemini | Powerful root cause analysis capability | | **Bug Diagnosis** | Gemini | Powerful root cause analysis capability |
| **Feature Development** | Qwen | High code generation efficiency | | **Code Generation** | Qwen | High code generation efficiency |
| **Code Review** | Codex (GPT) | Good Git integration, standard review format | | **Code Review** | Codex | Good Git integration, standard review format |
| **Long Text** | Claude | Large context window | | **Long Text Processing** | Claude | Large context window |
### 5.2.2 Collaboration Patterns
#### Serial Collaboration
```bash
# Step 1: Gemini analysis
ccw cli -p "Analyze code architecture" --tool gemini --mode analysis
# Step 2: Qwen implementation
ccw cli -p "Implement feature based on analysis" --tool qwen --mode write
# Step 3: Codex review
ccw cli -p "Review implementation code" --tool codex --mode review
```
#### Parallel Collaboration
Use `--tool gemini` and `--tool qwen` to analyze the same problem simultaneously:
```bash
# Terminal 1
ccw cli -p "Analyze from performance perspective" --tool gemini --mode analysis &
# Terminal 2
ccw cli -p "Analyze from security perspective" --tool codex --mode analysis &
```
### 5.2.3 Session Resume
Cross-model session resume:
```bash
# First call
ccw cli -p "Analyze authentication module" --tool gemini --mode analysis
# Resume session to continue
ccw cli -p "Based on previous analysis, design improvement plan" --tool qwen --mode write --resume
```
--- ---
## 5.3 Memory Management ## 5.3 Intelligent Memory Management
### 5.3.1 Memory Categories ### 5.3.1 Memory System Overview
| Category | Purpose | Example Content | CCW's memory system is an **AI self-managed** knowledge base, including:
| Category | Purpose | Example |
| --- | --- | --- | | --- | --- | --- |
| **learnings** | Learning insights | New technology usage experience | | **learnings** | Learning insights | New technology usage experience, best practices |
| **decisions** | Architecture decisions | Technology selection rationale | | **decisions** | Architecture decisions | Technology selection rationale, design tradeoffs |
| **conventions** | Coding standards | Naming conventions, patterns | | **conventions** | Coding standards | Naming conventions, code style |
| **issues** | Known issues | Bugs, limitations, TODOs | | **issues** | Known issues | Bug records, limitations |
### 5.3.2 Memory Commands ### 5.3.2 Automatic Memory Usage
| Command | Function | Example | AI automatically retrieves and applies relevant memories when executing tasks:
| --- | --- | --- |
| **list** | List all memories | `ccw memory list` |
| **search** | Search memories | `ccw memory search "authentication"` |
| **export** | Export memory | `ccw memory export <id>` |
| **import** | Import memory | `ccw memory import "..."` |
| **embed** | Generate embeddings | `ccw memory embed <id>` |
### 5.3.3 Memory Best Practices
::: tip Tip
- **Regular cleanup**: Organize Memory weekly, delete outdated content
- **Structure**: Use standard format for easy search and reuse
- **Context**: Record decision background, not just conclusions
- **Linking**: Cross-reference related content
:::
### 5.3.4 Memory Template
```markdown
## Title
### Background
- **Problem**: ...
- **Impact**: ...
### Decision
- **Solution**: ...
- **Rationale**: ...
### Result
- **Effect**: ...
- **Lessons Learned**: ...
### Related
- [Related Memory 1](memory-id-1)
- [Related Documentation](link)
``` ```
User: Help me implement the user authentication module
AI: [Automatically retrieves authentication-related decisions and conventions from memory]
Based on previous technical decisions, we use JWT + bcrypt approach...
```
### 5.3.3 How Users Guide Memory
While AI manages memory automatically, users can actively reinforce:
**Explicitly Request to Remember**
```
User: Remember this naming convention: all API routes use kebab-case
AI: [Stores this convention in conventions memory]
```
**Request to Review Decisions**
```
User: Why did we choose Redis for caching before?
AI: [Retrieves from decisions memory and responds]
```
**Correct Wrong Memory**
```
User: The previous decision changed, we now use PostgreSQL instead of MongoDB
AI: [Updates related decision memory]
```
### 5.3.4 Memory File Locations
- **Global Memory**: `~/.claude/projects/{project-name}/memory/`
- **Project Memory**: `.claude/memory/` or `MEMORY.md`
--- ---
## 5.4 CodexLens Advanced Usage ## 5.4 Hook Automation
### 5.4.1 Hybrid Search ### 5.4.1 Hook Concept
Combine vector search and keyword search: Hooks are automated processes before and after AI executes tasks, users don't need to trigger manually:
```bash
# Pure vector search
ccw search --mode vector "user authentication"
# Hybrid search (default)
ccw search --mode hybrid "user authentication"
# Pure keyword search
ccw search --mode keyword "authenticate"
```
### 5.4.2 Call Chain Tracing
Trace complete call chains of functions:
```bash
# Trace up (who called me)
ccw search --trace-up "authenticateUser"
# Trace down (who I called)
ccw search --trace-down "authenticateUser"
# Full call chain
ccw search --trace-full "authenticateUser"
```
### 5.4.3 Semantic Search Techniques
| Technique | Example | Effect |
| --- | --- | --- |
| **Functional description** | "handle user login" | Find login-related code |
| **Problem description** | "memory leak locations" | Find potential issues |
| **Pattern description** | "singleton implementation" | Find design patterns |
| **Technical description** | "using React Hooks" | Find related usage |
---
## 5.5 Hook Auto-Injection
### 5.5.1 Hook Types
| Hook Type | Trigger Time | Purpose | | Hook Type | Trigger Time | Purpose |
| --- | --- | --- | | --- | --- | --- |
| **pre-command** | Before command execution | Inject specifications, load context | | **pre-command** | Before AI thinking | Load project specs, retrieve memory |
| **post-command** | After command execution | Save Memory, update state | | **post-command** | After AI completion | Save decisions, update index |
| **pre-commit** | Before Git commit | Code review, standard checks | | **pre-commit** | Before Git commit | Code review, standard checks |
| **file-change** | On file change | Auto-format, update index |
### 5.5.2 Hook Configuration ### 5.4.2 Configuration Example
Configure in `.claude/hooks.json`: Configure in `.claude/hooks.json`:
@@ -258,19 +183,14 @@ Configure in `.claude/hooks.json`:
{ {
"pre-command": [ "pre-command": [
{ {
"name": "inject-specs", "name": "load-project-specs",
"description": "Inject project specifications", "description": "Load project specifications",
"command": "cat .workflow/specs/project-constraints.md" "command": "cat .workflow/specs/project-constraints.md"
},
{
"name": "load-memory",
"description": "Load related Memory",
"command": "ccw memory search \"{query}\""
} }
], ],
"post-command": [ "post-command": [
{ {
"name": "save-memory", "name": "save-decisions",
"description": "Save important decisions", "description": "Save important decisions",
"command": "ccw memory import \"{content}\"" "command": "ccw memory import \"{content}\""
} }
@@ -280,49 +200,54 @@ Configure in `.claude/hooks.json`:
--- ---
## 5.6 Performance Optimization ## 5.5 ACE Semantic Search
### 5.6.1 Indexing Optimization ### 5.5.1 What is ACE
| Optimization | Description | ACE (Augment Context Engine) is AI's **code perception capability**, enabling AI to understand the entire codebase semantically.
### 5.5.2 How AI Uses ACE
When users ask questions, AI automatically uses ACE to search for relevant code:
```
User: How is the authentication flow implemented?
AI: [Uses ACE semantic search for auth-related code]
Based on code analysis, the authentication flow is...
```
### 5.5.3 Configuration Reference
| Configuration Method | Link |
| --- | --- | | --- | --- |
| **Incremental indexing** | Only index changed files | | **Official Docs** | [Augment MCP Documentation](https://docs.augmentcode.com/context-services/mcp/overview) |
| **Parallel indexing** | Multi-process parallel processing | | **Proxy Tool** | [ace-tool (GitHub)](https://github.com/eastxiaodong/ace-tool) |
| **Caching strategy** | Vector embedding cache |
### 5.6.2 Search Optimization
| Optimization | Description |
| --- | --- |
| **Result caching** | Same query returns cached results |
| **Paginated loading** | Large result sets paginated |
| **Smart deduplication** | Auto-duplicate similar results |
--- ---
## 5.7 Quick Reference ## 5.6 Semantic Prompt Cheatsheet
### CLI Command Cheatsheet ### Common Semantic Patterns
| Command | Function | | Goal | Semantic Description Example |
| --- | --- | | --- | --- |
| `ccw cli -p "..." --tool gemini --mode analysis` | Analysis task | | **Analyze Code** | "Use Gemini to analyze the architecture design of src/auth" |
| `ccw cli -p "..." --tool qwen --mode write` | Implementation task | | **Security Audit** | "Use Gemini to scan for security vulnerabilities, focus on OWASP Top 10" |
| `ccw cli -p "..." --tool codex --mode review` | Review task | | **Implement Feature** | "Let Qwen implement a cached user repository" |
| `ccw memory list` | List memories | | **Code Review** | "Use Codex to review recent changes" |
| `ccw memory search "..."` | Search memories | | **Bug Diagnosis** | "Use Gemini to analyze the root cause of this memory leak" |
| `ccw search "..."` | Semantic search | | **Multi-Model Collaboration** | "Gemini designs, Qwen implements, Codex reviews" |
| `ccw search --trace "..."` | Call chain tracing | | **Remember Convention** | "Remember: all APIs use RESTful style" |
| **Review Decision** | "Why did we choose this tech stack before?" |
### Rule Template Cheatsheet ### Collaboration Pattern Cheatsheet
| Rule | Purpose | | Pattern | Semantic Example |
| --- | --- | | --- | --- |
| `analysis-diagnose-bug-root-cause` | Bug analysis | | **Collaborative** | "Let Gemini and Codex jointly analyze..." |
| `analysis-assess-security-risks` | Security assessment | | **Pipeline** | "Gemini designs, Qwen implements, Codex reviews" |
| `development-implement-feature` | Feature implementation | | **Iterative** | "Diagnose and fix until tests pass" |
| `development-refactor-codebase` | Code refactoring | | **Parallel** | "Let multiple models each provide suggestions" |
| `development-generate-tests` | Test generation |
--- ---

17
docs/reference/commands-skills.md
View File

@@ -4,23 +4,6 @@
--- ---
## 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 ## Quick Reference Table
### Commands Quick Reference ### Commands Quick Reference

613
docs/skills/claude-collaboration.md
View File

@@ -1,11 +1,6 @@
---
适用CLI: claude
分类: team
---
# Claude Skills - Team Collaboration # Claude Skills - Team Collaboration
## One-Liner ## One-Line Positioning
**Team Collaboration Skills is a multi-role collaborative work orchestration system** — Through coordinator, worker roles, and message bus, it enables parallel processing and state synchronization for complex tasks. **Team Collaboration Skills is a multi-role collaborative work orchestration system** — Through coordinator, worker roles, and message bus, it enables parallel processing and state synchronization for complex tasks.
@@ -13,32 +8,83 @@
| Pain Point | Current State | Claude Code Workflow Solution | | Pain Point | Current State | Claude Code Workflow Solution |
|------------|---------------|----------------------| |------------|---------------|----------------------|
| **Single model limitation** | Can only call one AI model | Multi-role parallel collaboration, leveraging各自专长 | | **Single model limitation** | Can only call one AI model | Multi-role parallel collaboration, leveraging respective strengths |
| **Chaotic task orchestration** | Manual task dependency and state management | Automatic task discovery, dependency resolution, pipeline orchestration | | **Chaotic task orchestration** | Manual task dependency and state management | Automatic task discovery, dependency resolution, pipeline orchestration |
| **Fragmented collaboration** | Team members work independently | Unified message bus, shared state, progress sync | | **Fragmented collaboration** | Team members work independently | Unified message bus, shared state, progress sync |
| **Resource waste** | Repeated context loading | Wisdom accumulation, exploration cache, artifact reuse | | **Resource waste** | Repeated context loading | Wisdom accumulation, exploration cache, artifact reuse |
## Skills List ---
| Skill | Function | Trigger | ## Skills Overview
|-------|----------|---------|
| `team-coordinate` | Universal team coordinator (dynamic role generation) | `/team-coordinate` | | Skill | Function | Use Case |
| `team-lifecycle` | Full lifecycle team (spec→impl→test→review) | `/team-lifecycle` | | --- | --- | --- |
| `team-planex` | Plan-execute pipeline (plan while executing) | `/team-planex` | | `team-coordinate-v2` | Universal team coordinator (dynamic role generation) | Any complex task |
| `team-review` | Code review team (scan→review→fix) | `/team-review` | | `team-lifecycle-v5` | Full lifecycle team (spec→impl→test) | Complete feature development |
| `team-testing` | Testing team (strategy→generate→execute→analyze) | `/team-testing` | | `team-planex` | Plan-execute pipeline | Issue batch processing |
| `team-review` | Code review team | Code review, vulnerability scanning |
| `team-testing` | Testing team | Test coverage, test case generation |
| `team-arch-opt` | Architecture optimization team | Refactoring, architecture analysis |
| `team-perf-opt` | Performance optimization team | Performance tuning, bottleneck analysis |
| `team-brainstorm` | Brainstorming team | Multi-angle analysis, idea generation |
| `team-frontend` | Frontend development team | UI development, design system |
| `team-uidesign` | UI design team | Design system, component specs |
| `team-issue` | Issue processing team | Issue analysis, implementation |
| `team-iterdev` | Iterative development team | Incremental delivery, agile development |
| `team-quality-assurance` | Quality assurance team | Quality scanning, defect management |
| `team-roadmap-dev` | Roadmap development team | Phased development, milestones |
| `team-tech-debt` | Tech debt team | Debt cleanup, code governance |
| `team-ultra-analyze` | Deep analysis team | Complex problem analysis, collaborative exploration |
| `team-executor-v2` | Lightweight executor | Session resume, pure execution |
---
## Core Architecture
All Team Skills share a unified **team-worker agent architecture**:
```
┌──────────────────────────────────────────────────────────┐
│ Skill(skill="team-xxx", args="task description") │
└────────────────────────┬─────────────────────────────────┘
│ Role Router
┌──── --role present? ────┐
│ NO │ YES
↓ ↓
Orchestration Mode Role Dispatch
(auto → coordinator) (route to role.md)
│
┌─────────┴─────────┬───────────────┬──────────────┐
↓ ↓ ↓ ↓
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ coord │ │worker 1│ │worker 2│ │worker N│
│(orchestrate)│ │(execute)│ │(execute)│ │(execute)│
└────────┘ └────────┘ └────────┘ └────────┘
│ │ │ │
└───────────────────┴───────────────┴──────────────┘
│
Message Bus (message bus)
```
**Core Components**:
- **Coordinator**: Built-in orchestrator for task analysis, dispatch, monitoring
- **Team-Worker Agent**: Unified agent, loads role-spec to execute role logic
- **Role Router**: `--role=xxx` parameter routes to role execution
- **Message Bus**: Inter-team member communication protocol
- **Shared Memory**: Cross-task knowledge accumulation (Wisdom)
---
## Skills Details ## Skills Details
### team-coordinate ### team-coordinate-v2
**One-Liner**: Universal team coordinator — Dynamically generates roles and orchestrates execution based on task analysis **One-Liner**: Universal team coordinator — Dynamically generates roles and orchestrates execution based on task analysis
**Trigger**: **Trigger**:
``` ```bash
/team-coordinate <task-description> team-coordinate <task-description>
/team-coordinate --role=coordinator <task> team-coordinate --role=coordinator <task>
/team-coordinate --role=<worker> --session=<path>
``` ```
**Features**: **Features**:
@@ -47,17 +93,6 @@
- Fast-Advance mechanism skips coordinator to directly spawn successor tasks - Fast-Advance mechanism skips coordinator to directly spawn successor tasks
- Wisdom accumulates cross-task knowledge - Wisdom accumulates cross-task knowledge
**Role Registry**:
| Role | File | Task Prefix | Type |
|------|------|-------------|------|
| coordinator | roles/coordinator/role.md | (none) | orchestrator |
| (dynamic) | `<session>/roles/<role>.md` | (dynamic) | worker |
**Pipeline**:
```
Task Analysis → Generate Roles → Initialize Session → Create Task Chain → Spawn First Batch Workers → Loop Progress → Completion Report
```
**Session Directory**: **Session Directory**:
``` ```
.workflow/.team/TC-<slug>-<date>/ .workflow/.team/TC-<slug>-<date>/
@@ -66,20 +101,18 @@ Task Analysis → Generate Roles → Initialize Session → Create Task Chain
├── roles/ # Dynamic role definitions ├── roles/ # Dynamic role definitions
├── artifacts/ # All MD deliverables ├── artifacts/ # All MD deliverables
├── wisdom/ # Cross-task knowledge ├── wisdom/ # Cross-task knowledge
├── explorations/ # Shared exploration cache
├── discussions/ # Inline discussion records
└── .msg/ # Team message bus logs └── .msg/ # Team message bus logs
``` ```
--- ---
### team-lifecycle ### team-lifecycle-v5
**One-Liner**: Full lifecycle team — Complete pipeline from specification to implementation to testing to review **One-Liner**: Full lifecycle team — Complete pipeline from specification to implementation to testing to review
**Trigger**: **Trigger**:
``` ```bash
/team-lifecycle <task-description> team-lifecycle <task-description>
``` ```
**Features**: **Features**:
@@ -97,164 +130,67 @@ Task Analysis → Generate Roles → Initialize Session → Create Task Chain
| executor | role-specs/executor.md | IMPL-* | true | | executor | role-specs/executor.md | IMPL-* | true |
| tester | role-specs/tester.md | TEST-* | false | | tester | role-specs/tester.md | TEST-* | false |
| reviewer | role-specs/reviewer.md | REVIEW-* | false | | reviewer | role-specs/reviewer.md | REVIEW-* | false |
| architect | role-specs/architect.md | ARCH-* | false |
| fe-developer | role-specs/fe-developer.md | DEV-FE-* | false |
| fe-qa | role-specs/fe-qa.md | QA-FE-* | false |
**Pipeline Definitions**: **Pipeline Definitions**:
``` ```
Specification Pipeline (6 tasks): Specification Pipeline: RESEARCH → DRAFT → QUALITY
RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001 Implementation Pipeline: PLAN → IMPL → TEST + REVIEW
Full Lifecycle: [Spec Pipeline] → [Impl Pipeline]
Implementation Pipeline (4 tasks):
PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
Full Lifecycle (10 tasks):
[Spec Pipeline] → PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
Frontend Pipeline:
PLAN-001 → DEV-FE-001 → QA-FE-001 (GC loop, max 2 rounds)
``` ```
**Quality Gate** (after QUALITY-001 completion):
```
═════════════════════════════════════════
SPEC PHASE COMPLETE
Quality Gate: <PASS|REVIEW|FAIL> (<score>%)
Dimension Scores:
Completeness: <bar> <n>%
Consistency: <bar> <n>%
Traceability: <bar> <n>%
Depth: <bar> <n>%
Coverage: <bar> <n>%
Available Actions:
resume -> Proceed to implementation
improve -> Auto-improve weakest dimension
improve <dimension> -> Improve specific dimension
revise <TASK-ID> -> Revise specific document
recheck -> Re-run quality check
feedback <text> -> Inject feedback, create revision
═════════════════════════════════════════
```
**User Commands** (wake paused coordinator):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph, no progress |
| `resume` / `continue` | Check worker status, advance next step |
| `revise <TASK-ID> [feedback]` | Create revision task + cascade downstream |
| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
| `recheck` | Re-run QUALITY-001 quality check |
| `improve [dimension]` | Auto-improve weakest dimension in readiness-report |
--- ---
### team-planex ### team-planex
**One-Liner**: Plan-and-execute team — Planner and executor work in parallel through per-issue beat pipeline **One-Liner**: Plan-and-execute team — Per-issue beat pipeline
**Trigger**: **Trigger**:
``` ```bash
/team-planex <task-description> team-planex <task-description>
/team-planex --role=planner <input> team-planex --role=planner <input>
/team-planex --role=executor --input <solution-file> team-planex --role=executor --input <solution-file>
``` ```
**Features**: **Features**:
- 2-member team (planner + executor), planner serves as lead role - 2-member team (planner + executor), planner serves as lead role
- Per-issue beat: planner creates EXEC-* task immediately after completing each issue's solution - Per-issue beat: planner creates EXEC-* task immediately after completing each issue
- Solution written to intermediate artifact file, executor loads from file - Solution written to intermediate artifact file, executor loads from file
- Supports multiple execution backends (agent/codex/gemini)
**Role Registry**: **Wave Pipeline**:
| Role | File | Task Prefix | Type |
|------|------|-------------|------|
| planner | roles/planner.md | PLAN-* | pipeline (lead) |
| executor | roles/executor.md | EXEC-* | pipeline |
**Input Types**:
| Input Type | Format | Example |
|------------|--------|---------|
| Issue IDs | Direct ID input | `--role=planner ISS-20260215-001 ISS-20260215-002` |
| Requirement text | `--text '...'` | `--role=planner --text 'Implement user authentication module'` |
| Plan file | `--plan path` | `--role=planner --plan plan/2026-02-15-auth.md` |
**Wave Pipeline** (per-issue beat):
``` ```
Issue 1: planner plans solution → write artifact → conflict check → create EXEC-* → issue_ready Issue 1: planner plans → write artifact → create EXEC-* → executor executes
↓ (executor starts immediately) Issue 2: planner plans → write artifact → create EXEC-* → executor parallel consume
Issue 2: planner plans solution → write artifact → conflict check → create EXEC-* → issue_ready Final: planner sends all_planned → executor completes remaining → finish
↓ (executor consumes in parallel)
Issue N: ...
Final: planner sends all_planned → executor completes remaining EXEC-* → finish
``` ```
**Execution Method Selection**:
| Executor | Backend | Use Case |
|----------|---------|----------|
| `agent` | code-developer subagent | Simple tasks, synchronous execution |
| `codex` | `ccw cli --tool codex --mode write` | Complex tasks, background execution |
| `gemini` | `ccw cli --tool gemini --mode write` | Analysis tasks, background execution |
**User Commands**:
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph, no progress |
| `resume` / `continue` | Check worker status, advance next step |
| `add <issue-ids or --text '...' or --plan path>` | Append new tasks to planner queue |
--- ---
### team-review ### team-review
**One-Liner**: Code review team — Unified code scanning, vulnerability review, optimization suggestions, and auto-fix **One-Liner**: Code review team — Unified code scanning, vulnerability review, auto-fix
**Trigger**: **Trigger**:
```bash
team-review <target-path>
team-review --full <target-path> # scan + review + fix
team-review --fix <review-files> # fix only
team-review -q <target-path> # quick scan only
``` ```
/team-review <target-path>
/team-review --full <target-path> # scan + review + fix
/team-review --fix <review-files> # fix only
/team-review -q <target-path> # quick scan only
```
**Features**:
- 4-role team (coordinator, scanner, reviewer, fixer)
- Multi-dimensional review: security, correctness, performance, maintainability
- Auto-fix loop (review → fix → verify)
**Role Registry**: **Role Registry**:
| Role | File | Task Prefix | Type | | Role | Task Prefix | Type |
|------|------|-------------|------| |------|-------------|------|
| coordinator | roles/coordinator/role.md | RC-* | orchestrator | | coordinator | RC-* | orchestrator |
| scanner | roles/scanner/role.md | SCAN-* | read-only analysis | | scanner | SCAN-* | read-only analysis |
| reviewer | roles/reviewer/role.md | REV-* | read-only analysis | | reviewer | REV-* | read-only analysis |
| fixer | roles/fixer/role.md | FIX-* | code generation | | fixer | FIX-* | code generation |
**Pipeline** (CP-1 Linear): **Pipeline**:
``` ```
coordinator dispatch SCAN-* (scan) → REV-* (review) → [User confirmation] → FIX-* (fix)
→ SCAN-* (scanner: toolchain + LLM scan)
→ REV-* (reviewer: deep analysis + report)
→ [User confirmation]
→ FIX-* (fixer: plan + execute + verify)
``` ```
**Checkpoints**: **Review Dimensions**: Security, Correctness, Performance, Maintainability
| Trigger | Location | Behavior |
|---------|----------|----------|
| Review→Fix transition | REV-* complete | Pause, show review report, wait for user `resume` to confirm fix |
| Quick mode (`-q`) | After SCAN-* | Pipeline ends after scan, no review/fix |
| Fix-only mode (`--fix`) | Entry | Skip scan/review, go directly to fixer |
**Review Dimensions**:
| Dimension | Check Points |
|-----------|--------------|
| Security (sec) | Injection vulnerabilities, sensitive data leakage, permission control |
| Correctness (cor) | Boundary conditions, error handling, type safety |
| Performance (perf) | Algorithm complexity, I/O optimization, resource usage |
| Maintainability (maint) | Code structure, naming conventions, comment quality |
--- ---
@@ -263,75 +199,318 @@ coordinator dispatch
**One-Liner**: Testing team — Progressive test coverage through Generator-Critic loop **One-Liner**: Testing team — Progressive test coverage through Generator-Critic loop
**Trigger**: **Trigger**:
```bash
team-testing <task-description>
``` ```
/team-testing <task-description>
```
**Features**:
- 5-role team (coordinator, strategist, generator, executor, analyst)
- Three pipelines: Targeted, Standard, Comprehensive
- Generator-Critic loop automatically improves test coverage
**Role Registry**: **Role Registry**:
| Role | File | Task Prefix | Type | | Role | Task Prefix | Type |
|------|------|-------------|------| |------|-------------|------|
| coordinator | roles/coordinator.md | (none) | orchestrator | | coordinator | (none) | orchestrator |
| strategist | roles/strategist.md | STRATEGY-* | pipeline | | strategist | STRATEGY-* | pipeline |
| generator | roles/generator.md | TESTGEN-* | pipeline | | generator | TESTGEN-* | pipeline |
| executor | roles/executor.md | TESTRUN-* | pipeline | | executor | TESTRUN-* | pipeline |
| analyst | roles/analyst.md | TESTANA-* | pipeline | | analyst | TESTANA-* | pipeline |
**Three Pipelines**: **Three Pipelines**:
``` ```
Targeted (small scope changes): Targeted: STRATEGY → TESTGEN(L1) → TESTRUN
STRATEGY-001 → TESTGEN-001(L1 unit) → TESTRUN-001 Standard: STRATEGY → TESTGEN(L1) → TESTRUN → TESTGEN(L2) → TESTRUN → TESTANA
Comprehensive: STRATEGY → [TESTGEN(L1+L2) parallel] → [TESTRUN parallel] → TESTGEN(L3) → TESTRUN → TESTANA
Standard (progressive):
STRATEGY-001 → TESTGEN-001(L1) → TESTRUN-001(L1) → TESTGEN-002(L2) → TESTRUN-002(L2) → TESTANA-001
Comprehensive (full coverage):
STRATEGY-001 → [TESTGEN-001(L1) + TESTGEN-002(L2)](parallel) → [TESTRUN-001(L1) + TESTRUN-002(L2)](parallel) → TESTGEN-003(L3) → TESTRUN-003(L3) → TESTANA-001
``` ```
**Generator-Critic Loop**: **Test Layers**: L1: Unit (80%) → L2: Integration (60%) → L3: E2E (40%)
```
TESTGEN → TESTRUN → (if coverage < target) → TESTGEN-fix → TESTRUN-2 ---
(if coverage >= target) → next layer or TESTANA
### team-arch-opt
**One-Liner**: Architecture optimization team — Analyze architecture issues, design refactoring strategies, implement improvements
**Trigger**:
```bash
team-arch-opt <task-description>
``` ```
**Test Layer Definitions**: **Role Registry**:
| Layer | Coverage Target | Example | | Role | Task Prefix | Function |
|-------|-----------------|---------| |------|-------------|----------|
| L1: Unit | 80% | Unit tests, function-level tests | | coordinator | (none) | orchestrator |
| L2: Integration | 60% | Integration tests, module interaction | | analyzer | ANALYZE-* | architecture analysis |
| L3: E2E | 40% | End-to-end tests, user scenarios | | designer | DESIGN-* | refactoring design |
| refactorer | REFACT-* | implement refactoring |
| validator | VALID-* | validate improvements |
| reviewer | REVIEW-* | code review |
**Shared Memory** (shared-memory.json): **Detection Scope**: Dependency cycles, coupling/cohesion, layering violations, God Classes, dead code
| Role | Field |
|------|-------| ---
| strategist | `test_strategy` |
| generator | `generated_tests` | ### team-perf-opt
| executor | `execution_results`, `defect_patterns` |
| analyst | `analysis_report`, `coverage_history` | **One-Liner**: Performance optimization team — Performance profiling, bottleneck identification, optimization implementation
**Trigger**:
```bash
team-perf-opt <task-description>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | orchestrator |
| profiler | PROFILE-* | performance profiling |
| strategist | STRAT-* | optimization strategy |
| optimizer | OPT-* | implement optimization |
| benchmarker | BENCH-* | benchmarking |
| reviewer | REVIEW-* | code review |
---
### team-brainstorm
**One-Liner**: Brainstorming team — Multi-angle creative analysis, Generator-Critic loop
**Trigger**:
```bash
team-brainstorm <topic>
team-brainstorm --role=ideator <topic>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | orchestrator |
| ideator | IDEA-* | idea generation |
| challenger | CHALLENGE-* | critical questioning |
| synthesizer | SYNTH-* | synthesis integration |
| evaluator | EVAL-* | evaluation scoring |
---
### team-frontend
**One-Liner**: Frontend development team — Built-in ui-ux-pro-max design intelligence
**Trigger**:
```bash
team-frontend <task-description>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | orchestrator |
| analyst | ANALYZE-* | requirement analysis |
| architect | ARCH-* | architecture design |
| developer | DEV-* | frontend implementation |
| qa | QA-* | quality assurance |
---
### team-uidesign
**One-Liner**: UI design team — Design system analysis, token definition, component specs
**Trigger**:
```bash
team-uidesign <task>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | orchestrator |
| researcher | RESEARCH-* | design research |
| designer | DESIGN-* | design definition |
| reviewer | AUDIT-* | accessibility audit |
| implementer | BUILD-* | code implementation |
---
### team-issue
**One-Liner**: Issue processing team — Issue processing pipeline
**Trigger**:
```bash
team-issue <issue-ids>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | orchestrator |
| explorer | EXPLORE-* | code exploration |
| planner | PLAN-* | solution planning |
| implementer | IMPL-* | code implementation |
| reviewer | REVIEW-* | code review |
| integrator | INTEG-* | integration validation |
---
### team-iterdev
**One-Liner**: Iterative development team — Generator-Critic loop, incremental delivery
**Trigger**:
```bash
team-iterdev <task-description>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | orchestrator |
| architect | ARCH-* | architecture design |
| developer | DEV-* | feature development |
| tester | TEST-* | test validation |
| reviewer | REVIEW-* | code review |
**Features**: Developer-Reviewer loop (max 3 rounds), Task Ledger real-time progress
---
### team-quality-assurance
**One-Liner**: Quality assurance team — Issue discovery + test validation closed loop
**Trigger**:
```bash
team-quality-assurance <task-description>
team-qa <task-description>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | orchestrator |
| scout | SCOUT-* | issue discovery |
| strategist | QASTRAT-* | strategy formulation |
| generator | QAGEN-* | test generation |
| executor | QARUN-* | test execution |
| analyst | QAANA-* | result analysis |
---
### team-roadmap-dev
**One-Liner**: Roadmap development team — Phased development, milestone management
**Trigger**:
```bash
team-roadmap-dev <task-description>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | human interaction |
| planner | PLAN-* | phase planning |
| executor | EXEC-* | phase execution |
| verifier | VERIFY-* | phase validation |
---
### team-tech-debt
**One-Liner**: Tech debt team — Debt scanning, assessment, cleanup, validation
**Trigger**:
```bash
team-tech-debt <task-description>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | orchestrator |
| scanner | TDSCAN-* | debt scanning |
| assessor | TDEVAL-* | quantitative assessment |
| planner | TDPLAN-* | governance planning |
| executor | TDFIX-* | cleanup execution |
| validator | TDVAL-* | validation regression |
---
### team-ultra-analyze
**One-Liner**: Deep analysis team — Multi-role collaborative exploration, progressive understanding
**Trigger**:
```bash
team-ultra-analyze <topic>
team-analyze <topic>
```
**Role Registry**:
| Role | Task Prefix | Function |
|------|-------------|----------|
| coordinator | (none) | orchestrator |
| explorer | EXPLORE-* | code exploration |
| analyst | ANALYZE-* | deep analysis |
| discussant | DISCUSS-* | discussion interaction |
| synthesizer | SYNTH-* | synthesis output |
**Features**: Supports Quick/Standard/Deep three depth modes
---
### team-executor-v2
**One-Liner**: Lightweight executor — Resume session, pure execution mode
**Trigger**:
```bash
team-executor --session=<path>
```
**Features**:
- No analysis, no role generation — only load and execute existing session
- Used to resume interrupted team-coordinate sessions
---
## User Commands
All Team Skills support unified user commands (wake paused coordinator):
| Command | Action |
|---------|--------|
| `check` / `status` | Output execution status graph, no progress |
| `resume` / `continue` | Check worker status, advance next step |
| `revise <TASK-ID>` | Create revision task + cascade downstream |
| `feedback <text>` | Analyze feedback impact, create targeted revision chain |
---
## Best Practices
1. **Choose the right team type**:
- General tasks → `team-coordinate-v2`
- Complete feature development → `team-lifecycle-v5`
- Issue batch processing → `team-planex`
- Code review → `team-review`
- Test coverage → `team-testing`
- Architecture optimization → `team-arch-opt`
- Performance tuning → `team-perf-opt`
- Brainstorming → `team-brainstorm`
- Frontend development → `team-frontend`
- UI design → `team-uidesign`
- Tech debt → `team-tech-debt`
- Deep analysis → `team-ultra-analyze`
2. **Leverage inner-loop roles**: Set `inner_loop: true` to let single worker handle multiple same-prefix tasks
3. **Wisdom accumulation**: All roles in team sessions accumulate knowledge to `wisdom/` directory
4. **Fast-Advance**: Simple linear successor tasks automatically skip coordinator to spawn directly
5. **Checkpoint recovery**: All team skills support session recovery via `--resume` or `resume` command
---
## Related Commands ## Related Commands
- [Claude Commands - Workflow](../commands/claude/workflow.md) - [Claude Commands - Workflow](../commands/claude/workflow.md)
- [Claude Commands - Session](../commands/claude/session.md) - [Claude Commands - Session](../commands/claude/session.md)
## Best Practices
1. **Choose the right team type**:
- General tasks → `team-coordinate`
- Full feature development → `team-lifecycle`
- Issue batch processing → `team-planex`
- Code review → `team-review`
- Test coverage → `team-testing`
2. **Leverage inner-loop roles**: For roles with multiple same-prefix serial tasks, set `inner_loop: true` to let a single worker handle all tasks, avoiding repeated spawn overhead
3. **Wisdom accumulation**: All roles in team sessions accumulate knowledge to `wisdom/` directory, subsequent tasks can reuse these patterns, decisions, and conventions
4. **Fast-Advance**: Simple linear successor tasks automatically skip coordinator to spawn directly, reducing coordination overhead
5. **Checkpoint recovery**: All team skills support session recovery, continue interrupted sessions via `--resume` or user command `resume`

52
docs/zh/features/cli.md
View File

@@ -14,6 +14,58 @@
| **错误恢复缺失** | 工具失败只能手动重试 | 自动 fallback 到备用模型 | | **错误恢复缺失** | 工具失败只能手动重试 | 自动 fallback 到备用模型 |
| **上下文管理弱** | 多轮对话上下文不连贯 | Native Resume 自动管理 | | **上下文管理弱** | 多轮对话上下文不连贯 | Native Resume 自动管理 |
---
## 语义化调用（推荐）
::: tip 核心理念
CLI 工具是 **AI 自动调用的能力扩展**。用户只需用自然语言描述需求，AI 会自动选择并调用合适的工具。
:::
### 语义触发示例
只需在对话中自然表达，AI 会自动调用对应工具：
| 目标 | 用户语义描述 | AI 自动执行 |
| :--- | :--- | :--- |
| **代码分析** | "用 Gemini 分析 auth 模块的代码结构" | Gemini + 分析规则 |
| **安全审计** | "用 Gemini 扫描安全漏洞，重点关注 OWASP Top 10" | Gemini + 安全评估规则 |
| **代码实现** | "让 Qwen 实现一个带缓存的用户仓库" | Qwen + 功能实现规则 |
| **代码审查** | "用 Codex 审查这个 PR 的改动" | Codex + 审查规则 |
| **Bug 诊断** | "用 Gemini 分析这个内存泄漏的根因" | Gemini + 诊断规则 |
### 多模型协作模式
通过语义描述，可以让多个 AI 模型协同工作：
| 模式 | 描述方式 | 适用场景 |
| --- | --- | --- |
| **协作型** | "让 Gemini 和 Codex 共同分析架构问题" | 多角度分析同一问题 |
| **流水线型** | "Gemini 设计方案，Qwen 实现，Codex 审查" | 分阶段完成复杂任务 |
| **迭代型** | "用 Gemini 诊断问题，Codex 修复，迭代直到通过测试" | Bug 修复循环 |
| **并行型** | "让 Gemini 和 Qwen 分别给出优化建议" | 对比不同方案 |
### 协作示例
**流水线开发**
```
用户：我需要实现一个 WebSocket 实时通知功能。
请 Gemini 设计架构，Qwen 实现代码，最后用 Codex 审查。
AI：[依次调用三个模型，完成设计→实现→审查流程]
```
**迭代修复**
```
用户：测试失败了，用 Gemini 诊断原因，让 Qwen 修复，循环直到测试通过。
AI：[自动迭代诊断-修复流程，直到问题解决]
```
---
## 底层命令参考
以下是 AI 自动调用时使用的底层命令，用户通常无需手动执行。
## 核心概念速览 ## 核心概念速览
| 概念 | 说明 | 示例 | | 概念 | 说明 | 示例 |

403
docs/zh/guide/ch05-advanced-tips.md
View File

@@ -2,255 +2,180 @@
## 一句话定位 ## 一句话定位
**高级技巧是提升效率的关键** — CLI 工具链深度使用、多模型协作优化、记忆管理最佳实践。 **用自然语言驱动 AI 编排工具链** — 语义化 CLI 调用、多模型协作、智能记忆管理。
--- ---
## 5.1 CLI 工具链使用 ## 5.1 语义化工具调度
### 5.1.1 CLI 配置 ### 5.1.1 核心理念
CLI 工具配置文件：`~/.claude/cli-tools.json` CCW 的 CLI 工具是 **AI 自动调用的能力扩展**，用户只需用自然语言描述需求，AI 会自动选择并调用合适的工具。
::: tip 关键理解
- 用户说："用 Gemini 分析这段代码"
- AI 自动：调用 Gemini CLI + 应用分析规则 + 返回结果
- 用户无需关心 `ccw cli` 命令细节
:::
### 5.1.2 可用工具与能力
| 工具 | 擅长领域 | 典型触发词 |
| --- | --- | --- |
| **Gemini** | 深度分析、架构设计、Bug 诊断 | "用 Gemini 分析"、"深度理解" |
| **Qwen** | 代码生成、功能实现 | "让 Qwen 实现"、"代码生成" |
| **Codex** | 代码审查、Git 操作 | "用 Codex 审查"、"代码评审" |
| **OpenCode** | 开源多模型 | "用 OpenCode" |
### 5.1.3 语义触发示例
只需在对话中自然表达，AI 会自动调用对应工具：
| 目标 | 用户语义描述 | AI 自动执行 |
| :--- | :--- | :--- |
| **安全评估** | "用 Gemini 扫描认证模块的安全漏洞" | Gemini + 安全分析规则 |
| **代码实现** | "让 Qwen 帮我实现一个速率限制中间件" | Qwen + 功能实现规则 |
| **代码审查** | "用 Codex 审查这个 PR 的改动" | Codex + 审查规则 |
| **Bug 诊断** | "用 Gemini 分析这个内存泄漏的根因" | Gemini + 诊断规则 |
### 5.1.4 底层配置（可选了解）
AI 调用工具的配置文件位于 `~/.claude/cli-tools.json`：
```json ```json
{ {
"version": "3.3.0",
"tools": { "tools": {
"gemini": { "gemini": {
"enabled": true, "enabled": true,
"primaryModel": "gemini-2.5-flash", "primaryModel": "gemini-2.5-flash",
"secondaryModel": "gemini-2.5-flash", "tags": ["分析", "Debug"]
"tags": ["分析", "Debug"],
"type": "builtin"
}, },
"qwen": { "qwen": {
"enabled": true, "enabled": true,
"primaryModel": "coder-model", "primaryModel": "coder-model",
"secondaryModel": "coder-model", "tags": ["实现"]
"tags": [],
"type": "builtin"
},
"codex": {
"enabled": true,
"primaryModel": "gpt-5.2",
"secondaryModel": "gpt-5.2",
"tags": [],
"type": "builtin"
} }
} }
} }
``` ```
### 5.1.2 标签路由 ::: info 说明
标签（tags）帮助 AI 根据任务类型自动选择最合适的工具。用户通常无需修改此配置。
根据任务类型自动选择模型： :::
| 标签 | 适用模型 | 任务类型 |
| --- | --- | --- |
| **分析** | Gemini | 代码分析、架构设计 |
| **Debug** | Gemini | 根因分析、问题诊断 |
| **实现** | Qwen | 功能开发、代码生成 |
| **审查** | Codex | 代码审查、Git 操作 |
### 5.1.3 CLI 命令模板
#### 分析任务
```bash
ccw cli -p "PURPOSE: 识别安全漏洞
TASK: • 扫描 SQL 注入 • 检查 XSS • 验证 CSRF
MODE: analysis
CONTEXT: @src/auth/**/*
EXPECTED: 安全报告，含严重性分级和修复建议
CONSTRAINTS: 聚焦认证模块" --tool gemini --mode analysis --rule analysis-assess-security-risks
```
#### 实现任务
```bash
ccw cli -p "PURPOSE: 实现速率限制
TASK: • 创建中间件 • 配置路由 • Redis 后端
MODE: write
CONTEXT: @src/middleware/**/* @src/config/**/*
EXPECTED: 生产代码 + 单元测试 + 集成测试
CONSTRAINTS: 遵循现有中间件模式" --tool qwen --mode write --rule development-implement-feature
```
### 5.1.4 规则模板
| 规则 | 用途 |
| --- | --- |
| **analysis-diagnose-bug-root-cause** | Bug 根因分析 |
| **analysis-analyze-code-patterns** | 代码模式分析 |
| **analysis-review-architecture** | 架构审查 |
| **analysis-assess-security-risks** | 安全评估 |
| **development-implement-feature** | 功能实现 |
| **development-refactor-codebase** | 代码重构 |
| **development-generate-tests** | 测试生成 |
--- ---
## 5.2 多模型协作 ## 5.2 多模型协作
### 5.2.1 模型选择指南 ### 5.2.1 协作模式
| 任务 | 推荐模型 | 理由 | 通过语义描述，可以让多个 AI 模型协同工作：
| 模式 | 描述方式 | 适用场景 |
| --- | --- | --- | | --- | --- | --- |
| **代码分析** | Gemini | 擅长深度代码理解和模式识别 | | **协作型** | "让 Gemini 和 Codex 共同分析架构问题" | 多角度分析同一问题 |
| **流水线型** | "Gemini 设计方案，Qwen 实现，Codex 审查" | 分阶段完成复杂任务 |
| **迭代型** | "用 Gemini 诊断问题，Codex 修复，迭代直到通过测试" | Bug 修复循环 |
| **并行型** | "让 Gemini 和 Qwen 分别给出优化建议" | 对比不同方案 |
### 5.2.2 语义示例
**协作分析**
```
用户：让 Gemini 和 Codex 共同分析 src/auth 模块的安全性和性能问题
AI：[自动调用两个模型，综合分析结果]
```
**流水线开发**
```
用户：我需要实现一个 WebSocket 实时通知功能。
请 Gemini 设计架构，Qwen 实现代码，最后用 Codex 审查。
AI：[依次调用三个模型，完成设计→实现→审查流程]
```
**迭代修复**
```
用户：测试失败了，用 Gemini 诊断原因，让 Qwen 修复，循环直到测试通过。
AI：[自动迭代诊断-修复流程，直到问题解决]
```
### 5.2.3 模型选择建议
| 任务类型 | 推荐模型 | 理由 |
| --- | --- | --- |
| **架构分析** | Gemini | 擅长深度理解和模式识别 |
| **Bug 诊断** | Gemini | 强大的根因分析能力 | | **Bug 诊断** | Gemini | 强大的根因分析能力 |
| **功能开发** | Qwen | 代码生成效率高 | | **代码生成** | Qwen | 代码生成效率高 |
| **代码审查** | Codex (GPT) | Git 集成好，审查格式标准 | | **代码审查** | Codex | Git 集成好，审查格式标准 |
| **长文本** | Claude | 上下文窗口大 | | **长文本处理** | Claude | 上下文窗口大 |
### 5.2.2 协作模式
#### 串行协作
```bash
# 步骤 1: Gemini 分析
ccw cli -p "分析代码架构" --tool gemini --mode analysis
# 步骤 2: Qwen 实现
ccw cli -p "基于分析结果实现功能" --tool qwen --mode write
# 步骤 3: Codex 审查
ccw cli -p "审查实现代码" --tool codex --mode review
```
#### 并行协作
使用 `--tool gemini` 和 `--tool qwen` 同时分析同一问题：
```bash
# 终端 1
ccw cli -p "从性能角度分析" --tool gemini --mode analysis &
# 终端 2
ccw cli -p "从安全角度分析" --tool codex --mode analysis &
```
### 5.2.3 会话恢复
跨模型会话恢复：
```bash
# 第一次调用
ccw cli -p "分析认证模块" --tool gemini --mode analysis
# 恢复会话继续
ccw cli -p "基于上次分析，设计改进方案" --tool qwen --mode write --resume
```
--- ---
## 5.3 Memory 管理 ## 5.3 智能记忆管理
### 5.3.1 Memory 分类 ### 5.3.1 记忆系统概述
| 分类 | 用途 | 示例内容 | CCW 的记忆系统是 **AI 自主管理** 的知识库，包括：
| 分类 | 用途 | 示例 |
| --- | --- | --- | | --- | --- | --- |
| **learnings** | 学习心得 | 新技术使用经验 | | **learnings** | 学习心得 | 新技术使用经验、最佳实践 |
| **decisions** | 架构决策 | 技术选型理由 | | **decisions** | 架构决策 | 技术选型理由、设计权衡 |
| **conventions** | 编码规范 | 命名约定、模式 | | **conventions** | 编码规范 | 命名约定、代码风格 |
| **issues** | 已知问题 | Bug、限制、TODO | | **issues** | 已知问题 | Bug 记录、限制说明 |
### 5.3.2 Memory 命令 ### 5.3.2 记忆的自动使用
| 命令 | 功能 | 示例 | AI 在执行任务时会自动检索和应用相关记忆：
| --- | --- | --- |
| **list** | 列出所有记忆 | `ccw memory list` |
| **search** | 搜索记忆 | `ccw memory search "认证"` |
| **export** | 导出记忆 | `ccw memory export <id>` |
| **import** | 导入记忆 | `ccw memory import "..."` |
| **embed** | 生成嵌入 | `ccw memory embed <id>` |
### 5.3.3 Memory 最佳实践
::: tip 提示
- **定期整理**: 每周整理一次 Memory，删除过时内容
- **结构化**: 使用标准格式，便于搜索和复用
- **上下文**: 记录决策背景，不只是结论
- **链接**: 相关内容互相引用
:::
### 5.3.4 Memory 模板
```markdown
## 标题
### 背景
- **问题**: ...
- **影响**: ...
### 决策
- **方案**: ...
- **理由**: ...
### 结果
- **效果**: ...
- **经验**: ...
### 相关
- [相关记忆 1](memory-id-1)
- [相关文档](link)
``` ```
用户：帮我实现用户认证模块
AI：[自动检索记忆中的认证相关 decisions 和 conventions]
根据之前的技术决策，我们使用 JWT + bcrypt 方案...
```
### 5.3.3 用户如何引导记忆
虽然 AI 自动管理记忆，但用户可以主动强化：
**明确要求记住**
```
用户：记住这个命名规范：所有 API 路由使用 kebab-case
AI：[将此规范存入 conventions 记忆]
```
**要求回顾决策**
```
用户：我们之前为什么选择 Redis 做缓存？
AI：[检索 decisions 记忆并回答]
```
**纠正错误记忆**
```
用户：之前的决定改了，我们现在用 PostgreSQL 代替 MongoDB
AI：[更新相关 decision 记忆]
```
### 5.3.4 记忆文件位置
- **全局记忆**: `~/.claude/projects/{project-name}/memory/`
- **项目记忆**: `.claude/memory/` 或 `MEMORY.md`
--- ---
## 5.4 CodexLens 高级用法 ## 5.4 Hook 自动化
### 5.4.1 混合搜索 ### 5.4.1 Hook 概念
结合向量搜索和关键词搜索： Hook 是 AI 执行任务前后的自动化流程，用户无需手动触发：
```bash
# 纯向量搜索
ccw search --mode vector "用户认证"
# 混合搜索（默认）
ccw search --mode hybrid "用户认证"
# 纯关键词搜索
ccw search --mode keyword "authenticate"
```
### 5.4.2 调用链追踪
追踪函数的完整调用链：
```bash
# 向上追踪（谁调用了我）
ccw search --trace-up "authenticateUser"
# 向下追踪（我调用了谁）
ccw search --trace-down "authenticateUser"
# 完整调用链
ccw search --trace-full "authenticateUser"
```
### 5.4.3 语义搜索技巧
| 技巧 | 示例 | 效果 |
| --- | --- | --- |
| **功能描述** | "处理用户登录" | 找到登录相关代码 |
| **问题描述** | "内存泄漏的地方" | 找到潜在问题 |
| **模式描述** | "单例模式的实现" | 找到设计模式 |
| **技术描述** | "使用 React Hooks" | 找到相关用法 |
---
## 5.5 Hook 自动注入
### 5.5.1 Hook 类型
| Hook 类型 | 触发时机 | 用途 | | Hook 类型 | 触发时机 | 用途 |
| --- | --- | --- | | --- | --- | --- |
| **pre-command** | 命令执行前 | 注入规范、加载上下文 | | **pre-command** | AI 思考前 | 加载项目规范、检索记忆 |
| **post-command** | 命令执行后 | 保存 Memory、更新状态 | | **post-command** | AI 完成后 | 保存决策、更新索引 |
| **pre-commit** | Git 提交前 | 代码审查、规范检查 | | **pre-commit** | Git 提交前 | 代码审查、规范检查 |
| **file-change** | 文件变更时 | 自动格式化、更新索引 |
### 5.5.2 Hook 配置 ### 5.4.2 配置示例
在 `.claude/hooks.json` 中配置： 在 `.claude/hooks.json` 中配置：
@@ -258,19 +183,14 @@ ccw search --trace-full "authenticateUser"
{ {
"pre-command": [ "pre-command": [
{ {
"name": "inject-specs", "name": "load-project-specs",
"description": "注入项目规范", "description": "加载项目规范",
"command": "cat .workflow/specs/project-constraints.md" "command": "cat .workflow/specs/project-constraints.md"
},
{
"name": "load-memory",
"description": "加载相关 Memory",
"command": "ccw memory search \"{query}\""
} }
], ],
"post-command": [ "post-command": [
{ {
"name": "save-memory", "name": "save-decisions",
"description": "保存重要决策", "description": "保存重要决策",
"command": "ccw memory import \"{content}\"" "command": "ccw memory import \"{content}\""
} }
@@ -280,49 +200,54 @@ ccw search --trace-full "authenticateUser"
--- ---
## 5.6 性能优化 ## 5.5 ACE 语义搜索
### 5.6.1 索引优化 ### 5.5.1 什么是 ACE
| 优化项 | 说明 | ACE (Augment Context Engine) 是 AI 的 **代码感知能力**，让 AI 能理解整个代码库的语义。
### 5.5.2 AI 如何使用 ACE
当用户提问时，AI 会自动使用 ACE 搜索相关代码：
```
用户：认证流程是怎么实现的？
AI：[通过 ACE 语义搜索 auth 相关代码]
根据代码分析，认证流程是...
```
### 5.5.3 配置参考
| 配置方式 | 链接 |
| --- | --- | | --- | --- |
| **增量索引** | 只索引变更文件 | | **官方文档** | [Augment MCP Documentation](https://docs.augmentcode.com/context-services/mcp/overview) |
| **并行索引** | 多进程并行处理 | | **代理工具** | [ace-tool (GitHub)](https://github.com/eastxiaodong/ace-tool) |
| **缓存策略** | 向量嵌入缓存 |
### 5.6.2 搜索优化
| 优化项 | 说明 |
| --- | --- |
| **结果缓存** | 相同查询返回缓存 |
| **分页加载** | 大结果集分页返回 |
| **智能去重** | 相似结果自动去重 |
--- ---
## 5.7 快速参考 ## 5.6 语义提示速查
### CLI 命令速查 ### 常用语义模式
| 命令 | 功能 | | 目标 | 语义描述示例 |
| --- | --- | | --- | --- |
| `ccw cli -p "..." --tool gemini --mode analysis` | 分析任务 | | **分析代码** | "用 Gemini 分析 src/auth 的架构设计" |
| `ccw cli -p "..." --tool qwen --mode write` | 实现任务 | | **安全审计** | "用 Gemini 扫描安全漏洞，重点关注 OWASP Top 10" |
| `ccw cli -p "..." --tool codex --mode review` | 审查任务 | | **实现功能** | "让 Qwen 实现一个带缓存的用户仓库" |
| `ccw memory list` | 列出记忆 | | **代码审查** | "用 Codex 审查最近的改动" |
| `ccw memory search "..."` | 搜索记忆 | | **Bug 诊断** | "用 Gemini 分析这个内存泄漏的根因" |
| `ccw search "..."` | 语义搜索 | | **多模型协作** | "Gemini 设计方案，Qwen 实现，Codex 审查" |
| `ccw search --trace "..."` | 调用链追踪 | | **记住规范** | "记住：所有 API 使用 RESTful 风格" |
| **回顾决策** | "我们之前为什么选择这个技术栈？" |
### 规则模板速查 ### 协作模式速查
| 规则 | 用途 | | 模式 | 语义示例 |
| --- | --- | | --- | --- |
| `analysis-diagnose-bug-root-cause` | Bug 分析 | | **协作** | "让 Gemini 和 Codex 共同分析..." |
| `analysis-assess-security-risks` | 安全评估 | | **流水线** | "Gemini 设计，Qwen 实现，Codex 审查" |
| `development-implement-feature` | 功能实现 | | **迭代** | "诊断并修复，直到测试通过" |
| `development-refactor-codebase` | 代码重构 | | **并行** | "让多个模型分别给出建议" |
| `development-generate-tests` | 测试生成 |
--- ---

17
docs/zh/reference/commands-skills.md
View File

@@ -4,23 +4,6 @@
--- ---
## 目录
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-能力)
---
## 快速参考表 ## 快速参考表
### 命令快速参考 ### 命令快速参考

596
docs/zh/skills/claude-collaboration.md
View File

@@ -13,27 +13,78 @@
| **协作流程割裂** | 团队成员各自为战 | 统一消息总线、共享状态、进度同步 | | **协作流程割裂** | 团队成员各自为战 | 统一消息总线、共享状态、进度同步 |
| **资源浪费** | 重复上下文加载 | Wisdom 累积、探索缓存、产物复用 | | **资源浪费** | 重复上下文加载 | Wisdom 累积、探索缓存、产物复用 |
## Skills 列表 ---
| Skill | 功能 | 触发方式 | ## Skills 总览
| Skill | 功能 | 适用场景 |
| --- | --- | --- | | --- | --- | --- |
| `team-coordinate` | 通用团队协调器（动态角色生成） | `/team-coordinate` | | `team-coordinate-v2` | 通用团队协调器（动态角色生成） | 任意复杂任务 |
| `team-lifecycle-v5` | 全生命周期团队（规范→实现→测试→审查） | `/team-lifecycle` | | `team-lifecycle-v5` | 全生命周期团队（规范→实现→测试） | 完整功能开发 |
| `team-planex` | 规划-执行流水线（边规划边执行） | `/team-planex` | | `team-planex` | 规划-执行流水线 | Issue 批处理 |
| `team-review` | 代码审查团队（扫描→审查→修复） | `/team-review` | | `team-review` | 代码审查团队 | 代码审查、漏洞扫描 |
| `team-testing` | 测试团队（策略→生成→执行→分析） | `/team-testing` | | `team-testing` | 测试团队 | 测试覆盖、用例生成 |
| `team-arch-opt` | 架构优化团队 | 重构、架构分析 |
| `team-perf-opt` | 性能优化团队 | 性能调优、瓶颈分析 |
| `team-brainstorm` | 头脑风暴团队 | 多角度分析、创意生成 |
| `team-frontend` | 前端开发团队 | UI 开发、设计系统 |
| `team-uidesign` | UI 设计团队 | 设计系统、组件规范 |
| `team-issue` | Issue 处理团队 | Issue 分析、实现 |
| `team-iterdev` | 迭代开发团队 | 增量交付、敏捷开发 |
| `team-quality-assurance` | 质量保证团队 | 质量扫描、缺陷管理 |
| `team-roadmap-dev` | 路线图开发团队 | 分阶段开发、里程碑 |
| `team-tech-debt` | 技术债务团队 | 债务清理、代码治理 |
| `team-ultra-analyze` | 深度分析团队 | 复杂问题分析、协作探索 |
| `team-executor-v2` | 轻量执行器 | 会话恢复、纯执行 |
---
## 核心架构
所有 Team Skills 共享统一的 **team-worker agent 架构**：
```
┌──────────────────────────────────────────────────────────┐
│ Skill(skill="team-xxx", args="任务描述") │
└────────────────────────┬─────────────────────────────────┘
│ Role Router
┌──── --role present? ────┐
│ NO │ YES
↓ ↓
Orchestration Mode Role Dispatch
(auto → coordinator) (route to role.md)
│
┌─────────┴─────────┬───────────────┬──────────────┐
↓ ↓ ↓ ↓
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
│ coord │ │worker 1│ │worker 2│ │worker N│
│ (编排) │ │(执行) │ │(执行) │ │(执行) │
└────────┘ └────────┘ └────────┘ └────────┘
│ │ │ │
└───────────────────┴───────────────┴──────────────┘
│
Message Bus (消息总线)
```
**核心组件**:
- **Coordinator**: 内置编排器，负责任务分析、派发、监控
- **Team-Worker Agent**: 统一代理，加载 role-spec 执行角色逻辑
- **Role Router**: `--role=xxx` 参数路由到角色执行
- **Message Bus**: 团队成员间通信协议
- **Shared Memory**: 跨任务知识累积 (Wisdom)
---
## Skills 详解 ## Skills 详解
### team-coordinate ### team-coordinate-v2
**一句话定位**: 通用团队协调器 — 根据任务分析动态生成角色并编排执行 **一句话定位**: 通用团队协调器 — 根据任务分析动态生成角色并编排执行
**触发**: **触发**:
``` ```bash
/team-coordinate <task-description> team-coordinate <task-description>
/team-coordinate --role=coordinator <task> team-coordinate --role=coordinator <task>
/team-coordinate --role=<worker> --session=<path>
``` ```
**功能**: **功能**:
@@ -42,17 +93,6 @@
- Fast-Advance 机制跳过协调器直接派生后继任务 - Fast-Advance 机制跳过协调器直接派生后继任务
- Wisdom 累积跨任务知识 - Wisdom 累积跨任务知识
**角色注册表**:
| 角色 | 文件 | 任务前缀 | 类型 |
|------|------|----------|------|
| coordinator | roles/coordinator/role.md | (无) | 编排器 |
| (动态) | `<session>/roles/<role>.md` | (动态) | 工作者 |
**流水线**:
```
任务分析 → 生成角色 → 初始化会话 → 创建任务链 → 派生首批工作者 → 循环推进 → 完成报告
```
**会话目录**: **会话目录**:
``` ```
.workflow/.team/TC-<slug>-<date>/ .workflow/.team/TC-<slug>-<date>/
@@ -61,8 +101,6 @@
├── roles/ # 动态角色定义 ├── roles/ # 动态角色定义
├── artifacts/ # 所有 MD 交付产物 ├── artifacts/ # 所有 MD 交付产物
├── wisdom/ # 跨任务知识 ├── wisdom/ # 跨任务知识
├── explorations/ # 共享探索缓存
├── discussions/ # 内联讨论记录
└── .msg/ # 团队消息总线日志 └── .msg/ # 团队消息总线日志
``` ```
@@ -73,8 +111,8 @@
**一句话定位**: 全生命周期团队 — 从规范到实现到测试到审查的完整流水线 **一句话定位**: 全生命周期团队 — 从规范到实现到测试到审查的完整流水线
**触发**: **触发**:
``` ```bash
/team-lifecycle <task-description> team-lifecycle <task-description>
``` ```
**功能**: **功能**:
@@ -92,164 +130,67 @@
| executor | role-specs/executor.md | IMPL-* | true | | executor | role-specs/executor.md | IMPL-* | true |
| tester | role-specs/tester.md | TEST-* | false | | tester | role-specs/tester.md | TEST-* | false |
| reviewer | role-specs/reviewer.md | REVIEW-* | false | | reviewer | role-specs/reviewer.md | REVIEW-* | false |
| architect | role-specs/architect.md | ARCH-* | false |
| fe-developer | role-specs/fe-developer.md | DEV-FE-* | false |
| fe-qa | role-specs/fe-qa.md | QA-FE-* | false |
**流水线定义**: **流水线定义**:
``` ```
规范流水线 (6 任务): 规范流水线: RESEARCH → DRAFT → QUALITY
RESEARCH-001 → DRAFT-001 → DRAFT-002 → DRAFT-003 → DRAFT-004 → QUALITY-001 实现流水线: PLAN → IMPL → TEST + REVIEW
全生命周期: [规范流水线] → [实现流水线]
实现流水线 (4 任务):
PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
全生命周期 (10 任务):
[规范流水线] → PLAN-001 → IMPL-001 → TEST-001 + REVIEW-001
前端流水线:
PLAN-001 → DEV-FE-001 → QA-FE-001 (GC 循环，最多 2 轮)
``` ```
**质量关卡** (QUALITY-001 完成后):
```
═════════════════════════════════════════
SPEC PHASE COMPLETE
Quality Gate: <PASS|REVIEW|FAIL> (<score>%)
Dimension Scores:
Completeness: <bar> <n>%
Consistency: <bar> <n>%
Traceability: <bar> <n>%
Depth: <bar> <n>%
Coverage: <bar> <n>%
Available Actions:
resume -> Proceed to implementation
improve -> Auto-improve weakest dimension
improve <dimension> -> Improve specific dimension
revise <TASK-ID> -> Revise specific document
recheck -> Re-run quality check
feedback <text> -> Inject feedback, create revision
═════════════════════════════════════════
```
**用户命令** (唤醒暂停的协调器):
| 命令 | 动作 |
|------|------|
| `check` / `status` | 输出执行状态图，不推进 |
| `resume` / `continue` | 检查工作者状态，推进下一步 |
| `revise <TASK-ID> [feedback]` | 创建修订任务 + 级联下游 |
| `feedback <text>` | 分析反馈影响，创建定向修订链 |
| `recheck` | 重新运行 QUALITY-001 质量检查 |
| `improve [dimension]` | 自动改进 readiness-report 中最弱维度 |
--- ---
### team-planex ### team-planex
**一句话定位**: 边规划边执行团队 — 通过逐 Issue 节拍流水线实现 planner 和 executor 并行工作 **一句话定位**: 边规划边执行团队 — 逐 Issue 节拍流水线
**触发**: **触发**:
``` ```bash
/team-planex <task-description> team-planex <task-description>
/team-planex --role=planner <input> team-planex --role=planner <input>
/team-planex --role=executor --input <solution-file> team-planex --role=executor --input <solution-file>
``` ```
**功能**: **功能**:
- 2 成员团队（planner + executor），planner 担任 lead 角色 - 2 成员团队（planner + executor），planner 担任 lead 角色
- 逐 Issue 节拍：planner 每完成一个 issue 的 solution 后立即创建 EXEC-* 任务 - 逐 Issue 节拍：planner 完成后立即创建 EXEC-* 任务
- Solution 写入中间产物文件，executor 从文件加载 - Solution 写入中间产物文件，executor 从文件加载
- 支持多种执行后端（agent/codex/gemini）
**角色注册表**: **Wave Pipeline**:
| 角色 | 文件 | 任务前缀 | 类型 |
|------|------|----------|------|
| planner | roles/planner.md | PLAN-* | pipeline (lead) |
| executor | roles/executor.md | EXEC-* | pipeline |
**输入类型**:
| 输入类型 | 格式 | 示例 |
|----------|------|------|
| Issue IDs | 直接传入 ID | `--role=planner ISS-20260215-001 ISS-20260215-002` |
| 需求文本 | `--text '...'` | `--role=planner --text '实现用户认证模块'` |
| Plan 文件 | `--plan path` | `--role=planner --plan plan/2026-02-15-auth.md` |
**Wave Pipeline** (逐 Issue 节拍):
``` ```
Issue 1: planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready Issue 1: planner 规划 → 写产物 → 创建 EXEC-* → executor 执行
↓ (executor 立即开始) Issue 2: planner 规划 → 写产物 → 创建 EXEC-* → executor 并行消费
Issue 2: planner 规划 solution → 写中间产物 → 冲突检查 → 创建 EXEC-* → issue_ready Final: planner 发送 all_planned → executor 完成剩余 → 结束
↓ (executor 并行消费)
Issue N: ...
Final: planner 发送 all_planned → executor 完成剩余 EXEC-* → 结束
``` ```
**执行方法选择**:
| 执行器 | 后端 | 适用场景 |
|--------|------|----------|
| `agent` | code-developer subagent | 简单任务、同步执行 |
| `codex` | `ccw cli --tool codex --mode write` | 复杂任务、后台执行 |
| `gemini` | `ccw cli --tool gemini --mode write` | 分析类任务、后台执行 |
**用户命令**:
| 命令 | 动作 |
|------|------|
| `check` / `status` | 输出执行状态图，不推进 |
| `resume` / `continue` | 检查工作者状态，推进下一步 |
| `add <issue-ids or --text '...' or --plan path>` | 追加新任务到 planner 队列 |
--- ---
### team-review ### team-review
**一句话定位**: 代码审查团队 — 统一的代码扫描、漏洞审查、优化建议和自动修复 **一句话定位**: 代码审查团队 — 统一的代码扫描、漏洞审查、自动修复
**触发**: **触发**:
```bash
team-review <target-path>
team-review --full <target-path> # scan + review + fix
team-review --fix <review-files> # fix only
team-review -q <target-path> # quick scan only
``` ```
/team-review <target-path>
/team-review --full <target-path> # scan + review + fix
/team-review --fix <review-files> # fix only
/team-review -q <target-path> # quick scan only
```
**功能**:
- 4 角色团队（coordinator, scanner, reviewer, fixer）
- 多维度审查：安全性、正确性、性能、可维护性
- 自动修复循环（审查 → 修复 → 验证）
**角色注册表**: **角色注册表**:
| 角色 | 文件 | 任务前缀 | 类型 | | 角色 | 任务前缀 | 类型 |
|------|------|----------|------| |------|----------|------|
| coordinator | roles/coordinator/role.md | RC-* | 编排器 | | coordinator | RC-* | 编排器 |
| scanner | roles/scanner/role.md | SCAN-* | 只读分析 | | scanner | SCAN-* | 只读分析 |
| reviewer | roles/reviewer/role.md | REV-* | 只读分析 | | reviewer | REV-* | 只读分析 |
| fixer | roles/fixer/role.md | FIX-* | 代码生成 | | fixer | FIX-* | 代码生成 |
**流水线** (CP-1 Linear): **流水线**:
``` ```
coordinator dispatch SCAN-* (扫描) → REV-* (审查) → [用户确认] → FIX-* (修复)
→ SCAN-* (scanner: 工具链 + LLM 扫描)
→ REV-* (reviewer: 深度分析 + 报告)
→ [用户确认]
→ FIX-* (fixer: 规划 + 执行 + 验证)
``` ```
**检查点**: **审查维度**: 安全性、正确性、性能、可维护性
| 触发 | 位置 | 行为 |
|------|------|------|
| Review→Fix 过渡 | REV-* 完成 | 暂停，展示审查报告，等待用户 `resume` 确认修复 |
| 快速模式 (`-q`) | SCAN-* 后 | 流水线在扫描后结束，无审查/修复 |
| 仅修复模式 (`--fix`) | 入口 | 跳过扫描/审查，直接进入 fixer |
**审查维度**:
| 维度 | 检查点 |
|------|--------|
| 安全性 (sec) | 注入漏洞、敏感信息泄露、权限控制 |
| 正确性 (cor) | 边界条件、错误处理、类型安全 |
| 性能 (perf) | 算法复杂度、I/O 优化、资源使用 |
| 可维护性 (maint) | 代码结构、命名规范、注释质量 |
--- ---
@@ -258,75 +199,318 @@ coordinator dispatch
**一句话定位**: 测试团队 — 通过 Generator-Critic 循环实现渐进式测试覆盖 **一句话定位**: 测试团队 — 通过 Generator-Critic 循环实现渐进式测试覆盖
**触发**: **触发**:
```bash
team-testing <task-description>
``` ```
/team-testing <task-description>
```
**功能**:
- 5 角色团队（coordinator, strategist, generator, executor, analyst）
- 三种流水线：Targeted、Standard、Comprehensive
- Generator-Critic 循环自动改进测试覆盖率
**角色注册表**: **角色注册表**:
| 角色 | 文件 | 任务前缀 | 类型 | | 角色 | 任务前缀 | 类型 |
|------|------|----------|------| |------|----------|------|
| coordinator | roles/coordinator.md | (无) | 编排器 | | coordinator | (无) | 编排器 |
| strategist | roles/strategist.md | STRATEGY-* | pipeline | | strategist | STRATEGY-* | pipeline |
| generator | roles/generator.md | TESTGEN-* | pipeline | | generator | TESTGEN-* | pipeline |
| executor | roles/executor.md | TESTRUN-* | pipeline | | executor | TESTRUN-* | pipeline |
| analyst | roles/analyst.md | TESTANA-* | pipeline | | analyst | TESTANA-* | pipeline |
**三种流水线**: **三种流水线**:
``` ```
Targeted (小范围变更): Targeted: STRATEGY → TESTGEN(L1) → TESTRUN
STRATEGY-001 → TESTGEN-001(L1 unit) → TESTRUN-001 Standard: STRATEGY → TESTGEN(L1) → TESTRUN → TESTGEN(L2) → TESTRUN → TESTANA
Comprehensive: STRATEGY → [TESTGEN(L1+L2) 并行] → [TESTRUN 并行] → TESTGEN(L3) → TESTRUN → TESTANA
Standard (渐进式):
STRATEGY-001 → TESTGEN-001(L1) → TESTRUN-001(L1) → TESTGEN-002(L2) → TESTRUN-002(L2) → TESTANA-001
Comprehensive (完整覆盖):
STRATEGY-001 → [TESTGEN-001(L1) + TESTGEN-002(L2)](并行) → [TESTRUN-001(L1) + TESTRUN-002(L2)](并行) → TESTGEN-003(L3) → TESTRUN-003(L3) → TESTANA-001
``` ```
**Generator-Critic 循环**: **测试层**: L1: Unit (80%) → L2: Integration (60%) → L3: E2E (40%)
```
TESTGEN → TESTRUN → (如果覆盖率 < 目标) → TESTGEN-fix → TESTRUN-2 ---
(如果覆盖率 >= 目标) → 下一层或 TESTANA
### team-arch-opt
**一句话定位**: 架构优化团队 — 分析架构问题、设计重构策略、实施改进
**触发**:
```bash
team-arch-opt <task-description>
``` ```
**测试层定义**: **角色注册表**:
| 层级 | 覆盖目标 | 示例 | | 角色 | 任务前缀 | 功能 |
|------|----------|------| |------|----------|------|
| L1: Unit | 80% | 单元测试、函数级测试 | | coordinator | (无) | 编排器 |
| L2: Integration | 60% | 集成测试、模块间交互 | | analyzer | ANALYZE-* | 架构分析 |
| L3: E2E | 40% | 端到端测试、用户场景 | | designer | DESIGN-* | 重构设计 |
| refactorer | REFACT-* | 实施重构 |
| validator | VALID-* | 验证改进 |
| reviewer | REVIEW-* | 代码审查 |
**共享内存** (shared-memory.json): **检测范围**: 依赖循环、耦合/内聚、分层违规、上帝类、死代码
| 角色 | 字段 |
---
### team-perf-opt
**一句话定位**: 性能优化团队 — 性能分析、瓶颈识别、优化实施
**触发**:
```bash
team-perf-opt <task-description>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 编排器 |
| profiler | PROFILE-* | 性能分析 |
| strategist | STRAT-* | 优化策略 |
| optimizer | OPT-* | 实施优化 |
| benchmarker | BENCH-* | 基准测试 |
| reviewer | REVIEW-* | 代码审查 |
---
### team-brainstorm
**一句话定位**: 头脑风暴团队 — 多角度创意分析、Generator-Critic 循环
**触发**:
```bash
team-brainstorm <topic>
team-brainstorm --role=ideator <topic>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 编排器 |
| ideator | IDEA-* | 创意生成 |
| challenger | CHALLENGE-* | 批判质疑 |
| synthesizer | SYNTH-* | 综合整合 |
| evaluator | EVAL-* | 评估评分 |
---
### team-frontend
**一句话定位**: 前端开发团队 — 内置 ui-ux-pro-max 设计智能
**触发**:
```bash
team-frontend <task-description>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 编排器 |
| analyst | ANALYZE-* | 需求分析 |
| architect | ARCH-* | 架构设计 |
| developer | DEV-* | 前端实现 |
| qa | QA-* | 质量保证 |
---
### team-uidesign
**一句话定位**: UI 设计团队 — 设计系统分析、Token 定义、组件规范
**触发**:
```bash
team-uidesign <task>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 编排器 |
| researcher | RESEARCH-* | 设计研究 |
| designer | DESIGN-* | 设计定义 |
| reviewer | AUDIT-* | 无障碍审计 |
| implementer | BUILD-* | 代码实现 |
---
### team-issue
**一句话定位**: Issue 处理团队 — Issue 处理流水线
**触发**:
```bash
team-issue <issue-ids>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 编排器 |
| explorer | EXPLORE-* | 代码探索 |
| planner | PLAN-* | 方案规划 |
| implementer | IMPL-* | 代码实现 |
| reviewer | REVIEW-* | 代码审查 |
| integrator | INTEG-* | 集成验证 |
---
### team-iterdev
**一句话定位**: 迭代开发团队 — Generator-Critic 循环、增量交付
**触发**:
```bash
team-iterdev <task-description>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 编排器 |
| architect | ARCH-* | 架构设计 |
| developer | DEV-* | 功能开发 |
| tester | TEST-* | 测试验证 |
| reviewer | REVIEW-* | 代码审查 |
**特点**: Developer-Reviewer 循环（最多 3 轮），Task Ledger 实时进度
---
### team-quality-assurance
**一句话定位**: 质量保证团队 — Issue 发现 + 测试验证闭环
**触发**:
```bash
team-quality-assurance <task-description>
team-qa <task-description>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 编排器 |
| scout | SCOUT-* | 问题发现 |
| strategist | QASTRAT-* | 策略制定 |
| generator | QAGEN-* | 测试生成 |
| executor | QARUN-* | 测试执行 |
| analyst | QAANA-* | 结果分析 |
---
### team-roadmap-dev
**一句话定位**: 路线图开发团队 — 分阶段开发、里程碑管理
**触发**:
```bash
team-roadmap-dev <task-description>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 人机交互 |
| planner | PLAN-* | 阶段规划 |
| executor | EXEC-* | 阶段执行 |
| verifier | VERIFY-* | 阶段验证 |
---
### team-tech-debt
**一句话定位**: 技术债务团队 — 债务扫描、评估、清理、验证
**触发**:
```bash
team-tech-debt <task-description>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 编排器 |
| scanner | TDSCAN-* | 债务扫描 |
| assessor | TDEVAL-* | 量化评估 |
| planner | TDPLAN-* | 治理规划 |
| executor | TDFIX-* | 清理执行 |
| validator | TDVAL-* | 验证回归 |
---
### team-ultra-analyze
**一句话定位**: 深度分析团队 — 多角色协作探索、渐进式理解
**触发**:
```bash
team-ultra-analyze <topic>
team-analyze <topic>
```
**角色注册表**:
| 角色 | 任务前缀 | 功能 |
|------|----------|------|
| coordinator | (无) | 编排器 |
| explorer | EXPLORE-* | 代码探索 |
| analyst | ANALYZE-* | 深度分析 |
| discussant | DISCUSS-* | 讨论交互 |
| synthesizer | SYNTH-* | 综合输出 |
**特点**: 支持 Quick/Standard/Deep 三种深度模式
---
### team-executor-v2
**一句话定位**: 轻量执行器 — 恢复会话、纯执行模式
**触发**:
```bash
team-executor --session=<path>
```
**功能**:
- 无分析、无角色生成 — 仅加载并执行现有会话
- 用于恢复中断的 team-coordinate 会话
---
## 用户命令
所有 Team Skills 支持统一的用户命令（唤醒暂停的协调器）：
| 命令 | 动作 |
|------|------| |------|------|
| strategist | `test_strategy` | | `check` / `status` | 输出执行状态图，不推进 |
| generator | `generated_tests` | | `resume` / `continue` | 检查工作者状态，推进下一步 |
| executor | `execution_results`, `defect_patterns` | | `revise <TASK-ID>` | 创建修订任务 + 级联下游 |
| analyst | `analysis_report`, `coverage_history` | | `feedback <text>` | 分析反馈影响，创建定向修订链 |
---
## 最佳实践
1. **选择合适的团队类型**:
- 通用任务 → `team-coordinate-v2`
- 完整功能开发 → `team-lifecycle-v5`
- Issue 批处理 → `team-planex`
- 代码审查 → `team-review`
- 测试覆盖 → `team-testing`
- 架构优化 → `team-arch-opt`
- 性能调优 → `team-perf-opt`
- 头脑风暴 → `team-brainstorm`
- 前端开发 → `team-frontend`
- UI 设计 → `team-uidesign`
- 技术债务 → `team-tech-debt`
- 深度分析 → `team-ultra-analyze`
2. **利用内循环角色**: 设置 `inner_loop: true` 让单个工作者处理多个同前缀任务
3. **Wisdom 累积**: 团队会话中的所有角色都会累积知识到 `wisdom/` 目录
4. **Fast-Advance**: 简单线性后继任务会自动跳过协调器直接派生
5. **断点恢复**: 所有团队技能支持会话恢复，通过 `--resume` 或 `resume` 命令继续
---
## 相关命令 ## 相关命令
- [Claude Commands - Workflow](../commands/claude/workflow.md) - [Claude Commands - Workflow](../commands/claude/workflow.md)
- [Claude Commands - Session](../commands/claude/session.md) - [Claude Commands - Session](../commands/claude/session.md)
## 最佳实践
1. **选择合适的团队类型**:
- 通用任务 → `team-coordinate`
- 完整功能开发 → `team-lifecycle`
- Issue 批处理 → `team-planex`
- 代码审查 → `team-review`
- 测试覆盖 → `team-testing`
2. **利用内循环角色**: 对于有多个同前缀串行任务的角色，设置 `inner_loop: true` 让单个工作者处理全部任务，避免重复派生开销
3. **Wisdom 累积**: 团队会话中的所有角色都会累积知识到 `wisdom/` 目录，后续任务可复用这些模式、决策和约定
4. **Fast-Advance**: 简单线性后继任务会自动跳过协调器直接派生，减少协调开销
5. **断点恢复**: 所有团队技能支持会话恢复，通过 `--resume` 或用户命令 `resume` 继续中断的会话