vscode: viewsWelcome stubs for the empty state of Codev sidebar trees (Workspace, Builders, Backlog, Pull Requests)

[amrmelsayed]

Problem

VS Code's empty-editor area (the faded logo + a few keyboard-shortcut hints visible when no editor is open) is rendered by the workbench itself and cannot be replaced by an extension. That platform constraint is upstream; we cannot brand it.

What we can brand is the empty state of every Codev sidebar tree, via the contributes.viewsWelcome extension point. Right now that contribution is empty (viewsWelcome: null in packages/vscode/package.json), so every Codev sidebar view renders blank in its first-launch / no-data state. New users open the sidebar, see no rows in any tree, and have no in-IDE guidance about what to do next.

Codev registers 9 tree views today:

Container	View id	View name
codev	codev.workspace	Workspace
codev	codev.builders	Builders
codev	codev.backlog	Backlog
codev	codev.pullRequests	Pull Requests
codev	codev.recentlyClosed	Recently Closed
codev	codev.team	Team
codev	codev.status	Status
codevPanel	codev.placeholder	Codev
codevPanel	codev.devServer	Codev Dev

The first three (Workspace, Builders, Backlog) are the views a new user looks at most. They're also the ones that take the longest to populate (workspace activation, Tower running, forge auth, at least one issue / one builder existing) so they spend the most time in an empty state.

Adjacent context

• The existing codevGettingStarted walkthrough (3 steps: detect / install / verify) covers first-install CLI setup. It does NOT fire as the empty-editor state and does NOT cover "now that Codev is installed, here's how to use it." This issue is complementary: walkthrough is one-shot onboarding via Help → Welcome; viewsWelcome is a passive in-IDE always-available stub on the views you'd naturally look at.
• VS Code's viewsWelcome API renders markdown content inside the tree view itself when the view has no items. Supports inline command links ([command:codev.foo](command:codev.foo)), so each stub can include direct CTAs to the relevant Codev commands.
• The empty-state copy is shown when the tree is empty for ANY reason (not connected to Tower, no architects registered, no issues in backlog, etc.) so the copy needs to read sensibly across all those modes. Detection of "why empty" via when-clauses is supported (see open question 2).

Proposal

Add contributes.viewsWelcome entries for the four views where the empty state is most user-visible and the CTA is most actionable:

1. codev.workspace (the most-visited Codev view)

Renders when the workspace tree is empty (Tower not running, no workspace registered). Copy directs to the start command:

**Welcome to Codev.** This view shows your architects, the Tower web dashboard, and a way to spawn builders for GitHub issues.

[Start Tower](command:codev.startTower) to begin.

[Get started with Codev](command:workbench.action.openWalkthrough?%22cluesmith.codev%23codevGettingStarted%22) if you haven't installed the CLI yet.

2. codev.builders (empty until a builder spawns)

Renders when no builders are active. Copy explains what a builder is and how to spawn one:

Builders are AI agents that implement features and fixes in isolated worktrees.

[Spawn a builder](command:codev.spawnBuilder) for a GitHub issue.

Want to learn more? Read [`codev/protocols/`](command:vscode.open?%22codev/protocols%22) for the available protocols (SPIR, PIR, AIR, BUGFIX).

3. codev.backlog (empty before forge is connected or before any issues are filed)

Renders with two distinct stubs depending on why the backlog is empty:

• No forge connection: "Codev needs a forge (GitHub) connection. Configure in .codev/config.json or run codev doctor."
• Connected but empty: "No issues match your filter. Show all backlog items or Open issue by number."

(The "Open issue by number" CTA is pending #1096; replace with codev.searchBacklog until that ships.)

4. codev.pullRequests (empty when no open PRs match)

Renders with a short copy explaining the view and a CTA to open the most recent merged PR:

Open pull requests against this repository. The list shows PRs you authored, were requested to review, or that are open against `main`.

When empty, [view recently merged](command:vscode.open?%22<recently-closed-view-url>%22) or [open issue by number](command:codev.openIssueByNumber).

Plan-gate decisions to lock at plan-approval

1. Scope: just these 4 views, or all 9? Lean: the 4 above for v1. codev.recentlyClosed is rarely empty in active workspaces; codev.team / codev.status / codev.placeholder / codev.devServer are situational. Stub them in a follow-up only if real users report being lost there.
2. Per-emptiness-reason stubs (when clauses). viewsWelcome supports when clauses, so different empty-state copy can render based on context keys (e.g. !codev.towerRunning, !codev.forgeConnected, codev.backlogEmpty). Lean: do this for codev.workspace and codev.backlog; one-size-fits-all copy for the simpler cases. Adds a few context-key publishes from extension.ts.
3. CTA command coverage. Some CTAs in the proposal reference commands that don't exist yet (e.g. codev.startTower , verify), or are pending (codev.openIssueByNumber from vscode: codev.openIssueByNumber quick-action + Cmd+K I keybinding for direct issue access #1096). For v1, only reference commands that ship today; substitute or omit CTAs whose target command is unshipped.
4. Voice/length. VS Code's viewsWelcome is a small markdown block (typically 2-4 lines + 1-2 inline CTAs). Avoid long marketing copy; keep each stub short and operational. The proposal above is the upper bound for length per view.
5. Walkthrough as a CTA from viewsWelcome. The Get started with Codev walkthrough link uses the URI-encoded workbench.action.openWalkthrough deep-link. Verify the syntax against bundled VS Code 1.125.

Acceptance criteria

• contributes.viewsWelcome populated in packages/vscode/package.json for at least the 4 views above (codev.workspace, codev.builders, codev.backlog, codev.pullRequests).
• Each stub uses palette-discoverable Codev commands as inline CTAs via command:codev.foo syntax. CTAs target only commands that ship today.
• At least codev.workspace and codev.backlog use when-clause-conditioned stubs so different empty-state reasons render different copy.
• Necessary context keys (e.g. codev.towerRunning, codev.forgeConnected, codev.backlogEmpty) are published by extension.ts if not already.
• The walkthrough deep-link from codev.workspace's stub correctly opens the existing codevGettingStarted walkthrough.
• No regression to populated states of any of the 9 views; the welcome stubs only render when the view is empty.
• Tests verify the package.json viewsWelcome shape (snapshot test or assertions on view-id coverage + CTA command names exist in contributes.commands).

Out of scope

• Replacing VS Code's empty-editor background (the faded logo + Open Chat / Show All Commands / Find in Files shortcuts shown when no editor is open). That surface is owned by the VS Code workbench and is not exposed to extensions; not addressable from Codev.
• Extending the existing codevGettingStarted walkthrough with more steps. That's a separate (filed-if-needed) enhancement; this issue is the always-available passive surface, not the one-shot guided one.
• Auto-opening a codev/HOME.md or the artifact-canvas preview on workspace activation. Intrusive; reshapes user layout; not the right hammer for empty-state guidance.
• Status-bar branding (a persistent Codev chip). Different surface, different concern, file separately if wanted.
• Per-architect viewsWelcome for the future "no architects registered" state on Workspace tab (feat(vscode): Architects tree — Add Architect UI, Cmd+K A picker, label casing #841 / PR feat(vscode): Architects tree — Add Architect UI, Cmd+K A picker, UPPERCASE labels #1082 already lists architects from Tower state; the empty case is "Tower not connected", which codev.workspace's stub above covers).

Protocol selection

Pure additive package.json + small extension.ts context-key publishing (if any of the keys aren't already published). No runtime behavior change. Roughly 60-120 LOC including the snapshot test. AIR fits cleanly; BUGFIX is a poor fit (additive, not a fix); PIR is overkill (no design ambiguity beyond the 5 plan-gate items above).

Related

• codevGettingStarted walkthrough (already in package.json): adjacent surface; this issue's empty-states link to it as the install-onboarding CTA.
• vscode: codev.openIssueByNumber quick-action + Cmd+K I keybinding for direct issue access #1096: codev.openIssueByNumber (referenced as a CTA in the backlog + PR stubs; substitute codev.searchBacklog until vscode: codev.openIssueByNumber quick-action + Cmd+K I keybinding for direct issue access #1096 ships).
• feat(vscode): Architects tree — Add Architect UI, Cmd+K A picker, label casing #841 / PR feat(vscode): Architects tree — Add Architect UI, Cmd+K A picker, UPPERCASE labels #1082: Add Architect UI (sibling sidebar polish work).
• vscode: sync Builders sidebar selection with the active builder-diff file #1066 / PR vscode: sync Builders sidebar selection with the active builder-diff file (#1066) #1075: Builders sidebar auto-reveal (sibling sidebar polish).
• packages/vscode/package.json: where the viewsWelcome contribution lands.
• VS Code API reference: contributes.viewsWelcome (https://code.visualstudio.com/api/references/contribution-points#contributes.viewsWelcome).