diff --git a/docs/.vitepress/theme/components/ProfessionalHome.vue b/docs/.vitepress/theme/components/ProfessionalHome.vue index 7016320b..d3da47ea 100644 --- a/docs/.vitepress/theme/components/ProfessionalHome.vue +++ b/docs/.vitepress/theme/components/ProfessionalHome.vue @@ -4,10 +4,6 @@
-
- - {{ t.badge }} -

{{ t.heroSubtitle }}

@@ -154,7 +150,7 @@ workflow.json
- 
{{ workflowJson }}
+
@@ -446,19 +442,59 @@ const sequence = [ ] const currentStep = computed(() => sequence[currentTick.value]) -const workflowJson = `{ - "project": "next-gen-api", - "cadence": "strict-sync", - "team": { - "arch": { "cli": "gemini" }, - "coder": { "cli": "qwen" }, - "audit": { "cli": "codex" } - }, - "stages": [ - { "id": "design", "agent": "arch" }, - { "id": "impl", "agent": "coder" } +// JSON with syntax highlighting and tooltips +const jsonTooltips = { + 'project': '项目名称，用于标识工作流实例', + 'cadence': '节拍模式：strict-sync(严格同步) | async(异步) | hybrid(混合)', + 'team': '团队成员配置，每个角色映射到特定 CLI 工具', + 'arch': '架构师角色：负责系统设计和文档生成', + 'coder': '开发者角色：负责代码实现', + 'audit': '审计员角色：负责质量检查和代码审查', + 'cli': 'CLI 工具：gemini | qwen | codex | claude', + 'stages': '执行阶段定义，按顺序执行', + 'id': '阶段唯一标识符', + 'agent': '执行该阶段的团队成员角色' +} + +const highlightedWorkflowJson = computed(() => { + const lines = [ + { text: '{', type: 'bracket' }, + { text: ' "project": "next-gen-api",', key: 'project', type: 'string' }, + { text: ' "cadence": "strict-sync",', key: 'cadence', type: 'string' }, + { text: ' "team": {', key: 'team', type: 'object' }, + { text: ' "arch": { "cli": "gemini" },', key: 'arch', type: 'object' }, + { text: ' "coder": { "cli": "qwen" },', key: 'coder', type: 'object' }, + { text: ' "audit": { "cli": "codex" }', key: 'audit', type: 'object' }, + { text: ' },', type: 'bracket' }, + { text: ' "stages": [', key: 'stages', type: 'array' }, + { text: ' { "id": "design", "agent": "arch" },', type: 'object' }, + { text: ' { "id": "impl", "agent": "coder" }', type: 'object' }, + { text: ' ]', type: 'bracket' }, + { text: '}', type: 'bracket' } ] -}` + + return lines.map(line => { + if (line.key && jsonTooltips[line.key]) { + const tooltip = jsonTooltips[line.key] + const highlighted = line.text + .replace(/"([^"]+)":/g, '"$1":') + .replace(/: "([^"]+)"/g, ': "$1"') + .replace(/: \[/g, ': [') + .replace(/\]/g, ']') + .replace(/: \{/g, ': {') + .replace(/\}/g, '}') + return `${highlighted}` + } + const highlighted = line.text + .replace(/"([^"]+)":/g, '"$1":') + .replace(/: "([^"]+)"/g, ': "$1"') + .replace(/\[/g, '[') + .replace(/\]/g, ']') + .replace(/\{/g, '{') + .replace(/\}/g, '}') + return `${highlighted}` + }).join('\n') +}) let terminalInterval, pipelineInterval @@ -885,7 +921,51 @@ onUnmounted(() => { border-radius: 16px; padding: 1.5rem; border: 1px solid rgba(255,255,255,0.08); + overflow: hidden; } +.json-pre { + margin: 0; + color: #e2e8f0; + font-size: 0.875rem; + line-height: 1.7; + white-space: pre; + overflow-x: auto; +} +.json-line { + display: block; + cursor: default; + transition: background 0.2s ease; + padding: 2px 8px; + margin: 0 -8px; + border-radius: 4px; +} +.json-line[title]:hover { + background: rgba(99, 102, 241, 0.15); + position: relative; +} +.json-line[title]:hover::after { + content: attr(title); + position: absolute; + left: calc(100% + 16px); + top: 50%; + transform: translateY(-50%); + background: #1e293b; + color: #e2e8f0; + padding: 8px 12px; + border-radius: 8px; + font-size: 0.75rem; + white-space: nowrap; + max-width: 280px; + white-space: normal; + box-shadow: 0 4px 12px rgba(0,0,0,0.3); + border: 1px solid rgba(255,255,255,0.1); + z-index: 10; + pointer-events: none; +} +.json-key { color: #7dd3fc; font-weight: 500; } +.json-string { color: #a5f3fc; } +.json-bracket { color: #94a3b8; } +.json-number { color: #fbbf24; } .code-header { display: flex; align-items: center; diff --git a/docs/features/dashboard.md b/docs/features/dashboard.md index 8b2c1f7c..7bc36d94 100644 --- a/docs/features/dashboard.md +++ b/docs/features/dashboard.md @@ -1,8 +1,8 @@ -# Dashboard Panel +# Dashboard ## One-Liner -**The Dashboard is a VS Code webview-based management interface** — Provides visual access to project configuration, specs, memory, and settings through an intuitive GUI. +**The Dashboard provides an at-a-glance overview of your project's workflow status, statistics, and recent activity through an intuitive widget-based interface.** --- @@ -10,10 +10,48 @@ | Pain Point | Current State | Dashboard Solution | |------------|---------------|-------------------| -| **Config complexity** | JSON files hard to edit | Visual form-based editing | -| **No overview** | Can't see project state at a glance | Unified dashboard view | -| **Scattered settings** | Settings in multiple files | Centralized management | -| **No visual feedback** | CLI only, no UI | Interactive webview | +| **No project visibility** | Can't see overall project health | Project info banner with tech stack and development index | +| **Scattered metrics** | Stats across multiple locations | Centralized statistics with sparklines | +| **Unknown workflow status** | Hard to track session progress | Pie chart with status breakdown | +| **Lost in recent work** | No quick access to active sessions | Session carousel with task details | +| **Indexing status unclear** | Don't know if code is indexed | Real-time index status indicator | + +--- + +## Page Overview + +**Location**: `ccw/frontend/src/pages/HomePage.tsx` + +**Purpose**: Dashboard home page providing project overview, statistics, workflow status, and recent activity monitoring. + +**Access**: Navigation → Dashboard (default home page) + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Dashboard Header (title + refresh) | ++--------------------------------------------------------------------------+ +| WorkflowTaskWidget (Combined Card) | +| +--------------------------------------------------------------------+ | +| | Project Info Banner (expandable) | | +| | - Project name, description, tech stack badges | | +| | - Quick stats (features, bugfixes, enhancements) | | +| | - Index status indicator | | +| +----------------------------------+---------------------------------+ | +| | Stats Section | Workflow Status | Task Details (Carousel) | | +| | - 6 mini cards | - Pie chart | - Session nav | | +| | - Sparklines | - Legend | - Task list (2 columns) | | +| +----------------+-----------------+-------------------------------+ | ++--------------------------------------------------------------------------+ +| RecentSessionsWidget | +| +--------------------------------------------------------------------+ | +| | Tabs: All Tasks | Workflow | Lite Tasks | | +| | +---------------+---------------+-------------------------------+ | | +| | | Task cards with status, progress, tags, time | | | +| | +---------------------------------------------------------------+ | | ++--------------------------------------------------------------------------+ +``` --- @@ -21,59 +59,94 @@ | Feature | Description | |---------|-------------| -| **Project Overview** | Tech stack, dependencies, status | -| **Spec Manager** | View and edit specification files | -| **Memory Viewer** | Browse persistent memories | -| **API Settings** | Configure AI model endpoints | -| **System Settings** | Global and project settings | +| **Project Info Banner** | Expandable banner showing project name, description, tech stack (languages, frameworks, architecture), development index (features/bugfixes/enhancements), and real-time index status | +| **Statistics Section** | 6 mini stat cards (Active Sessions, Total Tasks, Completed Tasks, Pending Tasks, Failed Tasks, Today Activity) with 7-day sparkline trends | +| **Workflow Status Pie Chart** | Donut chart showing session status breakdown (completed, in progress, planning, paused, archived) with percentages | +| **Session Carousel** | Auto-rotating (5s) session cards with task list, progress bar, and manual navigation arrows | +| **Recent Sessions Widget** | Tabbed view of recent tasks across all task types with filtering, status badges, and progress indicators | +| **Real-time Updates** | Auto-refresh every 60 seconds for stats and 30 seconds for index status | --- -## Access +## Usage Guide -Open via VS Code command palette: -``` -CCW: Open Dashboard -``` +### Basic Workflow -Or via CLI: -```bash -ccw view -``` +1. **View Project Overview**: Check the project info banner for tech stack and development index +2. **Monitor Statistics**: Review mini stat cards for current project metrics and trends +3. **Track Workflow Status**: View pie chart for session status distribution +4. **Browse Active Sessions**: Use session carousel to see task details and progress +5. **Access Recent Work**: Switch between All Tasks/Workflow/Lite Tasks tabs to find specific sessions + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Expand Project Details** | Click the chevron button in the project banner to show architecture, components, patterns | +| **Navigate Sessions** | Click arrow buttons or wait for auto-rotation (5s interval) in the carousel | +| **View Session Details** | Click on any session card to navigate to session detail page | +| **Filter Recent Tasks** | Click tab buttons to filter by task type (All/Workflow/Lite) | +| **Refresh Dashboard** | Click the refresh button in the header to reload all data | + +### Index Status Indicator + +| Status | Icon | Meaning | +|--------|------|---------| +| **Building** | Pulsing blue dot | Code index is being built/updated | +| **Completed** | Green dot | Index is up-to-date | +| **Idle** | Gray dot | Index status is unknown/idle | +| **Failed** | Red dot | Index build failed | --- -## Dashboard Sections +## Components Reference -### 1. Project Overview -- Technology stack detection -- Dependency status -- Workflow session status +### Main Components -### 2. Spec Manager -- List all specs -- Edit spec content -- Enable/disable specs +| Component | Location | Purpose | +|-----------|----------|---------| +| `DashboardHeader` | `@/components/dashboard/DashboardHeader.tsx` | Page header with title and refresh action | +| `WorkflowTaskWidget` | `@/components/dashboard/widgets/WorkflowTaskWidget.tsx` | Combined widget with project info, stats, workflow status, and session carousel | +| `RecentSessionsWidget` | `@/components/dashboard/widgets/RecentSessionsWidget.tsx` | Recent sessions across workflow and lite tasks | +| `MiniStatCard` | (internal to WorkflowTaskWidget) | Individual stat card with optional sparkline | +| `HomeEmptyState` | (internal to WorkflowTaskWidget) | Empty state display when no sessions exist | -### 3. Memory Viewer -- Browse memory entries -- Search memories -- Export/import +### State Management -### 4. API Settings -- Configure API keys -- Set model endpoints -- Manage rate limits +- **Local state**: + - `hasError` - Error tracking for critical failures + - `projectExpanded` - Project info banner expansion state + - `currentSessionIndex` - Active session in carousel + - `activeTab` - Recent sessions widget filter tab -### 5. System Settings -- Global configuration -- Project overrides -- Hook management +- **Custom hooks**: + - `useWorkflowStatusCounts` - Session status distribution data + - `useDashboardStats` - Statistics with auto-refresh (60s) + - `useProjectOverview` - Project information and tech stack + - `useIndexStatus` - Real-time index status (30s refresh) + - `useSessions` - Active sessions data + - `useLiteTasks` - Lite tasks data for recent widget + +--- + +## Configuration + +No configuration required. The dashboard automatically fetches data from the backend. + +### Auto-Refresh Intervals + +| Data Type | Interval | +|-----------|----------| +| Dashboard stats | 60 seconds | +| Index status | 30 seconds | +| Discovery sessions | 3 seconds (on discovery page) | --- ## Related Links -- [API Settings](/features/api-settings) - API configuration -- [System Settings](/features/system-settings) - System configuration -- [Spec System](/features/spec) - Specification management +- [Sessions](/features/sessions) - View and manage all sessions +- [Queue](/features/queue) - Issue execution queue management +- [Discovery](/features/discovery) - Discovery session tracking +- [Memory](/features/memory) - Persistent memory management +- [System Settings](/features/system-settings) - Global application settings diff --git a/docs/features/discovery.md b/docs/features/discovery.md new file mode 100644 index 00000000..3b6d25e8 --- /dev/null +++ b/docs/features/discovery.md @@ -0,0 +1,163 @@ +# Discovery + +## One-Liner + +**The Discovery page tracks multi-perspective discovery sessions, displaying findings from various analysis angles with real-time updates and export capabilities.** + +--- + +## Pain Points Solved + +| Pain Point | Current State | Discovery Solution | +|------------|---------------|-------------------| +| **No insight visibility** | Can't see analysis results | Dedicated page for discovery sessions | +| **Stale data** | Manual refresh required | Auto-refresh every 3 seconds | +| **Unstructured findings** | Hard to navigate results | Split pane with session list and findings detail | +| **No export** | Can't save findings | Export all or selected findings | +| **Missing context** | Don't know related issues | Link findings to related issues | + +--- + +## Page Overview + +**Location**: `ccw/frontend/src/pages/DiscoveryPage.tsx` + +**Purpose**: Track discovery sessions and view findings from multiple perspectives (Product, Technical, Quality, Risk, Coverage, etc.). + +**Access**: Navigation → Issues → Discovery tab OR directly via `/discovery` route + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Discovery Title | ++--------------------------------------------------------------------------+ +| Stats Cards | +| +-------------+ +-------------+ +-------------+ +-------------+ | +| | Total | | Completed | | Running | | Total | | +| | Sessions | | Sessions | | Sessions | | Findings | | +| +-------------+ +-------------+ +-------------+ +-------------+ | ++--------------------------------------------------------------------------+ +| Split Pane (3:1 ratio) | +| +-----------------------+ +------------------------------------------+ | +| | Session List (1/3) | | Findings Detail (2/3) | | +| | | | | | +| | - DiscoveryCard | | - Filters | | +| | (status, findings) | | - Findings list | | +| | | | - Export buttons | | +| | - Multiple sessions | | - Related issues links | | +| +-----------------------+ +------------------------------------------+ | ++--------------------------------------------------------------------------+ +``` + +--- + +## Core Features + +| Feature | Description | +|---------|-------------| +| **Stats Cards** | Four metric cards showing total sessions, completed sessions, running sessions, and total findings count | +| **Session List** | Left panel with discovery session cards showing status, findings count, and creation time | +| **Findings Detail** | Right panel displaying detailed findings for the selected session | +| **Auto-Refresh** | Data refreshes every 3 seconds to show real-time progress | +| **Findings Filters** | Filter findings by perspective, category, or other attributes | +| **Export Findings** | Export all findings or only selected findings to file | +| **Related Issues** | Click on findings to navigate to related issues in the Issues panel | +| **Status Badges** | Visual indicators for session status (completed, running, pending) | +| **Loading Skeletons** | Skeleton placeholders during data fetch | +| **Empty States** | Friendly message when no discovery sessions exist | + +--- + +## Usage Guide + +### Basic Workflow + +1. **View All Sessions**: Browse all discovery sessions in the left panel +2. **Select Session**: Click a session card to view its findings in the right panel +3. **Filter Findings**: Use filter controls to narrow down findings by category +4. **Export Findings**: Click "Export All" or "Export Selected" to save findings +5. **Navigate to Issues**: Click on a finding to view related issues +6. **Monitor Progress**: Watch running sessions update in real-time (3s auto-refresh) + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Select session** | Click a discovery card in the left panel to load its findings | +| **Filter findings** | Use filter controls in the findings detail panel to narrow results | +| **Export all findings** | Click "Export All" to download all findings for current session | +| **Export selected findings** | Select specific findings, click "Export Selected" | +| **Navigate to issue** | Click on a finding to open related issue in Issues panel | +| **Auto-refresh** | Data updates automatically every 3 seconds (no manual action needed) | + +### Session Status + +| Status | Icon | Description | +|--------|------|-------------| +| **Completed** | Green checkmark | Discovery session finished successfully | +| **Running** | Amber spinner | Discovery session is actively running | +| **Pending** | Gray clock | Discovery session is queued or not started | +| **Failed** | Red X | Discovery session encountered an error | + +### Finding Types + +Findings can include various perspectives: +- **Product** - Market fit, user value, business viability +- **Technical** - Feasibility, tech debt, performance, security +- **Quality** - Completeness, testability, consistency +- **Risk** - Risk identification, dependencies, failure modes +- **Coverage** - Requirement completeness vs discovery context + +--- + +## Components Reference + +### Main Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `DiscoveryPage` | `@/pages/DiscoveryPage.tsx` | Main discovery tracking page | +| `DiscoveryCard` | `@/components/issue/discovery/DiscoveryCard.tsx` | Session card in list | +| `DiscoveryDetail` | `@/components/issue/discovery/DiscoveryDetail.tsx` | Findings detail view with filters and export | + +### State Management + +- **Local state**: + - None (all data from hooks) + +- **Custom hooks**: + - `useIssueDiscovery` - Discovery sessions and findings data + - Returns: `sessions`, `activeSession`, `findings`, `filters`, `isLoadingSessions`, `isLoadingFindings`, `error` + - Methods: `setFilters`, `selectSession`, `exportFindings`, `exportSelectedFindings` + - `useIssues` - Related issues data for finding navigation + +--- + +## Configuration + +### Auto-Refresh Interval + +The discovery page automatically refreshes every 3 seconds: + +```typescript +const { sessions, findings, /* ... */ } = useIssueDiscovery({ + refetchInterval: 3000 // 3 seconds +}); +``` + +### Export Options + +| Export Type | Description | +|-------------|-------------| +| **Export All** | Export all findings from the selected session | +| **Export Selected** | Export only the findings that are currently selected/checked | + +--- + +## Related Links + +- [Issue Hub](/features/issue-hub) - Unified issues, queue, and discovery management +- [Queue](/features/queue) - Issue execution queue management +- [Issues Panel](/features/issue-hub) - Issue list and GitHub sync +- [Terminal Dashboard](/features/terminal-dashboard) - Real-time session monitoring diff --git a/docs/features/explorer.md b/docs/features/explorer.md new file mode 100644 index 00000000..5b3de8e4 --- /dev/null +++ b/docs/features/explorer.md @@ -0,0 +1,216 @@ +# Explorer & Graph Explorer + +## One-Liner + +**The Explorer pages provide codebase navigation with file tree browsing, code dependency visualization, and real-time search capabilities.** + +--- + +## Pain Points Solved + +| Pain Point | Current State | Explorer Solution | +|------------|---------------|-------------------| +| **No code overview** | Can't see codebase structure | File tree with hierarchical navigation | +| **Hard to find files** | Manual directory traversal | Search and filter with instant results | +| **Unknown dependencies** | Can't see relationships | Visual dependency graph with nodes/edges | +| **No context preview** | Open files blindly | File preview with syntax highlighting | +| **Lost in large codebases** | Can't navigate efficiently | Split view with resizable panes | + +--- + +## File Explorer + +### Page Overview + +**Location**: `ccw/frontend/src/pages/ExplorerPage.tsx` + +**Purpose**: File explorer with tree view and file preview panel. + +**Access**: Navigation → Explorer + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Explorer Title | ++--------------------------------------------------------------------------+ +| Toolbar: [Search...] [Root v] [View v] [Sort v] [Hidden] [Expand][Collapse]| ++--------------------------------------------------------------------------+ +| +----------------+ / +--------------------------------------------------+ | +| | Tree View | | File Preview | | +| | (resizable) | | - Syntax highlighting | | +| | | | - Line numbers | | +| | - Folder tree | | - Language detection | | +| | - File icons | | | | +| | - Expandable | | | | +| +----------------+ +--------------------------------------------------+ | ++--------------------------------------------------------------------------+ +``` + +### Core Features + +| Feature | Description | +|---------|-------------| +| **Tree View** | Hierarchical file tree with expand/collapse | +| **File Preview** | Syntax-highlighted preview with line numbers | +| **Resizable Panes** | Drag divider to resize tree width (200-600px) | +| **Root Selection** | Change root directory from available options | +| **Search/Filter** | Filter files by name | +| **View Mode** | Toggle between tree and list view | +| **Sort Options** | Name, size, modified date | +| **Hidden Files** | Toggle show/hide hidden files | +| **Expand/Collapse All** | Bulk expand or collapse all folders | +| **Max File Size** | 1MB limit for preview | + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Open file** | Click file in tree to show preview | +| **Expand folder** | Click folder arrow to expand/collapse | +| **Resize pane** | Drag divider between tree and preview | +| **Change root** | Select root directory from dropdown | +| **Search files** | Type in search box to filter tree | +| **Sort files** | Select sort option from dropdown | + +--- + +## Graph Explorer + +### Page Overview + +**Location**: `ccw/frontend/src/pages/GraphExplorerPage.tsx` + +**Purpose**: Code dependency graph visualization using ReactFlow with filtering and node details. + +**Access**: Navigation → Graph Explorer + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Graph Toolbar: [Filters] [Fit View] [Refresh] [Reset] | ++--------------------------------------------------------------------------+ +| +---------------------------------------------------+ +------------------+ | +| | Graph Canvas (ReactFlow) | | Sidebar | | +| | | | (conditional) | | +| | [Module] --> [Class] --> [Function] | | - Node details | | +| | | | - OR legend | | +| | Mini map, controls, background | | | | +| +---------------------------------------------------+ +------------------+ | ++--------------------------------------------------------------------------+ +``` + +### Core Features + +| Feature | Description | +|---------|-------------| +| **ReactFlow Canvas** | Interactive graph with zoom/pan | +| **Node Types** | Component, module, class, function, variable, interface, hook | +| **Edge Types** | Imports, exports, extends, implements, uses, calls, depends-on | +| **Filters** | Filter by node type, edge type, isolated nodes | +| **Sidebar** | Shows selected node details OR legend | +| **Mini Map** | Overview of entire graph | +| **Status Panel** | Node count, edge count, updating indicator | +| **Fit View** | Auto-fit graph in view | +| **Custom Node Styles** | Color-coded by node type | + +### Node Types + +| Type | Color | Description | +|------|-------|-------------| +| **Component** | Blue | React/component | +| **Module** | Blue | Code module | +| **Class** | Green | Class definition | +| **Function** | Orange | Function/method | +| **Variable** | Cyan | Variable declaration | +| **Interface** | Gray | Interface/type | +| **Hook** | Purple | React hook | + +### Edge Types + +| Type | Description | +|------|-------------| +| **Imports** | Module import | +| **Exports** | Module export | +| **Extends** | Class extension | +| **Implements** | Interface implementation | +| **Uses** | Usage reference | +| **Calls** | Function call | +| **Depends-on** | Dependency | + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Select node** | Click node to show details in sidebar | +| **Deselect** | Click canvas background | +| **Zoom in/out** | Use mouse wheel or zoom controls | +| **Pan canvas** | Drag canvas or use pan tool | +| **Fit view** | Click Fit View button | +| **Filter nodes** | Toggle node type filters in toolbar | +| **Filter edges** | Toggle edge type filters in toolbar | +| **Reset filters** | Click Reset button | + +--- + +## Components Reference + +### File Explorer Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `ExplorerPage` | `@/pages/ExplorerPage.tsx` | Main file explorer page | +| `TreeView` | `@/components/shared/TreeView.tsx` | Hierarchical tree component | +| `FilePreview` | `@/components/shared/FilePreview.tsx` | File content preview | +| `ExplorerToolbar` | `@/components/shared/ExplorerToolbar.tsx` | Toolbar with controls | + +### Graph Explorer Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `GraphExplorerPage` | `@/pages/GraphExplorerPage.tsx` | Main graph explorer page | +| `GraphToolbar` | `@/components/shared/GraphToolbar.tsx` | Toolbar with filters | +| `GraphSidebar` | `@/components/shared/GraphSidebar.tsx` | Node details or legend | +| `Custom Nodes` | `@/pages/graph-explorer/nodes/*` | Node type components | + +### State Management + +**File Explorer**: +- **Local state**: `rootPath`, `treeWidth`, `isResizing` +- **Custom hooks**: `useFileExplorer`, `useFileContent` + +**Graph Explorer**: +- **Local state**: `selectedNode`, `isSidebarOpen`, `filters` +- **Custom hooks**: `useGraphData` + +--- + +## Configuration + +### File Explorer Settings + +```typescript +const DEFAULT_TREE_WIDTH = 300; +const MIN_TREE_WIDTH = 200; +const MAX_TREE_WIDTH = 600; +const MAX_FILE_SIZE = 1024 * 1024; // 1MB +``` + +### Graph Explorer Settings + +```typescript +const defaultFilters: GraphFilters = { + nodeTypes: ['component', 'module', 'class', 'function', 'variable', 'interface', 'hook'], + edgeTypes: ['imports', 'exports', 'extends', 'implements', 'uses', 'calls', 'depends-on'], + showIsolatedNodes: false, +}; +``` + +--- + +## Related Links + +- [Memory](/features/memory) - Persistent codebase knowledge +- [Terminal Dashboard](/features/terminal) - Terminal workspace with file sidebar +- [Orchestrator](/features/orchestrator) - Visual workflow editor diff --git a/docs/features/extensions.md b/docs/features/extensions.md new file mode 100644 index 00000000..031bf808 --- /dev/null +++ b/docs/features/extensions.md @@ -0,0 +1,244 @@ +# Extensions + +## One-Liner + +**Extensions management provides unified interfaces for configuring and managing skills, commands, rules, MCP servers, and hooks across project and user scopes.** + +--- + +## Pain Points Solved + +| Pain Point | Current State | Extensions Solution | +|------------|---------------|---------------------| +| **Scattered management** | Edit config files manually | Dedicated pages for each extension type | +| **Scope confusion** | Global vs project unclear | Location tabs (project/user/hub) | +| **No templates** | Create from scratch | Quick templates and wizards | +| **Hard to discover** | Unknown extensions | Skill Hub, recommended MCPs | +| **No cross-CLI sync** | Separate configs | Cross-CLI sync panel | + +--- + +## Skills Manager + +### Page Overview + +**Location**: `ccw/frontend/src/pages/SkillsManagerPage.tsx` + +**Purpose**: Browse, enable/disable, and manage skill packages with CLI mode toggle. + +**Access**: Navigation → Skills + +### Features + +| Feature | Description | +|---------|-------------| +| **Location Tabs** | Project, User, Hub tabs | +| **CLI Mode Toggle** | Switch between Claude and Codex CLI modes | +| **Stats Cards** | Total, Enabled, Disabled, Categories count | +| **Filters** | Search, category, source, enabled status | +| **Skill Grid** | Visual card grid with toggle, click details, delete | +| **Skill Hub** | Remote/Local/Installed skills with install/uninstall | +| **Detail Panel** | Slide-over panel with full skill details | +| **Create Dialog** | Install new skills from source | + +### Skill Sources + +| Source | Description | +|--------|-------------| +| **Builtin** | Built-in skills provided by CCW | +| **Custom** | User-created custom skills | +| **Community** | Community-contributed skills | + +--- + +## Commands Manager + +### Page Overview + +**Location**: `ccw/frontend/src/pages/CommandsManagerPage.tsx` + +**Purpose**: Manage slash commands with group-based organization. + +**Access**: Navigation → Commands + +### Features + +| Feature | Description | +|---------|-------------| +| **Location Tabs** | Project, User tabs | +| **Stats Cards** | Total, Enabled, Disabled counts | +| **Search** | Filter by command name | +| **Group Accordion** | Commands organized by group (cli, workflow, etc.) | +| **Toggle Commands** | Enable/disable individual commands | +| **Toggle Groups** | Enable/disable all commands in a group | +| **Expand/Collapse All** | Bulk expand or collapse all groups | +| **Show Disabled** | Toggle visibility of disabled commands | +| **Create Dialog** | Create new custom commands | + +### Command Groups + +| Group | Description | +|-------|-------------| +| **cli** | CLI-related commands | +| **workflow** | Workflow and session commands | +| **terminal** | Terminal management commands | + +--- + +## Rules Manager + +### Page Overview + +**Location**: `ccw/frontend/src/pages/RulesManagerPage.tsx` + +**Purpose**: Manage rules with full CRUD operations and category filtering. + +**Access**: Navigation → Rules + +### Features + +| Feature | Description | +|---------|-------------| +| **Location Tabs** | All, Project, User tabs | +| **Status Filter** | All, Enabled, Disabled | +| **Category Filter** | Filter by rule category | +| **Search** | Filter by name, description, category | +| **Active Filters Display** | Visual filter badges with remove | +| **Rules Grid** | Card grid with edit, delete, toggle actions | +| **CRUD Dialogs** | Create, edit, delete rule with confirmation | +| **Empty States** | Context-sensitive empty states | + +### Rule Categories + +Common rule categories include: +- **Validation** - Input and data validation +- **Transformation** - Data transformation rules +- **Routing** - Request routing logic +- **Security** - Security and access control +- **Custom** - User-defined categories + +--- + +## MCP Manager + +### Page Overview + +**Location**: `ccw/frontend/src/pages/McpManagerPage.tsx` + +**Purpose**: Manage MCP (Model Context Protocol) servers with template library and cross-CLI sync. + +**Access**: Navigation → MCP + +### Features + +| Feature | Description | +|---------|-------------| +| **Main Tabs** | Templates, Servers, Cross-CLI tabs | +| **CLI Mode Toggle** | Switch between Claude and Codex modes | +| **Stats Cards** | Total, Enabled, Global, Project counts | +| **Server Cards** | Expandable cards with toggle, edit, delete, save as template | +| **CCW Tools MCP** | Special card for CCW Tools configuration | +| **Templates** | Recommended MCPs and custom templates | +| **Cross-CLI Sync** | Sync MCP servers between Claude and Codex | +| **Scope Filter** | All, Global, Project filter | +| **Conflict Detection** | Warn about scope conflicts | + +### MCP Server Configuration + +Each MCP server has: +- **Name** - Server identifier +- **Command** - Executable command +- **Args** - Command arguments array +- **Env** - Environment variables object +- **Scope** - Global or Project +- **Enabled** - Enable/disable toggle + +### MCP Scopes + +| Scope | Description | +|-------|-------------| +| **Global** | Available across all projects | +| **Project** | Available only for current project | + +--- + +## Hook Manager + +### Page Overview + +**Location**: `ccw/frontend/src/pages/HookManagerPage.tsx` + +**Purpose**: Manage CLI hooks with trigger type organization and wizard creation. + +**Access**: Navigation → Hooks + +### Features + +| Feature | Description | +|---------|-------------| +| **Trigger Filters** | Filter by hook trigger type | +| **Stats Badges** | Enabled/Total count per trigger | +| **Search** | Filter by name, description, command | +| **Hook Cards** | Expandable cards with toggle, edit, delete | +| **Quick Templates** | Pre-built hook templates for quick install | +| **Wizard Launchers** | Guided creation for common hook patterns | +| **Create Dialog** | Manual hook creation form | + +### Hook Trigger Types + +| Trigger | Description | +|---------|-------------| +| **SessionStart** | When a session starts | +| **UserPromptSubmit** | When user submits a prompt | +| **PreToolUse** | Before tool execution | +| **PostToolUse** | After tool execution | +| **PostToolUseFailure** | After tool execution failure | +| **Stop** | When session stops | +| **Notification** | On notifications | +| **SubagentStart** | When subagent starts | +| **SubagentStop** | When subagent stops | +| **PreCompact** | Before context compaction | +| **SessionEnd** | When session ends | +| **PermissionRequest** | On permission requests | + +### Hook Wizards + +| Wizard | Description | +|--------|-------------| +| **Memory Update** | Auto-update memory after sessions | +| **Danger Protection** | Prevent dangerous operations | +| **Skill Context** | Auto-inject skill context | + +--- + +## Components Reference + +### Main Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `SkillsManagerPage` | `@/pages/SkillsManagerPage.tsx` | Skills management | +| `CommandsManagerPage` | `@/pages/CommandsManagerPage.tsx` | Commands management | +| `RulesManagerPage` | `@/pages/RulesManagerPage.tsx` | Rules management | +| `McpManagerPage` | `@/pages/McpManagerPage.tsx` | MCP servers management | +| `HookManagerPage` | `@/pages/HookManagerPage.tsx` | Hooks management | + +### Shared Components + +| Component | Purpose | +|-----------|---------| +| `SkillCard` / `SkillHubCard` | Skill display with actions | +| `CommandGroupAccordion` | Command group with accordion | +| `RuleCard` | Rule display with actions | +| `McpServerCard` / `CodexMcpEditableCard` | MCP server display | +| `HookCard` | Hook display with expand/collapse | +| `TabsNavigation` | Tab switcher | +| `CliModeToggle` | CLI mode badge switcher | + +--- + +## Related Links + +- [Settings](/features/settings) - Application configuration +- [System Settings](/features/system-settings) - Global system settings +- [CLI Tools](/features/cli) - CLI tool configuration diff --git a/docs/features/issue-hub.md b/docs/features/issue-hub.md new file mode 100644 index 00000000..bd98e919 --- /dev/null +++ b/docs/features/issue-hub.md @@ -0,0 +1,172 @@ +# Issue Hub + +## One-Liner + +**The Issue Hub is a unified management interface for issues, execution queues, and discovery sessions with tabbed navigation and shared actions.** + +--- + +## Pain Points Solved + +| Pain Point | Current State | Issue Hub Solution | +|------------|---------------|-------------------| +| **Scattered views** | Separate pages for issues/queue/discovery | Single unified page with tab navigation | +| **Context switching** | Hard to move between related features | Tab-based navigation persists in URL | +| **Duplicate actions** | Different actions per view | Context-aware action buttons per tab | +| **No issue creation** | Can't create new issues from UI | New issue dialog with attachments | +| **Missing sync** | No GitHub integration | GitHub sync button on Issues tab | + +--- + +## Page Overview + +**Location**: `ccw/frontend/src/pages/IssueHubPage.tsx` + +**Purpose**: Unified page for managing issues, queue, and discovery with tab navigation and context-aware actions. + +**Access**: Navigation → Issues OR direct routes `/issues?tab=issues|queue|discovery` + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Issue Hub Header (dynamic based on active tab) | +| [Refresh] [GitHub Sync] [Create Issue] [Fullscreen] | ++--------------------------------------------------------------------------+ +| [Issues] [Queue] [Discovery] | ++--------------------------------------------------------------------------+ +| Tab Content (switches based on active tab) | +| +--------------------------------------------------------------------+ | +| | | | +| | Issues Panel OR Queue Panel OR Discovery Panel | | +| | | | +| | Each panel has its own layout and controls | | +| | | | +| +--------------------------------------------------------------------+ | ++--------------------------------------------------------------------------+ +``` + +--- + +## Core Features + +| Feature | Description | +|---------|-------------| +| **Tab Navigation** | Three tabs: Issues, Queue, Discovery. Tab state persists in URL (`?tab=issues`) | +| **Dynamic Header** | Header title changes based on active tab | +| **Context-Aware Actions** | Action buttons change based on current tab | +| **GitHub Sync** | Pull issues from GitHub (Issues tab only) | +| **Create Issue** | Modal dialog for creating new issues with attachments | +| **Immersive Mode** | Fullscreen toggle to hide app chrome | +| **Auto-Refresh** | Per-tab refresh buttons with loading states | + +### Tab-Specific Features + +| Tab | Features | +|-----|----------| +| **Issues** | Refresh, GitHub Sync, Create Issue buttons | +| **Queue** | Refresh button only | +| **Discovery** | Internal controls (no header actions) | + +--- + +## Usage Guide + +### Basic Workflow + +1. **Navigate to Issue Hub**: Click "Issues" in the navigation +2. **Switch Tabs**: Click tab buttons or modify URL (`?tab=queue`) +3. **Issues Tab**: View issues, sync from GitHub, create new issues +4. **Queue Tab**: View and manage execution queue +5. **Discovery Tab**: Track discovery sessions + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Switch tabs** | Click tab buttons OR use URL parameter `?tab=issues|queue|discovery` | +| **Refresh current tab** | Click the refresh button (actions update per tab) | +| **Sync from GitHub** | Click the GitHub sync button on Issues tab | +| **Create new issue** | Click "Create Issue" button, fill in the form | +| **Toggle fullscreen** | Click the fullscreen button to enter/exit immersive mode | + +### New Issue Dialog + +| Field | Description | Required | +|-------|-------------|----------| +| **Title** | Issue title (max 200 chars) | Yes | +| **Description** | Detailed context (max 10000 chars) | No | +| **Type** | Bug, Feature, Improvement, Other | No (default: Other) | +| **Priority** | Low, Medium, High, Critical | No (default: Medium) | +| **Attachments** | Images, Markdown, text, PDF files | No | + +**Attachment Support**: +- Drag and drop files onto the upload area +- Click to open file picker +- Supported types: Images, Markdown (.md), text (.txt), JSON (.json), PDF (.pdf) +- Remove attachments before creating issue + +--- + +## Components Reference + +### Main Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `IssueHubPage` | `@/pages/IssueHubPage.tsx` | Main issue hub with tabs | +| `IssueHubHeader` | `@/components/issue/hub/IssueHubHeader.tsx` | Dynamic header based on tab | +| `IssueHubTabs` | `@/components/issue/hub/IssueHubTabs.tsx` | Tab switcher | +| `IssuesPanel` | `@/components/issue/hub/IssuesPanel.tsx` | Issues list and management | +| `QueuePanel` | `@/components/issue/hub/QueuePanel.tsx` | Queue management | +| `DiscoveryPanel` | `@/components/issue/hub/DiscoveryPanel.tsx` | Discovery tracking | +| `NewIssueDialog` | (internal to IssueHubPage) | Create issue modal | + +### State Management + +- **Local state**: + - `currentTab`: IssueTab ('issues' | 'queue' | 'discovery') + - `isNewIssueOpen`: boolean + - `isGithubSyncing`: boolean + +- **URL state**: + - Tab persists in URL search param: `?tab=issues` + +- **Custom hooks**: + - `useIssues` - Issues data and refresh + - `useIssueQueue` - Queue data and refresh + - `useIssueMutations` - Create issue mutation + - `pullIssuesFromGitHub` - GitHub sync API call + - `uploadAttachments` - Attachment upload for new issues + +--- + +## Configuration + +### Tab Navigation + +Tabs are validated against allowed values: + +```typescript +const VALID_TABS: IssueTab[] = ['issues', 'queue', 'discovery']; +``` + +Invalid tab values automatically redirect to 'issues'. + +### Issue Types + +| Type | Color | Description | +|------|-------|-------------| +| **Bug** | Red | Functional errors or problems | +| **Feature** | Green | New feature requests | +| **Improvement** | Blue | Enhancements to existing features | +| **Other** | Gray | Other types | + +--- + +## Related Links + +- [Issues Panel](/features/issue-hub) - Detailed issue management +- [Queue](/features/queue) - Queue management details +- [Discovery](/features/discovery) - Discovery session details +- [Sessions](/features/sessions) - Workflow session management diff --git a/docs/features/memory.md b/docs/features/memory.md index 69d7cd2b..ff91e422 100644 --- a/docs/features/memory.md +++ b/docs/features/memory.md @@ -2,7 +2,7 @@ ## One-Liner -**The Memory System is a cross-session knowledge persistence mechanism** — Stores project context, decisions, and learnings so AI remembers across sessions without re-explanation. +**The Memory System provides a unified interface for managing persistent knowledge across sessions, including core memory, workflow context, CLI history, vector search, and V2 pipeline operations.** --- @@ -14,62 +14,178 @@ | **Lost decisions** | Architecture decisions forgotten | Decision log persists | | **Repeated explanations** | Same context explained multiple times | Memory auto-injection | | **Knowledge silos** | Each developer maintains own context | Shared team memory | +| **Scattered data sources** | Core/workflow/CLI history separate | Unified search across all categories | --- -## vs Traditional Methods +## Page Overview -| Dimension | CLAUDE.md | Notes | **Memory System** | -|-----------|-----------|-------|-------------------| -| Persistence | Static file | Manual | **Auto-extracted from sessions** | -| Search | Text search | Folder search | **Semantic vector search** | -| Updates | Manual edit | Manual note | **Auto-capture from conversations** | -| Sharing | Git | Manual | **Auto-sync via workflow** | +**Location**: `ccw/frontend/src/pages/MemoryPage.tsx` ---- +**Purpose**: View and manage core memory with CRUD operations and unified vector search. -## Core Concepts +**Access**: Navigation → Memory -| Concept | Description | Location | -|---------|-------------|----------| -| **Core Memory** | Persistent project knowledge | `~/.claude/memory/` | -| **Session Memory** | Current session context | `.workflow/.memory/` | -| **Memory Entry** | Individual knowledge item | JSONL format | -| **Memory Index** | Searchable index | Embedding-based | +### Layout ---- - -## Usage - -### Viewing Memory - -```bash -ccw memory list -ccw memory search "authentication" +``` ++--------------------------------------------------------------------------+ +| Memory Title [Refresh] [Fullscreen]| ++--------------------------------------------------------------------------+ +| [Core] [Workflow] [CLI History] [Search] [V2 Pipeline] | ++--------------------------------------------------------------------------+ +| Tab Content (varies by active tab) | +| +--------------------------------------------------------------------+ | +| | | | +| | - Memory list with CRUD operations | | +| | - Search interface with filters | | +| | - Source type badges and tags | | +| | - V2 pipeline job monitoring (V2 tab) | | +| | | | +| +--------------------------------------------------------------------+ | ++--------------------------------------------------------------------------+ ``` -### Memory Categories +--- -- **Project Context**: Architecture, tech stack, patterns -- **Decisions**: ADRs, design choices -- **Learnings**: What worked, what didn't -- **Conventions**: Coding standards, naming +## Core Features + +| Feature | Description | +|---------|-------------| +| **Tabbed Interface** | Five tabs: Core, Workflow, CLI History, Search, V2 Pipeline | +| **CRUD Operations** | Create, edit, delete memories with confirmation dialogs | +| **Unified Search** | Vector search across all memory categories | +| **Source Type Filtering** | Filter by core_memory, workflow, cli_history | +| **Tag Filtering** | Filter memories by custom tags | +| **Batch Operations** | Select all, delete selected | +| **Recommendations** | View memory recommendations from AI | +| **Re-index** | Rebuild memory index | +| **Export** | Export search results to file | +| **V2 Pipeline** | Monitor extraction and consolidation jobs | +| **Immersive Mode** | Fullscreen toggle for focused work | + +--- + +## Memory Categories + +| Tab | Source Type | Description | +|-----|-------------|-------------| +| **Core** | `core_memory` | Persistent project knowledge stored in `~/.claude/memory/` | +| **Workflow** | `workflow` | Session context from `.workflow/.memory/` | +| **CLI History** | `cli_history` | Command execution history | +| **Search** | All | Unified vector search across all categories | +| **V2 Pipeline** | - | Extraction and consolidation job monitoring | + +--- + +## Usage Guide + +### Basic Workflow + +1. **Browse Memories**: Switch between Core/Workflow/CLI History tabs +2. **Create Memory**: Click "New Memory" button, fill in the form +3. **Edit Memory**: Click edit button on memory card, modify content +4. **Delete Memory**: Click delete button, confirm in dialog +5. **Search**: Switch to Search tab, enter query to find memories +6. **Filter Results**: Use source type and tag filters to narrow results + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Create memory** | Click "New Memory" button, fill form, submit | +| **Edit memory** | Click edit (pencil) button on memory card | +| **Delete memory** | Click delete (trash) button, confirm | +| **Search memories** | Switch to Search tab, type query, filter results | +| **Export results** | Select memories, click "Export Selected" | +| **Re-index memory** | Click "Re-index" to rebuild search index | +| **Select all** | Click "Select All" checkbox to select all visible memories | +| **Delete selected** | Click "Delete Selected" to batch delete | + +### Source Type Badges + +| Source Type | Color | Description | +|-------------|-------|-------------| +| **core_memory** | Blue | Persistent project knowledge | +| **workflow** | Green | Workflow session context | +| **cli_history** | Amber | CLI command history | + +### Memory Metadata + +Each memory entry contains: +- **ID**: Unique identifier (format: `CMEM-YYYYMMDD-HHMMSS`) +- **Content**: Markdown-formatted text +- **Tags**: Array of tag strings for categorization +- **Created/Updated**: Timestamps +- **Source Type**: Category identifier + +--- + +## V2 Pipeline + +The V2 Pipeline tab monitors background jobs for: + +| Job Type | Description | +|----------|-------------| +| **Extraction** | Extract knowledge from sessions | +| **Consolidation** | Consolidate and summarize memories | +| **Embedding** | Generate vector embeddings for search | + +### Job Status + +| Status | Description | +|--------|-------------| +| **Pending** | Job queued, not started | +| **Running** | Job in progress | +| **Done** | Job completed successfully | +| **Error** | Job failed with error message | + +--- + +## Components Reference + +### Main Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `MemoryPage` | `@/pages/MemoryPage.tsx` | Main memory management page | +| `V2PipelineTab` | `@/components/memory/V2PipelineTab.tsx` | V2 pipeline job monitoring | +| `MemoryCard` | (internal to MemoryPage) | Individual memory display | + +### State Management + +- **Local state**: + - `activeTab`: TabValue + - `searchQuery`: string + - `selectedMemories`: Set + - `filters`: { sourceType?: string; tags?: string[] } + - `dialogStates`: create, edit, delete + +- **Custom hooks**: + - `useMemory` - Core memory CRUD operations + - `useMemoryMutations` - Memory mutations (create, update, delete) + - `useUnifiedSearch` - Vector search across categories + - `useUnifiedStats` - Memory statistics + - `useRecommendations` - AI-generated recommendations + - `useReindex` - Rebuild search index --- ## Configuration -```json -// ~/.claude/settings.json -{ - "memory": { - "enabled": true, - "maxEntries": 1000, - "autoCapture": true, - "embeddingModel": "text-embedding-3-small" - } -} -``` +No configuration required. The memory system automatically fetches data from the backend. + +### Memory API Endpoints + +| Operation | Endpoint | +|-----------|----------| +| List memories | `GET /api/memory` | +| Create memory | `POST /api/memory` | +| Update memory | `PUT /api/memory/:id` | +| Delete memory | `DELETE /api/memory/:id` | +| Search | `POST /api/memory/search` | +| Re-index | `POST /api/memory/reindex` | +| V2 Jobs | `GET /api/memory/v2/jobs` | --- @@ -77,4 +193,5 @@ ccw memory search "authentication" - [Spec System](/features/spec) - Constraint injection - [CLI Call](/features/cli) - Command line invocation -- [CodexLens](/features/codexlens) - Code indexing +- [Explorer](/features/explorer) - Codebase navigation +- [Dashboard](/features/dashboard) - Project overview diff --git a/docs/features/orchestrator.md b/docs/features/orchestrator.md new file mode 100644 index 00000000..ef738198 --- /dev/null +++ b/docs/features/orchestrator.md @@ -0,0 +1,209 @@ +# Orchestrator + +## One-Liner + +**The Orchestrator is a visual workflow template editor with React Flow, featuring drag-drop node palette, property panel, and template library for designing automation flows.** + +--- + +## Pain Points Solved + +| Pain Point | Current State | Orchestrator Solution | +|------------|---------------|-----------------------| +| **No visual workflow design** | Manual configuration file editing | Drag-and-drop canvas interface | +| **Hard to understand flows** | Text-based configuration | Visual node graphs with connections | +| **No template reuse** | Recreate flows from scratch | Template library for quick start | +| **Complex node configuration** | Remember all options | Contextual property panel | +| **Accidental edits during execution** | Can modify while running | Canvas lock during execution | + +--- + +## Page Overview + +**Location**: `ccw/frontend/src/pages/orchestrator/OrchestratorPage.tsx` + +**Purpose**: Visual workflow template editor for creating, editing, and managing automation flows. + +**Access**: Navigation → Orchestrator + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Flow Toolbar (save, load, template library, execution controls) | ++--------------------------------------------------------------------------+ +| +-------+------------------------------------------------------+-------+ | +| | Node | Flow Canvas (React Flow) | Prop | | +| | Palet | +----+ +----+ +----+ | Panel | | +| | (coll)| | N1 | -->| N2 | -->| N3 | | (cond)| | +| | | +----+ +----+ +----+ | | | +| | | | | | +| +-------+------------------------------------------------------+-------+ | ++--------------------------------------------------------------------------+ +``` + +--- + +## Core Features + +| Feature | Description | +|---------|-------------| +| **Node Palette (Left Sidebar)** | Collapsible panel with categorized nodes (templates, nodes tabs) | +| **Flow Canvas (Center)** | ReactFlow graph with zoom/pan, minimap, controls, grid background | +| **Property Panel (Right Overlay)** | Contextual property editor that appears when node is selected | +| **Template Library** | Dialog for browsing and loading saved templates | +| **Drag-and-Drop** | Drag nodes from palette to canvas to add them | +| **Connection Handles** | Connect nodes by dragging from output to input handles | +| **Interaction Modes** | Toggle between pan and selection modes (Ctrl to temporarily reverse) | +| **Execution Lock** | Canvas is read-only during flow execution | +| **Layout Persistence** | Sidebar width persists in local storage | +| **Snap to Grid** | Nodes align to 15px grid for neat layouts | + +--- + +## Usage Guide + +### Basic Workflow + +1. **Open Orchestrator**: Navigate to Orchestrator page (flows auto-load) +2. **Add Nodes**: Drag nodes from palette OR double-click palette items +3. **Connect Nodes**: Drag from output handle to input handle +4. **Configure Nodes**: Click node to open property panel, edit properties +5. **Save Flow**: Click save button in toolbar +6. **Use Templates**: Open template library to browse/load templates + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Add node (drag)** | Drag node from palette to canvas | +| **Add node (double-click)** | Double-click palette item | +| **Connect nodes** | Drag from source output handle to target input handle | +| **Select node** | Click node (opens property panel) | +| **Deselect** | Click canvas background | +| **Move node** | Drag node (when not executing) | +| **Delete node/edge** | Select and press Backspace/Delete (when not executing) | +| **Zoom in/out** | Use zoom controls or mouse wheel | +| **Fit view** | Click fit view button | +| **Pan canvas** | Drag canvas (pan mode) or use middle mouse button | +| **Toggle interaction mode** | Click mode toggle button or hold Ctrl (temporarily reverse) | +| **Collapse palette** | Click collapse button (or click expand button when collapsed) | +| **Open template library** | Click template library button in toolbar | + +### Node Categories + +The node palette organizes nodes into categories: +- **Prompt Templates** - Pre-built prompt templates with variables +- **Commands** - Slash command invocations +- **Tools** - External tool integrations +- **Custom** - User-defined nodes + +### Canvas Controls + +| Control | Location | Function | +|---------|----------|----------| +| **Zoom In/Out** | Controls (bottom-right) | Zoom canvas in/out | +| **Fit View** | Controls (bottom-right) | Fit all nodes in view | +| **Interactive Mode** | Controls (bottom-right) | Toggle pan/selection mode | +| **Mini Map** | Bottom-right | Overview of entire flow | +| **Grid Background** | Canvas | Visual reference for alignment | + +--- + +## Property Panel + +The property panel appears as an overlay when a node is selected. It provides: + +### Common Properties + +| Property | Description | +|----------|-------------| +| **Node Name** | Display name for the node | +| **Node ID** | Unique identifier (auto-generated) | +| **Execution Mode** | How node executes (sync/async/etc.) | +| **Instructions** | Prompt instructions with template support | +| **Variables** | Input/output variable definitions | +| **Tags** | Custom tags for organization | +| **Commands** | Associated slash commands | + +### Template Editor Features + +- **Built-in Templates**: Pre-defined instruction templates +- **Custom Tags**: Tag-based instruction system (e.g., `{{$INPUT}}`) +- **Variable Inputs**: Template variables with custom values +- **Preview**: Live preview of rendered instructions + +--- + +## Components Reference + +### Main Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `OrchestratorPage` | `@/pages/orchestrator/OrchestratorPage.tsx` | Main orchestrator page | +| `FlowToolbar` | `@/pages/orchestrator/FlowToolbar.tsx` | Top toolbar with actions | +| `LeftSidebar` | `@/pages/orchestrator/LeftSidebar.tsx` | Collapsible node palette | +| `FlowCanvas` | `@/pages/orchestrator/FlowCanvas.tsx` | ReactFlow graph canvas | +| `PropertyPanel` | `@/pages/orchestrator/PropertyPanel.tsx` | Node property editor overlay | +| `TemplateLibrary` | `@/pages/orchestrator/TemplateLibrary.tsx` | Template browser dialog | +| `NodeLibrary` | `@/pages/orchestrator/NodeLibrary.tsx` | Node palette content | +| `InlineTemplatePanel` | `@/pages/orchestrator/InlineTemplatePanel.tsx` | Template palette content | +| `InteractionModeToggle` | `@/pages/orchestrator/InteractionModeToggle.tsx` | Pan/selection mode toggle | + +### Node Types + +| Node Type | Purpose | +|-----------|---------| +| `PromptTemplateNode` | Unified prompt template node with instructions | +| Custom nodes | Extended from base node types | + +### State Management + +- **Local state** (OrchestratorPage): + - `isTemplateLibraryOpen`: boolean + +- **Zustand stores** (`useFlowStore`): + - `nodes` - Flow nodes array + - `edges` - Flow edges array + - `selectedNodeId` - Currently selected node + - `isPaletteOpen` - Palette expanded state + - `isPropertyPanelOpen` - Property panel visibility + - `leftPanelTab` - Active palette tab ('templates' | 'nodes') + - `interactionMode` - Pan or selection mode + +- **Execution store** (`useExecutionStore`): + - `isExecuting` - Whether flow is currently executing (locks canvas) + +--- + +## Configuration + +### Keyboard Shortcuts + +| Key | Action | +|-----|--------| +| **Backspace/Delete** | Delete selected node/edge (when not executing) | +| **Ctrl/Cmd (hold)** | Temporarily reverse interaction mode | +| **Mouse wheel** | Zoom in/out | +| **Middle mouse drag** | Pan canvas | + +### Canvas Settings + +```typescript +{ + snapToGrid: true, + snapGrid: [15, 15], // 15px grid alignment + nodesDraggable: !isExecuting, + nodesConnectable: !isExecuting, + elementsSelectable: !isExecuting +} +``` + +--- + +## Related Links + +- [Terminal Dashboard](/features/terminal) - Terminal-first execution monitoring +- [Sessions](/features/sessions) - Workflow session management +- [Commands Management](/features/extensions) - Slash command configuration diff --git a/docs/features/queue.md b/docs/features/queue.md new file mode 100644 index 00000000..6c5ef35b --- /dev/null +++ b/docs/features/queue.md @@ -0,0 +1,163 @@ +# Queue + +## One-Liner + +**The Queue page manages issue execution queues, displaying grouped tasks and solutions with conflict detection and merge capabilities.** + +--- + +## Pain Points Solved + +| Pain Point | Current State | Queue Solution | +|------------|---------------|----------------| +| **Disorganized execution** | No unified task queue | Centralized queue with grouped items | +| **Unknown queue status** | Can't tell if queue is ready | Status indicator with conflicts warning | +| **Manual queue management** | No way to control execution | Activate/deactivate/delete with actions | +| **Duplicate handling** | Confusing duplicate items | Merge queues functionality | +| **No visibility** | Don't know what's queued | Stats cards with items/groups/tasks/solutions counts | + +--- + +## Page Overview + +**Location**: `ccw/frontend/src/pages/QueuePage.tsx` + +**Purpose**: View and manage issue execution queues with stats, conflict detection, and queue operations. + +**Access**: Navigation → Issues → Queue tab OR directly via `/queue` route + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Queue Title [Refresh] | ++--------------------------------------------------------------------------+ +| Stats Cards | +| +-------------+ +-------------+ +-------------+ +-------------+ | +| | Total Items | | Groups | | Tasks | | Solutions | | +| +-------------+ +-------------+ +-------------+ +-------------+ | ++--------------------------------------------------------------------------+ +| Conflicts Warning (when conflicts exist) | ++--------------------------------------------------------------------------+ +| Queue Cards (1-2 columns) | +| +---------------------------------------------------------------------+ | +| | QueueCard | | +| | - Queue info | | +| | - Grouped items preview | | +| | - Action buttons (Activate/Deactivate/Delete/Merge) | | +| +---------------------------------------------------------------------+ | ++--------------------------------------------------------------------------+ +| Status Footer (Ready/Pending indicator) | ++--------------------------------------------------------------------------+ +``` + +--- + +## Core Features + +| Feature | Description | +|---------|-------------| +| **Stats Cards** | Four metric cards showing total items, groups, tasks, and solutions counts | +| **Conflicts Warning** | Banner alert when conflicts exist, showing count and description | +| **Queue Card** | Displays queue information with grouped items preview and action buttons | +| **Activate/Deactivate** | Toggle queue active state for execution control | +| **Delete Queue** | Remove queue with confirmation dialog | +| **Merge Queues** | Combine multiple queues (if multiple exist) | +| **Status Footer** | Visual indicator showing if queue is ready (active) or pending (inactive/conflicts) | +| **Loading State** | Skeleton placeholders during data fetch | +| **Empty State** | Friendly message when no queue exists | + +--- + +## Usage Guide + +### Basic Workflow + +1. **Check Queue Status**: Review stats cards and status footer to understand queue state +2. **Review Conflicts**: If conflicts warning is shown, resolve conflicts before activation +3. **Activate Queue**: Click "Activate" to enable queue for execution (only if no conflicts) +4. **Deactivate Queue**: Click "Deactivate" to pause execution +5. **Delete Queue**: Click "Delete" to remove the queue (requires confirmation) +6. **Merge Queues**: Use merge action to combine multiple queues when applicable + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Refresh queue** | Click the refresh button to reload queue data | +| **Activate queue** | Click the Activate button on the queue card | +| **Deactivate queue** | Click the Deactivate button to pause the queue | +| **Delete queue** | Click the Delete button, confirm in the dialog | +| **Merge queues** | Select source and target queues, click merge | +| **View status** | Check the status footer for ready/pending indication | + +### Queue Status + +| Status | Condition | Appearance | +|--------|-----------|------------| +| **Ready/Active** | Total items > 0 AND no conflicts | Green badge with checkmark | +| **Pending/Inactive** | No items OR conflicts exist | Gray/amber badge with clock icon | + +### Conflict Resolution + +When conflicts are detected: +1. A warning banner appears showing conflict count +2. Queue cannot be activated until conflicts are resolved +3. Status footer shows "Pending" state +4. Resolve conflicts through the Issues panel or related workflows + +--- + +## Components Reference + +### Main Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `QueuePage` | `@/pages/QueuePage.tsx` | Main queue management page | +| `QueueCard` | `@/components/issue/queue/QueueCard.tsx` | Queue display with actions | +| `QueuePageSkeleton` | (internal to QueuePage) | Loading placeholder | +| `QueueEmptyState` | (internal to QueuePage) | Empty state display | + +### State Management + +- **Local state**: + - None (all data from hooks) + +- **Custom hooks**: + - `useIssueQueue` - Queue data fetching + - `useQueueMutations` - Queue operations (activate, deactivate, delete, merge) + +### Mutation States + +| State | Loading Indicator | +|-------|------------------| +| `isActivating` | Disable activate button during activation | +| `isDeactivating` | Disable deactivate button during deactivation | +| `isDeleting` | Disable delete button during deletion | +| `isMerging` | Disable merge button during merge operation | + +--- + +## Configuration + +No configuration required. Queue data is automatically fetched from the backend. + +### Queue Data Structure + +```typescript +interface QueueData { + tasks: Task[]; + solutions: Solution[]; + conflicts: Conflict[]; + grouped_items: Record; +} +``` + +--- + +## Related Links + +- [Issue Hub](/features/issue-hub) - Unified issues, queue, and discovery management +- [Discovery](/features/discovery) - Discovery session tracking +- [Issues Panel](/features/issue-hub) - Issue list and GitHub sync diff --git a/docs/features/sessions.md b/docs/features/sessions.md new file mode 100644 index 00000000..7527ea84 --- /dev/null +++ b/docs/features/sessions.md @@ -0,0 +1,187 @@ +# Sessions + +## One-Liner + +**The Sessions page provides a centralized hub for viewing, filtering, and managing all workflow sessions with CRUD operations and status tracking.** + +--- + +## Pain Points Solved + +| Pain Point | Current State | Sessions Solution | +|------------|---------------|-------------------| +| **Lost sessions** | Can't find past work | Unified list of all sessions with search | +| **Unknown session status** | No progress visibility | Color-coded status badges with filters | +| **Cluttered view** | Active and archived mixed | Location tabs (active/archived/all) | +| **Hard to navigate** | No way to access details | Click to navigate to detail or review page | +| **No bulk actions** | Manual cleanup | Archive and delete with confirmation dialogs | + +--- + +## Page Overview + +**Location**: `ccw/frontend/src/pages/SessionsPage.tsx` + +**Purpose**: Sessions list page with filtering, search, and CRUD operations for managing workflow sessions. + +**Access**: Navigation → Sessions + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Sessions Title [Refresh] [Fullscreen]| ++--------------------------------------------------------------------------+ +| [Active] [Archived] [All] [Search...] [Filter v] | ++--------------------------------------------------------------------------+ +| Active filters display (when applied) | ++--------------------------------------------------------------------------+ +| Session Grid (1/2/3 columns responsive) | +| +-------------+ +-------------+ +-------------+ | +| | SessionCard | | SessionCard | | SessionCard | | +| | - Status | | - Status | | - Status | | +| | - Title | | - Title | | - Title | | +| | - Progress | | - Progress | | - Progress | | +| | - Actions | | - Actions | | - Actions | | +| +-------------+ +-------------+ +-------------+ | ++--------------------------------------------------------------------------+ +| Empty State (when no sessions) | ++--------------------------------------------------------------------------+ +``` + +--- + +## Core Features + +| Feature | Description | +|---------|-------------| +| **Location Tabs** | Filter sessions by location: Active, Archived, or All | +| **Search** | Full-text search across session titles and descriptions | +| **Status Filter** | Multi-select dropdown to filter by status (planning, in_progress, completed, paused) | +| **Active Filters Display** | Visual badges showing applied filters with remove buttons | +| **Session Cards** | Responsive grid (1/2/3 columns) with status badge, title, description, progress bar, and action buttons | +| **Immersive Mode** | Fullscreen toggle to hide app chrome for focused work | +| **Loading Skeletons** | Skeleton placeholders during data fetch | +| **Empty States** | Friendly message with call-to-action when no sessions match filters | + +--- + +## Usage Guide + +### Basic Workflow + +1. **Browse Sessions**: Use location tabs to switch between Active, Archived, and All sessions +2. **Search**: Type in the search box to filter by title or description +3. **Filter by Status**: Click the filter button to select one or more statuses +4. **Clear Filters**: Click individual filter badges or "Clear All" button +5. **View Details**: Click a session card to navigate to session detail page +6. **Manage Sessions**: Use action buttons to archive or delete sessions + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Navigate to detail** | Click anywhere on the session card to open detail page | +| **Navigate to review** | Review-type sessions automatically route to the review page | +| **Archive session** | Click the archive button on the card (no confirmation required) | +| **Delete session** | Click the delete button, confirm in the dialog | +| **Toggle fullscreen** | Click the fullscreen button to enter/exit immersive mode | +| **Clear search** | Click the X button in the search input | +| **Clear status filter** | Click the X on individual filter badges or use "Clear All" | + +### Status Types + +| Status | Color | Description | +|--------|-------|-------------| +| **Planning** | Violet | Session is in planning phase | +| **In Progress** | Amber | Session is actively being worked on | +| **Completed** | Green | Session has been completed | +| **Paused** | Slate | Session is paused | +| **Archived** | Gray | Session is archived | + +--- + +## Session Detail Page + +**Location**: `ccw/frontend/src/pages/SessionDetailPage.tsx` + +The session detail page provides a comprehensive view of a single session with tabbed content. + +### Tabs + +| Tab | Content | Always Shown | +|-----|---------|--------------| +| **Tasks** | List of all tasks with status | Yes (with badge count) | +| **Context** | Session context data | Conditional | +| **Summary** | Session summary | Conditional | +| **Impl Plan** | Implementation plan | Conditional | +| **Conflict** | Conflict resolution | Conditional | +| **Review** | Review content | Only if `has_review` or `review` exists | + +### Info Bar + +Displays created/updated dates and task progress (completed/total tasks). + +### Task Drawer + +Click any task to open a slide-over drawer with full task details. + +--- + +## Components Reference + +### Main Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `SessionsPage` | `@/pages/SessionsPage.tsx` | Main sessions list page | +| `SessionDetailPage` | `@/pages/SessionDetailPage.tsx` | Session detail with tabs | +| `SessionCard` | `@/components/shared/SessionCard.tsx` | Individual session display with actions | +| `SessionCardSkeleton` | `@/components/shared/SessionCard.tsx` | Loading placeholder | +| `TabsNavigation` | `@/components/ui/TabsNavigation.tsx` | Tab switcher component | +| `TaskListTab` | `@/pages/session-detail/TaskListTab.tsx` | Tasks list tab content | +| `TaskDrawer` | `@/components/shared/TaskDrawer.tsx` | Task detail slide-over | + +### State Management + +- **Local state** (SessionsPage): + - `locationFilter`: 'all' | 'active' | 'archived' + - `searchQuery`: string + - `statusFilter`: SessionMetadata['status'][] + - `deleteDialogOpen`: boolean + - `isImmersiveMode`: boolean (from global store) + +- **Local state** (SessionDetailPage): + - `activeTab`: TabValue + - `selectedTask`: TaskData | null + +- **Custom hooks**: + - `useSessions` - Sessions CRUD with filtering + - `useArchiveSession` - Archive session mutation + - `useDeleteSession` - Delete session mutation + - `useSessionDetail` - Session detail data fetch + +--- + +## Configuration + +No configuration required. Sessions are automatically fetched from the backend. + +### Filter Object Structure + +```typescript +interface SessionsFilter { + location?: 'all' | 'active' | 'archived'; + search?: string; + status?: SessionMetadata['status'][]; +} +``` + +--- + +## Related Links + +- [Dashboard](/features/dashboard) - Overview of all sessions with statistics +- [Lite Tasks](/features/tasks-history) - Lite-plan and lite-fix task management +- [Terminal Dashboard](/features/terminal-dashboard) - Terminal-first session monitoring +- [Orchestrator](/features/orchestrator) - Workflow template editor diff --git a/docs/features/settings.md b/docs/features/settings.md new file mode 100644 index 00000000..1918d713 --- /dev/null +++ b/docs/features/settings.md @@ -0,0 +1,187 @@ +# Settings + +## One-Liner + +**The Settings page provides a unified interface for managing application preferences, CLI tools, feature flags, and data management.** + +--- + +## Pain Points Solved + +| Pain Point | Current State | Settings Solution | +|------------|---------------|-------------------| +| **Scattered configuration** | Settings in multiple files | Centralized UI for all settings | +| **No tool management** | Edit config files manually | Enable/disable tools from UI | +| **Feature flags hidden** | Need to know config keys | Visual toggle switches | +| **No export/import** | Manual backup/restore | One-click export/import | +| **Unclear CCW status** | Can't tell if installed | Installation status indicator | + +--- + +## Page Overview + +**Location**: `ccw/frontend/src/pages/SettingsPage.tsx` + +**Purpose**: Application settings and configuration with CLI tools management. + +**Access**: Navigation → Settings + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Settings Title | ++--------------------------------------------------------------------------+ +| [Theme & Appearance v] | +| [Language v] | +| [Notifications v] | +| [Advanced v] | +| [CLI Tools v] | +| [Data Management v] | ++--------------------------------------------------------------------------+ +| (Each section expands/capses to show settings) | ++--------------------------------------------------------------------------+ +``` + +--- + +## Core Features + +| Feature | Description | +|---------|-------------| +| **Collapsible Sections** | Expand/collapse setting categories | +| **Theme Selection** | Choose light/dark theme | +| **Language Switcher** | Select UI language | +| **Notification Preferences** | Configure notification settings | +| **Feature Flags** | Toggle experimental features | +| **CLI Tools Management** | Enable/disable tools, select default | +| **Data Management** | Export/import settings, reset to defaults | +| **CCW Installation Status** | View and manage CCW installation | + +--- + +## Settings Categories + +### Theme & Appearance + +| Setting | Options | Description | +|---------|---------|-------------| +| **Theme** | Light, Dark, Auto | Select color theme | +| **Font Size** | Small, Medium, Large | Adjust UI text size | + +### Language + +| Setting | Options | Description | +|---------|---------|-------------| +| **Interface Language** | English, Chinese | Select UI language | + +### Notifications + +| Setting | Options | Description | +|---------|---------|-------------| +| **Enable Notifications** | Toggle | Show desktop notifications | +| **Sound Effects** | Toggle | Play sounds for actions | + +### Advanced + +| Setting | Options | Description | +|---------|---------|-------------| +| **Chinese Response** | Toggle | Enable Chinese language responses | +| **Windows Platform** | Toggle | Enable Windows-specific features | +| **Codex CLI Enhancement** | Toggle | Enhanced Codex CLI integration | + +### CLI Tools + +| Tool | Status | Models | Tags | +|------|--------|--------|------| +| **Gemini** | Toggle | gemini-2.5-flash, gemini-2.5-pro | analysis, debug | +| **Qwen** | Toggle | coder-model | - | +| **Codex** | Toggle | gpt-5.2 | - | +| **Claude** | Toggle | sonnet, haiku | - | +| **OpenCode** | Toggle | opencode/glm-4.7-free | - | + +### Default Tool Selection + +Choose which CLI tool to use by default for operations. + +--- + +## Usage Guide + +### Basic Workflow + +1. **Browse Settings**: Click section headers to expand/collapse +2. **Modify Settings**: Change values using toggles, dropdowns, or inputs +3. **Enable/Disable Tools**: Use toggle switches in CLI Tools section +4. **Set Default Tool**: Select from dropdown +5. **Export Settings**: Click Export to download settings file +6. **Import Settings**: Click Import to upload settings file +7. **Reset**: Click Reset to Defaults to restore defaults + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Expand section** | Click section header to expand/collapse | +| **Toggle setting** | Click toggle switch to enable/disable | +| **Select option** | Use dropdown to select from options | +| **Export settings** | Click Export button, saves to file | +| **Import settings** | Click Import button, select file to upload | +| **Reset defaults** | Click Reset to Defaults, confirm in dialog | + +### CCW Installation + +The CCW (Code Canvas Workflow) installation status is displayed with: +- **Status Indicator**: Shows if CCW is installed +- **Version**: Current CCW version +- **Install Button**: Click to install or upgrade CCW + +--- + +## Configuration + +### Settings Persistence + +Settings are stored in: +- **Global**: `~/.claude/settings.json` +- **Project**: `.claude/settings.json` +- **Local**: `.claude/settings.local.json` (highest priority) + +### Feature Flags + +```json +{ + "featureFlags": { + "chineseResponse": true, + "windowsPlatform": false, + "codexCliEnhancement": true, + "dashboardQueuePanelEnabled": true, + "dashboardInspectorEnabled": true, + "dashboardExecutionMonitorEnabled": true + } +} +``` + +### CLI Tools Configuration + +```json +{ + "cliTools": { + "gemini": { "enabled": true }, + "qwen": { "enabled": true }, + "codex": { "enabled": true }, + "claude": { "enabled": true }, + "opencode": { "enabled": true } + }, + "defaultCliTool": "gemini" +} +``` + +--- + +## Related Links + +- [API Settings](/features/api-settings) - API endpoint configuration +- [CLI Call](/features/cli) - Command line invocation +- [Extensions](/features/extensions) - Skills, commands, rules management +- [System Settings](/features/system-settings) - Hooks, agents, MCP configuration diff --git a/docs/features/tasks-history.md b/docs/features/tasks-history.md new file mode 100644 index 00000000..496bac62 --- /dev/null +++ b/docs/features/tasks-history.md @@ -0,0 +1,214 @@ +# Tasks & History + +## One-Liner + +**Tasks & History pages provide comprehensive views of lite tasks, analysis sessions, prompt history, and review sessions with filtering, search, and detail inspection capabilities.** + +--- + +## Lite Tasks + +### Page Overview + +**Location**: `ccw/frontend/src/pages/LiteTasksPage.tsx` + +**Purpose**: Lite-plan and lite-fix task list page with TaskDrawer for details. + +**Access**: Navigation → Lite Tasks + +### Features + +| Feature | Description | +|---------|-------------| +| **Type Tabs** | Switch between lite-plan, lite-fix, multi-cli-plan types | +| **Task Cards** | Display task title, description, status, tags, progress | +| **TaskDrawer** | Slide-over panel with full task context and synthesis | +| **Round Synthesis** | Multi-perspective analysis results | +| **Context Content** | Full context view with expandable sections | +| **Status Indicators** | Visual badges for task status (planning, in_progress, completed, failed) | +| **Progress Bars** | Visual progress for running tasks | +| **Tag System** | Category tags for organization | + +### Task Types + +| Type | Description | +|------|-------------| +| **lite-plan** | Quick planning tasks | +| **lite-fix** | Quick bug fix tasks | +| **multi-cli-plan** | Multi-perspective planning with multiple tools | + +### Task Status Flow + +``` +planning → in_progress → completed + ↓ + failed +``` + +--- + +## Analysis Page + +### Page Overview + +**Location**: `ccw/frontend/src/pages/AnalysisPage.tsx` + +**Purpose**: View analysis sessions from `/workflow:analyze-with-file` command. + +**Access**: Navigation → Analysis + +### Features + +| Feature | Description | +|---------|-------------| +| **Session Cards** | Grid view with topic, session ID, status, date | +| **Status Filter** | Filter by all, in_progress, completed | +| **Date Filter** | Filter by all, today, week, month | +| **Date Quick Filter** | Quick select by specific dates with counts | +| **Search** | Filter by topic or session ID | +| **Pagination** | 16 items per page (4x4 grid) | +| **Detail Drawer** | Slide-over panel with tabs | +| **Detail Tabs** | Discussion, Conclusions, Explorations, Perspectives | +| **Fullscreen Mode** | Immersive view toggle | + +### Analysis Session Structure + +Each session contains: +- **Discussion** - Markdown formatted discussion log +- **Conclusions** - Structured conclusion data +- **Explorations** - Code exploration findings +- **Perspectives** - Multi-perspective analysis results + +--- + +## Prompt History + +### Page Overview + +**Location**: `ccw/frontend/src/pages/PromptHistoryPage.tsx` + +**Purpose**: View and manage prompt history with AI insights and timeline view. + +**Access**: Navigation → Prompt History + +### Features + +| Feature | Description | +|---------|-------------| +| **Stats Dashboard** | Total prompts, unique intents, session groups | +| **Timeline View** | Grouped by session or date | +| **Intent Filter** | Filter by bug-fix, feature, refactor, document, analyze | +| **Project Filter** | Filter by project path | +| **Search** | Filter by prompt content | +| **AI Insights** | Pattern analysis and suggestions | +| **Insights History** | Historical insight list | +| **Batch Operations** | Select all, batch delete | +| **Insight Detail** | Click to view full insight | + +### Prompt Card Details + +Each prompt card shows: +- **Prompt Text** - Truncated preview +- **Intent Badge** - Category classification +- **Timestamp** - When prompt was created +- **Session Info** - Associated session +- **Delete Action** - Remove from history +- **Select Checkbox** - Batch selection mode + +--- + +## Review Session + +### Page Overview + +**Location**: `ccw/frontend/src/pages/ReviewSessionPage.tsx` + +**Purpose**: Review session detail page with findings display, multi-select, and fix progress tracking. + +**Access**: Click review link from session detail OR direct route + +### Features + +| Feature | Description | +|---------|-------------| +| **Findings Grid** | Card-based findings display | +| **Dimension Tabs** | Filter by analysis dimension | +| **Severity Filter** | Critical, High, Medium, Low | +| **Sort Controls** | Sort by severity, dimension, file | +| **Multi-Select** | Select multiple findings | +| **Fix Progress** | Track fix stages with carousel | +| **Export Selected** | Export selected findings | +| **Findings Drawer** | Detail panel for selected finding | + +### Finding Structure + +Each finding contains: +- **Title** - Finding summary +- **Description** - Detailed explanation +- **Severity** - Critical, High, Medium, Low +- **Dimension** - Analysis dimension (e.g., security, performance) +- **Category** - Finding category +- **File/Line** - Source location +- **Code Context** - Relevant code snippet +- **Recommendations** - Fix suggestions +- **Root Cause** - Analysis of root cause +- **Impact** - Potential impact + +### Fix Progress Tracking + +| Stage | Description | +|-------|-------------| +| **Planning** | Fix planning stage | +| **Execution** | Fix execution stage | +| **Completion** | Fix completion stage | + +--- + +## Components Reference + +### Main Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `LiteTasksPage` | `@/pages/LiteTasksPage.tsx` | Lite tasks list with drawer | +| `AnalysisPage` | `@/pages/AnalysisPage.tsx` | Analysis sessions viewer | +| `PromptHistoryPage` | `@/pages/PromptHistoryPage.tsx` | Prompt history with insights | +| `ReviewSessionPage` | `@/pages/ReviewSessionPage.tsx` | Review session details | + +### Shared Components + +| Component | Purpose | +|-----------|---------| +| `TaskDrawer` | Task detail slide-over panel | +| `PromptCard` | Prompt display with actions | +| `InsightsPanel` | AI insights display | +| `InsightDetailPanel` | Insight detail overlay | +| `BatchOperationToolbar` | Batch operations controls | + +### State Management + +**Lite Tasks**: +- `useLiteTasks` - Task data and context +- Fetching: `fetchLiteSessionContext` + +**Analysis**: +- `fetchAnalysisSessions` - Session list +- `fetchAnalysisDetail` - Session detail + +**Prompt History**: +- `usePromptHistory` - Prompt data and stats +- `usePromptInsights` - AI insights +- `useInsightsHistory` - Historical insights +- Mutations: `analyzePrompts`, `deletePrompt`, `batchDeletePrompts` + +**Review Session**: +- `useReviewSession` - Review data and fix progress + +--- + +## Related Links + +- [Sessions](/features/sessions) - Workflow session management +- [Dashboard](/features/dashboard) - Recent tasks widget +- [Memory](/features/memory) - Persistent knowledge storage +- [Extensions](/features/extensions) - Skills and commands management diff --git a/docs/features/terminal.md b/docs/features/terminal.md new file mode 100644 index 00000000..83b5d29c --- /dev/null +++ b/docs/features/terminal.md @@ -0,0 +1,170 @@ +# Terminal Dashboard + +## One-Liner + +**The Terminal Dashboard provides a terminal-first workspace with resizable panes, floating panels, and integrated tools for session monitoring and orchestration.** + +--- + +## Pain Points Solved + +| Pain Point | Current State | Terminal Dashboard Solution | +|------------|---------------|-----------------------------| +| **Scattered terminals** | Multiple terminal windows | Unified tmux-style grid layout | +| **No context linkage** | Can't associate terminal output with issues | Association highlight provider | +| **Panel overload** | Fixed layout wastes space | Floating panels (mutually exclusive) | +| **Missing tools** | Switch between apps | Integrated issues, queue, inspector, scheduler | +| **Limited workspace** | Can't see code and terminals together | Resizable three-column layout | + +--- + +## Page Overview + +**Location**: `ccw/frontend/src/pages/TerminalDashboardPage.tsx` + +**Purpose**: Terminal-first layout for multi-terminal session management with integrated tools and resizable panels. + +**Access**: Navigation → Terminal Dashboard + +### Layout + +``` ++--------------------------------------------------------------------------+ +| Dashboard Toolbar (panel toggles, layout presets, fullscreen) | ++--------------------------------------------------------------------------+ +| +----------------+-------------------------------------------+------------+ | +| | Session | Terminal Grid (tmux-style) | File | | +| | Group Tree | +----------+ +----------+ | Sidebar | | +| | (resizable) | | Term 1 | | Term 2 | | (resizable)| | +| | | +----------+ +----------+ | | | +| | | +----------+ +----------+ | | | +| | | | Term 3 | | Term 4 | | | | +| | | +----------+ +----------+ | | | +| +----------------+-------------------------------------------+------------+ | ++--------------------------------------------------------------------------+ +| [Floating Panel: Issues+Queue OR Inspector OR Execution OR Scheduler] | ++--------------------------------------------------------------------------+ +``` + +--- + +## Core Features + +| Feature | Description | +|---------|-------------| +| **Three-Column Layout** | Resizable panes using Allotment: Session tree (left), Terminal grid (center), File sidebar (right) | +| **Terminal Grid** | Tmux-style split panes with layout presets (single, split-h, split-v, grid-2x2) | +| **Session Group Tree** | Hierarchical view of CLI sessions with grouping by tags | +| **Floating Panels** | Mutually exclusive overlay panels (Issues+Queue, Inspector, Execution Monitor, Scheduler) | +| **Association Highlight** | Cross-panel linking between terminals, issues, and queue items | +| **Layout Presets** | Quick layout buttons: single pane, horizontal split, vertical split, 2x2 grid | +| **Launch CLI** | Config modal for creating new CLI sessions with tool, model, and settings | +| **Fullscreen Mode** | Immersive mode hides app chrome (header + sidebar) | +| **Feature Flags** | Panel visibility controlled by feature flags (queue, inspector, execution monitor) | + +--- + +## Usage Guide + +### Basic Workflow + +1. **Launch CLI Session**: Click "Launch CLI" button, configure options (tool, model, shell, working directory) +2. **Arrange Terminals**: Use layout presets or manually split panes +3. **Navigate Sessions**: Browse session groups in the left tree +4. **Toggle Panels**: Click toolbar buttons to show/hide floating panels +5. **Inspect Issues**: Open Issues panel to view associated issues +6. **Monitor Execution**: Use Execution Monitor panel for real-time tracking + +### Key Interactions + +| Interaction | How to Use | +|-------------|------------| +| **Launch CLI** | Click "Launch CLI" button, configure session in modal | +| **Toggle sidebar** | Click Sessions/Files button in toolbar | +| **Open floating panel** | Click Issues/Queue/Inspector/Execution/Scheduler button | +| **Close floating panel** | Click X on panel or toggle button again | +| **Resize panes** | Drag the divider between panes | +| **Change layout** | Click layout preset buttons (single/split/grid) | +| **Fullscreen mode** | Click fullscreen button to hide app chrome | + +### Panel Types + +| Panel | Content | Position | +|-------|---------|----------| +| **Issues+Queue** | Combined Issues panel + Queue list column | Left (overlay) | +| **Queue** | Full queue management panel | Right (overlay, feature flag) | +| **Inspector** | Association chain inspector | Right (overlay, feature flag) | +| **Execution Monitor** | Real-time execution tracking | Right (overlay, feature flag) | +| **Scheduler** | Queue scheduler controls | Right (overlay) | + +### Layout Presets + +| Preset | Layout | +|--------|--------| +| **Single** | One terminal pane | +| **Split-H** | Two panes side by side | +| **Split-V** | Two panes stacked vertically | +| **Grid-2x2** | Four panes in 2x2 grid | + +--- + +## Components Reference + +### Main Components + +| Component | Location | Purpose | +|-----------|----------|---------| +| `TerminalDashboardPage` | `@/pages/TerminalDashboardPage.tsx` | Main terminal dashboard page | +| `DashboardToolbar` | `@/components/terminal-dashboard/DashboardToolbar.tsx` | Top toolbar with panel toggles | +| `SessionGroupTree` | `@/components/terminal-dashboard/SessionGroupTree.tsx` | Session tree navigation | +| `TerminalGrid` | `@/components/terminal-dashboard/TerminalGrid.tsx` | Tmux-style terminal panes | +| `FileSidebarPanel` | `@/components/terminal-dashboard/FileSidebarPanel.tsx` | File explorer sidebar | +| `FloatingPanel` | `@/components/terminal-dashboard/FloatingPanel.tsx` | Overlay panel wrapper | +| `IssuePanel` | `@/components/terminal-dashboard/IssuePanel.tsx` | Issues list panel | +| `QueuePanel` | `@/components/terminal-dashboard/QueuePanel.tsx` | Queue management panel | +| `QueueListColumn` | `@/components/terminal-dashboard/QueueListColumn.tsx` | Queue list (compact) | +| `SchedulerPanel` | `@/components/terminal-dashboard/SchedulerPanel.tsx` | Queue scheduler controls | +| `InspectorContent` | `@/components/terminal-dashboard/BottomInspector.tsx` | Association inspector | +| `ExecutionMonitorPanel` | `@/components/terminal-dashboard/ExecutionMonitorPanel.tsx` | Execution tracking | + +### State Management + +- **Local state** (TerminalDashboardPage): + - `activePanel`: PanelId | null + - `isFileSidebarOpen`: boolean + - `isSessionSidebarOpen`: boolean + +- **Zustand stores**: + - `useWorkflowStore` - Project path + - `useAppStore` - Immersive mode state + - `useConfigStore` - Feature flags + - `useTerminalGridStore` - Terminal grid layout and focused pane + - `useExecutionMonitorStore` - Active execution count + - `useQueueSchedulerStore` - Scheduler status + +--- + +## Configuration + +### Panel IDs + +```typescript +type PanelId = 'issues' | 'queue' | 'inspector' | 'execution' | 'scheduler'; +``` + +### Feature Flags + +| Flag | Controls | +|------|----------| +| `dashboardQueuePanelEnabled` | Queue panel visibility | +| `dashboardInspectorEnabled` | Inspector panel visibility | +| `dashboardExecutionMonitorEnabled` | Execution Monitor panel visibility | + +--- + +## Related Links + +- [Orchestrator](/features/orchestrator) - Visual workflow editor +- [Sessions](/features/sessions) - Session management +- [Issue Hub](/features/issue-hub) - Issues, queue, discovery +- [Explorer](/features/explorer) - File explorer