From c1386ed227d0ae32700a51635230b4a4adf2154b Mon Sep 17 00:00:00 2001 From: Lukas May Date: Mon, 2 Feb 2026 14:58:06 +0100 Subject: [PATCH] docs(15-02): create initiative detail wireframe with hierarchical breakdown - ASCII wireframe showing phase -> plan -> task hierarchy - Status indicators: DONE, IN PROGRESS, PENDING, BLOCKED - Agent assignments shown inline with tasks - Dependency visualization with ^ indicators - Component specs: PhaseAccordion, PlanTree, TaskRow, DependencyIndicator, DecisionList - Interaction notes for click actions, modals, and spawn dialog --- docs/wireframes/initiative-detail.md | 299 +++++++++++++++++++++++++++ 1 file changed, 299 insertions(+) create mode 100644 docs/wireframes/initiative-detail.md diff --git a/docs/wireframes/initiative-detail.md b/docs/wireframes/initiative-detail.md new file mode 100644 index 0000000..0075d60 --- /dev/null +++ b/docs/wireframes/initiative-detail.md @@ -0,0 +1,299 @@ +# Initiative Detail Wireframe + +The Initiative Detail screen shows the hierarchical breakdown of an initiative into phases, plans, and tasks. It provides visibility into progress, dependencies, and agent assignments. + +## ASCII Wireframe + +``` ++--------------------------------------------------------------------------------+ +| <- Back to Dashboard INITIATIVE DETAIL [Actions]| ++--------------------------------------------------------------------------------+ +| | +| +--------------------------------------------------------------------------+ | +| | # User Authentication System [ACTIVE] | | +| | Created: 2026-01-15 | Updated: 2026-02-01 | By: user | | +| +--------------------------------------------------------------------------+ | +| | +| +---------------------------+ +--------------------------------------------+ | +| | PROGRESS | | KEY DECISIONS | | +| | | | | | +| | [==========------] 67% | | v Authentication Method | | +| | | | JWT with httpOnly cookies | | +| | Phases: 2/3 complete | | Reason: XSS protection, refresh tokens | | +| | Plans: 6/9 complete | | | | +| | Tasks: 18/27 complete | | v Token Expiry | | +| | | | 15min access / 7d refresh | | +| +---------------------------+ | Reason: Balance security & UX | | +| | | | +| | > Session Storage (collapsed) | | +| | > Password Policy (collapsed) | | +| +--------------------------------------------+ | +| | +| +---------------------------------------------------------------------------+ | +| | PHASES [Queue All] | | +| +---------------------------------------------------------------------------+ | +| | +| v Phase 1: Core Infrastructure ------------------------------------ COMPLETE | +| | | +| +-- Plan 01: Project Foundation (3/3 tasks) ---------------------- DONE | +| | |-- Task: Initialize repository -------------------- DONE | +| | |-- Task: Configure TypeScript --------------------- DONE | +| | +-- Task: Setup build pipeline --------------------- DONE | +| | | +| +-- Plan 02: CLI Entry Point (2/2 tasks) ------------------------- DONE | +| | |-- Task: Create bin entry ------------------------- DONE | +| | +-- Task: Add commander integration ---------------- DONE | +| | | +| +-- Plan 03: Process Management (3/3 tasks) ---------------------- DONE | +| |-- Task: Create ProcessManager -------------------- DONE | +| |-- Task: Implement graceful shutdown -------------- DONE | +| +-- Task: Add signal handlers ---------------------- DONE | +| | +| v Phase 2: Data Layer ----------------------------------------- IN PROGRESS | +| | | +| +-- Plan 01: Database Setup (1/2 tasks) ---------------------- ACTIVE | +| | |-- Task: Create schema ---------------------------- DONE | +| | +-- Task: Run migrations --------- [gastown] --- IN PROGRESS | +| | | +| +-- Plan 02: Repository Layer (0/3 tasks) ----- [blocked by Plan 01] ---- | +| |-- Task: User repository -------------------------- PENDING | +| |-- Task: Task repository -------------------------- PENDING | +| +-- Task: Init repository -------------------------- PENDING | +| ^ blocked by: Plan 01 tasks | +| | +| > Phase 3: Git Integration (0/2 plans) ----------------------------- PENDING | +| ^ blocked by: Phase 2 | +| | ++----------------------------------------------------------------------------------+ + +Legend: + v = Expanded section (click to collapse) + > = Collapsed section (click to expand) + ^ = Dependency indicator + +Status Indicators: + DONE / COMPLETE = Task/plan/phase finished + IN PROGRESS = Currently being worked on + PENDING = Not yet started + BLOCKED = Has unresolved dependencies + [agent-name] = Agent assigned to task +``` + +## Expanded View: Task with Agent + +``` ++-- Task: Run migrations -------------------------------------------- IN PROGRESS +| +| Assigned to: gastown Started: 2026-02-01 14:30 +| Worktree: ~/.cw-worktrees/gastown Duration: 12m 34s +| +| +------------------------------------------------------------------+ +| | Last output (3 min ago): | +| | > Running migration 003_add_sessions... | +| | > Creating index on sessions.user_id... | +| +------------------------------------------------------------------+ +| +| [View Logs] [View Worktree] [Stop Agent] +``` + +## Expanded View: Blocked Task with Dependencies + +``` ++-- Task: Init repository --------------------------------------------- PENDING +| +| ^ Blocked by: +| | Plan 01 / Task: User repository (PENDING) +| | Plan 01 / Task: Task repository (PENDING) +| +| Dependencies must complete before this task can start. +| +| [Spawn Agent] (disabled - blocked) +``` + +## Component Specifications + +### PhaseAccordion + +Container for a phase that can be expanded/collapsed to show its plans. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `phase` | `Phase` | Phase entity with status, number, name | +| `plans` | `Plan[]` | Plans belonging to this phase | +| `expanded` | `boolean` | Whether section is expanded | +| `onToggle` | `() => void` | Toggle expand/collapse | + +**Behavior:** +- Default: First incomplete phase expanded, completed phases collapsed +- Click header to toggle expand/collapse +- Shows phase status badge (COMPLETE, IN PROGRESS, PENDING, BLOCKED) +- Shows dependency indicator if blocked + +### PlanTree + +Displays a plan with its nested task list in tree format. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `plan` | `Plan` | Plan entity with number, name, wave | +| `tasks` | `Task[]` | Tasks belonging to this plan | +| `blockedBy` | `string | null` | What's blocking this plan (if any) | + +**Behavior:** +- Shows task count: (completed/total tasks) +- Tree connectors: `|--` for siblings, `+--` for last item +- Plan status derived from task statuses +- Shows blocked indicator if dependencies exist + +### TaskRow + +Single task row with status, assignment, and actions. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `task` | `Task` | Task entity with title, status, assigned_to | +| `depth` | `number` | Nesting depth for indentation | +| `isLast` | `boolean` | Whether this is last sibling (affects connector) | + +**Behavior:** +- Click row opens TaskDetailModal +- Shows agent name inline if assigned: `[agent-name]` +- Shows status: DONE, IN PROGRESS, PENDING, BLOCKED +- Pending tasks show "Spawn Agent" on hover + +### DependencyIndicator + +Shows what's blocking a task or plan. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `blockedBy` | `Dependency[]` | Array of blocking items | +| `type` | `'task' | 'plan' | 'phase'` | What level this dependency is at | + +**Behavior:** +- Renders `^` symbol with hover tooltip +- Clicking shows full dependency path +- Format: `blocked by: {dependency description}` + +### DecisionList + +Collapsible list of key decisions made for this initiative. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `decisions` | `Decision[]` | Array of {topic, decision, reason} | +| `maxVisible` | `number` | How many to show before "show more" | + +**Behavior:** +- Each decision is collapsible (topic visible, details expand) +- `v` prefix for expanded, `>` for collapsed +- Shows topic as header, decision and reason as details + +### ProgressPanel + +Shows overall progress metrics for the initiative. + +**Props:** +| Prop | Type | Description | +|------|------|-------------| +| `phasesComplete` | `number` | Completed phases count | +| `phasesTotal` | `number` | Total phases | +| `plansComplete` | `number` | Completed plans count | +| `plansTotal` | `number` | Total plans | +| `tasksComplete` | `number` | Completed tasks count | +| `tasksTotal` | `number` | Total tasks | + +**Behavior:** +- Progress bar shows percentage +- Breakdown by phase/plan/task counts + +## Interaction Notes + +### Click Actions + +| Element | Action | +|---------|--------| +| Phase header | Expand/collapse phase | +| Plan row | Expand/collapse plan tasks | +| Task row | Opens TaskDetailModal | +| Agent name `[gastown]` | Navigates to agent detail view | +| "Spawn Agent" button | Opens agent spawn dialog for this task | +| "Queue Phase" button | Dispatches all pending tasks in phase to queue | +| "Queue All" button | Dispatches all pending tasks across all phases | +| Back button | Returns to Initiative Dashboard | +| Decision topic | Expand/collapse decision details | + +### TaskDetailModal + +When clicking a task row, a modal opens with: + +``` ++------------------------------------------------------+ +| Task: Run migrations [X] | ++------------------------------------------------------+ +| | +| Status: IN PROGRESS Priority: Normal | +| Assigned: gastown Started: 14:30 | +| | +| Description: | +| Run database migrations for user and session | +| tables. Verify indexes created correctly. | +| | +| Dependencies: | +| - Task: Create schema (DONE) | +| | +| Blocks: | +| - Task: User repository | +| - Task: Task repository | +| | +| [View Agent Logs] [Stop Task] [Mark Complete] | ++------------------------------------------------------+ +``` + +### Agent Spawn Dialog + +When clicking "Spawn Agent" on a pending task: + +``` ++------------------------------------------------------+ +| Spawn Agent for Task [X] | ++------------------------------------------------------+ +| | +| Task: User repository | +| | +| Agent name: [auto-generated: yaletown] | +| Mode: [Execute v] | +| | +| The agent will: | +| 1. Create isolated git worktree | +| 2. Execute the task | +| 3. Report completion or questions | +| | +| [Cancel] [Spawn Agent] | ++------------------------------------------------------+ +``` + +## Status Colors + +| Status | Color | Meaning | +|--------|-------|---------| +| COMPLETE / DONE | Green | Work finished | +| IN PROGRESS / ACTIVE | Blue | Currently being worked | +| PENDING | Gray | Not yet started | +| BLOCKED | Orange | Has unresolved dependencies | + +## Responsive Considerations + +- On narrow screens, collapse the KEY DECISIONS panel +- Phase tree maintains full width for readability +- Task rows truncate long titles with ellipsis +- Agent names link to agent detail in all views + +--- +*Wireframe for: Initiative Detail Screen* +*Part of: Codewalk District Frontend Design*