portable-agent-layer 0.16.0 → 0.18.0

package/README.md

@@ -2,7 +2,7 @@
 
 A cross-platform, cross-agent layer for portable AI workflows, memory, and accumulated knowledge.
 
-PAL lets you carry your agent context across **Windows**, **macOS**, and **Linux**, and work across different agent runtimes and interfaces such as **Claude** and **OpenCode**. Its core idea is simple: your knowledge and workflows should belong to **you**, not to a single machine, tool, or vendor.
+PAL lets you carry your agent context across **Windows**, **macOS**, and **Linux**, and work across different agent runtimes and interfaces such as **Claude Code**, **opencode**, **Cursor**, and **Codex**. Its core idea is simple: your knowledge and workflows should belong to **you**, not to a single machine, tool, or vendor.
 
 > Inspired in part by [Daniel Miessler](https://danielmiessler.com)'s work on [Personal AI Infrastructure](https://github.com/danielmiessler/Personal_AI_Infrastructure). PAL is an independent open-source implementation focused on portability across platforms and agents. It is not affiliated with or endorsed by Daniel Miessler.
 
@@ -33,7 +33,7 @@ With PAL, you can:
 > **Bun is required.** PAL is built on [Bun](https://bun.sh) and will not work with Node.js or other runtimes. Install it with `curl -fsSL https://bun.sh/install | bash`.
 
 - [Bun](https://bun.sh) >= 1.3.0
-- At least one of: [Claude Code](https://claude.ai/code) or [opencode](https://opencode.ai)
+- At least one of: [Claude Code](https://claude.ai/code), [opencode](https://opencode.ai), [Cursor](https://cursor.com), or [Codex](https://openai.com/index/introducing-codex/)
 
 ### Package mode (recommended)
 
@@ -94,6 +94,15 @@ pal cli install --cursor      # Cursor only
 pal cli install               # all available (default)
 ```
 
+### Supported agents
+
+| Agent | Support | Skills | Hooks | AGENTS.md | Subagents |
+|-------|---------|--------|-------|-----------|-----------|
+| Claude Code | Full | Yes | Yes | Yes | Yes |
+| opencode | Full | Yes | Yes (plugin) | Yes | Yes |
+| Cursor | Full | Yes | Yes | Yes (injected via hook) | Yes |
+| Codex | Partial | Yes | No | Yes | No |
+
 ---
 
 ## Environment variables
@@ -114,6 +123,7 @@ pal cli install               # all available (default)
 | `PAL_CLAUDE_DIR` | Override Claude config dir (default: `~/.claude`) |
 | `PAL_OPENCODE_DIR` | Override opencode config dir (default: `~/.config/opencode`) |
 | `PAL_CURSOR_DIR` | Override Cursor config dir (default: `~/.cursor`) |
+| `PAL_CODEX_DIR` | Override Codex config dir (default: `~/.codex`) |
 | `PAL_AGENTS_DIR` | Override agents dir (default: `~/.agents`) |
 
 ---
@@ -162,7 +172,7 @@ Your setup should be able to travel with you.
 ## Features
 
 - **Cross-platform**: works on Windows, macOS, and Linux
-- **Cross-agent**: designed to work across multiple agent ecosystems
+- **Cross-agent**: full support for Claude Code, opencode, and Cursor; partial support for Codex
 - **Portable knowledge**: export and import accumulated knowledge
 - **TypeScript-first**: built in TypeScript from day one
 - **Open source**: hackable, inspectable, extensible

package/assets/templates/PAL/ALGORITHM.md

@@ -2,11 +2,11 @@
 
 Core: transition from CURRENT STATE to IDEAL STATE using verifiable criteria. Every criterion is atomic, binary testable, and checked off with evidence.
 
-## The Four Phases
+## The Five Phases
 
 All work happens inside these phases. No work outside the phase structure until the Algorithm completes.
 
-### ━━━ 👁️ OBSERVE ━━━ 1/4
+### ━━━ 👁️ OBSERVE ━━━ 1/5
 
 Thinking-only. No tool calls except context recovery (Grep/Glob/Read).
 
@@ -44,7 +44,7 @@ Output:
 🏹 CAPABILITIES: [list each selected skill/tool and why]
 ```
 
-### ━━━ 🧠 PLAN ━━━ 2/4
+### ━━━ 🧠 PLAN ━━━ 2/5
 
 **Pressure test the criteria:**
 
@@ -59,7 +59,7 @@ Refine criteria if the pressure test reveals gaps. Add criteria for uncovered fa
 - Decide execution order — what's serial, what can parallelize
 - If Advanced+ complexity, use EnterPlanMode for user alignment
 
-### ━━━ ⚡ EXECUTE ━━━ 3/4
+### ━━━ ⚡ EXECUTE ━━━ 3/5
 
 Do the work. Invoke selected capabilities via tool calls.
 
@@ -67,7 +67,7 @@ Do the work. Invoke selected capabilities via tool calls.
 - If a criterion can't be met, flag it immediately — don't defer to VERIFY
 - Make decisions explicit — state why you chose approach A over B
 
-### ━━━ ✅ VERIFY ━━━ 4/4
+### ━━━ ✅ VERIFY ━━━ 4/5
 
 No rubber-stamping. Each criterion needs specific evidence.
 
@@ -88,13 +88,30 @@ For EACH criterion:
 
 If any criteria failed, fix and re-verify before completing.
 
+### ━━━ 📚 LEARN ━━━ 5/5
+
+Reflect on the work and capture reusable knowledge. Skip this phase when the work was trivial or purely mechanical.
+
+**1. Reflection** (one sentence each):
+- What would I do differently next time?
+- What would a better algorithm have done differently?
+
+**2. Wisdom Frame** — if the session produced a genuine, reusable insight:
+
+```bash
+bun ~/.agents/PAL/tools/wisdom-frame.ts --domain <domain> --observation "insight" [--type principle|contextual-rule|anti-pattern|evolution]
+```
+
+Domains: `development`, `workflow`, `communication`, `infrastructure`, `integration`, or any fitting domain.
+Only write if the insight is **genuine and reusable** — not every session produces one. When in doubt, skip.
+
 ## Output Format
 
 ```
 ♻️ ALGORITHM ═══════════════════════════
 🗒️ TASK: [brief description]
 
-━━━ 👁️ OBSERVE ━━━ 1/4
+━━━ 👁️ OBSERVE ━━━ 1/5
 🔎 REVERSE ENGINEERING:
 [reverse engineering output]
 
@@ -103,18 +120,22 @@ If any criteria failed, fix and re-verify before completing.
 
 🏹 CAPABILITIES: [selected capabilities]
 
-━━━ 🧠 PLAN ━━━ 2/4
+━━━ 🧠 PLAN ━━━ 2/5
 🧠 RISKS: [risks]
 🧠 PREMORTEM: [failure modes]
 📐 APPROACH: [execution plan]
 
-━━━ ⚡ EXECUTE ━━━ 3/4
+━━━ ⚡ EXECUTE ━━━ 3/5
 [work happens here]
 
-━━━ ✅ VERIFY ━━━ 4/4
+━━━ ✅ VERIFY ━━━ 4/5
 ✅ VERIFICATION:
 [criterion-by-criterion evidence]
 
 🔧 CHANGE: [what changed]
 🗣️ {{IDENTITY_NAME}}: [summary]
+
+━━━ 📚 LEARN ━━━ 5/5
+🪞 REFLECT: [what I'd do differently]
+📝 WISDOM: [frame update if genuine insight, or "No new insight"]
 ```

package/assets/templates/PAL/README.md

@@ -1,12 +1,12 @@
 # PAL — Portable Agent Layer
 
-PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows, memory, and accumulated knowledge. It runs inside any compatible AI coding agent (Claude Code, opencode) as an interconnected set of skills, hooks, tools, memory, and configuration — all orchestrated by The Algorithm.
+PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows, memory, and accumulated knowledge. It runs inside any compatible AI coding agent (Claude Code, opencode, Cursor, Codex) as an interconnected set of skills, hooks, tools, memory, and configuration — all orchestrated by The Algorithm.
 
 ## How It Works
 
 **CLAUDE.md** (or the agent equivalent) is the entry point — generated from a template by the CLI installer. It defines execution modes, The Algorithm routing, and the context routing table. The agent loads it natively every session. A SessionStart hook keeps it fresh automatically.
 
-**The PAL home directory (`~/.agents/PAL/`)** contains all system documentation, user context (TELOS), and routing files. The rest of the system lives in the PAL package (`src/`) and the agent's config directory (`~/.claude/` or `~/.config/opencode/`).
+**The PAL home directory (`~/.agents/PAL/`)** contains all system documentation, user context (TELOS), and routing files. The rest of the system lives in the PAL package (`src/`) and the agent's config directory (`~/.claude/`, `~/.config/opencode/`, `~/.cursor/`, or `~/.codex/`).
 
 ## Directory Structure
 
@@ -29,7 +29,7 @@ PAL is a persistent, cross-platform, cross-agent layer for portable AI workflows
     hooks/                         # Session lifecycle hooks
       handlers/                    # Individual stop/prompt handlers
       lib/                         # Shared utilities
-    targets/                       # Agent-specific installers (Claude, opencode)
+    targets/                       # Agent-specific installers (Claude, opencode, Cursor)
     tools/                         # Standalone CLI tools
   assets/
     skills/                        # Bundled skills (16+)
@@ -104,6 +104,7 @@ pal                          # Start agent session with auto-summary on exit
 pal cli init                 # Scaffold PAL home + install hooks
 pal cli install [--claude]   # Register hooks/skills for Claude Code
 pal cli install [--opencode] # Register hooks/skills for opencode
+pal cli install [--cursor]   # Register hooks/skills for Cursor
 pal cli uninstall            # Remove hooks/skills
 pal cli status               # Show configuration
 pal cli doctor               # Check prerequisites and health
@@ -116,8 +117,8 @@ pal cli update               # Update PAL
 
 PAL is designed to work identically across:
 - **Platforms:** macOS, Linux, Windows
-- **Agents:** Claude Code, opencode (and future tools)
-- **Environment overrides:** `PAL_HOME`, `PAL_PKG`, `PAL_CLAUDE_DIR`, `PAL_OPENCODE_DIR`, `PAL_AGENTS_DIR`
+- **Agents:** Claude Code (full), opencode (full), Cursor (full), Codex (partial — AGENTS.md and skills only, no hooks or subagents)
+- **Environment overrides:** `PAL_HOME`, `PAL_PKG`, `PAL_CLAUDE_DIR`, `PAL_OPENCODE_DIR`, `PAL_CURSOR_DIR`, `PAL_CODEX_DIR`, `PAL_AGENTS_DIR`
 
 ## Extending PAL
 

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -433,9 +433,14 @@ src/targets/
 │   ├── install.ts   # Register hooks + skills in opencode config
 │   ├── uninstall.ts
 │   └── plugin.ts    # opencode plugin interface
+├── cursor/          # Cursor specific
+│   ├── install.ts   # Register hooks + skills in ~/.cursor/
+│   └── uninstall.ts
 └── lib.ts           # Shared: JSON read/write, settings merge, TELOS scaffold
 ```
 
+Codex support is partial — AGENTS.md is symlinked to `~/.codex/AGENTS.md` automatically (no dedicated target installer needed).
+
 ### Path Resolution
 
 All paths resolve through `src/hooks/lib/paths.ts`:
@@ -446,6 +451,8 @@ All paths resolve through `src/hooks/lib/paths.ts`:
 | PAL package | Auto-detected from source | `PAL_PKG` |
 | Claude config | `~/.claude` | `PAL_CLAUDE_DIR` |
 | opencode config | `~/.config/opencode` | `PAL_OPENCODE_DIR` |
+| Cursor config | `~/.cursor` | `PAL_CURSOR_DIR` |
+| Codex config | `~/.codex` | `PAL_CODEX_DIR` |
 | Agents dir | `~/.agents` | `PAL_AGENTS_DIR` |
 
 ### Portability Contract

package/assets/templates/settings.claude.json

@@ -19,7 +19,8 @@
       "Bash(file //*)",
       "Bash(stat //*)",
       "Bash(readlink //*)",
-      "Bash(bun ~/.agents/skills/*/tools/*.ts *)"
+      "Bash(bun ~/.agents/skills/*/tools/*.ts *)",
+      "Bash(bun run tool:wisdom-frame *)"
     ]
   },
   "hooks": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -44,7 +44,8 @@
     "prepare": "husky",
     "install:all": "bun run src/cli/index.ts cli install",
     "uninstall": "bun run src/cli/index.ts cli uninstall",
-    "tool:analyze": "bun run src/tools/analyze.ts",
+    "tool:analyze": "bun run src/tools/agent/analyze.ts",
+    "tool:wisdom-frame": "bun run src/tools/agent/wisdom-frame.ts",
     "tool:reflect": "bun run src/tools/relationship-reflect.ts",
     "tool:export": "bun run src/tools/export.ts",
     "tool:import": "bun run src/tools/import.ts",

package/src/hooks/lib/claude-md.ts

@@ -48,19 +48,25 @@ function latestMtime(...filePaths: string[]): number {
   return latest;
 }
 
-/** Ensure CLAUDE.md is a symlink pointing to AGENTS.md */
-function ensureSymlink(): void {
-  const { outputPath, symlinkPath } = getOutputPaths();
+/** Create or verify a symlink pointing to AGENTS.md */
+function ensureOneSymlink(linkPath: string, targetPath: string): void {
   try {
-    const stat = lstatSync(symlinkPath);
-    // If it exists but isn't a symlink (e.g. old generated file), remove it
-    if (!stat.isSymbolicLink()) unlinkSync(symlinkPath);
+    const stat = lstatSync(linkPath);
+    if (!stat.isSymbolicLink()) unlinkSync(linkPath);
     else return; // already a symlink, leave it
   } catch {
     // doesn't exist — create it
   }
-  const relTarget = relative(dirname(symlinkPath), outputPath).replaceAll("\\", "/");
-  symlinkSync(relTarget, symlinkPath);
+  ensureDir(dirname(linkPath));
+  const relTarget = relative(dirname(linkPath), targetPath).replaceAll("\\", "/");
+  symlinkSync(relTarget, linkPath);
+}
+
+/** Ensure all agent symlinks point to the canonical AGENTS.md */
+function ensureSymlinks(): void {
+  const { outputPath, symlinkPath } = getOutputPaths();
+  ensureOneSymlink(symlinkPath, outputPath);
+  ensureOneSymlink(resolve(platform.codexDir(), "AGENTS.md"), outputPath);
 }
 
 /** Returns true if AGENTS.md needs to be regenerated */
@@ -150,7 +156,7 @@ export function buildClaudeMd(): string {
 /** Regenerate AGENTS.md if any source file is newer, and ensure CLAUDE.md symlink exists. Returns true if rebuilt. */
 export function regenerateIfNeeded(): boolean {
   const { outputPath } = getOutputPaths();
-  ensureSymlink();
+  ensureSymlinks();
   if (!needsRebuild()) return false;
   ensureDir(dirname(outputPath));
   writeFileSync(outputPath, buildClaudeMd(), "utf-8");

package/src/hooks/lib/paths.ts

@@ -68,6 +68,7 @@ export const platform = {
   claudeDir: () => process.env.PAL_CLAUDE_DIR || resolve(h, ".claude"),
   opencodeDir: () => process.env.PAL_OPENCODE_DIR || resolve(h, ".config", "opencode"),
   cursorDir: () => process.env.PAL_CURSOR_DIR || resolve(h, ".cursor"),
+  codexDir: () => process.env.PAL_CODEX_DIR || resolve(h, ".codex"),
   agentsDir: () => process.env.PAL_AGENTS_DIR || resolve(h, ".agents"),
 } as const;
 
@@ -80,5 +81,6 @@ export const assets = {
   agentsMdTemplate: () => pkg("assets", "templates", "AGENTS.md.template"),
   claudeSettingsTemplate: () => pkg("assets", "templates", "settings.claude.json"),
   cursorHooksTemplate: () => pkg("assets", "templates", "hooks.cursor.json"),
+  agentTools: () => pkg("src", "tools", "agent"),
   palDocs: () => pkg("assets", "templates", "PAL"),
 } as const;

package/src/targets/lib.ts

@@ -273,10 +273,11 @@ export function copyPalDocs(): number {
     count++;
   }
 
-  // Symlink ~/.agents/PAL/telos and ~/.agents/PAL/memory → <palHome>/...
+  // Symlink ~/.agents/PAL/{telos,memory,tools} → source locations
   const linkType = process.platform === "win32" ? "junction" : "dir";
   ensureSymlink(resolve(PAL_DOCS_DIR, "telos"), resolve(palHome(), "telos"), linkType);
   ensureSymlink(resolve(PAL_DOCS_DIR, "memory"), resolve(palHome(), "memory"), linkType);
+  ensureSymlink(resolve(PAL_DOCS_DIR, "tools"), assets.agentTools(), linkType);
 
   return count;
 }

package/src/tools/agent/analyze.ts

@@ -0,0 +1,157 @@
+#!/usr/bin/env bun
+/**
+ * Unified Learning Analysis — graduation patterns + ratings summary.
+ *
+ * Reads failures and session learnings, finds recurring patterns,
+ * summarizes ratings, and generates recommendations.
+ *
+ * Usage: bun run tool:analyze
+ */
+
+import { parseArgs } from "node:util";
+import { type AnalysisResult, analyze } from "../../hooks/lib/graduation";
+
+// ── ANSI Colors ──
+
+const c = {
+  bold: (s: string) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s: string) => `\x1b[2m${s}\x1b[0m`,
+  cyan: (s: string) => `\x1b[36m${s}\x1b[0m`,
+  yellow: (s: string) => `\x1b[33m${s}\x1b[0m`,
+  green: (s: string) => `\x1b[32m${s}\x1b[0m`,
+  red: (s: string) => `\x1b[31m${s}\x1b[0m`,
+  magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
+};
+
+export function printReport(result: AnalysisResult): void {
+  const hasPatterns = result.candidates.length > 0 || result.emerging.length > 0;
+  const hasRatings = result.ratings !== null;
+
+  if (!hasPatterns && !hasRatings) {
+    console.log("\n  No patterns or ratings data found.\n");
+    return;
+  }
+
+  if (result.ratings) {
+    const r = result.ratings;
+    const avgColor = r.average >= 7 ? c.green : r.average <= 4 ? c.red : c.yellow;
+    console.log(
+      `\n  ${c.bold("Ratings:")} ${avgColor(`${r.average.toFixed(1)}/10`)} avg (${r.total} total)`
+    );
+    console.log(
+      `  ${c.red(`Low (≤4): ${r.low.count}`)} | ${c.green(`High (≥7): ${r.high.count}`)}`
+    );
+  }
+
+  if (result.candidates.length > 0) {
+    console.log(
+      `\n  ${c.bold(c.green(`Graduation Report — ${result.candidates.length} pattern(s) detected`))}\n`
+    );
+    console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
+
+    for (const candidate of result.candidates) {
+      console.log(
+        `  ${c.cyan(`[${candidate.domain}]`)} ${c.bold(`${candidate.entries.length}x`)} occurrences`
+      );
+      console.log("");
+
+      for (const entry of candidate.entries) {
+        const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
+        const tag =
+          sourceType === "failure"
+            ? c.red(`[${sourceType}]`)
+            : c.yellow(`[${sourceType}]`);
+        console.log(
+          `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 100)}`
+        );
+      }
+
+      console.log(`\n  ${c.dim("Files:")}`);
+      for (const entry of candidate.entries) {
+        console.log(`    ${c.dim(entry.path)}`);
+      }
+
+      console.log("");
+      console.log(
+        `  Target frame: ${c.magenta(`memory/wisdom/frames/${candidate.domain}.md`)}`
+      );
+      console.log(`  ${c.dim("─────────────────────────────────────────────────")}\n`);
+    }
+  }
+
+  if (result.emerging.length > 0) {
+    console.log(`  ${c.bold(c.yellow("Emerging (2x — one more to graduate)"))}\n`);
+    for (const group of result.emerging) {
+      console.log(
+        `  ${c.cyan(`[${group.domain}]`)} ${c.bold(`${group.entries.length}x`)}`
+      );
+      for (const entry of group.entries) {
+        const sourceType = entry.source.startsWith("failure:") ? "failure" : "learning";
+        const tag =
+          sourceType === "failure"
+            ? c.red(`[${sourceType}]`)
+            : c.yellow(`[${sourceType}]`);
+        console.log(
+          `    ${c.dim(entry.date || "unknown")} ${tag} ${entry.text.slice(0, 80)}`
+        );
+      }
+      console.log("  Files:");
+      for (const entry of group.entries) {
+        console.log(`    ${c.dim(entry.path)}`);
+      }
+      console.log("");
+    }
+  }
+
+  if (result.recommendations.length > 0) {
+    console.log(`  ${c.bold("Recommendations:")}\n`);
+    for (const rec of result.recommendations) {
+      console.log(`    ${rec}`);
+    }
+    console.log("");
+  }
+
+  if (result.candidates.length > 0) {
+    console.log(`  To crystallize: add a line to the wisdom frame file.`);
+    console.log(`  Format: ${c.green("- Your principle here [CRYSTAL: 85%]")}\n`);
+  }
+}
+
+async function run() {
+  const { values } = parseArgs({
+    args: Bun.argv.slice(2),
+    options: {
+      help: { type: "boolean", short: "h" },
+      actionable: { type: "boolean", short: "a" },
+    },
+  });
+
+  if (values.help) {
+    console.log(`
+  PAL Learning Analysis — unified graduation + ratings report
+
+  Reads all captured failures (rating ≤3) and session learnings,
+  groups recurring patterns via Dice similarity on context text,
+  and summarizes rating trends.
+
+  Sections:
+    Ratings       Overall average, low/high counts
+    Graduation    Patterns with 3+ occurrences → ready to crystallize
+    Emerging      Patterns with 2 occurrences → one more to graduate
+
+  Flags:
+    --actionable, -a  Generate actionable recommendations via Haiku inference
+
+  To crystallize a graduated pattern, add it to the target wisdom frame:
+    - Your principle here [CRYSTAL: 85%]
+
+  Usage: bun run tool:analyze [--actionable] [--help]
+`);
+    process.exit(0);
+  }
+
+  const result = await analyze({ actionable: values.actionable });
+  printReport(result);
+}
+
+if (import.meta.main) run();