mintree 0.1.10 → 0.2.0

package/README.md

@@ -4,12 +4,12 @@
 
 mintree wraps the steps you do manually every time a feature begins:
 
-1. Pick an issue assigned to you on GitHub.
-2. Create a git worktree on a branch named after that issue, following the project's convention.
+1. Pick an open issue or work item assigned to you (GitHub Issues or Plane).
+2. Create a git worktree on a branch named after that item, following the project's convention.
 3. Launch Claude Code inside the worktree with a session ID you can resume later.
 4. Live-track which Claude sessions are active, idle, or waiting.
 
-It is a smaller, opinionated cousin of [santree](https://github.com/santiagotoscanini/santree) — built on the same TypeScript + Ink + Pastel stack but stripped to GitHub-only and aligned with the `<type>/<issue>-<desc>` branch convention.
+It is a smaller, opinionated cousin of [santree](https://github.com/santiagotoscanini/santree) — built on the same TypeScript + Ink + Pastel stack but stripped to the `<type>/<issue>-<desc>` branch convention and the two issue trackers most likely to be used by a small team: GitHub Issues and Plane.
 
 ---
 
@@ -48,7 +48,7 @@ EOF
 
 `mintree doctor` should report **all required checks pass** before you continue. The most common gaps are:
 
-- `gh` not authenticated → `gh auth login`
+- `gh` not authenticated → `gh auth login` (still needed when using Plane — mintree uses `gh` for PR status on worktree branches)
 - Claude Code not installed → `npm install -g @anthropic-ai/claude-code`
 - Shell integration not loaded → re-run the `echo … >> ~/.zshrc` step and start a new shell
 
@@ -60,12 +60,58 @@ In every repository where you want to use mintree:
 
 ```bash
 cd path/to/repo
-mintree init                                   # creates .mintree/, updates .gitignore
-mintree helpers session-signal install         # optional: live session state in the dashboard
+
+# Default: GitHub Issues provider
+mintree init
+
+# Or: Plane provider
+mintree init --provider plane --workspace <your-workspace-slug>
+
+mintree helpers session-signal install   # optional: live session state in the dashboard
 ```
 
 `init` is idempotent — re-running it is a no-op when everything is already in place.
 
+### Picking the issue provider
+
+mintree supports two issue providers, selected per repo via `.mintree/metadata.json`:
+
+- **`github`** (default): lists issues assigned to you on the current repo via `gh`. Transitions to "In Progress" on a Projects v2 board when present.
+- **`plane`**: lists work items assigned to you across a configured set of [Plane](https://plane.so) projects, via the Plane REST API. Transitions to the project's "started" state on `w`.
+
+After `mintree init --provider plane`, edit `.mintree/metadata.json` to add at least one project:
+
+```json
+{
+  "version": 1,
+  "provider": "plane",
+  "issues": {},
+  "plane": {
+    "apiUrl": "https://api.plane.so",
+    "workspaceSlug": "my-team",
+    "projects": [
+      { "id": "<project-uuid>", "identifier": "BACK", "name": "Backend" },
+      { "id": "<project-uuid>", "identifier": "WEB",  "name": "Web" }
+    ]
+  }
+}
+```
+
+You can find each project's UUID in the Plane URL (`app.plane.so/<workspace>/projects/<uuid>/...`). The `identifier` is the short prefix shown on work-item IDs (the `BACK` in `BACK-100`).
+
+Authenticate by setting `PLANE_API_KEY` in your shell, or by writing the key to `~/.mintree/credentials.json`:
+
+```bash
+export PLANE_API_KEY=plane_api_XXXXXXXXXXXXXX
+# or
+cat > ~/.mintree/credentials.json <<'EOF'
+{ "plane": { "apiKey": "plane_api_XXXXXXXXXXXXXX" } }
+EOF
+chmod 600 ~/.mintree/credentials.json
+```
+
+`mintree doctor` validates the key + each configured project's reachability when `provider === "plane"`.
+
 ---
 
 ## Daily flow
@@ -76,15 +122,15 @@ mintree helpers session-signal install         # optional: live session state in
 mintree dashboard
 ```
 
-Opens a full-screen TUI listing your assigned open issues, each row marked with the live state of its Claude session (`● active`, `! waiting`, `○ idle`, `— exited`, `· no session`). The right pane shows the issue body, labels, worktree info, PR status, and live session message.
+Opens a full-screen TUI listing your assigned open issues (or work items), each row marked with the live state of its Claude session (`● active`, `! waiting`, `○ idle`, `— exited`, `· no session`). Rows are grouped by project board and Status. The right pane shows the issue body, labels, worktree info, PR status, and live session message.
 
 | Shortcut | Action                                                                |
 |----------|-----------------------------------------------------------------------|
 | `↑/↓` or `j/k` | Move between issues                                             |
 | `↵`      | Resume Claude in the existing worktree, or open the create overlay if there's none |
 | `w`      | Always open the create overlay (type + kebab description)             |
-| `d`      | Remove the selected worktree (confirmation overlay)                   |
-| `r`      | Manual refresh (auto-refreshes silently every 30s)                    |
+| `d`      | Delete the selected worktree (confirmation overlay)                   |
+| `r`      | Manual refresh (auto-refreshes silently every 5 min)                  |
 | `o`      | Open the issue in your browser                                        |
 | `q`/`Esc`| Quit (or cancel an open overlay)                                      |
 
@@ -97,10 +143,10 @@ Same building blocks, scriptable from any shell:
 ```bash
 # Create a worktree, optionally launch Claude with an initial prompt
 mintree worktree create feat/100-validar-patente
-mintree worktree create feat/100-validar-patente --work --prompt "empezar issue #100"
+mintree worktree create feat/BACK-100-validar-patente --work --prompt "empezar BACK-100"
 
 # Resume Claude in the worktree you're currently inside
-cd .mintree/worktrees/100-validar-patente
+cd .mintree/worktrees/BACK-100-validar-patente
 mintree worktree work
 
 # Inspect / clean up
@@ -127,7 +173,14 @@ mintree enforces:
 
 > `feat`, `fix`, `docs`, `chore`, `refactor`, `test`, `build`, `ci`, `perf`, `style`, `revert`
 
-`<issue>` is the GitHub issue number (no `#`), `<desc>` is lowercase kebab-case. Examples: `feat/42-validacion-patente`, `fix/55-selfie-upload-timeout`.
+`<issue>` is one of:
+
+- Bare digits for GitHub Issues (the issue number, no `#`): `42`, `100`, `1234`
+- `<PROJ>-<digits>` for Plane work items (the human identifier): `BACK-100`, `WEB-7`, `PROJ_X-12`. The prefix is uppercase letters / digits / underscores, matching Plane's project-identifier constraints.
+
+`<desc>` is lowercase kebab-case.
+
+Examples: `feat/42-validacion-patente`, `fix/55-selfie-upload-timeout`, `feat/BACK-100-readme-update`, `fix/WEB-7-modal`.
 
 When the dashboard's `w` overlay opens, it suggests a kebab description capped at 5 words. If your repo has a `docs/conventions/git-workflow.md`, `CONTRIBUTING.md`, or `.claude/skills/` directory, mintree mentions it on the overlay so you can verify the suggestion against your project's rules — then edit the description to match.
 
@@ -139,15 +192,18 @@ When the dashboard's `w` overlay opens, it suggests a kebab description capped a
 <repo>/
 ├── .gitignore                    # gets `.mintree/worktrees/` + session-states/ + metadata.json appended
 └── .mintree/
-    ├── metadata.json             # gitignored. <issue-id> → { base_branch?, session_id? }
+    ├── metadata.json             # gitignored. provider config + <issue-id> → { base_branch?, session_id? }
     ├── worktrees/                # gitignored
-    │   └── 100-validar-patente/  # one directory per active worktree (named <issue>-<desc>)
+    │   ├── 100-validar-patente/      # GH form: <digits>-<desc>
+    │   └── BACK-100-readme-update/   # Plane form: <PROJ-digits>-<desc>
     ├── session-states/           # gitignored
     │   └── 100.json              # live state written by Claude hooks (active/waiting/idle/exited)
     └── init.sh                   # opt-in. Runs in the new worktree post-create (copy .env, install deps, …)
 ```
 
-`metadata.json` is gitignored because the `session_id` is local to your machine — sharing it would only generate noise.
+`metadata.json` is gitignored because the `session_id` is local to your machine — sharing it would only generate noise. The `provider` and `plane.*` keys can be re-derived from a Plane workspace if needed; sharing them would just leak local config preference.
+
+Plane authentication lives in `~/.mintree/credentials.json` (user-scoped, not per-repo) or the `PLANE_API_KEY` env var.
 
 ---
 
@@ -163,7 +219,8 @@ When the dashboard's `w` overlay opens, it suggests a kebab description capped a
 
 - `mintree doctor` is the first stop. It surfaces missing tools, unauthenticated CLIs, missing hooks, and gitignore drift.
 - The shell wrapper exports `MINTREE_SHELL_INTEGRATION=1` — if doctor says it's missing, the wrapper isn't being loaded by your shell init file.
-- If the dashboard ever opens with a stale session state, press `r` to force a refetch (the auto-refresh runs every 30s).
+- If the dashboard ever opens with a stale session state, press `r` to force a refetch (the auto-refresh runs every 5 minutes).
+- Plane-side issues (timeouts, rate limits, unexpected response shapes) can be logged to `~/.mintree/plane-debug.log` by running `MINTREE_DEBUG=1 mintree dashboard`. The log is file-only so it never corrupts the Ink-rendered TUI.
 
 ---
 
@@ -171,7 +228,7 @@ When the dashboard's `w` overlay opens, it suggests a kebab description capped a
 
 mintree was written for projects that have:
 
-- GitHub Issues as the only tracker (santree supports both Linear and GitHub).
+- A small set of trackers (GitHub Issues or Plane) — santree supports both Linear and GitHub but is heavier.
 - An established branch convention without the `gh-` prefix santree imposes.
 - Skills (`.claude/skills/`) that own the SDD + TDD flow — mintree intentionally leaves the rich PR-create / PR-review prompts out of scope.
 

package/dist/commands/dashboard.js

@@ -13,7 +13,8 @@ import { ALLOWED_TYPES } from "../lib/branch.js";
 import { runCreate, runCreateDetached } from "../lib/worktreeCreate.js";
 import { runRemove, runRemoveByPath } from "../lib/worktreeRemove.js";
 import { buildCreateMarkers, emitMarkers } from "../lib/markers.js";
-import { transitionIssueToInProgress } from "../lib/githubProject.js";
+import { readMetadata } from "../lib/metadata.js";
+import { createProvider } from "../lib/providers/index.js";
 import { loadDashboard } from "../lib/dashboard.js";
 const require = createRequire(import.meta.url);
 const { version: mintreeVersion } = require("../../package.json");
@@ -115,8 +116,8 @@ function kebabize(title) {
  * the body inline (issue bodies can be long and contain markdown that
  * doesn't survive argv). User can clear or rewrite freely before Enter.
  */
-function defaultPromptForIssue(number, title) {
-    return `Empezá a trabajar el issue #${number} (${title}). Usá \`gh issue view ${number}\` para leer el contexto completo y seguí las convenciones del repo.`;
+function defaultPromptForIssue(id, title) {
+    return `Empezá a trabajar el issue #${id} (${title}). Usá \`gh issue view ${id}\` para leer el contexto completo y seguí las convenciones del repo.`;
 }
 /**
  * Sanitises whatever the user typed into the desc field on every keystroke.
@@ -174,22 +175,22 @@ function FooterRow({ phase, overlayKind, latestVersion, }) {
     if (overlayKind === "remove") {
         return (_jsxs(Box, { children: [_jsx(Text, { bold: true, children: "y/Y" }), _jsx(Text, { dimColor: true, children: " confirm " }), _jsx(Text, { bold: true, children: "n/Esc" }), _jsx(Text, { dimColor: true, children: " cancel" })] }));
     }
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { children: _jsxs(Text, { children: [_jsx(Text, { bold: true, children: "j/k" }), _jsx(Text, { dimColor: true, children: " nav " }), _jsx(Text, { bold: true, children: "\u21B5" }), _jsx(Text, { dimColor: true, children: " work (resume / create) " }), _jsx(Text, { bold: true, children: "w" }), _jsx(Text, { dimColor: true, children: " work (always create) " }), _jsx(Text, { bold: true, children: "d" }), _jsx(Text, { dimColor: true, children: " remove" })] }) }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "r" }), _jsx(Text, { dimColor: true, children: " refresh " }), _jsx(Text, { bold: true, children: "o" }), _jsx(Text, { dimColor: true, children: " open in browser " }), _jsx(Text, { bold: true, children: "PgUp/PgDn" }), _jsx(Text, { dimColor: true, children: "/" }), _jsx(Text, { bold: true, children: "wheel" }), _jsx(Text, { dimColor: true, children: " scroll detail " }), _jsx(Text, { bold: true, children: "q" }), _jsx(Text, { dimColor: true, children: " quit" })] }), latestVersion && (_jsxs(Box, { children: [_jsx(Text, { color: "yellow", children: "(*)" }), _jsx(Text, { dimColor: true, children: ` new version available — v${latestVersion} · npm i -g mintree` })] }))] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { children: _jsxs(Text, { children: [_jsx(Text, { bold: true, children: "j/k" }), _jsx(Text, { dimColor: true, children: " nav " }), _jsx(Text, { bold: true, children: "\u21B5" }), _jsx(Text, { dimColor: true, children: " work (resume / create) " }), _jsx(Text, { bold: true, children: "w" }), _jsx(Text, { dimColor: true, children: " work (always create) " }), _jsx(Text, { bold: true, children: "d" }), _jsx(Text, { dimColor: true, children: " delete" })] }) }), _jsxs(Box, { children: [_jsx(Text, { bold: true, children: "r" }), _jsx(Text, { dimColor: true, children: " refresh " }), _jsx(Text, { bold: true, children: "o" }), _jsx(Text, { dimColor: true, children: " open in browser " }), _jsx(Text, { bold: true, children: "PgUp/PgDn" }), _jsx(Text, { dimColor: true, children: "/" }), _jsx(Text, { bold: true, children: "wheel" }), _jsx(Text, { dimColor: true, children: " scroll detail " }), _jsx(Text, { bold: true, children: "q" }), _jsx(Text, { dimColor: true, children: " quit" })] }), latestVersion && (_jsxs(Box, { children: [_jsx(Text, { color: "yellow", children: "(*)" }), _jsx(Text, { dimColor: true, children: ` new version available — v${latestVersion} · npm i -g mintree` })] }))] }));
 }
 function RemoveOverlayView({ overlay }) {
-    return (_jsxs(Box, { flexGrow: 1, flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: "Remove worktree" }), _jsx(Text, { dimColor: true, children: ` for #${overlay.issue.issue.number}` })] }), _jsx(Box, { marginTop: 0, children: _jsx(Text, { children: overlay.issue.issue.title }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "Branch: " }), _jsx(Text, { color: "cyan", children: overlay.branch ?? `(detached) ${overlay.worktreePath}` })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "State: " }), overlay.dirty ? (_jsx(Text, { color: "yellow", children: "dirty (uncommitted changes will be lost)" })) : (_jsx(Text, { color: "green", children: "clean" }))] })] }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: _jsx(Text, { dimColor: true, children: "Removing the worktree leaves the branch and the issue's session_id in place. You can re-attach later with `mintree worktree create`." }) }), _jsx(Box, { marginTop: 1, children: overlay.dirty ? (_jsxs(Text, { children: ["This worktree is dirty. Press", " ", _jsx(Text, { bold: true, color: "red", children: "Y" }), " ", "to force-remove, ", _jsx(Text, { bold: true, children: "N" }), "/", _jsx(Text, { bold: true, children: "Esc" }), " to cancel."] })) : (_jsxs(Text, { children: ["Press", " ", _jsx(Text, { bold: true, color: "green", children: "y" }), " ", "to remove, ", _jsx(Text, { bold: true, children: "N" }), "/", _jsx(Text, { bold: true, children: "Esc" }), " to cancel."] })) }), overlay.error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", overlay.error] }) }))] }));
+    return (_jsxs(Box, { flexGrow: 1, flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: "Remove worktree" }), _jsx(Text, { dimColor: true, children: ` for ${overlay.issue.issue.id}` })] }), _jsx(Box, { marginTop: 0, children: _jsx(Text, { children: overlay.issue.issue.title }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "Branch: " }), _jsx(Text, { color: "cyan", children: overlay.branch ?? `(detached) ${overlay.worktreePath}` })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "State: " }), overlay.dirty ? (_jsx(Text, { color: "yellow", children: "dirty (uncommitted changes will be lost)" })) : (_jsx(Text, { color: "green", children: "clean" }))] })] }), _jsx(Box, { marginTop: 1, flexDirection: "column", children: _jsx(Text, { dimColor: true, children: "Removing the worktree leaves the branch and the issue's session_id in place. You can re-attach later with `mintree worktree create`." }) }), _jsx(Box, { marginTop: 1, children: overlay.dirty ? (_jsxs(Text, { children: ["This worktree is dirty. Press", " ", _jsx(Text, { bold: true, color: "red", children: "Y" }), " ", "to force-remove, ", _jsx(Text, { bold: true, children: "N" }), "/", _jsx(Text, { bold: true, children: "Esc" }), " to cancel."] })) : (_jsxs(Text, { children: ["Press", " ", _jsx(Text, { bold: true, color: "green", children: "y" }), " ", "to remove, ", _jsx(Text, { bold: true, children: "N" }), "/", _jsx(Text, { bold: true, children: "Esc" }), " to cancel."] })) }), overlay.error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", overlay.error] }) }))] }));
 }
 function CreateOverlayView({ overlay, onDescChange, onPromptChange, }) {
     const labelWidth = 14;
     const isNewBranch = overlay.branchMode === "new";
-    const detachedDesc = kebabize(overlay.issue.issue.title) || `issue-${overlay.issue.issue.number}`;
+    const detachedDesc = kebabize(overlay.issue.issue.title) || `issue-${overlay.issue.issue.id}`;
     const branchPreview = isNewBranch
-        ? `${overlay.type}/${overlay.issue.issue.number}-${overlay.desc}`
+        ? `${overlay.type}/${overlay.issue.issue.id}-${overlay.desc}`
         : `detached @ ${overlay.currentBranch ?? "(unknown)"}`;
     const dirPreview = isNewBranch
-        ? `${overlay.issue.issue.number}-${overlay.desc}`
-        : `${overlay.issue.issue.number}-${detachedDesc}`;
-    return (_jsxs(Box, { flexGrow: 1, flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: "Create worktree" }), _jsx(Text, { dimColor: true, children: ` for #${overlay.issue.issue.number}` })] }), _jsx(Box, { marginTop: 0, children: _jsx(Text, { children: overlay.issue.issue.title }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "branchMode", children: overlay.field === "branchMode" ? "▸ Branch:" : "  Branch:" }) }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "<  " }), _jsx(Text, { color: overlay.field === "branchMode" ? "cyan" : undefined, bold: overlay.field === "branchMode", children: isNewBranch ? "new" : `current (${overlay.currentBranch ?? "?"})` }), _jsx(Text, { dimColor: true, children: "  >" })] }), overlay.field === "branchMode" && _jsx(Text, { dimColor: true, children: "   (use ← / → to toggle)" })] }), isNewBranch && (_jsxs(_Fragment, { children: [_jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "type", children: overlay.field === "type" ? "▸ Type:" : "  Type:" }) }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "<  " }), _jsx(Text, { color: overlay.field === "type" ? "cyan" : undefined, bold: overlay.field === "type", children: overlay.type }), _jsx(Text, { dimColor: true, children: "  >" })] }), overlay.field === "type" && _jsx(Text, { dimColor: true, children: "   (use ← / → to cycle)" })] }), _jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "desc", children: overlay.field === "desc" ? "▸ Description:" : "  Description:" }) }), _jsx(Box, { children: overlay.field === "desc" ? (_jsx(TextInput, { value: overlay.desc, onChange: onDescChange, placeholder: "kebab-case" })) : (_jsx(Text, { children: overlay.desc || "(empty)" })) })] })] })), _jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "prompt", children: overlay.field === "prompt" ? "▸ Prompt:" : "  Prompt:" }) }), _jsx(Box, { children: overlay.field === "prompt" ? (_jsx(TextInput, { value: overlay.prompt, onChange: onPromptChange, placeholder: "(empty = no initial message)" })) : (_jsx(Text, { dimColor: true, children: overlay.prompt || "(empty — Claude starts with no message)" })) })] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: " Checkout:" }) }), _jsx(Text, { color: "green", children: branchPreview })] }), _jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: " Worktree:" }) }), _jsxs(Text, { dimColor: true, children: [".mintree/worktrees/", dirPreview] })] }), _jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: " Mode:" }) }), _jsx(Text, { dimColor: true, children: "--work (Claude launches in the new worktree)" })] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [isNewBranch ? (_jsxs(Text, { dimColor: true, children: ["Suggestion is a kebab of the title (capped at ", SUGGESTED_DESC_MAX_WORDS, " words). Edit it to match your repo's branch conventions."] })) : (_jsxs(Text, { dimColor: true, children: ["Detached HEAD at the tip of ", overlay.currentBranch ?? "the current branch", ". No new branch is created \u2014 commit on a new one with `git switch -c` when ready."] })), isNewBranch && overlay.conventionDoc && (_jsx(Text, { dimColor: true, children: `This repo has \`${overlay.conventionDoc}\` — review it before creating.` }))] }), overlay.error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", overlay.error] }) })), overlay.pending && (_jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "cyan", children: _jsx(Spinner, { type: "dots" }) }), _jsxs(Text, { children: [" ", overlay.pending] })] }))] }));
+        ? `${overlay.issue.issue.id}-${overlay.desc}`
+        : `${overlay.issue.issue.id}-${detachedDesc}`;
+    return (_jsxs(Box, { flexGrow: 1, flexDirection: "column", paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: "cyan", children: "Create worktree" }), _jsx(Text, { dimColor: true, children: ` for ${overlay.issue.issue.id}` })] }), _jsx(Box, { marginTop: 0, children: _jsx(Text, { children: overlay.issue.issue.title }) }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "branchMode", children: overlay.field === "branchMode" ? "▸ Branch:" : "  Branch:" }) }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "<  " }), _jsx(Text, { color: overlay.field === "branchMode" ? "cyan" : undefined, bold: overlay.field === "branchMode", children: isNewBranch ? "new" : `current (${overlay.currentBranch ?? "?"})` }), _jsx(Text, { dimColor: true, children: "  >" })] }), overlay.field === "branchMode" && _jsx(Text, { dimColor: true, children: "   (use ← / → to toggle)" })] }), isNewBranch && (_jsxs(_Fragment, { children: [_jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "type", children: overlay.field === "type" ? "▸ Type:" : "  Type:" }) }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "<  " }), _jsx(Text, { color: overlay.field === "type" ? "cyan" : undefined, bold: overlay.field === "type", children: overlay.type }), _jsx(Text, { dimColor: true, children: "  >" })] }), overlay.field === "type" && _jsx(Text, { dimColor: true, children: "   (use ← / → to cycle)" })] }), _jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "desc", children: overlay.field === "desc" ? "▸ Description:" : "  Description:" }) }), _jsx(Box, { children: overlay.field === "desc" ? (_jsx(TextInput, { value: overlay.desc, onChange: onDescChange, placeholder: "kebab-case" })) : (_jsx(Text, { children: overlay.desc || "(empty)" })) })] })] })), _jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { bold: overlay.field === "prompt", children: overlay.field === "prompt" ? "▸ Prompt:" : "  Prompt:" }) }), _jsx(Box, { children: overlay.field === "prompt" ? (_jsx(TextInput, { value: overlay.prompt, onChange: onPromptChange, placeholder: "(empty = no initial message)" })) : (_jsx(Text, { dimColor: true, children: overlay.prompt || "(empty — Claude starts with no message)" })) })] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: " Checkout:" }) }), _jsx(Text, { color: "green", children: branchPreview })] }), _jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: " Worktree:" }) }), _jsxs(Text, { dimColor: true, children: [".mintree/worktrees/", dirPreview] })] }), _jsxs(Box, { children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: " Mode:" }) }), _jsx(Text, { dimColor: true, children: "--work (Claude launches in the new worktree)" })] })] }), _jsxs(Box, { marginTop: 1, flexDirection: "column", children: [isNewBranch ? (_jsxs(Text, { dimColor: true, children: ["Suggestion is a kebab of the title (capped at ", SUGGESTED_DESC_MAX_WORDS, " words). Edit it to match your repo's branch conventions."] })) : (_jsxs(Text, { dimColor: true, children: ["Detached HEAD at the tip of ", overlay.currentBranch ?? "the current branch", ". No new branch is created \u2014 commit on a new one with `git switch -c` when ready."] })), isNewBranch && overlay.conventionDoc && (_jsx(Text, { dimColor: true, children: `This repo has \`${overlay.conventionDoc}\` — review it before creating.` }))] }), overlay.error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", bold: true, children: ["\u2717 ", overlay.error] }) })), overlay.pending && (_jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "cyan", children: _jsx(Spinner, { type: "dots" }) }), _jsxs(Text, { children: [" ", overlay.pending] })] }))] }));
 }
 function stateChar(state) {
     if (!state)
@@ -203,7 +204,11 @@ function stateChar(state) {
     return "—";
 }
 function IssueListRow({ d, selected, identifierWidth, maxTitleWidth, }) {
-    const idText = `#${d.issue.number}`.padEnd(identifierWidth, " ");
+    // Display the issue id raw (e.g. "AUTH-6", "100"). The `#` prefix is a
+    // GitHub convention that reads as noise for Plane's already-prefixed
+    // ids, and dropping it across the board keeps the dashboard provider-
+    // agnostic.
+    const idText = d.issue.id.padEnd(identifierWidth, " ");
     const icon = stateChar(d.session?.state ?? null);
     const title = truncate(d.issue.title, maxTitleWidth);
     // One single Text with a single string so the background highlight is
@@ -274,35 +279,62 @@ function buildListRows(issues) {
 }
 /**
  * Splits the grouped list into a pinned-header region and a scrollable body
- * windowed around the selected issue. The selected issue's own project and
- * Status headers are lifted out of the scroll flow so they stay visible
- * ("sticky") while paging through a long group — without them the user loses
- * track of which project/status the rows below belong to.
+ * windowed around the selected issue.
  *
- * Navigation is unaffected: it still moves `selectedIndex` over the flat
- * issues array; this only decides what's drawn where.
+ * Sticky pinning only kicks in when the whole list overflows the viewport
+ * AND the selected issue's project header would otherwise be scrolled off
+ * the top. In every other case (list fits, or selection is above its
+ * project header) the layout is rendered natively — moving the project
+ * label out of its natural position when there's no scrolling to track
+ * is purely confusing.
+ *
+ * Status headers are never pinned: they're short groups in close vertical
+ * proximity to their items, so the user always sees them inline. Pinning
+ * them was previously breaking grouping when the body window spanned
+ * multiple status sub-groups.
  */
 function windowListRows(listRows, selectedIndex, viewportRows) {
     const selRow = listRows.findIndex((r) => r.kind === "issue" && r.index === selectedIndex);
     const anchor = selRow >= 0 ? selRow : 0;
-    // Walk back from the selected row to find its enclosing project and Status
-    // headers. A "Sin proyecto" issue has a project header but no status one.
+    // If the entire list fits in the viewport, no scrolling will happen and
+    // pinning would just visually displace headers without serving any
+    // purpose. Render the list flat.
+    if (listRows.length <= viewportRows) {
+        return {
+            sticky: [],
+            body: [...listRows],
+            issuesAbove: 0,
+            issuesBelow: 0,
+        };
+    }
+    // Otherwise, decide if the project header needs to be pinned. It does iff
+    // the body window we'd render — centred on the anchor — would not include
+    // the project header itself. When it would, the user sees the header in
+    // place and pinning is again redundant.
     let projIdx = -1;
-    let statusIdx = -1;
     for (let i = anchor; i >= 0; i--) {
         const r = listRows[i];
         if (!r)
             continue;
-        if (statusIdx === -1 && r.kind === "status")
-            statusIdx = i;
         if (r.kind === "project") {
             projIdx = i;
             break;
         }
     }
-    // Pinned rows are pulled out of the body so they never render twice. The
-    // blank spacer that precedes a project header is dropped too, so the pane
-    // doesn't open with an empty line.
+    const tentativeMaxStart = Math.max(0, listRows.length - viewportRows);
+    const tentativeStart = Math.max(0, Math.min(tentativeMaxStart, anchor - Math.floor(viewportRows / 2)));
+    const projectVisibleInWindow = projIdx >= 0 && projIdx >= tentativeStart;
+    if (projectVisibleInWindow) {
+        const end = Math.min(listRows.length, tentativeStart + viewportRows);
+        return {
+            sticky: [],
+            body: listRows.slice(tentativeStart, end),
+            issuesAbove: listRows.slice(0, tentativeStart).filter((r) => r.kind === "issue").length,
+            issuesBelow: listRows.slice(end).filter((r) => r.kind === "issue").length,
+        };
+    }
+    // Project header is above the visible window — pin it (and drop the
+    // preceding spacer so the pane doesn't open with a blank line).
     const pinned = new Set();
     const sticky = [];
     if (projIdx >= 0) {
@@ -312,10 +344,6 @@ function windowListRows(listRows, selectedIndex, viewportRows) {
         if (before && before.kind === "spacer")
             pinned.add(projIdx - 1);
     }
-    if (statusIdx >= 0) {
-        pinned.add(statusIdx);
-        sticky.push(listRows[statusIdx]);
-    }
     const body = [];
     let anchorInBody = 0;
     listRows.forEach((r, i) => {
@@ -418,7 +446,7 @@ function buildDetailLines(d, width) {
     const lines = [];
     const blank = () => [{ text: " " }];
     const w = Math.max(20, width);
-    const titlePrefix = `#${d.issue.number} `;
+    const titlePrefix = `${d.issue.id} `;
     const titleWrapped = wrapLine(d.issue.title, Math.max(8, w - titlePrefix.length));
     titleWrapped.forEach((chunk, i) => {
         if (i === 0) {
@@ -557,8 +585,17 @@ export default function Dashboard() {
         process.stdout.write(ALT_SCREEN_ENTER);
         altScreenEntered.current = true;
     }
+    // Set as the dashboard unmounts. The overlay mouse-pause effect below
+    // re-enables mouse tracking in its cleanup, and that cleanup also fires on
+    // unmount (the create overlay is still open when `confirmCreate` calls
+    // exit()). React runs effect cleanups in mount order, so the overlay's
+    // MOUSE_ON would run *after* the mouse effect's MOUSE_OFF and leave the
+    // terminal capturing the scroll wheel — breaking scroll once Claude takes
+    // over. This flag lets the overlay cleanup skip MOUSE_ON during teardown.
+    const tearingDown = useRef(false);
     useEffect(() => {
         return () => {
+            tearingDown.current = true;
             process.stdout.write(ALT_SCREEN_LEAVE);
         };
     }, []);
@@ -585,10 +622,31 @@ export default function Dashboard() {
         }
         const issues = await loadDashboard(root);
         if (!issues) {
-            setState({
-                phase: "error",
-                message: "Could not fetch issues from GitHub.",
-                hint: "Check `mintree doctor` — gh must be authenticated and the repo must live on GitHub.",
+            const provider = readMetadata(root).provider ?? "github";
+            const message = provider === "plane"
+                ? "Could not fetch work items from Plane."
+                : "Could not fetch issues from GitHub.";
+            const hint = provider === "plane"
+                ? "Check `mintree doctor` — PLANE_API_KEY must be set and the workspace + projects reachable."
+                : "Check `mintree doctor` — gh must be authenticated and the repo must live on GitHub.";
+            setState((prev) => {
+                // Initial load failure → escalate to the full error screen so the
+                // user gets the actionable hint front-and-centre. But once the
+                // dashboard is up, a transient fetch failure (network blip on the
+                // 30s auto-refresh, momentary API slowness) shouldn't blow away
+                // what's already on screen — surface a toast and let the next
+                // refresh recover.
+                if (prev.phase !== "ready") {
+                    return { phase: "error", message, hint };
+                }
+                return {
+                    ...prev,
+                    refreshing: false,
+                    toast: {
+                        kind: "error",
+                        text: `${message} Showing last known data — press \`r\` to retry.`,
+                    },
+                };
             });
             return;
         }
@@ -690,12 +748,20 @@ export default function Dashboard() {
             return;
         process.stdout.write(MOUSE_OFF);
         return () => {
+            // Skip on unmount: re-enabling mouse tracking here would survive the
+            // dashboard exit and break scroll in the terminal Claude inherits.
+            if (tearingDown.current)
+                return;
             process.stdout.write(MOUSE_ON);
         };
     }, [state.phase === "ready" && state.overlay ? state.overlay.kind : null]);
-    // Auto-refresh every 30s while the dashboard is idle. Skipped while an
-    // overlay is open so we don't yank state from under a confirmation, and
-    // while a manual refresh is in flight to avoid stomping on its spinner.
+    // Auto-refresh every 5 minutes while the dashboard is idle. 30s was too
+    // aggressive for an issue list — most of the time nothing has changed,
+    // and with multiple Plane projects configured each refresh fires N×2
+    // API calls. Press `r` for an immediate refresh when something
+    // changed externally. Skipped while an overlay is open so we don't yank
+    // state from under a confirmation, and while a manual refresh is in
+    // flight to avoid stomping on its spinner.
     const stateRef = useRef(state);
     useEffect(() => {
         stateRef.current = state;
@@ -710,7 +776,7 @@ export default function Dashboard() {
             if (s.refreshing)
                 return;
             void refresh();
-        }, 30_000);
+        }, 5 * 60 * 1000);
         return () => clearInterval(id);
     }, []);
     useInput((input, key) => {
@@ -826,8 +892,8 @@ export default function Dashboard() {
                 branchMode: "new",
                 currentBranch: root ? getCurrentBranch(root) : null,
                 type: "feat",
-                desc: kebabize(issue.issue.title) || `issue-${issue.issue.number}`,
-                prompt: defaultPromptForIssue(issue.issue.number, issue.issue.title),
+                desc: kebabize(issue.issue.title) || `issue-${issue.issue.id}`,
+                prompt: defaultPromptForIssue(issue.issue.id, issue.issue.title),
                 field: "branchMode",
                 error: null,
                 conventionDoc: root ? findBranchConventionDoc(root) : null,
@@ -921,15 +987,15 @@ export default function Dashboard() {
         if (state.phase !== "ready")
             return;
         const prompt = overlay.prompt.trim();
-        const issueNumber = overlay.issue.issue.number;
+        const issueId = overlay.issue.issue.id;
         let result;
         if (overlay.branchMode === "current") {
             // Detached worktree off the main repo's current branch. Desc comes
             // from the issue title (kebabized), not user input — keeping the
             // "current branch" flow as low-friction as possible.
-            const descKebab = kebabize(overlay.issue.issue.title) || `issue-${issueNumber}`;
+            const descKebab = kebabize(overlay.issue.issue.title) || `issue-${issueId}`;
             result = runCreateDetached({
-                issueId: String(issueNumber),
+                issueId,
                 descKebab,
                 work: true,
                 ...(prompt.length > 0 ? { prompt } : {}),
@@ -944,7 +1010,7 @@ export default function Dashboard() {
                 });
                 return;
             }
-            const branch = `${overlay.type}/${issueNumber}-${desc}`;
+            const branch = `${overlay.type}/${issueId}-${desc}`;
             result = runCreate(branch, {
                 work: true,
                 ...(prompt.length > 0 ? { prompt } : {}),
@@ -968,7 +1034,8 @@ export default function Dashboard() {
         const repoRoot = findMainRepoRoot();
         if (repoRoot) {
             try {
-                await transitionIssueToInProgress(repoRoot, issueNumber);
+                const provider = createProvider(repoRoot);
+                await provider.transitionIssueToInProgress(issueId);
             }
             catch {
                 // best effort — surface via doctor / next dashboard refresh
@@ -1043,7 +1110,7 @@ export default function Dashboard() {
     const listWidthPct = 0.4;
     const listWidth = Math.max(32, Math.floor(columns * listWidthPct));
     const detailWidth = columns - listWidth - 2; // border slack
-    const identifierWidth = Math.max(3, ...issues.map((d) => `#${d.issue.number}`.length));
+    const identifierWidth = Math.max(3, ...issues.map((d) => d.issue.id.length));
     // Lista ocupa todo menos: "  #N  ICON  " (2-space nest indent + id + icon).
     const maxTitleWidth = Math.max(8, listWidth - identifierWidth - 9);
     // Reserve rows: header (2), top borders (1), footer (3).