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

package/extensions/plan-mode/types.ts

@@ -2,7 +2,10 @@
  * Shared types for plan mode.
  */
 
-export type TaskStatus = 'pending' | 'done' | 'skipped' | 'blocked';
+export type TaskStatus = 'pending' | 'done' | 'skipped' | 'blocked' | 'deferred';
+
+/** Where a task came from: the original submitted plan, or discovered during execution. */
+export type TaskOrigin = 'plan' | 'discovered';
 
 export interface TaskRecord {
   _type: 'task';
@@ -10,6 +13,8 @@ export interface TaskRecord {
   description: string;
   details?: string;
   status: TaskStatus;
+  /** Defaults to 'plan' when absent (back-compat with older tasks.jsonl files). */
+  origin?: TaskOrigin;
   depends_on?: string[];
   notes?: string;
   created_at: string;
@@ -45,40 +50,5 @@ export interface PersistedState {
   executionStartIdx: number | undefined;
 }
 
-const TASK_STATUSES = new Set<TaskStatus>(['pending', 'done', 'skipped', 'blocked']);
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null;
-}
-
-function isStringArray(value: unknown): value is string[] {
-  return Array.isArray(value) && value.every((item) => typeof item === 'string');
-}
-
-export function isTaskRecord(value: unknown): value is TaskRecord {
-  if (!isRecord(value)) return false;
-
-  return (
-    value._type === 'task' &&
-    typeof value.id === 'string' &&
-    typeof value.description === 'string' &&
-    (value.details === undefined || typeof value.details === 'string') &&
-    typeof value.status === 'string' &&
-    TASK_STATUSES.has(value.status as TaskStatus) &&
-    (value.depends_on === undefined || isStringArray(value.depends_on)) &&
-    (value.notes === undefined || typeof value.notes === 'string') &&
-    typeof value.created_at === 'string' &&
-    typeof value.updated_at === 'string'
-  );
-}
-
-export function isTaskMeta(value: unknown): value is TaskMeta {
-  if (!isRecord(value)) return false;
-
-  return (
-    value._type === 'meta' &&
-    typeof value.title === 'string' &&
-    typeof value.plan_name === 'string' &&
-    typeof value.created_at === 'string'
-  );
-}
+// Record validation lives in `schema.ts` (Effect Schema). The interfaces above
+// remain the mutable shapes used by the imperative orchestration code.

package/extensions/plan-mode/utils.ts

@@ -42,3 +42,23 @@ export function toKebabCase(name: string): string {
     .replace(/^-+|-+$/g, '')
     .slice(0, 60);
 }
+
+/**
+ * Generate the next sequential task id (`t-NNN`) given existing ids.
+ *
+ * Uses the max numeric suffix of `t-<digits>` ids + 1, zero-padded to 3.
+ * Falls back to `t-<count+1>` when no ids match the pattern.
+ */
+export function nextTaskId(existingIds: readonly string[]): string {
+  let max = 0;
+  let matched = false;
+  for (const id of existingIds) {
+    const m = /^t-(\d+)$/.exec(id);
+    if (!m) continue;
+    matched = true;
+    const n = Number.parseInt(m[1], 10);
+    if (n > max) max = n;
+  }
+  const next = matched ? max + 1 : existingIds.length + 1;
+  return `t-${String(next).padStart(3, '0')}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.15.1",
+  "version": "0.17.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"
@@ -41,6 +41,7 @@
   },
   "dependencies": {
     "@dreki-gg/pi-command-sandbox": "^0.3.0",
+    "effect": "^3.21.2",
     "pug": "^3.0.3"
   },
   "devDependencies": {

package/skills/planning-context/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: planning-context
+description: Maintain a living context.md during planning to capture intent, decisions, constraints, open questions, and discarded options before finalizing a plan. Use whenever you are in plan mode and converging on an approach, especially before calling submit_plan.
+---
+
+# Planning Context
+
+`context.md` is the living written record of a planning conversation. It exists to slow the jump from "read the codebase" to "submit the plan" — the moment where reasoning usually gets lost. Write it as you think, not as an afterthought.
+
+## When to use
+
+Use this throughout any planning session, from the first real decision onward. If you have read code and formed an opinion but have not written anything down, that is the signal to update `context.md`.
+
+## What it is
+
+`.plans/<plan-name>/context.md` — a deliberation document, not a plan. It captures the *why* and the *roads not taken*, which `HANDOFF.md` and the task list deliberately omit.
+
+## Process
+
+### 1. Create it early
+
+As soon as you understand the intent, write `.plans/<plan-name>/context.md` with the `write` tool. Do not wait until you are ready to submit.
+
+### 2. Keep these sections current
+
+- **Intent** — what the user actually wants, in their terms
+- **Decisions** — choices made and the reasoning behind each
+- **Constraints** — technical, product, or process limits that shape the work
+- **Open questions** — anything unresolved; do not submit a plan with silent unknowns
+- **Discarded options** — approaches considered and rejected, with why. This is the highest-value section and the one most often skipped.
+
+### 3. Style
+
+Caveman-lite: professional, tight, no filler. Bullet points over prose. Update in place as understanding shifts — do not append a changelog.
+
+### 4. Use it before submitting
+
+`context.md` is the input to `submit_plan`, not a duplicate of it. Before finalizing, re-read it: every open question resolved, every decision justified. The handoff is the distilled conclusion; `context.md` is the reasoning that earned it.
+
+## Relationship to prototypes
+
+For visual/UI work, a prototype is the visual sibling of `context.md` — see the `visual-prototype` skill. Both are deliberation artifacts. Written reasoning lives here; visual reasoning lives in the prototype.

package/skills/visual-prototype/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: visual-prototype
+description: Build a visual HTML prototype during planning for UI, component, layout, or style changes, so the user can react to the design before the plan is finalized. Use when a plan touches frontend appearance or interaction. Not for backend-only or non-visual work.
+---
+
+# Visual Prototype
+
+A prototype is a **convergence artifact**, not a deliverable. When a plan changes how something looks or behaves visually, a static markdown plan cannot show the user what they are agreeing to. Build the prototype while the plan is still soft, show it, and let the user redirect you before anything is committed to `submit_plan`.
+
+## When to use
+
+Use this when the plan involves any of:
+
+- New or restyled UI components
+- Layout, spacing, or visual hierarchy changes
+- Color, typography, or theming changes
+- Interaction states (hover, active, empty, loading, error)
+
+Do **not** use it for backend-only, refactor-only, or otherwise non-visual work.
+
+## Process
+
+### 1. Decide there is something to see
+
+If you cannot picture a screen or component changing, skip the prototype. A prototype for invisible work is noise.
+
+### 2. Build it with `preview_prototype`
+
+Call `preview_prototype` with:
+
+- `title` — short name for the prototype
+- `intent` — one line describing what it shows
+- `pug` — self-contained Pug markup for the prototype body. Inline any styles the prototype needs; assume nothing about the host page.
+
+The tool renders the Pug, writes `.plans/_prototypes/<slug>.html`, and opens it for review.
+
+### 3. Get a reaction before submitting
+
+Stop and ask the user what they think. Iterate on the prototype — call `preview_prototype` again with revisions — until the visual direction is agreed. Only then move toward `submit_plan`.
+
+`submit_plan` never generates HTML. The prototype lives entirely in the planning phase; its job is done once the user has reacted.
+
+## Relationship to context.md
+
+The prototype is the visual sibling of `context.md`. Both are deliberation artifacts that exist to slow the jump from "read the codebase" to "submit the plan." Keep `context.md` current as the living written record of intent, decisions, and open questions; use a prototype whenever the decision is visual. Resist the urge to skip straight to `submit_plan` on visual work.

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

@@ -1,70 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { isTaskMeta, isTaskRecord } from '../types.js';
-
-const now = '2026-05-27T12:00:00.000Z';
-
-describe('task record type guards', () => {
-  test('accepts valid task records', () => {
-    expect(
-      isTaskRecord({
-        _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,
-      }),
-    ).toBe(true);
-  });
-
-  test('accepts task records without details (lightweight checklist)', () => {
-    expect(
-      isTaskRecord({
-        _type: 'task',
-        id: 't-001',
-        description: 'Do work',
-        status: 'pending',
-        created_at: now,
-        updated_at: now,
-      }),
-    ).toBe(true);
-  });
-
-  test('rejects malformed task records', () => {
-    expect(isTaskRecord({ _type: 'task', id: 't-001', status: 'pending' })).toBe(false);
-    expect(
-      isTaskRecord({
-        _type: 'task',
-        id: 't-001',
-        description: 'Do work',
-        details: 'Full instructions',
-        status: 'unknown',
-        created_at: now,
-        updated_at: now,
-      }),
-    ).toBe(false);
-  });
-});
-
-describe('task meta type guard', () => {
-  test('accepts valid meta records', () => {
-    expect(
-      isTaskMeta({
-        _type: 'meta',
-        title: 'Refactor',
-        plan_name: 'refactor',
-        created_at: now,
-      }),
-    ).toBe(true);
-  });
-
-  test('rejects malformed meta records', () => {
-    expect(isTaskMeta({ _type: 'meta', title: 'Refactor' })).toBe(false);
-    expect(
-      isTaskMeta({ _type: 'task', title: 'Refactor', plan_name: 'refactor', created_at: now }),
-    ).toBe(false);
-  });
-});

package/extensions/plan-mode/html/templates/plan.pug

@@ -1,69 +0,0 @@
-doctype html
-html(lang="en")
-  head
-    meta(charset="utf-8")
-    meta(name="viewport" content="width=device-width, initial-scale=1")
-    title= plan.title
-    style.
-      :root { color-scheme: dark; --bg:#0b0d12; --panel:#11141b; --muted:#8b93a7; --text:#eef1f7; --line:#242936; --accent:#8b5cf6; --done:#33d69f; --blocked:#ff6b6b; }
-      * { box-sizing: border-box; }
-      body { margin:0; background:radial-gradient(circle at top left,#1c1730,transparent 34rem),var(--bg); color:var(--text); font:14px/1.5 Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; }
-      main { width:min(1040px, calc(100% - 48px)); margin:48px auto; }
-      header { display:flex; justify-content:space-between; gap:24px; align-items:flex-start; margin-bottom:28px; }
-      h1 { font-size:34px; line-height:1.08; margin:0 0 10px; letter-spacing:-0.04em; }
-      h2 { font-size:15px; text-transform:uppercase; color:var(--muted); letter-spacing:0.14em; margin:0 0 14px; }
-      .meta { color:var(--muted); display:flex; gap:12px; flex-wrap:wrap; }
-      .pill { border:1px solid var(--line); border-radius:999px; padding:6px 10px; background:rgba(255,255,255,0.03); }
-      section { background:rgba(17,20,27,0.82); border:1px solid var(--line); border-radius:18px; padding:22px; margin:18px 0; box-shadow:0 24px 80px rgba(0,0,0,0.24); }
-      .handoff :first-child { margin-top:0; }
-      .handoff :last-child { margin-bottom:0; }
-      .handoff pre { background:#161922; border:1px solid var(--line); border-radius:10px; padding:14px 16px; overflow-x:auto; margin:12px 0; }
-      .handoff pre code { font-family:ui-monospace, SFMono-Regular, Menlo, monospace; font-size:13px; color:#c7ccda; background:none; padding:0; border:none; border-radius:0; }
-      .handoff code { font-family:ui-monospace, SFMono-Regular, Menlo, monospace; font-size:13px; background:rgba(139,92,246,0.12); color:var(--accent); padding:2px 6px; border-radius:5px; }
-      .handoff strong { font-weight:650; }
-      .handoff a { color:var(--accent); text-decoration:none; }
-      .handoff a:hover { text-decoration:underline; }
-      .handoff h1, .handoff h3, .handoff h4 { font-size:15px; text-transform:uppercase; color:var(--muted); letter-spacing:0.14em; margin:20px 0 10px; }
-      .handoff p { margin:8px 0; }
-      .handoff ul { margin:8px 0; padding-left:20px; }
-      .handoff li { margin:4px 0; }
-      .tasks { display:grid; gap:12px; }
-      .task { border:1px solid var(--line); border-radius:14px; padding:16px; background:#0f1218; }
-      .task-top { display:flex; gap:10px; align-items:center; margin-bottom:8px; }
-      .id { color:var(--accent); font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
-      .status { margin-left:auto; color:var(--muted); }
-      .task.done .status { color:var(--done); }
-      .task.blocked .status { color:var(--blocked); }
-      .description { font-weight:650; }
-      .details { color:#c7ccda; margin:0; white-space:pre-wrap; }
-      .deps { color:var(--muted); margin-top:10px; font-size:12px; }
-  body
-    main
-      header
-        div
-          h1= plan.title
-          .meta
-            span.pill= plan.planName
-            span.pill= taskCountLabel
-        .meta
-          span.pill Generated #{generatedAt}
-      section.handoff
-        h2 Handoff
-        != handoffHtml
-      section
-        h2 Tasks
-        .tasks
-          each task in plan.tasks
-            article.task(class=task.status)
-              .task-top
-                span.id= task.id
-                span.description= task.description
-                span.status= task.status
-              if task.details
-                p.details= task.details
-              if task.depends_on && task.depends_on.length
-                .deps Depends on #{task.depends_on.join(', ')}
-      if prototypeHtml
-        section.prototype
-          h2 Prototype
-          != prototypeHtml