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

package/extensions/plan-mode/tools/update-initiative.ts

@@ -0,0 +1,120 @@
+/**
+ * update_initiative tool — initiative-level lifecycle control.
+ *
+ * The initiative sibling of update_plan. An initiative's `done` status is a
+ * projection of its member plans, but `superseded` / `abandoned` (and reopen)
+ * are explicit decisions recorded here with an optional `reason`. A manually
+ * set terminal status is never auto-overridden by projection.
+ */
+
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { StringEnum } from '@earendil-works/pi-ai';
+import { Text } from '@earendil-works/pi-tui';
+import { Type } from 'typebox';
+import type { InitiativeStatus } from '../types.js';
+import type { RunPlanIO } from '../effects/runtime.js';
+import {
+  readInitiativesManifest,
+  upsertInitiativeEntry,
+} from '../storage/initiatives-manifest.js';
+
+/** Normalize an initiative hint (`x` or `.plans/x`) to a bare name. */
+function normalizeName(hint: string): string {
+  return hint
+    .replace(/^\.plans\//, '')
+    .replace(/\/+$/, '')
+    .trim();
+}
+
+export function registerUpdateInitiativeTool(pi: ExtensionAPI, runPlanIO: RunPlanIO): void {
+  pi.registerTool({
+    name: 'update_initiative',
+    label: 'Update Initiative',
+    description:
+      'Set an initiative-level status (done, superseded, abandoned, or reopen to in-progress) with an optional reason.',
+    promptSnippet: 'Close or reopen an initiative (done/superseded/abandoned/in-progress)',
+    promptGuidelines: [
+      'Use update_initiative to close an initiative that will not complete via its plans: superseded (another initiative shipped it) or abandoned (won\u2019t do).',
+      'Always pass a reason for superseded/abandoned so the registry keeps honest history.',
+      'An initiative usually reaches done automatically once every member plan is closed \u2014 prefer letting projection handle it.',
+    ],
+    parameters: Type.Object({
+      initiative: Type.String({ description: 'Initiative name (or .plans/<name>) to update' }),
+      status: StringEnum(['in-progress', 'done', 'superseded', 'abandoned'] as const),
+      reason: Type.Optional(
+        Type.String({ description: 'Why — recorded in the registry (esp. superseded/abandoned)' }),
+      ),
+    }),
+
+    async execute(_toolCallId, params) {
+      const name = normalizeName(params.initiative);
+      const manifest = await runPlanIO(readInitiativesManifest());
+      const existing = manifest.find((entry) => entry.name === name);
+      if (!existing) {
+        const names = manifest.map((entry) => entry.name).join(', ');
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Initiative not found: ${name}. Known initiatives: ${names || '(none)'}`,
+            },
+          ],
+          details: { error: 'not_found', initiative: name } as Record<string, unknown>,
+        };
+      }
+
+      await runPlanIO(
+        upsertInitiativeEntry(name, {
+          status: params.status as InitiativeStatus,
+          title: existing.title,
+          reason: params.reason,
+        }),
+      );
+
+      const reasonSuffix = params.reason ? ` — ${params.reason}` : '';
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Initiative ${name}: ${existing.status} → ${params.status}${reasonSuffix}`,
+          },
+        ],
+        details: {
+          initiative: name,
+          from: existing.status,
+          status: params.status,
+          reason: params.reason,
+        } as Record<string, unknown>,
+      };
+    },
+
+    renderCall(args, theme) {
+      const name = (args as { initiative?: string }).initiative ?? 'initiative';
+      const status = (args as { status?: string }).status ?? '';
+      let content = theme.fg('toolTitle', theme.bold('update_initiative '));
+      content += theme.fg('accent', name);
+      if (status) content += ' ' + theme.fg('muted', status);
+      return new Text(content, 0, 0);
+    },
+
+    renderResult(result, _options, theme) {
+      const details = result.details as
+        | { initiative?: string; from?: string; status?: string }
+        | undefined;
+      if (!details?.status) return new Text(theme.fg('dim', 'Initiative updated'), 0, 0);
+      const color =
+        details.status === 'done'
+          ? 'success'
+          : details.status === 'in-progress'
+            ? 'accent'
+            : 'warning';
+      return new Text(
+        theme.fg('muted', `${details.initiative ?? 'initiative'} `) +
+          theme.fg('dim', `${details.from ?? ''} → `) +
+          theme.fg(color, details.status),
+        0,
+        0,
+      );
+    },
+  });
+}

package/extensions/plan-mode/tools/update-plan.ts

@@ -18,6 +18,7 @@ import { Type } from 'typebox';
 import type { PlanStatus } from '../types.js';
 import type { RunPlanIO } from '../effects/runtime.js';
 import { readPlansManifest, upsertPlanEntry } from '../storage/plans-manifest.js';
+import { reconcileInitiativeForPlan } from '../initiative.js';
 
 /** Normalize a plan hint (`my-plan` or `.plans/my-plan`) to a bare name. */
 function normalizeName(hint: string): string {
@@ -72,6 +73,8 @@ export function registerUpdatePlanTool(pi: ExtensionAPI, runPlanIO: RunPlanIO):
           reason: params.reason,
         }),
       );
+      // A plan-level status change can flip its parent initiative's projection.
+      await runPlanIO(reconcileInitiativeForPlan(name));
 
       const reasonSuffix = params.reason ? ` — ${params.reason}` : '';
       const okDetails: Record<string, unknown> = {

package/extensions/plan-mode/types.ts

@@ -13,6 +13,9 @@ export type TaskOrigin = 'plan' | 'discovered';
  */
 export type PlanStatus = 'in-progress' | 'done' | 'superseded' | 'abandoned';
 
+/** Initiative lifecycle reuses the plan lifecycle literals. */
+export type InitiativeStatus = PlanStatus;
+
 export interface TaskRecord {
   _type: 'task';
   id: string;

package/package.json

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

package/skills/planning-context/SKILL.md

@@ -37,6 +37,17 @@ Caveman-lite: professional, tight, no filler. Bullet points over prose. Update i
 
 `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.
 
+## Large work: initiatives
+
+When the work is too large for a single coherent execution session, or spans several
+subsystems with dependencies between chunks, do not force it into one general plan. Create
+an **initiative** (`submit_initiative`) and decompose the work into multiple plans, each
+linked with `initiative` and ordered with `depends_on_plans`. The initiative's status is a
+projection of its member plans; `initiative_status` shows which plans are *ready* (all
+dependencies done) so work can be divided across sessions or subagents. Keep the
+initiative-level deliberation (why this breakdown, the ordering, what each plan owns) in
+the initiative's `INITIATIVE.md` overview; each member plan keeps its own `context.md`.
+
 ## 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

@@ -30,9 +30,11 @@ 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.
+- `html` — a complete, self-contained HTML document you author **with full freedom**. There is no template engine and no imposed theme: pick your own markup, fonts, colors, layout, and inline `<style>`/`<script>`. Assume nothing about a host page.
 
-The tool renders the Pug, writes `.plans/_prototypes/<slug>.html`, and opens it for review.
+The tool persists your HTML to `.plans/_prototypes/<slug>.html` and opens it for review. It does not wrap, restyle, or theme your markup — what you write is what the user sees. (A bare fragment is tolerated and dropped into a minimal unstyled shell, but prefer sending a full document.)
+
+**Avoid generic boilerplate.** A dark dashboard with a purple accent and a card is not a design — it is slop. Design something that fits the actual product. For real design taste, delegate the markup to the `ux-designer` subagent and pass its HTML straight through `preview_prototype`.
 
 ### 3. Get a reaction before submitting
 

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

@@ -1,25 +0,0 @@
-doctype html
-html(lang="en")
-  head
-    meta(charset="utf-8")
-    meta(name="viewport" content="width=device-width, initial-scale=1")
-    title= title
-    style.
-      :root { color-scheme: dark; --bg:#0b0d12; --panel:#11141b; --muted:#8b93a7; --text:#eef1f7; --line:#242936; --accent:#8b5cf6; }
-      * { 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 { margin-bottom:24px; }
-      h1 { font-size:30px; line-height:1.1; margin:0 0 8px; letter-spacing:-0.04em; }
-      .intent { color:var(--muted); margin:0; }
-      .badge { display:inline-block; border:1px solid var(--line); border-radius:999px; padding:5px 10px; background:rgba(255,255,255,0.03); color:var(--muted); font-size:12px; margin-bottom:14px; }
-      .prototype { background:rgba(17,20,27,0.82); border:1px solid var(--line); border-radius:18px; padding:22px; box-shadow:0 24px 80px rgba(0,0,0,0.24); }
-  body
-    main
-      header
-        span.badge Prototype · #{generatedAt}
-        h1= title
-        if intent
-          p.intent= intent
-      section.prototype
-        != prototypeHtml

package/extensions/plan-mode/pug.d.ts

@@ -1,5 +0,0 @@
-declare module 'pug' {
-  export function render(template: string, options?: Record<string, unknown>): string;
-  const pug: { render: typeof render };
-  export default pug;
-}