mintree 0.4.6 → 0.4.9

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Mineo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,20 @@
-# mintree
+<h1 align="center">mintree</h1>
 
-> Issue-driven worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.
+<p align="center">
+  <strong>Issue-driven Git worktrees + Claude Code sessions</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/mintree"><img src="https://img.shields.io/npm/v/mintree.svg" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/mintree"><img src="https://img.shields.io/npm/dm/mintree.svg" alt="npm downloads"></a>
+  <a href="https://github.com/minex-labs/mintree/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/mintree.svg" alt="license"></a>
+</p>
+
+<p align="center">
+  Pick an issue, spin up an isolated worktree, and work it with Claude — for repos with an opinionated SDD+TDD flow.
+</p>
+
+---
 
 mintree wraps the steps you do manually every time a feature begins:
 
@@ -145,6 +159,9 @@ Same building blocks, scriptable from any shell:
 mintree worktree create feat/100-validar-patente
 mintree worktree create feat/FE-123-validar-patente --work --prompt "empezar FE-123"
 
+# On a Linear repo you can pass the issue's own Linear branch name
+mintree worktree create martinmineo/val-68-landing-publica --work
+
 # Resume Claude in the worktree you're currently inside
 # (the worktree dir is the bare issue id)
 cd .mintree/worktrees/FE-123
@@ -164,7 +181,7 @@ mintree worktree clean                         # sweep worktrees whose PR is mer
 
 ## Branch convention
 
-mintree enforces:
+By default mintree enforces:
 
 ```
 <type>/<issue>-<kebab-desc>
@@ -185,6 +202,17 @@ Examples: `feat/42-validacion-patente`, `fix/55-selfie-upload-timeout`, `feat/FE
 
 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.
 
+### Linear repos: branches come from Linear
+
+Many Linear-tracked repos follow the branch name Linear suggests — `<user>/<team>-<n>-<desc>`, e.g. `martinmineo/val-68-landing-publica` — rather than the `<type>/<issue>-<desc>` convention above. That value is the issue's `branchName` (a.k.a. gitBranchName), and it depends on the branch-name prefix configured in your Linear workspace.
+
+So **when `provider` is `linear` and the issue has a `branchName`, mintree uses it verbatim** instead of synthesising a `<type>/<issue>-<desc>` branch:
+
+- In the dashboard's `w` overlay, the "new branch" mode shows the Linear branch (read-only, labelled `from Linear`) and skips the type/description fields.
+- From the CLI, you can pass the Linear branch directly: `mintree worktree create martinmineo/val-68-landing-publica`. mintree finds the Linear identifier (`val-68`) by matching it against your configured `linear.teams[].key`, and normalises it to the canonical `VAL-68`.
+
+The worktree directory is still the **bare, upper-case issue id** (`VAL-68`) regardless of the branch name, matching the GitHub case. The `<type>/<issue>-<desc>` convention is still accepted on Linear repos too — it's used as a fallback when an issue has no `branchName`. GitHub repos are unaffected: they always use the convention and reject Linear-style branches.
+
 ---
 
 ## What gets stored where
@@ -202,7 +230,7 @@ When the dashboard's `w` overlay opens, it suggests a kebab description capped a
     └── init.sh                   # opt-in. Runs in the new worktree post-create (copy .env, install deps, …)
 ```
 
-The worktree directory is named after the bare issue id (`100`, `FE-123`); the branch keeps the full `<type>/<issue>-<desc>` name.
+The worktree directory is named after the bare issue id (`100`, `FE-123`, `VAL-68`); the branch keeps its full name — `<type>/<issue>-<desc>` for the convention, or Linear's own `<user>/<team>-<n>-<desc>` on Linear repos.
 
 `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.
 

package/dist/commands/dashboard.js

@@ -204,14 +204,22 @@ function RemoveOverlayView({ overlay }) {
 function CreateOverlayView({ overlay, onDescChange, onPromptChange, }) {
     const labelWidth = 14;
     const isNewBranch = overlay.branchMode === "new";
+    const isLinearBranch = overlay.linearBranch !== null;
+    // type/desc only apply to the convention "new branch" path — hidden both
+    // for detached ("current") mode and for the Linear-branchName case.
+    const showTypeDesc = isNewBranch && !isLinearBranch;
     const detachedDesc = kebabize(overlay.issue.issue.title) || `issue-${overlay.issue.issue.id}`;
-    const branchPreview = isNewBranch
-        ? `${overlay.type}/${overlay.issue.issue.id}-${overlay.desc}`
-        : `detached @ ${overlay.currentBranch ?? "(unknown)"}`;
-    const dirPreview = isNewBranch
-        ? `${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.steps.length > 0 && (_jsx(Box, { marginTop: 1, flexDirection: "column", children: overlay.steps.map((step, i) => (_jsxs(Box, { children: [_jsx(CreateStepIcon, { kind: step.kind }), _jsx(Text, { children: " " }), _jsx(Text, { children: step.label }), step.detail && _jsxs(Text, { dimColor: true, children: [" (", step.detail, ")"] })] }, i))) })), overlay.pending && (_jsxs(Box, { marginTop: overlay.steps.length > 0 ? 0 : 1, children: [_jsx(Text, { color: "cyan", children: _jsx(Spinner, { type: "dots" }) }), _jsxs(Text, { children: [" ", overlay.pending] })] }))] }));
+    const branchPreview = !isNewBranch
+        ? `detached @ ${overlay.currentBranch ?? "(unknown)"}`
+        : isLinearBranch
+            ? overlay.linearBranch
+            : `${overlay.type}/${overlay.issue.issue.id}-${overlay.desc}`;
+    const dirPreview = !isNewBranch
+        ? `${overlay.issue.issue.id}-${detachedDesc}`
+        : isLinearBranch
+            ? overlay.issue.issue.id
+            : `${overlay.issue.issue.id}-${overlay.desc}`;
+    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 && isLinearBranch && (_jsxs(Box, { marginTop: 0, children: [_jsx(Box, { width: labelWidth, children: _jsx(Text, { dimColor: true, children: "  Branch name:" }) }), _jsx(Text, { color: "green", children: overlay.linearBranch }), _jsx(Text, { dimColor: true, children: "   (from Linear)" })] })), showTypeDesc && (_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: [isLinearBranch ? (_jsx(Text, { dimColor: true, children: "Branch name comes from Linear (the issue's suggested `branchName`). The worktree dir is the bare issue id." })) : 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."] })), showTypeDesc && 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.steps.length > 0 && (_jsx(Box, { marginTop: 1, flexDirection: "column", children: overlay.steps.map((step, i) => (_jsxs(Box, { children: [_jsx(CreateStepIcon, { kind: step.kind }), _jsx(Text, { children: " " }), _jsx(Text, { children: step.label }), step.detail && _jsxs(Text, { dimColor: true, children: [" (", step.detail, ")"] })] }, i))) })), overlay.pending && (_jsxs(Box, { marginTop: overlay.steps.length > 0 ? 0 : 1, children: [_jsx(Text, { color: "cyan", children: _jsx(Spinner, { type: "dots" }) }), _jsxs(Text, { children: [" ", overlay.pending] })] }))] }));
 }
 function CreateStepIcon({ kind }) {
     if (kind === "ok")
@@ -964,6 +972,12 @@ export default function Dashboard() {
         if (state.phase !== "ready")
             return;
         const root = findMainRepoRoot();
+        // On a Linear repo, prefer the branch Linear suggests for the issue
+        // (its `branchName`) over the synthesised `<type>/<issue>-<desc>` form —
+        // that's the convention those repos actually follow. Falls back to the
+        // convention form when the issue has no branchName.
+        const provider = root ? readMetadata(root).provider : undefined;
+        const linearBranch = provider === "linear" && issue.issue.branchName ? issue.issue.branchName : null;
         setState({
             ...state,
             overlay: {
@@ -973,6 +987,7 @@ export default function Dashboard() {
                 currentBranch: root ? getCurrentBranch(root) : null,
                 type: "feat",
                 desc: kebabize(issue.issue.title) || `issue-${issue.issue.id}`,
+                linearBranch,
                 prompt: defaultPromptForIssue(issue.issue.id, issue.issue.title, issue.issue.url),
                 field: "branchMode",
                 error: null,
@@ -1001,11 +1016,13 @@ export default function Dashboard() {
             handleRemoveOverlayInput(input, key, overlay);
             return;
         }
-        // In "current" branch mode we skip type+desc fields entirely — they have
-        // no meaning when the worktree is going to be detached. Tab cycles
-        // branchMode ⇄ prompt only.
+        // In "current" branch mode (detached) and in the Linear-branchName case
+        // we skip type+desc fields entirely — they have no meaning when the
+        // branch is fixed (detached HEAD, or Linear's own `branchName`). Tab
+        // cycles branchMode ⇄ prompt only.
+        const skipTypeDesc = overlay.branchMode === "current" || overlay.linearBranch !== null;
         if (key.tab) {
-            const order = overlay.branchMode === "current"
+            const order = skipTypeDesc
                 ? ["branchMode", "prompt"]
                 : ["branchMode", "type", "desc", "prompt"];
             const i = order.indexOf(overlay.field);
@@ -1068,8 +1085,9 @@ export default function Dashboard() {
         if (state.phase !== "ready")
             return;
         // Validate first so we don't flash a spinner just to immediately show
-        // a sync-fail message.
-        if (overlay.branchMode === "new" && !overlay.desc.trim()) {
+        // a sync-fail message. A Linear-branch create needs no desc (the branch
+        // is Linear's `branchName`), so only the convention path requires it.
+        if (overlay.branchMode === "new" && !overlay.linearBranch && !overlay.desc.trim()) {
             setState({
                 ...state,
                 overlay: { ...overlay, error: "Description is required." },
@@ -1124,8 +1142,9 @@ export default function Dashboard() {
             });
         }
         else {
-            const desc = overlay.desc.trim();
-            const branch = `${overlay.type}/${issueId}-${desc}`;
+            // Linear repos with a `branchName` use it verbatim; everyone else
+            // synthesises the `<type>/<issue>-<desc>` convention branch.
+            const branch = overlay.linearBranch ?? `${overlay.type}/${issueId}-${overlay.desc.trim()}`;
             result = await runCreate(branch, {
                 work: true,
                 progress: { onStep, onPending },

package/dist/commands/worktree/create.js

@@ -13,7 +13,7 @@ export const description = "Create a worktree for an issue branch";
 export const args = z.tuple([
     z.string().describe(argument({
         name: "branch",
-        description: "Branch in `<type>/<issue>-<kebab-desc>` format (e.g. feat/100-claude-md-inicial)",
+        description: "Branch in `<type>/<issue>-<kebab-desc>` format (e.g. feat/100-claude-md-inicial). On a Linear repo you can instead pass the issue's Linear branch name (e.g. martinmineo/val-68-landing-publica).",
     })),
 ]);
 export const options = z.object({

package/dist/lib/branch.d.ts

@@ -7,19 +7,25 @@
  * bare digit run (GitHub issue number — "100") or a team-prefixed Linear
  * identifier ("FE-100"); `<desc>` is lower-case kebab-case.
  *
+ * The Linear team key is normalized to upper-case: `feat/be-256-x` is
+ * accepted and rewritten to `feat/BE-256-x` (issueId "BE-256"). Linear's
+ * canonical identifier is always upper-case, so this just rescues a branch
+ * a human (or a target-repo skill) typed in the wrong case.
+ *
  * Examples that PARSE: feat/100-readme-update, fix/55-upload-timeout,
- *                      feat/BACK-100-readme-update, fix/WEB-7-modal
+ *                      feat/BACK-100-readme-update, fix/WEB-7-modal,
+ *                      feat/back-100-x (normalized to feat/BACK-100-x)
  * Examples that REJECT: feat/abc-foo, /100-foo, gh-100-foo, feat/100,
- *                       feat/100-FooBar, feat/back-100-x (lowercase prefix)
+ *                       feat/100-FooBar, Feat/BE-1-x (upper-case type)
  */
 export declare const ALLOWED_TYPES: readonly ["feat", "fix", "docs", "chore", "refactor", "test", "build", "ci", "perf", "style", "revert"];
 export type BranchType = (typeof ALLOWED_TYPES)[number];
 export type ParsedBranch = {
     branch: string;
-    type: BranchType;
     issueId: string;
-    desc: string;
     worktreeDirName: string;
+    type?: BranchType;
+    desc?: string;
 };
 export type ParseError = {
     error: string;
@@ -27,3 +33,26 @@ export type ParseError = {
 };
 export declare function parseBranch(branch: string): ParsedBranch | ParseError;
 export declare function isParseError(result: ParsedBranch | ParseError): result is ParseError;
+/**
+ * Pulls the Linear issue identifier (`<TEAM>-<n>`) out of a Linear-style
+ * branch name. Linear's `branchName` looks like `<user>/<team>-<n>-<slug>`
+ * (or just `<team>-<n>-<slug>` when the workspace has no user prefix), with
+ * the identifier lower-cased. We locate `<team>-<digits>` as a delimited token
+ * and return it upper-cased so it matches the canonical issue id everywhere
+ * else in mintree.
+ *
+ * `teamKeys` narrows the search to the repo's configured teams (the robust
+ * path); when empty — a mis-configured repo — we fall back to the first
+ * `<letters>-<digits>` token, which is still correct for the common single-
+ * identifier branch shape.
+ */
+export declare function extractLinearIssueId(branch: string, teamKeys: string[]): string | null;
+/**
+ * Resolves a Linear `branchName` into a ParsedBranch. The branch is kept
+ * verbatim (only trimmed) — git refs are case-sensitive and Linear's value is
+ * the exact ref GitHub/Linear will link against, so we must not rewrite it.
+ * Only the extracted `issueId` is normalised to upper-case. The worktree dir
+ * is the bare issue id (`VAL-68`), matching the convention path and the
+ * dir-name recovery regexes elsewhere.
+ */
+export declare function parseLinearBranch(rawBranch: string, teamKeys: string[]): ParsedBranch | ParseError;

package/dist/lib/branch.js

@@ -7,10 +7,16 @@
  * bare digit run (GitHub issue number — "100") or a team-prefixed Linear
  * identifier ("FE-100"); `<desc>` is lower-case kebab-case.
  *
+ * The Linear team key is normalized to upper-case: `feat/be-256-x` is
+ * accepted and rewritten to `feat/BE-256-x` (issueId "BE-256"). Linear's
+ * canonical identifier is always upper-case, so this just rescues a branch
+ * a human (or a target-repo skill) typed in the wrong case.
+ *
  * Examples that PARSE: feat/100-readme-update, fix/55-upload-timeout,
- *                      feat/BACK-100-readme-update, fix/WEB-7-modal
+ *                      feat/BACK-100-readme-update, fix/WEB-7-modal,
+ *                      feat/back-100-x (normalized to feat/BACK-100-x)
  * Examples that REJECT: feat/abc-foo, /100-foo, gh-100-foo, feat/100,
- *                       feat/100-FooBar, feat/back-100-x (lowercase prefix)
+ *                       feat/100-FooBar, Feat/BE-1-x (upper-case type)
  */
 export const ALLOWED_TYPES = [
     "feat",
@@ -26,11 +32,12 @@ export const ALLOWED_TYPES = [
     "revert",
 ];
 // `<type>/<issueId>-<desc>` where issueId is either `\d+` (GitHub) or
-// `<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
-// reuse it as the worktree dir name.
-const BRANCH_REGEX = /^([a-z]+)\/((?:[A-Z][A-Z0-9_]*-)?\d+)-([a-z0-9][a-z0-9-]*)$/;
+// `<TEAM_PREFIX>-\d+` (Linear). The TEAM_PREFIX is letters/digits/underscores
+// starting with a letter, mirroring Linear's team-key constraints. Both cases
+// are accepted here and the captured team key is upper-cased on the way out
+// (see `parseBranch`), so the worktree dir name and the created branch stay
+// canonical regardless of how the caller typed it.
+const BRANCH_REGEX = /^([a-z]+)\/((?:[A-Za-z][A-Za-z0-9_]*-)?\d+)-([a-z0-9][a-z0-9-]*)$/;
 export function parseBranch(branch) {
     const match = BRANCH_REGEX.exec(branch);
     if (!match) {
@@ -39,8 +46,8 @@ export function parseBranch(branch) {
             hint: "Expected `<type>/<issue>-<kebab-desc>`. Examples: feat/100-claude-md-inicial, feat/BACK-100-claude-md-inicial",
         };
     }
-    const [, type, issueId, desc] = match;
-    if (!type || !issueId || !desc) {
+    const [, type, rawIssueId, desc] = match;
+    if (!type || !rawIssueId || !desc) {
         return {
             error: `Invalid branch name: ${branch}`,
             hint: "Expected `<type>/<issue>-<kebab-desc>`. Examples: feat/100-claude-md-inicial, feat/BACK-100-claude-md-inicial",
@@ -52,8 +59,14 @@ export function parseBranch(branch) {
             hint: `Allowed types: ${ALLOWED_TYPES.join(", ")}`,
         };
     }
+    // Normalize the Linear team key to upper-case. `toUpperCase()` is a no-op
+    // for a bare-digit GitHub id ("256") and only touches the team prefix of a
+    // Linear id ("be-256" → "BE-256"). The returned `branch` is rebuilt from
+    // the normalized id so callers create/look up the canonical branch name.
+    const issueId = rawIssueId.toUpperCase();
+    const normalizedBranch = `${type}/${issueId}-${desc}`;
     return {
-        branch,
+        branch: normalizedBranch,
         type: type,
         issueId,
         desc,
@@ -65,3 +78,71 @@ export function parseBranch(branch) {
 export function isParseError(result) {
     return "error" in result;
 }
+// Chars that make a string an invalid (or risky) git ref. Linear's
+// `branchName` never contains these, but this entry point is also reachable
+// from the CLI (`mintree worktree create <branch>`), so junk input is rejected
+// rather than handed to `git worktree add`.
+const GIT_REF_INVALID = /[\s~^:?*[\]\\]/;
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Pulls the Linear issue identifier (`<TEAM>-<n>`) out of a Linear-style
+ * branch name. Linear's `branchName` looks like `<user>/<team>-<n>-<slug>`
+ * (or just `<team>-<n>-<slug>` when the workspace has no user prefix), with
+ * the identifier lower-cased. We locate `<team>-<digits>` as a delimited token
+ * and return it upper-cased so it matches the canonical issue id everywhere
+ * else in mintree.
+ *
+ * `teamKeys` narrows the search to the repo's configured teams (the robust
+ * path); when empty — a mis-configured repo — we fall back to the first
+ * `<letters>-<digits>` token, which is still correct for the common single-
+ * identifier branch shape.
+ */
+export function extractLinearIssueId(branch, teamKeys) {
+    const keys = teamKeys.filter((k) => k.length > 0);
+    // The identifier must sit on a token boundary (start, or after `/ _ -`) and
+    // be followed by one (end, or before `/ _ -`) so we don't match a team key
+    // buried inside a slug word.
+    const keyAlt = keys.length > 0 ? keys.map(escapeRegex).join("|") : "[A-Za-z][A-Za-z0-9_]*";
+    const re = new RegExp(`(?:^|[/_-])(${keyAlt})-(\\d+)(?=$|[/_-])`, "i");
+    const m = re.exec(branch);
+    if (!m || !m[1] || !m[2])
+        return null;
+    return `${m[1].toUpperCase()}-${m[2]}`;
+}
+/**
+ * Resolves a Linear `branchName` into a ParsedBranch. The branch is kept
+ * verbatim (only trimmed) — git refs are case-sensitive and Linear's value is
+ * the exact ref GitHub/Linear will link against, so we must not rewrite it.
+ * Only the extracted `issueId` is normalised to upper-case. The worktree dir
+ * is the bare issue id (`VAL-68`), matching the convention path and the
+ * dir-name recovery regexes elsewhere.
+ */
+export function parseLinearBranch(rawBranch, teamKeys) {
+    const branch = rawBranch.trim();
+    if (!branch) {
+        return {
+            error: "Empty branch name",
+            hint: "Linear should provide a `branchName` like `martinmineo/val-68-landing-publica`.",
+        };
+    }
+    if (GIT_REF_INVALID.test(branch) || branch.startsWith("/") || branch.endsWith("/")) {
+        return {
+            error: `Invalid branch name: ${rawBranch}`,
+            hint: "A Linear branch must be a valid git ref (no spaces or ~^:?*[]\\).",
+        };
+    }
+    const issueId = extractLinearIssueId(branch, teamKeys);
+    if (!issueId) {
+        const hint = teamKeys.length > 0
+            ? `Expected a Linear identifier for one of: ${teamKeys.join(", ")} (e.g. ${teamKeys[0]}-123). Got \`${branch}\`.`
+            : `Expected a Linear identifier like \`team-123\` somewhere in the branch. Got \`${branch}\`.`;
+        return { error: `Could not find a Linear issue id in branch \`${branch}\``, hint };
+    }
+    return {
+        branch,
+        issueId,
+        worktreeDirName: issueId,
+    };
+}

package/dist/lib/providers/linear.js

@@ -271,6 +271,7 @@ const BOOTSTRAP_QUERY = /* GraphQL */ `
 				title
 				description
 				url
+				branchName
 				priority
 				createdAt
 				updatedAt
@@ -334,6 +335,7 @@ function mapIssueToProviderIssue(wi) {
         // value) to null so the dashboard treats it the same as GitHub's
         // no-priority rows.
         priority: wi.priority && wi.priority > 0 ? wi.priority : null,
+        ...(wi.branchName && wi.branchName.length > 0 ? { branchName: wi.branchName } : {}),
     };
 }
 export class LinearProvider {
@@ -504,8 +506,17 @@ export class LinearProvider {
         }
         const targetStateName = cfg.inProgressStateName;
         let targetState = targetStateName ? states.find((s) => s.name === targetStateName) : undefined;
-        if (!targetState)
-            targetState = states.find((s) => s.type === "started");
+        if (!targetState) {
+            // Linear marks BOTH "In Progress" and "In Review" as type "started",
+            // and the bootstrap query returns states unordered — so a plain
+            // `find(type === "started")` can land on "In Review". Prefer a state
+            // literally named "In Progress", otherwise pick the leftmost started
+            // state by workflow position (lowest = earliest = "In Progress").
+            const started = states.filter((s) => s.type === "started");
+            targetState =
+                started.find((s) => s.name?.toLowerCase() === "in progress") ??
+                    started.sort((a, b) => (a.position ?? 0) - (b.position ?? 0))[0];
+        }
         if (!targetState) {
             return {
                 kind: "skip-no-in-progress-option",

package/dist/lib/providers/types.d.ts

@@ -27,6 +27,7 @@ export type ProviderIssue = {
     createdAt: string;
     updatedAt: string;
     priority: number | null;
+    branchName?: string;
 };
 /**
  * The issue's membership on a project board (GitHub Projects v2 / Linear

package/dist/lib/worktreeCreate.js

@@ -2,9 +2,32 @@ import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
 import { execSync } from "child_process";
-import { parseBranch, isParseError } from "./branch.js";
+import { parseBranch, parseLinearBranch, isParseError, } from "./branch.js";
 import { findMainRepoRoot, getMintreeDir, getWorktreesDir, getInitScriptPath, getDefaultBranch, getCurrentBranch, branchExists, remoteBranchExists, fetchRemote, worktreeForBranch, addWorktree, pathExists, isExecutable, } from "./git.js";
-import { upsertIssue } from "./metadata.js";
+import { readMetadata, upsertIssue } from "./metadata.js";
+/**
+ * Resolves the branch arg into a ParsedBranch, choosing the parser by
+ * provider. The convention parser (`<type>/<issue>-<desc>`) is tried first for
+ * every provider — a Linear repo can still use convention branches. When that
+ * fails AND the repo is on the Linear provider, we fall back to parsing the
+ * arg as a Linear `branchName` (`<user>/<team>-<n>-<slug>`), keyed off the
+ * configured team keys. GitHub repos never reach the Linear branch, so their
+ * behaviour is unchanged.
+ */
+function resolveCreateBranch(repoRoot, branchArg) {
+    const conv = parseBranch(branchArg);
+    if (!isParseError(conv))
+        return conv;
+    const meta = readMetadata(repoRoot);
+    if (meta.provider === "linear" && meta.linear) {
+        const teamKeys = meta.linear.teams.map((t) => t.key);
+        const linear = parseLinearBranch(branchArg, teamKeys);
+        // On a Linear repo the Linear-branch error is the more useful one to
+        // surface, so return it whether it parsed or not.
+        return linear;
+    }
+    return conv;
+}
 function tryRunInitScript(scriptPath, worktreePath, repoRoot) {
     if (!pathExists(scriptPath))
         return { ran: false };
@@ -72,7 +95,7 @@ export async function runCreate(branchArg, opts) {
             hint: "Run `mintree init` first.",
         };
     }
-    const parsed = parseBranch(branchArg);
+    const parsed = resolveCreateBranch(root, branchArg);
     if (isParseError(parsed)) {
         return { ok: false, message: parsed.error, hint: parsed.hint };
     }
@@ -100,7 +123,9 @@ export async function runCreate(branchArg, opts) {
     pushStep({
         kind: "ok",
         label: "parsed branch",
-        detail: `type=${parsed.type}, issue=${parsed.issueId}, desc=${parsed.desc}`,
+        detail: parsed.type
+            ? `type=${parsed.type}, issue=${parsed.issueId}, desc=${parsed.desc}`
+            : `issue=${parsed.issueId}, branch=${parsed.branch}`,
     });
     await nextFrame(progress);
     // Fetch before resolving refs so the worktree forks from fresh code, not a

package/dist/lib/worktreeRemove.d.ts

@@ -17,6 +17,10 @@ export type RemoveResult = {
  *
  * Branch and metadata are deliberately preserved so a later re-attach can
  * resume the same Claude session.
+ *
+ * The branch name is NOT validated against the naming convention here:
+ * removal is a cleanup op, and a worktree on a non-canonical branch (e.g.
+ * one with a lowercase Linear team key) must still be removable.
  */
 export declare function runRemove(branchArg: string, force: boolean): RemoveResult;
 /**

package/dist/lib/worktreeRemove.js

@@ -1,4 +1,3 @@
-import { parseBranch, isParseError } from "./branch.js";
 import { findMainRepoRoot, getMintreeDir, worktreeForBranch, isDirty, removeWorktree, pruneWorktrees, pathExists, } from "./git.js";
 /**
  * Removes the worktree backing `branchArg`. Same behavior as the CLI command:
@@ -8,6 +7,10 @@ import { findMainRepoRoot, getMintreeDir, worktreeForBranch, isDirty, removeWork
  *
  * Branch and metadata are deliberately preserved so a later re-attach can
  * resume the same Claude session.
+ *
+ * The branch name is NOT validated against the naming convention here:
+ * removal is a cleanup op, and a worktree on a non-canonical branch (e.g.
+ * one with a lowercase Linear team key) must still be removable.
  */
 export function runRemove(branchArg, force) {
     const root = findMainRepoRoot();
@@ -25,15 +28,11 @@ export function runRemove(branchArg, force) {
             hint: "Run `mintree init` first.",
         };
     }
-    const parsed = parseBranch(branchArg);
-    if (isParseError(parsed)) {
-        return { ok: false, message: parsed.error, hint: parsed.hint };
-    }
-    const worktreePath = worktreeForBranch(root, parsed.branch);
+    const worktreePath = worktreeForBranch(root, branchArg);
     if (!worktreePath) {
         return {
             ok: false,
-            message: `No worktree found for branch ${parsed.branch}.`,
+            message: `No worktree found for branch ${branchArg}.`,
             hint: "Use `mintree worktree list` to see existing worktrees.",
         };
     }
@@ -49,7 +48,7 @@ export function runRemove(branchArg, force) {
         }
         return {
             ok: true,
-            branch: parsed.branch,
+            branch: branchArg,
             worktreePath,
             variant: "pruned-orphan",
             wasDirty: false,
@@ -76,7 +75,7 @@ export function runRemove(branchArg, force) {
     }
     return {
         ok: true,
-        branch: parsed.branch,
+        branch: branchArg,
         worktreePath,
         variant: "removed",
         wasDirty: dirty,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mintree",
-	"version": "0.4.6",
+	"version": "0.4.9",
 	"description": "Issue-driven git worktrees + Claude Code sessions for repos with an opinionated SDD+TDD flow.",
 	"license": "MIT",
 	"author": "Martin Mineo <mmineo@canarytechnologies.com>",
@@ -34,7 +34,8 @@
 		"start": "node dist/cli.js",
 		"lint": "eslint source",
 		"lint:fix": "eslint source --fix",
-		"format": "prettier --write source"
+		"format": "prettier --write source",
+		"test": "node --import tsx --test test/*.test.ts"
 	},
 	"files": [
 		"dist",
@@ -58,6 +59,7 @@
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-prettier": "^5.5.5",
 		"prettier": "^3.7.4",
+		"tsx": "^4.22.4",
 		"typescript": "^5.7.0"
 	},
 	"overrides": {