mintree 0.4.8 → 0.4.10

package/README.md

@@ -126,6 +126,32 @@ chmod 600 ~/.mintree/credentials.json
 
 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"`.
 
+### Launch behaviour (optional)
+
+Two top-level keys in `.mintree/metadata.json` tune how mintree launches Claude — both apply to GitHub and Linear repos alike:
+
+```json
+{
+  "version": 1,
+  "provider": "linear",
+  "issues": {},
+  "defaultPermissionMode": "auto",
+  "promptTemplate": "Trabajá en el ticket {{id}} ({{title}}). Abrí {{url}} para el contexto completo y seguí las convenciones del repo.",
+  "linear": { "workspaceSlug": "my-team", "teams": [{ "key": "FE" }] }
+}
+```
+
+- **`defaultPermissionMode`** (`"default"` | `"auto"`): the Claude `--permission-mode` mintree uses when it launches a session — from the dashboard (`w` / `↵`), `worktree work`, or `worktree create --work`. Omitted (or `"default"`) keeps the stricter default mode; `"auto"` starts every session with auto-accept on. The `--permission-mode` / `-m` CLI flag still overrides it per launch.
+- **`promptTemplate`**: the initial message seeded into the dashboard's `w` overlay (the text Claude receives as its first prompt). It replaces mintree's built-in default and supports these placeholders, substituted per issue:
+
+  | Placeholder | Replaced with                                         |
+  |-------------|-------------------------------------------------------|
+  | `{{id}}`    | Issue id — `100` (GitHub) or `FE-123` (Linear)        |
+  | `{{title}}` | Issue title                                           |
+  | `{{url}}`   | Issue URL (GitHub issue page / Linear issue link)     |
+
+  It's a single line on purpose — the overlay's prompt field is one line, and you can still edit it before launching. When omitted, mintree falls back to its provider-aware default (`gh issue view` for GitHub, the bare id + URL for Linear).
+
 ---
 
 ## Daily flow
@@ -159,6 +185,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 +207,7 @@ mintree worktree clean                         # sweep worktrees whose PR is mer
 
 ## Branch convention
 
-mintree enforces:
+By default mintree enforces:
 
 ```
 <type>/<issue>-<kebab-desc>
@@ -199,6 +228,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 +256,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

@@ -14,6 +14,7 @@ import { runCreate, runCreateDetached, } from "../lib/worktreeCreate.js";
 import { runRemove, runRemoveByPath } from "../lib/worktreeRemove.js";
 import { buildCreateMarkers, emitMarkers } from "../lib/markers.js";
 import { readMetadata } from "../lib/metadata.js";
+import { renderPromptTemplate } from "../lib/promptTemplate.js";
 import { createProvider } from "../lib/providers/index.js";
 import { loadDashboard } from "../lib/dashboard.js";
 import { priorityDisplay } from "../lib/priority.js";
@@ -121,11 +122,18 @@ function kebabize(title) {
  * Default prompt seeded into the overlay's Prompt field when the user opens
  * `w` for an issue. Single-line on purpose — `ink-text-input` is one-line,
  * so multi-line templates render weirdly when the user tabs in to edit.
- * Provider-aware: GitHub issues get the `#<n>` + `gh issue view` form;
- * Linear issues (id like `FE-123`) get the bare id + the issue URL, since
- * `gh` can't read Linear and `#` isn't Linear's notation.
+ *
+ * When the repo configures a `promptTemplate` in `.mintree/metadata.json`,
+ * it wins: the `{{id}}`, `{{title}}` and `{{url}}` placeholders are rendered
+ * and the result seeds the field. Otherwise we fall back to the built-in,
+ * provider-aware default: GitHub issues get the `#<n>` + `gh issue view`
+ * form; Linear issues (id like `FE-123`) get the bare id + the issue URL,
+ * since `gh` can't read Linear and `#` isn't Linear's notation.
  */
-function defaultPromptForIssue(id, title, url) {
+function defaultPromptForIssue(id, title, url, template) {
+    if (template) {
+        return renderPromptTemplate(template, { id, title, url });
+    }
     const isTeamPrefixed = /^[A-Z][A-Z0-9_]*-\d+$/.test(id);
     if (isTeamPrefixed) {
         return `Empezá a trabajar el ticket ${id} (${title}). Abrí ${url} para leer el contexto completo y seguí las convenciones del repo.`;
@@ -204,14 +212,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 +980,13 @@ 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 meta = root ? readMetadata(root) : undefined;
+        const provider = meta?.provider;
+        const linearBranch = provider === "linear" && issue.issue.branchName ? issue.issue.branchName : null;
         setState({
             ...state,
             overlay: {
@@ -973,7 +996,8 @@ export default function Dashboard() {
                 currentBranch: root ? getCurrentBranch(root) : null,
                 type: "feat",
                 desc: kebabize(issue.issue.title) || `issue-${issue.issue.id}`,
-                prompt: defaultPromptForIssue(issue.issue.id, issue.issue.title, issue.issue.url),
+                linearBranch,
+                prompt: defaultPromptForIssue(issue.issue.id, issue.issue.title, issue.issue.url, meta?.promptTemplate),
                 field: "branchMode",
                 error: null,
                 conventionDoc: root ? findBranchConventionDoc(root) : null,
@@ -1001,11 +1025,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 +1094,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 +1151,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/commands/worktree/work.d.ts

@@ -3,7 +3,7 @@ export declare const description = "Launch Claude in the current worktree (creat
 export declare const options: z.ZodObject<{
     prompt: z.ZodOptional<z.ZodString>;
     promptFile: z.ZodOptional<z.ZodString>;
-    permissionMode: z.ZodDefault<z.ZodEnum<{
+    permissionMode: z.ZodOptional<z.ZodEnum<{
         default: "default";
         auto: "auto";
     }>>;

package/dist/commands/worktree/work.js

@@ -8,7 +8,7 @@ import { randomUUID } from "crypto";
 import { readFileSync, unlinkSync } from "fs";
 import * as path from "path";
 import { findMainRepoRoot, getMintreeDir, getWorktreesDir, getCurrentBranch, pathExists, } from "../../lib/git.js";
-import { getSessionId, setSessionId } from "../../lib/metadata.js";
+import { getSessionId, setSessionId, readMetadata } from "../../lib/metadata.js";
 import { launchClaude, PERMISSION_MODES } from "../../lib/claude.js";
 export const description = "Launch Claude in the current worktree (creates or resumes a session)";
 export const options = z.object({
@@ -26,13 +26,13 @@ export const options = z.object({
     })),
     permissionMode: z
         .enum(PERMISSION_MODES)
-        .default("default")
+        .optional()
         .describe(option({
-        description: `Claude --permission-mode (one of: ${PERMISSION_MODES.join(", ")})`,
+        description: `Claude --permission-mode (one of: ${PERMISSION_MODES.join(", ")}). Defaults to metadata.defaultPermissionMode, else "default".`,
         alias: "m",
     })),
 });
-function resolve(cwd) {
+function resolve(cwd, flagPermissionMode) {
     const repoRoot = findMainRepoRoot(cwd);
     if (!repoRoot) {
         return {
@@ -93,6 +93,9 @@ function resolve(cwd) {
         setSessionId(repoRoot, issueId, sessionId);
         resume = false;
     }
+    // Effective permission mode: explicit `--permission-mode` flag wins, else
+    // the repo's `metadata.defaultPermissionMode`, else the stricter "default".
+    const permissionMode = flagPermissionMode ?? readMetadata(repoRoot).defaultPermissionMode ?? "default";
     return {
         ok: true,
         data: {
@@ -103,6 +106,7 @@ function resolve(cwd) {
             issueId,
             sessionId,
             resume,
+            permissionMode,
         },
     };
 }
@@ -118,7 +122,7 @@ export default function Work({ options }) {
                 });
                 return;
             }
-            const result = resolve(process.cwd());
+            const result = resolve(process.cwd(), options.permissionMode);
             if (!result.ok) {
                 setState({ phase: "error", message: result.message, hint: result.hint });
                 return;
@@ -151,7 +155,7 @@ export default function Work({ options }) {
         }
         try {
             const child = launchClaude({
-                permissionMode: options.permissionMode,
+                permissionMode: resolved.permissionMode,
                 sessionId: resolved.sessionId,
                 resume: resolved.resume,
                 prompt: effectivePrompt,
@@ -184,7 +188,7 @@ export default function Work({ options }) {
     const { resolved } = state;
     const sessionShort = resolved.sessionId.slice(0, 8);
     const action = resolved.resume ? "resuming" : "starting";
-    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "mintree worktree work" }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", resolved.branch ?? `detached @ ${resolved.worktreeDirName}`] })] }), _jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "session: " }), _jsxs(Text, { children: [sessionShort, "\u2026"] }), _jsxs(Text, { dimColor: true, children: [" (", action, ")"] })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "permission-mode: " }), _jsx(Text, { children: options.permissionMode })] }), options.prompt && (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "initial prompt: " }), _jsxs(Text, { children: ["\"", truncate(options.prompt, 60), "\""] })] })), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "cwd: " }), _jsx(Text, { dimColor: true, children: resolved.worktreePath })] })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "green", bold: true, children: "\u2713 Launching Claude..." }) })] }));
+    return (_jsxs(Box, { flexDirection: "column", padding: 1, children: [_jsxs(Box, { marginBottom: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: "mintree worktree work" }), _jsxs(Text, { dimColor: true, children: [" \u00B7 ", resolved.branch ?? `detached @ ${resolved.worktreeDirName}`] })] }), _jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "session: " }), _jsxs(Text, { children: [sessionShort, "\u2026"] }), _jsxs(Text, { dimColor: true, children: [" (", action, ")"] })] }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "permission-mode: " }), _jsx(Text, { children: resolved.permissionMode })] }), options.prompt && (_jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "initial prompt: " }), _jsxs(Text, { children: ["\"", truncate(options.prompt, 60), "\""] })] })), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "cwd: " }), _jsx(Text, { dimColor: true, children: resolved.worktreePath })] })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { color: "green", bold: true, children: "\u2713 Launching Claude..." }) })] }));
 }
 function truncate(s, max) {
     if (s.length <= max)

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/metadata.d.ts

@@ -1,3 +1,4 @@
+import { type PermissionMode } from "./claude.js";
 export type IssueMeta = {
     base_branch?: string;
     session_id?: string;
@@ -26,6 +27,8 @@ export type Metadata = {
     issues: Record<string, IssueMeta>;
     project?: ProjectMeta;
     linear?: LinearMeta;
+    defaultPermissionMode?: PermissionMode;
+    promptTemplate?: string;
 };
 export declare function readMetadata(repoRoot: string): Metadata;
 export declare function writeMetadata(repoRoot: string, data: Metadata): void;

package/dist/lib/metadata.js

@@ -1,11 +1,18 @@
 import * as fs from "fs";
 import { getMetadataPath } from "./git.js";
+import { PERMISSION_MODES } from "./claude.js";
 const EMPTY = { version: 1, issues: {} };
 function sanitizeProvider(raw) {
     if (raw === "github" || raw === "linear")
         return raw;
     return undefined;
 }
+function sanitizePermissionMode(raw) {
+    return PERMISSION_MODES.includes(raw) ? raw : undefined;
+}
+function sanitizePromptTemplate(raw) {
+    return typeof raw === "string" && raw.trim().length > 0 ? raw : undefined;
+}
 function sanitizeLinearTeam(raw) {
     if (typeof raw !== "object" || raw === null)
         return undefined;
@@ -77,6 +84,8 @@ export function readMetadata(repoRoot) {
         const project = sanitizeProject(parsed.project);
         const provider = sanitizeProvider(parsed.provider);
         const linear = sanitizeLinear(parsed.linear);
+        const defaultPermissionMode = sanitizePermissionMode(parsed.defaultPermissionMode);
+        const promptTemplate = sanitizePromptTemplate(parsed.promptTemplate);
         return {
             version: 1,
             issues: typeof parsed.issues === "object" && parsed.issues !== null
@@ -85,6 +94,8 @@ export function readMetadata(repoRoot) {
             ...(provider ? { provider } : {}),
             ...(project ? { project } : {}),
             ...(linear ? { linear } : {}),
+            ...(defaultPermissionMode ? { defaultPermissionMode } : {}),
+            ...(promptTemplate ? { promptTemplate } : {}),
         };
     }
     catch {

package/dist/lib/promptTemplate.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Variables available to a `promptTemplate` in `.mintree/metadata.json`.
+ * Kept intentionally small — the template seeds Claude's first message, it
+ * doesn't need the whole issue object.
+ */
+export type PromptVars = {
+    id: string;
+    title: string;
+    url: string;
+};
+export declare const PROMPT_PLACEHOLDERS: readonly ["{{id}}", "{{title}}", "{{url}}"];
+/**
+ * Renders a `promptTemplate` by substituting the `{{id}}`, `{{title}}` and
+ * `{{url}}` placeholders with the issue's values. Whitespace inside the braces
+ * is tolerated (`{{ id }}`). Unknown placeholders are left untouched so a typo
+ * is visible in the launched prompt instead of silently vanishing.
+ */
+export declare function renderPromptTemplate(template: string, vars: PromptVars): string;

package/dist/lib/promptTemplate.js

@@ -0,0 +1,15 @@
+// Placeholder tokens a user can drop into their `promptTemplate`. Documented
+// here so the README and any future `init`/help output stay in sync.
+export const PROMPT_PLACEHOLDERS = ["{{id}}", "{{title}}", "{{url}}"];
+/**
+ * Renders a `promptTemplate` by substituting the `{{id}}`, `{{title}}` and
+ * `{{url}}` placeholders with the issue's values. Whitespace inside the braces
+ * is tolerated (`{{ id }}`). Unknown placeholders are left untouched so a typo
+ * is visible in the launched prompt instead of silently vanishing.
+ */
+export function renderPromptTemplate(template, vars) {
+    return template
+        .replace(/\{\{\s*id\s*\}\}/g, vars.id)
+        .replace(/\{\{\s*title\s*\}\}/g, vars.title)
+        .replace(/\{\{\s*url\s*\}\}/g, vars.url);
+}

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.10",
 	"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": {