tas/Codewalkers
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add ASCII wireframe mockups for all frontend pages

Browse Source 
Covers: app layout, initiatives list, initiative detail (4 tabs),
agents page, inbox, settings (health + projects), and all dialogs.
This commit is contained in:
Lukas May
2026-03-02 17:28:14 +09:00
parent 988160b2b7
commit 89db580ca4
12 changed files with 1778 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/wireframes/README.md Normal file
View File

@@ -0,0 +1,24 @@
# UI Wireframes
ASCII wireframe mockups documenting the current state of the Codewalk District frontend.
## Pages
| Wireframe | Route | Description |
|-----------|-------|-------------|
| [app-layout.md](app-layout.md) | `*` | Global shell: header, nav tabs, content area |
| [initiatives-list.md](initiatives-list.md) | `/initiatives` | Initiative cards with progress, filters, actions |
| [initiative-detail.md](initiative-detail.md) | `/initiatives/$id` | Header + tab bar (content/plan/execution/review) |
| [content-tab.md](content-tab.md) | `?tab=content` | Page tree sidebar + Tiptap editor |
| [plan-tab.md](plan-tab.md) | `?tab=plan` | Phase sidebar + phase detail panel |
| [execution-tab.md](execution-tab.md) | `?tab=execution` | Kanban pipeline graph |
| [review-tab.md](review-tab.md) | `?tab=review` | Diff viewer + review sidebar |
| [agents.md](agents.md) | `/agents` | Agent list + output viewer |
| [inbox.md](inbox.md) | `/inbox` | Message list + question form |
| [settings.md](settings.md) | `/settings/*` | Health check + projects management |
## Dialogs
| Wireframe | Component | Trigger |
|-----------|-----------|---------|
| [dialogs.md](dialogs.md) | All dialogs | Various buttons throughout the app |

174
docs/wireframes/agents.md Normal file
View File

@@ -0,0 +1,174 @@
# Agents Page (`/agents`)
Two-column layout: agent card list (320px) + agent output viewer.
## Default State
```
+============================================================================+
| CODEWALK DISTRICT |
| [ Initiatives ] [*Agents*] [ Inbox ] [ Settings ] |
+============================================================================+
| |
| Agents (7) [ Refresh ] |
| |
| [*All (7)*] [Running (2)] [Questions (1)] [Exited (3)] [Dismissed (1)] |
| |
| +-------------+ +------------------------------------------------------+|
| | | | Output: blue-fox-7 [ Stop ] ||
| | * blue-fox-7| |-----------------------------------------------------||\
| | [claude] | | [System] Starting task: Implement OAuth routes ||
| | [execute] | | ||
| | 2m ago | | > I'll start by examining the current auth setup. ||
| | | | ||
| |-------------| | [Tool Call] Read ||
| | | | file_path: src/auth/index.ts ||
| | red-elk-3 | | ||
| | [claude] | | [Result] ||
| | [research]| | import { Router } from 'express'; ||
| | 5m ago | | export function setupAuth(app) { ... ||
| | Answer -> | | ||
| | | | > Based on the existing code, I'll create the ||
| |-------------| | > OAuth module with the following structure... ||
| | | | ||
| | grey-owl-1| | [Tool Call] Write ||
| | [openai] | | file_path: src/auth/oauth.ts ||
| | [plan] | | ||
| | 1h ago | | [Result] ||
| | Exited | | File written successfully ||
| | | | ||
| |-------------| | --- Session End --- ||
| | ... | | [Cost: $0.12] [Duration: 2m 34s] ||
| | | | ||
| +-------------+ | [Following v] [Jump to bottom] ||
| +------------------------------------------------------+|
| 320px flex-1 |
+============================================================================+
```
## Filter Bar
```
[*All (7)*] [Running (2)] [Questions (1)] [Exited (3)] [Dismissed (1)]
^^^^^^^^^
active pill (filled background), each shows count badge
```
Filter options:
- **All**: Every agent
- **Running**: Status = `running`
- **Questions**: Status = `waiting_for_input`
- **Exited**: Status = `exited`, `completed`, `crashed`
- **Dismissed**: Status = `dismissed`
## Agent Card (in left list)
### Running Agent
```
+---------------------------+
| * blue-fox-7 [...] | <-- StatusDot (green) + name + actions menu
| [claude] [execute] | <-- provider badge + mode badge
| 2m ago | <-- relative timestamp
+---------------------------+
```
### Waiting for Input
```
+---------------------------+
| ? red-elk-3 [...] | <-- StatusDot (orange)
| [claude] [research] |
| 5m ago |
| Answer questions -> | <-- link to inbox
+---------------------------+
```
### Exited
```
+---------------------------+
| - grey-owl-1 [...] | <-- StatusDot (grey)
| [openai] [plan] |
| 1h ago |
+---------------------------+
```
## Agent Actions Menu ([...])
```
+---------------------------+
| Go to Inbox | <-- only when waiting_for_input
| Stop | <-- only when running/waiting
| Dismiss | <-- only when stopped/crashed/idle
| Delete | <-- destructive, when stopped/dismissed
+---------------------------+
```
## Agent Output Viewer (right panel)
### Header
```
+------------------------------------------------------------------------+
| Output: blue-fox-7 [!] [ Stop ] |
| ^ |
| connection error indicator (if disconnected) |
+------------------------------------------------------------------------+
```
### Output Content (dark zinc-900 background, monospace)
```
[System] Starting task: Implement OAuth routes <-- grey badge
> I'll start by examining the current auth setup. <-- white text
| [Tool Call] Read <-- blue left border
| file_path: src/auth/index.ts
| [Result] <-- green left border
| import { Router } from 'express';
| export function setupAuth(app) { ...
> Based on the existing code, I'll create the OAuth module. <-- white text
| [Tool Call] Write <-- blue left border
| file_path: src/auth/oauth.ts
| [Result] <-- green left border
| File written successfully
| [Error] <-- red left border
| Permission denied: /etc/hosts <-- red text
─── Session End ─── <-- divider
[Cost: $0.12] [Duration: 2m 34s] <-- badges
```
### Footer Controls
```
[Following v] [Jump to bottom]
^^^^^^^^^^^
toggles: Following / Paused
```
- **Following**: auto-scrolls to bottom as new output arrives
- **Paused**: stops auto-scroll (toggled when user scrolls up)
- **Jump to bottom**: scrolls to latest output
## No Agent Selected
```
+------------------------------------------------------------------------+
| |
| |
| - - - - - - - - - - - - - - - - |
| Select an agent to view output |
| - - - - - - - - - - - - - - - - |
| |
| |
+------------------------------------------------------------------------+
```
## Source
- `packages/web/src/routes/agents.tsx`
- `packages/web/src/components/AgentOutputViewer.tsx`
- `packages/web/src/components/AgentActions.tsx`

68
docs/wireframes/app-layout.md Normal file
View File

@@ -0,0 +1,68 @@
# App Layout
Global shell wrapping all pages. Fixed header with navigation, scrollable content area.
```
+============================================================================+
| CODEWALK DISTRICT |
|----------------------------------------------------------------------------|
| [ Initiatives ] [ Agents ] [ Inbox ] [ Settings ] |
+============================================================================+
| |
| max-w-7xl padded content |
| |
| <Page Outlet> |
| |
| |
| |
| |
| |
| |
| |
| |
+============================================================================+
```
## Header Bar (56px, sticky, backdrop-blur)
```
+============================================================================+
| [logo] Codewalk District |
| |
| [Initiatives] [Agents] [Inbox] [Settings] |
| ^^^^^^^^^^ |
| bg-muted when active |
+============================================================================+
```
- Logo links to `/initiatives`
- Active tab gets `bg-muted` highlight
- Tabs are horizontal links below the wordmark
## Error States
### 404 Page
```
+============================================================================+
| CODEWALK DISTRICT |
| [ Initiatives ] [ Agents ] [ Inbox ] [ Settings ] |
+============================================================================+
| |
| |
| (!) Page not found |
| |
| [ Back to Dashboard ] |
| |
| |
+============================================================================+
```
## Components
- `<Toaster>` (sonner) renders globally for toast notifications (bottom-right)
- `<ErrorBoundary>` wraps the outlet
## Source
- `packages/web/src/layouts/AppLayout.tsx`
- `packages/web/src/routes/__root.tsx`

154
docs/wireframes/content-tab.md Normal file
View File

@@ -0,0 +1,154 @@
# Content Tab (`?tab=content`)
Two-column layout: page tree sidebar + rich text editor with refine agent panel.
## Default State (editing a page)
```
+============================================================================+
| < Back |
| Auth System Overhaul [ACTIVE] [YOLO] [git] main [P] backend |
| [*Content*] [ Plan ] [ Execution ] [ Review ] |
+============================================================================+
| | |
| Pages | [Refine with Agent] Saving... |
| | |
| > Root | Overview |
| > Auth | ___________________________________________________________ |
| > API | |
| > + | The authentication system needs a complete overhaul to |
| > + | support OAuth 2.0 and multi-tenant configurations. |
| | |
| | ## Current Problems |
| | |
| | - Session tokens expire too frequently |
| | - No support for SSO providers |
| | - Password reset flow is broken on mobile |
| | |
| | ## Proposed Solution |
| | |
| | Migrate to JWT-based auth with refresh token rotation... |
| | |
| 192px | flex-1 |
+============================================================================+
```
## Page Tree Sidebar (192px, border-right)
```
+-----------+
| Pages |
| |
| > Root Page Title [+] <-- hover shows + to add child
| > Auth Overview [+]
| > Login Flow <-- active page highlighted
| > Token Design
| > API Design [+]
| > Database Schema [+]
| |
+-----------+
```
- FileText icon + truncated title per node
- Active page gets accent background
- Hover reveals `+` button to create child page
- Indentation: 12px per depth level
- Click navigates to page
## Title Input
```
Overview___________________________
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3xl bold, transparent bg, no border
Editable inline, auto-saves on blur
```
## Tiptap Editor
Rich text editor with:
- StarterKit (headings, lists, bold, italic, code blocks, etc.)
- Slash commands (type `/` to trigger command palette)
- Page links (inline links to other pages in the tree)
- Auto-save via `useAutoSave` hook (debounced)
## Refine Agent Panel States
### Idle (no agent)
```
+------------------------------------------------------------------------+
| [sparkles] Refine with Agent |
+------------------------------------------------------------------------+
```
Clicking opens `<RefineSpawnDialog>`.
### Running
```
+------------------------------------------------------------------------+
| [spinner] Architect is refining... |
+------------------------------------------------------------------------+
```
### Waiting for Input (questions)
```
+------------------------------------------------------------------------+
| +------------------------------------------------------------------+ |
| | Q1: Should we include OAuth 2.0 PKCE flow? | |
| | ( ) Yes, include PKCE | |
| | ( ) No, standard auth code flow is fine | |
| | ( ) Let me specify: [________________] | |
| | | |
| | Q2: Which identity providers should we support? | |
| | [x] Google | |
| | [ ] GitHub | |
| | [x] Microsoft | |
| | | |
| | [ Cancel ] [ Dismiss ] [ Send Answers ]| |
| +------------------------------------------------------------------+ |
+------------------------------------------------------------------------+
```
### Completed (with changes)
```
+------------------------------------------------------------------------+
| [v] Agent completed |
| +------------------------------------------------------------------+ |
| | [v] ChangeSet: 3 changes [>] expand | |
| | | |
| | + page "OAuth Flow" | |
| | ~ page "Auth Overview" (modified) | |
| | + page "Token Rotation" | |
| | | |
| | [ Revert ] [ Dismiss ] | |
| +------------------------------------------------------------------+ |
+------------------------------------------------------------------------+
```
### Completed (no changes)
```
+------------------------------------------------------------------------+
| Agent completed -- no changes made. [ Dismiss ] |
+------------------------------------------------------------------------+
```
### Crashed
```
+------------------------------------------------------------------------+
| [!] Agent crashed unexpectedly. [ Retry ] |
+------------------------------------------------------------------------+
```
## Source
- `packages/web/src/components/editor/ContentTab.tsx`
- `packages/web/src/components/editor/PageTree.tsx`
- `packages/web/src/components/editor/RefineAgentPanel.tsx`
- `packages/web/src/components/QuestionForm.tsx`
- `packages/web/src/components/ChangeSetBanner.tsx`

186
docs/wireframes/dialogs.md Normal file
View File

@@ -0,0 +1,186 @@
# Dialogs
All modal/dialog overlays used throughout the application.
---
## Create Initiative Dialog
**Trigger**: "New Initiative" button on `/initiatives`
```
+----------------------------------------------------------+
| Create Initiative [x] |
| |
| Name * |
| [Auth System Overhaul___________________________] |
| |
| Branch (optional) |
| [cw/auth-overhaul_______________________________] |
| |
| Execution Mode |
| [ Review v ] |
| +--------------------+ |
| | Review | <-- confirm before merging |
| | YOLO | <-- auto-merge, no review |
| +--------------------+ |
| |
| Projects |
| +----------------------------------------------------+ |
| | [x] backend github.com/org/backend-api | |
| | [ ] frontend github.com/org/frontend-app | |
| | [ ] shared github.com/org/shared-lib | |
| | + Register new project | |
| +----------------------------------------------------+ |
| |
| [ Cancel ] [ Create ] |
+----------------------------------------------------------+
```
**Fields**:
- Name (required text input)
- Branch (optional text input)
- Execution Mode (select: Review / YOLO)
- Projects (ProjectPicker: checkbox list + register link)
**Source**: `packages/web/src/components/CreateInitiativeDialog.tsx`
---
## Register Project Dialog
**Trigger**: "Register Project" button on `/settings/projects` or "+ Register new project" in ProjectPicker
```
+----------------------------------------------------------+
| Register Project [x] |
| |
| Project Name * |
| [backend-api_______________________________________] |
| |
| Repository URL * |
| [https://github.com/org/backend-api________________] |
| |
| Default Branch |
| [main______________________________________________] |
| |
| [ Cancel ] [ Register ] |
+----------------------------------------------------------+
```
**Fields**:
- Project Name (required, unique)
- Repository URL (required, unique, git repo URL)
- Default Branch (text input, defaults to "main")
**Source**: `packages/web/src/components/RegisterProjectDialog.tsx`
---
## Refine Spawn Dialog
**Trigger**: "Refine with Agent" button in Content tab or "Retry" after crash
```
+----------------------------------------------------------+
| Refine Content [x] |
| |
| Instructions (optional) |
| +----------------------------------------------------+ |
| | Focus on the authentication flow section. | |
| | Add more detail about the OAuth providers we | |
| | need to support. | |
| | | |
| +----------------------------------------------------+ |
| |
| [ Cancel ] [ Start ] |
+----------------------------------------------------------+
```
**Fields**:
- Instructions (optional textarea, free-form guidance for the agent)
**Source**: `packages/web/src/components/editor/RefineSpawnDialog.tsx`
---
## Task Detail Modal
**Trigger**: Click any task row in Plan tab or Execution tab
```
+----------------------------------------------------------+
| Implement PKCE Flow [x] |
| |
| +------------------------+-------------------------+ |
| | Status [IN_PROGRESS]| Priority normal | |
| | Phase 2. OAuth Flow| Type execute | |
| | Agent blue-fox-7 | |
| +------------------------+-------------------------+ |
| |
| Description |
| Implement the OAuth 2.0 PKCE extension for public |
| clients. Generate code verifier/challenge pair, |
| include in authorization request, and validate |
| during token exchange. |
| |
| Dependencies |
| * Set up OAuth routes [DONE] |
| |
| Blocks |
| * GitHub provider adapter [BLOCKED] |
| * Microsoft provider adapter [PENDING] |
| |
| [ Queue Task ] [ Stop Task ] |
+----------------------------------------------------------+
```
**Fields** (read-only):
- 2-column metadata grid: Status, Priority, Phase, Type, Agent
- Description text
- Dependencies list (with StatusDot per dep)
- Blocks list (dependents)
**Actions**:
- Queue Task (disabled if already running/queued)
- Stop Task (disabled if not running)
**Source**: `packages/web/src/components/TaskDetailModal.tsx`
---
## Delete Subpage Dialog
**Trigger**: Auto-triggered when a page link is deleted in the Tiptap editor
```
+----------------------------------------------------------+
| Delete Subpage? [x] |
| |
| You removed a link to "Token Rotation". Do you |
| want to delete the subpage as well? |
| |
| [ Keep Subpage ] [ Delete ] |
+----------------------------------------------------------+
```
**Source**: `packages/web/src/components/editor/DeleteSubpageDialog.tsx`
---
## Confirmation Dialogs (window.confirm)
Used for destructive actions throughout the app. All support **Shift+click to bypass**.
| Action | Trigger Location | Message |
|--------|-----------------|---------|
| Delete initiative | Initiative card `...` menu | "Delete this initiative?" |
| Archive initiative | Initiative card `...` menu | "Archive this initiative?" |
| Delete phase | Phase detail `...` menu | "Delete this phase?" |
| Delete task | Task row `[x]` button | "Delete this task?" |
| Delete project | Project card trash button | "Delete this project?" |
| Delete agent | Agent actions menu | "Delete this agent?" |
## Source (shared)
- `packages/web/src/components/ProjectPicker.tsx`

111
docs/wireframes/execution-tab.md Normal file
View File

@@ -0,0 +1,111 @@
# Execution Tab (`?tab=execution`)
Horizontally scrollable kanban-style pipeline graph. Columns represent dependency levels computed via topological sort.
## Default State
```
+============================================================================+
| < Back |
| Auth System Overhaul [ACTIVE] [YOLO] [git] main [P] backend |
| [ Content ] [ Plan ] [*Execution*] [ Review ] |
+============================================================================+
| |
| <-- horizontally scrollable pipeline graph --> |
| |
| +----------+ +----------+ +----------+ |
| | Level 0 | -----> | Level 1 | -----> | Level 2 | |
| +----------+ +----------+ +----------+ |
| |
| +---------+ +---------+ +---------+ |
| | Phase 1 | ---> | Phase 2 | ---> | Phase 4 | |
| | DB Schm | | | OAuth | | | Testing | |
| | [DONE] | | | [READY] | | | [PEND] | |
| |---------| | |---------| | |---------| |
| | * task1 | | | * task1 | | | * task1 | |
| | * task2 | | | * task2 | | | * task2 | |
| | * task3 | | | * task3 | | | | |
| +---------+ | +---------+ | +---------+ |
| | | |
| | +---------+ | |
| | | Phase 3 | | |
| ---> | UI Comp |--- |
| | [PEND] | |
| |---------| |
| | * task1 | |
| | * task2 | |
| +---------+ |
| |
+============================================================================+
```
## Pipeline Stage Column
```
+-----------+
| Level N | <-- column header
+-----------+
| |
| +-------+ |
| | Phase | | <-- PipelinePhaseGroup cards stacked vertically
| +-------+ |
| |
| +-------+ |
| | Phase | |
| +-------+ |
| |
+-----------+
```
## Pipeline Phase Group
```
+-----------------------------------------+
| * Phase 2: OAuth Flow [READY] [play] | <-- status dot + name + queue btn
|-----------------------------------------|
| [play] Set up OAuth routes [PENDING] | <-- hover reveals play button
| [play] Implement PKCE flow [PENDING] |
| [ .. ] Google provider [RUNNING] | <-- running = no play button
| [ ] GitHub provider [BLOCKED] | <-- blocked = no play button
| [play] Microsoft provider [PENDING] |
+-----------------------------------------+
```
- Phase header: `StatusDot` + phase name + `StatusBadge` + queue button (plays icon)
- Task rows: play button (hover-visible) + task name + `StatusBadge`
- Queue button on phase header queues all eligible tasks
- Queue button on task queues individual task
- Clicking a task opens `<TaskDetailModal>`
## Connector Arrows
```
+--------+ +--------+
| Phase | ----[>]------> | Phase |
+--------+ +--------+
horizontal line + triangle arrow between columns
```
## Empty State (no phases)
Same as Plan tab empty state:
```
+============================================================================+
| |
| No phases yet |
| |
| [spinner] Planning phases... |
| -- or -- |
| [sparkles Plan Phases] or [ Add Phase ] |
| |
+============================================================================+
```
## Source
- `packages/web/src/components/pipeline/PipelineTab.tsx`
- `packages/web/src/components/pipeline/PipelineStageColumn.tsx`
- `packages/web/src/components/pipeline/PipelinePhaseGroup.tsx`
- `packages/web/src/components/pipeline/PipelineTaskCard.tsx`

188
docs/wireframes/inbox.md Normal file
View File

@@ -0,0 +1,188 @@
# Inbox Page (`/inbox`)
Two-column layout: message list (left) + detail panel (400px right).
## Default State
```
+============================================================================+
| CODEWALK DISTRICT |
| [ Initiatives ] [ Agents ] [*Inbox*] [ Settings ] |
+============================================================================+
| |
| Agent Inbox (3) [ Refresh ] |
| |
| [*All*] [Waiting (2)] [Completed (1)] |
| [Newest v] [Oldest] |
| |
| +-------------------------------+ +----------------------------------+ |
| | | | | |
| | (*) red-elk-3 (waiting) | | red-elk-3 -> You | |
| | "Should I use JWT or | | 2 minutes ago | |
| | session tokens f..." | | Task: #task-42 | |
| | 2m ago | | View in context | |
| | | | | |
| |-------------------------------| | +----------------------------+ | |
| | | | | Q1: Should I use JWT or | | |
| | (*) blue-fox-7 (waiting) | | | session tokens? | | |
| | "Which OAuth provider | | | | | |
| | should I priorit..." | | | ( ) JWT with refresh | | |
| | 5m ago | | | (*) Session cookies | | |
| | | | | ( ) Let me specify: | | |
| |-------------------------------| | | [________________] | | |
| | | | | | | |
| | ( ) grey-owl-1 (completed) | | | Q2: What session | | |
| | "Task completed | | | duration? | | |
| | successfully." | | | | | |
| | 1h ago | | | [24 hours____________] | | |
| | | | | | | |
| +-------------------------------+ | | | | |
| | | [Cancel] [Dismiss] | | |
| | | [Send Answers] | | |
| | +----------------------------+ | |
| | | |
| flex-1 +----------------------------------+ |
| 400px |
+============================================================================+
```
## Filter Bar
```
[*All*] [Waiting (2)] [Completed (1)]
```
## Sort Bar
```
[*Newest*] [Oldest]
```
## Message Card (in left list)
### Requires Response (waiting)
```
+-------------------------------+
| (*) red-elk-3 (waiting) | <-- filled orange dot
| "Should I use JWT or | <-- message preview (truncated 80 chars)
| session tokens f..." |
| 2m ago | <-- relative timestamp
+-------------------------------+
```
### No Response Needed (completed)
```
+-------------------------------+
| ( ) grey-owl-1 (completed) | <-- empty dot
| "Task completed |
| successfully." |
| 1h ago |
+-------------------------------+
```
- Orange filled dot = requires response
- Empty dot = no response needed
- Click selects agent and shows detail panel
- Selected card gets highlight background
## Inbox Detail Panel (400px right)
### Header
```
+----------------------------------+
| [<] red-elk-3 -> You | <-- mobile back button (hidden on desktop)
| 2 minutes ago |
| Task: #task-42 | <-- task ID link
| View in context | <-- link to initiative detail
+----------------------------------+
```
### Structured Questions (waiting_for_input)
```
+----------------------------------+
| Q1: Should I use JWT or |
| session tokens? |
| |
| ( ) JWT with refresh tokens |
| (*) Session cookies |
| ( ) Let me specify: |
| [________________________] |
| |
| Q2: What session duration |
| do you want? |
| |
| [24 hours___________________] | <-- free text input (textarea)
| |
| [Cancel] [Dismiss] |
| [Send Answers] | <-- disabled until all answered
+----------------------------------+
```
### Plain Message (notification, no structured questions)
```
+----------------------------------+
| Task completed successfully. |
| Created 3 files, modified 2. |
| |
| [ Dismiss ] |
+----------------------------------+
```
### Loading State
```
+----------------------------------+
| |
| [spinner] Loading... |
| |
+----------------------------------+
```
### Waiting for Questions
```
+----------------------------------+
| |
| Waiting for structured |
| questions... |
| |
+----------------------------------+
```
## No Agent Selected (right panel)
```
+----------------------------------+
| |
| - - - - - - - - - - - - - |
| Select a message to view |
| - - - - - - - - - - - - - |
| |
+----------------------------------+
```
## Empty State (no messages)
```
+============================================================================+
| |
| Agent Inbox (0) [ Refresh ] |
| |
| |
| No pending messages |
| |
| |
+============================================================================+
```
## Mobile Layout
On small screens, left list takes full width. When an agent is selected, detail panel takes full width with a back button `[<]` visible.
## Source
- `packages/web/src/routes/inbox.tsx`
- `packages/web/src/components/InboxList.tsx`
- `packages/web/src/components/InboxDetailPanel.tsx`
- `packages/web/src/components/MessageCard.tsx`
- `packages/web/src/components/QuestionForm.tsx`
- `packages/web/src/components/OptionGroup.tsx`
- `packages/web/src/components/FreeTextInput.tsx`

124
docs/wireframes/initiative-detail.md Normal file
View File

@@ -0,0 +1,124 @@
# Initiative Detail (`/initiatives/$id`)
Detail page for a single initiative with tabbed content areas.
## Default State
```
+============================================================================+
| CODEWALK DISTRICT |
| [*Initiatives*] [ Agents ] [ Inbox ] [ Settings ] |
+============================================================================+
| |
| < Back |
| |
| Auth System Overhaul [ACTIVE] [YOLO] [git] main [proj] backend |
| |
| [ Content ] [ Plan ] [*Execution*] [ Review ] |
| ----------------------------------------------------------------- |
| |
| <Tab Content Area> |
| |
| |
| |
+============================================================================+
```
## Initiative Header
```
+------------------------------------------------------------------------+
| [<] Initiative Name [STATUS] [MODE] [git] branch [P] proj |
+------------------------------------------------------------------------+
```
### Header Elements
```
[<] Back chevron (navigates to /initiatives)
Initiative Name h1, bold
[ACTIVE] StatusBadge (color-coded)
[YOLO] / [REVIEW] Execution mode (clickable toggle)
[git] cw/auth-overhaul Branch badge (GitBranch icon + name)
[P] backend Project badge(s), one per linked project
```
### Branch Editing (click branch badge)
```
[git] [ cw/auth-overhaul______ ] [v] [x]
```
### No Branch Yet
```
[<] Initiative Name [ACTIVE] [YOLO] [+ branch] [P] proj
```
### Project Editing (click pencil on project badges)
```
+------------------------------------------------------------------------+
| [<] Initiative Name [ACTIVE] [YOLO] [git] branch |
| |
| +----------------------------------+ |
| | [x] backend github.com/... | |
| | [ ] frontend github.com/... | |
| | [ ] shared github.com/... | |
| | + Register new project | |
| +----------------------------------+ |
| [ Save ] [ Cancel ] |
+------------------------------------------------------------------------+
```
### No Projects Yet
```
[<] Initiative Name [ACTIVE] [YOLO] [git] branch [+ Add projects]
```
## Tab Bar
```
[ Content ] [ Plan ] [*Execution*] [ Review ]
------------------------------------------------
^^^^^^^^^^
active tab (underlined/highlighted)
```
Tabs set `?tab=` URL search param. Default is `content`.
## Loading State
```
+============================================================================+
| < Back |
| |
| ░░░░░░░░░░░░░░░░░░ ░░░░░░ ░░░░░░ ░░░░░░░░░░░ |
| |
| ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ |
| +--------------------------+ +--------------------------+ |
| | ░░░░░░░░░░░░░░░░░░░░░░ | | ░░░░░░░░░░░░░░░░░░░░░░ | |
| | ░░░░░░░░░░░░░░ | | ░░░░░░░░░░░░░░ | |
| +--------------------------+ +--------------------------+ |
| |
+============================================================================+
```
## Error State
```
+============================================================================+
| |
| (!) Error loading initiative |
| Could not fetch initiative data |
| |
| [ Back to Dashboard ] |
| |
+============================================================================+
```
## Source
- `packages/web/src/routes/initiatives/$id.tsx`
- `packages/web/src/components/InitiativeHeader.tsx`

114
docs/wireframes/initiatives-list.md Normal file
View File

@@ -0,0 +1,114 @@
# Initiatives List (`/initiatives`)
Main dashboard showing all initiatives with progress tracking and quick actions.
## Default State
```
+============================================================================+
| CODEWALK DISTRICT |
| [*Initiatives*] [ Agents ] [ Inbox ] [ Settings ] |
+============================================================================+
| |
| Initiatives [All v] [ + New Initiative ] |
| |
| +----------------------------------------------------------------------+ |
| | Auth System Overhaul ACTIVE [=====> ] 3/7 phases | |
| | | |
| | [ View ] [Spawn Architect v] [ ... ] | |
| +----------------------------------------------------------------------+ |
| |
| +----------------------------------------------------------------------+ |
| | Mobile App Redesign ACTIVE [==> ] 1/5 phases | |
| | | |
| | [ View ] [Spawn Architect v] [ ... ] | |
| +----------------------------------------------------------------------+ |
| |
| +----------------------------------------------------------------------+ |
| | API Documentation COMPLETED [========] 4/4 phases | |
| | | |
| | [ View ] [Spawn Architect v] [ ... ] | |
| +----------------------------------------------------------------------+ |
| |
+============================================================================+
```
## Status Filter Dropdown
```
[ All v]
+--------------+
| All |
| Active |
| Completed |
| Archived |
+--------------+
```
## Initiative Card Detail
```
+------------------------------------------------------------------------+
| Initiative Name |
| |
| [STATUS] [==========> ] 3/7 phases |
| |
| [ View ] [Spawn Architect v] [ ... ] |
+------------------------------------------------------------------------+
| |
v v
+------------+ +----------+
| Discuss | | Archive |
| Plan | | Delete |
+------------+ +----------+
```
- **Status badge**: Color-coded (green=active, grey=completed, etc.)
- **Progress bar**: Green when 100%, blue otherwise
- **Spawn Architect dropdown**: Discuss / Plan options
- **More menu (...)**: Archive / Delete (with `window.confirm`, Shift+click bypasses)
## Empty State
```
+============================================================================+
| |
| Initiatives [ + New Initiative ] |
| |
| |
| No initiatives yet |
| |
| [ Create your first initiative ] |
| |
| |
+============================================================================+
```
## Loading State
```
+============================================================================+
| |
| Initiatives [ + New Initiative ] |
| |
| +----------------------------------------------------------------------+ |
| | ░░░░░░░░░░░░░░░░░░░░░░░ | |
| | ░░░░░░░░░░░░░ | |
| +----------------------------------------------------------------------+ |
| +----------------------------------------------------------------------+ |
| | ░░░░░░░░░░░░░░░░░░░░░░░ | |
| | ░░░░░░░░░░░░░ | |
| +----------------------------------------------------------------------+ |
| +----------------------------------------------------------------------+ |
| | ░░░░░░░░░░░░░░░░░░░░░░░ | |
| | ░░░░░░░░░░░░░ | |
| +----------------------------------------------------------------------+ |
| |
+============================================================================+
```
## Source
- `packages/web/src/routes/initiatives/index.tsx`
- `packages/web/src/components/InitiativeList.tsx`
- `packages/web/src/components/InitiativeCard.tsx`

225
docs/wireframes/plan-tab.md Normal file
View File

@@ -0,0 +1,225 @@
# Plan Tab (`?tab=plan`)
Two-column layout: phase sidebar (260px) + phase detail panel.
## Default State (phases exist, one selected)
```
+============================================================================+
| < Back |
| Auth System Overhaul [ACTIVE] [YOLO] [git] main [P] backend |
| [ Content ] [*Plan*] [ Execution ] [ Review ] |
+============================================================================+
| | |
| PHASES [+][detail] Phase 2: Implement OAuth [READY] [...] |
| | |
| +--------+ | +--------------------------------------------------------+ |
| | 1. DB | | | | |
| | Schema | | | Implement the OAuth 2.0 authorization code flow | |
| | [DONE] | | | with PKCE extension for public clients. | |
| | 3/3 | | | | |
| +--------+ | | Support Google, GitHub, and Microsoft as identity | |
| +--------+ | | providers with configurable scopes. | |
| | 2. OAuth| | | | |
| | Flow | | +--------------------------------------------------------+ |
| |*[READY]*| | |
| | 0 tasks| | Dependencies |
| | dep: 1 | | [+ Add dependency v] |
| +--------+ | * Phase 1: DB Schema [DONE] [x] |
| +--------+ | |
| | 3. UI | | Tasks (0/5) |
| | [PEND] | | ├── Set up OAuth routes [PENDING] [x] |
| | 5 tasks| | ├── Implement PKCE flow [PENDING] [x] |
| | dep:1,2| | ├── Google provider adapter [RUNNING] agent-1 [x] |
| +--------+ | ├── GitHub provider adapter [BLOCKED] [x] |
| | | blocked by: Google provider adapter |
| 260px | └── Microsoft provider adapter [PENDING] [x] |
| | |
+============================================================================+
```
## Phase Sidebar
```
+------------+
| PHASES [+][sparkles] <-- [+] adds phase, [sparkles] details all phases
| |
| +--------+ |
| | 1 | | Phase number
| | DB | | Phase name (truncated)
| | Schema | |
| | [DONE] | | StatusBadge (small)
| | 3/3 | | "X/Y tasks" count
| +--------+ |
| +--------+ |
| |*2 *| | * = active/selected (left blue border + accent bg)
| | OAuth | |
| | Flow | |
| |[READY] | |
| | 0 tasks| | "Needs decomposition" if 0 tasks
| | dep: 1 | | "depends on: Phase X" (if dependencies)
| +--------+ |
| |
| [New phase name___] <-- inline input when adding
| |
+------------+
```
## Phase Actions (sidebar header)
```
PHASES [Detailing (2)] [+] [Detail All]
^^^^^^^^^^^^^^ ^^^^^^^^^^^
spinner when agents sparkles icon
are detailing disabled if no eligible phases
```
## Phase Detail Panel
### Header
```
+------------------------------------------------------------------------+
| Phase 2: Implement OAuth Flow [READY] [git] branch [...] |
| | |
| branch badge v
| +--------+
| | Delete |
| | Phase |
| +--------+
+------------------------------------------------------------------------+
```
- Phase name is editable (click to toggle inline input)
- `[...]` dropdown: Delete Phase
### When No Tasks and No Agent Running
```
+------------------------------------------------------------------------+
| Phase 2: Implement OAuth Flow [READY] [ Detail Tasks ] |
+------------------------------------------------------------------------+
```
### Detailing In Progress
```
+------------------------------------------------------------------------+
| Phase 2: Implement OAuth Flow [READY] [spinner] Detailing |
+------------------------------------------------------------------------+
```
### Pending Review Banner
```
+------------------------------------------------------------------------+
| [!] This phase is pending review. Go to the Review tab to review. |
+------------------------------------------------------------------------+
```
### Phase Content Editor
```
+------------------------------------------------------------------------+
| Implement the OAuth 2.0 authorization code flow with PKCE |
| extension for public clients. |
| |
| Support Google, GitHub, and Microsoft as identity providers |
| with configurable scopes. |
+------------------------------------------------------------------------+
```
Tiptap editor, auto-saves via `usePhaseAutoSave`.
### Dependencies Section
```
Dependencies
[+ Add dependency v] <-- dropdown of other phases
* Phase 1: DB Schema [DONE] [x] <-- status dot + remove button
* Phase 4: Testing [PENDING] [x]
```
### ChangeSet Banner (after detail agent completes)
```
+------------------------------------------------------------------------+
| [v] 5 tasks created [>] expand |
| |
| + task "Set up OAuth routes" |
| + task "Implement PKCE flow" |
| + task "Google provider adapter" |
| + task "GitHub provider adapter" |
| + task "Microsoft provider adapter" |
| |
| [ Revert ] [ Dismiss ] |
+------------------------------------------------------------------------+
```
### Tasks Section
```
Tasks (3/5)
├── Set up OAuth routes [PENDING] [x]
├── Implement PKCE flow [PENDING] [x]
├── Google provider adapter [RUNNING] agent: blue-fox-7 [x]
├── GitHub provider adapter [BLOCKED] [x]
| blocked by: Google provider adapter
└── Microsoft provider adapter [PENDING] [x]
```
- Tree connectors: `├──` for middle items, `└──` for last
- Agent name links to `/inbox` when assigned
- Delete `[x]` appears on hover (Shift+click bypasses confirm)
- `<DependencyIndicator>` shown below blocked tasks
- Clicking a task row opens `<TaskDetailModal>`
## Empty State (no phases)
```
+============================================================================+
| | |
| PHASES [+] | |
| | No phases yet |
| | |
| | [spinner] Planning phases... |
| | -- or -- |
| | [sparkles Plan Phases] or [ Add Phase ] |
| | |
+============================================================================+
```
## Task Detail Modal (overlay)
```
+----------------------------------------------------------+
| Set up OAuth routes [x] |
| |
| Status [PENDING] | Priority normal |
| Phase 2. OAuth Flow | Type execute |
| Agent (none) | |
| |
| Description |
| Create Express routes for /auth/login, /auth/callback, |
| and /auth/logout with proper middleware chain. |
| |
| Dependencies |
| * DB Schema Migration [DONE] |
| |
| Blocks |
| * GitHub provider adapter [BLOCKED] |
| |
| [ Queue Task ] [ Stop Task ] |
+----------------------------------------------------------+
```
## Source
- `packages/web/src/components/ExecutionTab.tsx`
- `packages/web/src/components/execution/PhaseSidebarItem.tsx`
- `packages/web/src/components/execution/PhaseDetailPanel.tsx`
- `packages/web/src/components/execution/PhaseActions.tsx`
- `packages/web/src/components/execution/PlanSection.tsx`
- `packages/web/src/components/TaskRow.tsx`
- `packages/web/src/components/TaskDetailModal.tsx`

215
docs/wireframes/review-tab.md Normal file
View File

@@ -0,0 +1,215 @@
# Review Tab (`?tab=review`)
Two-column layout: diff viewer (main) + review sidebar (300px). Shows code diffs for phases pending review.
## Default State
```
+============================================================================+
| < Back |
| Auth System Overhaul [ACTIVE] [REVIEW] [git] main [P] backend |
| [ Content ] [ Plan ] [ Execution ] [*Review*] |
+============================================================================+
| | |
| Phase: [Phase 2: OAuth] [Phase 3: UI] <-- pill selector | Review |
| | |
| +-----------------------------------------------------------+ | Phase 2 |
| | [play] Start Preview | | OAuth |
| +-----------------------------------------------------------+ | Flow |
| | |
| +-----------------------------------------------------------+ |[PENDING] |
| | src/auth/oauth.ts +42 -8 | | |
| |--------------------------------------------------------- | | Author |
| | 37 | import { OAuth2Client } from 'google...' | | agent-3 |
| | 38 | + export async function initOAuth(config) { | | |
| | 39 | + const client = new OAuth2Client({ | | Branch |
| | 40 | + clientId: config.clientId, | | cw/auth |
| | 41 | + clientSecret: config.clientSecret, | | -> main |
| | 42 | + }); | | |
| | 43 | + return client; | |----------+
| | 44 | + } | | |
| | | | |[Approve] |
| | 58 | - function legacyAuth() { | |[Request |
| | 59 | - // old implementation | | Changes] |
| | 60 | - } | | |
| | | | |----------+
| | [+ Add comment] | | Discuss. |
| +-----------------------------------------------------------+ | 3 cmnts |
| | 2 reslvd |
| +-----------------------------------------------------------+ | 1 open |
| | src/auth/routes.ts +28 -3 | |----------+
| |--------------------------------------------------------- | | Changes |
| | 12 | + router.get('/auth/login', ... | | 4 files |
| | 13 | + router.get('/auth/callback', ... | | +120 -45 |
| | 14 | + router.post('/auth/logout', ... | |----------+
| +-----------------------------------------------------------+ | Files |
| | oauth.ts |
| | (2) +42 |
| | routes.ts|
| | +28 |
| | config.ts|
| | +35 |
| | test.ts |
| | +15 |
+============================================================================+
```
## Phase Selector (multiple phases pending review)
```
Phase: [*Phase 2: OAuth*] [Phase 3: UI Components]
^^^^^^^^^^^^^^^^
active pill (filled background)
```
Only shown when 2+ phases are in `pending_review` status.
## Preview Panel
### No Preview Running
```
+------------------------------------------------------------------------+
| [play] Start Preview |
+------------------------------------------------------------------------+
```
### Building
```
+------------------------------------------------------------------------+
| [spinner] Building preview... |
+------------------------------------------------------------------------+
```
### Running
```
+------------------------------------------------------------------------+
| [*] Preview running: http://localhost:9100/preview/abc123 [ Stop ] |
+------------------------------------------------------------------------+
```
### Failed
```
+------------------------------------------------------------------------+
| [!] Preview failed [ Retry ]|
+------------------------------------------------------------------------+
```
## Diff Viewer (left panel)
### File Card (expanded)
```
+------------------------------------------------------------------------+
| src/auth/oauth.ts +42 -8 |
|------------------------------------------------------------------------|
| 37 | import { OAuth2Client } from 'google-auth-library'; |
| 38 | + export async function initOAuth(config: OAuthConfig) { |
| 39 | + const client = new OAuth2Client({ |
| 40 | + clientId: config.clientId, |
| 41 | + clientSecret: config.clientSecret, |
| 42 | + }); |
| 43 | + return client; |
| 44 | + } |
| | ... |
| 58 | - function legacyAuth() { |
| 59 | - // old implementation |
| 60 | - } |
| | |
| [+ Add comment] |
+------------------------------------------------------------------------+
```
- Unified diff format with line numbers
- Green `+` lines for additions, red `-` lines for deletions
- Context lines (unchanged) in grey
- Inline comment form: click `[+ Add comment]` to expand textarea
- Hunk separators (`...`) between non-contiguous sections
### Inline Comment Thread
```
| 42 | + }); |
| | +--------------------------------------------------------------+ |
| | | user: Should this use env vars instead of config? | |
| | | [Resolve] | |
| | | | |
| | | [Reply...________________________________] [Comment] | |
| | +--------------------------------------------------------------+ |
| 43 | + return client; |
```
## Review Sidebar (300px, right)
```
+---------------------------+
| Review |
| |
| Phase 2: OAuth Flow |
| [PENDING REVIEW] |
| |
| Author |
| agent-3 (blue-fox) |
| |
| Branch |
| cw/auth-overhaul |
| -> main |
| |
|---------------------------|
| |
| [ Approve ] | <-- disabled if unresolved threads
| [ Request Changes ] |
| |
| -- or after action: -- |
| [v] Approved |
| [!] Changes Requested |
| |
|---------------------------|
| |
| Discussions |
| 3 comments |
| 2 resolved |
| 1 open |
| |
|---------------------------|
| |
| Changes |
| 4 files changed |
| +120 additions |
| -45 deletions |
| |
|---------------------------|
| |
| Files |
| oauth.ts (2) +42-8 | <-- (2) = comment count, clickable
| routes.ts +28-3 |
| config.ts +35-0 |
| test.ts +15-2 |
| |
+---------------------------+
```
- File list items are clickable (scrolls diff viewer to that file)
- Comment count shown per file
- Approve button disabled when unresolved comment threads exist
## Empty State
```
+============================================================================+
| |
| No phases pending review |
| |
+============================================================================+
```
## Source
- `packages/web/src/components/review/ReviewTab.tsx`
- `packages/web/src/components/review/DiffViewer.tsx`
- `packages/web/src/components/review/ReviewSidebar.tsx`
- `packages/web/src/components/review/PreviewPanel.tsx`
- `packages/web/src/components/review/FileCard.tsx`

195
docs/wireframes/settings.md Normal file
View File

@@ -0,0 +1,195 @@
# Settings Pages (`/settings/*`)
Nested layout with sub-navigation tabs: Health Check and Projects.
## Settings Layout
```
+============================================================================+
| CODEWALK DISTRICT |
| [ Initiatives ] [ Agents ] [ Inbox ] [*Settings*] |
+============================================================================+
| |
| Settings |
| |
| [*Health Check*] [ Projects ] |
| ---------------------------------------------------------------- |
| |
| <Settings Page Outlet> |
| |
+============================================================================+
```
`/settings` redirects to `/settings/health`.
---
## Health Check (`/settings/health`)
```
+============================================================================+
| Settings |
| [*Health Check*] [ Projects ] |
| ---------------------------------------------------------------- |
| [Refresh]|
| |
| +----------------------------------------------------------------------+ |
| | [v] Server Status | |
| | | |
| | Uptime: 2h 34m 12s | |
| | Started: 2026-03-02 10:15:00 | |
| +----------------------------------------------------------------------+ |
| |
| Accounts |
| |
| +----------------------------------------------------------------------+ |
| | [v] user@example.com [claude] [pro] | |
| | 2 agents (1 active) Active | |
| | | |
| | Session 5h [=========> ] 45% resets in 2h 15m | |
| | Weekly 7d [====> ] 22% resets in 4d 3h | |
| | Sonnet 7d [======> ] 31% resets in 4d 3h | |
| | Opus 7d [==> ] 12% resets in 4d 3h | |
| | | |
| | Extra usage: $2.40 / $50.00 limit | |
| +----------------------------------------------------------------------+ |
| |
| +----------------------------------------------------------------------+ |
| | [!] team@company.com [claude] [team] | |
| | 0 agents Exhausted until 11:30 AM | |
| | | |
| | Session 5h [=========================] 100% resets in 0h 45m | |
| | Weekly 7d [==================> ] 78% resets in 2d 1h | |
| +----------------------------------------------------------------------+ |
| |
| Projects |
| |
| +----------------------------------------------------------------------+ |
| | [v] backend | |
| | github.com/org/backend-api | |
| | Clone found | |
| +----------------------------------------------------------------------+ |
| |
| +----------------------------------------------------------------------+ |
| | [x] frontend | |
| | github.com/org/frontend-app | |
| | Clone missing | |
| +----------------------------------------------------------------------+ |
| |
+============================================================================+
```
### Account Card Detail
```
+------------------------------------------------------------------------+
| [status-icon] email@example.com [provider] [subscription] |
| N agents (M active) Status text |
| |
| Session 5h [=========> ] 45% resets in 2h 15m |
| Weekly 7d [====> ] 22% resets in 4d 3h |
| Sonnet 7d [======> ] 31% resets in 4d 3h |
| Opus 7d [==> ] 12% resets in 4d 3h |
| |
| Extra usage: $2.40 / $50.00 limit |
+------------------------------------------------------------------------+
```
Status icons:
- `[v]` CheckCircle2 (green) = healthy
- `[!]` AlertTriangle (yellow) = exhausted/warning
- `[x]` XCircle (red) = error
Usage bars are color-coded:
- Green < 50%
- Yellow 50-80%
- Red > 80%
### No Accounts
```
Accounts
+----------------------------------------------------------------------+
| No accounts configured. |
| Run `cw account add` in the CLI to add an account. |
+----------------------------------------------------------------------+
```
### Project Health Card
```
+------------------------------------------------------------------------+
| [v] project-name |
| github.com/org/repo-url |
| Clone found |
+------------------------------------------------------------------------+
+------------------------------------------------------------------------+
| [x] project-name |
| github.com/org/repo-url |
| Clone missing |
+------------------------------------------------------------------------+
```
---
## Projects (`/settings/projects`)
```
+============================================================================+
| Settings |
| [ Health Check ] [*Projects*] |
| ---------------------------------------------------------------- |
| [ Register Project ] |
| |
| +----------------------------------------------------------------------+ |
| | backend | |
| | github.com/org/backend-api | |
| | | |
| | Default branch: main [pencil] [trash] | |
| +----------------------------------------------------------------------+ |
| |
| +----------------------------------------------------------------------+ |
| | frontend | |
| | github.com/org/frontend-app | |
| | | |
| | Default branch: develop [pencil] [trash] | |
| +----------------------------------------------------------------------+ |
| |
+============================================================================+
```
### Inline Branch Editing (click pencil)
```
Default branch: [develop________] [enter to save / esc to cancel]
```
Click pencil icon -> input replaces text -> Enter saves, Escape/blur cancels.
### Empty State
```
+============================================================================+
| Settings |
| [ Health Check ] [*Projects*] |
| ---------------------------------------------------------------- |
| |
| +----------------------------------------------------------------------+ |
| | | |
| | No projects registered | |
| | | |
| | [ Register Project ] | |
| | | |
| +----------------------------------------------------------------------+ |
| |
+============================================================================+
```
## Source
- `packages/web/src/routes/settings.tsx`
- `packages/web/src/routes/settings/health.tsx`
- `packages/web/src/routes/settings/projects.tsx`
- `packages/web/src/components/AccountCard.tsx`