mintree 0.4.8 → 0.4.9

package/README.md

@@ -159,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
@@ -178,7 +181,7 @@ mintree worktree clean                         # sweep worktrees whose PR is mer
 
 ## Branch convention
 
-mintree enforces:
+By default mintree enforces:
 
 ```
 <type>/<issue>-<kebab-desc>
@@ -199,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
@@ -216,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

@@ -22,10 +22,10 @@ export declare const ALLOWED_TYPES: readonly ["feat", "fix", "docs", "chore", "r
 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;
@@ -33,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

@@ -78,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 {

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "mintree",
-	"version": "0.4.8",
+	"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": {