ultimate-pi 0.1.0

package/PLAN.md

@@ -0,0 +1,11 @@
+# Plan
+
+## Harness execution model improvements
+1. Make harness mimic enterprise software engineering team execution.
+2. Require project wiki creation at project start.
+3. Require every design decision to be documented in wiki with rationale.
+4. Before code changes, require referencing relevant wiki design decisions/guidelines to maintain continuity.
+5. Reference https://handbook.gitlab.com/handbook/engineering/ while building the harness architecture.
+
+## Tracking note
+- New execution-model requirements are now tracked here for implementation.

package/README.md

@@ -0,0 +1,58 @@
+![Ultimate PI banner](.github/banner.png)
+
+> (Beta) The **ultimate AI coding harness** on top of [**pi.dev**](https://pi.dev).
+
+## Goal
+
+Ship a production-grade coding harness where the agent:
+1. uses compressed context before raw tool spam,
+2. stays concise and deterministic in output style,
+3. remains easy to extend with skills and extensions.
+
+### Included skills (upstream repositories)
+
+| Skill | Upstream repo | What it does |
+|---|---|---|
+| caveman | [juliusbrussee/caveman](https://github.com/juliusbrussee/caveman) | Ultra-compressed response style for token-efficient, high-signal communication. |
+| compress | [juliusbrussee/caveman](https://github.com/juliusbrussee/caveman) | Compresses memory/context files into caveman format while preserving technical content. |
+| lean-ctx | [yvgude/lean-ctx](https://github.com/yvgude/lean-ctx) | Context runtime and compression toolkit for reads/search/shell/edit flows. |
+| context7-cli | [upstash/context7](https://github.com/upstash/context7) | Pulls current library docs and manages Context7 skills/config from CLI. |
+| emil-design-eng | [emilkowalski/skill](https://github.com/emilkowalski/skill) | UI/design craftsmanship guidance: interaction polish, motion, and component quality. |
+| scrapling-official | [D4Vinci/Scrapling](https://github.com/D4Vinci/Scrapling) | Official Scrapling skill for web extraction/scraping with adaptive parsing, JS rendering, stealth fetchers, and anti-bot handling. |
+
+### Runtime guardrail extension
+
+- `extensions/lean-ctx-enforce.ts`
+  - Detects `lean-ctx` availability.
+  - Blocks built-ins (`read`, `write`, `edit`, `grep`, `find`, `ls`, raw `bash`) when `lean-ctx` exists.
+  - Allows shell only via `lean-ctx -c <command>`.
+  - Adds status commands:
+    - `/lean-ctx-status`
+    - `/system-prompt-status`
+
+## Design choices (concise)
+
+1. **Lean-ctx-first execution**  
+   Reason: cut context/token waste and keep tool usage structured.
+
+2. **Caveman-by-default response style**  
+   Reason: short, exact, low-noise outputs for coding loops.
+
+3. **Policy in system prompt + enforcement in extension**  
+   Reason: prompt sets intent; extension guarantees behavior.
+
+4. **Skill-based composition**  
+   Reason: easy to swap/upgrade capabilities without rewiring core package.
+
+5. **Model-agnostic compression path**  
+   Reason: `compress` skill calls PI CLI, so provider/model can change per environment.
+
+## Use locally
+
+From repo root:
+
+```bash
+pi install . -l
+```
+
+Then restart PI or run `/reload`.

package/extensions/lean-ctx-enforce.ts

@@ -0,0 +1,166 @@
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { readFile, stat } from "node:fs/promises";
+import { resolve } from "node:path";
+
+const GUARDED_TOOLS = new Set(["read", "write", "edit", "grep", "find", "ls", "bash"]);
+const CACHE_TTL_MS = 10_000;
+
+type LeanCtxState = {
+  checkedAt: number;
+  available: boolean;
+  bin?: string;
+};
+
+type SystemPromptCache = {
+  path: string;
+  mtimeMs: number;
+  text: string;
+};
+
+let cachedLeanCtx: LeanCtxState = {
+  checkedAt: 0,
+  available: false,
+};
+
+let cachedSystemPrompt: SystemPromptCache | undefined;
+
+async function detectLeanCtx(pi: ExtensionAPI): Promise<LeanCtxState> {
+  const now = Date.now();
+  if (now - cachedLeanCtx.checkedAt < CACHE_TTL_MS) return cachedLeanCtx;
+
+  try {
+    const result = await pi.exec(
+      "bash",
+      [
+        "-lc",
+        'if command -v lean-ctx >/dev/null 2>&1; then command -v lean-ctx; elif [ -x "$HOME/.local/bin/lean-ctx" ]; then echo "$HOME/.local/bin/lean-ctx"; else exit 1; fi',
+      ],
+      { timeout: 2000 },
+    );
+
+    cachedLeanCtx = {
+      checkedAt: now,
+      available: result.code === 0,
+      bin: result.code === 0 ? result.stdout.trim().split("\n")[0] : undefined,
+    };
+  } catch {
+    cachedLeanCtx = { checkedAt: now, available: false };
+  }
+
+  return cachedLeanCtx;
+}
+
+function bashUsesLeanCtx(command: string): boolean {
+  const trimmed = command.trim();
+  if (!trimmed) return false;
+  return /(^|\s|&&|\|\|)lean-ctx(\s|$)/.test(trimmed);
+}
+
+async function loadProjectSystemPrompt(cwd: string): Promise<string | undefined> {
+  const path = resolve(cwd, ".pi", "SYSTEM.md");
+
+  try {
+    const info = await stat(path);
+    if (cachedSystemPrompt && cachedSystemPrompt.path === path && cachedSystemPrompt.mtimeMs === info.mtimeMs) {
+      return cachedSystemPrompt.text;
+    }
+
+    const text = await readFile(path, "utf8");
+    const trimmed = text.trim();
+    if (!trimmed) return undefined;
+
+    cachedSystemPrompt = {
+      path,
+      mtimeMs: info.mtimeMs,
+      text: trimmed,
+    };
+    return trimmed;
+  } catch {
+    return undefined;
+  }
+}
+
+function pickVerificationMarker(promptText: string): string | undefined {
+  for (const line of promptText.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith("#")) continue;
+    if (trimmed.startsWith("- ")) continue;
+    if (trimmed.length < 12) continue;
+    return trimmed.slice(0, 120);
+  }
+  return undefined;
+}
+
+async function reportSystemPromptStatus(ctx: ExtensionContext): Promise<"missing" | "verified" | "uncertain"> {
+  const projectPrompt = await loadProjectSystemPrompt(ctx.cwd);
+  if (!projectPrompt) {
+    ctx.ui.notify(".pi/SYSTEM.md not found. Pi default system prompt active.", "warning");
+    return "missing";
+  }
+
+  const effectivePrompt = ctx.getSystemPrompt();
+  const marker = pickVerificationMarker(projectPrompt);
+  if (marker && effectivePrompt.includes(marker)) {
+    ctx.ui.notify(".pi/SYSTEM.md detected and present in effective system prompt.", "success");
+    return "verified";
+  }
+
+  ctx.ui.notify(".pi/SYSTEM.md found. Verification uncertain; reload and re-check.", "info");
+  return "uncertain";
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.on("session_start", async (_event, ctx) => {
+    const state = await detectLeanCtx(pi);
+    if (state.available) {
+      ctx.ui.notify(`lean-ctx enforcement active (${state.bin ?? "lean-ctx"})`, "info");
+    } else {
+      ctx.ui.notify("lean-ctx not found. Built-in tools allowed until installed.", "warning");
+    }
+
+    await reportSystemPromptStatus(ctx);
+  });
+
+  pi.registerCommand("lean-ctx-status", {
+    description: "Show lean-ctx enforcement status",
+    handler: async (_args, ctx) => {
+      cachedLeanCtx.checkedAt = 0;
+      const state = await detectLeanCtx(pi);
+      if (state.available) {
+        ctx.ui.notify(`lean-ctx available: ${state.bin ?? "lean-ctx"}. Built-ins blocked.`, "success");
+      } else {
+        ctx.ui.notify("lean-ctx unavailable. Built-ins currently allowed.", "warning");
+      }
+    },
+  });
+
+  pi.registerCommand("system-prompt-status", {
+    description: "Check .pi/SYSTEM.md replacement status",
+    handler: async (_args, ctx) => {
+      await reportSystemPromptStatus(ctx);
+    },
+  });
+
+  pi.on("tool_call", async (event) => {
+    if (!GUARDED_TOOLS.has(event.toolName)) return;
+
+    const state = await detectLeanCtx(pi);
+    if (!state.available) return;
+
+    if (event.toolName === "bash") {
+      const command = String((event.input as { command?: unknown })?.command ?? "");
+      if (bashUsesLeanCtx(command)) return;
+
+      return {
+        block: true,
+        reason: "Blocked by lean-ctx enforcement. Use `lean-ctx -c <command>` for shell commands.",
+      };
+    }
+
+    return {
+      block: true,
+      reason: `Blocked by lean-ctx enforcement. Use lean-ctx tools/flows instead of built-in \`${event.toolName}\`.`,
+    };
+  });
+}

package/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "ultimate-pi",
+  "version": "0.1.0",
+  "description": "Custom pi package starter with caveman and impeccable.style skills",
+  "keywords": [
+    "pi-package"
+  ],
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./extensions"
+    ],
+    "skills": [
+      "./.agents/skills"
+    ]
+  }
+}

package/skills-lock.json

@@ -0,0 +1,35 @@
+{
+  "version": 1,
+  "skills": {
+    "caveman": {
+      "source": "juliusbrussee/caveman",
+      "sourceType": "github",
+      "computedHash": "a818cdc41dcfaa50dd891c5cb5e5705968338de02e7e37949ca56e8c30ad4176"
+    },
+    "compress": {
+      "source": "juliusbrussee/caveman",
+      "sourceType": "github",
+      "computedHash": "05c97bc3120108acd0b80bdef7fb4fa7c224ba83c8d384ccbc97f92e8a065918"
+    },
+    "context7-cli": {
+      "source": "upstash/context7",
+      "sourceType": "github",
+      "computedHash": "525bfb31161c3f8866920a28fb2d9a3003a23b449aa8619b1b1add0da2cc3300"
+    },
+    "emil-design-eng": {
+      "source": "emilkowalski/skill",
+      "sourceType": "github",
+      "computedHash": "8bdf9e4e6de7a4969147bf4828a4ad2c5aacd9fba4b690b250a85e0467ca387d"
+    },
+    "lean-ctx": {
+      "source": "yvgude/lean-ctx",
+      "sourceType": "github",
+      "computedHash": "3d29c02c1c3928c838228cf11635c8041e52acc2e804ba2dd19450530a34c53e"
+    },
+    "scrapling-official": {
+      "source": "D4Vinci/Scrapling",
+      "sourceType": "github",
+      "computedHash": "af9bee8b531aa5b4d499eeebca66edb0224b1ed9b61540588765140628bd7ff2"
+    }
+  }
+}

package/wiki/README.md

@@ -0,0 +1,10 @@
+# Project Wiki
+
+## Purpose
+Track architecture and implementation decisions for this repo.
+
+## Decision log
+- [0001 - Establish project wiki and decision record format](decisions/0001-establish-project-wiki-and-decision-record-format.md)
+- [0002 - Add project banner to README](decisions/0002-add-project-banner-to-readme.md)
+- [0003 - Remove redundant README title heading when banner already contains title](decisions/0003-remove-redundant-readme-title-heading.md)
+- [0004 - Publish package to npm as ultimate-pi](decisions/0004-publish-package-to-npm-as-ultimate-pi.md)

package/wiki/decisions/0001-establish-project-wiki-and-decision-record-format.md

@@ -0,0 +1,25 @@
+# 0001 - Establish project wiki and decision record format
+
+- Date: 2026-04-25
+- Status: Accepted
+
+## Context
+Execution model requires project wiki and documented design decisions.
+No wiki existed in repository.
+
+## Alternatives
+1. Keep decisions in ad-hoc commit messages.
+2. Store decisions in a single PLAN.md section.
+3. Create dedicated wiki/ with ADR-style files.
+
+## Chosen option
+Create wiki/ with numbered decision files in wiki/decisions/.
+
+## Rationale
+- Gives stable place for all implementation decisions.
+- Scales better than one growing plan file.
+- Easy to reference before each code change.
+
+## Consequences
+- Every implementation change must cite relevant decision docs.
+- Small overhead: keep decision log updated.

package/wiki/decisions/0002-add-project-banner-to-readme.md

@@ -0,0 +1,26 @@
+# 0002 - Add project banner to README
+
+- Date: 2026-04-25
+- Status: Accepted
+
+## Context
+User requested adding .github/banner.png to README.md as project banner.
+README currently has no image banner.
+
+## Alternatives
+1. Keep no banner.
+2. Use HTML img tag for size/alignment control.
+3. Use standard Markdown image link.
+
+## Chosen option
+Use standard Markdown image syntax near top of README:
+![Ultimate PI banner](.github/banner.png)
+
+## Rationale
+- Minimal diff.
+- Renders on GitHub without extra HTML.
+- Keeps README portable and simple.
+
+## Consequences
+- Large image may dominate first screen on some displays.
+- Future size control would require switching to HTML tag.

package/wiki/decisions/0003-remove-redundant-readme-title-heading.md

@@ -0,0 +1,26 @@
+# 0003 - Remove redundant README title heading when banner already contains title
+
+- Date: 2026-04-25
+- Status: Accepted
+
+## Context
+README shows an H1 title and a banner image.
+Banner already contains the same project title text (Ultimate Pi).
+User requested removing redundant headings.
+
+## Alternatives
+1. Keep H1 and keep banner unchanged.
+2. Keep H1 and replace banner with non-title artwork.
+3. Remove H1 and keep banner as top title element.
+
+## Chosen option
+Remove top-level H1 from README and keep banner at top.
+
+## Rationale
+- Directly satisfies user request with minimal diff.
+- Avoids duplicate title presentation.
+- Preserves remaining README structure.
+
+## Consequences
+- README no longer has explicit Markdown H1.
+- Banner becomes primary title element.

package/wiki/decisions/0004-publish-package-to-npm-as-ultimate-pi.md

@@ -0,0 +1,26 @@
+# 0004 - Publish package to npm as ultimate-pi
+
+- Date: 2026-04-25
+- Status: Accepted
+
+## Context
+User requested npm publication under package name ultimate-pi.
+Current package metadata blocks publish (private true) and uses different name (ultimate-pi-package).
+
+## Alternatives
+1. Keep current package name and publish under existing metadata.
+2. Publish under scoped name (for example @owner/ultimate-pi).
+3. Rename package to ultimate-pi and remove publish block.
+
+## Chosen option
+Rename package.json name to ultimate-pi and remove private field so npm publish can succeed.
+
+## Rationale
+- Matches explicit user requirement.
+- Keeps package unscoped and discoverable.
+- Smallest metadata diff needed for publish.
+
+## Consequences
+- Package name must stay unique in npm registry.
+- Future publishes require version bumps.
+- Publish operation depends on local npm authentication.