@dreki-gg/pi-plan-mode 0.15.1 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.17.0
+
+### Minor Changes
+
+- Refactor storage/domain layer to Effect (tagged errors, Schema-based JSONL validation, a FileSystem service + runtime layer) and add beads-style discovered follow-up tasks.
+
+  During execution the agent can now call `add_task` to capture worthwhile out-of-plan work as a `deferred` follow-up (with a reason), without implementing it. Discovered follow-ups are surfaced at checkpoints (blocked pause and when planned work finishes), keep the plan in-progress, and are picked up when you choose "Continue execution" via `/plan resume`.
+
+## 0.16.0
+
+### Minor Changes
+
+- 5c70b28: Reframe plan-mode HTML as a planning-phase visual aid instead of a finalization receipt.
+
+  - `submit_plan` no longer generates `plan.html`. It writes only `tasks.jsonl`, `HANDOFF.md`, and the manifest entry. The previous HTML duplicated the handoff and task list (already tracked elsewhere) and was never opened.
+  - Added a `preview_prototype` tool, available during planning. It renders self-contained Pug to a standalone HTML visual aid under `.plans/_prototypes/`, opens it, and notifies the path — so the user can react to a UI/component/style design _before_ the plan hardens.
+  - Added a bundled `visual-prototype` skill that routes UI/component/layout/style planning work to `preview_prototype` before `submit_plan`.
+  - Added a bundled `planning-context` skill that drives the living `context.md` deliberation discipline (intent, decisions, constraints, open questions, discarded options).
+
 ## 0.15.1
 
 ### Patch Changes

package/extensions/plan-mode/__tests__/add-task.test.ts

@@ -0,0 +1,75 @@
+import { describe, expect, test } from 'bun:test';
+import { registerAddTaskTool } from '../tools/add-task.js';
+import type { PlanData, TaskRecord } from '../types.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+interface CapturedTool {
+  execute: (
+    id: string,
+    params: { description: string; reason: string; details?: string; depends_on?: string[] },
+  ) => Promise<{ details?: unknown }>;
+}
+
+function setup(plan: PlanData | undefined) {
+  let tool: CapturedTool | undefined;
+  const added: TaskRecord[] = [];
+  const pi = {
+    registerTool: (config: CapturedTool) => {
+      tool = config;
+    },
+  } as unknown as Parameters<typeof registerAddTaskTool>[0];
+
+  registerAddTaskTool(pi, {
+    getPlan: () => plan,
+    onTaskAdded: (task) => {
+      added.push(task);
+    },
+  });
+
+  return { tool: tool!, added };
+}
+
+const basePlan = (tasks: TaskRecord[]): PlanData => ({
+  title: 'Plan',
+  planName: 'plan',
+  handoff: '',
+  tasks,
+});
+
+const planTask = (id: string): TaskRecord => ({
+  _type: 'task',
+  id,
+  description: 'planned',
+  status: 'done',
+  origin: 'plan',
+  created_at: now,
+  updated_at: now,
+});
+
+describe('add_task tool', () => {
+  test('captures a deferred discovered task with a generated id and reason as notes', async () => {
+    const plan = basePlan([planTask('t-001'), planTask('t-002')]);
+    const { tool, added } = setup(plan);
+
+    await tool.execute('call-1', {
+      description: 'Extract shared helper',
+      reason: 'noticed duplication while editing',
+    });
+
+    expect(added).toHaveLength(1);
+    const task = added[0];
+    expect(task.id).toBe('t-003');
+    expect(task.status).toBe('deferred');
+    expect(task.origin).toBe('discovered');
+    expect(task.notes).toBe('noticed duplication while editing');
+    expect(task.description).toBe('Extract shared helper');
+  });
+
+  test('throws when there is no active plan', async () => {
+    const { tool } = setup(undefined);
+    await expect(tool.execute('call-1', { description: 'x', reason: 'y' })).rejects.toThrow(
+      /No active plan/,
+    );
+  });
+});

package/extensions/plan-mode/__tests__/atomic-write.test.ts

@@ -1,4 +1,5 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Effect, Exit } from 'effect';
 import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
@@ -18,7 +19,7 @@ describe('writeFileAtomic', () => {
   test('writes complete content to the target path', async () => {
     const target = join(dir, 'data.txt');
 
-    await writeFileAtomic(target, 'hello world');
+    await Effect.runPromise(writeFileAtomic(target, 'hello world'));
 
     expect(await readFile(target, 'utf8')).toBe('hello world');
   });
@@ -27,17 +28,18 @@ describe('writeFileAtomic', () => {
     const target = join(dir, 'data.txt');
     await writeFile(target, 'old');
 
-    await writeFileAtomic(target, 'new');
+    await Effect.runPromise(writeFileAtomic(target, 'new'));
 
     expect(await readFile(target, 'utf8')).toBe('new');
   });
 
-  test('leaves target untouched when writing fails before rename', async () => {
+  test('fails with PlanWriteError and leaves target untouched when the write fails', async () => {
     const target = join(dir, 'data.txt');
     await writeFile(target, 'original');
 
-    await expect(writeFileAtomic(target, 'next', { mode: 0o400 })).rejects.toThrow();
+    const exit = await Effect.runPromiseExit(writeFileAtomic(target, 'next', { mode: 0o400 }));
 
+    expect(Exit.isFailure(exit)).toBe(true);
     expect(await readFile(target, 'utf8')).toBe('original');
   });
 });

package/extensions/plan-mode/__tests__/html-render.test.ts

@@ -1,43 +1,34 @@
 import { describe, expect, test } from 'bun:test';
-import { renderPlanHtml } from '../html/render.js';
-import type { PlanData } from '../types.js';
-
-const plan: PlanData = {
-  title: 'Refactor Auth',
-  planName: 'refactor-auth',
-  handoff: '# Handoff\nShip carefully.',
-  tasks: [
-    {
-      _type: 'task',
-      id: 't-001',
-      description: 'Add auth middleware',
-      details: 'Implement the middleware.',
-      status: 'pending',
-      created_at: '2026-05-27T12:00:00.000Z',
-      updated_at: '2026-05-27T12:00:00.000Z',
-    },
-  ],
-};
-
-describe('renderPlanHtml', () => {
-  test('renders title, task count, handoff, and tasks', () => {
-    const html = renderPlanHtml(plan);
-
-    expect(html).toContain('Refactor Auth');
-    expect(html).toContain('1 task');
-    expect(html).toContain('Ship carefully.');
-    expect(html).toContain('t-001');
-    expect(html).toContain('Add auth middleware');
+import { renderPrototypeHtml } from '../html/render.js';
+
+describe('renderPrototypeHtml', () => {
+  test('renders title and intent in a minimal header', () => {
+    const html = renderPrototypeHtml('Sidebar redesign', 'Left-aligned nav with icons', '.nav Nav');
+
+    expect(html).toContain('Sidebar redesign');
+    expect(html).toContain('Left-aligned nav with icons');
+    expect(html).toContain('Prototype');
+  });
+
+  test('renders the Pug body markup', () => {
+    const html = renderPrototypeHtml('Card', 'A product card', '.card Product card');
+
+    expect(html).toContain('class="card"');
+    expect(html).toContain('Product card');
   });
 
-  test('omits prototypes section when no prototype is provided', () => {
-    expect(renderPlanHtml(plan)).not.toContain('Prototype');
+  test('does not render tasks or handoff sections', () => {
+    const html = renderPrototypeHtml('Card', 'A product card', '.card Hello');
+
+    expect(html).not.toContain('Handoff');
+    expect(html).not.toContain('Tasks');
+    expect(html).not.toContain('Depends on');
   });
 
-  test('renders optional prototype pug markup', () => {
-    const html = renderPlanHtml(plan, '.mockup Prototype card');
+  test('handles an empty prototype body without throwing', () => {
+    const html = renderPrototypeHtml('Empty', 'Nothing yet', '');
 
-    expect(html).toContain('Prototype');
-    expect(html).toContain('Prototype card');
+    expect(html).toContain('Empty');
+    expect(html).toContain('Nothing yet');
   });
 });

package/extensions/plan-mode/__tests__/package-skills.test.ts

@@ -45,3 +45,54 @@ describe('bundled technical-options skill', () => {
     expect(content).toMatch(/challenge.*framing|framing.*challenge/i);
   });
 });
+
+describe('bundled visual-prototype skill', () => {
+  const skillDir = join(PKG_ROOT, 'skills', 'visual-prototype');
+  const skillFile = join(skillDir, 'SKILL.md');
+
+  test('SKILL.md exists', () => {
+    expect(existsSync(skillFile)).toBe(true);
+  });
+
+  test('has valid frontmatter with name and description', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toMatch(/^---\n/);
+    expect(content).toMatch(/name:\s*visual-prototype/);
+    expect(content).toMatch(/description:/);
+  });
+
+  test('routes on visual work, not backend-only', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toMatch(/description:.*\b(UI|component|layout|style)\b/i);
+    expect(content).toMatch(/not for.*backend|backend-only/i);
+  });
+
+  test('directs use of preview_prototype before submit_plan', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toContain('preview_prototype');
+    expect(content).toContain('submit_plan');
+  });
+});
+
+describe('bundled planning-context skill', () => {
+  const skillDir = join(PKG_ROOT, 'skills', 'planning-context');
+  const skillFile = join(skillDir, 'SKILL.md');
+
+  test('SKILL.md exists', () => {
+    expect(existsSync(skillFile)).toBe(true);
+  });
+
+  test('has valid frontmatter with name and description', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toMatch(/^---\n/);
+    expect(content).toMatch(/name:\s*planning-context/);
+    expect(content).toMatch(/description:/);
+  });
+
+  test('covers context.md deliberation sections', () => {
+    const content = readFileSync(skillFile, 'utf-8');
+    expect(content).toContain('context.md');
+    expect(content).toMatch(/discarded options/i);
+    expect(content).toMatch(/open questions/i);
+  });
+});

package/extensions/plan-mode/__tests__/plan-storage.test.ts

@@ -0,0 +1,57 @@
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Effect } from 'effect';
+import { chdir } from 'node:process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+import { FileSystem, nodeFileSystemService } from '../effects/filesystem.js';
+import {
+  loadHandoff,
+  readAndClearExecPending,
+  saveHandoff,
+  writeExecPending,
+} from '../storage/plan-storage.js';
+import type { ExecPendingConfig } from '../types.js';
+
+const run = <A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> =>
+  Effect.runPromise(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
+const originalCwd = process.cwd();
+let dir: string;
+const config: ExecPendingConfig = { model: { provider: 'anthropic', id: 'opus' }, thinking: 'low' };
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'plan-mode-plan-'));
+  chdir(dir);
+});
+afterEach(async () => {
+  chdir(originalCwd);
+  await rm(dir, { recursive: true, force: true });
+});
+
+describe('handoff documents', () => {
+  test('round trips handoff content', async () => {
+    await run(saveHandoff('.plans/p', '# Handoff'));
+    await expect(run(loadHandoff('.plans/p'))).resolves.toBe('# Handoff');
+  });
+
+  test('missing handoff returns undefined', async () => {
+    await expect(run(loadHandoff('.plans/missing'))).resolves.toBeUndefined();
+  });
+});
+
+describe('exec-pending markers', () => {
+  test('writes, reads, and clears a marker', async () => {
+    await run(writeExecPending('.plans/p', config));
+    const first = await run(readAndClearExecPending());
+    expect(first?.planDir).toBe('.plans/p');
+    expect(first?.config).toEqual(config);
+
+    // Marker is cleared after reading.
+    await expect(run(readAndClearExecPending())).resolves.toBeUndefined();
+  });
+
+  test('returns undefined when .plans does not exist', async () => {
+    await expect(run(readAndClearExecPending())).resolves.toBeUndefined();
+  });
+});

package/extensions/plan-mode/__tests__/plans-manifest.test.ts

@@ -1,14 +1,19 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Effect } from 'effect';
 import { chdir } from 'node:process';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
+import { FileSystem, nodeFileSystemService } from '../effects/filesystem.js';
 import {
   readPlansManifest,
   upsertPlanEntry,
   writePlansManifest,
 } from '../storage/plans-manifest.js';
 
+const run = <A, E>(program: Effect.Effect<A, E, FileSystem>): Promise<A> =>
+  Effect.runPromise(program.pipe(Effect.provideService(FileSystem, nodeFileSystemService)));
+
 const originalCwd = process.cwd();
 let dir: string;
 
@@ -31,31 +36,37 @@ describe('plans.jsonl manifest', () => {
       created_at: 'now',
       completed_at: null,
     };
-    await writePlansManifest([entry]);
-    await expect(readPlansManifest()).resolves.toEqual([entry]);
+    await run(writePlansManifest([entry]));
+    await expect(run(readPlansManifest())).resolves.toEqual([entry]);
+  });
+
+  test('missing manifest returns an empty list', async () => {
+    await expect(run(readPlansManifest())).resolves.toEqual([]);
   });
 
   test('upserts new entries', async () => {
-    await upsertPlanEntry('new-plan', { status: 'in-progress', title: 'New Plan' });
-    const entries = await readPlansManifest();
+    await run(upsertPlanEntry('new-plan', { status: 'in-progress', title: 'New Plan' }));
+    const entries = await run(readPlansManifest());
     expect(entries).toHaveLength(1);
     expect(entries[0]?.name).toBe('new-plan');
     expect(entries[0]?.title).toBe('New Plan');
   });
 
   test('upserts existing entries without changing created_at', async () => {
-    await writePlansManifest([
-      {
-        _type: 'plan',
-        name: 'p',
-        status: 'in-progress',
-        title: 'Old',
-        created_at: 'created',
-        completed_at: null,
-      },
-    ]);
-    await upsertPlanEntry('p', { status: 'done', title: 'New' });
-    const [entry] = await readPlansManifest();
+    await run(
+      writePlansManifest([
+        {
+          _type: 'plan',
+          name: 'p',
+          status: 'in-progress',
+          title: 'Old',
+          created_at: 'created',
+          completed_at: null,
+        },
+      ]),
+    );
+    await run(upsertPlanEntry('p', { status: 'done', title: 'New' }));
+    const [entry] = await run(readPlansManifest());
     expect(entry.created_at).toBe('created');
     expect(entry.status).toBe('done');
     expect(entry.completed_at).toBeString();

package/extensions/plan-mode/__tests__/schema.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, test } from 'bun:test';
+import { Either } from 'effect';
+import {
+  decodeExecPendingConfig,
+  decodePlanManifestEntry,
+  decodeTaskMeta,
+  decodeTaskRecord,
+  decodeTasksLine,
+} from '../schema.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+
+const isOk = (value: unknown, decode: (v: unknown) => Either.Either<unknown, unknown>): boolean =>
+  Either.isRight(decode(value));
+
+describe('task record schema', () => {
+  test('accepts a full task record', () => {
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-001',
+          description: 'Do work',
+          details: 'Full instructions',
+          status: 'pending',
+          depends_on: ['t-000'],
+          notes: 'note',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(true);
+  });
+
+  test('accepts a lightweight task record without details', () => {
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-001',
+          description: 'Do work',
+          status: 'pending',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(true);
+  });
+
+  test('accepts a deferred discovered task', () => {
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-011',
+          description: 'Follow-up discovered mid-run',
+          status: 'deferred',
+          origin: 'discovered',
+          notes: 'noticed while implementing',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(true);
+  });
+
+  test('rejects an unknown origin', () => {
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-001',
+          description: 'Do work',
+          status: 'pending',
+          origin: 'bogus',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(false);
+  });
+
+  test('rejects missing fields and unknown status', () => {
+    expect(isOk({ _type: 'task', id: 't-001', status: 'pending' }, decodeTaskRecord)).toBe(false);
+    expect(
+      isOk(
+        {
+          _type: 'task',
+          id: 't-001',
+          description: 'Do work',
+          status: 'unknown',
+          created_at: now,
+          updated_at: now,
+        },
+        decodeTaskRecord,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe('task meta schema', () => {
+  test('accepts a valid meta record', () => {
+    expect(
+      isOk(
+        { _type: 'meta', title: 'Refactor', plan_name: 'refactor', created_at: now },
+        decodeTaskMeta,
+      ),
+    ).toBe(true);
+  });
+
+  test('rejects malformed meta records', () => {
+    expect(isOk({ _type: 'meta', title: 'Refactor' }, decodeTaskMeta)).toBe(false);
+    expect(
+      isOk(
+        { _type: 'task', title: 'Refactor', plan_name: 'refactor', created_at: now },
+        decodeTaskMeta,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe('tasks.jsonl line schema (meta | task union)', () => {
+  test('discriminates meta from task', () => {
+    const meta = decodeTasksLine({ _type: 'meta', title: 'T', plan_name: 'p', created_at: now });
+    const task = decodeTasksLine({
+      _type: 'task',
+      id: 't-001',
+      description: 'Do work',
+      status: 'pending',
+      created_at: now,
+      updated_at: now,
+    });
+    expect(Either.isRight(meta) && Either.getOrThrow(meta)._type).toBe('meta');
+    expect(Either.isRight(task) && Either.getOrThrow(task)._type).toBe('task');
+  });
+
+  test('round-trips a deferred discovered task', () => {
+    const decoded = decodeTasksLine({
+      _type: 'task',
+      id: 't-011',
+      description: 'Follow-up',
+      status: 'deferred',
+      origin: 'discovered',
+      created_at: now,
+      updated_at: now,
+    });
+    expect(Either.isRight(decoded)).toBe(true);
+    if (Either.isRight(decoded) && decoded.right._type === 'task') {
+      expect(decoded.right.status).toBe('deferred');
+      expect(decoded.right.origin).toBe('discovered');
+    }
+  });
+
+  test('rejects records with an unknown _type', () => {
+    expect(isOk({ _type: 'bogus' }, decodeTasksLine)).toBe(false);
+  });
+});
+
+describe('plan manifest entry schema', () => {
+  test('accepts a valid entry with null completed_at', () => {
+    expect(
+      isOk(
+        {
+          _type: 'plan',
+          name: 'plan',
+          status: 'in-progress',
+          title: 'Plan',
+          created_at: now,
+          completed_at: null,
+        },
+        decodePlanManifestEntry,
+      ),
+    ).toBe(true);
+  });
+
+  test('rejects an invalid status', () => {
+    expect(
+      isOk(
+        {
+          _type: 'plan',
+          name: 'plan',
+          status: 'paused',
+          title: 'Plan',
+          created_at: now,
+          completed_at: null,
+        },
+        decodePlanManifestEntry,
+      ),
+    ).toBe(false);
+  });
+});
+
+describe('exec pending config schema', () => {
+  test('accepts a valid config', () => {
+    expect(
+      isOk(
+        { model: { provider: 'anthropic', id: 'opus' }, thinking: 'low' },
+        decodeExecPendingConfig,
+      ),
+    ).toBe(true);
+  });
+
+  test('rejects a config missing the model id', () => {
+    expect(
+      isOk({ model: { provider: 'anthropic' }, thinking: 'low' }, decodeExecPendingConfig),
+    ).toBe(false);
+  });
+});

package/extensions/plan-mode/__tests__/task-status.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  activeTasksResolved,
+  deferredTasks,
+  isPlanFinalizable,
+  reactivateForExecution,
+} from '../task-status.js';
+import type { TaskRecord, TaskStatus } from '../types.js';
+
+const now = '2026-05-27T12:00:00.000Z';
+let counter = 0;
+const make = (status: TaskStatus, origin?: 'plan' | 'discovered'): TaskRecord => ({
+  _type: 'task',
+  id: `t-${String(++counter).padStart(3, '0')}`,
+  description: 'task',
+  status,
+  origin,
+  created_at: now,
+  updated_at: now,
+});
+
+describe('deferredTasks', () => {
+  test('returns only deferred tasks', () => {
+    const tasks = [make('done'), make('deferred', 'discovered'), make('pending')];
+    expect(deferredTasks(tasks).map((t) => t.status)).toEqual(['deferred']);
+  });
+});
+
+describe('activeTasksResolved', () => {
+  test('true when only done/skipped/deferred remain', () => {
+    expect(
+      activeTasksResolved([make('done'), make('skipped'), make('deferred', 'discovered')]),
+    ).toBe(true);
+  });
+
+  test('false when a task is still pending', () => {
+    expect(activeTasksResolved([make('done'), make('pending')])).toBe(false);
+  });
+
+  test('false when a task is still blocked', () => {
+    expect(activeTasksResolved([make('done'), make('blocked')])).toBe(false);
+  });
+});
+
+describe('isPlanFinalizable', () => {
+  test('true when all work is done/skipped and nothing is deferred', () => {
+    expect(isPlanFinalizable([make('done'), make('skipped')])).toBe(true);
+  });
+
+  test('false when a deferred follow-up awaits the user', () => {
+    expect(isPlanFinalizable([make('done'), make('deferred', 'discovered')])).toBe(false);
+  });
+
+  test('false when active work remains', () => {
+    expect(isPlanFinalizable([make('pending')])).toBe(false);
+  });
+});
+
+describe('reactivateForExecution', () => {
+  test('flips blocked and deferred tasks to pending and stamps updated_at', () => {
+    const tasks = [make('done'), make('blocked'), make('deferred', 'discovered')];
+    const ts = '2026-06-01T00:00:00.000Z';
+    const changed = reactivateForExecution(tasks, ts);
+    expect(changed).toBe(true);
+    expect(tasks.map((t) => t.status)).toEqual(['done', 'pending', 'pending']);
+    expect(tasks[1].updated_at).toBe(ts);
+    expect(tasks[2].updated_at).toBe(ts);
+  });
+
+  test('returns false and leaves tasks untouched when nothing to reactivate', () => {
+    const tasks = [make('done'), make('pending')];
+    expect(reactivateForExecution(tasks, '2026-06-01T00:00:00.000Z')).toBe(false);
+  });
+});