omni-pi 0.1.0

package/src/context.ts

@@ -0,0 +1,165 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { OmniPhase, TaskBrief } from "./contracts.js";
+import { OMNI_DIR } from "./contracts.js";
+
+const CHARS_PER_TOKEN = 4;
+
+export interface TokenBudget {
+  maxTokens: number;
+  usedTokens: number;
+  remainingTokens: number;
+}
+
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / CHARS_PER_TOKEN);
+}
+
+export function createBudget(maxTokens: number): TokenBudget {
+  return { maxTokens, usedTokens: 0, remainingTokens: maxTokens };
+}
+
+export function consumeBudget(budget: TokenBudget, text: string): TokenBudget {
+  const tokens = estimateTokens(text);
+  const usedTokens = budget.usedTokens + tokens;
+  return {
+    maxTokens: budget.maxTokens,
+    usedTokens,
+    remainingTokens: Math.max(0, budget.maxTokens - usedTokens),
+  };
+}
+
+export function fitsInBudget(budget: TokenBudget, text: string): boolean {
+  return estimateTokens(text) <= budget.remainingTokens;
+}
+
+const PHASE_FILES: Record<OmniPhase, string[]> = {
+  understand: ["PROJECT.md", "IDEAS.md", "SESSION-SUMMARY.md", "PROGRESS.md"],
+  plan: [
+    "PROJECT.md",
+    "SPEC.md",
+    "TASKS.md",
+    "DECISIONS.md",
+    "SESSION-SUMMARY.md",
+  ],
+  build: ["SPEC.md", "TASKS.md", "TESTS.md", "PROGRESS.md"],
+  check: ["TESTS.md", "TASKS.md", "SPEC.md"],
+  escalate: [
+    "SPEC.md",
+    "TASKS.md",
+    "TESTS.md",
+    "DECISIONS.md",
+    "SESSION-SUMMARY.md",
+    "PROGRESS.md",
+  ],
+};
+
+export function getPhaseFiles(phase: OmniPhase): string[] {
+  return PHASE_FILES[phase];
+}
+
+async function safeReadFile(filePath: string): Promise<string | null> {
+  try {
+    return await readFile(filePath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+export interface ContextBlock {
+  file: string;
+  content: string;
+  tokens: number;
+}
+
+export async function gatherPhaseContext(
+  rootDir: string,
+  phase: OmniPhase,
+  maxTokens: number,
+): Promise<ContextBlock[]> {
+  const files = getPhaseFiles(phase);
+  let budget = createBudget(maxTokens);
+  const blocks: ContextBlock[] = [];
+
+  for (const file of files) {
+    const content = await safeReadFile(path.join(rootDir, OMNI_DIR, file));
+    if (!content) continue;
+    if (!fitsInBudget(budget, content)) continue;
+
+    budget = consumeBudget(budget, content);
+    blocks.push({
+      file,
+      content,
+      tokens: estimateTokens(content),
+    });
+  }
+
+  return blocks;
+}
+
+export async function gatherTaskContext(
+  rootDir: string,
+  task: TaskBrief,
+  maxTokens: number,
+): Promise<ContextBlock[]> {
+  const coreFiles = ["SPEC.md", "TESTS.md"];
+  let budget = createBudget(maxTokens);
+  const blocks: ContextBlock[] = [];
+
+  // Core omni files first
+  for (const file of coreFiles) {
+    const content = await safeReadFile(path.join(rootDir, OMNI_DIR, file));
+    if (!content) continue;
+    if (!fitsInBudget(budget, content)) continue;
+
+    budget = consumeBudget(budget, content);
+    blocks.push({ file, content, tokens: estimateTokens(content) });
+  }
+
+  // Task brief
+  const briefPath = path.join(
+    rootDir,
+    OMNI_DIR,
+    "tasks",
+    `${task.id}-BRIEF.md`,
+  );
+  const briefContent = await safeReadFile(briefPath);
+  if (briefContent && fitsInBudget(budget, briefContent)) {
+    budget = consumeBudget(budget, briefContent);
+    blocks.push({
+      file: `tasks/${task.id}-BRIEF.md`,
+      content: briefContent,
+      tokens: estimateTokens(briefContent),
+    });
+  }
+
+  // Context files from the task definition
+  for (const file of task.contextFiles) {
+    const content = await safeReadFile(path.join(rootDir, file));
+    if (!content) continue;
+    if (!fitsInBudget(budget, content)) continue;
+
+    budget = consumeBudget(budget, content);
+    blocks.push({ file, content, tokens: estimateTokens(content) });
+  }
+
+  return blocks;
+}
+
+export function renderContextBlocks(blocks: ContextBlock[]): string {
+  if (blocks.length === 0) return "";
+
+  return blocks
+    .map(
+      (block) =>
+        `--- ${block.file} (${block.tokens} tokens) ---\n${block.content}`,
+    )
+    .join("\n\n");
+}
+
+export function renderContextSummary(blocks: ContextBlock[]): string {
+  const totalTokens = blocks.reduce((sum, b) => sum + b.tokens, 0);
+  const fileList = blocks.map((b) => `${b.file} (${b.tokens}t)`).join(", ");
+  return `Pre-loaded context: ${totalTokens} tokens from ${blocks.length} files: ${fileList}`;
+}

package/src/contracts.ts

@@ -0,0 +1,183 @@
+export const OMNI_DIR = ".omni";
+
+export type OmniPhase = "understand" | "plan" | "build" | "check" | "escalate";
+
+export type TaskStatus = "todo" | "in_progress" | "blocked" | "done";
+
+export type SkillPolicy =
+  | "auto-install"
+  | "recommend-only"
+  | "never-auto-install";
+
+export interface ConversationBrief {
+  summary: string;
+  desiredOutcome: string;
+  constraints: string[];
+  userSignals: string[];
+  preset?: WorkflowPreset;
+}
+
+export interface ImplementationSpec {
+  title: string;
+  scope: string[];
+  architecture: string[];
+  taskSlices: TaskBrief[];
+  acceptanceCriteria: string[];
+}
+
+export interface TaskBrief {
+  id: string;
+  title: string;
+  objective: string;
+  contextFiles: string[];
+  skills: string[];
+  doneCriteria: string[];
+  role: "worker" | "expert";
+  status: TaskStatus;
+  dependsOn: string[];
+}
+
+export interface VerificationResult {
+  taskId: string;
+  passed: boolean;
+  checksRun: string[];
+  failureSummary: string[];
+  retryRecommended: boolean;
+}
+
+export interface TaskAttemptResult {
+  summary: string;
+  verification: VerificationResult;
+  modifiedFiles?: string[];
+}
+
+export interface EscalationBrief {
+  taskId: string;
+  priorAttempts: number;
+  failureLogs: string[];
+  expertObjective: string;
+  verificationResults?: Array<{
+    command: string;
+    passed: boolean;
+    stdout: string;
+    stderr: string;
+  }>;
+  modifiedFiles?: string[];
+}
+
+export interface SkillCandidate {
+  name: string;
+  reason: string;
+  confidence: "high" | "medium" | "low";
+  policy: SkillPolicy;
+}
+
+export interface OmniState {
+  currentPhase: OmniPhase;
+  activeTask: string;
+  statusSummary: string;
+  blockers: string[];
+  nextStep: string;
+  recoveryOptions?: string[];
+}
+
+export type WorkflowPreset =
+  | "bugfix"
+  | "feature"
+  | "refactor"
+  | "spike"
+  | "security-audit";
+
+export interface PresetConfig {
+  name: WorkflowPreset;
+  description: string;
+  maxTasks: number;
+  skipInterview: boolean;
+  requireVerification: boolean;
+  workerHint: string;
+}
+
+export const WORKFLOW_PRESETS: Record<WorkflowPreset, PresetConfig> = {
+  bugfix: {
+    name: "bugfix",
+    description:
+      "Quick fix for a known bug. Minimal planning, regression test required.",
+    maxTasks: 2,
+    skipInterview: true,
+    requireVerification: true,
+    workerHint:
+      "Focus on the root cause. Write a regression test before fixing.",
+  },
+  feature: {
+    name: "feature",
+    description:
+      "New feature implementation. Full planning flow with user interview.",
+    maxTasks: 8,
+    skipInterview: false,
+    requireVerification: true,
+    workerHint: "Follow the spec. Keep tasks bounded and verifiable.",
+  },
+  refactor: {
+    name: "refactor",
+    description: "Code restructuring. Existing tests must stay green.",
+    maxTasks: 5,
+    skipInterview: true,
+    requireVerification: true,
+    workerHint:
+      "Preserve all existing behavior. Run the full test suite after each change.",
+  },
+  spike: {
+    name: "spike",
+    description:
+      "Exploratory work. No verification required, no commit artifacts.",
+    maxTasks: 1,
+    skipInterview: true,
+    requireVerification: false,
+    workerHint: "Explore freely. Document findings in .omni/research/.",
+  },
+  "security-audit": {
+    name: "security-audit",
+    description: "Security review. Read-only analysis, produce a report.",
+    maxTasks: 3,
+    skipInterview: true,
+    requireVerification: false,
+    workerHint:
+      "Analyze for OWASP Top 10, secrets in code, dependency vulnerabilities. Do not modify source code.",
+  },
+};
+
+export function detectPreset(
+  branchName: string,
+  brief: string,
+): WorkflowPreset | null {
+  const lower = `${branchName} ${brief}`.toLowerCase();
+  if (/\b(fix|bug|hotfix)\b/u.test(lower)) return "bugfix";
+  if (/\b(refactor|clean\s*up|restructure)\b/u.test(lower)) return "refactor";
+  if (/\b(spike|explore|experiment|prototype)\b/u.test(lower)) return "spike";
+  if (/\b(security|audit|vulnerability|cve)\b/u.test(lower))
+    return "security-audit";
+  if (/\b(feat|feature|add|implement|build)\b/u.test(lower)) return "feature";
+  return null;
+}
+
+export interface OmniConfig {
+  models: {
+    worker: string;
+    expert: string;
+    planner: string;
+    brain: string;
+  };
+  retryLimit: number;
+  chainEnabled: boolean;
+  cleanupCompletedPlans: boolean;
+}
+
+export type PlanStatus = "active" | "completed" | "discarded";
+
+export interface PlanEntry {
+  id: string;
+  title: string;
+  status: PlanStatus;
+  createdAt: string;
+  completedAt?: string;
+}

package/src/doctor.ts

@@ -0,0 +1,225 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+import { readConfig } from "./config.js";
+import { OMNI_DIR } from "./contracts.js";
+import { detectRepoSignals } from "./repo.js";
+import { readTasks } from "./tasks.js";
+
+export type HealthLevel = "green" | "yellow" | "red";
+
+export interface DiagnosticResult {
+  name: string;
+  level: HealthLevel;
+  message: string;
+}
+
+export interface DoctorReport {
+  overall: HealthLevel;
+  checks: DiagnosticResult[];
+}
+
+async function fileExists(filePath: string): Promise<boolean> {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function checkOmniInitialized(
+  rootDir: string,
+): Promise<DiagnosticResult> {
+  const stateExists = await fileExists(
+    path.join(rootDir, OMNI_DIR, "STATE.md"),
+  );
+  if (!stateExists) {
+    return {
+      name: "omni-init",
+      level: "red",
+      message:
+        ".omni/ directory not found. Run /omni-init to initialize the project.",
+    };
+  }
+  return { name: "omni-init", level: "green", message: "Omni-Pi initialized." };
+}
+
+async function checkConfigParseable(
+  rootDir: string,
+): Promise<DiagnosticResult> {
+  try {
+    const config = await readConfig(rootDir);
+    const roles = ["worker", "expert", "planner", "brain"] as const;
+    for (const role of roles) {
+      if (!config.models[role]) {
+        return {
+          name: "config",
+          level: "yellow",
+          message: `Model for ${role} is empty in CONFIG.md.`,
+        };
+      }
+    }
+    return { name: "config", level: "green", message: "Config is valid." };
+  } catch {
+    return {
+      name: "config",
+      level: "yellow",
+      message: "CONFIG.md could not be parsed. Using defaults.",
+    };
+  }
+}
+
+async function checkRepoSignals(rootDir: string): Promise<DiagnosticResult> {
+  const signals = await detectRepoSignals(rootDir);
+  if (signals.languages.length === 0) {
+    return {
+      name: "repo-signals",
+      level: "yellow",
+      message:
+        "No programming languages detected. Verification commands may not be inferred automatically.",
+    };
+  }
+  return {
+    name: "repo-signals",
+    level: "green",
+    message: `Detected: ${signals.languages.join(", ")}.`,
+  };
+}
+
+async function checkOrphanedTasks(rootDir: string): Promise<DiagnosticResult> {
+  try {
+    const tasksPath = path.join(rootDir, OMNI_DIR, "TASKS.md");
+    const tasks = await readTasks(tasksPath);
+    const inProgress = tasks.filter((t) => t.status === "in_progress");
+    const blocked = tasks.filter((t) => t.status === "blocked");
+
+    if (blocked.length > 0) {
+      return {
+        name: "task-health",
+        level: "red",
+        message: `${blocked.length} blocked task(s): ${blocked.map((t) => t.id).join(", ")}. Review escalation notes or restructure the plan.`,
+      };
+    }
+    if (inProgress.length > 1) {
+      return {
+        name: "task-health",
+        level: "yellow",
+        message: `${inProgress.length} tasks marked in_progress simultaneously. Only one should be active.`,
+      };
+    }
+    return {
+      name: "task-health",
+      level: "green",
+      message: "Tasks are healthy.",
+    };
+  } catch {
+    return {
+      name: "task-health",
+      level: "green",
+      message: "No tasks file yet.",
+    };
+  }
+}
+
+export interface StuckSignal {
+  detected: boolean;
+  reason: string;
+  taskId?: string;
+}
+
+export async function detectStuck(rootDir: string): Promise<StuckSignal> {
+  const taskDir = path.join(rootDir, OMNI_DIR, "tasks");
+  try {
+    const tasksPath = path.join(rootDir, OMNI_DIR, "TASKS.md");
+    const tasks = await readTasks(tasksPath);
+    const inProgressOrTodo = tasks.filter(
+      (t) => t.status === "in_progress" || t.status === "todo",
+    );
+    if (inProgressOrTodo.length === 0) {
+      return { detected: false, reason: "No active tasks." };
+    }
+
+    const candidate = inProgressOrTodo[0];
+    try {
+      const historyPath = path.join(taskDir, `${candidate.id}.history.json`);
+      const raw = await readFile(historyPath, "utf8");
+      const history = JSON.parse(raw) as Array<{
+        verification: { passed: boolean; failureSummary: string[] };
+      }>;
+      const failures = history.filter((h) => !h.verification.passed);
+
+      if (failures.length >= 3) {
+        const lastErrors = failures
+          .slice(-3)
+          .map((f) => f.verification.failureSummary.join("; "));
+        const allSame =
+          lastErrors.length === 3 &&
+          lastErrors[0] === lastErrors[1] &&
+          lastErrors[1] === lastErrors[2];
+
+        if (allSame) {
+          return {
+            detected: true,
+            reason: `Task ${candidate.id} has failed 3+ times with the same error: "${lastErrors[0]}".`,
+            taskId: candidate.id,
+          };
+        }
+
+        return {
+          detected: true,
+          reason: `Task ${candidate.id} has ${failures.length} failures. Consider splitting or restructuring.`,
+          taskId: candidate.id,
+        };
+      }
+    } catch {
+      // no history yet
+    }
+
+    return { detected: false, reason: "No stuck signals." };
+  } catch {
+    return { detected: false, reason: "Could not read tasks." };
+  }
+}
+
+function worstLevel(checks: DiagnosticResult[]): HealthLevel {
+  if (checks.some((c) => c.level === "red")) return "red";
+  if (checks.some((c) => c.level === "yellow")) return "yellow";
+  return "green";
+}
+
+export async function runDoctor(rootDir: string): Promise<DoctorReport> {
+  const checks = await Promise.all([
+    checkOmniInitialized(rootDir),
+    checkConfigParseable(rootDir),
+    checkRepoSignals(rootDir),
+    checkOrphanedTasks(rootDir),
+  ]);
+
+  const stuck = await detectStuck(rootDir);
+  if (stuck.detected) {
+    checks.push({
+      name: "stuck-detection",
+      level: "red",
+      message: stuck.reason,
+    });
+  }
+
+  return { overall: worstLevel(checks), checks };
+}
+
+const HEALTH_ICONS: Record<HealthLevel, string> = {
+  green: "[OK]",
+  yellow: "[WARN]",
+  red: "[FAIL]",
+};
+
+export function renderDoctorReport(report: DoctorReport): string {
+  const lines = [`Health: ${HEALTH_ICONS[report.overall]} ${report.overall}`];
+  for (const check of report.checks) {
+    lines.push(
+      `  ${HEALTH_ICONS[check.level]} ${check.name}: ${check.message}`,
+    );
+  }
+  return lines.join("\n");
+}

package/src/git.ts

@@ -0,0 +1,135 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+import type { TaskBrief } from "./contracts.js";
+import { parseTaskRow } from "./tasks.js";
+
+type ExecFn = (
+  command: string,
+  args: string[],
+  options?: { cwd?: string },
+) => Promise<{ stdout: string; stderr: string; code: number; killed: boolean }>;
+
+export interface CommitPlan {
+  branch: string;
+  message: string;
+  files: string[];
+  taskId: string;
+  prBody: string;
+}
+
+export function buildBranchName(taskId: string): string {
+  return `omni/${taskId.toLowerCase().replace(/[^a-z0-9-]/gu, "-")}`;
+}
+
+export function buildCommitMessage(task: TaskBrief): string {
+  return `feat(${task.id}): ${task.title}\n\nObjective: ${task.objective}\nDone criteria: ${task.doneCriteria.join("; ") || "None listed"}`;
+}
+
+export function generatePrBody(
+  task: TaskBrief,
+  verificationSummary?: string,
+): string {
+  const lines = [
+    `## Summary`,
+    "",
+    `Implements ${task.id}: ${task.title}`,
+    "",
+    `**Objective:** ${task.objective}`,
+    "",
+    `## Done Criteria`,
+    "",
+    ...task.doneCriteria.map((c) => `- [x] ${c}`),
+    "",
+  ];
+  if (verificationSummary) {
+    lines.push("## Verification", "", verificationSummary, "");
+  }
+  return lines.join("\n");
+}
+
+export async function readLastCompletedTask(
+  rootDir: string,
+): Promise<{ taskId: string; task: TaskBrief } | null> {
+  try {
+    const tasksContent = await readFile(
+      path.join(rootDir, ".omni", "TASKS.md"),
+      "utf8",
+    );
+    const doneRows = tasksContent
+      .split("\n")
+      .filter((line) => line.startsWith("| T") && line.includes("| done |"));
+    if (doneRows.length === 0) return null;
+
+    const lastRow = doneRows[doneRows.length - 1];
+    const task = parseTaskRow(lastRow);
+    if (!task || task.status !== "done") return null;
+    return { taskId: task.id, task };
+  } catch {
+    return null;
+  }
+}
+
+export async function readModifiedFilesFromHistory(
+  rootDir: string,
+  taskId: string,
+): Promise<string[]> {
+  try {
+    const historyPath = path.join(
+      rootDir,
+      ".omni",
+      "tasks",
+      `${taskId}.history.json`,
+    );
+    const history = JSON.parse(await readFile(historyPath, "utf8")) as Array<{
+      modifiedFiles?: string[];
+    }>;
+    return [...new Set(history.flatMap((entry) => entry.modifiedFiles ?? []))];
+  } catch {
+    return [];
+  }
+}
+
+export async function createBranch(
+  exec: ExecFn,
+  cwd: string,
+  branch: string,
+): Promise<boolean> {
+  const result = await exec("git", ["checkout", "-b", branch], { cwd });
+  return result.code === 0;
+}
+
+export async function stageFiles(
+  exec: ExecFn,
+  cwd: string,
+  files: string[],
+): Promise<boolean> {
+  if (files.length === 0) return false;
+  const result = await exec("git", ["add", ...files], { cwd });
+  return result.code === 0;
+}
+
+export async function commitChanges(
+  exec: ExecFn,
+  cwd: string,
+  message: string,
+): Promise<boolean> {
+  const result = await exec("git", ["commit", "-m", message], { cwd });
+  return result.code === 0;
+}
+
+export async function prepareCommitPlan(
+  rootDir: string,
+): Promise<CommitPlan | null> {
+  const completed = await readLastCompletedTask(rootDir);
+  if (!completed) return null;
+
+  const files = await readModifiedFilesFromHistory(rootDir, completed.taskId);
+  return {
+    branch: buildBranchName(completed.taskId),
+    message: buildCommitMessage(completed.task),
+    files,
+    taskId: completed.taskId,
+    prBody: generatePrBody(completed.task),
+  };
+}