@dreki-gg/pi-plan-mode 0.23.0 → 0.24.0

package/extensions/plan-mode/index.ts

@@ -39,8 +39,10 @@ import { activeTasksResolved, deferredTasks, isPlanFinalizable } from './task-st
 import { enterPlanMode, exitPlanMode, switchModel } from './phase-transitions.js';
 import { resumePlan, executeInNewSession } from './resume.js';
 import { resolveActivePlan, focusActivePlan } from './resolve-plan.js';
+import { reconcileInitiativeForPlan } from './initiative.js';
 import { collectPlanDrift } from './reconcile.js';
 import { registerSubmitPlanTool } from './tools/submit-plan.js';
+import { registerSubmitInitiativeTool } from './tools/submit-initiative.js';
 import { registerRevisePlanTool } from './tools/revise-plan.js';
 import { registerPreviewPrototypeTool } from './tools/preview-prototype.js';
 import { registerUpdateTaskTool } from './tools/update-task.js';
@@ -49,9 +51,12 @@ import { registerAddTaskTool } from './tools/add-task.js';
 import { registerPlanStatusTool } from './tools/plan-status.js';
 import { registerSetActivePlanTool } from './tools/set-active-plan.js';
 import { registerUpdatePlanTool } from './tools/update-plan.js';
+import { registerUpdateInitiativeTool } from './tools/update-initiative.js';
+import { registerInitiativeStatusTool } from './tools/initiative-status.js';
 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';
 
 export default function planMode(pi: ExtensionAPI): void {
   const state = new PlanModeState();
@@ -83,6 +88,8 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  registerSubmitInitiativeTool(pi, runPlanIO);
+
   registerPreviewPrototypeTool(pi, runPlanIO);
 
   // Shared task-write closure: mutate the in-memory task, persist tasks.jsonl,
@@ -120,6 +127,8 @@ export default function planMode(pi: ExtensionAPI): void {
         state.plan.title,
       ),
     );
+    // Project plan status up to its parent initiative (no-op when standalone).
+    await runPlanIO(reconcileInitiativeForPlan(state.plan.planName));
     state.persist(pi);
   };
 
@@ -162,6 +171,7 @@ export default function planMode(pi: ExtensionAPI): void {
           state.plan.title,
         ),
       );
+      await runPlanIO(reconcileInitiativeForPlan(state.plan.planName));
       state.persist(pi);
     },
   });
@@ -186,6 +196,8 @@ export default function planMode(pi: ExtensionAPI): void {
   });
 
   registerUpdatePlanTool(pi, runPlanIO);
+  registerUpdateInitiativeTool(pi, runPlanIO);
+  registerInitiativeStatusTool(pi, runPlanIO);
   registerReconcilePlansTool(pi, runPlanIO);
 
   registerAddTaskTool(pi, {
@@ -214,6 +226,7 @@ export default function planMode(pi: ExtensionAPI): void {
           state.plan.title,
         ),
       );
+      await runPlanIO(reconcileInitiativeForPlan(state.plan.planName));
       state.persist(pi);
     },
   });
@@ -277,6 +290,14 @@ export default function planMode(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerCommand('initiatives', {
+    description:
+      'List all initiatives with member-plan rollup. Usage: /initiatives [filter]. Filters: all, in-progress, done, superseded, abandoned.',
+    handler: async (args, ctx) => {
+      await handleListInitiatives(ctx, runPlanIO, args);
+    },
+  });
+
   pi.registerCommand('todos', {
     description: 'Show current plan progress',
     handler: async (_args, ctx) => {
@@ -513,6 +534,7 @@ export default function planMode(pi: ExtensionAPI): void {
           await runPlanIO(
             upsertPlanEntry(state.plan.planName, { status: 'done', title: state.plan.title }),
           );
+          await runPlanIO(reconcileInitiativeForPlan(state.plan.planName));
           await runPlanIO(
             writeTasksJsonl(
               state.planDir,

package/extensions/plan-mode/initiative.ts

@@ -0,0 +1,168 @@
+/**
+ * Initiative logic — ready-work computation and the initiative→plan projection.
+ *
+ * Two layers live here:
+ *   - PURE: `computePlanReadiness`, `isInitiativeFinalizable`, `initiativeRollup`
+ *     reason over a plans-manifest snapshot with no IO. They are the basis for
+ *     "what work is unblocked right now" — the foundation for phase-2 subagent
+ *     fan-out.
+ *   - IO: `reconcileInitiativeStatus` / `reconcileInitiativeForPlan` keep an
+ *     initiative's registry status a PROJECTION of its member plans, mirroring
+ *     `reconcilePlanStatus` one level up. They read the PLANS manifest, so they
+ *     live here (not in `initiatives-manifest.ts`) to keep the dependency
+ *     direction one-way: initiative.ts → {plans-manifest, initiatives-manifest}.
+ */
+
+import { Effect } from 'effect';
+import { FileSystem } from './effects/filesystem.js';
+import type { JsonlParseError, JsonlValidationError, PlanWriteError } from './errors.js';
+import { readPlansManifest, type PlanManifestEntry } from './storage/plans-manifest.js';
+import {
+  readInitiativesManifest,
+  upsertInitiativeEntry,
+} from './storage/initiatives-manifest.js';
+import type { PlanStatus } from './types.js';
+
+// ── Pure: readiness + projection rules ───────────────────────────────────────
+
+export interface PlanReadiness {
+  name: string;
+  /** True when every plan in `depends_on` is `done`. */
+  ready: boolean;
+  /** Dependency plan names that are not yet `done` (unknown deps count too). */
+  blockedBy: string[];
+}
+
+/**
+ * For each `in-progress` plan, whether all of its plan-level dependencies are
+ * `done`. Only a `done` dependency unblocks — a missing, in-progress, or
+ * terminally-closed (superseded/abandoned) dependency keeps a plan blocked.
+ */
+export function computePlanReadiness(plans: readonly PlanManifestEntry[]): PlanReadiness[] {
+  const statusByName = new Map(plans.map((plan) => [plan.name, plan.status]));
+  return plans
+    .filter((plan) => plan.status === 'in-progress')
+    .map((plan) => {
+      const deps = plan.depends_on ?? [];
+      const blockedBy = deps.filter((dep) => statusByName.get(dep) !== 'done');
+      return { name: plan.name, ready: blockedBy.length === 0, blockedBy };
+    });
+}
+
+/** Member plans of an initiative (linked by name in the plans manifest). */
+export function membersOf(
+  initiative: string,
+  plans: readonly PlanManifestEntry[],
+): PlanManifestEntry[] {
+  return plans.filter((plan) => plan.initiative === initiative);
+}
+
+/**
+ * An initiative is finalizable (`done`) when it has ≥1 member plan AND every
+ * member is terminal (no member is `in-progress`). Mirrors the plan-level rule
+ * one level up.
+ */
+export function isInitiativeFinalizable(
+  initiative: string,
+  plans: readonly PlanManifestEntry[],
+): boolean {
+  const members = membersOf(initiative, plans);
+  if (members.length === 0) return false;
+  return members.every((plan) => plan.status !== 'in-progress');
+}
+
+export interface InitiativeMemberRow {
+  name: string;
+  title: string;
+  status: PlanStatus;
+  /** Present for in-progress members. */
+  ready?: boolean;
+  blockedBy?: string[];
+}
+
+export interface InitiativeRollup {
+  name: string;
+  total: number;
+  done: number;
+  /** Terminal but not done (superseded / abandoned). */
+  closed: number;
+  inProgress: number;
+  ready: number;
+  blocked: number;
+  members: InitiativeMemberRow[];
+}
+
+/** Aggregate an initiative's member plans into counts + per-member readiness. */
+export function initiativeRollup(
+  initiative: string,
+  plans: readonly PlanManifestEntry[],
+): InitiativeRollup {
+  const members = membersOf(initiative, plans);
+  const readiness = new Map(computePlanReadiness(plans).map((row) => [row.name, row]));
+
+  let done = 0;
+  let closed = 0;
+  let inProgress = 0;
+  let ready = 0;
+  let blocked = 0;
+
+  const rows: InitiativeMemberRow[] = members.map((plan) => {
+    if (plan.status === 'done') done += 1;
+    else if (plan.status === 'in-progress') inProgress += 1;
+    else closed += 1; // superseded / abandoned
+
+    const row: InitiativeMemberRow = { name: plan.name, title: plan.title, status: plan.status };
+    if (plan.status === 'in-progress') {
+      const r = readiness.get(plan.name);
+      row.ready = r?.ready ?? true;
+      row.blockedBy = r?.blockedBy ?? [];
+      if (row.ready) ready += 1;
+      else blocked += 1;
+    }
+    return row;
+  });
+
+  return { name: initiative, total: members.length, done, closed, inProgress, ready, blocked, members: rows };
+}
+
+// ── IO: keep initiative registry status a projection of member plans ─────────
+
+type ReconcileError = JsonlParseError | JsonlValidationError | PlanWriteError;
+
+/**
+ * Re-derive an initiative's registry status from its member plans.
+ *
+ * Like `reconcilePlanStatus`: only reflects state for a KNOWN initiative (never
+ * conjures an entry), and never clobbers a manually-set terminal status
+ * (`superseded` / `abandoned`). Only `in-progress` ⇄ `done` is derived.
+ */
+export function reconcileInitiativeStatus(
+  name: string,
+): Effect.Effect<void, ReconcileError, FileSystem> {
+  return Effect.gen(function* () {
+    const initiatives = yield* readInitiativesManifest();
+    const existing = initiatives.find((entry) => entry.name === name);
+    if (!existing) return;
+    if (existing.status === 'superseded' || existing.status === 'abandoned') return;
+    const plans = yield* readPlansManifest();
+    const status: PlanStatus = isInitiativeFinalizable(name, plans) ? 'done' : 'in-progress';
+    if (existing.status === status) return;
+    yield* upsertInitiativeEntry(name, { status, title: existing.title });
+  });
+}
+
+/**
+ * Reconcile the initiative that a given plan belongs to (no-op when the plan is
+ * standalone). Call this after any plan-status write so the initiative level
+ * stays in sync without callers needing to know the parent name.
+ */
+export function reconcileInitiativeForPlan(
+  planName: string,
+): Effect.Effect<void, ReconcileError, FileSystem> {
+  return Effect.gen(function* () {
+    const plans = yield* readPlansManifest();
+    const plan = plans.find((entry) => entry.name === planName);
+    if (!plan?.initiative) return;
+    yield* reconcileInitiativeStatus(plan.initiative);
+  });
+}

package/extensions/plan-mode/prompts.ts

@@ -33,6 +33,10 @@ Plan weight:
 
 submit_plan is finalization, not the starting point. It records tasks and the handoff — it does not generate HTML.
 
+Sizing the work — flat plan vs initiative:
+- For a bounded change that fits one coherent execution session, submit a single flat plan.
+- For LARGE work that does not fit one session, or spans multiple subsystems with dependencies between chunks, create an **initiative** first with submit_initiative, then submit each executable chunk as its own plan with \`initiative\` set and \`depends_on_plans\` capturing ordering. An initiative's status is a projection of its member plans; \`initiative_status\` shows which member plans are READY (all dependencies done) so the work can be split across sessions or subagents. Use \`/initiatives\` and \`update_initiative\` to track and close initiatives.
+
 If a plan with the same name already exists and the user asks for follow-up changes (e.g. you submitted prematurely), call revise_plan instead of submit_plan. It rewrites the existing plan in place — pass only the fields that change (title, handoff, and/or tasks); status and notes are preserved for tasks whose id is unchanged.
 
 For visual/UI/layout/style work, build a prototype with preview_prototype DURING planning, before submit_plan, so the user can react to the visual before the plan hardens. You author the HTML freely — no template engine, no imposed theme — and can delegate the markup to the ux-designer subagent for real design taste. The visual-prototype skill covers when and how.

package/extensions/plan-mode/reconcile.ts

@@ -22,6 +22,13 @@ import type {
   PlanWriteError,
 } from './errors.js';
 import { readPlansManifest, reconcilePlanStatus } from './storage/plans-manifest.js';
+import { readInitiativesManifest } from './storage/initiatives-manifest.js';
+import {
+  isInitiativeFinalizable,
+  membersOf,
+  reconcileInitiativeForPlan,
+  reconcileInitiativeStatus,
+} from './initiative.js';
 import { readTasksJsonl } from './storage/task-storage.js';
 import { isPlanFinalizable } from './task-status.js';
 import type { PlanStatus } from './types.js';
@@ -121,6 +128,62 @@ export function collectPlanDrift(): Effect.Effect<PlanDriftRow[], CollectError,
   });
 }
 
+// ── Initiative-level drift ───────────────────────────────────────────────────
+
+export interface InitiativeDriftRow {
+  name: string;
+  registryStatus: PlanStatus;
+  title: string;
+  /** Projected from member plans: `done` when finalizable, else `in-progress`. */
+  derivedStatus: 'in-progress' | 'done';
+  members: number;
+  /** 'status' when the registry status disagrees with the projection. */
+  drift?: 'status';
+}
+
+/** Compare each initiative's registry status against its member-plan projection. */
+export function collectInitiativeDrift(): Effect.Effect<
+  InitiativeDriftRow[],
+  CollectError,
+  FileSystem
+> {
+  return Effect.gen(function* () {
+    const initiatives = yield* readInitiativesManifest();
+    const plans = yield* readPlansManifest();
+    return initiatives.map((entry) => {
+      const derivedStatus: 'in-progress' | 'done' = isInitiativeFinalizable(entry.name, plans)
+        ? 'done'
+        : 'in-progress';
+      // Terminal statuses (superseded/abandoned) are intentional — never drift.
+      const isTerminalManual = entry.status === 'superseded' || entry.status === 'abandoned';
+      const drift = !isTerminalManual && entry.status !== derivedStatus ? ('status' as const) : undefined;
+      return {
+        name: entry.name,
+        registryStatus: entry.status,
+        title: entry.title,
+        derivedStatus,
+        members: membersOf(entry.name, plans).length,
+        drift,
+      };
+    });
+  });
+}
+
+/** Repair `status`-class initiative drift by re-projecting from member plans. */
+export function applyInitiativeReconcile(
+  rows: InitiativeDriftRow[],
+): Effect.Effect<InitiativeDriftRow[], CollectError | PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const repaired: InitiativeDriftRow[] = [];
+    for (const row of rows) {
+      if (row.drift !== 'status') continue;
+      yield* reconcileInitiativeStatus(row.name);
+      repaired.push(row);
+    }
+    return repaired;
+  });
+}
+
 /**
  * Repair `status`-class drift by projecting derived status into the registry.
  * Orphans and registry-only rows are reported but not auto-fixed (they need a
@@ -134,6 +197,8 @@ export function applyReconcile(
     for (const row of rows) {
       if (row.drift !== 'status' || !row.derivedStatus) continue;
       yield* reconcilePlanStatus(row.name, row.derivedStatus === 'done', row.title);
+      // Repairing a plan's status can flip its parent initiative's projection.
+      yield* reconcileInitiativeForPlan(row.name);
       repaired.push(row);
     }
     return repaired;

package/extensions/plan-mode/schema.ts

@@ -55,6 +55,31 @@ export const PlanManifestEntrySchema = Schema.Struct({
   completed_at: Schema.NullOr(Schema.String),
   /** Optional human-readable reason, used for terminal statuses. */
   reason: Schema.optional(Schema.String),
+  /** Parent initiative name (kebab). Absent = standalone flat plan. */
+  initiative: Schema.optional(Schema.String),
+  /**
+   * Plan-level dependencies: names of plans this plan depends on. Distinct from
+   * the task-level `depends_on` above. Cross-initiative references are allowed.
+   */
+  depends_on: Schema.optional(Schema.mutable(Schema.Array(Schema.String))),
+});
+
+/**
+ * Initiative lifecycle statuses reuse the plan lifecycle literals. An
+ * initiative's status is a projection of its member plans' statuses, with the
+ * same terminal-guard semantics as plans.
+ */
+export const InitiativeStatusSchema = PlanStatusSchema;
+
+export const InitiativeManifestEntrySchema = Schema.Struct({
+  _type: Schema.Literal('initiative'),
+  name: Schema.String,
+  status: InitiativeStatusSchema,
+  title: Schema.String,
+  created_at: Schema.String,
+  completed_at: Schema.NullOr(Schema.String),
+  /** Optional human-readable reason, used for terminal statuses. */
+  reason: Schema.optional(Schema.String),
 });
 
 export const ExecPendingConfigSchema = Schema.Struct({
@@ -66,4 +91,7 @@ export const decodeTaskRecord = Schema.decodeUnknownEither(TaskRecordSchema);
 export const decodeTaskMeta = Schema.decodeUnknownEither(TaskMetaSchema);
 export const decodeTasksLine = Schema.decodeUnknownEither(TasksLineSchema);
 export const decodePlanManifestEntry = Schema.decodeUnknownEither(PlanManifestEntrySchema);
+export const decodeInitiativeManifestEntry = Schema.decodeUnknownEither(
+  InitiativeManifestEntrySchema,
+);
 export const decodeExecPendingConfig = Schema.decodeUnknownEither(ExecPendingConfigSchema);

package/extensions/plan-mode/storage/initiatives-manifest.ts

@@ -0,0 +1,112 @@
+/**
+ * `.plans/initiatives.jsonl` registry — the initiative-level sibling of
+ * `plans-manifest.ts`.
+ *
+ * An initiative groups multiple plans. Its `status` is a PROJECTION of its
+ * member plans' statuses (see `reconcileInitiativeStatus` in `../initiative.ts`
+ * for the projection wiring): `done` when every member plan is terminal,
+ * `in-progress` otherwise. Manually-set terminal statuses (`superseded` /
+ * `abandoned` via `update_initiative`) are never auto-overridden.
+ *
+ * This module is intentionally dependency-light: it knows how to read/write the
+ * registry. The projection (which must read the PLANS manifest) lives in
+ * `../initiative.ts` to keep the dependency direction one-way and cycle-free.
+ */
+
+import { Effect, Either, Option } from 'effect';
+import { FileSystem } from '../effects/filesystem.js';
+import { JsonlParseError, JsonlValidationError, PlanWriteError } from '../errors.js';
+import { decodeInitiativeManifestEntry } from '../schema.js';
+import type { InitiativeStatus } from '../types.js';
+
+const MANIFEST_DIR = '.plans';
+const MANIFEST_PATH = '.plans/initiatives.jsonl';
+
+export interface InitiativeManifestEntry {
+  _type: 'initiative';
+  name: string;
+  status: InitiativeStatus;
+  title: string;
+  created_at: string;
+  completed_at: string | null;
+  reason?: string;
+}
+
+/** A status is terminal (closed) when it is anything other than in-progress. */
+export function isTerminalStatus(status: InitiativeStatus): boolean {
+  return status !== 'in-progress';
+}
+
+type ReadError = JsonlParseError | JsonlValidationError;
+
+export function readInitiativesManifest(): Effect.Effect<
+  InitiativeManifestEntry[],
+  ReadError,
+  FileSystem
+> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    // A missing or unreadable manifest is treated as "no initiatives".
+    const maybeText = yield* Effect.option(fs.readFileString(MANIFEST_PATH));
+    if (Option.isNone(maybeText)) return [];
+
+    const entries: InitiativeManifestEntry[] = [];
+    for (const [index, raw] of maybeText.value.split(/\r?\n/).entries()) {
+      if (!raw.trim()) continue;
+      const line = index + 1;
+
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(raw);
+      } catch (cause) {
+        return yield* Effect.fail(new JsonlParseError({ path: MANIFEST_PATH, line, cause }));
+      }
+
+      const decoded = decodeInitiativeManifestEntry(parsed);
+      if (Either.isLeft(decoded)) {
+        return yield* Effect.fail(
+          new JsonlValidationError({ path: MANIFEST_PATH, line, reason: decoded.left.message }),
+        );
+      }
+      entries.push(decoded.right);
+    }
+    return entries;
+  });
+}
+
+export function writeInitiativesManifest(
+  entries: InitiativeManifestEntry[],
+): Effect.Effect<void, PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    yield* fs.makeDir(MANIFEST_DIR);
+    const content =
+      entries.map((entry) => JSON.stringify(entry)).join('\n') + (entries.length ? '\n' : '');
+    yield* fs.writeFileAtomic(MANIFEST_PATH, content);
+  });
+}
+
+export function upsertInitiativeEntry(
+  name: string,
+  updates: { status: InitiativeStatus; title?: string; reason?: string },
+): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const entries = yield* readInitiativesManifest();
+    const now = new Date().toISOString();
+    const index = entries.findIndex((entry) => entry.name === name);
+    const existing = index === -1 ? undefined : entries[index];
+    const entry: InitiativeManifestEntry = {
+      _type: 'initiative',
+      name,
+      status: updates.status,
+      title: updates.title ?? existing?.title ?? 'Untitled initiative',
+      created_at: existing?.created_at ?? now,
+      // Terminal statuses record a completion timestamp; reopening clears it.
+      completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
+      reason: updates.reason ?? existing?.reason,
+    };
+    if (index === -1) entries.push(entry);
+    else entries[index] = entry;
+    yield* writeInitiativesManifest(entries);
+  });
+}

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

@@ -75,3 +75,14 @@ export function loadHandoff(planDir: string): Effect.Effect<string | undefined,
     return Option.getOrUndefined(maybeText);
   });
 }
+
+export function saveInitiative(
+  initiativeDir: string,
+  content: string,
+): Effect.Effect<void, PlanWriteError, FileSystem> {
+  return Effect.gen(function* () {
+    const fs = yield* FileSystem;
+    yield* fs.makeDir(initiativeDir);
+    yield* fs.writeFileString(`${initiativeDir}/INITIATIVE.md`, content);
+  });
+}

package/extensions/plan-mode/storage/plans-manifest.ts

@@ -15,6 +15,10 @@ export interface PlanManifestEntry {
   created_at: string;
   completed_at: string | null;
   reason?: string;
+  /** Parent initiative name (kebab). Absent = standalone flat plan. */
+  initiative?: string;
+  /** Plan-level dependencies (plan names). Cross-initiative allowed. */
+  depends_on?: string[];
 }
 
 /** A status is terminal (closed) when it is anything other than in-progress. */
@@ -69,7 +73,15 @@ export function writePlansManifest(
 
 export function upsertPlanEntry(
   name: string,
-  updates: { status: PlanStatus; title?: string; reason?: string },
+  updates: {
+    status: PlanStatus;
+    title?: string;
+    reason?: string;
+    /** Parent initiative name; preserved when omitted. */
+    initiative?: string;
+    /** Plan-level dependencies (plan names); preserved when omitted. */
+    depends_on?: string[];
+  },
 ): Effect.Effect<void, ReadError | PlanWriteError, FileSystem> {
   return Effect.gen(function* () {
     const entries = yield* readPlansManifest();
@@ -85,6 +97,9 @@ export function upsertPlanEntry(
       // Terminal statuses record a completion timestamp; reopening clears it.
       completed_at: isTerminalStatus(updates.status) ? (existing?.completed_at ?? now) : null,
       reason: updates.reason ?? existing?.reason,
+      // Membership + plan-level deps are preserved across status-only upserts.
+      initiative: updates.initiative ?? existing?.initiative,
+      depends_on: updates.depends_on ?? existing?.depends_on,
     };
     if (index === -1) entries.push(entry);
     else entries[index] = entry;