@dreki-gg/pi-plan-mode 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @dreki-gg/pi-plan-mode
 
+## 0.4.0
+
+### Minor Changes
+
+- [`c86c935`](https://github.com/dreki-gg/pi-extensions/commit/c86c9352150a5bed61602243c8164bdd5d679745) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Add plans.json lifecycle tracking and CLI for cleaning completed plans
+
+  - Extension now writes `.plans/plans.json` to track plan status (`in-progress` / `done`) with timestamps and titles
+  - Plans are recorded as `in-progress` when created, marked `done` when all execution steps complete
+  - New `pi-plan-mode clean` CLI (`npx @dreki-gg/pi-plan-mode clean [--dry-run]`) removes completed plan directories while preserving in-flight plans
+  - Cleanup step added to publish.yml workflow to auto-clean done plans on merge to main
+  - Removed stale `docs/plans/` from browser-tools and subagent packages
+
+## 0.3.1
+
+### Patch Changes
+
+- [`d133c3d`](https://github.com/dreki-gg/pi-extensions/commit/d133c3da917e7e5def568d27d6cde8ae8a6c00d2) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Mark pi peer dependencies as optional so npm does not auto-install pi internals when installing extension packages.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -67,12 +67,84 @@ When **Execute Plan** is selected:
 
 ```
 .plans/
+├── plans.json                # Tracking manifest — plan status lifecycle
 └── add-auth-middleware/
-    ├── PLAN.md           # Numbered plan with context
-    ├── START-PROMPT.md   # Self-contained executor handoff prompt
-    └── ...               # Optional supporting files
+    ├── PLAN.md               # Numbered plan with context
+    ├── START-PROMPT.md       # Self-contained executor handoff prompt
+    └── ...                   # Optional supporting files
 ```
 
+### plans.json
+
+The extension automatically maintains `.plans/plans.json` to track plan lifecycle:
+
+```json
+{
+  "add-auth-middleware": {
+    "status": "in-progress",
+    "title": "Add Authentication Middleware with JWT Support",
+    "created": "2026-05-08T12:00:00.000Z",
+    "completed": null
+  },
+  "fix-ci-flakes": {
+    "status": "done",
+    "title": "Fix CI Flaky Tests",
+    "created": "2026-05-07T10:00:00.000Z",
+    "completed": "2026-05-07T14:30:00.000Z"
+  }
+}
+```
+
+Plans start as `"in-progress"` when created and are marked `"done"` when all execution steps complete. This prevents accidental deletion of in-flight plans.
+
+## Cleaning completed plans
+
+Use the CLI to remove completed plan directories:
+
+```bash
+# Preview what would be deleted
+npx @dreki-gg/pi-plan-mode clean --dry-run
+
+# Delete completed plans and update plans.json
+npx @dreki-gg/pi-plan-mode clean
+```
+
+In-flight plans (`"status": "in-progress"`) are never touched.
+
+### GitHub Actions
+
+Clean done plans automatically after merge — similar to changesets:
+
+```yaml
+name: Clean Plans
+
+on:
+  push:
+    branches: [main]
+    paths: ['.plans/**']
+
+jobs:
+  clean:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '24'
+      - run: npx @dreki-gg/pi-plan-mode clean
+      - name: Commit cleanup
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add .plans/
+          git diff --cached --quiet || git commit -m "chore: clean completed plans"
+          git push
+```
+
+### Should you gitignore `.plans/`?
+
+**No.** Commit your plans — they provide decision history and execution context. Use the `clean` CLI to remove done plans after merge, keeping the directory lean. Plans are execution blueprints, not permanent documentation; for lasting decisions, use ADRs.
+
 ## Footer indicators
 
 - `📝 plan` — plan mode active (opus-4-6:medium, strict bash)
@@ -81,3 +153,14 @@ When **Execute Plan** is selected:
 ## Bash safety
 
 In plan mode, bash is restricted to read-only commands (ls, grep, git status, cat, rg, etc.). Destructive commands (rm, mv, git commit, etc.) are blocked.
+
+## CLI reference
+
+```
+pi-plan-mode clean [--dry-run]
+```
+
+| Option      | Description                                      |
+| ----------- | ------------------------------------------------ |
+| `clean`     | Remove completed plan directories, update manifest |
+| `--dry-run` | Show what would be deleted without deleting      |

package/bin/clean-plans.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * CLI to clean completed plans from `.plans/`.
+ *
+ * Usage:
+ *   npx @dreki-gg/pi-plan-mode clean [--dry-run]
+ *
+ * Reads `.plans/plans.json`, deletes directories for plans with status "done",
+ * and updates `plans.json` to remove them.
+ *
+ * Designed for use in GitHub Actions after merge — similar to changesets.
+ */
+
+import { readFileSync, writeFileSync, rmSync, readdirSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+const PLANS_DIR = '.plans';
+const PLANS_JSON = join(PLANS_DIR, 'plans.json');
+
+function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (command !== 'clean') {
+    console.error('Usage: pi-plan-mode clean [--dry-run]\n');
+    console.error('Commands:');
+    console.error('  clean       Remove completed plan directories and update plans.json\n');
+    console.error('Options:');
+    console.error('  --dry-run   Show what would be deleted without actually deleting');
+    process.exit(1);
+  }
+
+  const dryRun = args.includes('--dry-run');
+  const plansJsonPath = resolve(PLANS_JSON);
+
+  if (!existsSync(plansJsonPath)) {
+    console.log('No .plans/plans.json found — nothing to clean.');
+    process.exit(0);
+  }
+
+  /** @type {Record<string, { status: string; title: string; created: string; completed: string | null }>} */
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(plansJsonPath, 'utf-8'));
+  } catch (err) {
+    console.error(`Failed to parse ${PLANS_JSON}:`, err);
+    process.exit(1);
+  }
+
+  const donePlans = Object.entries(manifest).filter(([, entry]) => entry.status === 'done');
+  const inFlightPlans = Object.entries(manifest).filter(
+    ([, entry]) => entry.status === 'in-progress',
+  );
+
+  if (donePlans.length === 0) {
+    console.log('No completed plans to clean.');
+    if (inFlightPlans.length > 0) {
+      console.log(`\n${inFlightPlans.length} plan(s) still in progress:`);
+      for (const [name, entry] of inFlightPlans) {
+        console.log(`  ○ ${name} — ${entry.title}`);
+      }
+    }
+    process.exit(0);
+  }
+
+  console.log(dryRun ? 'Dry run — would clean:\n' : 'Cleaning completed plans:\n');
+
+  let cleaned = 0;
+  for (const [name, entry] of donePlans) {
+    const planPath = resolve(join(PLANS_DIR, name));
+    const exists = existsSync(planPath);
+
+    if (dryRun) {
+      console.log(`  ✓ ${name} — ${entry.title}${exists ? '' : ' (directory already missing)'}`);
+    } else {
+      if (exists) {
+        rmSync(planPath, { recursive: true, force: true });
+        console.log(`  ✓ Deleted ${PLANS_DIR}/${name} — ${entry.title}`);
+      } else {
+        console.log(`  ✓ ${name} — directory already missing, removing from manifest`);
+      }
+      delete manifest[name];
+      cleaned++;
+    }
+  }
+
+  if (!dryRun) {
+    const remaining = Object.keys(manifest).length;
+    if (remaining === 0) {
+      rmSync(plansJsonPath, { force: true });
+      // Remove .plans/ if completely empty
+      const plansDir = resolve(PLANS_DIR);
+      try {
+        if (existsSync(plansDir) && readdirSync(plansDir).length === 0) {
+          rmSync(plansDir, { recursive: true, force: true });
+          console.log(`\nRemoved empty ${PLANS_DIR}/`);
+        }
+      } catch {
+        // Directory might have other contents
+      }
+    } else {
+      writeFileSync(plansJsonPath, JSON.stringify(manifest, null, 2) + '\n');
+    }
+
+    console.log(`\nCleaned ${cleaned} plan(s).`);
+    if (remaining > 0) {
+      console.log(`${remaining} plan(s) still in progress.`);
+    }
+  } else {
+    console.log(`\n${donePlans.length} plan(s) would be cleaned.`);
+    if (inFlightPlans.length > 0) {
+      console.log(`${inFlightPlans.length} plan(s) still in progress (will be kept).`);
+    }
+  }
+}
+
+main();

package/extensions/plan-mode/index.ts

@@ -28,6 +28,12 @@ import {
   markCompletedSteps,
   type TodoItem,
 } from './utils.js';
+import {
+  extractPlanTitle,
+  readPlansJson,
+  serializePlansJson,
+  type PlansManifest,
+} from './plans-json.js';
 
 // ── Tool sets ────────────────────────────────────────────────────────────────
 // Plan phase: read-only + edit/write (for .plans/ files only, enforced by prompt)
@@ -99,6 +105,29 @@ export default function planMode(pi: ExtensionAPI): void {
     });
   }
 
+  // ── plans.json tracking ───────────────────────────────────────────────────
+  async function updatePlansManifest(
+    planName: string,
+    status: 'in-progress' | 'done',
+    title?: string,
+  ): Promise<void> {
+    const manifest = await readPlansJson((cmd, args) => pi.exec(cmd, args));
+    const existing = manifest[planName];
+    const now = new Date().toISOString();
+
+    manifest[planName] = {
+      status,
+      title: title ?? existing?.title ?? 'Untitled plan',
+      created: existing?.created ?? now,
+      completed: status === 'done' ? now : null,
+    };
+
+    await pi.exec('mkdir', ['-p', '.plans']);
+    const content = serializePlansJson(manifest);
+    // Write via a temp approach — use bash echo to avoid needing the write tool
+    await pi.exec('bash', ['-c', `cat > .plans/plans.json << 'PLANS_EOF'\n${content}PLANS_EOF`]);
+  }
+
   // ── UI updates ────────────────────────────────────────────────────────────
   function updateUI(ctx: ExtensionContext): void {
     const { theme } = ctx.ui;
@@ -384,7 +413,33 @@ Execute each step in order. You MUST include [DONE:n] in your response after com
     const match = path.match(/\.plans\/([^/]+)\//);
     if (match && !planDir) {
       planDir = `.plans/${match[1]}`;
+      const planName = match[1];
+
+      // Read PLAN.md to extract the title for plans.json
+      let title = 'Untitled plan';
+      if (path.endsWith('PLAN.md')) {
+        try {
+          const result = await pi.exec('cat', [path]);
+          if (result.code === 0) {
+            title = extractPlanTitle(result.stdout);
+          }
+        } catch {
+          // Fall through
+        }
+      }
+      await updatePlansManifest(planName, 'in-progress', title);
       persist();
+    } else if (match && planDir && path.endsWith('PLAN.md')) {
+      // planDir already set but PLAN.md just written — update title
+      try {
+        const result = await pi.exec('cat', [path]);
+        if (result.code === 0) {
+          const title = extractPlanTitle(result.stdout);
+          await updatePlansManifest(match[1], 'in-progress', title);
+        }
+      } catch {
+        // Fall through
+      }
     }
   });
 
@@ -393,6 +448,12 @@ Execute each step in order. You MUST include [DONE:n] in your response after com
     // Check execution completion
     if (executing && todos.length > 0) {
       if (todos.every((t) => t.completed)) {
+        // Mark plan as done in plans.json
+        if (planDir) {
+          const planName = planDir.replace(/^\.plans\//, '');
+          await updatePlansManifest(planName, 'done');
+        }
+
         const list = todos.map((t) => `~~${t.text}~~`).join('\n');
         pi.sendMessage(
           {

package/extensions/plan-mode/plans-json.ts

@@ -0,0 +1,50 @@
+/**
+ * Reads and writes `.plans/plans.json` — the tracking manifest for plan lifecycle.
+ *
+ * Schema:
+ * ```json
+ * {
+ *   "<plan-name>": {
+ *     "status": "in-progress" | "done",
+ *     "title": "Human-readable plan title",
+ *     "created": "2026-05-08T12:00:00.000Z",
+ *     "completed": "2026-05-08T13:00:00.000Z" | null
+ *   }
+ * }
+ * ```
+ */
+
+export interface PlanEntry {
+  status: 'in-progress' | 'done';
+  title: string;
+  created: string;
+  completed: string | null;
+}
+
+export type PlansManifest = Record<string, PlanEntry>;
+
+const PLANS_JSON = '.plans/plans.json';
+
+/** Read plans.json via pi.exec, returning current manifest (empty object if missing). */
+export async function readPlansJson(exec: (cmd: string, args: string[]) => Promise<{ code: number; stdout: string }>): Promise<PlansManifest> {
+  try {
+    const result = await exec('cat', [PLANS_JSON]);
+    if (result.code === 0 && result.stdout.trim()) {
+      return JSON.parse(result.stdout) as PlansManifest;
+    }
+  } catch {
+    // File doesn't exist or isn't valid JSON
+  }
+  return {};
+}
+
+/** Serialize the manifest to a formatted JSON string. */
+export function serializePlansJson(manifest: PlansManifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`;
+}
+
+/** Extract the plan title from the first `# ...` heading in PLAN.md content. */
+export function extractPlanTitle(planContent: string): string {
+  const match = planContent.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : 'Untitled plan';
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-plan-mode",
-  "version": "0.3.0",
+  "version": "0.4.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"
@@ -13,17 +13,21 @@
     "directory": "packages/plan-mode"
   },
   "type": "module",
+  "bin": {
+    "pi-plan-mode": "./bin/clean-plans.js"
+  },
   "files": [
     "extensions",
+    "bin",
     "README.md",
     "CHANGELOG.md",
     "package.json"
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "oxlint extensions",
-    "format": "oxfmt --write extensions",
-    "format:check": "oxfmt --check extensions"
+    "lint": "oxlint extensions bin",
+    "format": "oxfmt --write extensions bin",
+    "format:check": "oxfmt --check extensions bin"
   },
   "pi": {
     "extensions": [
@@ -39,5 +43,13 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
   }
 }