Define the :Forge master picker / home workflow #59

New issue

Closed

opened 2026-04-05 04:04:27 +00:00 by barrettruth · 2 comments

barrettruth commented

2026-04-05 04:04:27 +00:00

Summary

Define what the :Forge entry point should be as a master picker / home workflow.

Today :Forge is mostly a route launcher:

routes.lua builds root sections (prs, issues, ci, branches, commits, worktrees, browse, releases)
each section resolves through vim.g.forge.routes
the resolved route opens a concrete picker from pickers.lua

That works, but the top-level workflow is still thin and hard to reason about.

Important boundary

This issue is about the top-level home/master workflow.

The first-class PR review workflow is tracked separately in #63 and its linked child issues. This issue should not absorb the review-session work itself.

Problems to solve

the root picker does not explain what each section actually does
the overall workflow is not obvious from the top
local git sections (branches, commits, worktrees) are useful but visually lighter than PR/issue/CI surfaces
there is no explicit inventory of route -> command -> action behavior
backend capability differences are implicit rather than documented in one place

Scope

define what the :Forge home/master workflow should be
decide whether the root should remain a route launcher or become a richer first-party home surface
make the top-level UX clearer, especially around local git sections
document or expose the route -> command -> action mapping
document backend capability differences in one place

Deliverables

design note for the :Forge master workflow
explicit inventory of per-route shell commands and actions
visual pass on root/branch/commit/worktree entries and highlighting
backend capability matrix for fzf-lua, snacks, and telescope
recommendation on whether to keep extending the current abstraction or build a first-party picker/client

Nice-to-haves

secondary text in the root picker (route target, scope, or short description)
a way to surface command provenance/debug info from the UI
a public registration API for custom picker backends if the workflow stays backend-agnostic

Consolidates #79.

## Summary Define what the `:Forge` entry point should be as a master picker / home workflow. Today `:Forge` is mostly a route launcher: - `routes.lua` builds root sections (`prs`, `issues`, `ci`, `branches`, `commits`, `worktrees`, `browse`, `releases`) - each section resolves through `vim.g.forge.routes` - the resolved route opens a concrete picker from `pickers.lua` That works, but the top-level workflow is still thin and hard to reason about. ## Important boundary This issue is about the **top-level home/master workflow**. The first-class **PR review workflow** is tracked separately in #63 and its linked child issues. This issue should not absorb the review-session work itself. ## Problems to solve - the root picker does not explain what each section actually does - the overall workflow is not obvious from the top - local git sections (`branches`, `commits`, `worktrees`) are useful but visually lighter than PR/issue/CI surfaces - there is no explicit inventory of route -> command -> action behavior - backend capability differences are implicit rather than documented in one place ## Scope - define what the `:Forge` home/master workflow should be - decide whether the root should remain a route launcher or become a richer first-party home surface - make the top-level UX clearer, especially around local git sections - document or expose the route -> command -> action mapping - document backend capability differences in one place ## Deliverables - [ ] design note for the `:Forge` master workflow - [ ] explicit inventory of per-route shell commands and actions - [ ] visual pass on root/branch/commit/worktree entries and highlighting - [ ] backend capability matrix for `fzf-lua`, `snacks`, and `telescope` - [ ] recommendation on whether to keep extending the current abstraction or build a first-party picker/client ## Nice-to-haves - secondary text in the root picker (route target, scope, or short description) - a way to surface command provenance/debug info from the UI - a public registration API for custom picker backends if the workflow stays backend-agnostic Consolidates #79.

barrettruth commented

2026-04-07 17:38:05 +00:00

Keeping this as the seed idea, but moving the detailed discussion to #87.

#87 is the consolidated planning thread for the :Forge master workflow: philosophy, verified architecture, shell-outs, backend differences, and the concrete first implementation path around root legibility plus the branches/commits/worktrees pickers.

Keeping this as the seed idea, but moving the detailed discussion to #87. #87 is the consolidated planning thread for the `:Forge` master workflow: philosophy, verified architecture, shell-outs, backend differences, and the concrete first implementation path around root legibility plus the branches/commits/worktrees pickers.

barrettruth commented

2026-04-07 19:20:07 +00:00

Superseded by #87, which now serves as the canonical issue for the :Forge master workflow / home-surface lane. PR review remains separately tracked under #63 and its child issues.