pneuma-skills 1.18.8 → 2.0.0

package/README.md

@@ -24,7 +24,7 @@ When humans and code agents co-create content, they need more than a chat window
 
 **Skills** — Domain-specific knowledge and seed templates injected into the agent per mode. A presentation skill teaches layout, rhythm, and export; a document skill teaches prose and structure. Skills version and evolve with each release, and sessions persist across runs — the agent picks up where it left off.
 
-**Continuous Learning** *(v2.0)* — Skills today are static presets. The next step: mine cross-session conversation history to extract user preferences and style patterns, then dynamically augment the preset skill. During a session, the agent further adapts in real-time — learning what "good" looks like for *this* user, in *this* domain, over time.
+**Continuous Learning** — Skills aren't static presets. The Evolution Agent mines cross-session conversation history to extract user preferences and style patterns, then augments the preset skill with learned knowledge. Run `pneuma evolve <mode>` to analyze your history, review AI-generated proposals with evidence citations, and apply them to personalize your experience.
 
 **Distribution** — A complete ecosystem for sharing capabilities. Build a custom mode with AI assistance via Mode Maker, publish to the marketplace, and let anyone `pneuma mode add` it instantly.
 
@@ -36,6 +36,7 @@ When humans and code agents co-create content, they need more than a chat window
 | **slide** | HTML presentations — content sets, drag-reorder, presenter mode, PDF/image export |
 | **draw** | Excalidraw whiteboard with `.excalidraw` file editing |
 | **mode-maker** | Create custom modes with AI — fork, play-test, publish |
+| **evolve** | Evolution Agent — analyze history, propose skill improvements, apply/rollback |
 
 ## Prerequisites
 
@@ -84,6 +85,7 @@ Modes:
   slide                        Presentation editing mode (HTML slides with iframe preview)
   draw                         Excalidraw whiteboard drawing mode
   mode-maker                   Create and develop custom modes with AI
+  evolve                       Launch the Evolution Agent for skill learning
   /path/to/mode                Load mode from a local directory
   github:user/repo             Load mode from a GitHub repository
   github:user/repo#branch      Load mode from a specific branch/tag
@@ -99,6 +101,7 @@ Options:
   --dev                Force dev mode (Vite)
 
 Subcommands:
+  evolve <mode>        Analyze history and propose skill improvements
   mode add <url>       Install a remote mode to ~/.pneuma/modes/
   mode list            List published modes on the R2 registry
   mode publish         Publish the current workspace as a mode
@@ -172,7 +175,7 @@ When Claude Code edits files, chokidar detects the changes and pushes updated co
 | **ViewerContract** | Preview component, context extraction, file workspace model, agent-callable actions | Custom renderers, viewport tracking, action protocols |
 | **AgentBackend** | Launch, resume, kill, capability declaration | Other agents (Codex, Aider) |
 
-Contracts are defined in `core/types/` with 274 tests across 17 test files.
+Contracts are defined in `core/types/` with 316 tests across 20 test files.
 
 ## Project Structure
 
@@ -193,7 +196,8 @@ pneuma-skills/
 │   ├── doc/                   # Doc Mode — markdown editing
 │   ├── slide/                 # Slide Mode — presentation editing
 │   ├── draw/                  # Draw Mode — Excalidraw whiteboard
-│   └── mode-maker/            # Mode Maker — create custom modes with AI
+│   ├── mode-maker/            # Mode Maker — create custom modes with AI
+│   └── evolve/                # Evolve Mode — evolution agent dashboard
 │       ├── manifest.ts        # Mode manifest (fork, play, publish workflow)
 │       ├── seed/              # Template files for new modes
 │       ├── skill/             # Skill prompt for mode development
@@ -212,7 +216,10 @@ pneuma-skills/
 │   ├── terminal-manager.ts    # PTY terminal sessions
 │   ├── path-resolver.ts       # Binary PATH resolution (cross-platform)
 │   ├── system-bridge.ts       # OS-level operations (open, reveal, openUrl)
-│   └── mode-maker-routes.ts   # Mode Maker API routes (fork, play, publish, reset)
+│   ├── mode-maker-routes.ts   # Mode Maker API routes (fork, play, publish, reset)
+│   ├── evolution-agent.ts     # Evolution Agent launcher (spawns CC with analysis tools)
+│   ├── evolution-proposal.ts  # Proposal CRUD + apply/rollback + CLAUDE.md sync
+│   └── evolution-routes.ts    # Evolution API routes (/api/evolve/*)
 ├── src/
 │   ├── App.tsx                # Root layout (dynamic viewer from store)
 │   ├── store.ts               # Zustand state (session, messages, viewer)
@@ -276,6 +283,8 @@ pneuma-skills/
 - **Image upload** — Drag & drop or paste images into chat
 - **Viewer context enrichment** — `<viewer-context>` XML blocks align agent perception with user viewport
 - **Viewer action protocol** — Agent can invoke viewer capabilities (navigate, toggle UI, capture)
+- **Evolution Agent** — `pneuma evolve <mode>` analyzes conversation history, proposes skill improvements with evidence
+- **Proposal lifecycle** — Review, apply, rollback, discard, or fork proposals into custom modes
 - **Windows compatibility** — Cross-platform PATH resolution, terminal, browser opening, process management
 - **Debug mode** — `--debug` flag shows enriched CLI payloads for each message
 
@@ -298,13 +307,10 @@ pneuma-skills/
 - [x] Launcher process management — Monitor and kill child processes
 - [x] Next-gen visual redesign — Ethereal Tech aesthetic (glassmorphism, cinematic dark UI)
 - [x] Export & image capture — Slide export via `@zumer/snapdom`
+- [x] Evolution Agent — AI-native continuous skill learning (`pneuma evolve <mode>`)
+- [x] Skill effectiveness optimization — standardized claudeMdSection + YAML frontmatter for native skill discovery
 - [ ] Additional agent backends — Codex CLI, custom agents
-
-### v2.0 — Continuous Learning
-
-- [ ] Cross-session preference extraction — mine conversation history to discover user style, tone, and layout preferences
-- [ ] Dynamic skill augmentation — automatically append learned preferences to preset skills at session start
-- [ ] In-session adaptation — agent refines its approach in real-time based on user feedback patterns
+- [ ] In-session adaptation — agent refines its approach in real-time based on feedback within a session
 
 ## Acknowledgements
 

package/bin/pneuma.ts

@@ -276,8 +276,308 @@ function checkClaudeCode() {
   }
 }
 
+async function handleEvolveCommand(args: string[]) {
+  let workspace = process.cwd();
+  let modeName = "";
+  let subAction = ""; // "apply", "rollback", "show", or "" (propose)
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--workspace" && i + 1 < args.length) {
+      workspace = resolve(args[++i]);
+    } else if (arg === "--mode" && i + 1 < args.length) {
+      modeName = args[++i];
+    } else if (["apply", "rollback", "show", "list"].includes(arg)) {
+      subAction = arg;
+    }
+  }
+
+  workspace = resolve(workspace);
+
+  const {
+    loadProposal, loadLatestProposal, listProposals,
+    applyProposal, rollbackProposal, formatProposalForDisplay,
+  } = await import("../server/evolution-proposal.js");
+
+  if (subAction === "list") {
+    const proposals = listProposals(workspace);
+    if (proposals.length === 0) {
+      p.log.info("No evolution proposals found.");
+    } else {
+      p.log.info(`${proposals.length} proposal(s):`);
+      for (const prop of proposals) {
+        const changesCount = prop.changes.length;
+        p.log.message(`  ${prop.id}  [${prop.status}]  ${prop.mode}  ${changesCount} change(s)  ${prop.createdAt}`);
+      }
+    }
+    return;
+  }
+
+  if (subAction === "show") {
+    const proposal = loadLatestProposal(workspace);
+    if (!proposal) {
+      p.log.error("No proposals found. Run `pneuma evolve` first.");
+      process.exit(1);
+    }
+    console.log(formatProposalForDisplay(proposal));
+    return;
+  }
+
+  if (subAction === "apply") {
+    const proposal = loadLatestProposal(workspace);
+    if (!proposal) {
+      p.log.error("No proposals found. Run `pneuma evolve` first.");
+      process.exit(1);
+    }
+    if (proposal.status !== "pending") {
+      p.log.error(`Proposal ${proposal.id} is already ${proposal.status}.`);
+      process.exit(1);
+    }
+
+    console.log(formatProposalForDisplay(proposal));
+    console.log("");
+
+    const confirm = await p.confirm({ message: "Apply this proposal?" });
+    if (p.isCancel(confirm) || !confirm) {
+      p.log.info("Cancelled.");
+      return;
+    }
+
+    const result = applyProposal(workspace, proposal.id);
+    if (result.success) {
+      p.log.success(`Applied ${result.appliedFiles.length} file(s). Use \`pneuma evolve rollback\` to revert.`);
+      for (const f of result.appliedFiles) {
+        p.log.step(`  ✓ ${f}`);
+      }
+    } else {
+      p.log.error(`Apply failed: ${result.error}`);
+    }
+    return;
+  }
+
+  if (subAction === "rollback") {
+    const proposals = listProposals(workspace);
+    const applied = proposals.find(p => p.status === "applied");
+    if (!applied) {
+      p.log.error("No applied proposals to rollback.");
+      process.exit(1);
+    }
+
+    const confirm = await p.confirm({ message: `Rollback proposal ${applied.id}?` });
+    if (p.isCancel(confirm) || !confirm) {
+      p.log.info("Cancelled.");
+      return;
+    }
+
+    const result = rollbackProposal(workspace, applied.id);
+    if (result.success) {
+      p.log.success(`Rolled back ${result.restoredFiles.length} file(s).`);
+      for (const f of result.restoredFiles) {
+        p.log.step(`  ✓ ${f}`);
+      }
+    } else {
+      p.log.error(`Rollback failed: ${result.error}`);
+    }
+    return;
+  }
+
+  // Default: launch evolution agent as a standard pneuma session
+  let port = 0;
+  let noOpen = false;
+  let noPrompt = false;
+  let debug = false;
+  let forceDev = false;
+
+  // Re-parse flags from the evolve subcommand args
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--port" && i + 1 < args.length) {
+      port = Number(args[++i]);
+    } else if (arg === "--no-open") {
+      noOpen = true;
+    } else if (arg === "--no-prompt") {
+      noPrompt = true;
+    } else if (arg === "--debug") {
+      debug = true;
+    } else if (arg === "--dev") {
+      forceDev = true;
+    }
+  }
+
+  // Resolve target mode from --mode flag or existing session
+  if (!modeName) {
+    const session = loadSession(workspace);
+    if (session?.mode) {
+      modeName = session.mode;
+    } else {
+      // Check if targetMode was passed via config (from Launcher)
+      const configPath = join(workspace, ".pneuma", "config.json");
+      try {
+        const config = JSON.parse(readFileSync(configPath, "utf-8"));
+        if (config.targetMode) modeName = config.targetMode;
+      } catch {}
+    }
+    if (!modeName) {
+      p.cancel("No mode specified and no .pneuma/session.json found.\nUse: pneuma evolve --mode <mode> --workspace <path>");
+      process.exit(1);
+    }
+  }
+
+  checkClaudeCode();
+
+  // 1. Resolve target mode and build evolution data
+  let resolved: ResolvedMode;
+  try {
+    resolved = await resolveModeSource(modeName, PROJECT_ROOT);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    p.cancel(`Failed to resolve mode "${modeName}": ${msg}`);
+    process.exit(1);
+  }
+
+  if (resolved.type !== "builtin") {
+    registerExternalMode(resolved.name, resolved.path);
+  }
+
+  let manifest: ModeManifest;
+  try {
+    manifest = await loadModeManifest(resolved.name);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    p.cancel(`Failed to load mode "${resolved.name}": ${msg}`);
+    process.exit(1);
+  }
+
+  p.log.step(`Evolving skill for ${manifest.displayName} mode...`);
+  p.log.info(`Workspace: ${workspace}`);
+
+  // 2. Build evolution prompt + metadata, save metadata as initParams
+  const { buildEvolutionPrompt, buildEvolutionMetadata } = await import("../server/evolution-agent.js");
+  const evolutionPrompt = buildEvolutionPrompt({ workspace, manifest });
+  const metadata = buildEvolutionMetadata({ workspace, manifest });
+
+  // Save metadata to .pneuma/config.json so the viewer dashboard can read it
+  const pneumaDir = join(workspace, ".pneuma");
+  mkdirSync(pneumaDir, { recursive: true });
+  writeFileSync(join(pneumaDir, "config.json"), JSON.stringify(metadata, null, 2));
+
+  // 3. Install evolve skill (so agent has dashboard context in SKILL.md)
+  const evolveManifest = await loadModeManifest("evolve");
+  const evolveModeSourceDir = join(PROJECT_ROOT, "modes", "evolve");
+  installSkill(workspace, evolveManifest.skill, evolveModeSourceDir, {}, evolveManifest.viewerApi);
+
+  // 4. Determine dev vs production mode
+  const distDir = resolve(PROJECT_ROOT, "dist");
+  const isDev = forceDev || !existsSync(join(distDir, "index.html"));
+  const effectivePort = port || (isDev ? 17007 : 17996);
+
+  // 5. Start server with evolution routes
+  const { server, wsBridge, port: actualPort } = startServer({
+    port: effectivePort,
+    workspace,
+    watchPatterns: [],
+    ...(isDev ? {} : { distDir }),
+    modeName: "evolve",
+    projectRoot: PROJECT_ROOT,
+    debug,
+    forceDev: isDev,
+    initParams: metadata as unknown as Record<string, string | number>,
+  });
+
+  // 6. Launch agent via ClaudeCodeBackend (fresh session, bypassPermissions)
+  const backend = new ClaudeCodeBackend(actualPort);
+  const session = backend.launch({
+    cwd: workspace,
+    permissionMode: "bypassPermissions",
+  });
+
+  p.log.info(`Agent session: ${session.sessionId}`);
+
+  // 7. Inject evolution prompt as greeting (dynamic, not from manifest)
+  wsBridge.injectGreeting(session.sessionId, evolutionPrompt);
+  console.log("[pneuma] Sent evolution prompt to agent");
+
+  // 8. Start Vite (dev) or serve dist (prod), open browser
+  let viteProc: ReturnType<typeof Bun.spawn> | null = null;
+  let browserPort = actualPort;
+
+  if (isDev) {
+    const VITE_PORT = 17996;
+    p.log.step(`Starting Vite dev server on port ${VITE_PORT}...`);
+
+    const viteEnv: Record<string, string> = {
+      ...process.env as Record<string, string>,
+      VITE_API_PORT: String(actualPort),
+    };
+
+    viteProc = Bun.spawn(
+      ["bunx", "vite", "--port", String(VITE_PORT)],
+      { cwd: PROJECT_ROOT, stdout: "pipe", stderr: "pipe", env: viteEnv },
+    );
+
+    let vitePortResolved = false;
+    browserPort = await new Promise<number>((resolvePort) => {
+      const timeout = setTimeout(() => {
+        if (!vitePortResolved) { vitePortResolved = true; resolvePort(VITE_PORT); }
+      }, 10_000);
+
+      const pipeAndParse = async (stream: ReadableStream<Uint8Array>) => {
+        const reader = stream.getReader();
+        const decoder = new TextDecoder();
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          const text = decoder.decode(value, { stream: true });
+          for (const line of text.split("\n")) {
+            if (line.trim()) console.log(`[vite] ${line}`);
+            if (!vitePortResolved) {
+              const match = line.match(/Local:\s+https?:\/\/[^:]+:(\d+)/);
+              if (match) {
+                vitePortResolved = true;
+                clearTimeout(timeout);
+                resolvePort(parseInt(match[1], 10));
+              }
+            }
+          }
+        }
+      };
+      if (viteProc!.stdout && typeof viteProc!.stdout !== "number") pipeAndParse(viteProc!.stdout);
+      if (viteProc!.stderr && typeof viteProc!.stderr !== "number") pipeAndParse(viteProc!.stderr);
+    });
+  }
+
+  // 9. Open browser with evolution mode dashboard
+  const debugParam = debug ? "&debug=1" : "";
+  const browserUrl = `http://localhost:${browserPort}?session=${session.sessionId}&mode=evolve${debugParam}`;
+  console.log(`[pneuma] ready ${browserUrl}`);
+
+  if (!noOpen) {
+    p.log.success(`Ready → ${browserUrl}`);
+    try {
+      if (process.platform === "win32") {
+        Bun.spawn(["cmd", "/c", "start", "", browserUrl], { stdout: "ignore", stderr: "ignore" });
+      } else {
+        const opener = process.platform === "darwin" ? "open" : "xdg-open";
+        Bun.spawn([opener, browserUrl], { stdout: "ignore", stderr: "ignore" });
+      }
+    } catch {
+      p.log.warn(`Could not open browser. Visit: ${browserUrl}`);
+    }
+  }
+
+  // 10. Graceful shutdown
+  const shutdown = async () => {
+    viteProc?.kill();
+    await backend.killAll();
+    server.stop(true);
+    p.outro("Goodbye!");
+    process.exit(0);
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
 async function main() {
-  // Read version from package.json
   const pkgPath = join(PROJECT_ROOT, "package.json");
   const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
 
@@ -352,6 +652,16 @@ async function main() {
     // Unknown mode subcommand — fall through to normal mode resolution
   }
 
+  // Evolve subcommand — AI-native skill evolution
+  // Find "evolve" in rawArgs (may be preceded by flags like --dev)
+  const evolveIdx = rawArgs.findIndex(a => a === "evolve");
+  if (evolveIdx !== -1) {
+    // Pass all args except "evolve" itself to the handler
+    const evolveArgs = [...rawArgs.slice(0, evolveIdx), ...rawArgs.slice(evolveIdx + 1)];
+    await handleEvolveCommand(evolveArgs);
+    return;
+  }
+
   const { mode, workspace, port, noOpen, debug, forceDev, noPrompt, skipSkill } = parseArgs(process.argv);
 
   // Launcher mode — no mode arg → start marketplace UI

package/core/mode-loader.ts

@@ -61,6 +61,13 @@ const builtinModes: Record<string, ModeSource> = {
     definitionLoader: () =>
       import("../modes/mode-maker/pneuma-mode.js").then((m) => m.default),
   },
+  evolve: {
+    type: "builtin",
+    manifestLoader: () =>
+      import("../modes/evolve/manifest.js").then((m) => m.default),
+    definitionLoader: () =>
+      import("../modes/evolve/pneuma-mode.js").then((m) => m.default),
+  },
 };
 
 /** 外部 mode 注册表 — 由 CLI 在启动时通过 registerExternalMode 注册 */

package/core/types/index.ts

@@ -14,6 +14,8 @@ export type {
   AgentPreferences,
   InitConfig,
   ViewerApiConfig,
+  EvolutionConfig,
+  EvolutionTool,
 } from "./mode-manifest.js";
 
 export type {

package/core/types/mode-manifest.ts

@@ -159,6 +159,47 @@ export interface ViewerApiConfig {
   };
 }
 
+/**
+ * Skill 演进配置 — 定义 Evolution Agent 的目标方向和可用工具。
+ *
+ * Evolution Agent 是一个独立的 Agent 过程，分析用户历史并增强 skill 文件。
+ * 它输出一个 proposal（附带证据和引用），用户审核后可 apply 或取消。
+ */
+export interface EvolutionConfig {
+  /**
+   * 演进方向 — 给 Evolution Agent 的目标描述。
+   * 告诉 Agent 这个 Mode 的 skill 应该朝什么方向个性化。
+   *
+   * @example
+   * "Learn the user's presentation style preferences: typography choices,
+   *  color palette tendencies, layout density, slide structure patterns.
+   *  Augment the skill to guide the main agent toward these preferences
+   *  as defaults while respecting explicit user instructions."
+   */
+  directive: string;
+
+  /**
+   * 额外的数据获取工具（预留，第一版不实现）。
+   * 框架已内置基础工具（读取 CC 历史等），这里声明 Mode 特有的。
+   */
+  tools?: EvolutionTool[];
+}
+
+/**
+ * Evolution Agent 可用的外部数据获取工具（预留）。
+ * 第一版不实现，框架内置工具足够。
+ */
+export interface EvolutionTool {
+  /** 工具名称 */
+  name: string;
+  /** 工具描述（给 Agent 看的） */
+  description: string;
+  /** 实现方式 */
+  type: "command" | "http" | "mcp";
+  /** 具体配置 */
+  config: Record<string, unknown>;
+}
+
 /** Mode 的完整声明式描述 */
 export interface ModeManifest {
   /** Mode 唯一标识 (e.g. "doc", "slide") */
@@ -182,4 +223,6 @@ export interface ModeManifest {
   init?: InitConfig;
   /** Viewer 自描述 API — 纯数据声明，后端可读，自动注入 CLAUDE.md */
   viewerApi?: ViewerApiConfig;
+  /** Skill 演进配置 — 定义 Evolution Agent 的演进方向 (可选) */
+  evolution?: EvolutionConfig;
 }