Skip to content

Commit 4a11b04

Browse files
amrmelsayedamrmelsayed
committed
[Spec 0602] Add architect editor-split layout and inline UX walkthrough
- Architect terminal opens as a side editor (full vertical height) via workbench.action.terminal.moveIntoEditor + vertical split - Builders/shells stay in the bottom terminal panel - Merge UX walkthrough (browser vs VS Code comparison) into the spec - Delete standalone walkthrough file
1 parent ebc6b9b commit 4a11b04

1 file changed

Lines changed: 190 additions & 1 deletion

File tree

‎codev/specs/0602-vscode-extension.md‎

Lines changed: 190 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -247,9 +247,31 @@ Each Tower PTY session maps to a VS Code `Pseudoterminal`:
247247
**Opening a terminal:**
248248
1. User triggers "Open Architect Terminal" or "Open Builder #42 Terminal" via Command Palette or TreeView
249249
2. Extension calls `GET /api/terminals` to find the terminal ID
250-
3. Creates WebSocket to `/ws/terminal/:id`
250+
3. Creates WebSocket to `/workspace/:base64path/ws/terminal/:id`
251251
4. Creates `vscode.window.createTerminal({ name: "Architect" | "Builder #42 [implement]", pty })`
252252

253+
**Architect terminal layout (editor split):**
254+
The architect terminal is a native `Pseudoterminal` that opens as a **side editor** for full vertical height — not in the bottom panel. On "Open Architect Terminal":
255+
1. Create the terminal as above
256+
2. Move it into the editor area via `workbench.action.terminal.moveIntoEditor`
257+
3. Split the editor group vertically so architect is on the left, code files on the right
258+
259+
```
260+
┌──────────┬───────────────┬──────────────┐
261+
│ Work View│ Architect │ │
262+
│ TreeView │ (native │ Code Editor │
263+
│ │ terminal) │ │
264+
│ │ │ │
265+
│ ├───────────────┴──────────────┤
266+
│ │ Builder terminals (bottom) │
267+
└──────────┴──────────────────────────────┘
268+
```
269+
270+
This mirrors the browser dashboard's split-pane layout (architect left, content right) while using native VS Code terminals with full keyboard handling. The user can resize or rearrange freely. Builder and shell terminals remain in the bottom panel.
271+
272+
**Builder/shell terminals:**
273+
Builders and shells open in the standard bottom terminal panel. Named `Builder #42 [implement]`, `Shell #1`, etc.
274+
253275
**Binary protocol adapter:**
254276
- **Inbound** (`0x01` data): `slice(1)` → `TextDecoder.decode()` → `onDidWrite.fire(string)`
255277
- **Inbound** (`0x00` control): Parse JSON, handle ping/pong/seq
@@ -627,6 +649,173 @@ Spec 0066 was written against a fundamentally different architecture (tmux + tty
627649
**Relationship to browser dashboard:**
628650
This extension is additive. The browser dashboard continues to work. Both UIs consume the same Tower API. No server-side changes are required for the initial version. Future Tower API enhancements (e.g., a multi-topic WebSocket for state + terminals on one connection) would benefit both clients.
629651

652+
## UX Walkthrough: Browser Dashboard vs VS Code Extension
653+
654+
### Starting Up
655+
656+
**Browser today:**
657+
1. Run `afx tower start`
658+
2. Open browser to `localhost:4100`
659+
3. See the full dashboard — architect terminal on the left, work view on the right
660+
661+
**VS Code:**
662+
1. Run `afx tower start` (same)
663+
2. Open your project in VS Code — extension auto-activates when it detects `codev/` directory
664+
3. Status bar at the bottom shows `$(server) 3 builders · 1 blocked`
665+
4. Sidebar has a "Codev Agent Farm" panel with your Work View TreeView
666+
5. Open the architect terminal — it splits the editor vertically (architect left, code right)
667+
6. No browser needed
668+
669+
```
670+
┌──────────┬───────────────┬──────────────┐
671+
│ Work View│ Architect │ │
672+
│ TreeView │ (native │ Code Editor │
673+
│ │ terminal) │ │
674+
│ │ │ │
675+
│ ├───────────────┴──────────────┤
676+
│ │ Builder terminals (bottom) │
677+
└──────────┴──────────────────────────────┘
678+
```
679+
680+
### Monitoring Builders
681+
682+
**Browser today:**
683+
- Work View tab on the right panel — builder cards showing status, phase, progress
684+
- Click a builder card to switch to its terminal tab
685+
- Needs Attention section at the top highlights blocked gates
686+
687+
**VS Code:**
688+
- TreeView sidebar always visible alongside your code — no tab switching
689+
- Expand "Builders" to see `#42 password-hashing [implement] ● running`
690+
- "Needs Attention" node at the top: `#44 api-refactor — blocked on plan-approval (12m)`
691+
- Status bar gives you the count at a glance without even looking at the sidebar
692+
693+
**Key difference:** In the browser, monitoring builders means you're *in the dashboard*. In VS Code, you see builder state *while editing code* — it's peripheral information, not a separate context.
694+
695+
### Opening a Builder Terminal
696+
697+
**Browser today:**
698+
- Click the builder's tab in the tab bar (e.g., "Builder #42")
699+
- xterm.js renders the terminal in the right panel
700+
- You can see the architect terminal simultaneously in the left panel (split pane)
701+
702+
**VS Code:**
703+
- Right-click builder in TreeView → "Open Terminal", or `Cmd+Shift+P` → "Codev: Open Builder Terminal"
704+
- Terminal opens in VS Code's bottom terminal panel
705+
- Architect stays in the left editor split, code on the right, builders at the bottom
706+
- You can see architect + code + builder simultaneously
707+
708+
**Key difference:** Both give you a split layout. The browser's is purpose-built (architect left, content right). VS Code's uses native editor splits and terminal panel — the architect is a side editor at full vertical height, builders are in the bottom panel, and your code is always visible.
709+
710+
### Sending a Message to a Builder
711+
712+
**Browser today:**
713+
- Switch to architect terminal tab
714+
- Type `afx send 42 "implement the password hashing function"`
715+
- Or use the inline send UI
716+
717+
**VS Code:**
718+
- Option A: Type `afx send 42 "..."` in any VS Code terminal (identical to today)
719+
- Option B: `Cmd+Shift+P` → "Codev: Send Message" → pick builder from dropdown → type message in input box → done
720+
- Option C: Right-click builder #42 in TreeView → "Send Message"
721+
722+
**Key difference:** The Command Palette flow is faster than switching to the architect terminal. You can send a message without leaving the file you're editing.
723+
724+
### Clicking a File Path in Terminal Output
725+
726+
**Browser today:**
727+
- Builder terminal shows `/src/auth/hash.ts:42`
728+
- Click it → opens in the browser's built-in file viewer (Shiki highlighting, line numbers)
729+
- It's a read-only viewer — you can't edit there
730+
731+
**VS Code:**
732+
- Builder terminal shows `/src/auth/hash.ts:42`
733+
- Click it → opens in VS Code's editor at line 42
734+
- You're immediately in a full editor — syntax highlighting, IntelliSense, go-to-definition, edit in place
735+
736+
**Key difference:** This is the single biggest UX improvement. Today, file clicks dead-end in a read-only viewer. In VS Code, they land you exactly where you need to be to take action.
737+
738+
### Approving a Gate
739+
740+
**Browser today:**
741+
- See "Needs Attention" in Work View
742+
- Switch to your terminal
743+
- Run `porch approve 44 plan-approval`
744+
745+
**VS Code:**
746+
- Status bar shows `$(bell) Gate: plan-approval #44`
747+
- Click it → approval prompt appears
748+
- Or `Cmd+Shift+P` → "Codev: Approve Gate" → pick from list
749+
- Or right-click the blocked builder in TreeView → "Approve Gate"
750+
751+
**Key difference:** Three clicks vs switching context to a terminal and typing a command.
752+
753+
### Spawning a New Builder
754+
755+
**Browser today:**
756+
- Switch to architect terminal
757+
- Type `afx spawn 190 --protocol spir`
758+
759+
**VS Code:**
760+
- `Cmd+Shift+P` → "Codev: Spawn Builder"
761+
- Quick-pick: enter issue number → pick protocol → optionally enter branch name
762+
- Builder spawns, appears in TreeView, terminal becomes available
763+
764+
**Key difference:** Guided flow vs remembering CLI syntax. Also supports `--branch` for continuing on existing PR branches.
765+
766+
### Reviewing Code (Annotations)
767+
768+
**Browser today:**
769+
- `afx open file.ts` → opens in browser annotation viewer
770+
- Click the "+" gutter button → type a `REVIEW(@architect)` comment
771+
- Comment is written directly into the file
772+
773+
**VS Code:**
774+
- Open the file normally in your editor
775+
- Click the native "+" gutter icon (same as GitHub PR inline comments)
776+
- Type your review comment → it inserts `// REVIEW(@architect): text` into the file
777+
- Same file format — interoperable with the browser dashboard
778+
779+
**Key difference:** Uses VS Code's native Comments API instead of a custom web UI. Feels like doing a PR review inline.
780+
781+
### Team & Analytics
782+
783+
**Browser today:**
784+
- Team tab shows member cards, activity feed, messages
785+
- Analytics tab shows Recharts charts (merged PR metrics, wall-clock hours)
786+
787+
**VS Code:**
788+
- `Cmd+Shift+P` → "Codev: View Team" or "Codev: View Analytics"
789+
- Opens as a Webview panel (essentially the same React components embedded in VS Code)
790+
- Data proxied securely through the extension host
791+
792+
**Key difference:** Minimal — these are Webview panels, so the experience is similar. The benefit is not having to switch to a browser to see them.
793+
794+
### What VS Code Loses
795+
796+
| Feature | Why |
797+
|---------|-----|
798+
| **Curated split pane** | Browser's layout is automatic. VS Code requires a one-time "Open Architect Terminal" action to set up the split, but then mirrors the same layout. |
799+
| **Mobile layout** | Browser dashboard has a mobile-responsive view. VS Code is desktop-only. |
800+
| **Rich file viewer** | Browser handles images, video, PDF, 3D models inline. VS Code handles most natively except 3D. |
801+
| **Multi-workspace overview** | Browser dashboard shows all workspaces at once. VS Code scopes to the open workspace by default. |
802+
| **Remote access** | Browser works through cloud tunnel for remote collaboration. VS Code extension is local-only (unless using VS Code Remote SSH). |
803+
804+
### What VS Code Gains
805+
806+
| Feature | Why |
807+
|---------|-----|
808+
| **Zero context switching** | Never leave the IDE |
809+
| **Native file editing** | File clicks → real editor, not a viewer |
810+
| **Command Palette** | All operations keyboard-accessible |
811+
| **Peripheral monitoring** | Builder state visible while coding |
812+
| **Native review comments** | Gutter "+" feels like PR reviews |
813+
| **IDE integration** | IntelliSense, go-to-definition, git, extensions all available alongside |
814+
815+
### Summary
816+
817+
The browser dashboard is a **dedicated control center** — best for monitoring multiple builders, remote access, and the curated split-pane experience. The VS Code extension is for **staying in flow** — you see builder state, send messages, approve gates, and click into files without ever leaving your editor.
818+
630819
**Dashboard features deliberately excluded from the extension:**
631820
- **File tree browser** — VS Code's native Explorer is superior; no need to replicate
632821
- **Rich file viewer** (images, video, PDF, 3D models) — VS Code handles all natively except 3D; not worth a custom viewer

0 commit comments

Comments
 (0)