@matyah00/openpi 0.1.4 → 0.2.0

package/package.json

@@ -1,15 +1,19 @@
 {
   "name": "@matyah00/openpi",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "type": "module",
-  "description": "Pi-native commands, skills, agents, and workflows.",
+  "description": "Comprehensive, high-performance, and safety-hardened Pi-native multi-agent orchestration package, featuring advanced workflows, damage-control rules, and developer tooling.",
   "keywords": [
     "pi-package",
     "pi-coding-agent",
     "commands",
     "skills",
     "agents",
-    "workflows"
+    "workflows",
+    "orchestration",
+    "safety",
+    "multi-agent",
+    "damage-control"
   ],
   "homepage": "https://github.com/haytamAroui/OpenPi#readme",
   "repository": {
@@ -24,6 +28,7 @@
     "agents",
     "extensions",
     "prompts",
+    "scripts",
     "skills",
     "themes",
     "types",
@@ -35,6 +40,12 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "check": "npm run validate && npm run typecheck && npm run pack:check",
+    "pack:check": "npm pack --dry-run",
+    "typecheck": "tsc --noEmit",
+    "validate": "node scripts/validate-package.mjs"
+  },
   "dependencies": {
     "yaml": "^2.8.0"
   },

package/prompts/docs.md

@@ -0,0 +1,37 @@
+---
+description: Generate or update documentation with gap detection and review
+category: quality
+aliases:
+  - document
+---
+
+Generate or update documentation for:
+
+$ARGUMENTS
+
+Process:
+
+1. Use `project_tree` to map the project structure.
+2. Use `code_search_batch` to find exports, public APIs, route definitions, and type declarations.
+3. Identify documentation gaps:
+   - Missing README sections (setup, usage, API, contributing)
+   - Undocumented public functions, classes, or endpoints
+   - Stale documentation that doesn't match current code
+   - Missing architecture or design decision records
+4. Use `spawn_agents` with `docs-writer` for detailed documentation generation when useful.
+5. Use `spawn_agents` with `reviewer` to validate accuracy of generated docs.
+
+Rules:
+
+- Match existing documentation style and conventions.
+- Include working code examples.
+- Document error cases and edge cases.
+- Use concrete language, not abstract descriptions.
+- Link between related sections.
+- Include prerequisites and setup steps.
+
+Output:
+
+- Generated or updated documentation files.
+- List of remaining documentation gaps.
+- Review verdict on documentation accuracy.

package/prompts/migrate.md

@@ -0,0 +1,44 @@
+---
+description: Plan and execute migrations with risk assessment, phased execution, and rollback strategies
+category: planning
+aliases:
+  - upgrade
+---
+
+Plan a migration for:
+
+$ARGUMENTS
+
+Process:
+
+1. Use `env_scan` to identify the current stack and versions.
+2. Use `dependency_inventory` to audit current dependencies.
+3. Use `code_search_batch` to find all touchpoints for the migration target.
+4. Use `spawn_agents` with `migration-expert` for detailed migration analysis.
+5. If the migration is risky (data loss possible, breaking changes), use `spawn_agents` with `red-team` to challenge the plan.
+
+Output:
+
+```text
+Migration: {from} → {to}
+
+Risk: low | medium | high - {why}
+
+Current state:
+- ...
+
+Breaking changes:
+1. ...
+
+Phases:
+1. {phase} - rollback: {strategy}
+2. ...
+
+Validation:
+- {command or check}
+
+Point of no return:
+- {phase N} — after this, rollback requires {strategy}
+```
+
+Do not execute destructive operations. Present the plan and wait for approval.

package/prompts/perf.md

@@ -0,0 +1,52 @@
+---
+description: Performance audit with bottleneck identification and improvement prioritization
+category: quality
+aliases:
+  - performance
+---
+
+Run a performance audit for:
+
+$ARGUMENTS
+
+Process:
+
+1. Use `env_scan` to identify the stack and build tooling.
+2. Use `project_tree` to understand project structure and identify hot paths.
+3. Use `code_search_batch` for known performance anti-patterns:
+   - N+1 queries, missing indexes, synchronous I/O in async code
+   - Large bundle imports, missing tree-shaking, barrel re-exports
+   - Missing memoization, inline closures in render, unstable keys
+   - O(n²) loops, repeated serialization, missing caching
+4. Use `spawn_agents` with `perf-auditor` for in-depth analysis when useful.
+5. Categorize findings by impact and effort.
+
+Output:
+
+```text
+Performance Audit: {scope}
+
+Risk Level: low | medium | high | critical
+
+Quick Wins (< 1 hour):
+1. file:line - issue - estimated improvement
+
+Medium Effort (1-4 hours):
+1. file:line - issue - estimated improvement
+
+Architecture Changes:
+1. description - estimated improvement - effort
+
+Bundle Analysis:
+- Total: ...
+- Largest deps: ...
+
+Query Analysis:
+- Hot paths: ...
+- N+1 patterns: ...
+
+Recommendations:
+1. ...
+```
+
+Do not optimize prematurely. Focus on measured or evidenced bottlenecks.

package/prompts/refactor.md

@@ -0,0 +1,53 @@
+---
+description: Structured refactoring workflow with smell detection, test verification, and safe execution
+category: quality
+aliases:
+  - cleanup
+---
+
+Refactor the following:
+
+$ARGUMENTS
+
+Do not change behavior. The output of the code before and after must be identical for all inputs.
+
+Process:
+
+1. Use `code_search_batch` and `project_tree` to map the scope.
+2. Identify the code smell or structural problem. Name it:
+   - duplicate code, long method, large class, feature envy, data clump,
+   - shotgun surgery, divergent change, primitive obsession, dead code,
+   - inappropriate intimacy, message chain, speculative generality.
+3. Check for existing tests covering the target code. If tests exist, run them before refactoring.
+4. If no tests exist and the change is risky, write a characterization test first.
+5. Plan the refactoring as a series of small, independently verifiable steps.
+6. Execute one step at a time. Re-run tests after each step.
+7. If any test fails after a step, revert that step and investigate.
+8. Use `spawn_agents` with `reviewer` to verify the refactoring preserves behavior.
+
+Output:
+
+```text
+Refactoring: {smell} in {scope}
+
+Before:
+- Structure: ...
+- Issues: ...
+
+Steps:
+1. {step} - verified by {test or check}
+2. ...
+
+After:
+- Structure: ...
+- Behavior change: NONE
+
+Test results:
+- Before: ...
+- After: ...
+
+Remaining smells:
+- ...
+```
+
+Do not combine refactoring with feature work. Refactoring is behavior-preserving only.

package/scripts/validate-package.mjs

@@ -0,0 +1,127 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml } from "yaml";
+
+const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const failures = [];
+
+function fail(message) {
+  failures.push(message);
+}
+
+function read(path) {
+  return readFileSync(join(root, path), "utf-8");
+}
+
+function walk(dir, predicate = () => true) {
+  const absolute = join(root, dir);
+  if (!existsSync(absolute)) return [];
+  const files = [];
+  for (const entry of readdirSync(absolute, { withFileTypes: true })) {
+    const full = join(absolute, entry.name);
+    if (entry.isDirectory()) files.push(...walk(relative(root, full), predicate));
+    else if (predicate(entry.name)) files.push(relative(root, full).replace(/\\/g, "/"));
+  }
+  return files;
+}
+
+function parseMarkdown(file) {
+  const raw = read(file);
+  const match = raw.match(/^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n([\s\S]*)$/);
+  if (!match) return { frontmatter: {}, body: raw };
+  const frontmatter = parseYaml(match[1]) ?? {};
+  if (!frontmatter || typeof frontmatter !== "object" || Array.isArray(frontmatter)) {
+    fail(`${file}: frontmatter must be a mapping`);
+    return { frontmatter: {}, body: match[2] };
+  }
+  return { frontmatter, body: match[2] };
+}
+
+for (const file of walk("extensions", (name) => name.endsWith(".ts"))) {
+  const content = read(file);
+  if (content.includes("@mariozechner/")) fail(`${file}: uses old @mariozechner namespace`);
+  if (content.includes("@sinclair/typebox")) fail(`${file}: uses @sinclair/typebox instead of typebox`);
+  if (/--append-system-prompt",\s*(state\.def|agentDef)\.systemPrompt/.test(content)) {
+    fail(`${file}: passes raw system prompt instead of a temp file`);
+  }
+}
+
+const promptNames = new Map();
+for (const file of walk("prompts", (name) => name.endsWith(".md"))) {
+  const { frontmatter, body } = parseMarkdown(file);
+  const name = typeof frontmatter.name === "string" ? frontmatter.name : basename(file, ".md");
+  if (!body.trim()) fail(`${file}: prompt body is empty`);
+  if (promptNames.has(name)) fail(`${file}: duplicate prompt name "${name}" also used by ${promptNames.get(name)}`);
+  promptNames.set(name, file);
+}
+
+const agentNames = new Set();
+for (const file of walk("agents", (name) => name.endsWith(".md"))) {
+  const { frontmatter, body } = parseMarkdown(file);
+  if (typeof frontmatter.name !== "string" || !frontmatter.name.trim()) fail(`${file}: missing agent name`);
+  if (typeof frontmatter.description !== "string" || !frontmatter.description.trim()) fail(`${file}: missing agent description`);
+  if (!body.trim()) fail(`${file}: agent body is empty`);
+  if (typeof frontmatter.name === "string") agentNames.add(frontmatter.name);
+}
+
+const teams = parseYaml(read("agents/teams.yaml")) ?? {};
+for (const [team, members] of Object.entries(teams)) {
+  if (!Array.isArray(members)) {
+    fail(`agents/teams.yaml: ${team} must be a list`);
+    continue;
+  }
+  for (const member of members) {
+    if (!agentNames.has(member)) fail(`agents/teams.yaml: ${team} references unknown agent ${member}`);
+  }
+}
+
+const chains = parseYaml(read("agents/agent-chain.yaml")) ?? {};
+for (const [chainName, chain] of Object.entries(chains)) {
+  if (!chain || typeof chain !== "object" || Array.isArray(chain) || !Array.isArray(chain.steps)) {
+    fail(`agents/agent-chain.yaml: ${chainName} must have steps`);
+    continue;
+  }
+  for (const [index, step] of chain.steps.entries()) {
+    if (!step || typeof step !== "object" || Array.isArray(step)) {
+      fail(`agents/agent-chain.yaml: ${chainName} step ${index + 1} must be a mapping`);
+      continue;
+    }
+    if (!agentNames.has(step.agent)) fail(`agents/agent-chain.yaml: ${chainName} references unknown agent ${step.agent}`);
+    if (typeof step.prompt !== "string" || !step.prompt.trim()) {
+      fail(`agents/agent-chain.yaml: ${chainName} step ${index + 1} missing prompt`);
+    } else if (!step.prompt.includes("$INPUT") && !step.prompt.includes("$ORIGINAL") && !/\$STEP_\d+/.test(step.prompt)) {
+      fail(`agents/agent-chain.yaml: ${chainName} step ${index + 1} prompt must contain either $INPUT, $ORIGINAL or $STEP_N`);
+    }
+  }
+}
+
+// 2. Validate skill directories
+const skillsAbsolute = join(root, "skills");
+if (existsSync(skillsAbsolute)) {
+  for (const entry of readdirSync(skillsAbsolute, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      const skillFile = join(skillsAbsolute, entry.name, "SKILL.md");
+      if (!existsSync(skillFile)) {
+        fail(`skills/${entry.name}: missing SKILL.md`);
+      }
+    }
+  }
+}
+
+// 3. Validate theme JSON files
+for (const file of walk("themes", (name) => name.endsWith(".json"))) {
+  try {
+    JSON.parse(read(file));
+  } catch (err) {
+    fail(`${file}: invalid JSON theme file: ${err.message}`);
+  }
+}
+
+if (failures.length) {
+
+  console.error(failures.map((item) => `- ${item}`).join("\n"));
+  process.exit(1);
+}
+
+console.log("openpi package validation passed");

package/skills/perf-auditor/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: perf-auditor
+description: Use when diagnosing performance issues, optimizing bundle size, fixing slow queries, reducing memory usage, or auditing hot paths.
+---
+
+# Performance Auditor
+
+Focus on measured or evidenced bottlenecks. Do not optimize prematurely.
+
+## Frontend Performance
+
+Check for:
+- Large bundle imports (`import _ from 'lodash'` instead of `import get from 'lodash/get'`)
+- Barrel file re-exports that prevent tree-shaking
+- Missing `React.memo`, `useMemo`, `useCallback` on expensive renders
+- Inline object/function props causing unnecessary re-renders
+- Unoptimized images, missing lazy loading
+- Blocking synchronous scripts in `<head>`
+- Layout thrashing from synchronous DOM read/write cycles
+
+## Backend Performance
+
+Check for:
+- N+1 query patterns in ORM usage (loop with `.find()` or `.get()`)
+- Missing database indexes on filtered/sorted columns
+- Synchronous file I/O in async request handlers
+- Unclosed database connections or missing connection pooling
+- CPU-bound work blocking the event loop
+- Unbounded in-memory caches
+- Missing pagination on list endpoints
+
+## General
+
+Check for:
+- O(n²) or worse algorithmic complexity in hot paths
+- Repeated JSON serialization/deserialization
+- Missing HTTP caching headers
+- Unnecessary network roundtrips
+- Cold start overhead from eager loading
+
+## Tools
+
+Use `code_search_batch` with patterns:
+- `\.find\(`, `\.findOne\(`, `\.get\(` inside loops for N+1
+- `import .* from ['"]lodash['"]` for barrel imports
+- `fs\.readFileSync`, `fs\.writeFileSync` for sync I/O
+- `JSON\.parse.*JSON\.stringify` for repeated serialization
+
+Report findings with `file:line`, estimated impact, and effort to fix.

package/skills/refactor-guide/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: refactor-guide
+description: Use when refactoring code, cleaning up technical debt, removing code smells, extracting modules, or restructuring without changing behavior.
+---
+
+# Refactor Guide
+
+Refactoring preserves behavior. Never combine refactoring with feature work.
+
+## Before Refactoring
+
+1. Identify the code smell by name:
+   - Duplicate code, long method, large class, feature envy, data clump,
+   - shotgun surgery, divergent change, primitive obsession, dead code,
+   - inappropriate intimacy, message chain, speculative generality.
+2. Find existing tests covering the target. Run them. They must pass.
+3. If no tests exist and the change is risky, write a characterization test first.
+
+## During Refactoring
+
+1. Plan as a series of small, independently verifiable steps.
+2. Execute one step at a time.
+3. Re-run relevant tests after each step.
+4. If any test fails, revert that step and investigate.
+5. Do not refactor and add features in the same change.
+
+## After Refactoring
+
+1. Run the full relevant test suite.
+2. Use `ghost_test_scan` before trusting green tests.
+3. Verify no behavior change with concrete before/after evidence.
+4. Use `spawn_agents` with `reviewer` to validate the diff preserves behavior.
+
+## Anti-Patterns to Avoid
+
+- Refactoring without tests as a safety net.
+- "While I'm in here" feature additions.
+- Speculative abstraction (don't extract what you don't need yet).
+- Renaming for style without consensus.

package/tsconfig.json

@@ -6,7 +6,8 @@
     "allowImportingTsExtensions": true,
     "noEmit": true,
     "skipLibCheck": true,
-    "strict": false
+    "strict": true,
+    "noImplicitAny": false
   },
   "include": [
     "extensions/**/*.ts",

package/types/pi-shims.d.ts

@@ -1,11 +1,3 @@
-declare module "@mariozechner/pi-coding-agent" {
-  export type ExtensionContext = any;
-  export type ExtensionAPI = any;
-  export const DynamicBorder: any;
-  export function isToolCallEventType(...args: any[]): boolean;
-  export function getMarkdownTheme(...args: any[]): any;
-}
-
 declare module "@earendil-works/pi-coding-agent" {
   export type ExtensionContext = any;
   export type ExtensionAPI = any;
@@ -17,36 +9,6 @@ declare module "@earendil-works/pi-coding-agent" {
   export function withFileMutationQueue<T = any>(...args: any[]): Promise<T>;
 }
 
-declare module "@mariozechner/pi-tui" {
-  export class Text {
-    constructor(...args: any[]);
-    setText(...args: any[]): any;
-    render(...args: any[]): any;
-    invalidate(...args: any[]): any;
-  }
-  export class Box {
-    constructor(...args: any[]);
-  }
-  export class Markdown {
-    constructor(...args: any[]);
-  }
-  export class Container {
-    constructor(...args: any[]);
-    addChild(...args: any[]): any;
-    render(...args: any[]): any;
-    invalidate(...args: any[]): any;
-  }
-  export class Spacer {
-    constructor(...args: any[]);
-  }
-  export type AutocompleteItem = any;
-  export const Key: any;
-  export function matchesKey(...args: any[]): any;
-  export function truncateToWidth(...args: any[]): any;
-  export function visibleWidth(...args: any[]): any;
-  export function getMarkdownTheme(...args: any[]): any;
-}
-
 declare module "@earendil-works/pi-tui" {
   export class Text {
     constructor(...args: any[]);
@@ -77,16 +39,6 @@ declare module "@earendil-works/pi-tui" {
   export function getMarkdownTheme(...args: any[]): any;
 }
 
-declare module "@sinclair/typebox" {
-  export const Type: any;
-}
-
-declare module "@mariozechner/pi-ai" {
-  export type AssistantMessage = any;
-  export type Message = any;
-  export function StringEnum(...args: any[]): any;
-}
-
 declare module "@earendil-works/pi-ai" {
   export type AssistantMessage = any;
   export type Message = any;