mintree 0.4.4 → 0.4.6

package/README.md

@@ -4,12 +4,12 @@
 
 mintree wraps the steps you do manually every time a feature begins:
 
-1. Pick an open issue or work item assigned to you (GitHub Issues or Plane).
+1. Pick an open issue or work item assigned to you (GitHub Issues or Linear).
 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 the `<type>/<issue>-<desc>` branch convention and the two issue trackers most likely to be used by a small team: GitHub Issues and Plane.
+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 Linear.
 
 ---
 
@@ -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` (still needed when using Plane — mintree uses `gh` for PR status on worktree branches)
+- `gh` not authenticated → `gh auth login` (still needed when using Linear — 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
 
@@ -64,8 +64,8 @@ cd path/to/repo
 # Default: GitHub Issues provider
 mintree init
 
-# Or: Plane provider
-mintree init --provider plane --workspace <your-workspace-slug>
+# Or: Linear provider (--team is repeatable, one per team you pull work from)
+mintree init --provider linear --workspace <your-workspace-slug> --team FE --team BE
 
 mintree helpers session-signal install   # optional: live session state in the dashboard
 ```
@@ -77,40 +77,40 @@ mintree helpers session-signal install   # optional: live session state in the d
 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`.
+- **`linear`**: lists issues assigned to you across a configured set of [Linear](https://linear.app) teams, via the Linear GraphQL API. Moves the issue to "In Progress" on `w`.
 
-After `mintree init --provider plane`, edit `.mintree/metadata.json` to add at least one project:
+`mintree init --provider linear --workspace <slug> --team FE --team BE` scaffolds the metadata for you. If you skip `--team`, or want to tweak it later, edit `.mintree/metadata.json` so `linear.teams` lists at least one team key:
 
 ```json
 {
   "version": 1,
-  "provider": "plane",
+  "provider": "linear",
   "issues": {},
-  "plane": {
-    "apiUrl": "https://api.plane.so",
+  "linear": {
+    "apiUrl": "https://api.linear.app/graphql",
     "workspaceSlug": "my-team",
-    "projects": [
-      { "id": "<project-uuid>", "identifier": "BACK", "name": "Backend" },
-      { "id": "<project-uuid>", "identifier": "WEB",  "name": "Web" }
+    "teams": [
+      { "key": "FE", "name": "Frontend" },
+      { "key": "BE", "name": "Backend" }
     ]
   }
 }
 ```
 
-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`).
+The `workspaceSlug` is the URL key of your Linear workspace (`linear.app/<slug>/...`). Each team `key` is the short prefix shown on issue IDs (the `FE` in `FE-123`); `name` is optional. Optional keys: `inProgressStateName` (override the workflow state `w` transitions to) and `protectedStateTypes` (workflow-state types `clean` won't touch).
 
-Authenticate by setting `PLANE_API_KEY` in your shell, or by writing the key to `~/.mintree/credentials.json`:
+Authenticate by setting `LINEAR_API_KEY` in your shell, or by writing the key to `~/.mintree/credentials.json`:
 
 ```bash
-export PLANE_API_KEY=plane_api_XXXXXXXXXXXXXX
+export LINEAR_API_KEY=lin_api_XXXXXXXXXXXXXX
 # or
 cat > ~/.mintree/credentials.json <<'EOF'
-{ "plane": { "apiKey": "plane_api_XXXXXXXXXXXXXX" } }
+{ "linear": { "apiKey": "lin_api_XXXXXXXXXXXXXX" } }
 EOF
 chmod 600 ~/.mintree/credentials.json
 ```
 
-`mintree doctor` validates the key + each configured project's reachability when `provider === "plane"`.
+The key goes straight into the `Authorization` header (no `Bearer` prefix). `mintree doctor` validates the key, resolves the viewer, and pings each configured team when `provider === "linear"`.
 
 ---
 
@@ -143,10 +143,11 @@ 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/BACK-100-validar-patente --work --prompt "empezar BACK-100"
+mintree worktree create feat/FE-123-validar-patente --work --prompt "empezar FE-123"
 
 # Resume Claude in the worktree you're currently inside
-cd .mintree/worktrees/BACK-100-validar-patente
+# (the worktree dir is the bare issue id)
+cd .mintree/worktrees/FE-123
 mintree worktree work
 
 # Inspect / clean up
@@ -176,11 +177,11 @@ mintree enforces:
 `<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.
+- `<TEAM>-<digits>` for Linear issues (the human identifier): `FE-123`, `BE-7`, `DSGN-12`. The prefix is uppercase letters / digits / underscores, matching Linear's team-key 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`.
+Examples: `feat/42-validacion-patente`, `fix/55-selfie-upload-timeout`, `feat/FE-123-readme-update`, `fix/BE-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.
 
@@ -194,16 +195,18 @@ When the dashboard's `w` overlay opens, it suggests a kebab description capped a
 └── .mintree/
     ├── metadata.json             # gitignored. provider config + <issue-id> → { base_branch?, session_id? }
     ├── worktrees/                # gitignored
-    │   ├── 100-validar-patente/      # GH form: <digits>-<desc>
-    │   └── BACK-100-readme-update/   # Plane form: <PROJ-digits>-<desc>
+    │   ├── 100/                  # GH form: <digits>
+    │   └── FE-123/               # Linear form: <TEAM-digits>
     ├── 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. The `provider` and `plane.*` keys can be re-derived from a Plane workspace if needed; sharing them would just leak local config preference.
+The worktree directory is named after the bare issue id (`100`, `FE-123`); the branch keeps the full `<type>/<issue>-<desc>` name.
 
-Plane authentication lives in `~/.mintree/credentials.json` (user-scoped, not per-repo) or the `PLANE_API_KEY` env var.
+`metadata.json` is gitignored because the `session_id` is local to your machine — sharing it would only generate noise. The `provider` and `linear.*` keys can be re-derived from a Linear workspace if needed; sharing them would just leak local config preference.
+
+Linear authentication lives in `~/.mintree/credentials.json` (user-scoped, not per-repo) or the `LINEAR_API_KEY` env var.
 
 ---
 
@@ -220,7 +223,7 @@ Plane authentication lives in `~/.mintree/credentials.json` (user-scoped, not pe
 - `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 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.
+- Linear-side issues (timeouts, rate limits, unexpected response shapes) can be logged to `~/.mintree/linear-debug.log` by running `MINTREE_DEBUG=1 mintree dashboard`. The log is file-only so it never corrupts the Ink-rendered TUI.
 
 ---
 
@@ -228,7 +231,7 @@ Plane authentication lives in `~/.mintree/credentials.json` (user-scoped, not pe
 
 mintree was written for projects that have:
 
-- A small set of trackers (GitHub Issues or Plane) — santree supports both Linear and GitHub but is heavier.
+- A small set of trackers (GitHub Issues or Linear) — santree supports both too 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/worktree/work.js

@@ -67,15 +67,16 @@ function resolve(cwd) {
     const worktreeDirName = path.basename(worktreePath);
     // IssueId comes from the worktree dir name, not the branch — that way
     // detached-HEAD worktrees (the "current branch" path from the dashboard)
-    // still resolve their session_id. Convention guarantees the dir is named
-    // `<issueId>-<desc>` for both attached and detached creates, where
-    // issueId is either bare digits (GitHub) or `<TEAM>-\d+` (Linear).
-    const issueIdMatch = worktreeDirName.match(/^((?:[A-Z][A-Z0-9_]*-)?\d+)-/);
+    // still resolve their session_id. The dir is named after the bare issue
+    // id for both attached and detached creates; the trailing `-` clause still
+    // matches legacy `<issueId>-<desc>` worktrees. issueId is either bare
+    // digits (GitHub) or `<TEAM>-\d+` (Linear).
+    const issueIdMatch = worktreeDirName.match(/^((?:[A-Z][A-Z0-9_]*-)?\d+)(?:-|$)/);
     if (!issueIdMatch || !issueIdMatch[1]) {
         return {
             ok: false,
             message: `Worktree directory '${worktreeDirName}' doesn't start with an issue id.`,
-            hint: "Expected `<issue>-<desc>` (e.g. 100-claude-md-inicial or AUTH-6-legal-endpoint).",
+            hint: "Expected the issue id (e.g. 100 or AUTH-6).",
         };
     }
     const issueId = issueIdMatch[1];

package/dist/lib/branch.js

@@ -29,7 +29,7 @@ export const ALLOWED_TYPES = [
 // `<TEAM_PREFIX>-\d+` (Linear). The TEAM_PREFIX is uppercase letters/digits/
 // underscores starting with a letter, mirroring Linear's team-key
 // constraints. The full issueId captures group 2 verbatim so callers can
-// round-trip it into the worktree dir name.
+// reuse it as the worktree dir name.
 const BRANCH_REGEX = /^([a-z]+)\/((?:[A-Z][A-Z0-9_]*-)?\d+)-([a-z0-9][a-z0-9-]*)$/;
 export function parseBranch(branch) {
     const match = BRANCH_REGEX.exec(branch);
@@ -57,7 +57,9 @@ export function parseBranch(branch) {
         type: type,
         issueId,
         desc,
-        worktreeDirName: `${issueId}-${desc}`,
+        // Worktree dir is the bare issue id (e.g. "100" or "FE-123"). The desc
+        // only seeds the branch name, not the directory.
+        worktreeDirName: issueId,
     };
 }
 export function isParseError(result) {

package/dist/lib/dashboard.js

@@ -16,8 +16,10 @@ import { createProvider } from "./providers/index.js";
 function buildWorktreeIndex(repoRoot) {
     const worktreesRoot = path.resolve(getWorktreesDir(repoRoot));
     // Same shape as the BRANCH_REGEX issueId capture: bare digits (GitHub) or
-    // `<TEAM>-\d+` (Linear). Matches `100-foo` and `FE-123-foo` alike.
-    const dirNameRegex = /^((?:[A-Z][A-Z0-9_]*-)?\d+)-/;
+    // `<TEAM>-\d+` (Linear). The dir name is now the bare issue id (`100`,
+    // `FE-123`); the trailing `-` clause keeps matching legacy `<id>-<desc>`
+    // worktrees still on disk.
+    const dirNameRegex = /^((?:[A-Z][A-Z0-9_]*-)?\d+)(?:-|$)/;
     const index = new Map();
     for (const w of listWorktrees(repoRoot)) {
         const wAbs = path.resolve(w.path);
@@ -119,9 +121,10 @@ function sortGroupedIssues(issues, configuredUrl) {
  * Worktrees" at the bottom of the dashboard so the user can find and `d`elete
  * them.
  *
- * The `issue` stub uses the worktree directory name as the title (the part
- * after the issue id, e.g. "claude-md-inicial") so the row is identifiable
- * even when there's no live issue to fetch a title from.
+ * The `issue` stub uses the worktree directory name as the title — the bare
+ * issue id (e.g. "FE-123"), or the legacy "<id>-<desc>" suffix for older
+ * worktrees — so the row is identifiable even when there's no live issue to
+ * fetch a title from.
  */
 function buildOrphanRows(worktreesByIssue, assignedIds, sessionLookup, prByBranch, metadataSessionId) {
     const orphans = [];

package/dist/lib/session-signal.d.ts

@@ -16,10 +16,12 @@ export declare function extractRepoAndDir(cwd: string): {
     worktreeDir: string;
 } | null;
 /**
- * Pulls the issue id out of a `<issue>-<desc>` worktree directory name.
- * Returns null when the directory name doesn't follow the convention (e.g.
- * a manually-created worktree dropped under .mintree/worktrees/). The id
- * is either bare digits (GitHub) or a `<TEAM>-\d+` Linear identifier.
+ * Pulls the issue id out of a worktree directory name. The dir name is the
+ * bare issue id (`100`, `FE-123`); the trailing `-` clause still matches
+ * legacy `<issue>-<desc>` worktrees on disk. Returns null when the directory
+ * name doesn't follow the convention (e.g. a manually-created worktree
+ * dropped under .mintree/worktrees/). The id is either bare digits (GitHub)
+ * or a `<TEAM>-\d+` Linear identifier.
  */
 export declare function issueIdFromWorktreeDir(worktreeDir: string): string | null;
 export type StatePayload = {

package/dist/lib/session-signal.js

@@ -32,13 +32,15 @@ export function extractRepoAndDir(cwd) {
     return { repoRoot, worktreeDir };
 }
 /**
- * Pulls the issue id out of a `<issue>-<desc>` worktree directory name.
- * Returns null when the directory name doesn't follow the convention (e.g.
- * a manually-created worktree dropped under .mintree/worktrees/). The id
- * is either bare digits (GitHub) or a `<TEAM>-\d+` Linear identifier.
+ * Pulls the issue id out of a worktree directory name. The dir name is the
+ * bare issue id (`100`, `FE-123`); the trailing `-` clause still matches
+ * legacy `<issue>-<desc>` worktrees on disk. Returns null when the directory
+ * name doesn't follow the convention (e.g. a manually-created worktree
+ * dropped under .mintree/worktrees/). The id is either bare digits (GitHub)
+ * or a `<TEAM>-\d+` Linear identifier.
  */
 export function issueIdFromWorktreeDir(worktreeDir) {
-    const m = worktreeDir.match(/^((?:[A-Z][A-Z0-9_]*-)?\d+)-/);
+    const m = worktreeDir.match(/^((?:[A-Z][A-Z0-9_]*-)?\d+)(?:-|$)/);
     return m && m[1] ? m[1] : null;
 }
 /**

package/dist/lib/worktreeCreate.d.ts

@@ -66,7 +66,7 @@ export type CreateDetachedOpts = {
  * the `<type>/<issue>-<desc>` convention upfront. They can `git switch -c`
  * later if/when the work warrants a branch.
  *
- * Worktree dir naming follows the same `<issueId>-<desc>` shape as the
+ * Worktree dir naming follows the same bare-issueId shape as the
  * branch-based flow so `worktree work` can still recover the issueId from
  * the dir name (where it can't read it from the branch).
  */

package/dist/lib/worktreeCreate.js

@@ -238,7 +238,7 @@ export async function runCreate(branchArg, opts) {
  * the `<type>/<issue>-<desc>` convention upfront. They can `git switch -c`
  * later if/when the work warrants a branch.
  *
- * Worktree dir naming follows the same `<issueId>-<desc>` shape as the
+ * Worktree dir naming follows the same bare-issueId shape as the
  * branch-based flow so `worktree work` can still recover the issueId from
  * the dir name (where it can't read it from the branch).
  */
@@ -280,7 +280,7 @@ export async function runCreateDetached(opts) {
             hint: "Switch the main repo to a branch first (`git switch main`) and try again.",
         };
     }
-    const worktreeDirName = `${opts.issueId}-${opts.descKebab}`;
+    const worktreeDirName = opts.issueId;
     const worktreePath = path.join(getWorktreesDir(root), worktreeDirName);
     if (pathExists(worktreePath)) {
         return {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mintree",
-	"version": "0.4.4",
+	"version": "0.4.6",
 	"description": "Issue-driven git worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.",
 	"license": "MIT",
 	"author": "Martin Mineo <mmineo@canarytechnologies.com>",