ticketlens 0.1.20 → 0.1.21

package/README.md

@@ -99,6 +99,8 @@ ticketlens CNV1-2 --check          # Append local VCS diff + Claude Code review
 ticketlens CNV1-2 --compliance     # Check ticket requirements against local diff [Pro/Free 3/mo]
 ticketlens CNV1-2 --summarize      # AI summary via your own API key (BYOK) [Pro]
 ticketlens CNV1-2 --summarize --cloud  # AI summary routed through TicketLens API [Pro]
+ticketlens CNV1-2 --handoff        # AI handoff brief from comment thread (BYOK) [Pro]
+ticketlens CNV1-2 --handoff --cloud    # AI handoff brief via TicketLens API [Pro]
 ```
 
 | `--depth` | Scope |
@@ -201,6 +203,7 @@ ticketlens standup --help                    # Standup subcommand help
 
 Scans `git log` for the configured window, extracts ticket keys from commit messages, and groups commits by ticket. Optionally fetches ticket summaries from your Jira profile to add context. Outputs a dated standup brief or a PR body depending on `--format`.
 
+**`--format=standup` (default)**
 ```
 ## Standup — Mon, May 18, 2026
 
@@ -214,6 +217,21 @@ Scans `git log` for the configured window, extracts ticket keys from commit mess
   jkl3456 chore: bump deps
 ```
 
+**`--format=pr`** — paste directly into a GitHub/GitLab PR description
+```
+## What changed
+
+- **PROJ-123** — Fix payment validation
+
+## Commits (3)
+
+- `abc1234` feat: PROJ-123 add payment validation check
+- `def5678` test: PROJ-123 payment validation tests
+- `jkl3456` chore: bump deps
+```
+
+When no commits reference a ticket key, `## What changed` shows `_No ticket references found in commits._` instead of a blank section.
+
 ---
 
 ### Cache
@@ -331,6 +349,8 @@ ticketlens CNV1-2 --check                    # Append local VCS diff + Claude Co
 ticketlens CNV1-2 --compliance               # Check ticket requirements against local diff [Pro/Free 3/mo]
 ticketlens CNV1-2 --summarize                # AI summary via your own API key (BYOK) [Pro]
 ticketlens CNV1-2 --summarize --cloud        # AI summary via TicketLens API [Pro]
+ticketlens CNV1-2 --handoff                  # AI handoff brief from comment thread (BYOK) [Pro]
+ticketlens CNV1-2 --handoff --cloud          # AI handoff brief via TicketLens API [Pro]
 ticketlens CNV1-2 --depth=2 --profile=acme --plain   # Combine flags freely
 
 # Pipe plain output to clipboard, LLM, or file
@@ -433,6 +453,8 @@ Start free, upgrade when you need it — `ticketlens activate <key>`
 ```bash
 ticketlens CNV1-2 --summarize            # AI summary via your own API key (BYOK)
 ticketlens CNV1-2 --summarize --cloud    # AI summary via TicketLens API (no local key needed)
+ticketlens CNV1-2 --handoff              # AI handoff brief from the ticket's comment thread (BYOK)
+ticketlens CNV1-2 --handoff --cloud      # AI handoff brief via TicketLens API
 ticketlens CNV1-2 --compliance           # Check ticket requirements against local diff [Free 3/mo]
 ticketlens triage --stale=3              # Custom stale threshold (default is 5)
 ticketlens triage --digest               # POST scored triage results to digest endpoint
@@ -440,6 +462,15 @@ ticketlens schedule                      # Set up a scheduled daily digest
 ticketlens activate YOUR-LICENSE-KEY     # Activate Pro license
 ```
 
+**`--handoff`** synthesizes the comment thread into a structured one-pager for the developer picking up the ticket. No context-reading required — the AI reads the full comment history and returns:
+
+- **What was attempted** — concrete work already done
+- **Current blockers** — unresolved issues
+- **Open questions** — decisions not yet made
+- **Recommendation** — where to start
+
+Add `ANTHROPIC_API_KEY` or `OPENAI_API_KEY` to `~/.ticketlens/credentials.json` for BYOK, or use `--cloud` to route through the TicketLens API.
+
 <div align="center">
   <img src="docs/demos/pro-triage.gif" alt="ticketlens triage --stale=3 demo" width="700" />
 </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticketlens",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "Jira CLI for developers — fetch ticket context, triage your queue, and stop tab-switching. Zero dependencies, all local.",
   "type": "module",
   "bin": {

package/skills/jtb/scripts/fetch-ticket.mjs

@@ -145,6 +145,38 @@ async function applySummarize(brief, args, opts, configDir, conn, licensedFn, up
   }
 }
 
+/**
+ * Apply --handoff: generate a structured handoff brief from the ticket's comment thread.
+ * Returns the handoff brief string, or null if the caller should exit (license gate / error).
+ */
+async function applyHandoff(ticket, args, opts, configDir, licensedFn, upgradeFn) {
+  if (!licensedFn('pro', configDir)) {
+    upgradeFn('pro', '--handoff');
+    process.exitCode = 1;
+    return null;
+  }
+
+  const mode = args.includes('--cloud') ? 'cloud' : 'byok';
+
+  try {
+    const { buildHandoffInput, HANDOFF_PROMPT } = await import('./lib/handoff-assembler.mjs');
+    const summarizerFn = opts.summarizer ?? (async (sumOpts) => {
+      const { summarize } = await import('./lib/summarizer.mjs');
+      return summarize(sumOpts);
+    });
+    const credentials = opts.credentials ?? loadCredentials(configDir);
+    const licenseKey = readLicense(configDir)?.key;
+    const input = buildHandoffInput(ticket);
+    const body = await summarizerFn({ brief: input, mode, credentials, licenseKey, prompt: HANDOFF_PROMPT, maxTokens: 512 });
+    return `## Handoff Brief — ${ticket.key}\n\n${body}\n`;
+  } catch (err) {
+    const onErrorFn = opts.onError ?? ((msg) => process.stderr.write(msg + '\n'));
+    onErrorFn(`Could not generate handoff brief: ${err.message}`);
+    process.exitCode = 1;
+    return null;
+  }
+}
+
 function makeSpinner(s) {
   // setInterval won't fire while spawnSync blocks the event loop, so we draw
   // synchronously on update() and only use setInterval during async fetch phases.
@@ -783,7 +815,7 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
 
   const validatedArgs = await handleUnknownFlags(
     args,
-    ['--help', '-h', '--plain', '--styled', '--no-attachments', '--no-cache', '--profile=', '--depth=', '--check', '--summarize', '--cloud', '--compliance', '--budget='],
+    ['--help', '-h', '--plain', '--styled', '--no-attachments', '--no-cache', '--profile=', '--depth=', '--check', '--summarize', '--cloud', '--compliance', '--budget=', '--handoff'],
     { hints: ['--stale=', '--status=', '--static'] } // triage-only flags — shown as hints, not applied
   );
   if (validatedArgs === null) { process.exitCode = 1; return; }
@@ -905,6 +937,13 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
         ? plainBrief
         : (useStyled ? styleBrief(cached.ticket, codeRefs, { styled: true }) : plainBrief);
 
+      if (args.includes('--handoff')) {
+        const handoffResult = await applyHandoff(cached.ticket, args, opts, configDir, licensedFn, upgradeFn);
+        if (handoffResult === null) return;
+        printFn(handoffResult);
+        return;
+      }
+
       if (args.includes('--check')) brief = applyCheck(brief, opts);
 
       if (args.includes('--summarize')) {
@@ -1084,6 +1123,13 @@ export async function run(args, envOrOpts = process.env, fetcher = globalThis.fe
     ? plainOutput
     : (useStyled ? styleBrief(ticket, codeRefs, { styled: true }) : plainOutput);
 
+  if (args.includes('--handoff')) {
+    const handoffResult = await applyHandoff(ticket, args, opts, configDir, licensedFn, upgradeFn);
+    if (handoffResult === null) return;
+    printFn(handoffResult);
+    return;
+  }
+
   if (args.includes('--check')) output = applyCheck(output, opts);
 
   if (args.includes('--summarize')) {

package/skills/jtb/scripts/lib/handoff-assembler.mjs

@@ -0,0 +1,59 @@
+export const HANDOFF_PROMPT = `Build a structured handoff brief from this Jira ticket's comment thread.
+The developer receiving this ticket has never seen it before — they need to get up to speed immediately.
+
+Respond in exactly this format (use the exact headings):
+
+### What was attempted
+[2–5 bullet points of concrete work already done, based on the comments. Be specific — mention code paths, methods, or files if the comments reference them.]
+
+### Current blockers
+[Bullet points of unresolved issues, errors, or dependencies blocking progress. Write "None identified" if the comments suggest the path is clear.]
+
+### Open questions
+[Bullet points of unanswered questions or decisions not yet made. Write "None identified" if everything is resolved.]
+
+### Recommendation
+[1–2 sentences on the best starting point for the incoming developer.]
+
+Rules:
+- Be specific and factual. Reference actual details from the comments.
+- Do not invent anything not present in the comments.
+- Keep each bullet under 20 words.
+- If there are no comments, state that clearly in each section.
+
+`;
+
+/**
+ * Build the text input sent to the AI for handoff analysis.
+ * Contains the ticket header and full comment thread.
+ *
+ * @param {object} ticket - Normalized ticket object from jira-client.normalizeTicket
+ * @returns {string}
+ */
+export function buildHandoffInput(ticket) {
+  const lines = [];
+
+  const summary = ticket.summary ?? '(no summary)';
+  lines.push(`Ticket: ${ticket.key} — ${summary}`);
+  lines.push(`Status: ${ticket.status ?? 'Unknown'}`);
+  lines.push(`Assignee: ${ticket.assignee ?? 'Unassigned'}`);
+  if (ticket.reporter) lines.push(`Reporter: ${ticket.reporter}`);
+  lines.push('');
+
+  const comments = ticket.comments ?? [];
+  lines.push(`--- Comments (${comments.length} total) ---`);
+
+  if (comments.length === 0) {
+    lines.push('(no comments)');
+  } else {
+    for (let i = 0; i < comments.length; i++) {
+      const c = comments[i];
+      const dateStr = c.created ? c.created.slice(0, 10) : 'unknown date';
+      lines.push('');
+      lines.push(`[${i + 1}] ${c.author ?? 'Unknown'} — ${dateStr}`);
+      lines.push(c.body ?? '');
+    }
+  }
+
+  return lines.join('\n');
+}

package/skills/jtb/scripts/lib/help.mjs

@@ -61,7 +61,8 @@ export function printHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--check')}            Append VCS diff + review instructions for Claude Code`,
     `    ${s.brand('--compliance')}       Check ticket requirements against local diff  ${s.dim('[Pro/Free 3/mo]')}`,
     `    ${s.brand('--summarize')}        Generate AI summary ${s.dim('(BYOK or --cloud) [Pro]')}`,
-    `    ${s.brand('--cloud')}            Route summary through TicketLens API ${s.dim('[Pro]')}`,
+    `    ${s.brand('--handoff')}          AI handoff brief from comment thread ${s.dim('(BYOK or --cloud) [Pro]')}`,
+    `    ${s.brand('--cloud')}            Route AI request through TicketLens API ${s.dim('[Pro]')}`,
     '',
     `  ${s.bold('TRIAGE OPTIONS')}`,
     '',
@@ -128,7 +129,8 @@ export function printFetchHelp({ stream = process.stdout } = {}) {
     `    ${s.brand('--check')}            Append VCS diff + review instructions for Claude Code`,
     `    ${s.brand('--compliance')}       Check ticket requirements against local diff  ${s.dim('[Pro/Free 3/mo]')}`,
     `    ${s.brand('--summarize')}        Generate AI summary ${s.dim('(BYOK or --cloud) [Pro]')}`,
-    `    ${s.brand('--cloud')}            Route summary through TicketLens API ${s.dim('[Pro]')}`,
+    `    ${s.brand('--handoff')}          AI handoff brief from comment thread ${s.dim('(BYOK or --cloud) [Pro]')}`,
+    `    ${s.brand('--cloud')}            Route AI request through TicketLens API ${s.dim('[Pro]')}`,
     `    ${s.brand('-h')}, ${s.brand('--help')}         Show this help`,
     '',
     `  ${s.bold('EXAMPLES')}`,
@@ -136,6 +138,8 @@ export function printFetchHelp({ stream = process.stdout } = {}) {
     `    ${s.dim('$')} ticketlens PROJ-123`,
     `    ${s.dim('$')} ticketlens PROJ-123 --depth=0`,
     `    ${s.dim('$')} ticketlens PROJ-123 --profile=acme --depth=2`,
+    `    ${s.dim('$')} ticketlens PROJ-123 --handoff`,
+    `    ${s.dim('$')} ticketlens PROJ-123 --handoff --cloud`,
     '',
   ];
   stream.write(lines.join('\n') + '\n');

package/skills/jtb/scripts/lib/summarizer.mjs

@@ -1,7 +1,8 @@
 const ANTHROPIC_URL = 'https://api.anthropic.com/v1/messages';
 const OPENAI_URL = 'https://api.openai.com/v1/chat/completions';
 const CLOUD_URL = 'https://api.ticketlens.dev/v1/summarize';
-const PROMPT = 'Summarize this Jira ticket in 3 sentences. Focus on what matters most for implementation. Be concrete.\n\n';
+const DEFAULT_PROMPT = 'Summarize this Jira ticket in 3 sentences. Focus on what matters most for implementation. Be concrete.\n\n';
+const DEFAULT_MAX_TOKENS = 256;
 
 /**
  * Summarize a ticket brief using BYOK or cloud mode.
@@ -14,14 +15,16 @@ const PROMPT = 'Summarize this Jira ticket in 3 sentences. Focus on what matters
  * @param {number} [opts.timeoutMs]
  * @returns {Promise<string>} Summary text
  */
-export async function summarize({ brief, mode, credentials = null, licenseKey = null, fetcher = globalThis.fetch, timeoutMs = 30_000 }) {
+export async function summarize({ brief, mode, credentials = null, licenseKey = null, fetcher = globalThis.fetch, timeoutMs = 30_000, prompt, maxTokens }) {
+  const effectivePrompt = prompt ?? DEFAULT_PROMPT;
+  const effectiveMaxTokens = maxTokens ?? DEFAULT_MAX_TOKENS;
   if (mode === 'byok') {
-    return byok({ brief, credentials, fetcher, timeoutMs });
+    return byok({ brief, credentials, fetcher, timeoutMs, prompt: effectivePrompt, maxTokens: effectiveMaxTokens });
   }
   return cloud({ brief, licenseKey, fetcher, timeoutMs });
 }
 
-async function byok({ brief, credentials, fetcher, timeoutMs }) {
+async function byok({ brief, credentials, fetcher, timeoutMs, prompt, maxTokens }) {
   const anthropicKey = credentials?.anthropicApiKey;
   const openaiKey = credentials?.openaiApiKey;
 
@@ -30,13 +33,13 @@ async function byok({ brief, credentials, fetcher, timeoutMs }) {
   }
 
   if (anthropicKey) {
-    return callAnthropic({ brief, apiKey: anthropicKey, fetcher, timeoutMs });
+    return callAnthropic({ brief, apiKey: anthropicKey, fetcher, timeoutMs, prompt, maxTokens });
   }
 
-  return callOpenAi({ brief, apiKey: openaiKey, fetcher, timeoutMs });
+  return callOpenAi({ brief, apiKey: openaiKey, fetcher, timeoutMs, prompt, maxTokens });
 }
 
-async function callAnthropic({ brief, apiKey, fetcher, timeoutMs }) {
+async function callAnthropic({ brief, apiKey, fetcher, timeoutMs, prompt, maxTokens }) {
   const res = await fetcher(ANTHROPIC_URL, {
     method: 'POST',
     signal: AbortSignal.timeout(timeoutMs),
@@ -47,8 +50,8 @@ async function callAnthropic({ brief, apiKey, fetcher, timeoutMs }) {
     },
     body: JSON.stringify({
       model: 'claude-haiku-4-5-20251001',
-      max_tokens: 256,
-      messages: [{ role: 'user', content: PROMPT + brief }],
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: prompt + brief }],
     }),
   });
 
@@ -62,7 +65,7 @@ async function callAnthropic({ brief, apiKey, fetcher, timeoutMs }) {
   return data.content[0].text;
 }
 
-async function callOpenAi({ brief, apiKey, fetcher, timeoutMs }) {
+async function callOpenAi({ brief, apiKey, fetcher, timeoutMs, prompt, maxTokens }) {
   const res = await fetcher(OPENAI_URL, {
     method: 'POST',
     signal: AbortSignal.timeout(timeoutMs),
@@ -72,8 +75,8 @@ async function callOpenAi({ brief, apiKey, fetcher, timeoutMs }) {
     },
     body: JSON.stringify({
       model: 'gpt-4o-mini',
-      max_tokens: 256,
-      messages: [{ role: 'user', content: PROMPT + brief }],
+      max_tokens: maxTokens,
+      messages: [{ role: 'user', content: prompt + brief }],
     }),
   });