@topce/pizx 0.3.0 → 0.5.0

package/README.md

@@ -2,6 +2,8 @@
 
 [![GitHub Sponsors](https://img.shields.io/github/sponsors/topce?style=social&logo=github)](https://github.com/sponsors/topce)
 
+![pizx — zx fork with native Pi AI integration](github-social-banner.png)
+
 > **zx fork with native Pi AI integration** — 15 template tags for shell scripting, AI text generation, coding agents, agentic patterns, communication, and orchestration topologies.
 
 ## Quick Start
@@ -46,7 +48,7 @@ npm install @topce/pizx
 
 **Prerequisites:**
 - Node.js >= 22.19.0
-- [Pi AI](https://github.com/earendil-works/pi-ai) installed and configured (`pi auth login`)
+- [Pi AI](https://github.com/earendil-works/pi) installed and configured (`pi auth login`)
 - Shell commands from [zx](https://github.com/google/zx) (`$`, `cd`, `echo`, `fetch`, etc.)
 
 ## Writing Scripts
@@ -66,16 +68,25 @@ echo(intro)
 ```js
 import { $, π, Π, Ρ, Φ, Σ } from '@topce/pizx'
 
+// Greek letters work everywhere...
 const output = await $`ls src/ | grep '.ts'`
 console.log(output.stdout)
 
 const review = await π`review this code for issues:\n${output.stdout}`
 console.log(review.text)
 
-// Use the coding agent to fix issues
-await Π`fix the TypeScript errors in src/`
+// ...and so do English word aliases:
+import { pi, Pi, ralph, fleet, subagent } from '@topce/pizx'
+
+const answer = await pi`explain async/await`
+await Pi`fix the TypeScript errors in src/`
+await fleet`review all files in src/`
 ```
 
+> **English word aliases**: Every Greek letter tag has an English alternative.
+> `pi` (alias for `π`), `Pi` (alias for `Π`), `fleet` (alias for `Φ`), `ralph` (alias for `Ρ`),
+> `pipeline` (alias for `Λ`), etc. — use whichever style you prefer. See [full mapping](#english-aliases) below.
+
 ### CLI Quick Queries
 
 ```bash
@@ -126,6 +137,24 @@ Each tag has detailed documentation in [`docs/`](docs/):
 | `Χ` | Chi | Analyze traces → extract patterns | [docs/chi.md](docs/chi.md) |
 | `Τ` | Tau | Define schema → write → refine → consolidate | [docs/tau.md](docs/tau.md) |
 
+### English Aliases
+
+Every Greek letter tag has an equivalent English word. They're interchangeable — use whichever style you prefer.
+
+| Greek | English | Greek | English |
+|-------|---------|-------|---------|
+| `π` | `pi` | `Π` | `Pi` |
+| `Ρ` | `ralph` | `Φ` | `fleet` |
+| `Σ` | `subagent` | `Δ` | `debate` |
+| `Λ` | `pipeline` | `Ψ` | `critique` |
+| `Ω` | `orchestrator` | `Ν` | `team` |
+| `Θ` | `thread` | `Μ` | `memory` |
+| `Β` | `broadcast` | `Α` | `adaptive` |
+| `Γ` | `graph` | `Χ` | `learn` |
+| `Τ` | `store` | | |
+
+See [`english-examples/`](english-examples/) for runnable examples using all English aliases.
+
 ## Architecture
 
 See [docs/decisions/](docs/decisions/) for Architecture Decision Records covering the key design choices:
@@ -289,6 +318,57 @@ configurePi({ model: 'anthropic/claude-sonnet-4-5', maxTokens: 8000, timeoutMs:
 configureAgent({ maxTurns: 5, excludeTools: ['write'] })
 ```
 
+### System Prompt Overrides
+
+All tags accept `system` (replaces default) and `appendSystemPrompt` (appended after system).
+
+```js
+// π: custom system prompt
+await π({ system: 'You are a security auditor' })`review this code`
+
+// Π: set system prompt and append extra instructions
+await Π({ system: 'You are a test engineer', appendSystemPrompt: 'Write tests first' })`add tests for auth`
+
+// Patterns: inject system context via mergeSystem
+await Ω({ system: 'Prioritize security over performance' })`design login flow`
+```
+
+### Thinking Budgets
+
+Fine-grained token budgets per reasoning level. Passes through to providers via `thinkingBudgets`.
+
+```js
+// Per-call
+await π({ thinkingBudgets: { medium: 16384, high: 65536 } })`analyze`
+
+// Global default
+configurePi({ thinkingBudgets: { medium: 20480, high: 131072 } })
+
+// Patterns support it too
+await Ω({ thinkingBudgets: { high: 65536 } })`deep analysis task`
+```
+
+### Skill Integration
+
+Load Pi agent skills from disk and inject them as system context. Skills are discovered from the same paths as `skill.sh`: `.pi/skills`, `.agents/skills`, `~/.pi/agent/skills`, etc.
+
+```js
+import { loadSkillContent, loadSkillContents } from '@topce/pizx'
+
+// Load a single skill
+const codeStyle = await loadSkillContent('code-simplification')
+if (codeStyle) {
+  await π({ system: codeStyle })`refactor auth.ts`
+}
+
+// Load multiple skills
+const skills = await loadSkillContents(['test-driven-development', 'spec-driven-development'])
+
+// Π and all patterns accept skills option
+await Π({ skills: ['code-simplification'] })`clean up this file`
+await Ω({ skills: ['spec-driven-development', 'incremental-implementation'] })`build the feature`
+```
+
 ## CLI Reference
 
 ```bash
@@ -344,3 +424,10 @@ See [`examples/`](examples/) for runnable examples of every pattern and feature:
 ## License
 
 MIT
+
+## Credits
+
+Built on the shoulders of two outstanding tools:
+
+- [**zx**](https://github.com/google/zx) by [Anton Medvedev](https://github.com/antonmedv) — the original shell scripting tool for Node.js that popularized template-tag ergonomics for command execution. pizx preserves every zx API (`$`, `cd`, `echo`, `fetch`, `chalk`, etc.) unchanged.
+- [**Pi**](https://github.com/earendil-works/pi) by Mario Zechner / Earendil Works — the unified LLM API and coding agent harness that powers all `π`, `Π`, and pattern tags through `@earendil-works/pi-ai` and `@earendil-works/pi-coding-agent`.

package/dist/cli.js

@@ -179,6 +179,37 @@ function pickModel(preferred) {
   return models[0];
 }
 
+// src/skill-loader.ts
+import { readFile } from "node:fs/promises";
+import { homedir as homedir3 } from "node:os";
+import { join as join3 } from "node:path";
+var SKILL_PATHS = [
+  ".pi/skills",
+  ".agents/skills",
+  "skills",
+  join3(homedir3(), ".pi", "agent", "skills"),
+  join3(homedir3(), ".codewhale", "skills"),
+  join3(homedir3(), ".claude", "skills")
+];
+async function loadSkillContent(name) {
+  for (const base of SKILL_PATHS) {
+    const candidate = join3(base, name, "SKILL.md");
+    try {
+      return await readFile(candidate, "utf-8");
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function loadSkillContents(names) {
+  const map = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const content = await loadSkillContent(name);
+    if (content) map.set(name, content);
+  }
+  return map;
+}
+
 // src/patterns/types.ts
 var PatternOutput = class {
   constructor(text, startTime = Date.now(), endTime = Date.now()) {
@@ -309,18 +340,35 @@ async function confirmPhase(description, opts) {
 async function ask(prompt, opts = {}) {
   const model = pickModel(opts.model);
   if (!model) throw new Error("pizx/patterns: No AI models configured. Run `pi auth login` first.");
+  let systemPrompt = opts.system;
+  if (opts.skills && opts.skills.length > 0) {
+    const skillMap = await loadSkillContents(opts.skills);
+    if (skillMap.size > 0) {
+      const skillBlocks = [];
+      for (const [name, content] of skillMap) {
+        skillBlocks.push(`Skill context (${name}):
+${content}`);
+      }
+      const skillContext = skillBlocks.join("\n\n");
+      systemPrompt = systemPrompt ? `${systemPrompt}
+
+${skillContext}` : skillContext;
+    }
+  }
   const t0 = Date.now();
   const result = await completeSimple(
     model,
     {
-      systemPrompt: opts.system,
+      systemPrompt,
       messages: [{ role: "user", content: prompt, timestamp: Date.now() }]
     },
     {
       maxTokens: opts.maxTokens ?? 4096,
       reasoning: opts.thinkingLevel ?? "medium",
+      thinkingBudgets: opts.thinkingBudgets,
       timeoutMs: opts.timeoutMs,
-      maxRetries: opts.maxRetries
+      maxRetries: opts.maxRetries,
+      apiKey: opts.apiKey
     }
   );
   const durationMs = Date.now() - t0;
@@ -857,9 +905,9 @@ var defaults4 = {
   rounds: 1
 };
 var CritiqueRound = class {
-  constructor(content, critique, round) {
+  constructor(content, critique2, round) {
     this.content = content;
-    this.critique = critique;
+    this.critique = critique2;
     this.round = round;
   }
   content;
@@ -923,12 +971,12 @@ Revise the content based on the critique.`,
     }
     if (!opts.quiet) process.stderr.write(`  \u2192 Critiquing (round ${r + 1})...
 `);
-    const critique = await ask(currentContent, {
+    const critique2 = await ask(currentContent, {
       ...opts,
       model: plannerModel,
       system: mergeSystem(opts.system, CRITIQUE_SYSTEM)
     });
-    critiqueRounds.push(new CritiqueRound(currentContent, critique, r));
+    critiqueRounds.push(new CritiqueRound(currentContent, critique2, r));
   }
   const t1 = Date.now();
   const finalContent = currentContent;
@@ -2414,21 +2462,21 @@ ${prompt}`, {
   }
   return { keys, roles: roles.slice(0, agentCount), assignments };
 }
-function formatStore(store) {
-  const entries = Object.entries(store).filter(([, v]) => v);
+function formatStore(store2) {
+  const entries = Object.entries(store2).filter(([, v]) => v);
   if (entries.length === 0) return "(empty \u2014 you are the first contributor)";
   return entries.map(([k, v]) => `[${k}]: ${v}`).join("\n\n");
 }
-function mergeEntry(store, key, content) {
-  if (store[key]) {
-    store[key] += `
+function mergeEntry(store2, key, content) {
+  if (store2[key]) {
+    store2[key] += `
 
 ${content}`;
   } else {
-    store[key] = content;
+    store2[key] = content;
   }
 }
-async function executeRound(roles, assignments, store, round, opts) {
+async function executeRound(roles, assignments, store2, round, opts) {
   const workerModel = opts.workerModel ?? opts.model;
   const isWrite = round === 1;
   const operation = isWrite ? "write" : "update";
@@ -2436,7 +2484,7 @@ async function executeRound(roles, assignments, store, round, opts) {
     roles.map(async (role) => {
       const assignedKeys = assignments.get(role) ?? ["General"];
       const keysStr = assignedKeys.join(", ");
-      const storeText = formatStore(store);
+      const storeText = formatStore(store2);
       const systemPrompt = isWrite ? WRITE_SYSTEM(role, keysStr).replace("{store}", storeText) : UPDATE_SYSTEM(role, keysStr).replace("{store}", storeText);
       const task = isWrite ? `Write your initial findings to your assigned keys: ${keysStr}` : `Review the shared context and update your entries for keys: ${keysStr}`;
       const response = await ask(task, {
@@ -2448,7 +2496,7 @@ async function executeRound(roles, assignments, store, round, opts) {
     })
   );
   const entries = [];
-  const newStore = { ...store };
+  const newStore = { ...store2 };
   for (const r of roundResults) {
     if (r.status !== "fulfilled") continue;
     const { role, response } = r.value;
@@ -2471,8 +2519,8 @@ async function executeRound(roles, assignments, store, round, opts) {
   }
   return { entries, store: newStore };
 }
-async function consolidateStore(task, store, opts) {
-  const storeText = formatStore(store);
+async function consolidateStore(task, store2, opts) {
+  const storeText = formatStore(store2);
   return ask(
     `Original task: ${task}
 
@@ -2513,7 +2561,7 @@ async function execute14(pieces, args, opts) {
     }
   }
   const allEntries = [];
-  let store = {};
+  let store2 = {};
   for (let round = 1; round <= totalRounds; round++) {
     const label = round === 1 ? "Writing" : "Updating";
     if (!opts.quiet) process.stderr.write(`  \u2192 Round ${round}/${totalRounds}: ${label}...
@@ -2521,15 +2569,15 @@ async function execute14(pieces, args, opts) {
     const { entries, store: updatedStore } = await executeRound(
       roles,
       assignments,
-      store,
+      store2,
       round,
       opts
     );
     allEntries.push(...entries);
-    store = updatedStore;
+    store2 = updatedStore;
   }
   if (!opts.quiet) process.stderr.write("  \u2192 Consolidating store...\n");
-  const synthesis = await consolidateStore(task, store, { ...opts, plannerModel });
+  const synthesis = await consolidateStore(task, store2, { ...opts, plannerModel });
   if (!opts.quiet && opts.qualityCheck) process.stderr.write("  \u2192 Quality review...\n");
   const qualityReview = await runQualityReview(task, synthesis, opts);
   const t1 = Date.now();
@@ -2540,7 +2588,7 @@ async function execute14(pieces, args, opts) {
     `Entries: ${allEntries.length}`,
     `Synthesis: ${synthesis}`
   ].join("\n\n");
-  return new TauOutput(summary, allEntries, store, synthesis, t0, t1, qualityReview);
+  return new TauOutput(summary, allEntries, store2, synthesis, t0, t1, qualityReview);
 }
 var \u03A4 = createPatternTag(defaults14, execute14);
 
@@ -2581,10 +2629,10 @@ The conversation so far:
 Respond as your role. Be specific, build on or challenge what others have said.
 Keep your response under 200 words.`;
 var SYNTHESIS_SYSTEM6 = `You are a neutral facilitator. Synthesize the multi-agent conversation thread into a clear, actionable conclusion. Weigh the evidence, resolve conflicts, and present the best path forward.`;
-function buildThreadPrompt(role, thread) {
+function buildThreadPrompt(role, thread2) {
   return THREAD_PROMPT.replace("{role}", role).replace(
     "{thread}",
-    thread || "(This is the first message in the thread.)"
+    thread2 || "(This is the first message in the thread.)"
   );
 }
 async function execute15(pieces, args, opts) {
@@ -2602,17 +2650,17 @@ async function execute15(pieces, args, opts) {
 `);
   }
   const messages = [];
-  let thread = `Topic: ${topic}
+  let thread2 = `Topic: ${topic}
 `;
   for (let turn = 1; turn <= maxTurns; turn++) {
     if (!opts.quiet) process.stderr.write(`  \u2192 Turn ${turn}/${maxTurns}
 `);
     for (let a = 0; a < roles.length; a++) {
       const role = roles[a] ?? `Agent ${a + 1}`;
-      const prompt = buildThreadPrompt(role, thread);
+      const prompt = buildThreadPrompt(role, thread2);
       const response = await ask(prompt, { ...opts, model: workerModel });
       messages.push(new ThreadMessage(role, turn, response));
-      thread += `
+      thread2 += `
 [${role}] (Turn ${turn}): ${response}
 `;
     }
@@ -2622,7 +2670,7 @@ async function execute15(pieces, args, opts) {
     `Topic: ${topic}
 
 Conversation thread:
-${thread}
+${thread2}
 
 Synthesize a clear, actionable conclusion.`,
     {
@@ -2642,6 +2690,23 @@ Synthesize a clear, actionable conclusion.`,
 }
 var \u0398 = createPatternTag(defaults15, execute15);
 
+// src/patterns/index.ts
+var ralph = \u03A1;
+var fleet = \u03A6;
+var subagent = \u03A3;
+var debate = \u0394;
+var pipeline = \u039B;
+var critique = \u03A8;
+var orchestrator = \u03A9;
+var thread = \u0398;
+var memory = \u039C;
+var broadcast = \u0392;
+var adaptive = \u0391;
+var graph = \u0393;
+var team = \u039D;
+var learn = \u03A7;
+var store = \u03A4;
+
 // src/pi.ts
 import {
   streamSimple
@@ -2709,8 +2774,11 @@ var defaults16 = {
   maxTokens: 4096
 };
 function makeContext(pieces, args, opts) {
+  const systemParts = [];
+  if (opts.system) systemParts.push(opts.system);
+  if (opts.appendSystemPrompt) systemParts.push(opts.appendSystemPrompt);
   return {
-    systemPrompt: opts.system,
+    systemPrompt: systemParts.length > 0 ? systemParts.join("\n\n") : void 0,
     messages: [
       {
         role: "user",
@@ -2724,8 +2792,10 @@ function makeOpts(opts) {
   return {
     maxTokens: opts.maxTokens,
     reasoning: opts.thinkingLevel,
+    thinkingBudgets: opts.thinkingBudgets,
     timeoutMs: opts.timeoutMs,
-    maxRetries: opts.maxRetries
+    maxRetries: opts.maxRetries,
+    apiKey: opts.apiKey
   };
 }
 async function run(pieces, args, opts) {
@@ -2810,7 +2880,10 @@ function makePi(opts = {}) {
 var \u03C0 = makePi();
 
 // src/pi-agent.ts
-import { createAgentSession as createAgentSession2 } from "@earendil-works/pi-coding-agent";
+import {
+  createAgentSession as createAgentSession2,
+  DefaultResourceLoader
+} from "@earendil-works/pi-coding-agent";
 var _agentDefaults = {
   quiet: false,
   maxTurns: 10
@@ -2842,14 +2915,43 @@ var AgentOutput = class {
 var AgentPromise = class extends Promise {
 };
 var _sharedSession = null;
+function createLoader(opts) {
+  const hasSystem = opts.system !== void 0;
+  const hasAppend = opts.appendSystemPrompt !== void 0;
+  const hasSkills = opts.skills && opts.skills.length > 0;
+  if (!hasSystem && !hasAppend && !hasSkills) return void 0;
+  return new DefaultResourceLoader({
+    cwd: opts.cwd ?? process.cwd(),
+    agentDir: "",
+    systemPrompt: opts.system,
+    appendSystemPrompt: opts.appendSystemPrompt ? [opts.appendSystemPrompt] : void 0
+  });
+}
 async function getSession(opts) {
   if (_sharedSession && !opts.model) return _sharedSession;
   try {
+    const loader = createLoader(opts);
+    if (opts.skills && opts.skills.length > 0 && loader) {
+      const skillMap = await loadSkillContents(opts.skills);
+      const skillPaths = [];
+      for (const [name] of skillMap) {
+        for (const base of SKILL_PATHS) {
+          skillPaths.push({
+            path: `${base}/${name}`,
+            metadata: { source: "pizx", scope: "project", origin: "top-level" }
+          });
+        }
+      }
+      if (skillPaths.length > 0) {
+        loader.extendResources({ skillPaths });
+      }
+    }
     const result = await createAgentSession2({
       cwd: opts.cwd,
       thinkingLevel: opts.thinkingLevel,
       tools: opts.tools,
-      excludeTools: opts.excludeTools
+      excludeTools: opts.excludeTools,
+      resourceLoader: loader
     });
     _sharedSession = result.session;
     return _sharedSession;
@@ -3064,6 +3166,23 @@ async function runScriptMode(scriptPath) {
   g.\u0392 = \u0392;
   g.\u0391 = \u0391;
   g.\u0393 = \u0393;
+  g.pi = \u03C0;
+  g.Pi = \u03A0;
+  g.ralph = ralph;
+  g.fleet = fleet;
+  g.subagent = subagent;
+  g.debate = debate;
+  g.pipeline = pipeline;
+  g.critique = critique;
+  g.orchestrator = orchestrator;
+  g.thread = thread;
+  g.memory = memory;
+  g.broadcast = broadcast;
+  g.adaptive = adaptive;
+  g.graph = graph;
+  g.team = team;
+  g.learn = learn;
+  g.store = store;
   const { createRequire: createRequire2 } = await import("node:module");
   const __filename = absPath;
   const __dirname = path.dirname(absPath);