@dreki-gg/pi-plan-mode 0.24.1 → 0.25.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.25.0
+
+### Minor Changes
+
+- Add `@plan:<slug>` plan references with autocomplete. Type `@plan:` in any message to fuzzy-search and tag a plan (all plans listed, in-progress first), and on send the referenced plan's tasks + handoff are attached as context so the agent understands the reference. Resolution is context-only — it never switches execution mode, tools, or model — and follows first-wins when multiple tokens are present.
+
 ## 0.24.1
 
 ### Patch Changes

package/extensions/plan-mode/__tests__/plan-references-autocomplete.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, test } from 'bun:test';
+import { filterPlanReferences, formatPlanSuggestion } from '../references/autocomplete.js';
+import type { PlanListItem } from '../commands/list-plans.js';
+
+function item(overrides: Partial<PlanListItem> & { name: string }): PlanListItem {
+  return {
+    title: `Title ${overrides.name}`,
+    status: 'in-progress',
+    created_at: '2026-01-01T00:00:00.000Z',
+    completed_at: null,
+    totalTasks: 3,
+    doneTasks: 1,
+    pendingTasks: 2,
+    ...overrides,
+  };
+}
+
+const items: PlanListItem[] = [
+  item({ name: 'done-plan', status: 'done' }),
+  item({ name: 'active-one', status: 'in-progress' }),
+  item({ name: 'abandoned-plan', status: 'abandoned' }),
+  item({ name: 'active-two', status: 'in-progress' }),
+];
+
+describe('filterPlanReferences', () => {
+  test('empty query lists all plans, in-progress first', () => {
+    const result = filterPlanReferences(items, '');
+    expect(result.map((p) => p.name).slice(0, 2).sort()).toEqual(['active-one', 'active-two']);
+    expect(result).toHaveLength(4);
+  });
+
+  test('name-prefix matches win', () => {
+    const result = filterPlanReferences(items, 'active-t');
+    expect(result[0].name).toBe('active-two');
+  });
+
+  test('fuzzy fallback finds non-prefix matches', () => {
+    const result = filterPlanReferences(items, 'abandon');
+    expect(result.some((p) => p.name === 'abandoned-plan')).toBe(true);
+  });
+
+  test('returns empty array for no match', () => {
+    expect(filterPlanReferences(items, 'zzz-nope-nope')).toHaveLength(0);
+  });
+});
+
+describe('formatPlanSuggestion', () => {
+  test('builds a @plan: value with status + progress description', () => {
+    const suggestion = formatPlanSuggestion(item({ name: 'active-one', status: 'in-progress' }));
+    expect(suggestion.value).toBe('@plan:active-one');
+    expect(suggestion.label).toContain('Title active-one');
+    expect(suggestion.description).toContain('active-one');
+    expect(suggestion.description).toContain('1/3');
+  });
+});

package/extensions/plan-mode/__tests__/plan-references-context.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { chdir } from 'node:process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { makePlanRuntime } from '../effects/runtime.js';
+import { upsertPlanEntry } from '../storage/plans-manifest.js';
+import { writeTasksJsonl } from '../storage/task-storage.js';
+import { saveHandoff } from '../storage/plan-storage.js';
+import type { TaskMeta, TaskRecord } from '../types.js';
+import { buildPlanContextPack, resolvePlanReference } from '../references/context.js';
+
+const runPlanIO = makePlanRuntime();
+const originalCwd = process.cwd();
+let dir: string;
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-refctx-'));
+  chdir(dir);
+});
+
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+const meta: TaskMeta = {
+  _type: 'meta',
+  title: 'Add Auth',
+  plan_name: 'add-auth',
+  created_at: '2026-01-01T00:00:00.000Z',
+};
+
+const tasks: TaskRecord[] = [
+  {
+    _type: 'task',
+    id: 't-001',
+    description: 'Write middleware',
+    status: 'done',
+    origin: 'plan',
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+  },
+  {
+    _type: 'task',
+    id: 't-002',
+    description: 'Wire routes',
+    status: 'pending',
+    origin: 'plan',
+    created_at: '2026-01-01T00:00:00.000Z',
+    updated_at: '2026-01-01T00:00:00.000Z',
+  },
+];
+
+describe('buildPlanContextPack', () => {
+  test('includes title, status, tasks, and handoff', () => {
+    const pack = buildPlanContextPack('add-auth', 'Add Auth', 'in-progress', tasks, 'Handoff body');
+    expect(pack).toContain('Add Auth');
+    expect(pack).toContain('add-auth');
+    expect(pack).toContain('in-progress');
+    expect(pack).toContain('t-001');
+    expect(pack).toContain('Write middleware');
+    expect(pack).toContain('t-002');
+    expect(pack).toContain('Handoff body');
+  });
+});
+
+describe('resolvePlanReference', () => {
+  test('resolves a real plan on disk', async () => {
+    await runPlanIO(upsertPlanEntry('add-auth', { status: 'in-progress', title: 'Add Auth' }));
+    await runPlanIO(writeTasksJsonl('.plans/add-auth', meta, tasks));
+    await runPlanIO(saveHandoff('.plans/add-auth', 'Handoff body'));
+
+    const resolved = await runPlanIO(resolvePlanReference('add-auth'));
+    expect(resolved).toBeDefined();
+    expect(resolved?.title).toBe('Add Auth');
+    expect(resolved?.status).toBe('in-progress');
+    expect(resolved?.tasks).toHaveLength(2);
+    expect(resolved?.handoff).toBe('Handoff body');
+  });
+
+  test('returns undefined for an unknown slug', async () => {
+    const resolved = await runPlanIO(resolvePlanReference('nope'));
+    expect(resolved).toBeUndefined();
+  });
+});

package/extensions/plan-mode/__tests__/plan-references-tokens.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  PLAN_TOKEN_PREFIX,
+  buildPlanToken,
+  parsePlanSlug,
+  findActivePlanToken,
+  extractPlanReferences,
+  firstPlanReference,
+} from '../references/tokens.js';
+
+describe('buildPlanToken / parsePlanSlug', () => {
+  test('round-trips a slug', () => {
+    const token = buildPlanToken('add-auth-middleware');
+    expect(token).toBe(`${PLAN_TOKEN_PREFIX}add-auth-middleware`);
+    expect(parsePlanSlug(token)).toBe('add-auth-middleware');
+  });
+
+  test('parsePlanSlug returns undefined for non-plan tokens', () => {
+    expect(parsePlanSlug('@chat:abc')).toBeUndefined();
+    expect(parsePlanSlug('@plan:')).toBeUndefined();
+  });
+});
+
+describe('findActivePlanToken', () => {
+  test('detects a token being typed at the cursor', () => {
+    const active = findActivePlanToken('start working on @plan:add-au');
+    expect(active?.query).toBe('add-au');
+    expect(active?.token).toBe('@plan:add-au');
+  });
+
+  test('detects an empty query right after the prefix', () => {
+    const active = findActivePlanToken('do @plan:');
+    expect(active?.query).toBe('');
+  });
+
+  test('returns undefined when there is no token at the cursor', () => {
+    expect(findActivePlanToken('just some text')).toBeUndefined();
+    expect(findActivePlanToken('email me@plan-b.com')).toBeUndefined();
+  });
+
+  test('does not match when the token is not adjacent to the cursor', () => {
+    expect(findActivePlanToken('@plan:foo and more text')).toBeUndefined();
+  });
+});
+
+describe('extractPlanReferences / firstPlanReference', () => {
+  test('extracts all tokens in order', () => {
+    const tokens = extractPlanReferences('work on @plan:alpha then @plan:beta');
+    expect(tokens).toEqual(['@plan:alpha', '@plan:beta']);
+  });
+
+  test('first-wins helper returns only the first slug', () => {
+    expect(firstPlanReference('work on @plan:alpha then @plan:beta')).toBe('alpha');
+  });
+
+  test('firstPlanReference returns undefined when no token present', () => {
+    expect(firstPlanReference('nothing here')).toBeUndefined();
+  });
+
+  test('does not treat email-like text as a token', () => {
+    expect(extractPlanReferences('reach me@plan-x.dev')).toEqual([]);
+  });
+});

package/extensions/plan-mode/index.ts

@@ -57,11 +57,16 @@ import { registerReconcilePlansTool } from './tools/reconcile-plans.js';
 import { isSafeCommand, isPlanPath } from './utils.js';
 import { handleListPlans } from './commands/list-plans.js';
 import { handleListInitiatives } from './commands/list-initiatives.js';
+import { createPlanReferenceIndex } from './references/plan-index.js';
+import { registerPlanReferenceAutocomplete } from './references/autocomplete.js';
+import { registerPlanReferenceContext } from './references/context.js';
 
 export default function planMode(pi: ExtensionAPI): void {
   const state = new PlanModeState();
   // Build the live Effect runtime once; all storage I/O runs through this bridge.
   const runPlanIO = makePlanRuntime();
+  // Cached plan list for `@plan:<slug>` autocomplete; refreshed at session start.
+  const planReferenceIndex = createPlanReferenceIndex(runPlanIO);
 
   // ── Flag ──────────────────────────────────────────────────────────────────
   pi.registerFlag('plan', {
@@ -200,6 +205,9 @@ export default function planMode(pi: ExtensionAPI): void {
   registerInitiativeStatusTool(pi, runPlanIO);
   registerReconcilePlansTool(pi, runPlanIO);
 
+  // Attach a referenced plan (`@plan:<slug>`) as context when present in a prompt.
+  registerPlanReferenceContext(pi, runPlanIO);
+
   registerAddTaskTool(pi, {
     resolvePlan: (opts) => resolveActivePlan(state, pi, runPlanIO, opts),
     onTaskAdded: async (task) => {
@@ -602,6 +610,10 @@ export default function planMode(pi: ExtensionAPI): void {
       ctx.sessionManager.getEntries() as Array<{ type: string; customType?: string; data?: any }>,
     );
 
+    // Register `@plan:<slug>` autocomplete and warm its cache.
+    await planReferenceIndex.refresh();
+    registerPlanReferenceAutocomplete(ctx, planReferenceIndex);
+
     // Check for exec-pending handoff from planning session
     const pending = await runPlanIO(readAndClearExecPending());
     if (pending) {

package/extensions/plan-mode/references/autocomplete.ts

@@ -0,0 +1,120 @@
+/**
+ * `@plan:` autocomplete provider — stacks on top of the built-in provider.
+ *
+ * Lists all plans, ranking in-progress first. Empty query keeps that ordering;
+ * a non-empty query prefers exact name-prefix matches and otherwise falls back
+ * to a fuzzy search over name + title.
+ */
+
+import type { ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type {
+  AutocompleteItem,
+  AutocompleteProvider,
+  AutocompleteSuggestions,
+} from '@earendil-works/pi-tui';
+import { fuzzyFilter } from '@earendil-works/pi-tui';
+import type { PlanListItem } from '../commands/list-plans.js';
+import type { PlanStatus } from '../types.js';
+import { buildPlanToken, findActivePlanToken } from './tokens.js';
+import type { PlanReferenceIndex } from './plan-index.js';
+
+const MAX_SUGGESTIONS = 20;
+
+const STATUS_ICON: Record<PlanStatus, string> = {
+  'in-progress': '🔵',
+  done: '✅',
+  superseded: '🔄',
+  abandoned: '❌',
+};
+
+const STATUS_RANK: Record<PlanStatus, number> = {
+  'in-progress': 0,
+  done: 1,
+  superseded: 2,
+  abandoned: 3,
+};
+
+/** In-progress first, then newest plans within each status group. */
+function byInProgressFirst(a: PlanListItem, b: PlanListItem): number {
+  const rank = STATUS_RANK[a.status] - STATUS_RANK[b.status];
+  if (rank !== 0) return rank;
+  return b.created_at.localeCompare(a.created_at);
+}
+
+export function filterPlanReferences(items: PlanListItem[], query: string): PlanListItem[] {
+  const trimmed = query.trim().toLowerCase();
+  if (!trimmed) {
+    return [...items].sort(byInProgressFirst).slice(0, MAX_SUGGESTIONS);
+  }
+
+  const prefixMatches = items
+    .filter((item) => item.name.toLowerCase().startsWith(trimmed))
+    .sort(byInProgressFirst);
+  if (prefixMatches.length) return prefixMatches.slice(0, MAX_SUGGESTIONS);
+
+  return fuzzyFilter(items, trimmed, (item) => `${item.name} ${item.title}`).slice(
+    0,
+    MAX_SUGGESTIONS,
+  );
+}
+
+export function formatPlanSuggestion(item: PlanListItem): AutocompleteItem {
+  const progress = item.totalTasks > 0 ? `${item.doneTasks}/${item.totalTasks} tasks` : 'no tasks';
+  return {
+    value: buildPlanToken(item.name),
+    label: `${item.title}`,
+    description: `${STATUS_ICON[item.status]} ${item.name} • ${item.status} • ${progress}`,
+  };
+}
+
+export function createPlanReferenceAutocompleteProvider(
+  current: AutocompleteProvider,
+  index: PlanReferenceIndex,
+): AutocompleteProvider {
+  return {
+    async getSuggestions(
+      lines,
+      cursorLine,
+      cursorCol,
+      options,
+    ): Promise<AutocompleteSuggestions | null> {
+      const line = lines[cursorLine] ?? '';
+      const beforeCursor = line.slice(0, cursorCol);
+      const active = findActivePlanToken(beforeCursor);
+      if (!active) return current.getSuggestions(lines, cursorLine, cursorCol, options);
+
+      const items = await index.getItems();
+      if (options.signal.aborted) return null;
+
+      const matches = filterPlanReferences(items, active.query);
+      if (matches.length === 0) {
+        return current.getSuggestions(lines, cursorLine, cursorCol, options);
+      }
+
+      return {
+        prefix: active.token,
+        items: matches.map(formatPlanSuggestion),
+      };
+    },
+
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      return current.applyCompletion(lines, cursorLine, cursorCol, item, prefix);
+    },
+
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      const line = lines[cursorLine] ?? '';
+      const beforeCursor = line.slice(0, cursorCol);
+      if (findActivePlanToken(beforeCursor)) return false;
+      return current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ?? true;
+    },
+  };
+}
+
+export function registerPlanReferenceAutocomplete(
+  ctx: ExtensionContext,
+  index: PlanReferenceIndex,
+): void {
+  ctx.ui.addAutocompleteProvider((current) =>
+    createPlanReferenceAutocompleteProvider(current, index),
+  );
+}

package/extensions/plan-mode/references/context.ts

@@ -0,0 +1,140 @@
+/**
+ * `@plan:` context injection.
+ *
+ * When a submitted message references a plan with `@plan:<slug>`, attach that
+ * plan's tasks + handoff as a hidden context message so the agent understands
+ * the reference. First-wins: only the first token in the message is resolved.
+ *
+ * This is *context only* — it never switches execution mode, tools, or model.
+ */
+
+import { Effect } from 'effect';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { FileSystem } from '../effects/filesystem.js';
+import type { RunPlanIO } from '../effects/runtime.js';
+import type { PlanStatus, TaskRecord, TaskStatus } from '../types.js';
+import { readPlansManifest } from '../storage/plans-manifest.js';
+import { readTasksJsonl } from '../storage/task-storage.js';
+import { loadHandoff } from '../storage/plan-storage.js';
+import { firstPlanReference } from './tokens.js';
+
+export interface ResolvedPlanReference {
+  name: string;
+  title: string;
+  status: PlanStatus;
+  tasks: TaskRecord[];
+  handoff: string;
+}
+
+const TASK_ICON: Record<TaskStatus, string> = {
+  pending: '○',
+  done: '✓',
+  skipped: '⊘',
+  blocked: '✗',
+  deferred: '⏸',
+};
+
+/** Resolve a plan slug to its registry entry + tasks + handoff (Effect-based). */
+export function resolvePlanReference(
+  slug: string,
+): Effect.Effect<ResolvedPlanReference | undefined, never, FileSystem> {
+  return Effect.gen(function* () {
+    const manifest = yield* Effect.orElseSucceed(readPlansManifest(), () => []);
+    const entry = manifest.find((candidate) => candidate.name === slug);
+    if (!entry) return undefined;
+
+    const dir = `.plans/${slug}`;
+    const snapshot = yield* Effect.orElseSucceed(readTasksJsonl(dir), () => undefined);
+    const handoff = yield* loadHandoff(dir);
+
+    return {
+      name: entry.name,
+      title: entry.title,
+      status: entry.status,
+      tasks: snapshot?.tasks ?? [],
+      handoff: handoff ?? '',
+    };
+  });
+}
+
+/** Build the markdown context pack injected for a resolved plan reference. */
+export function buildPlanContextPack(
+  name: string,
+  title: string,
+  status: PlanStatus,
+  tasks: TaskRecord[],
+  handoff: string,
+): string {
+  const done = tasks.filter((t) => t.status === 'done' || t.status === 'skipped').length;
+  const taskLines = tasks.length
+    ? tasks
+        .map((t) => {
+          const marker = t.origin === 'discovered' ? ' (discovered)' : '';
+          const notes = t.notes ? `\n   ${t.notes}` : '';
+          return `${t.id}. ${TASK_ICON[t.status]} ${t.description}${marker}${notes}`;
+        })
+        .join('\n')
+    : '_(no tasks)_';
+
+  return [
+    `# Referenced plan: ${title} (\`${name}\`)`,
+    `The user referenced this plan with \`@plan:${name}\`. Status: **${status}** — ${done}/${tasks.length} tasks done.`,
+    `Use this as context. The source of truth is \`.plans/${name}/\` (tasks.jsonl + HANDOFF.md) — inspect it with tools if you need more detail.`,
+    '',
+    '## Tasks',
+    '',
+    taskLines,
+    '',
+    '## Handoff',
+    '',
+    handoff.trim() || '_(no handoff recorded)_',
+  ].join('\n');
+}
+
+/**
+ * Register the `before_agent_start` handler that attaches a referenced plan as
+ * context. Chains alongside plan-mode's own `before_agent_start` handler.
+ */
+export function registerPlanReferenceContext(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.on('before_agent_start', async (event, ctx) => {
+    const slug = firstPlanReference(event.prompt);
+    if (!slug) return undefined;
+
+    const resolved = await runPlanIO(resolvePlanReference(slug));
+
+    if (!resolved) {
+      if (ctx.hasUI) {
+        ctx.ui.notify(`plan-mode: no plan named "${slug}" for @plan:${slug}`, 'warning');
+      }
+      return {
+        message: {
+          customType: 'plan-reference-context',
+          content: `The prompt referenced @plan:${slug}, but no plan with that name exists in .plans/plans.jsonl.`,
+          display: true,
+          details: { slug, resolved: false },
+        },
+      };
+    }
+
+    const content = buildPlanContextPack(
+      resolved.name,
+      resolved.title,
+      resolved.status,
+      resolved.tasks,
+      resolved.handoff,
+    );
+
+    if (ctx.hasUI) {
+      ctx.ui.notify(`Attached plan reference: ${resolved.title} (${resolved.name}).`, 'info');
+    }
+
+    return {
+      message: {
+        customType: 'plan-reference-context',
+        content,
+        display: false,
+        details: { slug, name: resolved.name, status: resolved.status, resolved: true },
+      },
+    };
+  });
+}

package/extensions/plan-mode/references/plan-index.ts

@@ -0,0 +1,55 @@
+/**
+ * In-memory cache of plan list items for `@plan:` autocomplete.
+ *
+ * Autocomplete `getSuggestions` runs on every keystroke, so it must be cheap.
+ * We cache the manifest-derived `PlanListItem[]` and refresh at most once per
+ * TTL window — fresh enough to surface plans submitted mid-session without a
+ * per-keystroke disk hit.
+ */
+
+import type { RunPlanIO } from '../effects/runtime.js';
+import { loadPlanListItems, type PlanListItem } from '../commands/list-plans.js';
+
+const DEFAULT_TTL_MS = 2_000;
+
+export interface PlanReferenceIndex {
+  /** Force a reload from disk. */
+  refresh(): Promise<void>;
+  /** Cached items, reloading first when the cache is stale. */
+  getItems(): Promise<PlanListItem[]>;
+  /** Cached items without triggering IO (may be stale or empty). */
+  peek(): PlanListItem[];
+}
+
+export function createPlanReferenceIndex(
+  runPlanIO: RunPlanIO,
+  ttlMs: number = DEFAULT_TTL_MS,
+): PlanReferenceIndex {
+  let items: PlanListItem[] = [];
+  let loadedAt = 0;
+  let inflight: Promise<void> | undefined;
+
+  const load = async (): Promise<void> => {
+    items = await runPlanIO(loadPlanListItems());
+    loadedAt = Date.now();
+  };
+
+  const refresh = async (): Promise<void> => {
+    // Coalesce concurrent refreshes so rapid keystrokes share one read.
+    if (!inflight) {
+      inflight = load().finally(() => {
+        inflight = undefined;
+      });
+    }
+    await inflight;
+  };
+
+  return {
+    refresh,
+    peek: () => items,
+    async getItems() {
+      if (Date.now() - loadedAt > ttlMs) await refresh();
+      return items;
+    },
+  };
+}

package/extensions/plan-mode/references/tokens.ts

@@ -0,0 +1,76 @@
+/**
+ * `@plan:<slug>` reference tokens.
+ *
+ * Lets a user reference a plan inside a normal chat message (e.g.
+ * "start working on @plan:add-auth"). Mirrors the past-chats `@chat:` /
+ * `@session:` token model: a cursor-anchored matcher drives autocomplete, and a
+ * global matcher extracts referenced slugs from a submitted prompt.
+ *
+ * Pure module — no IO, safe to unit test.
+ */
+
+export const PLAN_TOKEN_PREFIX = '@plan:' as const;
+
+/** Plan slugs are kebab-ish identifiers. */
+const SLUG_CHARS = 'A-Za-z0-9_-';
+
+export interface ActivePlanToken {
+  /** The query typed after the prefix (may be empty). */
+  query: string;
+  /** The full token under the cursor, including the prefix. */
+  token: string;
+  /** Offset in the line where the token starts. */
+  tokenStart: number;
+}
+
+export function buildPlanToken(slug: string): string {
+  return `${PLAN_TOKEN_PREFIX}${slug}`;
+}
+
+/** Extract the slug from a `@plan:<slug>` token, or undefined when invalid. */
+export function parsePlanSlug(token: string): string | undefined {
+  if (!token.startsWith(PLAN_TOKEN_PREFIX)) return undefined;
+  const slug = token.slice(PLAN_TOKEN_PREFIX.length).trim();
+  return slug || undefined;
+}
+
+// Token must be at a word boundary: start of line or after whitespace / open
+// bracket. Prevents matching inside emails like `me@plan-x.dev`.
+const ACTIVE_RE = new RegExp(`(?:^|[\\s([{])(${PLAN_TOKEN_PREFIX}([${SLUG_CHARS}]*))$`);
+const GLOBAL_RE = new RegExp(
+  `(?:^|[\\s([{])(${PLAN_TOKEN_PREFIX}([${SLUG_CHARS}]+))`,
+  'g',
+);
+
+/** Detect a `@plan:` token being typed immediately before the cursor. */
+export function findActivePlanToken(textBeforeCursor: string): ActivePlanToken | undefined {
+  const match = textBeforeCursor.match(ACTIVE_RE);
+  if (!match) return undefined;
+  const token = match[1] ?? '';
+  return {
+    query: match[2] ?? '',
+    token,
+    tokenStart: textBeforeCursor.length - token.length,
+  };
+}
+
+/** All `@plan:<slug>` tokens in a message, in order, de-duplicated by slug. */
+export function extractPlanReferences(text: string): string[] {
+  const tokens: string[] = [];
+  const seen = new Set<string>();
+  for (const match of text.matchAll(GLOBAL_RE)) {
+    const token = match[1];
+    const slug = token ? parsePlanSlug(token) : undefined;
+    if (token && slug && !seen.has(slug)) {
+      seen.add(slug);
+      tokens.push(token);
+    }
+  }
+  return tokens;
+}
+
+/** First referenced slug in a message (first-wins), or undefined. */
+export function firstPlanReference(text: string): string | undefined {
+  const [first] = extractPlanReferences(text);
+  return first ? parsePlanSlug(first) : undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.24.1",
+  "version": "0.25.0",
   "description": "Two-phase planning workflow for pi — plan with claude-opus-4-6:medium, execute with gpt-5.5:low, with .plans/ file-based handoff",
   "keywords": [
     "pi-package"