From 31bb8c77588b4d563d6f0df67a3c8a086549fab9 Mon Sep 17 00:00:00 2001 From: Lukas May Date: Mon, 2 Feb 2026 14:57:42 +0100 Subject: [PATCH] docs(15-01): create initiative dashboard wireframe - ASCII wireframe showing initiative list with status, progress, actions - Empty state wireframe for no initiatives - Component specs: InitiativeCard, ProgressBar, StatusBadge, ActionMenu, SpawnArchitectDropdown - Interaction notes for navigation, spawning architects, filtering - Data requirements and responsive behavior documentation --- docs/wireframes/initiative-dashboard.md | 344 ++++++++++++++++++++++++ 1 file changed, 344 insertions(+) create mode 100644 docs/wireframes/initiative-dashboard.md diff --git a/docs/wireframes/initiative-dashboard.md b/docs/wireframes/initiative-dashboard.md new file mode 100644 index 0000000..012d82e --- /dev/null +++ b/docs/wireframes/initiative-dashboard.md @@ -0,0 +1,344 @@ +# Initiative Dashboard Wireframe + +The Initiative Dashboard is the primary entry point for Codewalk District. It displays all initiatives with their status, progress, and quick actions. + +--- + +## ASCII Wireframe + +### Default State (With Initiatives) + +``` ++------------------------------------------------------------------------------+ +| CODEWALK DISTRICT [+ New Initiative] | ++------------------------------------------------------------------------------+ +| Initiatives Agents Tasks Settings | ++------------------------------------------------------------------------------+ +| | +| +------------------------------------------------------------------------+ | +| | INITIATIVES Filter: [All v]| | +| +------------------------------------------------------------------------+ | +| | | | +| | +--------------------------------------------------------------------+ | | +| | | User Authentication | | | +| | | Status: [IN PROGRESS] Progress: ████████░░░░ 67% Phases: 3/4 | | | +| | | [View] [Spawn Architect v] [...] | | | +| | +--------------------------------------------------------------------+ | | +| | | | +| | +--------------------------------------------------------------------+ | | +| | | Payment Integration | | | +| | | Status: [APPROVED] Progress: ░░░░░░░░░░░░ 0% Phases: 0/5 | | | +| | | [View] [Spawn Architect v] [...] | | | +| | +--------------------------------------------------------------------+ | | +| | | | +| | +--------------------------------------------------------------------+ | | +| | | Dashboard Redesign | | | +| | | Status: [DRAFT] Progress: ░░░░░░░░░░░░ 0% Phases: 0/0 | | | +| | | [View] [Spawn Architect v] [...] | | | +| | +--------------------------------------------------------------------+ | | +| | | | +| | +--------------------------------------------------------------------+ | | +| | | API Rate Limiting | | | +| | | Status: [COMPLETED] Progress: ████████████ 100% Phases: 2/2 | | | +| | | [View] [Spawn Architect v] [...] | | | +| | +--------------------------------------------------------------------+ | | +| | | | +| +------------------------------------------------------------------------+ | +| | ++------------------------------------------------------------------------------+ +``` + +### Empty State + +``` ++------------------------------------------------------------------------------+ +| CODEWALK DISTRICT [+ New Initiative] | ++------------------------------------------------------------------------------+ +| Initiatives Agents Tasks Settings | ++------------------------------------------------------------------------------+ +| | +| +------------------------------------------------------------------------+ | +| | INITIATIVES Filter: [All v]| | +| +------------------------------------------------------------------------+ | +| | | | +| | | | +| | | | +| | No initiatives yet | | +| | | | +| | Create your first initiative to | | +| | start planning and executing work. | | +| | | | +| | [+ New Initiative] | | +| | | | +| | | | +| | | | +| +------------------------------------------------------------------------+ | +| | ++------------------------------------------------------------------------------+ +``` + +### Spawn Architect Dropdown + +``` ++--------------------------------------------------------------------+ +| User Authentication | +| Status: [IN PROGRESS] Progress: ████████░░░░ 67% Phases: 3/4 | +| [View] [Spawn Architect v] [...] | +| +--------------------+ | +| | Discuss | <-- Capture context/decisions | +| | Breakdown | <-- Create phases from initiative | +| +--------------------+ | ++--------------------------------------------------------------------+ +``` + +### More Actions Menu + +``` ++--------------------------------------------------------------------+ +| User Authentication | +| Status: [IN PROGRESS] Progress: ████████░░░░ 67% Phases: 3/4 | +| [View] [Spawn Architect v] [...] | +| +--------------------+ | +| | Edit | | +| | Duplicate | | +| | Archive | | +| | Delete | | +| +--------------------+ | ++--------------------------------------------------------------------+ +``` + +--- + +## Component Specifications + +### InitiativeCard + +Displays a single initiative as a row in the dashboard list. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `initiative` | `Initiative` | The initiative data object | +| `onView` | `() => void` | Callback when View is clicked | +| `onSpawnArchitect` | `(mode: 'discuss' \| 'breakdown') => void` | Callback for architect actions | +| `onDelete` | `() => void` | Callback when Delete is selected | + +**Display Logic:** +- Title: `initiative.title` +- Status: Rendered via `StatusBadge` component +- Progress: Rendered via `ProgressBar` component using `phases_completed / phases_total` +- Phases: Text showing `{completed}/{total}` phase count + +**Behavior:** +- Entire row is clickable, navigates to initiative detail view +- Click propagation stopped for action buttons + +--- + +### ProgressBar + +Visual progress indicator showing completion percentage. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `completed` | `number` | Number of completed phases | +| `total` | `number` | Total number of phases | + +**Display Logic:** +``` +Progress calculation: percentage = (completed / total) * 100 +If total is 0, show empty bar (0%) + +Visual representation (12 characters wide): + 0%: ░░░░░░░░░░░░ + 25%: ███░░░░░░░░░ + 50%: ██████░░░░░░ + 75%: █████████░░░ +100%: ████████████ +``` + +**Variants:** +- Default: Blue filled blocks +- Completed (100%): Green filled blocks +- Empty (0/0 phases): Gray outline, no fill + +--- + +### StatusBadge + +Color-coded badge indicating initiative status. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `status` | `InitiativeStatus` | One of the status enum values | + +**Color Mapping:** +| Status | Color | Background | +|--------|-------|------------| +| `draft` | Gray | `#E5E7EB` | +| `review` | Yellow | `#FEF3C7` | +| `approved` | Blue | `#DBEAFE` | +| `in_progress` | Blue | `#DBEAFE` | +| `completed` | Green | `#D1FAE5` | +| `rejected` | Red | `#FEE2E2` | + +**Text Display:** +- Uppercase, e.g., `DRAFT`, `IN PROGRESS`, `COMPLETED` +- `in_progress` rendered as `IN PROGRESS` (space separated) + +--- + +### ActionMenu + +Dropdown menu for initiative actions. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `initiativeId` | `string` | ID of the initiative | +| `onEdit` | `() => void` | Edit callback | +| `onDuplicate` | `() => void` | Duplicate callback | +| `onArchive` | `() => void` | Archive callback | +| `onDelete` | `() => void` | Delete callback | + +**Menu Items:** +1. Edit - Opens initiative edit form +2. Duplicate - Creates a copy of the initiative +3. Archive - Moves to archived state (soft delete) +4. Delete - Permanent deletion (with confirmation) + +**Behavior:** +- Opens on click of `[...]` button +- Closes on outside click or Escape key +- Delete shows confirmation dialog before executing + +--- + +### SpawnArchitectDropdown + +Dropdown for selecting Architect agent mode. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `initiativeId` | `string` | ID of the initiative | +| `onSpawn` | `(mode: 'discuss' \| 'breakdown') => void` | Spawn callback with selected mode | + +**Menu Items:** +1. **Discuss** - Spawns Architect in discuss mode to capture context and decisions +2. **Breakdown** - Spawns Architect in breakdown mode to create phases from initiative + +**Behavior:** +- Opens on click of `[Spawn Architect v]` button +- Selecting an option triggers the spawn and closes dropdown +- Shows loading state while agent is spawning + +--- + +## Interaction Notes + +### Navigation + +| Action | Result | +|--------|--------| +| Click initiative row | Navigate to `/initiatives/{id}` (detail view) | +| Click "View" button | Navigate to `/initiatives/{id}` (detail view) | +| Click "New Initiative" | Navigate to `/initiatives/new` (create form) | +| Click "Initiatives" nav | Current page (highlight active) | +| Click "Agents" nav | Navigate to `/agents` | +| Click "Tasks" nav | Navigate to `/tasks` | +| Click "Settings" nav | Navigate to `/settings` | + +### Spawn Architect Flow + +1. User clicks "Spawn Architect" dropdown +2. Dropdown shows mode options: Discuss, Breakdown +3. User selects mode (e.g., "Discuss") +4. System calls `cw architect discuss --initiative {id}` +5. Agent spawns, dropdown closes +6. Toast notification: "Architect agent spawned for discussion" +7. User can monitor progress in Agents view + +### Filter Behavior + +The filter dropdown allows filtering by status: +- **All** - Shows all initiatives +- **Draft** - Only draft initiatives +- **Review** - Only initiatives in review +- **Approved** - Only approved initiatives +- **In Progress** - Only in-progress initiatives +- **Completed** - Only completed initiatives +- **Rejected** - Only rejected initiatives + +### Keyboard Shortcuts (Future) + +| Key | Action | +|-----|--------| +| `n` | Open new initiative form | +| `/` | Focus filter/search | +| `j/k` | Navigate up/down in list | +| `Enter` | Open selected initiative | +| `Esc` | Close any open dropdown | + +--- + +## Data Requirements + +### Initiative Object + +```typescript +interface Initiative { + id: string; // e.g., "init-a1b2c3" + title: string; // e.g., "User Authentication" + status: InitiativeStatus; + phasesTotal: number; // Total number of phases + phasesCompleted: number; // Phases with status='completed' + createdAt: number; // Unix timestamp + updatedAt: number; // Unix timestamp +} + +type InitiativeStatus = + | 'draft' + | 'review' + | 'approved' + | 'in_progress' + | 'completed' + | 'rejected'; +``` + +### API Endpoint + +```typescript +// GET /api/initiatives +// Returns: Initiative[] + +// Query params: +// - status?: InitiativeStatus (filter by status) +// - limit?: number (pagination) +// - offset?: number (pagination) +``` + +--- + +## Responsive Behavior + +### Desktop (>1024px) +- Full layout as shown in wireframes +- All columns visible +- Actions inline + +### Tablet (768px - 1024px) +- Progress text hidden, only bar visible +- Phase count condensed: `3/4` instead of `Phases: 3/4` + +### Mobile (<768px) +- Cards stack vertically (one per row) +- Progress bar below title +- Actions in collapsible menu only (no inline buttons) + +--- + +*Wireframe version: 1.0* +*Last updated: 2026-02-02*