When it doesn’t crash before answering, Gemini 4 Argon can give some useful answers. It’s not always the case, but sometimes it is. You can even throw an archive of files at it or point to a GitHub repo, and it could offer some valid advice. What it cannot do in this non-agentic usage is create files, but Argon is already very expensive as it is—it’s eating tokens like they’re peanuts! Below, you’ll find a thread with answers (some questions being suggested by it, so I just clicked on “Yes”) that stopped when my 5-hour quota was exhausted by this thread! 🙄

After reading someone write, “I am migrating my company to Pi with OpenRouter,” I got curious about exploring that solution. A quick search found this on GitHub Gist, but I wanted more: Setting Up PI Agent with OpenRouter.

One

Ludditus: Pi with OpenRouter: what are the ways one could use it? Costs? Usefulness for coding?

Argon:

Pairing Pi (@mariozechner/pi-coding-agent / pi.dev) with OpenRouter connects an extensible terminal coding harness to a unified API gateway of over 400 LLMs. While Pi runs as a lightweight Node.js tool on your machine or inside a container, OpenRouter handles model inference in the cloud (though Pi can also route to local models alongside it).

Ways to Use It (Local vs. Cloud)

  • Local CLI Execution (Standard): You install Pi locally via npm and run it directly in your terminal or inside an IDE’s integrated terminal (such as Cursor or VS Code). Pi executes bash commands, searches files (fd, ripgrep), and edits your local codebase directly while routing LLM prompts to OpenRouter in the cloud.
  • Sandboxed & Cloud Environments:Because Pi has full system access by default, many developers run it inside isolated containers or cloud sandboxes (like Docker or NVIDIA OpenShell).In a sandbox setup, you upload your project directory into the container and restrict network access so Pi can only reach openrouter.ai, keeping your host machine and real API keys isolated.
  • Hybrid Local + Cloud Models:Through Pi’s custom models.json configuration, you can mix cloud models from OpenRouter with completely local models running on your hardware (via Ollama, vLLM, or LM Studio).You can hot-swap between them mid-session using /model or Ctrl+P.
  • Headless & Embedded Modes:Beyond the interactive terminal UI, Pi runs in JSON streaming mode, RPC mode for process integration, or as an SDK embedded inside custom automation pipelines and CI/CD workflows.

Costs

  • Pi Software: Free and open-source (MIT license).
  • OpenRouter Platform Fee:OpenRouter charges a 5.5% fee on Pay-As-You-Go credit purchases (8% for Business tiers) and passes through raw token costs at the model provider’s market rate with no per-token markup.
  • Zero-Cost Option:OpenRouter offers 25+ :free model variants (up to 50 requests/day on a zero-balance account, or higher with credits loaded) alongside its free openrouter/auto-code router.
  • Paid Token Rates:Costs scale entirely by the models you select. High-speed coding models like DeepSeek V4.1 Flash cost roughly $0.03–$0.15 per 1M input tokens and $0.12–$0.60 per 1M output tokens, whereas frontier reasoning models like Claude Sonnet 5.5 or Claude Opus 5.5 run $2–$4 per 1M input tokens and $10–$20 per 1M output tokens.

Usefulness for Coding

Pi is one of the top five most active coding agents on OpenRouter because its design solves several common frustrations with rigid AI coding tools:

  • Mid-Session Model Switching & Tree Branching:You can use a cheap, fast model (like DeepSeek Flash or Gemini Flash) to explore a repository and run grep searches, then press Ctrl+L to switch to a heavy hitter (like Claude Opus or GPT-6) for complex architectural refactoring—all within the same context window. If an approach fails, /tree and /fork let you rewind to an earlier turn and branch off without losing history.
  • Minimalist, Hackable Architecture:Instead of hiding logic inside black-box sub-agents or complex MCP servers, Pi relies on composable CLI scripts, hierarchical AGENTS.md context files, and TypeScript extensions.
  • OpenRouter-Specific Extensions:The Pi ecosystem includes dedicated packages like pi-openrouter-realtime (which adds live endpoint latency/uptime metrics, provider quantization picking, and /openrouter-balance checks without polluting your prompt context) and pi-openrouter-session (which groups your multi-turn agent runs cleanly in the OpenRouter activity dashboard).

Two

Ludditus: So what is Pi, actually, and how to use it? How to configure it?

Argon:

Pi (pi.dev, originally built by Mario Zechner and maintained under earendil-works/pi) is a minimalist, open-source terminal coding harness written in TypeScript.It rejects the bloat of heavy agent frameworks by operating on a strict philosophy: frontier models already know how to code and reason, so the harness shouldn’t get in the way with bloated system prompts or rigid workflows.

What Pi Actually Is (Core Architecture)

  • The Four-Tool Substrate:Out of the box, Pi uses a sub-1,000-token system prompt and gives the LLM exactly four tools: read (inspect files), write (create files), edit (apply targeted surgical diffs), and bash (execute shell commands).You can also optionally enable codemode for programmatic tool execution.
  • Deliberate Omissions:By default, Pi has no built-in sub-agents, no forced “Plan Mode,” no hidden RAG indexers, and no constant permission popups (it assumes you either trust the environment or run it inside a container/sandbox).
  • Opt-In Extensibility:Anything left out of the core can be bolted on via four layers: Extensions (TypeScript modules that can intercept turns, filter context, or add UI elements), Skills (/skill:name loaded on demand), Prompt Templates (/templatename), and MCP servers.

How to Install & Use It

Install Pi globally via its install script or npm:

curl -fsSL https://pi.dev/install.sh | sh
# Or via npm:
npm install -g @earendil-works/pi

Navigate to any project directory and run pi to launch the terminal UI (which displays the conversation, an input editor, and a status footer showing your git branch, active model, thinking level, and token/context usage).

  • Keybindings:
    • Ctrl+L (or /model): Open the interactive model selector (Ctrl+S inside the menu saves a model as your new default).
    • Ctrl+P: Fast-cycle through your favorite “scoped” models mid-conversation.
    • Shift+Tab (or /thinking): Cycle the model’s reasoning/thinking effort level.
  • Essential Slash Commands:
    • /login: Authenticate with providers interactively.
    • /scoped-models: Define the shortlist of models that Ctrl+P cycles through.
    • /tree & /fork: View the session’s conversation tree, jump back to an earlier turn before a bad refactor, and branch off cleanly without polluting your context window.
    • /new & /resume: Start fresh or resume a previous session (or launch directly from bash with pi -c to continue the last session, or pi -r to browse history).
    • /reload: Hot-reload configuration files, extensions, and instructions without restarting.

How to Configure It

Pi splits configuration between your global user directory (~/.pi/agent/) and project-local overrides (.pi/ in your repo root).

1. Authentication (~/.pi/agent/auth.json)

While Pi reads environment variables like OPENROUTER_API_KEY, storing credentials in auth.json takes priority and keeps keys out of your shell profile:

{
  "openrouter": {
    "type": "api_key",
    "key": "sk-or-v1-your-key-here"
  }
}

2. Preferences & Defaults (~/.pi/agent/settings.json)

Controls your default model, tools, and installed packages (can also be tweaked via /settings in the TUI):

{
  "defaultProvider": "openrouter",
  "defaultModel": "anthropic/claude-sonnet-4",
  "defaultTools": ["read", "write", "edit", "bash"],
  "packages": [
    "npm:pi-openrouter-session"
  ]
}

3. Custom & Local Endpoints (~/.pi/agent/models.json)

Used to register local servers (Ollama, vLLM, llama.cpp), custom OpenAI-compatible proxies, or specific model metadata overrides (such as custom context limits, pricing, or OpenRouter provider routing rules). Opening /model reloads this file in real time. (Note: Pi also has a built-in /llama command that connects directly to the llama.cpp router to load local GGUF files on demand.)

4. System Prompt & Context Hierarchy (AGENTS.md & SYSTEM.md)

Pi automatically discovers and concatenates AGENTS.md (or CLAUDE.md) files from three locations on startup:

  1. Global user rules (~/.pi/agent/AGENTS.md) — great for global coding style, formatting rules, and tool preferences.
  2. Parent directories walking up from your current working directory.
  3. The current project root (./AGENTS.md) — for build commands, test runners, and architecture notes.

If you want to completely replace Pi’s default system prompt or append directly to it without using AGENTS.md, you can drop a SYSTEM.md or APPEND_SYSTEM.md file into ~/.pi/agent/ or your project’s .pi/ folder.

Three

Ludditus: What is an MCP Server (Model Context Protocol Server), and what alternatives could replace Pi?

Argon:

An MCP Server (Model Context Protocol Server) is not a standalone coding agent like Pi, but rather a standardized backend plugin that gives an AI client access to local tools, files, and external APIs.

Introduced by Anthropic as an open standard, MCP uses JSON-RPC 2.0 messages (running locally over stdio pipes or remotely over HTTP/SSE) to connect three components:

  1. MCP Host / Client: The user-facing interface that holds the conversation and talks to the LLM (such as Claude Desktop, Cursor, Zed, LibreChat, or Pi itself).
  2. MCP Protocol: The standardized wire format for negotiating capabilities and passing tool calls.
  3. MCP Server: A lightweight process (written in Python, TypeScript, Rust, or Go) that exposes Tools (functions the LLM can execute), Resources (files or data streams the LLM can read), and Prompts (reusable templates).

Why Pi and MCP Differ Architecturally
When an AI client connects to multiple MCP servers on startup, those servers typically inject all of their JSON tool schemas directly into the LLM’s context window—often consuming 5,000 to 20,000+ tokens before you even send a prompt. Pi was built as a direct reaction against this overhead: it keeps its system prompt under 1,000 tokens with just four built-in tools (read, write, edit, bash) and expects the model to run standard CLI tools or load skills only when needed.

How to Replace Pi: Two Distinct Approaches

Because an MCP server only provides the tools rather than the interface, replacing Pi means either pairing a coding MCP server with a general AI client, or switching to an alternative terminal agent harness.

SolutionCategoryCore MechanismOpenRouter SupportBest For
wcgwMCP ServerShell + file edit via stdioVia Host ClientTurning chat apps into local agents
SerenaMCP ServerLSP semantic code navigationVia Host ClientLarge monorepo symbol refactoring
Desktop CommanderMCP ServerTerminal + diff search/replaceVia Host ClientLocal OS & file control in GUI chats
Oh My Pi (omp)CLI HarnessRust-native Pi fork + LSP/DAPNativeBatteries-included Pi with sub-agents
AiderCLI HarnessGit-centric diff & repo-mapNativeAutomated Git commits & Architect mode
OpenCodeCLI HarnessTUI agent with built-in LSPNativePolished terminal UI & session sharing
GooseCLI / DesktopMCP-native agent frameworkNativeWorkflows built entirely around MCP

Approach 1: Any MCP Client + Coding MCP Servers (The Pure MCP Route)
If you already use an MCP-compatible interface (like Claude Desktop, OpenWebUI, LibreChat, or Zed) and want it to edit code and run shell commands like Pi:

  • wcgw (“What Could Go Wrong”): A Python MCP server (uvx wcgw@latest) that replicates Pi’s core capabilities inside any chat client. It runs a persistent screen terminal multiplexer in the background for shell commands, enforces read-before-write file protections, includes a ContextSave checkpoint tool, and offers three safety modes (architect for read-only planning, code-writer for path-restricted edits, and unrestricted wcgw).
  • Serena (oraios/serena): While Pi relies on text search (ripgrep) and line-based edits, Serena is an MCP server that spins up real Language Server Protocol (LSP) backends across 40+ languages. It gives any MCP client IDE-level tools like find_symbol, find_references, rename_symbol, and replace_symbol_body, allowing the LLM to refactor code by AST symbol rather than reading entire files.
  • Desktop Commander (@wonderwhy-er/desktop-commander): Extends the standard MCP Filesystem server with surgical search-and-replace diff blocks and long-running background process control over stdio.

Approach 2: Alternative CLI Agent Harnesses (Direct Pi Replacements)
If you want a standalone terminal agent that connects directly to OpenRouter or local models without needing a separate GUI host:

  • Oh My Pi (omp / can1357/oh-my-pi): Created by Can Bölük, omp is a direct fork of Pi designed for users who want Pi’s workflow without having to build everything from scratch. It replaces external shell-outs with 30+ built-in Rust-native tools, adds native LSP and Debugger (DAP) integration, supports multi-role model routing (default, smol, slow, plan), includes project-scoped memory (retain, recall, reflect), and automatically reads existing AGENTS.md, .claude, and .cursor configurations.
  • Aider: The most mature Python CLI coding tool. Instead of giving the model raw bash autonomy by default, Aider builds a compressed Tree-sitter repository map of your codebase, applies changes via surgical edit formats, automatically commits every change to Git with a descriptive message (making /undo trivial), and popularized the two-model Architect/Editor pattern (using a frontier reasoning model to plan changes and a cheap, fast model to write the file diffs).
  • OpenCode: An open-source terminal agent with a multi-pane TUI, built-in LSP diagnostics, client-server process separation, and first-class OpenRouter support.
  • Goose (block/goose): Block’s open-source terminal and desktop agent built specifically around MCP. Every capability in Goose is an MCP server, making it the strongest choice if you want a CLI agent that treats MCP plugins as its native architecture.

ℹ️ Here’s the visual included by Argon, which I found more annoying than useful:

Explore the architectural comparison below to step through how a direct CLI harness (like Pi) executes tool calls compared to an MCP Host + Server setup: 👉 share.gemini.google/Vgp3ewjmYtx1

Four

Ludditus: I know how to use Oh My Pi (omp) more like Antigravity CLI (agy) or  Qwen Code CLI (qwen). Give me some quick hints on how to use it to coordinate agents in a smarter way. Is it more appropriate than Goose, which I believe is overrated?

Then, recommend me some SKILL.md skills, in 2 scenarios:
1). Oh My Pi.
2). Antigravity IDE or CLI.

With Antigravity, possible use cases (albeit naive):

  • The context is filling, and Gemini Flash could trigger an automatic compaction. The result might ruin my session, so I’d like to be able to invoke a skill that would create a MEMORY.md with the most relevant requests from me and changed by the agent, other than those saved into PLAN.md.
  • As a variant, suppose PLAN.md holds the relevant data regarding the implementation of a new feature requested through PLAN.md and whose steps’ implementation and testing are written there. But at the prompt, I added requests regarding newly discovered bugs and regressions, and PLAN.md might not refer to them in any way. A MEMORY.md might help.

What other basic SKILL.md skills would be recommended for software development?

What basic SKILL.md skills would be recommended for use with Pi or Oh My Pi?

Argon:

An MCP Server (Model Context Protocol Server) does not replace a coding harness by itself; instead, you either pair coding MCP servers (like wcgw for shell/file control or Serena for LSP symbol refactoring) with an MCP client, or you use a standalone terminal harness like Pi, Oh My Pi (omp), Antigravity CLI (agy), Qwen Code (qwen), or Aider.

1. Is Oh My Pi (omp) More Appropriate Than Goose?

Your skepticism about Goose is well-founded. Goose is architected around the premise that every capability should be an MCP server. In practice, that design introduces three bottlenecks for serious software engineering:

  1. Upfront Context Tax: Loading multiple MCP servers dumps thousands of tokens of JSON tool schemas into your system prompt on turn 1—accelerating the exact context-window exhaustion and compaction decay you are trying to avoid.
  2. IPC & Process Overhead: Every file read, grep search, or shell command gets serialized over JSON-RPC pipes to external processes.
  3. Loose Coordination: Sub-tasks in Goose lack tight IDE-level symbol awareness and isolated git workspace primitives.

Why omp is far stronger for coding:
Rather than routing basic operations through external MCP wrappers, omp compiles over 30 core tools—including ripgrep, glob, find, a persistent bash 5.3 engine with 58 built-in Unix utilities, an LSP client, and a DAP debugger (lldb, dlv, debugpy)—directly in-process in Rust with zero fork/exec overhead. Furthermore, omp natively inherits existing configurations and skills from .agents/skills/, .claude, .cursor, and .gemini without requiring migration.

2. How to Coordinate Agents Smarter in Oh My Pi (omp)

If you are currently driving omp like a single-threaded CLI (agy or qwen), you are only using half of its engine. Use these five mechanisms to turn omp into a multi-agent orchestrator:

  • Multi-Role Model Routing (default, smol, slow, plan, advisor): Configure omp to route distinct cognitive tasks to different models automatically. Bind smol to a fast, cheap model (e.g., Qwen3-Coder, DeepSeek Flash, or Gemini Flash) for repository exploration and file reads; bind plan and slow to a high-reasoning model for architecture and gnarly bug triage; keep your balanced coder as default.
  • Parallel Subagents in Isolated Worktrees (task tool): When you ask omp to use its task tool, it doesn’t just spawn chatty sub-prompts in the same directory. It fans workers out into isolated Git worktrees, gives each worker a scoped tool surface, and forces them to return a schema-validated typed object to the parent agent. Sibling agents cannot overwrite each other’s files or cause dirty-tree merge conflicts.
  • Live Steering via the Agent Hub (Alt+A): Press Alt+A while subagents are running to open the Agent Hub TUI. You get a live roster showing each worker’s status (running, idle, parked, aborted), model role, token cost, and patch path. You can press Enter on any worker to inspect its live transcript, inject a mid-flight steering message, switch its model (Ctrl+P), or revive a killed/parked worker directly from its on-disk JSONL transcript.
  • The advisor Watchdog Role (/advisor): Instead of burning main-session context asking the agent to double-check itself, enable a second model in the advisor role (/advisor on or configured via WATCHDOG.md). The advisor runs in a separate, bounded context window and receives a compact per-turn digest (your prompt, unified diffs up to 200 lines, and failed tool errors—excluding raw file dumps). When the main agent rushes past an edge case or violates PLAN.md, the advisor injects an inline warning or hard blocker before the mistake cascades.
  • Time-Traveling Stream Rules & Subagent autoloadSkills: You can define dormant regex stream rules in omp that sit at zero token cost until the model outputs a forbidden pattern—at which point omp aborts the stream mid-token, injects the rule reminder, and retries from that exact token. For subagents managed via /agents, use the autoloadSkills frontmatter property so specialized SKILL.md packs are injected only into the worker subagent that needs them, keeping your parent context lean.

3. Solving the PLAN.md vs. MEMORY.md Problem in Antigravity (agy & IDE)

Your two Antigravity use cases are not naive at all—they target the two most common failure modes in long agentic coding sessions: compaction amnesia (where automatic summarization flattens critical constraints) and plan-vs-reality drift (where PLAN.md stays static while live prompts address regressions and out-of-band bugs).

Both Antigravity and Pi / Oh My Pi follow the open Agent Skills specification:

  • Shared Project Scope: .agents/skills/<skill-name>/SKILL.md (discovered automatically by both agy and omp/pi).
  • Antigravity Global Scope: ~/.gemini/config/skills/<skill-name>/SKILL.md.
  • Pi / omp Global Scope: ~/.agents/skills/<skill-name>/SKILL.md or ~/.pi/agent/skills/.

At startup, the agent only loads the YAML name and description (~30 tokens) into the system prompt, reading the full SKILL.md body only when triggered automatically or invoked via /skills or /skill:<name>.

Skill 1: Pre-Compaction Delta Snapshot (compaction-guard)

Save this to .agents/skills/compaction-guard/SKILL.md. It prevents Gemini Flash compaction from wiping out your ad-hoc requests and file changes that live outside PLAN.md.

---
name: compaction-guard
description: Snapshot unplanned user requests, architectural pivots, and out-of-band code modifications into MEMORY.md before context compaction or session handoff. Use when requested to save session state, update MEMORY.md, or prepare for compaction.
---

# Compaction Guard & Delta Memory Snapshot

Your goal is to preserve high-signal session state in `MEMORY.md` **without duplicating** what is already documented in `PLAN.md`.

## Execution Steps
1. **Read Baseline:** Read `PLAN.md` (if present) and the existing `MEMORY.md` (if present).
2. **Inspect Real Workspace State:** Run `git status -s` and `git diff --stat` (plus targeted `git diff` on modified files) to verify what code has actually changed versus what was merely discussed.
3. **Extract the Delta:** Identify every item from the current conversation and working tree that is **NOT** explicitly captured in `PLAN.md`:
   - Ad-hoc user constraints, coding style corrections, or rejected approaches ("Do NOT do X").
   - Unplanned file edits, hotfixes, or refactoring side-effects.
   - Open questions or half-finished debugging threads.
4. **Write `MEMORY.md`:** Create or update `MEMORY.md` using the exact structure below. Keep entries terse, factual, and anchored to file paths and symbol names.

## Required `MEMORY.md` Template
### 1. Active User Constraints & Guardrails (Not in PLAN.md)
- Bullet list of explicit user instructions, preferences, and forbidden patterns established during chat.

### 2. Out-of-Band Code Changes (Delta vs. PLAN.md)
- `path/to/file.ext` (`symbol_or_function`): Why it was modified outside the main plan and current verification status.

### 3. Rejected Approaches & Dead Ends
- What was tried or proposed, why it failed or was rejected by the user, and why future turns post-compaction must not repeat it.

### 4. Immediate Next Action Post-Compaction
- Exact command or file/line target to resume from immediately after context compaction or `/rewind`.

Skill 2: Ad-Hoc Bug & Regression Ledger (regression-ledger)

Save this to .agents/skills/regression-ledger/SKILL.md. It addresses your second scenario: keeping PLAN.md clean as the feature roadmap while tracking newly discovered bugs and regressions in MEMORY.md.

---
name: regression-ledger
description: Track and triage newly discovered bugs, test failures, and regressions in MEMORY.md without polluting the feature roadmap in PLAN.md. Trigger whenever the user reports a bug, regression, or unexpected side-effect mid-implementation.
---

# Bug & Regression Delta Ledger

When the user reports a bug or regression during feature work, **do not rewrite `PLAN.md`** unless the core feature architecture is invalidated. Instead, log and track the defect inside `MEMORY.md`.

## Workflow
1. **Cross-Reference `PLAN.md`:** Check which planned step in `PLAN.md` was active when the regression surfaced.
2. **Isolate the Defect:** Before editing implementation code, record the regression in `MEMORY.md` under `## Regression & Bug Ledger`.
3. **Verify & Update:** Once fixed and verified with a test command, mark the entry `[RESOLVED]` in `MEMORY.md` and note the exact regression test added so `PLAN.md` execution can resume safely.

## Entry Format in `MEMORY.md`
- **[OPEN | RESOLVED] Bug ID / Short Title** (Discovered during `PLAN.md` Step X)
  - **Symptom / Prompt Report:** Exact failure observed by the user.
  - **Root Cause & Location:** `file:line` (`symbol`) and causal mechanism.
  - **Fix Applied:** Surgical summary of the change.
  - **Verification Command:** Exact test/build command executed to prove no regression remains.

4. Recommended SKILL.md Skills by Scenario

Because skills are markdown workflows with optional scripts in scripts/ and reference docs in references/, the best setup separates platform-specific orchestration skills from universal software engineering skills.

Skill NameTarget EnvironmentTrigger ModePrimary Purpose
compaction-guardAntigravity (agy) & ompManual / PromptDiffs live session & git diff against PLAN.md into MEMORY.md
regression-ledgerAntigravity (agy) & ompAuto on bug reportTracks ad-hoc bugs/regressions in MEMORY.md separately from PLAN.md
worktree-fanoutOh My Pi (omp)Manual (/skill:)Dispatches parallel task subagents in worktrees with typed JSON schemas
dap-crash-triageOh My Pi (omp)Auto on crash/hangForces native debug (DAP) + lsp inspection instead of print debugging
memory-bank-syncPi / Oh My Pi (omp)Manual (/skill:)Syncs omp‘s native retain/recall/reflect bank with MEMORY.md
surgical-refactorUniversal (.agents/skills/)Auto on refactorEnforces LSP/grep reference checks and zero unrelated diff noise
test-first-fixUniversal (.agents/skills/)Auto on bugfixMandates a failing reproduction test before modifying target source

Scenario 1: Skills Specifically for Pi and Oh My Pi (omp)

  1. worktree-fanout (Parallel Subagent Coordinator for omp):
  • Why: Models often underutilize omp‘s task tool or pass vague prose prompts to subagents.
  • What to put in SKILL.md: Instruct the parent agent to break independent module changes into parallel task calls using isolated worktrees, require a strict JSON output schema (modified_files, test_exit_code, summary, blockers), and automatically run /review across the resulting diffs before merging. Set disable-model-invocation: true in the frontmatter so it only fires when you explicitly type /skill:worktree-fanout.
  1. dap-crash-triage (Debugger-First Fault Isolation for omp):
  • Why: Even with omp‘s built-in DAP debugger, LLMs instinctively fall back to adding print() or console.log() statements.
  • What to put in SKILL.md: Forbid adding temporary logging statements when investigating segfaults, exceptions, or hangs. Instruct the agent to attach omp‘s native debug tool (debugpy, lldb, or dlv), set a breakpoint at the suspect symbol located via lsp, inspect local frame variables, and detach cleanly.
  1. memory-bank-sync (Bridging omp Native Memory with MEMORY.md):
  • Why: omp includes built-in memory tools (retain, recall, reflect, memory_edit), while your cross-agent workflow with agy and qwen relies on markdown files (PLAN.md and MEMORY.md).
  • What to put in SKILL.md: Instruct omp to dump its internal recall/reflect observations into MEMORY.md at the end of a milestone so that if you switch to agy or qwen on the same repository, the next CLI immediately sees the updated state.

Scenario 2: Skills Specifically for Antigravity IDE / CLI (agy)

  1. explore-plan-verify (Strict 3-Phase Execution Gate):
  • Why: Antigravity performs best when exploration, planning, and execution are separated, especially when using faster models that jump straight into editing files.
  • What to put in SKILL.md: Enforce a strict state machine:
  • Phase 1 (Explore): Read-only symbol search and file inspection.
  • Phase 2 (Plan): Update PLAN.md with exact file paths, function signatures, and verification commands; halt for user approval if architectural scope changed.
  • Phase 3 (Execute & Verify): Apply edits, run the local test suite/linter, and update MEMORY.md if any unplanned edge case was discovered.
  1. context-hygiene-reader (Preventing Early Context Bloat):
  • Why: Prevents the context window from filling up prematurely in agy so Gemini Flash compaction is delayed as long as possible.
  • What to put in SKILL.md: Forbid reading entire files larger than 250 lines when searching for a definition. Require running line-numbered rg -n first, followed by ranged file reads around the target lines, and summarizing findings into MEMORY.md if more than 5 files are inspected.

General Software Development SKILL.md Essentials (Portable across .agents/skills/)

  • surgical-refactor: Instructs the agent to find all callers before changing any function signature, preserve existing indentation/formatting outside changed lines, avoid drive-by rewrites or unsolicited docstrings, and verify that imports/exports remain clean.
  • test-first-bugfix: Requires the agent to write or update a minimal failing unit test that reproduces the reported bug before modifying the implementation code, run the single test file (not the entire slow suite) to confirm the red-to-green transition, and record the test command.
  • git-atomic-commit: Reviews git diff, separates unrelated bugfixes from feature work into distinct atomic commits, and formats commit messages according to Conventional Commits without touching unstaged experimental files.

Five

Ludditus: I want the full SKILL.md files for all skills you named, but only summarized.

Argon:

Each SKILL.md file below follows the open Agent Skills specification—requiring a name that matches its parent directory name and a trigger-rich description in the YAML frontmatter—while keeping the procedural Markdown body distilled to minimal token overhead when loaded into context. Save each file to .agents/skills/{skill-name}/SKILL.md for shared project use across Oh My Pi (omp) and Antigravity (agy).

1. Session & State Management (PLAN.md + MEMORY.md)

.agents/skills/compaction-guard/SKILL.md

---
name: compaction-guard
description: Snapshot unplanned user requests, architectural pivots, and out-of-band code edits into MEMORY.md before context compaction. Use when asked to save session state, update MEMORY.md, or prepare for compaction.
---

# Compaction Guard (Delta Snapshot)

Preserve high-signal session state in `MEMORY.md` without duplicating `PLAN.md`.

1. **Diff Reality:** Read `PLAN.md` and `MEMORY.md`. Run `git status -s` and `git diff --stat` to verify actual code changes.
2. **Extract Delta:** Filter for items NOT in `PLAN.md` (user constraints, rejected approaches, unplanned file edits, active debugging state).
3. **Update `MEMORY.md`:** Write terse bullets under four headers:
   - `## Active Constraints & Guardrails` (Explicit user rules/preferences from chat)
   - `## Out-of-Band Code Changes` (`file:symbol` + reason + verification status)
   - `## Rejected Approaches` (What failed or was vetoed—do not repeat)
   - `## Next Immediate Action` (Exact file, symbol, or command to resume post-compaction)

.agents/skills/regression-ledger/SKILL.md

---
name: regression-ledger
description: Log and track newly discovered bugs, regressions, and test failures in MEMORY.md without cluttering PLAN.md. Use whenever the user reports a bug, regression, or unexpected side-effect mid-implementation.
---

# Bug & Regression Ledger

Keep `PLAN.md` focused on the feature roadmap; track ad-hoc defects in `MEMORY.md`.

1. **Log Before Fixing:** Record the defect under `## Regression Ledger` in `MEMORY.md`, noting which `PLAN.md` step was active.
2. **Isolate & Fix:** Identify `file:line` (`symbol`), apply the minimal fix, and run a targeted verification command.
3. **Update Ledger:** Mark `[OPEN]` or `[RESOLVED]` using this compact entry format:
   - `[STATUS] Short Title (PLAN.md Step X)` — **Symptom:** ... | **Cause:** `file:line` | **Fix:** ... | **Verified:** `command`

2. Oh My Pi (omp) Specific Skills

.agents/skills/worktree-fanout/SKILL.md

(Uses disable-model-invocation: true so it only triggers when you explicitly run /skill:worktree-fanout.)

---
name: worktree-fanout
description: Coordinate parallel subagents across isolated Git worktrees using the omp task tool and typed output schemas. Invoke manually via /skill:worktree-fanout for multi-module changes.
disable-model-invocation: true
---

# Parallel Worktree Fanout (omp)

1. **Partition by Boundary:** Split the task into independent work units with zero overlapping file writes.
2. **Dispatch Isolated Workers:** Spawn parallel `task` subagents in isolated worktrees. Assign `smol` to discovery tasks and `default`/`slow` to implementation tasks.
3. **Enforce Output Schema:** Require every worker to return a JSON summary: `{ "modified_files": [], "verification_cmd": "", "exit_code": 0, "blockers": [] }`.
4. **Verify Before Merge:** Inspect each worker's unified diff for cross-module signature conflicts and run integration tests before merging worktrees.

.agents/skills/dap-crash-triage/SKILL.md

---
name: dap-crash-triage
description: Diagnose crashes, exceptions, hangs, and logic bugs using native DAP debugger and LSP tools instead of print debugging. Use when debugging failing tests, segfaults, or runtime errors in omp.
---

# Debugger-First Triage (omp)

Do NOT insert temporary `print`, `printf`, or `console.log` statements to diagnose bugs.

1. **Locate Symbol:** Use the native `lsp` tool to find the exact definition, callers, and line numbers of the suspect function.
2. **Attach DAP Debugger:** Launch the native `debug` tool (`debugpy`, `lldb`, or `dlv`) on the failing test or binary.
3. **Inspect State:** Set a conditional breakpoint prior to the fault, step through execution, inspect local frame variables/call stack, and detach cleanly before editing code.

.agents/skills/memory-bank-sync/SKILL.md

---
name: memory-bank-sync
description: Synchronize omp internal memory tools (retain, recall, reflect) with project-root MEMORY.md and PLAN.md files for cross-CLI portability. Use before switching between omp, agy, or qwen.
---

# Cross-CLI Memory Bank Sync

Bridge `omp` internal memory with portable Markdown files (`MEMORY.md` / `PLAN.md`).

1. **Ingest:** Read `MEMORY.md` and `PLAN.md`; call `retain` / `memory_edit` on new architectural invariants so `omp` subagents inherit them.
2. **Export:** Run `recall` and `reflect` to extract learned repo conventions, build quirks, and unresolved bugs discovered during the `omp` session.
3. **Persist:** Append any missing high-signal findings into `MEMORY.md` so external CLIs (`agy`, `qwen`) have immediate parity.

3. Antigravity (agy & IDE) Specific Skills

.agents/skills/explore-plan-verify/SKILL.md

---
name: explore-plan-verify
description: Enforce a strict 3-phase Explore, Plan, and Verify gate synchronized with PLAN.md and MEMORY.md. Use when implementing multi-file features or architectural changes in Antigravity.
---

# Explore -> Plan -> Verify Gate

Never jump straight from prompt to file edits on multi-file tasks.

1. **Phase 1 (Explore):** Perform read-only symbol/grep searches. Identify affected files, types, and existing tests.
2. **Phase 2 (Plan):** Update `PLAN.md` with discrete steps, target `file:symbol` paths, and exact verification commands. Pause for user confirmation if scope expanded.
3. **Phase 3 (Execute & Verify):** Apply surgical edits one step at a time, run the verification command after each step, check off the item in `PLAN.md`, and log any unplanned side-effects in `MEMORY.md`.

.agents/skills/context-hygiene-reader/SKILL.md

---
name: context-hygiene-reader
description: Minimize context window bloat during codebase exploration to prevent premature Gemini Flash compaction. Use whenever searching or inspecting unfamiliar files across a repository.
---

# Context-Hygiene File Reader

Prevent raw file dumps from exhausting the active context window.

1. **Grep First:** Never read a file over 200 lines from top to bottom to locate a symbol. Run `rg -n` or LSP symbol lookup first.
2. **Ranged Reads Only:** Read only a 40-to-80 line window around the target line number.
3. **Evict to Disk:** If exploration spans more than 5 files, write a 5-bullet architectural map (`file:line` -> responsibility) into `MEMORY.md` instead of re-reading those files in later turns.

4. Universal Software Development Skills

.agents/skills/surgical-refactor/SKILL.md

---
name: surgical-refactor
description: Execute minimal-diff, behavior-preserving code refactorings with full caller verification. Use when asked to refactor, rename, extract, or clean up existing code.
---

# Surgical Refactor

1. **Map All Callers:** Before changing any signature, struct, or export, find every reference across the repo via LSP or `rg`.
2. **Zero Diff Noise:** Preserve surrounding indentation, comments, and import ordering. Never mix formatting rewrites, unsolicited docstrings, or unrelated cleanups into a refactor diff.
3. **Verify Parity:** Run existing unit tests and typecheckers/compilers immediately after applying the edit.

.agents/skills/test-first-bugfix/SKILL.md

---
name: test-first-bugfix
description: Enforce a red-to-green reproduction test workflow before modifying production source code. Use when fixing bugs, edge cases, or broken behavior.
---

# Test-First Bugfix

1. **Reproduce (Red):** Write or update a minimal automated test that reproduces the exact bug and run *only* that test target to confirm it fails for the expected reason.
2. **Fix (Green):** Apply the smallest possible production code change to make the failing test pass.
3. **Guard:** Re-run the single test plus the immediate module test suite, then log the verification command in `MEMORY.md` if discovered mid-feature.

.agents/skills/git-atomic-commit/SKILL.md

---
name: git-atomic-commit
description: Stage and commit changes in logical, atomic units using Conventional Commits without sweeping in unrelated or untracked files. Use when asked to commit, stage, or prepare git history.
---

# Git Atomic Commit

1. **Audit Working Tree:** Run `git status -s` and `git diff`. Never use `git add .` or `git add -A`.
2. **Separate Concerns:** Stage files explicitly (`git add path/to/file`) so bugfixes, refactors, and features are split into distinct atomic commits. Leave temporary files and `MEMORY.md` unstaged unless requested.
3. **Format Message:** Write a concise Conventional Commit message (`feat|fix|refactor|test|chore(scope): imperative summary under 72 chars`).

Six

Ludditus: Give me a single bash script that creates the .agents/skills directories and writes all 10 summarized SKILL.md files automatically.

Argon:

This single-file bash script scaffolds all 10 skill directories and writes each SKILL.md file using single-quoted heredocs ('EOF') so backticks and Markdown formatting are preserved verbatim without shell expansion. Each generated file adheres to the Agent Skills specification by matching the YAML name field to its parent directory name and defining explicit trigger conditions in description.

Save this as install-skills.sh and run bash install-skills.sh for project-local setup (.agents/skills), or pass a target path like bash install-skills.sh ~/.agents/skills to install them globally:

#!/usr/bin/env bash
set -euo pipefail

BASE_DIR="${1:-.agents/skills}"

echo "Scaffolding 10 Agent Skills into: ${BASE_DIR}"

# 1. compaction-guard
mkdir -p "${BASE_DIR}/compaction-guard"
cat << 'EOF' > "${BASE_DIR}/compaction-guard/SKILL.md"
---
name: compaction-guard
description: Snapshot unplanned user requests, architectural pivots, and out-of-band code edits into MEMORY.md before context compaction. Use when asked to save session state, update MEMORY.md, or prepare for compaction.
---

# Compaction Guard (Delta Snapshot)

Preserve high-signal session state in `MEMORY.md` without duplicating `PLAN.md`.

1. **Diff Reality:** Read `PLAN.md` and `MEMORY.md`. Run `git status -s` and `git diff --stat` to verify actual code changes.
2. **Extract Delta:** Filter for items NOT in `PLAN.md` (user constraints, rejected approaches, unplanned file edits, active debugging state).
3. **Update `MEMORY.md`:** Write terse bullets under four headers:
   - `## Active Constraints & Guardrails` (Explicit user rules/preferences from chat)
   - `## Out-of-Band Code Changes` (`file:symbol` + reason + verification status)
   - `## Rejected Approaches` (What failed or was vetoed—do not repeat)
   - `## Next Immediate Action` (Exact file, symbol, or command to resume post-compaction)
EOF

# 2. regression-ledger
mkdir -p "${BASE_DIR}/regression-ledger"
cat << 'EOF' > "${BASE_DIR}/regression-ledger/SKILL.md"
---
name: regression-ledger
description: Log and track newly discovered bugs, regressions, and test failures in MEMORY.md without cluttering PLAN.md. Use whenever the user reports a bug, regression, or unexpected side-effect mid-implementation.
---

# Bug & Regression Ledger

Keep `PLAN.md` focused on the feature roadmap; track ad-hoc defects in `MEMORY.md`.

1. **Log Before Fixing:** Record the defect under `## Regression Ledger` in `MEMORY.md`, noting which `PLAN.md` step was active.
2. **Isolate & Fix:** Identify `file:line` (`symbol`), apply the minimal fix, and run a targeted verification command.
3. **Update Ledger:** Mark `[OPEN]` or `[RESOLVED]` using this compact entry format:
   - `[STATUS] Short Title (PLAN.md Step X)` — **Symptom:** ... | **Cause:** `file:line` | **Fix:** ... | **Verified:** `command`
EOF

# 3. worktree-fanout
mkdir -p "${BASE_DIR}/worktree-fanout"
cat << 'EOF' > "${BASE_DIR}/worktree-fanout/SKILL.md"
---
name: worktree-fanout
description: Coordinate parallel subagents across isolated Git worktrees using the omp task tool and typed output schemas. Invoke manually via /skill:worktree-fanout for multi-module changes.
disable-model-invocation: true
---

# Parallel Worktree Fanout (omp)

1. **Partition by Boundary:** Split the task into independent work units with zero overlapping file writes.
2. **Dispatch Isolated Workers:** Spawn parallel `task` subagents in isolated worktrees. Assign `smol` to discovery tasks and `default`/`slow` to implementation tasks.
3. **Enforce Output Schema:** Require every worker to return a JSON summary: `{ "modified_files": [], "verification_cmd": "", "exit_code": 0, "blockers": [] }`.
4. **Verify Before Merge:** Inspect each worker's unified diff for cross-module signature conflicts and run integration tests before merging worktrees.
EOF

# 4. dap-crash-triage
mkdir -p "${BASE_DIR}/dap-crash-triage"
cat << 'EOF' > "${BASE_DIR}/dap-crash-triage/SKILL.md"
---
name: dap-crash-triage
description: Diagnose crashes, exceptions, hangs, and logic bugs using native DAP debugger and LSP tools instead of print debugging. Use when debugging failing tests, segfaults, or runtime errors in omp.
---

# Debugger-First Triage (omp)

Do NOT insert temporary `print`, `printf`, or `console.log` statements to diagnose bugs.

1. **Locate Symbol:** Use the native `lsp` tool to find the exact definition, callers, and line numbers of the suspect function.
2. **Attach DAP Debugger:** Launch the native `debug` tool (`debugpy`, `lldb`, or `dlv`) on the failing test or binary.
3. **Inspect State:** Set a conditional breakpoint prior to the fault, step through execution, inspect local frame variables/call stack, and detach cleanly before editing code.
EOF

# 5. memory-bank-sync
mkdir -p "${BASE_DIR}/memory-bank-sync"
cat << 'EOF' > "${BASE_DIR}/memory-bank-sync/SKILL.md"
---
name: memory-bank-sync
description: Synchronize omp internal memory tools (retain, recall, reflect) with project-root MEMORY.md and PLAN.md files for cross-CLI portability. Use before switching between omp, agy, or qwen.
---

# Cross-CLI Memory Bank Sync

Bridge `omp` internal memory with portable Markdown files (`MEMORY.md` / `PLAN.md`).

1. **Ingest:** Read `MEMORY.md` and `PLAN.md`; call `retain` / `memory_edit` on new architectural invariants so `omp` subagents inherit them.
2. **Export:** Run `recall` and `reflect` to extract learned repo conventions, build quirks, and unresolved bugs discovered during the `omp` session.
3. **Persist:** Append any missing high-signal findings into `MEMORY.md` so external CLIs (`agy`, `qwen`) have immediate parity.
EOF

# 6. explore-plan-verify
mkdir -p "${BASE_DIR}/explore-plan-verify"
cat << 'EOF' > "${BASE_DIR}/explore-plan-verify/SKILL.md"
---
name: explore-plan-verify
description: Enforce a strict 3-phase Explore, Plan, and Verify gate synchronized with PLAN.md and MEMORY.md. Use when implementing multi-file features or architectural changes in Antigravity.
---

# Explore -> Plan -> Verify Gate

Never jump straight from prompt to file edits on multi-file tasks.

1. **Phase 1 (Explore):** Perform read-only symbol/grep searches. Identify affected files, types, and existing tests.
2. **Phase 2 (Plan):** Update `PLAN.md` with discrete steps, target `file:symbol` paths, and exact verification commands. Pause for user confirmation if scope expanded.
3. **Phase 3 (Execute & Verify):** Apply surgical edits one step at a time, run the verification command after each step, check off the item in `PLAN.md`, and log any unplanned side-effects in `MEMORY.md`.
EOF

# 7. context-hygiene-reader
mkdir -p "${BASE_DIR}/context-hygiene-reader"
cat << 'EOF' > "${BASE_DIR}/context-hygiene-reader/SKILL.md"
---
name: context-hygiene-reader
description: Minimize context window bloat during codebase exploration to prevent premature Gemini Flash compaction. Use whenever searching or inspecting unfamiliar files across a repository.
---

# Context-Hygiene File Reader

Prevent raw file dumps from exhausting the active context window.

1. **Grep First:** Never read a file over 200 lines from top to bottom to locate a symbol. Run `rg -n` or LSP symbol lookup first.
2. **Ranged Reads Only:** Read only a 40-to-80 line window around the target line number.
3. **Evict to Disk:** If exploration spans more than 5 files, write a 5-bullet architectural map (`file:line` -> responsibility) into `MEMORY.md` instead of re-reading those files in later turns.
EOF

# 8. surgical-refactor
mkdir -p "${BASE_DIR}/surgical-refactor"
cat << 'EOF' > "${BASE_DIR}/surgical-refactor/SKILL.md"
---
name: surgical-refactor
description: Execute minimal-diff, behavior-preserving code refactorings with full caller verification. Use when asked to refactor, rename, extract, or clean up existing code.
---

# Surgical Refactor

1. **Map All Callers:** Before changing any signature, struct, or export, find every reference across the repo via LSP or `rg`.
2. **Zero Diff Noise:** Preserve surrounding indentation, comments, and import ordering. Never mix formatting rewrites, unsolicited docstrings, or unrelated cleanups into a refactor diff.
3. **Verify Parity:** Run existing unit tests and typecheckers/compilers immediately after applying the edit.
EOF

# 9. test-first-bugfix
mkdir -p "${BASE_DIR}/test-first-bugfix"
cat << 'EOF' > "${BASE_DIR}/test-first-bugfix/SKILL.md"
---
name: test-first-bugfix
description: Enforce a red-to-green reproduction test workflow before modifying production source code. Use when fixing bugs, edge cases, or broken behavior.
---

# Test-First Bugfix

1. **Reproduce (Red):** Write or update a minimal automated test that reproduces the exact bug and run *only* that test target to confirm it fails for the expected reason.
2. **Fix (Green):** Apply the smallest possible production code change to make the failing test pass.
3. **Guard:** Re-run the single test plus the immediate module test suite, then log the verification command in `MEMORY.md` if discovered mid-feature.
EOF

# 10. git-atomic-commit
mkdir -p "${BASE_DIR}/git-atomic-commit"
cat << 'EOF' > "${BASE_DIR}/git-atomic-commit/SKILL.md"
---
name: git-atomic-commit
description: Stage and commit changes in logical, atomic units using Conventional Commits without sweeping in unrelated or untracked files. Use when asked to commit, stage, or prepare git history.
---

# Git Atomic Commit

1. **Audit Working Tree:** Run `git status -s` and `git diff`. Never use `git add .` or `git add -A`.
2. **Separate Concerns:** Stage files explicitly (`git add path/to/file`) so bugfixes, refactors, and features are split into distinct atomic commits. Leave temporary files and `MEMORY.md` unstaged unless requested.
3. **Format Message:** Write a concise Conventional Commit message (`feat|fix|refactor|test|chore(scope): imperative summary under 72 chars`).
EOF

echo "Done. Installed $(find "${BASE_DIR}" -maxdepth 2 -name 'SKILL.md' | wc -l) skills."

Seven

Ludditus: Give me a concise AGENTS.md template that instructs omp and agy how to coordinate PLAN.md, MEMORY.md, and these 10 skills automatically.

Argon:

Because AGENTS.md is injected into every turn, keeping it under 60–100 lines prevents reasoning token bloat and instruction dilution while relying on progressive disclosure to load full SKILL.md bodies only when triggered. Both Oh My Pi (omp) and Antigravity (agy) read AGENTS.md from the repository root (and you can run ln -s AGENTS.md GEMINI.md if a specific Gemini CLI tool expects GEMINI.md).

Save this template to ./AGENTS.md in your project root:

# Project Agent Contract (`omp` & `agy`)

## 1. Build, Test & Verify Commands
- **Build / Check:** `<insert-build-or-typecheck-cmd>`
- **Single Test:** `<insert-single-test-cmd, e.g., pytest path/to/test.py -k test_name>`
- **Lint / Format Check:** `<insert-lint-cmd>`

## 2. Two-File State Architecture (`PLAN.md` vs. `MEMORY.md`)
On session start or post-compaction recovery, inspect `PLAN.md` and `MEMORY.md` before exploring code:
- **`PLAN.md` (Feature Roadmap):** Holds the approved implementation steps, target `file:symbol` paths, and verification commands for the primary feature. Do NOT clutter `PLAN.md` with ad-hoc bug reports or chat guardrails.
- **`MEMORY.md` (Live Session Delta & Regression Ledger):** Holds everything outside `PLAN.md`:
  1. Active user constraints, style rules, and rejected approaches established during chat.
  2. Out-of-band file modifications not listed in `PLAN.md`.
  3. Newly discovered bugs and regressions (`[OPEN]` / `[RESOLVED]`).
  4. The exact next action to resume after context compaction or CLI switching.

## 3. Automatic Skill Trigger Matrix (`.agents/skills/`)
Load and follow the corresponding skill whenever a trigger condition is met:
- **Codebase Exploration:** Load `context-hygiene-reader` before searching unfamiliar files (use `rg -n` or `lsp` first; read 40–80 line windows; never dump 200+ line files into context).
- **Multi-File Feature Work:** Load `explore-plan-verify` to enforce the Explore -> `PLAN.md` -> Execute & Verify gate.
- **Refactoring / Renaming:** Load `surgical-refactor` to verify all callers via `lsp`/`rg` and guarantee zero unrelated diff noise.
- **Ad-Hoc Bug or Regression Reported Mid-Session:** Load `regression-ledger` immediately to log the defect in `MEMORY.md` without rewriting `PLAN.md`, then load `test-first-bugfix` to enforce a failing reproduction test before editing production code.
- **Crashes, Hangs, or Failing Tests (`omp`):** Load `dap-crash-triage` and attach the native `debug` (DAP) + `lsp` tools instead of adding temporary print statements.
- **Context Filling / Pre-Compaction / Session Pause:** Load `compaction-guard` to diff `git status`/`git diff` and live chat constraints against `PLAN.md`, writing the delta into `MEMORY.md`.
- **Switching Between `omp`, `agy`, or `qwen`:** Load `memory-bank-sync` to bridge `omp` internal memory (`retain`/`recall`/`reflect`) with `MEMORY.md`.
- **Git Staging & Commits:** Load `git-atomic-commit` (never run `git add .`; leave `MEMORY.md` unstaged unless requested).
- **Parallel Multi-Module Fanout (`omp`):** Only run `worktree-fanout` when explicitly invoked via `/skill:worktree-fanout`.

## 4. Harness-Specific Execution Rules
- **Oh My Pi (`omp`):** Route read-only discovery to the `smol` model role, architectural planning to `plan`, and implementation to `default`. Prefer built-in Rust `lsp`, `debug`, and `rg` tools over raw shell pipelines.
- **Antigravity (`agy`):** Keep turn outputs and file reads compact to delay automatic Gemini Flash compaction. If context usage exceeds 70% or before a major phase shift, execute `compaction-guard` proactively.

Why this layout works well in practice:

  • Zero Redundancy: Instead of pasting the step-by-step checklists into AGENTS.md, Section 3 acts as a routing table that points the model’s attention to the exact skill name in .agents/skills/.
  • Executable Grounding: Putting concrete single-file test and typecheck commands at the very top ensures both omp subagents and agy verify their diffs mechanically rather than running slow full-suite builds.
  • Post-Compaction Resilience: Because AGENTS.md is re-injected cleanly even after automatic context compaction, Section 2 forces the agent to immediately re-read PLAN.md and MEMORY.md on the very first turn after a compaction event.

Eight

Ludditus: Give me a concise starter template for PLAN.md and MEMORY.md that matches this AGENTS.md contract.

Argon:

Drop these two starter templates into your repository root. Their section headers match the exact target headings expected by compaction-guard, regression-ledger, context-hygiene-reader, and explore-plan-verify, ensuring that Oh My Pi (omp) and Antigravity (agy) update existing sections in place rather than inventing new ones.

1. ./PLAN.md (Feature Roadmap & Verification Gates)

# Feature Plan: <Short Feature or Milestone Name>

## Objective & Scope
- **Goal:** <1-2 sentences defining the end state and architectural boundary>
- **Non-Goals:** <What is explicitly out of scope for this plan>

## Implementation Steps
- [ ] **Step 1: <Short imperative title>**
  - **Targets:** `path/to/file.ext:symbol_name`, `path/to/other.ext:TypeName`
  - **Changes:** <Concise summary of signature/logic change>
  - **Verify:** `<exact single-test or typecheck command>`

- [ ] **Step 2: <Short imperative title>**
  - **Targets:** `path/to/file.ext:symbol_name`
  - **Changes:** <Concise summary of signature/logic change>
  - **Verify:** `<exact single-test or typecheck command>`

- [ ] **Step 3: <Short imperative title>**
  - **Targets:** `path/to/test_file.ext:test_symbol`
  - **Changes:** <Integration test / edge-case coverage>
  - **Verify:** `<exact test suite command>`

2. ./MEMORY.md (Live Session Delta & Regression Ledger)

# Session Memory & Delta Ledger

## Next Immediate Action
- **Active Step:** `PLAN.md` Step 1
- **Resume Target:** `path/to/file.ext:line` (`symbol_name`)
- **Next Command:** `<exact command or edit to run first after compaction/resume>`

## Active Constraints & Guardrails
- <Explicit user rules from chat, e.g., "Do not change public signature of Foo()">

## Out-of-Band Code Changes
- `path/to/file.ext:symbol` — <Why modified outside PLAN.md> | **Verified:** `<cmd or pending>`

## Regression Ledger
- `[OPEN] <Short Bug Title> (PLAN.md Step X)` — **Symptom:** <error/behavior> | **Cause:** `file:line` (`symbol`) | **Fix:** <pending or summary> | **Verified:** `<cmd>`

## Rejected Approaches
- **<Approach Name>:** <Why it failed or was vetoed by user — do not retry post-compaction>

## Architectural Map (Evicted Context)
- `path/to/file.ext:line` (`symbol`) -> <1-line responsibility note to avoid re-reading large files>

Keeping MEMORY.md Out of Git Commits Automatically

To prevent accidental staging of MEMORY.md without modifying the project’s shared .gitignore, add it to your local repository exclusions:

echo "MEMORY.md" >> .git/info/exclude

This keeps git status clean while letting omp, agy, and qwen read and write MEMORY.md freely on disk.

Nine

Ludditus: Give me a concise WATCHDOG.md configuration for Oh My Pi (omp) so the advisor model flags violations of PLAN.md and MEMORY.md automatically.

Argon:

In Oh My Pi (omp), WATCHDOG.md (discovered automatically from ./WATCHDOG.md or ./.omp/WATCHDOG.md) injects standing review instructions into the advisor model’s system prompt. By default, the advisor operates in a separate bounded context with read-only workspace tools (read, grep, glob) plus the advise tool, which routes feedback across three severity tiers: blocker (immediate mid-stream steer), concern (triggers a continuation or turn follow-up), and nit (leaves a non-interrupting transcript card).

Save this file to ./WATCHDOG.md (or ./.omp/WATCHDOG.md):

# Watchdog Review Contract (`PLAN.md` & `MEMORY.md` Enforcement)

You are the read-only compliance watchdog for this repository. Before evaluating primary agent diffs or tool calls, use `read` to inspect `PLAN.md` and `MEMORY.md` so you judge the primary agent against live session state.

## Core Operating Rule
- **Silence is mandatory when compliant:** If the primary agent's turn adheres to `PLAN.md`, `MEMORY.md`, and `AGENTS.md`, do NOT call `advise`. Never emit filler notes ("LGTM", "no issues").
- **Verify on disk:** Use `read` or `grep` on modified files when a diff snippet is ambiguous before raising a `concern` or `blocker`.

## Severity Escalation Matrix (`advise` tool)

### 1. Emit `blocker` (Immediate Interruption) when the primary agent:
- **Violates `MEMORY.md` Guardrails:** Repeats a rejected approach listed under `## Rejected Approaches` or breaks an explicit rule under `## Active Constraints & Guardrails`.
- **Skips Test-First on Bugs:** Edits production code to fix a reported bug or regression before logging it in `MEMORY.md` (`## Regression Ledger`) or running a failing reproduction test.
- **Rewrites `PLAN.md` for Ad-Hoc Bugs:** Pollutes `PLAN.md` with mid-session bug triage instead of recording the defect in `MEMORY.md`.
- **Uses Unsafe Git Commands:** Executes `git add .`, `git add -A`, or stages `MEMORY.md` without explicit user permission.
- **Repeats Unresolved Advice:** Ignores a previously raised `concern` and continues mutating files without addressing the underlying defect.

### 2. Emit `concern` (Turn Follow-Up Required) when the primary agent:
- **Drifts from `PLAN.md` Scope:** Modifies files or symbols outside the active step's `Targets` in `PLAN.md` without recording the reason under `## Out-of-Band Code Changes` in `MEMORY.md`.
- **Skips Step Verification:** Marks a step complete in `PLAN.md` or moves to the next step without executing the exact `Verify` command defined for that step.
- **Leaves Caller References Broken:** Changes a function signature, struct, or export without checking callers via `lsp` or `rg`.
- **Uses Print Debugging:** Inserts temporary `print`, `printf`, or `console.log` statements to diagnose a crash or test failure instead of using `omp`'s native `debug` (DAP) and `lsp` tools.

### 3. Emit `nit` (Non-Interrupting Card) when the primary agent:
- **Dumps Large Files:** Reads an entire 200+ line file instead of using `rg -n` / `lsp` followed by ranged `read` calls.
- **Introduces Diff Noise:** Mixes unrelated formatting changes, import reordering, or unsolicited docstrings into a surgical edit.
- **Forgets Delta Bookkeeping:** Completes a significant out-of-band fix or 5+ file exploration without updating `MEMORY.md` (`## Next Immediate Action` or `## Architectural Map`).

Optional: ./.omp/WATCHDOG.yml (Tuning Advisor Cadence & Model)

While WATCHDOG.md works standalone with your default advisor model role, adding a minimal .omp/WATCHDOG.yml lets you cap non-blocker noise and prevent the primary agent from stalling while waiting for the watchdog:

maxNotesPerUpdate: 2
advisors:
  - name: state-auditor
    enabled: true
    # Uses your configured 'advisor' role model by default, or pin a fast reasoning model:
    # model: openrouter/deepseek/deepseek-r1
    syncBacklog: 1
    tools:
      - read
      - grep
      - glob
      - advise
  • maxNotesPerUpdate: 2 caps non-blocker notes (nit and concern) to at most 2 per review cycle so the primary agent isn’t flooded, while blocker notes remain exempt.
  • syncBacklog: 1 bounds how long the primary agent waits if the advisor model falls behind (capping the catch-up wait at 30 seconds before letting the primary agent continue).

Ten

Ludditus: Show me how to configure time-traveling regex stream rules in Oh My Pi (omp) to abort and correct forbidden patterns like git add -A or print debugging mid-generation.

Argon:

In Oh My Pi (omp), Time-Traveling Stream Rules (TTSR) are managed by TtsrManager. When you place a Markdown rule file in .omp/rules/*.md or .agents/rules/*.md (or globally in ~/.omp/rules/*.md) that includes a condition or astCondition in its YAML frontmatter, omp places it into the TTSR bucket.

Unlike AGENTS.md, TTSR rules sit completely dormant at zero system-prompt token cost until the model’s output stream matches the trigger. When triggered, omp aborts the generation mid-token, injects the Markdown body as a system violation reminder, and retries from that exact point. Because TTSR injection records persist across context compaction, the model remembers the correction for the rest of the session.

Key TTSR Frontmatter Fields & The “Prose Trap”

Before writing rules, note how omp evaluates TTSR frontmatter:

  • condition: One or more regex strings matched against the live token stream (supports leading inline flags (?i), (?m), (?s)).
  • astCondition: Structural ast-grep patterns matched against finalized code snapshots from edit and write tool calls (language is inferred automatically from the file extension).
  • scope: Controls where omp watches for matches. By default, omitting scope watches both assistant prose (text) and all tool arguments (tool). Critical tip: Always narrow violation rules to specific tools—such as scope: "tool:bash" or scope: "tool:edit(*), tool:write(*)"—so omp doesn’t false-positive abort when the agent merely mentions git add -A in prose while explaining what it is avoiding.
  • interruptMode: Set to tool-only or always ("always" | "prose-only" | "tool-only" | "never") to guarantee an immediate stream abort and retry when matched.
  • agents: Optional filter (e.g., agents: main for the parent session only, or omitted to enforce across both main and all task subagents).

1. Abort git add -A / git add . & Staging MEMORY.md

Save to .omp/rules/no-unsafe-git-stage.md (or .agents/rules/no-unsafe-git-stage.md):

---
name: no-unsafe-git-stage
description: Block sweeping git staging commands and accidental commits of MEMORY.md.
scope: "tool:bash"
interruptMode: tool-only
condition:
  - '(?m)\bgit\s+add\s+(?:-[A-Za-z]*A|--all|\.|\*)(?:\s|$)'
  - '(?m)\bgit\s+commit\s+-[A-Za-z]*a[A-Za-z]*\b'
  - '(?m)\bgit\s+add\s+[^\n]*\bMEMORY\.md\b'
---

# TTSR Violation: Unsafe Git Staging Aborted

You attempted to run a sweeping `git add` (`.` / `-A` / `--all`), `git commit -a`, or stage `MEMORY.md`.

## Required Correction
1. Run `git status -s` and `git diff` first.
2. Stage only the specific source/test files belonging to the current atomic change (`git add path/to/file`).
3. Never stage `MEMORY.md` or untracked temporary artifacts unless the user explicitly requested it in the current prompt.

2. Abort Print Debugging Mid-Edit (Regex + ast-grep)

Save to .omp/rules/no-print-debugging.md. Combining condition (live stream regex) with astCondition (structural AST match on edit/write) stops the model from sprinkling temporary logs across Python, C/C++, JS/TS, Rust, or Go:

---
name: no-print-debugging
description: Block temporary print/console/printf debugging in favor of omp native DAP debug and lsp tools.
scope: "tool:edit(*.py), tool:write(*.py), tool:edit(*.ts), tool:write(*.ts), tool:edit(*.js), tool:write(*.js), tool:edit(*.c), tool:write(*.c), tool:edit(*.cpp), tool:write(*.cpp), tool:edit(*.rs), tool:write(*.rs)"
interruptMode: tool-only
condition:
  - '(?i)\b(?:console\.log|print|printf|fprintf|dbg!)\s*\(\s*["''](?:DEBUG|HERE|TRACE|TODO|FIXME|TEST\b)'
astCondition:
  - 'console.log($$$)'
  - 'dbg!($$$)'
---

# TTSR Violation: Print Debugging Aborted

Do not insert temporary `print()`, `printf()`, `console.log()`, or `dbg!()` calls to diagnose bugs or test failures.

## Required Correction
1. Use the built-in `lsp` tool to locate symbol definitions, references, and call sites.
2. Attach the built-in `debug` (DAP) tool (`debugpy`, `lldb`, or `dlv`), set a breakpoint at the suspect line, and inspect frame variables directly.

(Note: If you are working on a CLI project where legitimate print() or printf() calls exist in production code, keep condition scoped to debug-prefix markers as shown above, or scope astCondition paths to exclude CLI output modules.)

3. Abort Shell File Dumps (cat / head / tail) That Bypass Ranged Reads

Save to .omp/rules/no-shell-file-dumps.md. Models sometimes bypass the read tool’s line limits by running cat or huge sed/head commands inside bash, which floods your context window:

---
name: no-shell-file-dumps
description: Block dumping source files into context via bash cat, head, tail, or sed.
scope: "tool:bash"
interruptMode: tool-only
condition:
  - '(?m)(?:^|[;&|]\s*)(?:cat|less|more)\s+[^\n|>;]+\.(?:py|ts|js|rs|go|c|cpp|h|hpp|java|md)\b'
---

# TTSR Violation: Raw Shell File Dump Aborted

Do not use `cat`, `less`, or `more` in `bash` to read source files into the context window.

## Required Correction
1. Use `grep` (`rg`) or `lsp` to locate the exact symbol and line number first.
2. Use the native `read` tool with an explicit line range (`offset` and `limit` of 40–80 lines) around the target symbol.

4. Verifying & Tuning TTSR via the omp CLI

Once your rule files are saved in .omp/rules/ or .agents/rules/, verify and tune them directly from your terminal:

# 1. Verify that omp discovered and registered your rules into the TTSR bucket:
omp ttsr list

# 2. Test a sample string or tool payload against your registered regex rules:
omp ttsr test "git add -A && git commit -m 'wip'"

# 3. Ensure global TTSR settings abort immediately and retain injected rules in context:
omp config set ttsr.enabled true
omp config set ttsr.interruptMode always
omp config set ttsr.contextMode keep
omp config set ttsr.repeatMode after-gap
omp config set ttsr.repeatGap 10
  • ttsr.contextMode keep ensures the injected reminder remains anchored in the conversation history (and survives compaction).
  • ttsr.repeatMode after-gap (repeatGap 10) allows the rule to re-fire if the model behaves for 10+ turns and then drifts back into the same mistake later in a long session.

Eleven

Ludditus: Show me how to write a TTSR rule or pre-tool hook in Oh My Pi (omp) that prevents editing source files when PLAN.md or MEMORY.md constraints are violated.

Argon:

In Oh My Pi (omp), enforcing stateful rules (such as “Has the agent read PLAN.md?” or “Does this edit violate a constraint in MEMORY.md?”) requires understanding the architectural split between TTSR and Pre-Tool Extensions:

  • TTSR (Time-Traveling Stream Rules): Stateless pattern matching. It inspects what the model is currently outputting (tokens or tool arguments) but cannot natively query whether a file was read 5 turns ago.
  • Pre-Tool Extension Hooks: Programmatic TypeScript/JavaScript interceptors (.omp/extensions/*.ts) that have full access to the session history, tool call arguments, file read states, and working tree before a tool executes.

To enforce that source files are never edited until PLAN.md / MEMORY.md are respected or constraints are met, use an omp Extension Hook.

Solution: Stateful Pre-Tool Hook (.omp/extensions/enforce-plan-guard.ts)

Save this file to .omp/extensions/enforce-plan-guard.ts. It intercepts every edit and write tool call, verifies whether PLAN.md has been loaded into session memory, and blocks edits to production source files if unapproved or if MEMORY.md has active blockers.

import { ExtensionAPI } from "@earendil-works/omp-sdk";
import * as fs from "fs";
import * as path from "path";

export default function(api: ExtensionAPI) {
  let planReadThisSession = false;

  // Track when the agent reads PLAN.md or MEMORY.md
  api.on("afterToolCall", (event) => {
    if (event.tool === "read") {
      const filePath = event.args?.path || "";
      if (filePath.endsWith("PLAN.md") || filePath.endsWith("MEMORY.md")) {
        planReadThisSession = true;
      }
    }
  });

  // Intercept before any file modification tool runs
  api.on("beforeToolCall", async (event) => {
    if (event.tool === "edit" || event.tool === "write") {
      const targetFile = event.args?.path || event.args?.file || "";
      
      // Skip guardrails for test files, markdown docs, or dotfiles
      if (
        targetFile.includes("test") ||
        targetFile.endsWith(".md") ||
        targetFile.startsWith(".")
      ) {
        return;
      }

      // Rule 1: Prevent editing source code if PLAN.md has not been read in this session
      if (!planReadThisSession && fs.existsSync(path.join(api.getCwd(), "PLAN.md"))) {
        event.cancel = true;
        event.errorResult = 
          "GUARDRAIL BLOCKED: You attempted to edit source code (" + targetFile + ") " +
          "before reading PLAN.md. Read PLAN.md and MEMORY.md first to align with session scope.";
        return;
      }

      // Rule 2: Check MEMORY.md for explicit guardrail vetoes or active regressions
      const memoryPath = path.join(api.getCwd(), "MEMORY.md");
      if (fs.existsSync(memoryPath)) {
        const memoryContent = fs.readFileSync(memoryPath, "utf8");
        
        // If MEMORY.md contains a rejected approach or active un-vetted blocker referencing this file
        if (memoryContent.includes(targetFile) && memoryContent.includes("[OPEN]")) {
          event.cancel = true;
          event.errorResult = 
            "GUARDRAIL BLOCKED: Target file " + targetFile + " has an active [OPEN] regression " +
            "or guardrail restriction logged in MEMORY.md. Resolve the ledger entry before editing.";
          return;
        }
      }
    }
  });
}

Alternative: Pure TTSR Tool-Argument Rule (.omp/rules/enforce-plan-referenced.md)

If you prefer a pure TTSR regex rule (which blocks immediately based on the generated tool arguments rather than tracking prior file-read state), you can check if the model tries to edit a file that is clearly outside the scope or format conventions.

Save to .omp/rules/enforce-plan-referenced.md:

---
name: enforce-plan-referenced
description: Block edits to core source files unless accompanied by PLAN reference patterns in tool payload.
scope: "tool:edit(*), tool:write(*)"
interruptMode: tool-only
condition:
  - '(?i)\bpath\b.*(?:src/|lib/|app/)(?!.*test)'
---

# TTSR Violation: Unplanned Source Mutation Blocked

You attempted to mutate core production source code.

## Required Correction
1. Ensure your current step is explicitly defined and checked out in `PLAN.md`.
2. Do not modify production files outside the active step's target specification without updating `PLAN.md` and logging the delta in `MEMORY.md`.

Enabling and Verifying Extensions in omp

Activate and test your new extension from the terminal:

# 1. Enable extensions in omp settings
omp config set extensions.enabled true

# 2. Verify loaded extensions and active hooks
omp extensions list

Limit reached. Continuing with Flash-Lite.

Thanks, but no, thanks.