ultimate-pi

Commit staged git changes with configurable message format and Co-authored-by trailer from .pi/auto-commit.json. Use when the user asks to commit, when /harness-auto or harness run completion requires a commit, or before any git commit — never use raw git commit -m.

Compile task-specific harness context using context-mode and graphify. Use for architecture questions, large codebase context before harness-plan or harness-run. NEVER use lean-ctx on harness paths.

Plan-phase Review Gate debate — pi-messenger threads, lane YAML, bus tools for parent orchestrator.

Structured user decisions via ask_user for harness setup, planning, and governance forks. Use with /harness-setup, /harness-plan, harness-auto plan phase, and when agents emit human_required.

Deprecated — use harness-review skill and /harness-review for the full post-run gate. This file remains as a pointer for older prompts.

Enforce harness governance phases, policy gates, budgets, and promotion rules. Use during execute, evaluate, merge, or when interpreting policy-gate / budget-guard messages.

Bootstrap ls-lint filename rules for harness projects — seed naming.manifest.json, generate merge-safe .ls-lint.yml, and document bootstrap vs --force sync. Use during /harness-setup, when adding ls-lint to a repo, or when .ls-lint.yml is missing or out of date.

Orchestrate ultimate-pi harness phases with the native `subagent` tool (isolated `pi --mode json` subprocesses). Use for plan/execute/evaluate pipelines, L4 verification, optional planning-context, and debate prep.

Agent-native harness plans — lakes/context bundles, planning context, parallel_probes debate profile, plan-synthesizer on low/med risk, path-first approve_plan/create_plan, then DAG + debate.

Post-run verification gate (/harness-review): harness-verify, Sentrux fitness functions, benchmark + verdict evaluator, adversary, optional tie-breaker. Subagents use submit_*; parent uses harness_artifact_ready. Use after /harness-run; claim cross-session runs with /harness-use-run --claim.

OSS Sentrux capture, diagnostics synthesis, and repair-plan loop for harness runs. Use during /harness-run post-work, /harness-review Phase 1/1b, /harness-steer, or when artifacts/sentrux-report.json or sentrux-repair-plan.yaml are mentioned. No Sentrux Pro or MCP.

Bootstrap Sentrux architectural rules for harness projects — seed architecture.manifest.json, generate merge-safe .sentrux/rules.toml, and document bootstrap vs --force sync. Use during /harness-setup, when adding Sentrux to a repo, or when rules.toml is missing or out of date.

Draft or refine harness artifact contracts under .pi/harness/specs. Use when defining PlanPacket, RunTrace, HarnessRunRecord, eval verdicts, or PostHog event schemas for ultimate-pi.

Post-review repair loop via harness-steer and executor repair mode.

Analyze pi agentic conversations, errors, and misalignments using PostHog MCP. Queries $ai_generation, $ai_span, $ai_trace events, segments by model, detects failure patterns, cross-references the wiki's model-adaptive harness research, and generates model-specific recommendations filed to the wiki. Use this skill when the user wants to analyze agent performance, understand where the harness breaks per model, audit LLM errors or tool failures, improve model profiles based on real data, or run a postmortem on agentic sessions. Trigger on: "posthog analyze", "/posthog-analyze", "analyze agent sessions", "audit llm errors", "postmortem", "what's failing per model", "harness performance analysis", "find misalignments", "model error patterns", "agent conversation audit".

Architectural quality sensor for AI-assisted code — rules, modularity, session baselines, and degradation detection via the Sentrux CLI (not MCP in Pi sessions). Use when the user mentions sentrux, quality signal, architectural health, gate, check rules, modularity, session baseline, degradation, structural drift, or before/after agent work on a harness project. Triggers on: sentrux check, sentrux gate, rules.toml, quality gate.

Agentic Web Retrieval Stack (WRS) — tiered web_search/web_fetch/web_contents (harness-web.py + Scrapling). Default tier=deep with web-query-expander angles. Use for search, scrape, landscape, prior art, comparisons, planning pre-research, cited answers, similar URLs, websets scoring. Triggers on non-API web research, scrape URL, web_search, web_fetch, .web/ artifacts. Library API docs → context7 only. Install: /harness-setup or harness-cli-verify.

Save the current conversation, answer, or insight into the Obsidian wiki vault as a structured note. Analyzes the chat, determines the right note type, creates frontmatter, files it in the correct wiki folder, and updates index, log, and hot cache. Triggers on: "save this", "save that answer", "/wiki-save", "/save", "file this", "save to wiki", "save this session", "file this conversation", "keep this", "save this analysis", "add this to the wiki".

Autonomous iterative research loop. Takes a topic, runs web searches, fetches sources, synthesizes findings, and builds a queryable knowledge graph via Graphify. Based on Karpathy's autoresearch pattern: program.md configures objectives and constraints, the loop runs until depth is reached, output goes into the graph. Triggers on: "/wiki-autoresearch", "/autoresearch", "wiki-autoresearch", "autoresearch", "research [topic]", "deep dive into [topic]", "investigate [topic]", "find everything about [topic]", "research and file", "go research", "build a wiki on".

Structural code search and replacement using the sg CLI. Use for function calls, imports, class/method definitions, call sites, and codemods. Prefer LSP for definitions/references/types; use sg for structural patterns; reserve grep for exact literals, comments, URLs, or non-code files.

Navigate code with IDE features and run proactive LSP diagnostics on files/folders/batches. Use as PRIMARY for code intelligence and type/error checks.

Use when implementing the Broker-Domain pattern: event-brokered integration around cohesive domain services, separating broker concerns from domain behavior, with explicit event contracts and bounded context ownership.

Use when implementing CQRS: separate command and query models, explicit write invariants, optimized read projections, consistency boundaries, projection rebuilds, and tests for command/query behavior.

Use when implementing event-driven architecture: domain/integration events, producers, consumers, broker or mediator topology, eventual consistency, idempotency, ordering, retries, and observable asynchronous flows.

Use when implementing hexagonal architecture / ports and adapters: domain core isolated from delivery and infrastructure mechanisms, inbound and outbound ports, adapters for external interfaces, dependency inversion, and testable business logic.

Use when designing, refactoring, or validating a codebase as layered architecture: delivery/interface, application/use-case, domain, and infrastructure/data layers with one-way dependency rules and minimal cross-layer coupling.

Use when building plugin or extension architecture: a stable core kernel with explicit extension points, plugin contracts, registration, isolation, versioning, and compatibility checks.

Use when designing, extracting, or repairing microservices: independently deployable bounded-context services with owned data, explicit contracts, observability, resilience, distributed workflow choices, and operational readiness checks.

Use when designing, splitting, or repairing a modular monolith: one deployable application with explicit business modules, bounded contexts, private internals, stable module APIs, and database boundaries that can later support service extraction.

Use when implementing orchestration-driven service-oriented architecture: central workflow orchestration across services, explicit process models, compensations, service contracts, long-running transactions, and governance boundaries.

Use when implementing pipeline architecture: data or task processing split into ordered filters/stages with explicit inputs, outputs, composition, error handling, and observability across the flow.

Use when implementing service-based architecture: coarse-grained domain services inside a mostly centralized system, with explicit service contracts, transaction boundaries, shared infrastructure discipline, and fewer operational costs than microservices.

Use when applying the service mesh pattern to service architectures: move cross-cutting network concerns such as retries, mTLS, routing, observability, policy, and traffic shaping out of service code while preserving domain ownership.

Use when implementing space-based architecture: horizontally scalable processing units, in-memory/distributed state, partitioning, eventual persistence, backpressure, replication, and operational safeguards for high-volume systems.

Debug systematically instead of guessing. Use when fixing bugs, failing tests, flaky behavior, runtime errors, regressions, or unexpected output. Guides reproduction, isolation, hypotheses, evidence, one-variable changes, root cause, and regression tests.

Update documentation only where it helps future work. Use when behavior, setup, contracts, commands, architecture decisions, operational procedures, or user-facing workflows change. Avoids redundant comments while capturing decisions, invariants, examples, and caveats near the relevant surface.

Translate vague or high-level requests into safe implementation steps. Use before coding features, bug fixes, refactors, or ambiguous tasks. Extracts requirements, constraints, done criteria, non-goals, risk, and the smallest viable implementation path.

Match verification depth to change risk. Use after code, test, config, dependency, data, or docs changes. Helps agents choose targeted checks for low risk, broader checks for medium/high risk, and report unverified residual risk clearly.

Make engineering tradeoffs explicit before choosing an implementation. Use when multiple viable approaches exist or when simplicity, maintainability, performance, reliability, compatibility, security, and delivery speed conflict. Chooses the least-worst option with rationale.

Design stable contracts for modules, services, commands, events, plugins, CLIs, and public interfaces. Use when adding or changing any boundary that other code or people depend on. Focuses on minimal contracts, compatibility, versioning, errors, idempotency, and documentation.