omni-pi 0.1.0

package/CREDITS.md

@@ -0,0 +1,28 @@
+# Credits
+
+Omni-Pi exists because of the Pi ecosystem and the work of earlier authors.
+
+## Core upstream foundations
+
+- [badlogic/pi-mono](https://github.com/badlogic/pi-mono) by Mario Zechner and contributors
+  - Pi runtime, package model, extension system, skill loading, and terminal agent foundation
+- [@mariozechner/pi-coding-agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent) by Mario Zechner
+  - Pi coding agent package (direct dependency)
+
+## Workflow and orchestration inspiration
+
+- [can1357/oh-my-pi](https://github.com/can1357/oh-my-pi)
+  - Model-role routing, orchestration ideas, and Pi-native workflow enhancements
+- [gsd-build/gsd-2](https://github.com/gsd-build/gsd-2)
+  - Disk-first workflow state, durable progress files, and batteries-included product shape
+
+## Ecosystem inspiration
+
+- [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents) by Nico Bailon
+  - Isolated worker/expert execution substrate (direct dependency) and broader subagent and extension ecosystem inspiration
+- The broader Pi community
+  - Package, skill, and workflow ideas that shaped the Omni-Pi direction
+
+## Attribution intent
+
+Omni-Pi is an original project, but it is intentionally built in conversation with upstream Pi work. This file is the canonical source for attribution and should be kept up to date as the project evolves.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eduard-David Gyarmati
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# Omni-Pi
+
+Omni-Pi: Guided software delivery for everyone.
+
+Omni-Pi is an opinionated Pi package and branded launcher that helps people move from a blank repo to a structured plan, implemented work, and explicit verification without having to assemble the workflow themselves.
+
+Requires Node.js 22 or newer.
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![npm version](https://img.shields.io/npm/v/omni-pi.svg)](https://www.npmjs.com/package/omni-pi)
+[![CI](https://github.com/EdGy2k/Omni-Pi/actions/workflows/ci.yml/badge.svg)](https://github.com/EdGy2k/Omni-Pi/actions/workflows/ci.yml)
+
+## Why Omni-Pi
+
+- Guided step-by-step workflow keeps the process moving without blank-canvas paralysis.
+- Durable project memory in `.omni/` survives across sessions.
+- Automatic verification infers checks from the language and project shape.
+- Expert fallback takes over when the worker agent gets stuck.
+
+## Quick Start
+
+```bash
+npm install -g omni-pi
+cd your-project
+omni
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/omni-init` | Initialize `.omni/` project memory, run quick-start wizard, scan repo signals, run health checks (`--quick` to skip wizard) |
+| `/omni-plan` | Create or refresh spec, tasks, and tests (supports `--preset bugfix/feature/refactor/spike/security-audit`) |
+| `/omni-work` | Run the next task through worker, verifier, and expert fallback |
+| `/omni-status` | Show current phase, task, blockers, next step (add `metrics` for agent stats) |
+| `/omni-sync` | Update durable memory files from recent progress |
+| `/omni-skills` | Inspect installed, recommended, deferred, and rejected skills |
+| `/omni-explain` | Explain what Omni-Pi is doing in simple language |
+| `/omni-model` | Interactively select the model for a specific agent role |
+| `/omni-commit` | Create a branch and commit for the last completed task |
+| `/omni-doctor` | Run diagnostic health checks and detect stuck tasks |
+
+## How It Works
+
+Omni-Pi follows a simple agent pipeline: Brain, Planner, Worker, Expert. The Brain handles conversation, the Planner turns intent into concrete steps and checks, and the Worker executes bounded tasks with filesystem-backed state in `.omni/`.
+
+When the Worker gets stuck or verification fails repeatedly, the Expert role steps in to recover the task, adapt the approach, or surface the blocker clearly instead of letting the session stall.
+
+## Features
+
+- Core workflow with durable `.omni/` project memory, typed planning and execution contracts, filesystem-backed init/planning/status, and retry-aware task execution.
+- Language-aware verification that infers test commands for common stacks and supports custom checks in `.omni/TESTS.md`.
+- Workflow presets for bugfix, feature, refactor, spike, and security-audit work.
+- Doctor checks for init state, config validity, repo signals, task health, and stuck detection.
+- Plan and progress memory with dated plan files, an index tracker, and timestamped progress logs.
+- Context-aware file selection for different workflow phases.
+- Subagent integration for worker and expert execution with raw output persistence and model overrides.
+- Persistent dashboard state for phase, task, blockers, next step, and health status.
+- Git integration for branch creation and task-derived commits.
+- Interactive planning for constraints, user context, and skill install tracking.
+
+## Development
+
+For contributor setup, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+```bash
+git clone https://github.com/EdGy2k/Omni-Pi.git
+cd Omni-Pi
+npm install
+npm test
+npm run check
+npm run lint
+```
+
+## Attribution
+
+Omni-Pi builds on the Pi ecosystem. See [CREDITS.md](CREDITS.md) for full attribution.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/agents/brain.md

@@ -0,0 +1,24 @@
+---
+name: brain
+model: friendly-primary-model
+description: User-facing orchestrator for Omni-Pi.
+---
+
+# Brain
+
+You are the user-facing guide for Omni-Pi.
+
+## Responsibilities
+
+- Talk to the user in plain English.
+- Keep the user oriented with simple progress updates.
+- Update durable project memory through the `.omni/` file model.
+- Decide when to invoke the planner, worker, verifier, or expert roles.
+- Hide internal complexity unless the user asks for technical detail.
+
+## Rules
+
+- Prefer clarity over jargon.
+- Keep tasks small before handing them off.
+- Record important changes in `.omni/STATE.md`, `.omni/SESSION-SUMMARY.md`, and `.omni/DECISIONS.md`.
+- Route only relevant skills to each subagent.

package/agents/expert.md

@@ -0,0 +1,21 @@
+---
+name: expert
+model: strongest-implementation-model
+description: Advanced fallback subagent for difficult tasks.
+---
+
+# Expert
+
+You take over tasks that remain blocked after repeated worker failures or that require deeper reasoning.
+
+## Responsibilities
+
+- Read the original task brief plus failure history.
+- Fix the root issue instead of repeating the last attempt.
+- Leave a clear explanation of what changed and why.
+
+## Rules
+
+- Focus on the smallest complete fix.
+- Preserve previous useful work where possible.
+- Update the escalation trail for future debugging.

package/agents/planner.md

@@ -0,0 +1,22 @@
+---
+name: planner
+model: strongest-reasoning-model
+description: Spec writer and task decomposer for Omni-Pi.
+---
+
+# Planner
+
+You turn user intent and project context into a detailed implementation spec.
+
+## Responsibilities
+
+- Read only the relevant `.omni/` files for the task at hand.
+- Refine `.omni/SPEC.md`, `.omni/TASKS.md`, and `.omni/TESTS.md`.
+- Break large goals into bounded, verifiable task slices.
+- Recommend skills when they will materially improve quality or speed.
+
+## Rules
+
+- Every task slice must fit inside one focused worker session.
+- Every task slice must have explicit done criteria.
+- Prefer a small number of high-value tasks over a noisy task list.

package/agents/worker.md

@@ -0,0 +1,21 @@
+---
+name: worker
+model: cheap-fast-model
+description: Narrow implementation subagent for Omni-Pi.
+---
+
+# Worker
+
+You execute one bounded task brief at a time.
+
+## Responsibilities
+
+- Read the assigned task brief and minimal supporting files.
+- Use only the skills attached to the current task.
+- Implement the requested change and leave concise notes for verification.
+
+## Rules
+
+- Stay within scope.
+- Do not silently expand the task.
+- If blocked, write a compact failure summary that can be reused for retry or escalation.

package/bin/omni.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function getOmniPackageDir() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+}
+
+export function resolvePiCliPath() {
+  return path.join(
+    getOmniPackageDir(),
+    "node_modules",
+    "@mariozechner",
+    "pi-coding-agent",
+    "dist",
+    "cli.js",
+  );
+}
+
+export function buildOmniEnvironment(baseEnv = process.env) {
+  return {
+    ...baseEnv,
+  };
+}
+
+export function buildPiProcessSpec(
+  argv = process.argv.slice(2),
+  baseEnv = process.env,
+) {
+  return {
+    command: process.execPath,
+    args: [resolvePiCliPath(), "-e", getOmniPackageDir(), ...argv],
+    env: buildOmniEnvironment(baseEnv),
+  };
+}
+
+export async function runOmni(argv = process.argv.slice(2), options = {}) {
+  const spec = buildPiProcessSpec(argv, options.env);
+
+  await new Promise((resolve, reject) => {
+    const child = spawn(spec.command, spec.args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: spec.env,
+      stdio: "inherit",
+    });
+
+    const forwardSignal = (sig) => child.kill(sig);
+    process.on("SIGINT", forwardSignal);
+    process.on("SIGTERM", forwardSignal);
+
+    child.on("exit", (code, signal) => {
+      process.off("SIGINT", forwardSignal);
+      process.off("SIGTERM", forwardSignal);
+
+      if (signal) {
+        reject(new Error(`omni terminated with signal ${signal}`));
+        return;
+      }
+
+      process.exitCode = code ?? 0;
+      resolve(code ?? 0);
+    });
+    child.on("error", (err) => {
+      process.off("SIGINT", forwardSignal);
+      process.off("SIGTERM", forwardSignal);
+      reject(err);
+    });
+  });
+}
+
+const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : "";
+if (invokedPath === fileURLToPath(import.meta.url)) {
+  runOmni().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  });
+}

package/extensions/omni-core/index.ts

@@ -0,0 +1,22 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { createOmniCommands } from "../../src/commands.js";
+import {
+  registerOmniMessageRenderer,
+  registerPiCommands,
+} from "../../src/pi.js";
+
+export default function omniCoreExtension(api: ExtensionAPI): void {
+  registerOmniMessageRenderer(api);
+  const commands = createOmniCommands().filter((command) =>
+    [
+      "omni-init",
+      "omni-plan",
+      "omni-work",
+      "omni-sync",
+      "omni-model",
+      "omni-commit",
+    ].includes(command.name),
+  );
+  registerPiCommands(api, commands);
+}

package/extensions/omni-memory/index.ts

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+
+import type { OmniState } from "../../src/contracts.js";
+import { runDoctor } from "../../src/doctor.js";
+import { renderCompactStatus } from "../../src/status.js";
+
+async function readState(cwd: string): Promise<OmniState | null> {
+  try {
+    const content = await readFile(path.join(cwd, ".omni", "STATE.md"), "utf8");
+    const matchValue = (label: string): string => {
+      const regex = new RegExp(`^${label}:\\s*(.*)$`, "mu");
+      return content.match(regex)?.[1]?.trim() ?? "";
+    };
+    const blockersValue = matchValue("Blockers");
+    const recoveryMatch = content.match(/Recovery Options:\n((?:- .*\n?)*)/u);
+    const recoveryOptions = recoveryMatch
+      ? recoveryMatch[1]
+          .split("\n")
+          .map((line) => line.replace(/^- /u, "").trim())
+          .filter(Boolean)
+      : undefined;
+    return {
+      currentPhase: matchValue(
+        "Current Phase",
+      ).toLowerCase() as OmniState["currentPhase"],
+      activeTask: matchValue("Active Task"),
+      statusSummary: matchValue("Status Summary"),
+      blockers:
+        blockersValue && blockersValue !== "None"
+          ? blockersValue.split(/;\s*/u)
+          : [],
+      nextStep: matchValue("Next Step"),
+      recoveryOptions,
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function updateWidget(ctx: ExtensionContext): Promise<void> {
+  const state = await readState(ctx.cwd);
+  if (state) {
+    const report = await runDoctor(ctx.cwd);
+    ctx.ui.setWidget(
+      "omni-dashboard",
+      renderCompactStatus(state, report.overall),
+      { placement: "aboveEditor" },
+    );
+  } else {
+    ctx.ui.setWidget("omni-dashboard", undefined);
+  }
+}
+
+export default function omniMemoryExtension(api: ExtensionAPI): void {
+  api.on("session_start", async (_event, ctx) => {
+    await updateWidget(ctx);
+  });
+
+  api.on("session_switch", async (_event, ctx) => {
+    await updateWidget(ctx);
+  });
+
+  api.on("turn_end", async (_event, ctx) => {
+    await updateWidget(ctx);
+  });
+}

package/extensions/omni-skills/index.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { createOmniCommands } from "../../src/commands.js";
+import { registerPiCommands } from "../../src/pi.js";
+
+export default function omniSkillsExtension(api: ExtensionAPI): void {
+  const commands = createOmniCommands().filter((command) =>
+    ["omni-skills"].includes(command.name),
+  );
+  registerPiCommands(api, commands);
+}

package/extensions/omni-status/index.ts

@@ -0,0 +1,11 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { createOmniCommands } from "../../src/commands.js";
+import { registerPiCommands } from "../../src/pi.js";
+
+export default function omniStatusExtension(api: ExtensionAPI): void {
+  const commands = createOmniCommands().filter((command) =>
+    ["omni-status", "omni-explain", "omni-doctor"].includes(command.name),
+  );
+  registerPiCommands(api, commands);
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "omni-pi",
+  "version": "0.1.0",
+  "description": "Opinionated Pi package for guided, beginner-friendly planning and implementation workflows.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Eduard-David Gyarmati",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/EdGy2k/Omni-Pi.git"
+  },
+  "homepage": "https://github.com/EdGy2k/Omni-Pi#readme",
+  "bugs": {
+    "url": "https://github.com/EdGy2k/Omni-Pi/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "omni": "./bin/omni.js"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "agent",
+    "planning",
+    "skills",
+    "orchestration"
+  ],
+  "files": [
+    "bin",
+    "agents",
+    "extensions",
+    "prompts",
+    "skills",
+    "src",
+    "templates",
+    "README.md",
+    "CREDITS.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "test": "vitest run",
+    "pack:check": "npm pack --dry-run",
+    "prepublishOnly": "npm run check && npm run lint && npm test"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.9",
+    "@types/node": "^24.12.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "pi": {
+    "extensions": [
+      "./node_modules/pi-subagents/index.ts",
+      "./node_modules/pi-subagents/notify.ts",
+      "./extensions/omni-core/index.ts",
+      "./extensions/omni-memory/index.ts",
+      "./extensions/omni-skills/index.ts",
+      "./extensions/omni-status/index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "prompts": [
+      "./prompts"
+    ]
+  },
+  "dependencies": {
+    "@mariozechner/pi-coding-agent": "^0.62.0",
+    "pi-subagents": "^0.11.11"
+  }
+}

package/prompts/brainstorm.md

@@ -0,0 +1,15 @@
+# Brainstorm Prompt
+
+Help the user turn rough ideas into a clear project direction.
+
+## Capture
+
+- what they want to build
+- who it is for
+- what matters most
+- what constraints matter now
+- what can wait until later
+
+## Output
+
+Write concise updates into `.omni/PROJECT.md`, `.omni/IDEAS.md`, and `.omni/SESSION-SUMMARY.md`.

package/prompts/spec-template.md

@@ -0,0 +1,14 @@
+# Spec Template Prompt
+
+Produce a focused implementation spec using the current `.omni/` context.
+
+## Include
+
+- problem statement
+- solution shape
+- key workflows
+- architecture outline
+- acceptance criteria
+- open risks or unknowns
+
+Update `.omni/SPEC.md` and keep the language understandable for a human reviewer.

package/prompts/task-template.md

@@ -0,0 +1,16 @@
+# Task Template Prompt
+
+Turn the current spec into bounded task slices.
+
+## Each task must include
+
+- ID
+- title
+- objective
+- minimal context files
+- relevant skills
+- done criteria
+- dependencies
+- role assignment
+
+Update `.omni/TASKS.md` and keep tasks small enough for one focused worker session.

package/skills/omni-escalation/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: omni-escalation
+description: Expert takeover for tasks that have failed repeatedly or need the strongest reasoning to unblock. Triggers include "stuck", "blocked", "tried multiple times", "keeps failing", or when normal execution cannot make progress.
+---
+
+# Omni Escalation
+
+## Goals
+
+- read the task brief and failure history
+- identify the root cause of repeated failure
+- complete or unblock the task with the strongest available reasoning model
+
+## Rules
+
+- avoid retrying the same failed path blindly
+- leave a clear postmortem note for future tasks

package/skills/omni-execution/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: omni-execution
+description: Implements the next task from .omni/TASKS.md with narrow scope and concise handoff notes. Triggers include "do the next task", "implement", "execute", or when a task is ready for implementation.
+---
+
+# Omni Execution
+
+## Goals
+
+- read the next task brief
+- complete the requested change with minimal context
+- record concise implementation notes for verification and handoff
+
+## Rules
+
+- stay narrowly scoped
+- do not rewrite the plan during execution
+- leave reusable failure notes if the task cannot be completed

package/skills/omni-init/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: omni-init
+description: Initializes Omni-Pi in a new or existing project by creating .omni/ folder and capturing project context. Triggers include "initialize", "setup", "new project", "configure", or when .omni/ does not exist.
+---
+
+# Omni Init
+
+## Goals
+
+- create the `.omni/` folder and starter files
+- capture project goals, users, constraints, and success criteria
+- inspect the repo for stack and tooling signals
+- propose initial skills and install only high-confidence, low-risk ones
+
+## Outputs
+
+- updated `.omni/PROJECT.md`
+- updated `.omni/STATE.md`
+- updated `.omni/SKILLS.md`

package/skills/omni-planning/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: omni-planning
+description: Produces or refines implementation plans in .omni/SPEC.md, task breakdowns in .omni/TASKS.md, and verification criteria in .omni/TESTS.md. Triggers include "plan", "break down", "what tasks", "how to implement", or when starting a new feature.
+---
+
+# Omni Planning
+
+## Goals
+
+- update `.omni/SPEC.md`
+- decompose work into bounded slices in `.omni/TASKS.md`
+- define verification criteria in `.omni/TESTS.md`
+- recommend any missing skills that would help the planned work
+
+## Rules
+
+- tasks must stay small and concrete
+- done criteria must be explicit
+- only recommend skills when they materially help execution

package/skills/omni-verification/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: omni-verification
+description: Runs checks from .omni/TESTS.md after task implementation, summarizes pass/fail, and prepares retry briefs. Triggers include "verify", "test", "check", "did it work", or after completing an implementation task.
+---
+
+# Omni Verification
+
+## Goals
+
+- run the planned checks from `.omni/TESTS.md`
+- summarize pass/fail status clearly
+- produce a compact retry brief when checks fail
+
+## Rules
+
+- keep verification deterministic when possible
+- separate implementation failure from environment failure
+- make the next action obvious